@deployfoundation/foundation-deploy 0.1.0

package/src/stacks/agent-stack.ts

@@ -0,0 +1,938 @@
+import * as cdk from "aws-cdk-lib";
+import type * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import type * as ec2 from "aws-cdk-lib/aws-ec2";
+import * as ecr from "aws-cdk-lib/aws-ecr";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type * as kms from "aws-cdk-lib/aws-kms";
+import type * as s3 from "aws-cdk-lib/aws-s3";
+import type * as secretsmanager from "aws-cdk-lib/aws-secretsmanager";
+import type { Construct } from "constructs";
+import { agentImage, agentImageTagRequired, releaseImageRepositoryArn } from "../artifacts.ts";
+import {
+  type Instance,
+  type InstanceNames,
+  WEB_SEARCH_TARGET,
+  namesFor,
+  provisionsIntegration,
+  requiresAuthenticatedQueue,
+} from "../names.ts";
+
+export interface FoundationAgentProps extends cdk.StackProps {
+  /** The deployment this stack belongs to; every name below comes from it. */
+  instance: Instance;
+  vpc: ec2.IVpc;
+  egressSubnets: ec2.SubnetSelection;
+  agentSecurityGroup: ec2.ISecurityGroup;
+  /** SG on the S3 Files mount targets (NFS from `agentSecurityGroup`). */
+  mountTargetSecurityGroup: ec2.ISecurityGroup;
+  /** `FileSystemId` of the FoundationData S3 Files file system. */
+  fileSystemId: string;
+  /** ARN of its access point — mounted at `/mnt/sky`. */
+  dataKey: kms.IKey;
+  bucket: s3.IBucket;
+  /** Dedicated bucket for durable per-channel documents. */
+  documentBucket: s3.IBucket;
+  table: dynamodb.ITable;
+  /** The `pk`+`sk` table holding todos and routines. */
+  itemsTable: dynamodb.ITable;
+  /** Deployment-owned CRM table; never directly readable by the shell-capable agent. */
+  crmTable?: dynamodb.ITable;
+  /** Proxy-only proposal drafts; explicitly denied to every agent-assumable role. */
+  upworkApprovalTable?: dynamodb.ITable;
+  secrets: {
+    runtime: secretsmanager.ISecret;
+    codex: secretsmanager.ISecret;
+    googleAiStudio: secretsmanager.ISecret;
+    googleDrive: secretsmanager.ISecret;
+    googleCalendar: secretsmanager.ISecret;
+    googleOauth: secretsmanager.ISecret;
+    githubApp: secretsmanager.ISecret;
+    /** Read-only Atlas connection string; a placeholder until someone fills it. */
+    mongodbReadonly: secretsmanager.ISecret;
+    /** Read-only Otter Enterprise Public API key, provisioned only for opted-in instances. */
+    otterApi?: secretsmanager.ISecret;
+    /** Knock public client and credential; the shell-capable role is denied both. */
+    knockOauthClient?: secretsmanager.ISecret;
+    knockCredential?: secretsmanager.ISecret;
+    /** Combined Upwork OAuth client and token secret, explicitly denied to the agent role. */
+    upwork?: secretsmanager.ISecret;
+    /** The connected mailbox. The agent role is explicitly DENIED read on it. */
+    googleEmail: secretsmanager.ISecret;
+    slackApp: secretsmanager.ISecret;
+    signing: secretsmanager.ISecret;
+  };
+}
+
+/**
+ * FoundationAgent — the ECR repository holding the agent image and the AgentCore
+ * Runtime that runs it.
+ *
+ * There is no L2 construct for AgentCore, so the runtime is declared as the
+ * `AWS::BedrockAgentCore::Runtime` L1 resource.
+ *
+ * Two-phase bootstrap: the runtime references an image in the repo this same
+ * stack creates, and AgentCore validates the container URI at *create* time,
+ * so the first deploy must run with `-c deployRuntime=false` (repo + role
+ * only), push the image, then re-deploy with the flag on (the default).
+ * During phase one `agentRuntimeArn` is a syntactically valid `…-pending`
+ * placeholder so FoundationApi still synthesizes.
+ *
+ * AgentCore VPC mode supports only some AZs (us-east-1: use1-az1/az2/az4).
+ * CDK cannot check that at synth time, so `-c agentSubnetIds=subnet-a,subnet-b`
+ * is the escape hatch when the VPC's default egress subnets land in an
+ * unsupported zone.
+ */
+export class FoundationAgent extends cdk.Stack {
+  public readonly repository: ecr.Repository;
+  public readonly executionRole: iam.Role;
+  /** The S3 Files access point the runtime mounts at /mnt/sky. */
+  public readonly accessPoint: cdk.CfnResource;
+  private readonly accessPointArn: string;
+  /** Real `AgentRuntimeArn` when deployed, else the `-pending` placeholder. */
+  public readonly agentRuntimeArn: string;
+  /** MCP endpoint of the tool gateway; rides the runtime secret to the container. */
+  public readonly webSearchUrl: string;
+  /** The instance's OWN account expressed as a role `aws-readonly` assumes. */
+  public readonly readOnlyRole: iam.Role;
+
+  /** `namesFor(props.instance)`; the private helpers below read it. */
+  private readonly names: InstanceNames;
+
+  constructor(scope: Construct, id: string, props: FoundationAgentProps) {
+    super(scope, id, props);
+    const names = namesFor(props.instance);
+    this.names = names;
+    const display = props.instance.displayName;
+
+    const deployRuntime = String(this.node.tryGetContext("deployRuntime") ?? "true") !== "false";
+    const imageTag: string | undefined = this.node.tryGetContext("agentImageTag");
+
+    this.repository = new ecr.Repository(this, "AgentRepository", {
+      repositoryName: names.ecrRepo,
+      imageScanOnPush: true,
+      // Immutable tags: every build pushes a fresh tag (the short commit sha)
+      // and passes it as `-c agentImageTag=<tag>`.
+      imageTagMutability: ecr.TagMutability.IMMUTABLE,
+      encryption: ecr.RepositoryEncryption.KMS,
+      encryptionKey: props.dataKey,
+      // Only one tag is ever referenced; five keeps the live image plus four
+      // builds' worth of rollback.
+      lifecycleRules: [{ maxImageCount: 5 }],
+    });
+
+    // The access point is runtime-specific (POSIX ids of the container user,
+    // root directory) and its ARN changes when those change — keeping it here
+    // avoids a cross-stack export that CloudFormation would refuse to update
+    // while the runtime imports it (2026-09-05).
+    const accessPoint = new cdk.CfnResource(this, "FoundationMountAccessPoint", {
+      type: "AWS::S3Files::AccessPoint",
+      properties: {
+        FileSystemId: props.fileSystemId,
+        PosixUser: { Uid: "10001", Gid: "10001" },
+        // A dedicated root that S3 Files CREATES with these POSIX ids: the file
+        // system root itself is root-owned (0755), so a 10001 client could
+        // mount but not write (probe 2026-09-05: EACCES on /mnt/sky).
+        RootDirectory: {
+          Path: "/sky",
+          CreationPermissions: { OwnerUid: "10001", OwnerGid: "10001", Permissions: "0755" },
+        },
+      },
+    });
+    accessPoint.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);
+    this.accessPointArn = accessPoint.getAtt("AccessPointArn").toString();
+    new cdk.CfnOutput(this, "FoundationMountAccessPointArn", { value: this.accessPointArn });
+    this.accessPoint = accessPoint;
+    this.executionRole = this.buildExecutionRole(props);
+    this.readOnlyRole = this.buildReadOnlyRole(props);
+
+    // The gateway is independent of the runtime: it can (and does) exist
+    // during the phase-one bootstrap deploy.
+    const gateway = this.buildToolGateway(display);
+    this.webSearchUrl = gateway.getAtt("GatewayUrl").toString();
+    this.executionRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "InvokeToolGateway",
+        actions: ["bedrock-agentcore:InvokeGateway"],
+        resources: [gateway.getAtt("GatewayArn").toString()],
+      }),
+    );
+
+    if (!deployRuntime) {
+      // Phase one. FoundationApi needs a syntactically valid ARN to put in the
+      // gateway's environment; nothing can invoke this one.
+      this.agentRuntimeArn = `arn:${this.partition}:bedrock-agentcore:${this.region}:${this.account}:runtime/${names.runtimeName}-pending`;
+      this.outputs();
+      return;
+    }
+
+    // A release names the image by digest, so there is no tag to pass and
+    // nothing local to have built first.
+    if (!imageTag && agentImageTagRequired(this)) {
+      throw new Error(
+        `${id}: -c agentImageTag=<tag> is required when deploying the runtime. Pass the tag of an image already pushed to the ${names.ecrRepo} repository, deploy a release with -c release=<version>, or run the bootstrap phase with -c deployRuntime=false.`,
+      );
+    }
+
+    const explicitSubnets = String(this.node.tryGetContext("agentSubnetIds") ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const runtimeSubnets =
+      explicitSubnets.length > 0
+        ? explicitSubnets
+        : props.vpc.selectSubnets(props.egressSubnets).subnetIds;
+
+    // One mount target per egress subnet: the runtime schedules session ENIs
+    // across both AZs and a mount only resolves in its own AZ.
+    const mountTargets = runtimeSubnets.map(
+      (subnetId, index) =>
+        new cdk.CfnResource(this, `MountTarget${index}`, {
+          type: "AWS::S3Files::MountTarget",
+          properties: {
+            FileSystemId: props.fileSystemId,
+            SubnetId: subnetId,
+            SecurityGroups: [props.mountTargetSecurityGroup.securityGroupId],
+          },
+        }),
+    );
+
+    const runtime = new cdk.CfnResource(this, "AgentRuntime", {
+      type: "AWS::BedrockAgentCore::Runtime",
+      properties: {
+        AgentRuntimeName: names.runtimeName,
+        Description: `${display} agent runtime (Codex + Slack, single workspace)`,
+        AgentRuntimeArtifact: {
+          ContainerConfiguration: {
+            ContainerUri: agentImage(this, this.repository, imageTag),
+          },
+        },
+        NetworkConfiguration: {
+          NetworkMode: "VPC",
+          NetworkModeConfig: {
+            Subnets: runtimeSubnets,
+            SecurityGroups: [props.agentSecurityGroup.securityGroupId],
+          },
+        },
+        // BYO mounts require VPC mode (above) and are attached at
+        // *invocation* time, not container init — anything reading /mnt/sky
+        // must do so lazily, per request.
+        FilesystemConfigurations: [
+          {
+            S3FilesAccessPoint: {
+              AccessPointArn: this.accessPointArn,
+              MountPath: "/mnt/sky",
+            },
+          },
+        ],
+        LifecycleConfiguration: {
+          IdleRuntimeSessionTimeout: 3600,
+          MaxLifetime: 28800,
+        },
+        RoleArn: this.executionRole.roleArn,
+        EnvironmentVariables: {
+          // The whole env map lives in this one secret, read at boot by
+          // ts/agent/src/server.ts — so changing it needs no redeploy.
+          RUNTIME_SECRET_ID: props.secrets.runtime.secretName,
+          AWS_REGION: this.region,
+          FOUNDATION_WORKSPACE_ROOT: "/workspace",
+        },
+        // The App-level tag aspect cannot reach a raw CfnResource.
+        Tags: { project: props.instance.naming.secretPrefix },
+      },
+    });
+    runtime.node.addDependency(this.executionRole);
+    runtime.node.addDependency(accessPoint);
+    // The mount must exist in both AZs before a session can attach it.
+    for (const mountTarget of mountTargets) runtime.node.addDependency(mountTarget);
+
+    this.agentRuntimeArn = runtime.getAtt("AgentRuntimeArn").toString();
+    this.outputs();
+  }
+
+  private outputs(): void {
+    new cdk.CfnOutput(this, "AgentRuntimeArn", { value: this.agentRuntimeArn });
+    new cdk.CfnOutput(this, "RepositoryUri", { value: this.repository.repositoryUri });
+    new cdk.CfnOutput(this, "WebSearchGatewayUrl", { value: this.webSearchUrl });
+    new cdk.CfnOutput(this, "ReadOnlyRoleArn", { value: this.readOnlyRole.roleArn });
+  }
+
+  /**
+   * The AgentCore Gateway that fronts managed tool connectors, plus its one
+   * target: Amazon's `web-search` connector.
+   *
+   * Inbound is `AWS_IAM` — the container signs its MCP calls with the runtime
+   * execution role's own SigV4 credentials, so there is no OAuth issuer and no
+   * token to store. Outbound is `GATEWAY_IAM_ROLE`: the gateway calls the
+   * search tool as the service role built here, which can reach nothing else.
+   *
+   * There is no L2 for either resource, so both are raw L1s with the
+   * CloudFormation property names verbatim.
+   */
+  private buildToolGateway(display: string): cdk.CfnResource {
+    const gatewayArnPattern = `arn:${this.partition}:bedrock-agentcore:${this.region}:${this.account}:gateway/*`;
+    const role = new iam.Role(this, "ToolGatewayRole", {
+      description: "AgentCore tool gateway service role (web search only)",
+      assumedBy: new iam.ServicePrincipal("bedrock-agentcore.amazonaws.com", {
+        // Confused-deputy guard: only this account's gateways may assume it.
+        conditions: {
+          StringEquals: { "aws:SourceAccount": this.account },
+          ArnLike: { "aws:SourceArn": gatewayArnPattern },
+        },
+      }),
+    });
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "GatewayInvoke",
+        actions: ["bedrock-agentcore:InvokeGateway"],
+        resources: [gatewayArnPattern],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "WebSearchTool",
+        actions: ["bedrock-agentcore:InvokeWebSearch"],
+        // The managed tool is an AWS-owned resource, not one of ours. It is
+        // regional, so it follows the instance's region rather than naming one.
+        resources: [`arn:aws:bedrock-agentcore:${this.region}:aws:tool/web-search.v1`],
+      }),
+    );
+
+    const gateway = new cdk.CfnResource(this, "ToolGateway", {
+      type: "AWS::BedrockAgentCore::Gateway",
+      properties: {
+        Name: this.names.gatewayName,
+        Description: `${display} managed tool gateway (web search)`,
+        ProtocolType: "MCP",
+        AuthorizerType: "AWS_IAM",
+        RoleArn: role.roleArn,
+      },
+    });
+    gateway.node.addDependency(role);
+
+    const target = new cdk.CfnResource(this, "WebSearchTarget", {
+      type: "AWS::BedrockAgentCore::GatewayTarget",
+      properties: {
+        GatewayIdentifier: gateway.getAtt("GatewayIdentifier"),
+        Name: WEB_SEARCH_TARGET,
+        TargetConfiguration: {
+          Mcp: {
+            Connector: {
+              // The schema for ConnectorSource carries only ConnectorId, so
+              // the connector's current default version is what runs.
+              Source: { ConnectorId: "web-search" },
+              Configurations: [{ Name: "WebSearch", ParameterValues: {} }],
+            },
+          },
+        },
+        CredentialProviderConfigurations: [{ CredentialProviderType: "GATEWAY_IAM_ROLE" }],
+      },
+    });
+    target.node.addDependency(gateway);
+
+    return gateway;
+  }
+
+  private denyDirectCrmTableAccess(
+    role: iam.Role,
+    instance: Instance,
+    crmTable: dynamodb.ITable | undefined,
+  ): void {
+    if (!instance.integrations.crmStorage) return;
+    // CRM tables are RETAINed. Match every historical prefix so a supported
+    // prefix migration cannot make an older retained table readable.
+    const retainedTableArn = cdk.Stack.of(this).formatArn({
+      service: "dynamodb",
+      resource: "table",
+      resourceName: "*-CrmTable*",
+    });
+    const resources = [
+      retainedTableArn,
+      `${retainedTableArn}/index/*`,
+      ...(crmTable === undefined ? [] : [crmTable.tableArn, `${crmTable.tableArn}/index/*`]),
+    ];
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyDirectCrmTableAccess",
+        effect: iam.Effect.DENY,
+        actions: [
+          "dynamodb:GetItem",
+          "dynamodb:BatchGetItem",
+          "dynamodb:TransactGetItems",
+          "dynamodb:Query",
+          "dynamodb:Scan",
+          "dynamodb:PartiQLSelect",
+          "dynamodb:ExecuteStatement",
+          "dynamodb:BatchExecuteStatement",
+          "dynamodb:ExportTableToPointInTime",
+        ],
+        resources,
+      }),
+    );
+  }
+
+  /** Deny remains attached to both execution and assumed read-only roles. */
+  private denyDirectKnockSecretAccess(role: iam.Role, props: FoundationAgentProps): void {
+    if (!provisionsIntegration(props.instance, "knock")) return;
+    const { knockOauthClient, knockCredential } = props.secrets;
+    if (knockOauthClient === undefined || knockCredential === undefined)
+      throw new Error(
+        `${this.stackName}: integrations.knock is enabled but FoundationData supplied no Knock secrets`,
+      );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyKnockSecrets",
+        effect: iam.Effect.DENY,
+        actions: ["secretsmanager:GetSecretValue", "secretsmanager:BatchGetSecretValue"],
+        resources: [secretArnPattern(knockOauthClient), secretArnPattern(knockCredential)],
+      }),
+    );
+  }
+
+  private denyDirectUpworkApprovalAccess(
+    role: iam.Role,
+    upworkApprovalTable: dynamodb.ITable | undefined,
+  ): void {
+    if (upworkApprovalTable === undefined) return;
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyDirectUpworkApprovalAccess",
+        effect: iam.Effect.DENY,
+        // Cover reads today and any future managed-policy or inline write grant.
+        actions: ["dynamodb:*"],
+        resources: [upworkApprovalTable.tableArn, `${upworkApprovalTable.tableArn}/index/*`],
+      }),
+    );
+  }
+
+  /**
+   * `<Prefix>ReadOnlyRole` — how the agent reads its OWN account.
+   *
+   * The instance's account is not a special case: `aws-readonly` reaches
+   * every account through an assumed role, and this is the one for this one.
+   * That keeps the execution role itself narrow (it can write exactly the
+   * handful of resources it owns, and reads nothing else), and it makes every
+   * read the agent performs land in CloudTrail under a session named for the
+   * instance and the label rather than under the runtime's own identity.
+   *
+   * `ReadOnlyAccess` is AWS's own managed read-only policy. The inline
+   * additions are the two things it does NOT cover which the observability
+   * tools need: starting a Logs Insights query, and reading trace summaries.
+   */
+  private buildReadOnlyRole(props: FoundationAgentProps): iam.Role {
+    const role = new iam.Role(this, "AgentReadOnlyRole", {
+      roleName: `${props.instance.naming.prefix}ReadOnlyRole`,
+      description: `${props.instance.displayName} read-only role assumed by the agent (aws-readonly)`,
+      // Only this instance's own execution role may assume it. Nothing else
+      // in the account can, and it grants no write anywhere.
+      assumedBy: new iam.ArnPrincipal(this.executionRole.roleArn),
+      maxSessionDuration: cdk.Duration.hours(1),
+      managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")],
+    });
+    this.denyDirectCrmTableAccess(role, props.instance, props.crmTable);
+    this.denyDirectKnockSecretAccess(role, props);
+    this.denyDirectUpworkApprovalAccess(role, props.upworkApprovalTable);
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyAgentCoreBrowserMetadata",
+        effect: iam.Effect.DENY,
+        actions: ["bedrock-agentcore:*Browser*"],
+        resources: ["*"],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "LogsInsights",
+        // StartQuery is a WRITE action in IAM's taxonomy, so ReadOnlyAccess
+        // omits it — without this the log tools can only ever list groups.
+        actions: [
+          "logs:StartQuery",
+          "logs:StopQuery",
+          "logs:GetQueryResults",
+          "logs:FilterLogEvents",
+          "logs:DescribeLogGroups",
+          "logs:DescribeLogStreams",
+        ],
+        resources: ["*"],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "TraceRead",
+        actions: ["xray:GetTraceSummaries", "xray:BatchGetTraces"],
+        resources: ["*"],
+      }),
+    );
+    this.executionRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "AssumeReadOnlyRole",
+        actions: ["sts:AssumeRole"],
+        resources: [role.roleArn],
+      }),
+    );
+    return role;
+  }
+
+  private buildExecutionRole(props: FoundationAgentProps): iam.Role {
+    const role = new iam.Role(this, "AgentExecutionRole", {
+      assumedBy: new iam.ServicePrincipal("bedrock-agentcore.amazonaws.com"),
+      description: `${props.instance.displayName} AgentCore execution role (least privilege)`,
+    });
+    this.denyDirectCrmTableAccess(role, props.instance, props.crmTable);
+    this.denyDirectKnockSecretAccess(role, props);
+    this.denyDirectUpworkApprovalAccess(role, props.upworkApprovalTable);
+
+    // Foundation's own repository when a release names the image, because the
+    // runtime then pulls across accounts. The pull also needs Foundation's
+    // repository POLICY to allow this account (`release-account-stack.ts`);
+    // this side is the half the instance owns.
+    const releaseRepositoryArn = releaseImageRepositoryArn(this);
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "EcrPull",
+        actions: [
+          "ecr:BatchGetImage",
+          "ecr:GetDownloadUrlForLayer",
+          "ecr:BatchCheckLayerAvailability",
+        ],
+        resources: [
+          this.repository.repositoryArn,
+          ...(releaseRepositoryArn === undefined ? [] : [releaseRepositoryArn]),
+        ],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "EcrAuth",
+        // GetAuthorizationToken has no resource-level scoping.
+        actions: ["ecr:GetAuthorizationToken"],
+        resources: ["*"],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "AgentLogs",
+        actions: [
+          "logs:CreateLogGroup",
+          "logs:CreateLogStream",
+          "logs:PutLogEvents",
+          "logs:DescribeLogStreams",
+        ],
+        resources: [
+          `arn:${this.partition}:logs:${this.region}:${this.account}:log-group:/aws/bedrock-agentcore/runtimes/${this.names.runtimeName}-*`,
+        ],
+      }),
+    );
+    // Spans: the runtime SigV4-posts OTLP to the X-Ray endpoint, which routes
+    // them into the log group `AgentLogs` above already covers. None of these
+    // actions take a resource ARN — X-Ray scopes ingestion by account.
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "TraceIngest",
+        actions: [
+          "xray:PutTraceSegments",
+          "xray:PutTelemetryRecords",
+          "xray:PutSpans",
+          "xray:PutSpansForIndexing",
+        ],
+        resources: ["*"],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "AgentSecrets",
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [
+          secretArnPattern(props.secrets.runtime),
+          secretArnPattern(props.secrets.codex),
+          secretArnPattern(props.secrets.googleAiStudio),
+          secretArnPattern(props.secrets.googleDrive),
+          secretArnPattern(props.secrets.googleCalendar),
+          secretArnPattern(props.secrets.googleOauth),
+          secretArnPattern(props.secrets.githubApp),
+          secretArnPattern(props.secrets.slackApp),
+          secretArnPattern(props.secrets.mongodbReadonly),
+        ],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "CodexCredentialWriteback",
+        // SharedAuthCredentialStore writes the rotated Codex token back.
+        actions: ["secretsmanager:PutSecretValue"],
+        resources: [secretArnPattern(props.secrets.codex)],
+      }),
+    );
+    // The signing secret proves inbound Slack authenticity. If the agent
+    // could read it, a prompt injection could forge Slack events past
+    // verification. Removing the grant is what closes that today; an explicit
+    // Deny beats any future Allow, so it stays closed.
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenySlackSigningSecret",
+        effect: iam.Effect.DENY,
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [secretArnPattern(props.secrets.signing)],
+      }),
+    );
+    // Email is the sharpest version of the same argument as the signing
+    // secret, and the reason the proxy is a separate Lambda. The scope Google
+    // grants the mailbox (`gmail.compose`) permits SENDING, so a container
+    // that could read this secret could send mail as the company — and the
+    // model's shell can reach the execution role's credentials. Denying the
+    // read is what makes "the teammate cannot send" true rather than merely intended.
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyEmailSecret",
+        effect: iam.Effect.DENY,
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [secretArnPattern(props.secrets.googleEmail)],
+      }),
+    );
+    // The whole of the agent's email permission: invoke the proxy. Not the
+    // Gmail API, not the secret, not the identity list.
+    // Built from the NAME rather than from FoundationApi's function object: FoundationApi
+    // already depends on this stack for the runtime ARN, so referring to its
+    // output here would close a cycle. The function name is derived from the
+    // instance file, so both stacks compute the same string.
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "EmailProxyInvoke",
+        actions: ["lambda:InvokeFunction"],
+        resources: [
+          cdk.Stack.of(this).formatArn({
+            service: "lambda",
+            resource: "function",
+            resourceName: namesFor(props.instance).emailProxyFunctionName,
+            arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+          }),
+        ],
+      }),
+    );
+    // Defense in depth: the model shell shares this role. A future broad grant must not let it
+    // bypass the proxy's domain, operation, or user/profile checks through the Browser APIs.
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyDirectAgentCoreBrowser",
+        effect: iam.Effect.DENY,
+        actions: ["bedrock-agentcore:*Browser*"],
+        resources: ["*"],
+      }),
+    );
+    // AgentCore Browser follows the same isolation boundary: the agent can invoke this one
+    // policy-enforcing function, but it cannot start a browser session or connect to CDP itself.
+    // The deny above is unconditional; this ALLOW exists only where the instance file opted the
+    // browser capability's infrastructure in, so an instance without it names no function.
+    if (provisionsIntegration(props.instance, "browser")) {
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "BrowserProxyInvoke",
+          actions: ["lambda:InvokeFunction"],
+          resources: [
+            cdk.Stack.of(this).formatArn({
+              service: "lambda",
+              resource: "function",
+              resourceName: this.names.browserProxyFunctionName,
+              arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+            }),
+          ],
+        }),
+      );
+    }
+    if (provisionsIntegration(props.instance, "otter")) {
+      const otterApi = props.secrets.otterApi;
+      if (otterApi === undefined)
+        throw new Error(
+          `${this.stackName}: integrations.otter is enabled but FoundationData supplied no Otter secret`,
+        );
+      // Defense in depth: even a future broad Secrets Manager Allow cannot
+      // expose the API key to the shell-capable agent execution role.
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "DenyOtterSecret",
+          effect: iam.Effect.DENY,
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(otterApi)],
+        }),
+      );
+      // The entire Otter permission surface: invoke the fixed read-only
+      // proxy. The name is derived locally to avoid a FoundationAgent ↔ FoundationApi cycle.
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "OtterProxyInvoke",
+          actions: ["lambda:InvokeFunction"],
+          resources: [
+            cdk.Stack.of(this).formatArn({
+              service: "lambda",
+              resource: "function",
+              resourceName: this.names.otterProxyFunctionName,
+              arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+            }),
+          ],
+        }),
+      );
+    }
+    if (provisionsIntegration(props.instance, "knock")) {
+      // Knock's entire agent-facing surface is one proxy invocation. Neither
+      // the public client nor the connected OAuth credential reaches the shell.
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "KnockProxyInvoke",
+          actions: ["lambda:InvokeFunction"],
+          resources: [
+            cdk.Stack.of(this).formatArn({
+              service: "lambda",
+              resource: "function",
+              resourceName: this.names.knockProxyFunctionName,
+              arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+            }),
+          ],
+        }),
+      );
+    }
+    if (provisionsIntegration(props.instance, "upwork")) {
+      const upwork = props.secrets.upwork;
+      if (upwork === undefined)
+        throw new Error(
+          `${this.stackName}: integrations.upwork is enabled but FoundationData supplied no Upwork secret`,
+        );
+      // The full Upwork credential (including a refresh token) is never
+      // readable in the shell-capable runtime. The one Lambda invocation below
+      // is the entire agent-facing Upwork authority.
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "DenyUpworkSecret",
+          effect: iam.Effect.DENY,
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(upwork)],
+        }),
+      );
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "UpworkProxyInvoke",
+          actions: ["lambda:InvokeFunction"],
+          resources: [
+            cdk.Stack.of(this).formatArn({
+              service: "lambda",
+              resource: "function",
+              resourceName: this.names.upworkProxyFunctionName,
+              arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+            }),
+          ],
+        }),
+      );
+    }
+    if (provisionsIntegration(props.instance, "crm")) {
+      // The CRM permission surface is one named proxy Lambda. Derive the ARN
+      // locally so FoundationAgent never depends on FoundationApi's output and closes a
+      // stack cycle through the runtime ARN.
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "CrmProxyInvoke",
+          actions: ["lambda:InvokeFunction"],
+          resources: [
+            cdk.Stack.of(this).formatArn({
+              service: "lambda",
+              resource: "function",
+              resourceName: this.names.crmProxyFunctionName,
+              arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+            }),
+          ],
+        }),
+      );
+    }
+    // Config and curated skills are deployment-owned: direct S3 API writes are
+    // limited to memory/*. The separate fs/* persistent mount remains writable
+    // through S3 Files for workspace state and learned skills.
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ConfigAndSkills",
+        actions: ["s3:GetObject"],
+        resources: [props.bucket.arnForObjects("*")],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "MemoryWrite",
+        actions: ["s3:PutObject"],
+        resources: [props.bucket.arnForObjects("memory/*")],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ConfigList",
+        actions: ["s3:ListBucket"],
+        resources: [props.bucket.bucketArn],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DocumentsObjects",
+        actions: ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+        resources: [props.documentBucket.arnForObjects("*")],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DocumentsList",
+        actions: ["s3:ListBucket"],
+        resources: [props.documentBucket.bucketArn],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PersistentMount",
+        actions: ["s3files:ClientMount", "s3files:ClientWrite"],
+        resources: [
+          `arn:${this.partition}:s3files:${this.region}:${this.account}:file-system/${props.fileSystemId}`,
+        ],
+        // The file system carries exactly one access point today; the
+        // condition keeps that true from the role's side, so a second one
+        // added later is not silently mountable by the agent.
+        conditions: { ArnEquals: { "s3files:AccessPointArn": this.accessPointArn } },
+      }),
+    );
+    // AgentCore validates the access point at runtime create/update time and
+    // checks GetAccessPoint against the ACCESS POINT ARN itself (2026-09-05:
+    // "Execution role is missing required permissions. Ensure the role has
+    // s3files:GetAccessPoint" when it was granted only on the file system).
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PersistentMountDescribe",
+        // Read-only describe set: the validator also asks for ListMountTargets
+        // (and may add more); none of these grant data access.
+        actions: ["s3files:Get*", "s3files:List*", "s3files:Describe*"],
+        resources: [
+          this.accessPointArn,
+          `arn:${this.partition}:s3files:${this.region}:${this.account}:file-system/${props.fileSystemId}`,
+        ],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "StateTable",
+        // DeleteItem releases the Codex credential lease.
+        actions: [
+          "dynamodb:GetItem",
+          "dynamodb:PutItem",
+          "dynamodb:UpdateItem",
+          "dynamodb:DeleteItem",
+          "dynamodb:Query",
+        ],
+        resources: [props.table.tableArn],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ItemsTable",
+        actions: [
+          "dynamodb:GetItem",
+          "dynamodb:PutItem",
+          "dynamodb:UpdateItem",
+          "dynamodb:DeleteItem",
+          "dynamodb:Query",
+        ],
+        resources: [props.itemsTable.tableArn],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DataKeyUsage",
+        actions: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
+        resources: [props.dataKey.keyArn],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "RoutineSchedules",
+        actions: [
+          "scheduler:CreateSchedule",
+          "scheduler:UpdateSchedule",
+          "scheduler:DeleteSchedule",
+          "scheduler:GetSchedule",
+        ],
+        // Only inside the instance's own group: the agent cannot touch a schedule it
+        // did not create, and cannot create the group either.
+        resources: [
+          `arn:${this.partition}:scheduler:${this.region}:${this.account}:schedule/${this.names.routineGroup}/*`,
+        ],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PassRoutineSchedulerRole",
+        actions: ["iam:PassRole"],
+        resources: [
+          `arn:${this.partition}:iam::${this.account}:role/${this.names.routineSchedulerRole}`,
+        ],
+        // Passing it anywhere but Scheduler would be privilege escalation.
+        conditions: { StringEquals: { "iam:PassedToService": "scheduler.amazonaws.com" } },
+      }),
+    );
+    if (requiresAuthenticatedQueue(props.instance)) {
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "RoutineIngressInvoke",
+          actions: ["lambda:InvokeFunction"],
+          resources: [
+            cdk.Stack.of(this).formatArn({
+              service: "lambda",
+              resource: "function",
+              resourceName: this.names.slackGatewayFunctionName,
+              arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+            }),
+          ],
+        }),
+      );
+    } else {
+      role.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "InvokeQueueSend",
+          // Legacy instances still let a fired `turn` routine re-enqueue.
+          actions: ["sqs:SendMessage"],
+          resources: [
+            `arn:${this.partition}:sqs:${this.region}:${this.account}:${this.names.api}-InvokeQueue*`,
+          ],
+        }),
+      );
+    }
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "SessionEni",
+        // VPC-mode session ENIs; these actions do not support scoping.
+        actions: [
+          "ec2:CreateNetworkInterface",
+          "ec2:DescribeNetworkInterfaces",
+          "ec2:DeleteNetworkInterface",
+          "ec2:DescribeSubnets",
+          "ec2:DescribeSecurityGroups",
+          "ec2:DescribeVpcs",
+        ],
+        resources: ["*"],
+      }),
+    );
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "WorkloadIdentity",
+        actions: [
+          "bedrock-agentcore:GetWorkloadAccessToken",
+          "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
+          "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
+        ],
+        resources: [
+          `arn:${this.partition}:bedrock-agentcore:${this.region}:${this.account}:workload-identity-directory/default*`,
+        ],
+      }),
+    );
+
+    return role;
+  }
+}
+
+/**
+ * Secrets imported by name carry a partial ARN (no service-generated
+ * 6-character suffix), which IAM will not match — append the wildcard the
+ * same way CDK's own `grantRead` does.
+ */
+function secretArnPattern(secret: secretsmanager.ISecret): string {
+  return secret.secretFullArn ?? `${secret.secretArn}-??????`;
+}