feat(bootstrap): custom bootstrap template generation

[scottschreckengaust]

Parent

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

Branch strategy

feat/bootstrap-template → targets feat/bootstrap-policies

Estimated review time: ~30 min

Summary

Generate a custom CDK bootstrap CloudFormation template that replaces AdministratorAccess with the three IaCRole-ABCA policies, and adds version/hash outputs for preflight validation.

Deliverables

• Create cdk/src/bootstrap/bootstrap-template.ts — programmatically generates the custom CF template:
  • Based on CDK's default bootstrap template structure
  • Substitutes AdministratorAccess on the CloudFormation execution role with the three managed policies
  • Adds CF outputs: BootstrapPolicyVersion, BootstrapPolicyHash
  • Retains all other default resources (S3 staging bucket, ECR repo, deploy/lookup/publishing roles)
• Create cdk/test/bootstrap/bootstrap-template.test.ts:
  • Generated template is valid YAML/JSON
  • Execution role references exactly three managed policies (not AdministratorAccess)
  • BootstrapPolicyVersion and BootstrapPolicyHash outputs are present
  • All default bootstrap resources still exist
  • Template parameters match CDK bootstrap expectations
• Generate cdk/bootstrap/bootstrap-template.yaml — the operator-consumable artifact
• Add mise //cdk:bootstrap:generate task in cdk/mise.toml — regenerates all cdk/bootstrap/ artifacts
• Add mise //cdk:bootstrap task — wraps cdk bootstrap --template cdk/bootstrap/bootstrap-template.yaml

Key design decisions

• Template is generated (not hand-edited) so it stays in sync with policy source code
• Uses CF pseudo-parameters (AWS::AccountId, AWS::Region) for account/region — no hardcoding
• Managed policies are created inline in the template (not referencing external ARNs) — eliminates the "create policies first, then bootstrap" two-step
• Qualifier remains hnb659fds (CDK default) for compatibility with existing deployments

Acceptance criteria

• mise //cdk:bootstrap:generate produces a valid CF template
• Template passes cfn-lint validation (if available)
• Existing mise //cdk:synth and mise //cdk:test still pass (no regression)
• An operator can bootstrap a fresh account with a single command: mise //cdk:bootstrap

[scottschreckengaust]

Architecture revision: per-compute-variant policies

After reviewing #122's implementation and the placement boundaries, proposing the following changes to this issue's design:

1. Template generator is a build script, not a CDK construct

The bootstrap template is an operational prerequisite (separate CDKToolkit stack), not part of the application synthesis. The generator belongs in cdk/scripts/, not cdk/src/:

cdk/scripts/generate-bootstrap-template.ts   ← generator (build tool)
cdk/bootstrap/bootstrap-template.yaml        ← output (operator artifact)
cdk/src/bootstrap/policies/                  ← stays (Aspect in #125 imports at synth-time)

2. Per-compute-variant policies instead of monolithic ECS conditional

Rather than cramming ECS into the Application policy or a single "Compute" policy, use per-variant policy modules:

Policy	Always required?	Scope
infrastructure	Yes	VPC, IAM, CloudFormation
application	Yes	DynamoDB, Lambda, API GW, Cognito, WAF, EventBridge, Secrets
observability	Yes	Bedrock, CloudWatch, ECR, S3, KMS, SSM, STS
compute-agentcore	Yes (default runtime)	AgentCore-specific permissions
compute-ecs	Optional	ECS Fargate cluster, task definitions
compute-eks	Future	EKS permissions
compute-ec2	Future	EC2 permissions

Benefits:

• Each variant stays under 6,144 chars independently
• Operators get least-privilege for their specific deployment — no ECS permissions if unused
• Template accepts a parameter (e.g., ComputeTypes: agentcore,ecs) and conditionally includes relevant policy resources
• Adding new compute backends doesn't touch existing policies
• IAM allows up to 10 managed policies per role — plenty of headroom

3. Revised deliverables

• Create cdk/src/bootstrap/policies/compute-agentcore.ts — extract AgentCore-specific actions from current observability policy (currently bedrock-agentcore:*)
• Create cdk/src/bootstrap/policies/compute-ecs.ts — ECS statement from DEPLOYMENT_ROLES.md lines 611-637
• Create cdk/scripts/generate-bootstrap-template.ts — template generator
• Generate cdk/bootstrap/bootstrap-template.yaml with CF conditions for compute variants
• Add ComputeTypes template parameter (default: agentcore)
• Existing mise //cdk:bootstrap task wraps cdk bootstrap --template cdk/bootstrap/bootstrap-template.yaml

4. Open question

Should compute-agentcore actions be extracted out of the observability policy (breaking change to #122's output) or duplicated in the new policy (allowing the observability policy to remain stable)? The clean answer is extract — but that changes the golden-baseline test and requires a version bump. Recommend: extract and bump to 1.1.0 in this PR.

---

Requesting input before implementation begins. cc @scottschreckengaust

[scottschreckengaust]

Architecture revision v2: sufficiency model with operator-controlled ceiling

Incorporating feedback on multi-stack accounts and intentional restriction.

Core insight: bootstrap = security boundary ceiling

The CDKToolkit stack is account-level (one per account/region). Multiple app stacks may share it with different compute needs. The bootstrap's attached policies represent the maximum permissions the operator authorizes for any CloudFormation deployment in that account — not what any single stack needs.

Model

Operator bootstraps:
  ComputeTypes=agentcore         → PolicySet=[infra, app, obs, compute-agentcore]
  (intentionally excludes ECS — security posture decision)

App stack declares:
  requiredBootstrapPolicies: ['infrastructure', 'application', 'observability', 'compute-agentcore']

Preflight:
  deployed PolicySet ⊇ app's required set → PASS (proceed to deploy)
  deployed PolicySet ⊉ app's required set → FAIL with actionable message:
    "compute-ecs not in bootstrap PolicySet. Either:
     (a) re-bootstrap: mise //cdk:bootstrap -- --context ComputeTypes=agentcore,ecs
     (b) disable ECS in app config (set compute_type context to agentcore)"

Key principles

1. Bootstrap is additive, never subtractive — re-bootstrapping with more compute types adds policies without removing existing ones
2. Hash covers all attached policies — detects console drift (someone hand-edited IAM)
3. PolicySet output is the sufficiency check — "does bootstrap cover what the app needs?"
4. Operator restriction is intentional — a subset bootstrap is a security posture decision, not a misconfiguration. The app must not deploy if it exceeds the ceiling.
5. Fail fast, fail clear — preflight fails before CloudFormation starts, with exact remediation steps

Revised hash semantics

Check	What it compares	What failure means
Hash match	Deployed hash vs. computed hash of deployed PolicySet	Console drift — someone edited IAM outside code
PolicySet sufficiency	App's required set ⊆ deployed PolicySet	Missing compute variant — operator action needed
Version compatibility	Deployed version ≥ app's minimum required version	Stale bootstrap — permissions may be missing from known policies

Impact on #123 deliverables

• computeBootstrapHash(policyNames: string[]) — hash function takes explicit policy list (not always "all")
• Template parameter ComputeTypes (default: agentcore) — controls which compute policy resources are created
• CF output BootstrapPolicySet — comma-separated list of included policies
• CF output BootstrapPolicyHash — hash of the included policies only
• App-side constant: REQUIRED_BOOTSTRAP_POLICIES derived from CDK context compute_type

Impact on #122 (already merged)

• Extract bedrock-agentcore:* from observability → new compute-agentcore.ts
• Bump BOOTSTRAP_VERSION to 1.1.0
• allPolicies() returns core + all compute variants (for artifact generation)
• Add getPoliciesByNames(names: string[]) for selective hash computation
• Update golden-baseline test, artifact-sync test, regenerate artifacts

This extraction + the template generator are both in scope for #123.