feat(bootstrap): live-account preflight validator

[scottschreckengaust]

Parent

Sub-issue 6 of #120 (RFC: Least-privilege CDK bootstrap policies as code)

Branch strategy

feat/bootstrap-preflight → targets feat/bootstrap-aspect

Estimated review time: ~30 min

Summary

Implement a validator that checks the deployed CDKToolkit stack's CloudFormation outputs against the required bootstrap version/hash before deploying. This prevents the "pull latest, deploy, fail 15 minutes later" failure mode.

Deliverables

• Create cdk/src/bootstrap/preflight/validator.ts:
  • Reads CDKToolkit stack CF outputs (BootstrapPolicyVersion, BootstrapPolicyHash) via CloudFormation.describeStacks
  • Compares against required version/hash from the app's policy code
  • Returns structured result:
    • PASS: version matches, hash matches → safe to deploy
    • WARN: version compatible but hash mismatch → possible console drift, recommend re-bootstrap
    • FAIL: version too old → lists missing permissions, provides exact remediation command
    • FAIL: no outputs found → default bootstrap detected (AdministratorAccess), provide bootstrap command
  • Outputs both structured JSON (for CI parsing) and human-readable summary (for terminal)
• Create cdk/test/bootstrap/validator.test.ts:
  • Mock CloudFormation.describeStacks responses for each scenario
  • Version match → PASS
  • Hash mismatch with compatible version → WARN with advisory message
  • Version too old → FAIL with specific missing actions listed
  • No CDKToolkit stack → FAIL with "not bootstrapped" message
  • No version/hash outputs → FAIL with "default bootstrap detected" message
  • AWS SDK error (permissions, network) → clear error message
• Add mise //cdk:preflight task in cdk/mise.toml:
  • Runs the validator
  • Exits 0 on PASS or WARN
  • Exits 1 on FAIL
  • Prints remediation: exact mise //cdk:bootstrap command to fix

Key design decisions

• Requires only cloudformation:DescribeStacks permission (read-only, safe for CI with minimal credentials)
• WARN does not block deploy — hash drift from console edits is advisory, not fatal
• FAIL prints the exact mise //cdk:bootstrap command needed (copy-paste friendly)
• Validator is importable as a library (for integration tests) and runnable as a CLI entry point (for mise task)
• Uses @aws-sdk/client-cloudformation (already a transitive dep via CDK)

Acceptance criteria

• All test scenarios pass with mocked AWS responses
• mise //cdk:preflight exits cleanly when CDKToolkit outputs match
• mise //cdk:preflight exits 1 with actionable message when versions mismatch
• Error messages include the exact command to run (no guessing for operators)

[scottschreckengaust]

Implementation note from #122: Version-bump enforcement

PR #158 establishes the bootstrap policy source code with:

• cdk/src/bootstrap/version.ts — BOOTSTRAP_VERSION (semver) + computeBootstrapHash() (SHA256)
• cdk/bootstrap/BOOTSTRAP_VERSION and cdk/bootstrap/BOOTSTRAP_HASH — committed artifacts consumed by the preflight validator

Current enforcement (CI-level, #158)

• Artifact sync test — if policies change but artifacts aren't regenerated, CI fails
• Hash snapshot test — if policies change, the snapshot must be explicitly updated (-u)

Missing enforcement (for this issue to address)

• Version-bump detection — when hash changes, nothing forces a semver bump today. The simplest approach: the preflight validator (feat(bootstrap): live-account preflight validator #126) should compare the deployed hash against required hash. If they differ, it outputs "re-bootstrap required" with the exact mise //cdk:bootstrap command. This is the deploy-time gate that catches missing bumps.
• Developer workflow — document in the generation script output or a cdk/bootstrap/README.md: "If you change any file in cdk/src/bootstrap/policies/, you must: (1) bump BOOTSTRAP_VERSION in version.ts, (2) run npx tsx cdk/scripts/generate-bootstrap-artifacts.ts, (3) update the snapshot with npx jest -u"
• Optional future automation — a pre-commit hook or CI check that detects changes to cdk/src/bootstrap/policies/*.ts without corresponding changes to BOOTSTRAP_VERSION / BOOTSTRAP_HASH files.

The key insight: the two artifact files exist for this validator to compare against deployed state. Their lifecycle is: code changes → artifacts regenerated → operator re-bootstraps → preflight passes → deploy proceeds.

[scottschreckengaust]

Coordination update (from #120/#123 architecture revision)

1. Add BootstrapPolicySet sufficiency check

The issue body only references BootstrapPolicyVersion and BootstrapPolicyHash. With the sufficiency model from #123, the validator also needs to:

• Read the BootstrapPolicySet CF output (comma-separated list of included policies)
• Compare: deployed PolicySet ⊇ app's required set (from getRequiredBootstrapPolicies())
• FAIL if the app requires a policy not in the deployed set, with actionable message:

  "compute-ecs not in bootstrap PolicySet. Either:
  (a) re-bootstrap: mise //cdk:bootstrap -- --context ComputeTypes=agentcore,ecs
  (b) disable ECS compute in app config"

2. Distinguish intentional restriction from misconfiguration

The operator may intentionally exclude policies (security posture decision). The error message must present both remediation paths (expand bootstrap OR change app config) — not assume the operator "forgot."

3. Revised check hierarchy

Check	Source	Failure means
PolicySet sufficiency	BootstrapPolicySet output vs. getRequiredBootstrapPolicies()	Missing compute variant — operator action needed
Version compatibility	BootstrapPolicyVersion output vs. BOOTSTRAP_VERSION	Stale bootstrap — policies may be missing
Hash integrity	BootstrapPolicyHash output vs. computeBootstrapHash(deployedPolicySet)	Console drift — someone hand-edited IAM

4. Branch strategy

Change: targets feat/bootstrap-aspect → targets main (after #125 merges, per ADR-001 §8)

5. Prior context

See the implementation note comment above (from #122) for version-bump enforcement details and developer workflow documentation.