feat(security): per-session IAM scoping — session-tagged AssumeRole, DynamoDB leading-key conditions, Bedrock ARN allowlist

[krokoko]

Summary

⚠️ SCOPE REVISED 2026-05-28 (v4) — pending RE-APPROVAL. Evolution captured in this issue's comments: v2 reframed to the achievable design; v3 added design-review corrections (role-chaining 1h cap, Bedrock credential chain, full client surface); v4 makes the design backend-agnostic across both compute backends (AgentCore Runtime + ECS Fargate).

Reduce cross-task blast radius from a compromised agent session by scoping each task's agent tenant-data access (DynamoDB, trace S3) to short-lived, task_id/user_id-tagged IAM credentials — on both compute backends — instead of the long-lived shared compute role.

Roadmap: "Per-session IAM scoping" (Credentials and authorization). Design: docs/design/SECURITY.md. Resolves the TODO at cdk/src/stacks/agent.ts:376-389.

Backend context

The platform runs the agent under a ComputeStrategy:

• AgentCore Runtime (live): agent boots under the per-runtime ExecutionRole. Bedrock already ARN-scoped via grantInvoke.
• ECS Fargate (ecs-agent-cluster.ts, currently commented out in agent.ts:540-583, gating tracked in refactor(compute): gate ECS construct on compute_type context instead of comment toggle #164): agent boots under the Fargate task role (ECS credential endpoint). Bedrock currently Resource:'*'; task role is also missing Approvals/Nudges/trace/attachments grants.

Both base credentials are themselves assumed-role creds → an agent-side sts:AssumeRole is role chaining on both → 1h cap applies on both.

Design (backend-agnostic)

1. Per-task SessionRole + refreshable agent-side AssumeRole (portable). Agent (agent/src/) assumes a per-task SessionRole with session tags {user_id, repo, task_id} at startup and uses the derived creds for tenant-data clients only. Identical Python on both backends. SessionRole self-constrains via aws:PrincipalTag/*.
   • Refreshable credential provider (botocore RefreshableCredentials) re-assumes before the 1h role-chaining cap; tasks run to maxLifetime 8h. A one-shot assume_role() would ExpiredToken mid-task — forbidden.
   • SessionRole trust policy permits both compute roles (AgentCore exec role + ECS task role) as principals allowed to sts:AssumeRole/sts:TagSession, constrained so only they may pass tag values.
2. task_id leading-key conditions on TaskTable, TaskEventsTable, TaskApprovalsTable, TaskNudgesTable (dynamodb:LeadingKeys/FirstPartitionKeyValues ← aws:PrincipalTag/task_id). Scan denied/omitted. Cross-table approval TransactWriteItems satisfied (shared task_id). On the SessionRole — backend-agnostic.
3. S3 trace-prefix condition ← aws:PrincipalTag/user_id (resolves agent.ts:376-389); attachments read scoped. On the SessionRole.
4. Bedrock per backend:
   • AgentCore exec role: already ARN-scoped — leave as-is (optional action-glob tidy).
   • ECS task role: replace Resource:'*' on InvokeModel with the explicit model + inference-profile ARNs (parity with AgentCore). Net-new work.
5. Compute-role slimming + parity: both compute roles keep baseline (Bedrock, logs, secrets, Memory) plus sts:AssumeRole/sts:TagSession on the SessionRole. Tenant-data grants move OFF the compute roles onto the SessionRole. ECS task role gains the currently-missing grants (Approvals, Nudges, trace, attachments) — now expressed only via the SessionRole, so parity is achieved by construction.

Tenant-data clients to switch to the session (6) vs. left on compute role (8)

• Switch: DDB task_state.py:59/549, nudge_reader.py:82, progress_writer.py:380; S3 trace telemetry.py:456; S3 attachments read attachments.py:61.
• Leave: secrets config.py:33/97 (PAT read once at startup, pre-assume), CloudWatch logs shell.py:67/server.py:153,180/telemetry.py:59,167, AgentCore Memory memory.py:43.
• AgentCore Memory session-tag scoping: DEFERRED (not leading-key-able; namespace isolation actorId=repo/sessionId=task_id is the current boundary).

Acceptance criteria

• Per-task SessionRole; trust policy admits both the AgentCore exec role and ECS task role as assuming principals (synth-verified).
• Agent assumes SessionRole with tags {user_id, repo, task_id} via a refreshable provider; test simulates >1h run → auto re-assume (no ExpiredToken). Verifiable via CloudTrail / sts:GetCallerIdentity.
• 6 tenant-data boto3 constructions use the session; 8 non-tenant remain on the compute role (agent tests assert).
• task_id leading-key conditions on the 4 task tables (on SessionRole); Scan denied/omitted; synth tests assert; approval TransactWriteItems still succeeds.
• user_id prefix condition on trace-bucket PutObject; agent.ts:376-389 TODO removed.
• ECS task-role Bedrock Resource:'*' replaced with explicit model/inference-profile ARNs; ECS NagSuppression reason (ecs-agent-cluster.ts:141) updated accordingly.
• Both compute roles slimmed to baseline + sts:AssumeRole/TagSession; tenant-data grants live only on the SessionRole; ECS parity (Approvals/Nudges/trace/attachments) achieved via SessionRole.
• In-account validation that ${aws:PrincipalTag/...} drives dynamodb:LeadingKeys (policy simulator or live test).
• mise //cdk:test, //cdk:synth, //agent:quality pass; no new unsuppressed cdk-nag findings (incl. the dormant ECS construct path).
• docs/design/SECURITY.md + docs/guides/ROADMAP.md updated; Starlight mirrors regenerated (mise //docs:sync).
• No task-lifecycle regression on a >1h task; verified on AgentCore (live). ECS construct synth-verified (backend dormant — no live deploy test possible until refactor(compute): gate ECS construct on compute_type context instead of comment toggle #164).

Out of scope

GitHub App/Token Vault PAT replacement; MicroVM attestation; layered per-tool derivation; principal-to-repo auth; table remodel to PK=user_id; AgentCore Memory session-tag scoping; enabling the ECS backend itself (#164).

Key references

• Role-chaining 1h cap: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html
• AgentCore exec role per-runtime: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html
• dynamodb:LeadingKeys = base-table PK only: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/specifying-conditions.html , https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazondynamodb.html
• IAM session tags / aws:PrincipalTag: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html

Risks

• Major change — CDK (SessionRole construct, AgentCore exec role, dormant ECS construct) + agent Python (refreshable STS provider, client wiring).
• Touching the commented-out ECS block: must keep it synth-clean without enabling it (coordinate with refactor(compute): gate ECS construct on compute_type context instead of comment toggle #164).
• SessionRole trust must prevent tag impersonation (only the two compute roles may pass tags).
• Refreshable-creds bug class: clock skew, refresh-on-error, thread-safety across async hooks — explicit tests.

[krokoko]

Starting implementation.

Pre-start checks (ADR-003):

• approved label present, self-assigned (@krokoko)
• blockedBy: none; no parent/predecessor issues
• Cross-reference audit: no duplicate issues; no open PR scopes per-session IAM. PR feat(bootstrap): resource-action-map for synth-time validation #165 (feat/bootstrap-action-map) also edits cdk/src/stacks/agent.ts but in the bootstrap/preflight region — low conflict risk, will rebase if it merges first.

Note: flagged "Major change" (new IAM architecture + agent credential contract). Per CLAUDE.md Boundaries I'll post a design sketch on this issue for alignment before writing implementation code — resolving the two open unknowns (AgentCore Runtime session-credential delivery mechanics; whether task/event/approval table key schemas support dynamodb:LeadingKeys conditions).

Branch: feat/209-per-session-iam-scoping.

[krokoko]

Design investigation — findings change scope (re-approval likely needed)

Investigated the codebase + AWS docs before implementation (per CLAUDE.md "Major changes"). Three of the issue's stated deliverables turn out to be already done, impossible as written, or require an architecture not implied by the issue. Details below with sources.

Finding 1 — Bedrock ARN allowlist (criterion 3): already implemented ✅

grantInvoke on the three BedrockFoundationModel + CrossRegionInferenceProfile objects (agent.ts:428-433) already scopes the runtime role to explicit ARNs. Synth of the runtime ExecutionRole confirms no Resource: "*" on any Bedrock statement — each bedrock:InvokeModel* is pinned to e.g. arn:aws:bedrock:*::foundation-model/anthropic.claude-sonnet-4-6 and the us.anthropic.* inference-profile ARNs.

The AwsSolutions-IAM5 suppression (agent.ts:444) covers only the action-level glob InvokeModel* (→ could be expanded to explicit InvokeModel + InvokeModelWithResponseStream) and the genuinely wildcard-only actions that don't support resource scoping: cloudwatch:PutMetricData, xray:Put*, ecr:GetAuthorizationToken. So this criterion is essentially a no-op; at most a cosmetic action-glob tightening.

Finding 2 — Per-session tagged credentials (criterion 1): not achievable via the AgentCore service

AgentCore Runtime's execution role is per-runtime, shared across all sessions/invocations. The trust policy grants bedrock-agentcore.amazonaws.com a plain sts:AssumeRole with no sts:TagSession and no session-tag pass-through. There is no API parameter to inject per-invocation session tags, and AgentCore explicitly does not maintain session↔user mappings.

• Source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html , https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-sessions.html

runtimeUserId (already passed at agentcore-strategy.ts:59) drives the AgentCore Identity workload-access-token path — a first-party opaque token, not scoped AWS IAM credentials.

• Source: https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html , https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/get-workload-access-token.html

The only way to get per-session scoped IAM credentials: the agent code itself (inside the MicroVM) calls sts:AssumeRole with Tags={user_id,repo,task_id}, using the execution role as a minimal bootstrap principal. The per-task session role then self-constrains via aws:PrincipalTag/* conditions. This is a real, supported ABAC pattern — but it moves the work into agent/src/ (Python), not just CDK, and reshapes the execution role into a bootstrap-only role.

• Source: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html

Finding 3 — DynamoDB leading-key conditions (criterion 2): cannot key on user_id for the main tables

dynamodb:LeadingKeys (and the newer FirstPartitionKeyValues) binds only to the base-table partition key — never a GSI partition key (confirmed in both the DynamoDB Developer Guide and the Service Authorization Reference).

• Source: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/specifying-conditions.html , https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazondynamodb.html

Current key schemas (verified):

Table	Base PK	Runtime grant
TaskTable	task_id (user_id only a GSI)	RW
TaskEventsTable	task_id + event_id	RW
TaskApprovalsTable	task_id + request_id	RW
TaskNudgesTable	task_id + nudge_id	RW
UserConcurrencyTable	user_id	RW

So per-user_id leading-key isolation is impossible for the four task-scoped tables without a table remodel (PK→user_id), which would break task_id GetItem lookups and require a data migration — not viable.

But the natural isolation boundary is actually task_id: one task = one session = one MicroVM. Leading-keys on task_id is directly enforceable and would prevent a compromised session from reading/writing any other task's records — a strong blast-radius reduction. user_id leading-keys works cleanly on UserConcurrencyTable only.

Revised achievable design

1. Bootstrap execution role + agent-side AssumeRole — minimal exec role whose net-new privilege is sts:AssumeRole/sts:TagSession on a per-task session role. Agent (agent/src/) assumes it with tags {user_id, repo, task_id} at startup; all DDB/S3 access uses the derived session.
2. task_id leading-key conditions on Task/Events/Approvals/Nudges (via aws:PrincipalTag/task_id); user_id leading-key on UserConcurrencyTable.
3. S3 prefix condition on the traces bucket keyed on aws:PrincipalTag/user_id — directly resolves the existing TODO at agent.ts:376-389.
4. Bedrock — leave as-is (already scoped) or trivially tighten the action glob.

Caveat to validate in-account: AWS's LeadingKeys examples use federated-identity variables, not ${aws:PrincipalTag/...}. Driving leading-keys from a session tag is standard ABAC and structurally valid, but I'll confirm with the IAM policy simulator / a live test before relying on it.

Why this needs a scope decision

The approved issue framed this as a CDK-only, user_id-keyed change. Reality: it's CDK + agent-Python, task_id-keyed for the main tables, and criterion 3 is already met. That changes the deliverables, so per ADR-003 the scope should be re-confirmed/re-approved before I implement. Posting options in the thread.

[krokoko]

Scope revised → requesting re-approval (ADR-003 §scope-frozen).

The approved scope changed materially after investigation, so I've removed the approved label and rewritten the issue body to the achievable design (full revised design, per maintainer direction):

• Bootstrap ExecutionRole + agent-side sts:AssumeRole with {user_id, repo, task_id} session tags (AgentCore can't vend per-session tagged creds).
• task_id leading-key isolation on the 4 task tables; user_id on UserConcurrencyTable.
• S3 trace-prefix condition (resolves the agent.ts:376-389 TODO).
• Bedrock allowlist already shipped → at most a cosmetic action-glob tidy.

Deliverables now span CDK + agent/src Python and key on task_id rather than user_id. No code written yet — the worktree feat/209-per-session-iam-scoping exists with deps installed and a clean baseline build only.

@admin: please re-apply approved if the revised body looks right, or comment with adjustments. I'll begin implementation once re-approved.

[krokoko]

Design review — verified against code + AWS docs. Three corrections, otherwise sound.

Re-reviewed the revised design adversarially. The IAM-mechanism conclusions hold, but two runtime-breaking gaps and one scope-completeness gap surfaced. Net: design is correct in direction, needs three fixes before implementation.

✅ Confirmed correct

• task_id is the right isolation key. Every agent DDB access keys on task_id (task_state.py:114/167/219/306/383/453, approvals at :781/812, nudges Key={task_id,nudge_id}). The agent reads/writes Task, Events, Approvals, Nudges — never queries a GSI and never touches UserConcurrencyTable (that's orchestrator/reconciler only). So task_id leading-keys won't break any agent read path.
• Cross-table TransactWriteItems (transact_write_approval_request: Put TaskApprovals + Update TaskTable) — both items keyed by the same task_id, so a single task_id principal-tag satisfies leading-keys on both. ✔
• Bedrock already ARN-scoped (no Resource:*); session-tag self-constraint via aws:PrincipalTag is valid ABAC.

❌ Correction 1 — Role chaining caps the session at 1 hour, but maxLifetime is 8 hours (agent.ts:332-333)

The agent runs under the AgentCore execution role, so the agent calling sts:AssumeRole on the SessionRole is role chaining, which AWS hard-caps at 1 hour regardless of the role's MaxSessionDuration — "if you assume a role using role chaining and provide a DurationSeconds parameter value greater than one hour, the operation fails." (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html)

A task can run up to 8h. Static assumed creds would expire mid-task and every DDB/S3 call after ~1h would fail with ExpiredToken.
Fix: the agent must use a refreshable credential provider (e.g. botocore RefreshableCredentials / DeferredRefreshableCredentials wrapping a re-AssumeRole), not a one-shot assume_role() call. This must be an explicit acceptance criterion + test (simulate expiry → auto-refresh).

❌ Correction 2 — Bedrock InvokeModel uses the default credential chain, which would break under the SessionRole

The Claude Agent SDK invokes Bedrock via CLAUDE_CODE_USE_BEDROCK=1 (runner.py:70) — the Node CLI subprocess picks up creds from the process/container default chain (the execution role), independently of any boto3 session the Python agent creates. The design said "all subsequent access uses the derived session," but:

• If we don't export the assumed creds to the subprocess env, InvokeModel keeps using the execution role → then the execution role still needs bedrock:InvokeModel* (can't be a pure bootstrap role), and Bedrock is not session-tag-scoped.
• If we do export assumed creds to the subprocess, the SessionRole needs the Bedrock ARN grants too and the 1-hour expiry (Correction 1) now also breaks model calls — far worse blast radius.
  Fix: decide explicitly. Recommended: leave bedrock:InvokeModel on the execution role (already ARN-scoped, low cross-tenant value since models are shared, not tenant data) and scope only tenant-data access (DDB/S3) to the SessionRole. The "bootstrap role" framing in the issue body is therefore wrong — the execution role retains Bedrock + the new sts:AssumeRole.

⚠️ Correction 3 — Incomplete client refactor surface + AgentCore Memory

There are 14 boto3 client/resource constructions across agent/src/. The design only named DDB/S3. For correct enforcement each tenant-data client must use the refreshable session:

• DDB: task_state.py:59/549, nudge_reader.py:82, progress_writer.py:380
• S3: attachments.py:61 (read), telemetry.py:456 (trace upload)
• AgentCore Memory (memory.py:43, bedrock-agentcore client) — scoped by actorId=repo, sessionId=task_id; runtime has grantReadWrite. Decide whether Memory is in scope for session-tag scoping (likely defer — it's not IAM-leading-key-able and namespace isolation already exists).
• Out of scope (keep on execution role): secrets (config.py GitHub PAT — read once at startup before assume), logs (shell.py/server.py/telemetry.py CloudWatch).

Revised acceptance criteria deltas

• Agent uses a refreshable assumed-role credential provider (auto re-AssumeRole before 1h expiry); test simulates expiry + refresh.
• bedrock:InvokeModel* stays on the execution role (NOT moved to SessionRole); execution role = baseline Bedrock/logs/secrets + sts:AssumeRole/TagSession on SessionRole. Drop the "bootstrap-only role" framing.
• SessionRole scopes tenant-data clients only: DDB (4 tables, task_id leading-keys), trace-bucket S3 (user_id prefix), attachments read. Each of the 6 tenant-data boto3 constructions switched to the session; the 8 non-tenant ones explicitly left on the execution role.
• AgentCore Memory session-tag scoping explicitly deferred (namespace isolation documented as the current boundary).

I'll fold these into the issue body. Still no code written. Re-approval should be against the corrected body.

[krokoko]

⚠️ Design gap: ECS Fargate backend not accounted for

Good catch in review — the v3 design was AgentCore-shaped. We also support an ECS Fargate compute backend (ComputeStrategy): ecs-strategy.ts + ecs-agent-cluster.ts. It's currently commented out in agent.ts:540-583 (dormant; gating tracked in #164) but fully implemented and routable via compute_type: 'ecs'.

ECS differs from AgentCore in ways that affect this issue

Aspect	AgentCore	ECS Fargate (ecs-agent-cluster.ts)
Agent base credential	Runtime ExecutionRole (per-runtime)	Fargate task role via ECS cred endpoint (:112)
Bedrock scoping today	✅ ARN-scoped via grantInvoke	❌ resources: ['*'] wildcard (:123-129)
Tenant-data grants	Task, Events, Approvals, Nudges, trace S3, attachments	Only Task, Events, UserConcurrency, secrets, logs (missing Approvals/Nudges/trace/attachments)
Role delivery	Service-assumed exec role	Orchestrator iam:PassRole of task+exec role at RunTask (:134-136)

Corrections to the design

1. Bedrock ARN-allowlist is NOT a no-op for ECS — the ECS task role has a genuine Resource: * on InvokeModel. The "Bedrock already scoped, skip" conclusion was AgentCore-only.
2. Agent-side refreshable AssumeRole is the portable solution and the reason to prefer it: identical agent Python works whether booting under an AgentCore exec role or an ECS task role. Both base creds are themselves assumed-role creds → both hit the 1h role-chaining cap → refreshable provider required on both. (ECS RunTask overrides.taskRoleArn is a backend-specific alternative but can't inject session tags, so the portable path wins.)
3. ECS task role is already behind on grants (no Approvals/Nudges/trace/attachments) — a SessionRole rework there doubles as parity catch-up.

Scope decision needed

• (A) Backend-agnostic now: build SessionRole + leading-keys + refreshable creds once in the agent (works for both), and apply the IAM construct changes to both the AgentCore exec role and the ECS task role (incl. ARN-scoping ECS Bedrock). Larger, but no follow-up debt.
• (B) AgentCore-only now + ECS follow-up: scope feat(security): per-session IAM scoping — session-tagged AssumeRole, DynamoDB leading-key conditions, Bedrock ARN allowlist #209 to the live AgentCore path; file a follow-up issue to bring the dormant ECS task role to parity (SessionRole + ARN-scoped Bedrock + missing grants). Smaller, ships the live path faster.

Leaning (A) for the agent-side code (it's naturally portable) + (B) for the ECS CDK construct (dormant, can be a fast-follow) — i.e. write the portable agent once, scope the CDK wiring to AgentCore now, follow up on the ECS construct. Awaiting maintainer direction before finalizing the body.

[krokoko]

Starting implementation (revised v4 backend-agnostic scope, re-approved).

Plan:

1. Portable refreshable-AssumeRole credential provider in agent/src/ + tests (riskiest — clock skew, async thread-safety)
2. SessionRole construct + trust policy admitting both compute roles
3. task_id leading-key + S3 user_id prefix conditions; slim both compute roles; ARN-scope ECS Bedrock
4. In-account PrincipalTag→LeadingKeys validation
5. Docs + mise //docs:sync

Branch: feat/209-per-session-iam-scoping.

[krokoko]

✅ In-account validation: ${aws:PrincipalTag/...} drives both isolation conditions

Validated the design's one doc-unverified assumption with the IAM policy simulator (iam:SimulateCustomPolicy, read-only — no resources created), using the exact policy shapes the constructs emit.

DynamoDB task_id leading-keys (statement from AgentSessionRole):

Scenario	dynamodb:LeadingKeys	aws:PrincipalTag/task_id	Decision
Own task's items	task-abc	task-abc	allowed ✅
Another task's items	task-OTHER	task-abc	implicitDeny ✅
No tag present (impersonation attempt)	task-abc	(unset)	implicitDeny ✅ (fail-closed)

S3 per-user trace prefix (traces/${aws:PrincipalTag/user_id}/*):

Scenario	Object key	aws:PrincipalTag/user_id	Decision
Own prefix	traces/user-1/...	user-1	allowed ✅
Another user's prefix	traces/user-2/...	user-1	implicitDeny ✅

Confirms: ${aws:PrincipalTag/...} substitutes correctly into dynamodb:LeadingKeys and S3 resource ARNs, cross-tenant access is denied, and a session with no tag fails closed. This was the only assumption AWS docs left open (their LeadingKeys examples use federated-identity variables). Acceptance criterion met.

[krokoko]

Implementation complete — opened #211.

All acceptance criteria met:

• ✅ Per-task SessionRole; runtime ExecutionRole slimmed to non-tenant + assume
• ✅ Refreshable agent-side AssumeRole with {user_id, repo, task_id} tags (1h-cap-safe)
• ✅ task_id leading-keys on the 4 task tables (Scan denied); S3 user_id prefix; agent.ts:376 TODO removed
• ✅ ECS task-role Bedrock ARN-scoped; backend-agnostic SessionRole trust
• ✅ In-account policy-simulator validation of PrincipalTag→LeadingKeys + S3 prefix
• ✅ 808 agent + 1798 cdk tests; full mise run build green; docs + Starlight mirrors updated

Ready for review.