feat(bootstrap): resource-action-map for synth-time validation

[scottschreckengaust]

Parent

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

Branch strategy

feat/bootstrap-action-map → targets feat/bootstrap-template

Estimated review time: ~25 min

Summary

Create a mapping from CloudFormation resource types to the IAM actions required to manage them (CRUD lifecycle), scoped to the ~30 resource types used by this app. This map powers the synth-time Aspect (Sub-issue 5) and informs the preflight validator (Sub-issue 6).

Deliverables

• Create cdk/src/bootstrap/preflight/resource-action-map.ts:
  • Export a typed map: Record<string, { create: string[], read: string[], update: string[], delete: string[] }>
  • Cover all CF resource types present in cdk.out/ after synth (e.g., AWS::DynamoDB::Table, AWS::Lambda::Function, AWS::ApiGateway::RestApi, AWS::EC2::VPC, AWS::Cognito::UserPool, AWS::WAFv2::WebACL, AWS::Bedrock::Guardrail, etc.)
  • Each entry's action list is the minimum CloudFormation needs to manage the resource lifecycle
• Create cdk/src/bootstrap/preflight/index.ts — barrel export
• Create cdk/test/bootstrap/resource-action-map.test.ts:
  • All resource types in the synthesized template have a mapping entry (synth → extract types → assert coverage)
  • Each action list is non-empty
  • All actions use valid IAM action format (service:ActionName)
  • Combined action set is a subset of the three policy documents' action sets (the map doesn't require more than what policies allow)

Key design decisions

• Scoped to this app's resources — not all 800+ AWS CF resource types. Keeps maintenance tractable.
• Actions derived from CloudFormation resource type documentation and validated against CloudTrail from prior deployments.
• Unknown resource types (not in map) produce a warning, not an error — allows new constructs to be added without immediately updating the map.
• Map is a plain TypeScript object (not loaded from JSON) — benefits from IDE autocomplete and type checking.

Acceptance criteria

• mise //cdk:synth followed by resource-type extraction shows 100% map coverage of current template
• All tests pass
• No circular imports between preflight/ and policies/

[scottschreckengaust]

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

The following items need updating in this issue's body before implementation:

1. Branch strategy

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

2. "Three policy documents" → "configured policy set"

The test "combined action set is a subset of the three policy documents' action sets" should validate against the configured policy set — the three core policies (infrastructure, application, observability) plus the active compute-variant policies (e.g., compute-agentcore). Not all five globally, not just three statically.

3. New deliverable: REQUIRED_BOOTSTRAP_POLICIES constant

Introduce cdk/src/bootstrap/required-policies.ts:

• Exports getRequiredBootstrapPolicies(computeType: string): string[]
• Returns core policies + compute-variant policies based on CDK context compute_type
• Consumed downstream by the Aspect (feat(bootstrap): CDK Aspect for policy envelope checking #125) and preflight validator (feat(bootstrap): live-account preflight validator #126)
• This is where the app declares "I need these policies" — the sufficiency model's app-side contract

4. Map scoping

Resource-action-map entries should be scoped to the app's active compute type. ECS resource types (e.g., AWS::ECS::Cluster) only need map coverage when compute_type=ecs. The coverage test should synth with the relevant compute type and validate map completeness for that configuration.

5. Traceability

Note in the issue: this implements the "action-set comparison" layer from #120's versioning table — "precisely which actions are missing?"

[scottschreckengaust]

Implementation Status & Inconsistencies (2026-05-29)

PR #165 is rebased on main (post-#211 merge) with all 4 tasks complete. Noting inconsistencies for downstream workers picking up #125–#128:

Resolved by current implementation

1. Branch targets main directly — feat(bootstrap): custom template generator with compute-variant policies #162 merged, stacking no longer needed. Sub-issues 5–8 should branch from main once feat(bootstrap): resource-action-map for synth-time validation #165 merges.
2. ECS context gate (refactor(compute): gate ECS construct on compute_type context instead of comment toggle #164) — Fully implemented in PR feat(bootstrap): resource-action-map for synth-time validation #165 Task 0. Issue refactor(compute): gate ECS construct on compute_type context instead of comment toggle #164 should close when feat(bootstrap): resource-action-map for synth-time validation #165 merges.
3. Dynamic orchestrator wiring — ...(ecsCluster && { ecsConfig }) spread replaces the old comment-toggle pattern.

Open questions for review/next worker

4. SQS policy gap — Plan's Open Question Docs: user guide hard-codes us-east-1 #3 flagged AWS::SQS::Queue / QueuePolicy lacking coverage. Was this resolved by the map test passing (wildcard match?), or deferred? Needs explicit resolution comment.
5. compute-ecs policy module — getRequiredBootstrapPolicies('ecs') returns 'compute-ecs' but no TypeScript policy module exists under cdk/src/bootstrap/policies/. The rendered JSON (cdk/bootstrap/policies/compute-ecs.json) exists but the source .ts doesn't. Intentional deferral? Document for feat(bootstrap): CDK Aspect for policy envelope checking #125 worker.
6. Resource type count drift — Plan says 57/61 types. PR feat(security): per-session IAM scoping — tag-scoped SessionRole for agent tenant-data access (#209) #211 added AgentSessionRole (new IAM resources). Workers on feat(bootstrap): CDK Aspect for policy envelope checking #125 should regenerate the type list from fresh cdk synth output, not the plan snapshot.
7. agentSessionRole is now required for ECS — PR feat(security): per-session IAM scoping — tag-scoped SessionRole for agent tenant-data access (#209) #211 merged a mandatory agentSessionRole prop on EcsAgentCluster. ECS synth (compute_type=ecs) requires this in scope. The dual-config test must account for it.
8. Update/destroy cycle validation (original plan Tasks 15–16) — The 2026-04-23 deployment validation plan tracked update + destroy testing. Status unknown. If untested, the scoped role may be missing UpdateStack/DeleteStack-path actions that only surface during lifecycle operations.

Superseded local artifacts

The docs/superpowers/plans/ directory contains the original planning files. All actionable content is now in this issue (#124), PR #165 comments, and RFC #120. The policies/*.json files there are the old 3-way split (pre-#162); current policies live in cdk/bootstrap/policies/.

[scottschreckengaust]

SQS gap identified: AWS::SQS::Queue and AWS::SQS::QueuePolicy are in the synthesized template (DLQs for Lambda event-source mappings in fanout-consumer and approval-metrics-publisher-consumer), but no bootstrap policy includes sqs:* actions. Fix: add SQS statement to application.ts. Will be committed to PR #165.