@deployfoundation/foundation-deploy 0.1.0

package/src/stacks/api-stack.ts

@@ -0,0 +1,1005 @@
+import { readFileSync } from "node:fs";
+import { crmPolicyFingerprint, parseInstanceConfig } from "@deployfoundation/foundation-core";
+import { slackCommandPrefixes } from "@deployfoundation/foundation-core/instance";
+import * as cdk from "aws-cdk-lib";
+import * as apigateway from "aws-cdk-lib/aws-apigateway";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import * as cwActions from "aws-cdk-lib/aws-cloudwatch-actions";
+import type * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type * as kms from "aws-cdk-lib/aws-kms";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as lambdaEventSources from "aws-cdk-lib/aws-lambda-event-sources";
+import * as scheduler from "aws-cdk-lib/aws-scheduler";
+import type * as secretsmanager from "aws-cdk-lib/aws-secretsmanager";
+import * as sns from "aws-cdk-lib/aws-sns";
+import * as sqs from "aws-cdk-lib/aws-sqs";
+import type { Construct } from "constructs";
+import { parse as parseYaml } from "yaml";
+import { lambdaCode } from "../artifacts.ts";
+import {
+  type Instance,
+  LIVE_ENDPOINT_NAME,
+  namesFor,
+  provisionsIntegration,
+  requiresAuthenticatedQueue,
+} from "../names.ts";
+
+export interface FoundationApiProps extends cdk.StackProps {
+  /** The deployment this stack belongs to; every name below comes from it. */
+  instance: Instance;
+  /**
+   * The instance's runtime config. Several proxies bake policy from it at
+   * synth — the identities email may draft as, the domains the browser may
+   * visit, CRM's channels and statuses — so a config sync alone can never
+   * widen a deployed proxy.
+   */
+  configPath: string;
+  dataKey: kms.IKey;
+  table: dynamodb.ITable;
+  /** `pk` + `sk`: where the Google Calendar callback stores per-person tokens. */
+  itemsTable: dynamodb.ITable;
+  /** Dedicated CRM table, present only when the instance enables the integration. */
+  crmTable?: dynamodb.ITable;
+  /** Proxy-only one-hour proposal drafts; never granted to the agent runtime. */
+  upworkApprovalTable?: dynamodb.ITable;
+  secrets: {
+    signing: secretsmanager.ISecret;
+    slackApp: secretsmanager.ISecret;
+    googleCalendar: secretsmanager.ISecret;
+    /** The shared OAuth client; the gateway reads it to build a consent link. */
+    googleOauth: secretsmanager.ISecret;
+    /** The Drive identity. The gateway WRITES this one and never reads it. */
+    googleDrive: secretsmanager.ISecret;
+    /** The connected mailbox. The gateway WRITES it; only the proxy reads it. */
+    googleEmail: secretsmanager.ISecret;
+    /** Otter API key. Only the optional Otter proxy role can read it. */
+    otterApi?: secretsmanager.ISecret;
+    /** Knock's public OAuth client. Gateway reads it; deployment owns registration. */
+    knockOauthClient?: secretsmanager.ISecret;
+    /** Connected Knock credential. Gateway writes; proxy alone reads or refreshes. */
+    knockCredential?: secretsmanager.ISecret;
+    /** Combined Upwork OAuth client and token secret, present only for opted-in instances. */
+    upwork?: secretsmanager.ISecret;
+  };
+  /**
+   * The AgentCore runtime the invoker calls. On a phase-one deploy this is
+   * FoundationAgent's `…-pending` placeholder — a syntactically valid ARN that
+   * nothing can invoke, so the plumbing synthesizes before the image exists.
+   */
+  agentRuntimeArn: string;
+  /** CSV of Slack user ids allowed to run privileged commands. */
+  admins: string;
+  /** Optional address subscribed to the DLQ alarm topic. */
+  alarmEmail?: string;
+}
+
+/**
+ * FoundationApi — the edge: API Gateway → gateway Lambda → SQS → invoker
+ * Lambda → `InvokeAgentRuntime`. The gateway must answer Slack inside 3
+ * seconds, so it only verifies, dedupes and enqueues; the invoker holds the
+ * blocking agent turn for up to Lambda's 15 minutes (which is also
+ * AgentCore's per-invoke ceiling).
+ *
+ * Neither Lambda is VPC-attached. Everything they call — Secrets Manager,
+ * SQS, DynamoDB, AgentCore — is a public AWS endpoint, so the VPC would buy
+ * nothing but ENI cold-start latency on the 3-second path.
+ *
+ * `maxReceiveCount: 1` on the invoke queue: chat prefers dropping a turn over
+ * duplicating it. A failed invoke rolls straight to the DLQ for manual
+ * redrive, and the DLQ alarm below is what says so.
+ */
+export class FoundationApi extends cdk.Stack {
+  public readonly api: apigateway.RestApi;
+  public readonly gatewayDlq: sqs.Queue;
+  public readonly invokeQueue: sqs.Queue;
+  public readonly invokeDlq: sqs.Queue;
+  /** The email proxy: the agent role's only email grant is to invoke this. */
+  public readonly emailProxyFunction: lambda.Function;
+  /** Isolated policy boundary for AgentCore Browser; absent when the capability is disabled. */
+  public readonly browserProxyFunction?: lambda.Function;
+  /** Read-only Otter proxy, present only when the instance opts in. */
+  public readonly otterProxyFunction?: lambda.Function;
+  /** CRM proxy, present only when the instance opts into its CRM integration. */
+  public readonly crmProxyFunction?: lambda.Function;
+  /** Read-only Knock remote-MCP proxy, present only for opted-in instances. */
+  public readonly knockProxyFunction?: lambda.Function;
+  /** Fixed-operation Upwork proxy, present only when the instance opts in. */
+  public readonly upworkProxyFunction?: lambda.Function;
+
+  constructor(scope: Construct, id: string, props: FoundationApiProps) {
+    super(scope, id, props);
+    const names = namesFor(props.instance);
+    const display = props.instance.displayName;
+    const upwork = provisionsIntegration(props.instance, "upwork")
+      ? upworkConfigForProvisioning(props.configPath)
+      : undefined;
+    const upworkSecret = upwork === undefined ? undefined : props.secrets.upwork;
+    const upworkApprovalTable = upwork === undefined ? undefined : props.upworkApprovalTable;
+    if (upwork !== undefined && (upworkSecret === undefined || upworkApprovalTable === undefined))
+      throw new Error(
+        `${id}: integrations.upwork is enabled but its secret or approval table was not supplied by FoundationData`,
+      );
+    const authenticatedQueue = requiresAuthenticatedQueue(props.instance);
+
+    this.gatewayDlq = new sqs.Queue(this, "GatewayDlq", {
+      encryption: sqs.QueueEncryption.KMS,
+      encryptionMasterKey: props.dataKey,
+      enforceSSL: true,
+      retentionPeriod: cdk.Duration.days(14),
+    });
+
+    this.invokeDlq = new sqs.Queue(this, "InvokeDlq", {
+      encryption: sqs.QueueEncryption.KMS,
+      encryptionMasterKey: props.dataKey,
+      enforceSSL: true,
+      retentionPeriod: cdk.Duration.days(14),
+    });
+
+    this.invokeQueue = new sqs.Queue(this, "InvokeQueue", {
+      encryption: sqs.QueueEncryption.KMS,
+      encryptionMasterKey: props.dataKey,
+      enforceSSL: true,
+      // Matches the invoker's 15-minute timeout: Lambda extends visibility
+      // while the turn runs, and a dead invoker's message surfaces once and
+      // then rolls to the DLQ.
+      visibilityTimeout: cdk.Duration.seconds(900),
+      retentionPeriod: cdk.Duration.hours(6),
+      deadLetterQueue: { queue: this.invokeDlq, maxReceiveCount: 1 },
+    });
+
+    const gatewayRole = new iam.Role(this, "GatewayRole", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: `${display} gateway Lambda role (least privilege)`,
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+      ],
+    });
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "GatewayCredentials",
+        actions: ["secretsmanager:GetSecretValue"],
+        // Slack request verification, plus the Google OAuth *client* used to
+        // build a consent link and redeem a code. No refresh token is ever
+        // read from a secret: they are per-person rows in `FoundationItems`.
+        resources: [
+          secretArnPattern(props.secrets.signing),
+          secretArnPattern(props.secrets.slackApp),
+          secretArnPattern(props.secrets.googleCalendar),
+          secretArnPattern(props.secrets.googleOauth),
+          ...(props.secrets.knockOauthClient === undefined
+            ? []
+            : [secretArnPattern(props.secrets.knockOauthClient)]),
+        ],
+      }),
+    );
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DriveIdentityConnect",
+        // `/sky-drive-connect` stores the connected account's refresh token.
+        // Write-only and on this one secret: the gateway must be unable to
+        // read back the Drive credential it just wrote, which is what keeps
+        // Drive reads exclusive to the agent runtime.
+        actions: ["secretsmanager:PutSecretValue"],
+        resources: [secretArnPattern(props.secrets.googleDrive)],
+      }),
+    );
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "EmailIdentityConnect",
+        // The same shape, and here it matters more: the mailbox credential is
+        // the one thing in the system that could SEND mail. A read grant would
+        // put it one injection away from an internet-facing Lambda.
+        actions: ["secretsmanager:PutSecretValue"],
+        resources: [secretArnPattern(props.secrets.googleEmail)],
+      }),
+    );
+    if (props.secrets.knockCredential !== undefined) {
+      gatewayRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "KnockCredentialConnect",
+          // The callback writes a newly connected token but never reads it;
+          // the fixed proxy owns every subsequent read and refresh.
+          actions: ["secretsmanager:PutSecretValue"],
+          resources: [secretArnPattern(props.secrets.knockCredential)],
+        }),
+      );
+    }
+    if (upworkSecret !== undefined) {
+      gatewayRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "UpworkOAuth",
+          // The callback exchanges a code and conditionally promotes refreshed
+          // token state alongside the manually entered client credentials.
+          actions: [
+            "secretsmanager:GetSecretValue",
+            "secretsmanager:PutSecretValue",
+            "secretsmanager:UpdateSecretVersionStage",
+          ],
+          resources: [secretArnPattern(upworkSecret)],
+        }),
+      );
+    }
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DedupeAndThreadIndex",
+        // UpdateItem is the proactive channels' hourly budget counter: one row
+        // per channel per hour, incremented under a condition so two Lambdas
+        // cannot both spend the last start of the hour.
+        actions: ["dynamodb:PutItem", "dynamodb:GetItem", "dynamodb:UpdateItem"],
+        resources: [props.table.tableArn],
+      }),
+    );
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "CalendarConnections",
+        // Write-only, and only on the OAuth callback: the gateway stores a
+        // person's refresh token but never reads one back.
+        actions: ["dynamodb:PutItem"],
+        resources: [props.itemsTable.tableArn],
+      }),
+    );
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "QueueSend",
+        actions: ["sqs:SendMessage"],
+        // The gateway DLQ is granted separately by `deadLetterQueue` below.
+        resources: [this.invokeQueue.queueArn],
+      }),
+    );
+    gatewayRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DataKeyUsage",
+        actions: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
+        resources: [props.dataKey.keyArn],
+      }),
+    );
+
+    const gatewayFunction = new lambda.Function(this, "GatewayFunction", {
+      ...(authenticatedQueue ? { functionName: names.slackGatewayFunctionName } : {}),
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambdaCode(this, "gateway"),
+      role: gatewayRole,
+      timeout: cdk.Duration.seconds(10),
+      memorySize: 256,
+      deadLetterQueue: this.gatewayDlq,
+      environment: {
+        FOUNDATION_TABLE_NAME: props.table.tableName,
+        FOUNDATION_INVOKE_QUEUE_URL: this.invokeQueue.queueUrl,
+        FOUNDATION_GATEWAY_DLQ_URL: this.gatewayDlq.queueUrl,
+        FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+        FOUNDATION_SLACK_APP_SECRET_ID: props.secrets.slackApp.secretName,
+        FOUNDATION_ADMINS: props.admins,
+        FOUNDATION_AGENT_RUNTIME_ARN: props.agentRuntimeArn,
+        // What the teammate is called. The gateway renders it in `/help`, in
+        // every "not configured" reply and in each OAuth result page, and
+        // `triggers.ts` uses it to tell a message addressed to the teammate
+        // from one addressed to a person. Without it the gateway falls back
+        // to a hard-coded name, wrong for every instance but one.
+        FOUNDATION_DISPLAY_NAME: props.instance.displayName,
+        FOUNDATION_ITEMS_TABLE_NAME: props.itemsTable.tableName,
+        FOUNDATION_GOOGLE_CALENDAR_SECRET_ID: props.secrets.googleCalendar.secretName,
+        FOUNDATION_GOOGLE_OAUTH_SECRET_ID: props.secrets.googleOauth.secretName,
+        FOUNDATION_GOOGLE_DRIVE_SECRET_ID: props.secrets.googleDrive.secretName,
+        FOUNDATION_GOOGLE_EMAIL_SECRET_ID: props.secrets.googleEmail.secretName,
+        ...(props.secrets.knockOauthClient === undefined
+          ? {}
+          : { FOUNDATION_KNOCK_OAUTH_CLIENT_SECRET_ID: props.secrets.knockOauthClient.secretName }),
+        ...(props.secrets.knockCredential === undefined
+          ? {}
+          : { FOUNDATION_KNOCK_CREDENTIAL_SECRET_ID: props.secrets.knockCredential.secretName }),
+        ...(upworkSecret === undefined
+          ? {}
+          : { FOUNDATION_UPWORK_SECRET_ID: upworkSecret.secretName }),
+        // Signed into every Drive and email consent link, so one instance's
+        // link cannot be redeemed against another's gateway.
+        FOUNDATION_INSTANCE: props.instance.name,
+        // Slash-command prefixes the gateway answers (current first, then legacy),
+        // from the instance file; the manifest renders the same prefix.
+        FOUNDATION_COMMAND_PREFIXES: slackCommandPrefixes(props.instance).join(","),
+        // Read at SYNTH from the instance file, like FOUNDATION_ADMINS: the gateway
+        // decides what starts a turn and never reads `config/<name>.yaml`, so
+        // making the teammate speak unasked in a channel is a deploy, not a config sync.
+        // Empty for an instance that watches nothing, which is every instance
+        // that omits the block.
+        FOUNDATION_PROACTIVE_CHANNELS: props.instance.proactive.channels.join(","),
+        FOUNDATION_PROACTIVE_MAX_PER_HOUR: String(props.instance.proactive.maxPerHour),
+      },
+    });
+    // One mention must produce one reply: Lambda's default of two async
+    // retries would re-run a slow turn into duplicate Slack messages.
+    gatewayFunction.configureAsyncInvoke({
+      retryAttempts: 0,
+      maxEventAge: cdk.Duration.seconds(60),
+    });
+
+    const invokerRole = new iam.Role(this, "InvokerRole", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: `${display} invoker Lambda role (least privilege)`,
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+      ],
+    });
+    invokerRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "InvokeAgentRuntime",
+        actions: ["bedrock-agentcore:InvokeAgentRuntime"],
+        // Name prefix, not the literal ARN: on a phase-one deploy the runtime
+        // does not exist yet, and the placeholder ARN this stack is handed
+        // would otherwise bake a dead resource into the policy.
+        resources: [
+          `arn:${this.partition}:bedrock-agentcore:${this.region}:${this.account}:runtime/${names.runtimeName}*`,
+          `arn:${this.partition}:bedrock-agentcore:${this.region}:${this.account}:runtime/${names.runtimeName}*/runtime-endpoint/*`,
+        ],
+      }),
+    );
+    invokerRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "SlackBotToken",
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [secretArnPattern(props.secrets.slackApp)],
+      }),
+    );
+    if (authenticatedQueue) {
+      // Hardened queue envelopes are HMAC-authenticated before AgentCore.
+      // This trusted invoker can verify Slack's signing secret; the agent role
+      // remains explicitly denied and cannot forge a normal turn.
+      invokerRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "QueueEnvelopeVerification",
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(props.secrets.signing)],
+        }),
+      );
+    } else {
+      // Legacy instances do not yet require authenticated queue envelopes.
+      invokerRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "DenySlackSigningSecret",
+          effect: iam.Effect.DENY,
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [
+            `arn:${this.partition}:secretsmanager:${this.region}:${this.account}:secret:${names.secretSlackSigning}-??????`,
+          ],
+        }),
+      );
+    }
+    invokerRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DataKeyUsage",
+        actions: ["kms:Decrypt", "kms:GenerateDataKey"],
+        resources: [props.dataKey.keyArn],
+      }),
+    );
+
+    const invokerFunction = new lambda.Function(this, "InvokerFunction", {
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambdaCode(this, "invoker"),
+      role: invokerRole,
+      timeout: cdk.Duration.seconds(900),
+      memorySize: 512,
+      environment: {
+        FOUNDATION_SLACK_APP_SECRET_ID: props.secrets.slackApp.secretName,
+        FOUNDATION_AWS_REGION: this.region,
+        // Production traffic hits the pinned `live` endpoint, promoted by the
+        // deploy workflow after the smoke test — never DEFAULT (newest version).
+        FOUNDATION_AGENT_RUNTIME_QUALIFIER: LIVE_ENDPOINT_NAME,
+        ...(authenticatedQueue
+          ? { FOUNDATION_QUEUE_SIGNING_SECRET_ID: props.secrets.signing.secretName }
+          : {}),
+      },
+    });
+    invokerFunction.addEventSource(
+      new lambdaEventSources.SqsEventSource(this.invokeQueue, {
+        batchSize: 1,
+        // One message per invocation, so partial-batch reporting has nothing
+        // to report: a failed record must fail the whole invocation and roll
+        // to the DLQ (maxReceiveCount 1) rather than be retried.
+        reportBatchItemFailures: false,
+      }),
+    );
+
+    // AuthorizationType NONE by design: Slack cannot sign AWS IAM requests.
+    // Authentication is the Slack v2 signature the gateway Lambda verifies.
+    this.api = new apigateway.RestApi(this, "FoundationApi", {
+      restApiName: `${props.instance.naming.secretPrefix}-events`,
+      description: `${display} Slack ingress (events + slash commands + interactivity)`,
+      endpointTypes: [apigateway.EndpointType.REGIONAL],
+      deployOptions: {
+        stageName: "prod",
+        throttlingRateLimit: 50,
+        throttlingBurstLimit: 100,
+        metricsEnabled: true,
+      },
+      cloudWatchRole: false,
+    });
+    const slack = this.api.root.addResource("slack");
+    const integration = new apigateway.LambdaIntegration(gatewayFunction);
+    slack.addResource("events").addMethod("POST", integration);
+    slack.addResource("commands").addMethod("POST", integration);
+    // Block Kit answers to `ask_user` questions (Slack "Interactivity").
+    slack.addResource("interactive").addMethod("POST", integration);
+    // Google's OAuth redirect. Not a Slack route and not Slack-signed: it
+    // authenticates the person through the signed `state` the gateway issued.
+    this.api.root
+      .addResource("calendar")
+      .addResource("oauth")
+      .addResource("callback")
+      .addMethod("GET", integration);
+    // The same for the company Drive identity an admin connects.
+    this.api.root
+      .addResource("drive")
+      .addResource("oauth")
+      .addResource("callback")
+      .addMethod("GET", integration);
+    // And for the mailbox. The gateway derives this callback's URL from the
+    // shared client's `redirect_uri` (`redirectUriFor`), so nothing here has
+    // to tell it — which also avoids depending on the deployment stage from
+    // the very function the stage depends on.
+    this.api.root
+      .addResource("email")
+      .addResource("oauth")
+      .addResource("callback")
+      .addMethod("GET", integration);
+    if (provisionsIntegration(props.instance, "knock")) {
+      // Knock redirects only for deployments that opted its infrastructure in,
+      // which is what creates both its public client and the write-only
+      // callback credential destination.
+      this.api.root
+        .addResource("knock")
+        .addResource("oauth")
+        .addResource("callback")
+        .addMethod("GET", integration);
+    }
+    if (upworkSecret !== undefined && upwork !== undefined) {
+      const upworkRedirectUri = this.api.urlForPath("/upwork/oauth/callback");
+      this.api.root
+        .addResource("upwork")
+        .addResource("oauth")
+        .addResource("callback")
+        .addMethod("GET", integration);
+      new cdk.CfnOutput(this, "UpworkOAuthRedirectUrl", { value: upworkRedirectUri });
+    }
+
+    // --- email proxy -----------------------------------------------------
+    // The permission barrier for Gmail, and the reason the design puts it in
+    // a Lambda rather than a broker inside the agent container: this role is
+    // the ONLY principal in the account that can read the mailbox secret, and
+    // the agent's execution role carries an explicit Deny on it. A fully
+    // hijacked session can invoke the four operations and nothing more.
+    const emailProxyRole = new iam.Role(this, "EmailProxyRole", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: `${display} email proxy Lambda role (the only reader of the mailbox secret)`,
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+      ],
+    });
+    emailProxyRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "EmailProxyCredentials",
+        actions: ["secretsmanager:GetSecretValue"],
+        // Exactly two: the mailbox, and the OAuth client its token is minted
+        // with. Nothing else in the account is readable by this role.
+        resources: [
+          secretArnPattern(props.secrets.googleEmail),
+          secretArnPattern(props.secrets.googleOauth),
+        ],
+      }),
+    );
+    emailProxyRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "EmailProxyDataKey",
+        actions: ["kms:Decrypt"],
+        resources: [props.dataKey.keyArn],
+      }),
+    );
+
+    this.emailProxyFunction = new lambda.Function(this, "EmailProxyFunction", {
+      functionName: namesFor(props.instance).emailProxyFunctionName,
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambdaCode(this, "email-proxy"),
+      role: emailProxyRole,
+      timeout: cdk.Duration.seconds(30),
+      memorySize: 256,
+      // No reserved concurrency: a fresh account's Lambda quota is 10 and
+      // reserving any of it is refused ("decreases UnreservedConcurrentExecution
+      // below its minimum", 2026-09-06). Gmail-side rate is bounded
+      // by the hourly routine and one turn per channel at a time instead.
+      environment: {
+        FOUNDATION_GOOGLE_EMAIL_SECRET_ID: props.secrets.googleEmail.secretName,
+        FOUNDATION_GOOGLE_OAUTH_SECRET_ID: props.secrets.googleOauth.secretName,
+        // Read at SYNTH from the instance's config file. The identity list a
+        // turn can draft as is therefore fixed at deploy time and cannot be
+        // widened by anything the agent sends or by a config sync alone.
+        FOUNDATION_EMAIL_IDENTITIES: JSON.stringify(emailIdentitiesFor(props.configPath)),
+      },
+    });
+
+    // --- AgentCore Browser proxy ----------------------------------------
+    // The model-facing runtime can invoke this Lambda but has no Browser API grants. The proxy
+    // owns those grants and re-validates a gateway-signed DM/user scope plus this deploy-time
+    // domain policy before every read operation.
+    const browserDomains = provisionsIntegration(props.instance, "browser")
+      ? browserDomainsFor(props.configPath)
+      : [];
+    if (browserDomains.length > 0) {
+      const browserProxyRole = new iam.Role(this, "BrowserProxyRole", {
+        assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+        description: `${display} policy-enforcing AgentCore Browser proxy role`,
+        managedPolicies: [
+          iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+        ],
+      });
+      browserProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "BrowserProxySigningSecret",
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(props.secrets.signing)],
+        }),
+      );
+      browserProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "BrowserProxyDataKey",
+          actions: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
+          resources: [props.dataKey.keyArn],
+        }),
+      );
+      browserProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "BrowserProxySessions",
+          actions: [
+            "bedrock-agentcore:StartBrowserSession",
+            "bedrock-agentcore:StopBrowserSession",
+            "bedrock-agentcore:SaveBrowserSessionProfile",
+            "bedrock-agentcore:ConnectBrowserAutomationStream",
+          ],
+          resources: [
+            `arn:${this.partition}:bedrock-agentcore:${this.region}:aws:browser/aws.browser.v1`,
+            `arn:${this.partition}:bedrock-agentcore:${this.region}:${this.account}:browser-profile/*`,
+          ],
+        }),
+      );
+      browserProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "BrowserProxyProfiles",
+          actions: [
+            "bedrock-agentcore:CreateBrowserProfile",
+            "bedrock-agentcore:GetBrowserProfile",
+            "bedrock-agentcore:ListBrowserProfiles",
+          ],
+          // Create/List have no resource ARN. The proxy derives opaque profile names from the
+          // verified Slack user and a server-side allowlisted domain and exposes no delete API.
+          resources: ["*"],
+        }),
+      );
+      browserProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "BrowserProxyLease",
+          actions: ["dynamodb:PutItem", "dynamodb:DeleteItem"],
+          resources: [props.itemsTable.tableArn],
+        }),
+      );
+      this.browserProxyFunction = new lambda.Function(this, "BrowserProxyFunction", {
+        functionName: names.browserProxyFunctionName,
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: "index.handler",
+        role: browserProxyRole,
+        timeout: cdk.Duration.seconds(240),
+        code: lambdaCode(this, "browser-proxy"),
+        environment: {
+          FOUNDATION_BROWSER_ALLOWED_DOMAINS: JSON.stringify(browserDomains),
+          FOUNDATION_INSTANCE: props.instance.name,
+          FOUNDATION_ITEMS_TABLE_NAME: props.itemsTable.tableName,
+          FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+          FOUNDATION_TEAM_ID: props.instance.slack.teamId,
+        },
+      });
+    }
+
+    // --- Otter proxy -----------------------------------------------------
+    // Like email, this is a hard credential boundary: the shell-capable
+    // agent can invoke two fixed GET operations but cannot read the API key.
+    if (provisionsIntegration(props.instance, "otter")) {
+      const otterApi = props.secrets.otterApi;
+      if (otterApi === undefined)
+        throw new Error(
+          `${id}: integrations.otter is enabled but FoundationData supplied no Otter secret`,
+        );
+      const otterProxyRole = new iam.Role(this, "OtterProxyRole", {
+        assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+        description: `${display} Otter proxy Lambda role (the only reader of the API key)`,
+        managedPolicies: [
+          iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+        ],
+      });
+      otterProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "OtterProxyCredentials",
+          actions: ["secretsmanager:GetSecretValue"],
+          // Otter key for the API call; Slack signing secret to verify the
+          // actor capability the gateway minted and the agent cannot forge.
+          resources: [secretArnPattern(otterApi), secretArnPattern(props.secrets.signing)],
+        }),
+      );
+      this.otterProxyFunction = new lambda.Function(this, "OtterProxyFunction", {
+        functionName: names.otterProxyFunctionName,
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: "index.handler",
+        code: lambdaCode(this, "otter-proxy"),
+        role: otterProxyRole,
+        timeout: cdk.Duration.seconds(30),
+        memorySize: 256,
+        environment: {
+          FOUNDATION_OTTER_API_SECRET_ID: otterApi.secretName,
+          FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+          FOUNDATION_SLACK_TEAM_ID: props.instance.slack.teamId,
+          FOUNDATION_ADMINS: props.admins,
+        },
+      });
+      new cdk.CfnOutput(this, "OtterProxyFunctionArn", {
+        value: this.otterProxyFunction.functionArn,
+      });
+    }
+
+    // --- Knock proxy -----------------------------------------------------
+    // The proxy is the only runtime role that can read or refresh the tenant
+    // credential. The gateway has write-only callback access; the agent can
+    // invoke this Lambda and is explicitly denied both Knock secrets.
+    if (provisionsIntegration(props.instance, "knock")) {
+      const knockCredential = props.secrets.knockCredential;
+      if (knockCredential === undefined)
+        throw new Error(
+          `${id}: integrations.knock is enabled but FoundationData supplied no Knock secret`,
+        );
+      const knock = knockConfigForProvisioning(props.configPath);
+      const knockProxyRole = new iam.Role(this, "KnockProxyRole", {
+        assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+        description: `${display} Knock read-only MCP proxy Lambda`,
+        managedPolicies: [
+          iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+        ],
+      });
+      knockProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "KnockProxyCredentialRead",
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(knockCredential), secretArnPattern(props.secrets.signing)],
+        }),
+      );
+      knockProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "KnockProxyCredentialRefresh",
+          actions: ["secretsmanager:PutSecretValue", "secretsmanager:UpdateSecretVersionStage"],
+          resources: [secretArnPattern(knockCredential)],
+        }),
+      );
+      this.knockProxyFunction = new lambda.Function(this, "KnockProxyFunction", {
+        functionName: names.knockProxyFunctionName,
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: "index.handler",
+        code: lambdaCode(this, "knock-proxy"),
+        role: knockProxyRole,
+        timeout: cdk.Duration.seconds(30),
+        memorySize: 256,
+        environment: {
+          FOUNDATION_KNOCK_CREDENTIAL_SECRET_ID: knockCredential.secretName,
+          FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+          FOUNDATION_SLACK_TEAM_ID: props.instance.slack.teamId,
+          FOUNDATION_ADMINS: props.admins,
+          FOUNDATION_KNOCK_DEBUG: String(knock.debug),
+        },
+      });
+      new cdk.CfnOutput(this, "KnockProxyFunctionArn", {
+        value: this.knockProxyFunction.functionArn,
+      });
+    }
+
+    // --- Upwork proxy ----------------------------------------------------
+    // The shell-capable agent receives only this Lambda ARN. OAuth client and
+    // token state remain in one retained secret that this role alone can read
+    // or update; every request also carries a gateway-signed actor envelope.
+    if (upworkSecret !== undefined && upwork !== undefined && upworkApprovalTable !== undefined) {
+      const upworkProxyRole = new iam.Role(this, "UpworkProxyRole", {
+        assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+        description: `${display} Upwork proxy Lambda role (fixed OAuth and proposal operations)`,
+        managedPolicies: [
+          iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+        ],
+      });
+      upworkProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "UpworkProxySecret",
+          actions: [
+            "secretsmanager:GetSecretValue",
+            "secretsmanager:PutSecretValue",
+            "secretsmanager:UpdateSecretVersionStage",
+          ],
+          resources: [secretArnPattern(upworkSecret)],
+        }),
+      );
+      upworkProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "UpworkProxySigningSecret",
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(props.secrets.signing)],
+        }),
+      );
+      upworkProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "UpworkDraftState",
+          actions: ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:DeleteItem"],
+          resources: [upworkApprovalTable.tableArn],
+        }),
+      );
+      this.upworkProxyFunction = new lambda.Function(this, "UpworkProxyFunction", {
+        functionName: names.upworkProxyFunctionName,
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: "index.handler",
+        code: lambdaCode(this, "upwork-proxy"),
+        role: upworkProxyRole,
+        timeout: cdk.Duration.seconds(30),
+        memorySize: 256,
+        environment: {
+          FOUNDATION_UPWORK_SECRET_ID: upworkSecret.secretName,
+          FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+          FOUNDATION_TABLE_NAME: upworkApprovalTable.tableName,
+          FOUNDATION_SLACK_TEAM_ID: props.instance.slack.teamId,
+          FOUNDATION_UPWORK_ALLOWED_CHANNELS: JSON.stringify(upwork.channels),
+          FOUNDATION_ADMINS: props.admins,
+          FOUNDATION_INSTANCE: props.instance.name,
+        },
+      });
+      new cdk.CfnOutput(this, "UpworkProxyFunctionArn", {
+        value: this.upworkProxyFunction.functionArn,
+      });
+    }
+
+    // --- CRM proxy -------------------------------------------------------
+    // Fixed operations and deployment-baked policy over the instance's own
+    // self-hosted CRM table.
+    if (provisionsIntegration(props.instance, "crm")) {
+      const crm = crmConfigForProvisioning(props.configPath);
+      const crmTable = props.crmTable;
+      if (crmTable === undefined)
+        throw new Error(
+          `${id}: integrations.crm is enabled but no CRM table was supplied by FoundationData`,
+        );
+      const crmProxyRole = new iam.Role(this, "CrmProxyRole", {
+        assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+        description: `${display} CRM proxy Lambda role (self-hosted CRM table access only)`,
+        managedPolicies: [
+          iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+        ],
+      });
+      crmProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "CrmProxySigningSecret",
+          actions: ["secretsmanager:GetSecretValue"],
+          resources: [secretArnPattern(props.secrets.signing)],
+        }),
+      );
+      crmProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "CrmTableData",
+          actions: [
+            "dynamodb:GetItem",
+            "dynamodb:PutItem",
+            "dynamodb:UpdateItem",
+            "dynamodb:DeleteItem",
+            "dynamodb:BatchWriteItem",
+            "dynamodb:TransactWriteItems",
+          ],
+          resources: [crmTable.tableArn],
+        }),
+      );
+      crmProxyRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "CrmRecordsIndex",
+          actions: ["dynamodb:Query"],
+          resources: [crmTable.tableArn, `${crmTable.tableArn}/index/RecordsIndex`],
+        }),
+      );
+      this.crmProxyFunction = new lambda.Function(this, "CrmProxyFunction", {
+        functionName: names.crmProxyFunctionName,
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: "index.handler",
+        code: lambdaCode(this, "crm-proxy"),
+        role: crmProxyRole,
+        timeout: cdk.Duration.seconds(30),
+        memorySize: 256,
+        environment: {
+          FOUNDATION_CRM_TABLE_NAME: crmTable.tableName,
+          FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+          FOUNDATION_SLACK_TEAM_ID: props.instance.slack.teamId,
+          FOUNDATION_CRM_TENANT_ID: props.instance.name,
+          FOUNDATION_CRM_ALLOWED_CHANNELS: JSON.stringify(crm.channels),
+          FOUNDATION_CRM_ALLOWED_STATUSES: JSON.stringify(crm.statuses),
+          FOUNDATION_CRM_ACTIVITY_TYPES: JSON.stringify(crm.activityTypes),
+          FOUNDATION_CRM_MAX_BATCH_SIZE: String(crm.maxBatchSize),
+        },
+      });
+      new cdk.CfnOutput(this, "CrmProxyFunctionArn", {
+        value: this.crmProxyFunction.functionArn,
+      });
+      new cdk.CfnOutput(this, "CrmPolicyFingerprint", {
+        value: crm.policyFingerprint,
+      });
+    }
+
+    const alarmTopic = new sns.Topic(this, "AlarmTopic", {
+      displayName: `${display} alarms`,
+    });
+    if (props.alarmEmail) {
+      new sns.Subscription(this, "AlarmEmail", {
+        topic: alarmTopic,
+        protocol: sns.SubscriptionProtocol.EMAIL,
+        endpoint: props.alarmEmail,
+      });
+    }
+    const alarmAction = new cwActions.SnsAction(alarmTopic);
+    // Depth ≥ 1 on either DLQ means a user's message was silently dropped —
+    // the only way anyone learns it needs a redrive.
+    for (const [name, queue] of [
+      ["GatewayDlqDepthAlarm", this.gatewayDlq],
+      ["InvokeDlqDepthAlarm", this.invokeDlq],
+    ] as const) {
+      const alarm = new cloudwatch.Alarm(this, name, {
+        alarmDescription: `${name}: messages are sitting in the DLQ`,
+        metric: queue.metricApproximateNumberOfMessagesVisible({
+          period: cdk.Duration.minutes(5),
+          statistic: "Maximum",
+        }),
+        threshold: 1,
+        evaluationPeriods: 1,
+        comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+      });
+      alarm.addAlarmAction(alarmAction);
+    }
+
+    // --- routines --------------------------------------------------------
+    // The group and the role live here because the queue does. The agent
+    // creates schedules INSIDE the group and passes the role; it never needs
+    // to create either, which is what keeps its own grants narrow.
+    new scheduler.CfnScheduleGroup(this, "RoutineGroup", { name: names.routineGroup });
+
+    const schedulerRole = new iam.Role(this, "RoutineSchedulerRole", {
+      roleName: names.routineSchedulerRole,
+      description: "Assumed by EventBridge Scheduler to enqueue a routine fire",
+      // Scoped to this account: without the condition any Scheduler schedule
+      // in any account could be pointed at this role.
+      assumedBy: new iam.ServicePrincipal("scheduler.amazonaws.com", {
+        conditions: { StringEquals: { "aws:SourceAccount": this.account } },
+      }),
+    });
+    // Grants the KMS use on the data key too, since the queue is encrypted.
+    this.invokeQueue.grantSendMessages(schedulerRole);
+
+    new cdk.CfnOutput(this, "GoogleCalendarOAuthRedirectUrl", {
+      value: this.api.urlForPath("/calendar/oauth/callback"),
+    });
+    new cdk.CfnOutput(this, "GoogleDriveOAuthRedirectUrl", {
+      value: this.api.urlForPath("/drive/oauth/callback"),
+    });
+    new cdk.CfnOutput(this, "GoogleEmailOAuthRedirectUrl", {
+      value: this.api.urlForPath("/email/oauth/callback"),
+    });
+    if (this.knockProxyFunction !== undefined) {
+      new cdk.CfnOutput(this, "KnockOAuthRedirectUrl", {
+        value: this.api.urlForPath("/knock/oauth/callback"),
+      });
+    }
+    new cdk.CfnOutput(this, "EmailProxyFunctionArn", {
+      value: this.emailProxyFunction.functionArn,
+    });
+    if (this.browserProxyFunction !== undefined) {
+      new cdk.CfnOutput(this, "BrowserProxyFunctionArn", {
+        value: this.browserProxyFunction.functionArn,
+      });
+    }
+    new cdk.CfnOutput(this, "InvokeQueueUrl", { value: this.invokeQueue.queueUrl });
+    new cdk.CfnOutput(this, "RoutineSchedulerRoleArn", { value: schedulerRole.roleArn });
+    if (authenticatedQueue)
+      new cdk.CfnOutput(this, "RoutineIngressFunctionArn", {
+        value: gatewayFunction.functionArn,
+      });
+
+    new cdk.CfnOutput(this, "EventsUrl", { value: this.api.urlForPath("/slack/events") });
+    new cdk.CfnOutput(this, "CommandsUrl", { value: this.api.urlForPath("/slack/commands") });
+    new cdk.CfnOutput(this, "InteractiveUrl", {
+      value: this.api.urlForPath("/slack/interactive"),
+    });
+  }
+}
+
+interface ProvisionedCrmConfig {
+  channels: string[];
+  statuses: string[];
+  activityTypes: string[];
+  maxBatchSize: number;
+  policyFingerprint: string;
+}
+
+function crmConfigForProvisioning(configPath: string): ProvisionedCrmConfig {
+  const config = parseInstanceConfig(readFileSync(configPath, "utf8"));
+  const crm = config.capabilities.crm;
+  const missing = [
+    ...(crm.enabled ? [] : ["capabilities.crm.enabled"]),
+    ...(crm.channels.length > 0 ? [] : ["capabilities.crm.channels"]),
+    ...(crm.statuses.length > 0 ? [] : ["capabilities.crm.statuses"]),
+    ...(crm.activityTypes.length > 0 ? [] : ["capabilities.crm.activityTypes"]),
+  ];
+  if (missing.length > 0)
+    throw new Error(
+      `${configPath}: integrations.crm requires a configured CRM capability (${missing.join(", ")})`,
+    );
+  return {
+    channels: [...crm.channels],
+    statuses: [...crm.statuses],
+    activityTypes: [...crm.activityTypes],
+    maxBatchSize: crm.maxBatchSize,
+    policyFingerprint: crmPolicyFingerprint(crm),
+  };
+}
+
+/** Deployment-baked debug policy: a config-only edit cannot widen the proxy. */
+export function knockConfigForProvisioning(configPath: string): { debug: boolean } {
+  const config = parseInstanceConfig(readFileSync(configPath, "utf8"));
+  return {
+    debug: config.capabilities.knock.enabled && config.capabilities.knock.debug,
+  };
+}
+
+interface ProvisionedUpworkConfig {
+  channels: string[];
+}
+
+function upworkConfigForProvisioning(configPath: string): ProvisionedUpworkConfig {
+  const config = parseInstanceConfig(readFileSync(configPath, "utf8"));
+  const upwork = config.capabilities.upwork;
+  const missing = [
+    ...(upwork.enabled ? [] : ["capabilities.upwork.enabled"]),
+    ...(upwork.channels.length > 0 ? [] : ["capabilities.upwork.channels"]),
+  ];
+  if (missing.length > 0)
+    throw new Error(
+      `${configPath}: integrations.upwork requires a configured Upwork capability (${missing.join(", ")})`,
+    );
+  return { channels: [...upwork.channels] };
+}
+
+/**
+ * The mailbox identities to bake into the proxy, read from the instance's own
+ * config file at synth.
+ *
+ * A plain file read: the CDK app must synthesize with no credentials and no
+ * network. A disabled capability yields an empty list, and so does a config
+ * that does not mention email at all — the proxy then refuses every identity,
+ * which is the correct behaviour for a capability nobody has turned on.
+ */
+export function emailIdentitiesFor(configPath: string): unknown[] {
+  const doc = parseYaml(readFileSync(configPath, "utf8")) as {
+    capabilities?: { email?: { enabled?: unknown; identities?: unknown } };
+  };
+  const email = doc.capabilities?.email;
+  if (email?.enabled !== true || !Array.isArray(email.identities)) return [];
+  return email.identities;
+}
+
+/** Server-side Browser allowlist baked into the isolated proxy at deploy time. */
+export function browserDomainsFor(configPath: string): string[] {
+  const browser = parseInstanceConfig(readFileSync(configPath, "utf8")).capabilities.browser;
+  return browser.enabled && browser.mode === "read" ? [...browser.allowedDomains] : [];
+}
+
+/**
+ * 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}-??????`;
+}