feat(bootstrap): policies as typed TypeScript with version and hash

[scottschreckengaust]

Summary

Closes #122

Ports the three IaCRole-ABCA IAM policies from docs/design/DEPLOYMENT_ROLES.md into typed
TypeScript modules at cdk/src/bootstrap/policies/. Adds SHA256 hashing and semver versioning
for drift detection.

Stack position

PR 3 for #120 — least-privilege CDK bootstrap policies as code

Prior: ADR-002 documented the design rationale (PR #133, pending merge)

This PR: Policies as code with tests and audit artifacts

Next: Custom bootstrap template generation (#123)

Key decisions

• Uses iam.PolicyDocument / iam.PolicyStatement for CDK interop (downstream Aspect in feat(bootstrap): CDK Aspect for policy envelope checking #125)
• Golden-file test enforces parity with DEPLOYMENT_ROLES.md — drift in either direction fails CI
• ECS conditional deferred to feat(bootstrap): custom bootstrap template generation #123 (context-gated in bootstrap template)
• Generated JSON committed as audit artifacts for security reviewers

Test plan

• npx jest test/bootstrap/ passes (31 tests)
• Golden-baseline test confirms action-for-action parity with DEPLOYMENT_ROLES.md
• Each policy < 6,144 chars (IAM limit)
• All SIDs globally unique across 3 policies
• Hash is deterministic and snapshot-locked
• tsc --noEmit compiles cleanly

References: RFC #120, ADR-002 (#133)

🤖 Generated with Claude Code

[scottschreckengaust]

#126 — has a detailed implementation note explaining the version-bump enforcement gap and how the preflight validator should close it.

Summary of the artifact management lifecycle:

Developer changes policy TS
↓
CI fails (3 ways):
• snapshot mismatch (hash changed)
• artifact-sync test (committed files stale)
• golden-baseline test (if DEPLOYMENT_ROLES.md also needs updating)
↓
Developer must:
1. Bump BOOTSTRAP_VERSION in version.ts
2. Run generate-bootstrap-artifacts.ts
3. Update snapshot (-u)
4. Commit all together
↓
Operator pulls & deploys
↓
Preflight (#126, future) compares deployed hash vs required hash
• Match → deploy proceeds
• Mismatch → "re-bootstrap required" + exact command

The version-bump itself remains a developer responsibility (enforced by review convention now, deploy-time gate in #126 later). The files exist to give
the preflight validator something to compare against the live CDKToolkit stack outputs.

---

the combination of two tests:

1. artifact-sync.test.ts — asserts each committed JSON file (cdk/bootstrap/policies/infrastructure.json etc.) equals the live fn().toJSON() output. So TypeScript → JSON conversion is verified.
2. artifact-sync.test.ts — asserts committed BOOTSTRAP_HASH equals computeBootstrapHash(), which itself is computed from the live allPolicies().map(p => p.toJSON()) output. So the hash is verified against the actual policy content.

The chain is:

TypeScript policies (source of truth)
↓ toJSON()
Live PolicyDocument objects
↓ compared by artifact-sync test
Committed JSON files (must match)
↓ SHA256 of serialized toJSON()
Computed hash
↓ compared by artifact-sync test
Committed BOOTSTRAP_HASH file (must match)

If any link breaks — TypeScript changes, JSON stale, hash stale — the test fails. The golden-baseline test separately verifies the TypeScript matches DEPLOYMENT_ROLES.md, closing the full loop from documentation → code → artifacts → hash.