@deployfoundation/foundation-deploy 0.2.51 → 0.2.53

package/src/stacks/agent-stack.ts

@@ -23,6 +23,7 @@ import {
   provisionsIntegration,
   requiresAuthenticatedQueue,
 } from "../names.ts";
+import { SECRET_BEARING_READ_ACTIONS } from "./secret-bearing-reads.ts";
 
 export interface FoundationAgentProps extends cdk.StackProps {
   /** The deployment this stack belongs to; every name below comes from it. */
@@ -154,6 +155,7 @@ export class FoundationAgent extends cdk.Stack {
     this.accessPoint = accessPoint;
     this.executionRole = this.buildExecutionRole(props);
     this.readOnlyRole = this.buildReadOnlyRole(props);
+    this.secretBearingReadsPolicy(props.instance, [this.executionRole, this.readOnlyRole]);
     this.buildSpansIngestionPolicy();
 
     // The gateway is independent of the runtime: it can (and does) exist
@@ -378,26 +380,47 @@ export class FoundationAgent extends cdk.Stack {
       `${retainedTableArn}/index/*`,
       ...(crmTable === undefined ? [] : [crmTable.tableArn, `${crmTable.tableArn}/index/*`]),
     ];
+    // Every DynamoDB action, not only reads. The table also holds the
+    // proxy-owned outreach ledger (`TENANT#<name>#OUTREACH`, the weekly draft
+    // counters and each contact's touch clock). Until 2026-10 the deny named
+    // only read actions, so a future broad allow could have let the agent
+    // write a counter back to zero, delete a clock or restore a copy, and lift
+    // the weekly caps without going through the proxy.
     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",
-        ],
+        actions: ["dynamodb:*"],
         resources,
       }),
     );
   }
 
+  /**
+   * The key for a company's own CRM (`crm.provider` kind `http`) is the CRM
+   * proxy's alone. Both shell-reachable roles deny every action on it, by its
+   * fixed name, so no future broad grant can read it or overwrite it with a
+   * key of the agent's choosing.
+   */
+  private denyDirectCrmHttpSecretAccess(role: iam.Role, instance: Instance): void {
+    if (!provisionsIntegration(instance, "crm") || instance.crm.provider.kind !== "http") return;
+    role.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "DenyCrmHttpSecret",
+        effect: iam.Effect.DENY,
+        actions: ["secretsmanager:*"],
+        resources: [
+          cdk.Stack.of(this).formatArn({
+            service: "secretsmanager",
+            resource: "secret",
+            resourceName: `${this.names.secretCrmHttp}-??????`,
+            arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+          }),
+        ],
+      }),
+    );
+  }
+
   /** 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;
@@ -616,6 +639,8 @@ export class FoundationAgent extends cdk.Stack {
    * `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.
+   * What it covers but must not, the reads whose responses carry secrets,
+   * is denied by `secretBearingReadsPolicy`.
    */
   private buildReadOnlyRole(props: FoundationAgentProps): iam.Role {
     const role = new iam.Role(this, "AgentReadOnlyRole", {
@@ -628,6 +653,7 @@ export class FoundationAgent extends cdk.Stack {
       managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")],
     });
     this.denyDirectCrmTableAccess(role, props.instance, props.crmTable);
+    this.denyDirectCrmHttpSecretAccess(role, props.instance);
     this.denyDirectKnockSecretAccess(role, props);
     this.denyDirectEmailSecretAccess(
       role,
@@ -687,6 +713,36 @@ export class FoundationAgent extends cdk.Stack {
     return role;
   }
 
+  /**
+   * `ReadOnlyAccess` reads that return secrets: Lambda and container
+   * environment variables, user data, job and connection arguments, sampled
+   * WAF request headers, minted tokens ({@link SECRET_BEARING_READ_ACTIONS}).
+   *
+   * Both shell-reachable roles carry the deny. The read-only role needs it
+   * today, since its managed policy grants every one of these. The execution
+   * role grants none of them, and it gets the deny anyway for the same reason
+   * as the secret denies above: no future broad grant may reopen them.
+   *
+   * A managed policy of its own, like the pages policy, because the execution
+   * role's inline policy is near IAM's size limit. `Resource: "*"` because
+   * the point is every function, project and parameter in the account, not
+   * the instance's own.
+   */
+  private secretBearingReadsPolicy(instance: Instance, roles: iam.IRole[]): void {
+    new iam.ManagedPolicy(this, "AgentSecretBearingReadsDeny", {
+      description: `${instance.displayName} agent: no AWS read whose response carries a secret`,
+      roles,
+      statements: [
+        new iam.PolicyStatement({
+          sid: "DenySecretBearingReads",
+          effect: iam.Effect.DENY,
+          actions: [...SECRET_BEARING_READ_ACTIONS],
+          resources: ["*"],
+        }),
+      ],
+    });
+  }
+
   /**
    * Let X-Ray write this runtime's spans into the runtime's own log group.
    *
@@ -735,6 +791,7 @@ export class FoundationAgent extends cdk.Stack {
       description: `${props.instance.displayName} AgentCore execution role (least privilege)`,
     });
     this.denyDirectCrmTableAccess(role, props.instance, props.crmTable);
+    this.denyDirectCrmHttpSecretAccess(role, props.instance);
     this.denyDirectKnockSecretAccess(role, props);
     this.denyDirectUpworkApprovalAccess(role, props.upworkApprovalTable);
     this.denyDirectEmailSecretAccess(

package/src/stacks/api-stack.ts

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import {
   type CrmOutreachConfig,
+  type CrmStatusPolicy,
+  type CrmStatusesByType,
   type EmailIdentity,
   type GoogleDocsIdentity,
   type ScheduledJobBinding,
@@ -16,7 +18,10 @@ import {
   webhookJobBindings,
 } from "@deployfoundation/foundation-core";
 import { JOB_ACTOR } from "@deployfoundation/foundation-core/actor-capability";
-import { slackCommandPrefixes } from "@deployfoundation/foundation-core/instance";
+import {
+  FOUNDATION_VERSION_RE,
+  slackCommandPrefixes,
+} from "@deployfoundation/foundation-core/instance";
 import { parseSchedule } from "@deployfoundation/foundation-core/schedule";
 import * as cdk from "aws-cdk-lib";
 import * as apigateway from "aws-cdk-lib/aws-apigateway";
@@ -34,7 +39,7 @@ 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 { lambdaCode, releaseSource } from "../artifacts.ts";
 import {
   type Instance,
   LIVE_ENDPOINT_NAME,
@@ -1129,17 +1134,26 @@ export class FoundationApi extends cdk.Stack {
 
     // --- CRM proxy -------------------------------------------------------
     // Fixed operations and deployment-baked policy over the instance's own
-    // self-hosted CRM table.
+    // self-hosted CRM table, or over the company's own CRM through `crm/1`
+    // (`crm.provider` in the instance file). Either way this role is the only
+    // principal that touches the records or holds a credential for them.
     if (provisionsIntegration(props.instance, "crm")) {
       const crm = crmConfigForProvisioning(props.configPath);
+      const provider = props.instance.crm.provider;
       const crmTable = props.crmTable;
       if (crmTable === undefined)
         throw new Error(
           `${id}: integrations.crm is enabled but no CRM table was supplied by FoundationData`,
         );
+      // With `http` the table holds only the outreach cap ledger, so the
+      // proxy's role gets it only when outreach is configured.
+      const usesTable = provider.kind === "dynamodb" || crm.outreach !== undefined;
       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)`,
+        description:
+          provider.kind === "dynamodb"
+            ? `${display} CRM proxy Lambda role (self-hosted CRM table access only)`
+            : `${display} CRM proxy Lambda role (crm/1 key and outreach ledger only)`,
         managedPolicies: [
           iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
         ],
@@ -1151,41 +1165,128 @@ export class FoundationApi extends cdk.Stack {
           resources: [secretArnPattern(props.secrets.signing)],
         }),
       );
-      crmProxyRole.addToPolicy(
-        new iam.PolicyStatement({
-          sid: "CrmTableData",
-          actions: [
-            "dynamodb:GetItem",
-            "dynamodb:PutItem",
-            "dynamodb:UpdateItem",
-            "dynamodb:DeleteItem",
-            "dynamodb:BatchGetItem",
-            "dynamodb:BatchWriteItem",
-            "dynamodb:TransactWriteItems",
-            // A transaction's ConditionCheck is its own IAM action; the
-            // repository guards every upsert and activity with one.
-            "dynamodb:ConditionCheckItem",
-          ],
-          resources: [crmTable.tableArn],
-        }),
-      );
-      crmProxyRole.addToPolicy(
-        new iam.PolicyStatement({
-          sid: "CrmRecordsIndex",
-          actions: ["dynamodb:Query"],
-          resources: [crmTable.tableArn, `${crmTable.tableArn}/index/RecordsIndex`],
-        }),
-      );
+      if (provider.kind === "dynamodb") {
+        crmProxyRole.addToPolicy(
+          new iam.PolicyStatement({
+            sid: "CrmTableData",
+            actions: [
+              "dynamodb:GetItem",
+              "dynamodb:PutItem",
+              "dynamodb:UpdateItem",
+              "dynamodb:DeleteItem",
+              "dynamodb:BatchGetItem",
+              "dynamodb:BatchWriteItem",
+              "dynamodb:TransactWriteItems",
+              // A transaction's ConditionCheck is its own IAM action; the
+              // repository guards every upsert and activity with one.
+              "dynamodb:ConditionCheckItem",
+            ],
+            resources: [crmTable.tableArn],
+          }),
+        );
+        crmProxyRole.addToPolicy(
+          new iam.PolicyStatement({
+            sid: "CrmRecordsIndex",
+            actions: ["dynamodb:Query"],
+            resources: [crmTable.tableArn, `${crmTable.tableArn}/index/RecordsIndex`],
+          }),
+        );
+      } else {
+        // Read only. The key is written by an operator (`crm-key`), never by
+        // the proxy; the name is the fixed one FoundationData created it
+        // under, so this stack holds no cross-stack reference to it.
+        crmProxyRole.addToPolicy(
+          new iam.PolicyStatement({
+            sid: "CrmHttpSecret",
+            actions: ["secretsmanager:GetSecretValue"],
+            resources: [
+              secretArnPattern(
+                secretsmanager.Secret.fromSecretNameV2(this, "CrmHttpSecret", names.secretCrmHttp),
+              ),
+            ],
+          }),
+        );
+        // The ledger's items only: its weekly counters and reservations under
+        // one partition (`TENANT#<instance>#OUTREACH`). The profile and
+        // activity items a DynamoDB-provider proxy wrote stay in the table,
+        // unreadable to this role, and so does the records index. A reserve
+        // is one transaction (Put plus Update); a release deletes the
+        // reservation in another.
+        if (usesTable)
+          crmProxyRole.addToPolicy(
+            new iam.PolicyStatement({
+              sid: "CrmOutreachLedger",
+              actions: [
+                "dynamodb:GetItem",
+                "dynamodb:PutItem",
+                "dynamodb:UpdateItem",
+                "dynamodb:DeleteItem",
+                "dynamodb:TransactWriteItems",
+              ],
+              resources: [crmTable.tableArn],
+              conditions: {
+                "ForAllValues:StringEquals": {
+                  "dynamodb:LeadingKeys": [crmOutreachLedgerPartition(props.instance.name)],
+                },
+              },
+            }),
+          );
+      }
       // The table is encrypted with the instance's data key, so every read and
       // write needs it. Without this grant each call failed as `proxy_error`
       // (KMS AccessDenied) the first time a deployment actually used its CRM.
-      crmProxyRole.addToPolicy(
-        new iam.PolicyStatement({
-          sid: "CrmTableKey",
-          actions: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
-          resources: [(crmTable.encryptionKey ?? props.dataKey).keyArn],
-        }),
-      );
+      if (usesTable)
+        crmProxyRole.addToPolicy(
+          new iam.PolicyStatement({
+            sid: "CrmTableKey",
+            actions: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
+            resources: [(crmTable.encryptionKey ?? props.dataKey).keyArn],
+          }),
+        );
+      const release = releaseVersionContext(this);
+      const crmProxyEnvironment: Record<string, string> = {
+        // Baked even when `http` has no ledger to keep (the proxy then ignores
+        // it, and the role above has no grant on the table): dropping it would
+        // drop FoundationData's export of the name while the API stack still
+        // deployed imports it, and the data stack, deployed first, would fail.
+        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),
+        // Which status changes the agent may make, and whether it may
+        // delete: refused here, so a config sync alone cannot widen them.
+        FOUNDATION_CRM_STATUS_POLICY: JSON.stringify(crm.statusPolicy),
+        FOUNDATION_CRM_DELETES: String(crm.deletes),
+        // The outreach caps are enforced here, so they are baked like the
+        // rest of the policy: a config sync alone cannot lift them.
+        ...(crm.outreach === undefined
+          ? {}
+          : {
+              FOUNDATION_CRM_OUTREACH: JSON.stringify(crm.outreach),
+              FOUNDATION_CRM_TIMEZONE: crm.timezone,
+            }),
+        // Where the records live. Unset means `dynamodb`, so a DynamoDB
+        // deployment's environment is what it was before `http` existed.
+        ...(provider.kind === "http"
+          ? {
+              FOUNDATION_CRM_PROVIDER: "http",
+              FOUNDATION_CRM_HTTP_BASE_URL: provider.baseUrl,
+              // The id, never the key: the proxy reads it at request time.
+              FOUNDATION_CRM_HTTP_SECRET_ID: names.secretCrmHttp,
+              FOUNDATION_CRM_HTTP_EXPECTED_TENANT: provider.expectedTenant,
+              // Only the User-Agent the CRM sees, for its logs.
+              ...(release === undefined ? {} : { FOUNDATION_RELEASE: release }),
+            }
+          : {}),
+      };
+      // The config parser caps the policy JSON (CRM_MAX_POLICY_ENV_BYTES);
+      // this checks the whole environment, names and table included, at synth
+      // rather than as a failed Lambda update halfway through a deploy.
+      assertLambdaEnvironmentBudget(crmProxyEnvironment);
       this.crmProxyFunction = new lambda.Function(this, "CrmProxyFunction", {
         functionName: names.crmProxyFunctionName,
         runtime: lambda.Runtime.NODEJS_22_X,
@@ -1194,24 +1295,7 @@ export class FoundationApi extends cdk.Stack {
         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),
-          // The outreach caps are enforced here, so they are baked like the
-          // rest of the policy: a config sync alone cannot lift them.
-          ...(crm.outreach === undefined
-            ? {}
-            : {
-                FOUNDATION_CRM_OUTREACH: JSON.stringify(crm.outreach),
-                FOUNDATION_CRM_TIMEZONE: crm.timezone,
-              }),
-        },
+        environment: crmProxyEnvironment,
       });
       new cdk.CfnOutput(this, "CrmProxyFunctionArn", {
         value: this.crmProxyFunction.functionArn,
@@ -1277,6 +1361,13 @@ export class FoundationApi extends cdk.Stack {
       agentRuntimeArn: props.agentRuntimeArn,
       alarmAction,
     });
+    // A company's own CRM refusing, or answering as someone else.
+    if (this.crmProxyFunction !== undefined && props.instance.crm.provider.kind === "http")
+      addCrmProviderAlarms(this, {
+        instance: props.instance,
+        functionName: names.crmProxyFunctionName,
+        alarmAction,
+      });
 
     // --- deployment-owned scheduled jobs --------------------------------
     // Config jobs never share the agent-managed routine group or pass role.
@@ -1451,37 +1542,13 @@ export function addConfigLoadAlarm(
   if (args.agentRuntimeArn.endsWith("-pending")) return undefined;
   const runtimeId = cdk.Fn.select(1, cdk.Fn.split("/", args.agentRuntimeArn));
   const logGroupName = `/aws/bedrock-agentcore/runtimes/${runtimeId}-${LIVE_ENDPOINT_NAME}`;
-  const role = new iam.Role(stack, "AgentLiveLogGroupRole", {
-    assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
-    description: `${args.instance.displayName} creates the runtime's live log group when missing`,
-    managedPolicies: [
-      iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
-    ],
-  });
-  role.addToPolicy(
-    new iam.PolicyStatement({
-      sid: "CreateRuntimeLiveLogGroup",
-      actions: ["logs:CreateLogGroup"],
-      resources: [
-        `arn:${stack.partition}:logs:${stack.region}:${stack.account}:log-group:${logGroupName}`,
-      ],
-    }),
-  );
-  const ensureFunction = new lambda.Function(stack, "AgentLiveLogGroupFunction", {
-    runtime: lambda.Runtime.NODEJS_22_X,
-    handler: "index.runtimeLogGroupHandler",
-    code: lambdaCode(stack, "gateway"),
-    role,
-    timeout: cdk.Duration.seconds(30),
-    memorySize: 128,
-  });
-  const ensureLogGroup = new cdk.CustomResource(stack, "AgentLiveLogGroup", {
-    serviceToken: ensureFunction.functionArn,
+  const ensureLogGroup = ensureLogGroupExists(stack, {
+    id: "AgentLiveLogGroup",
+    sid: "CreateRuntimeLiveLogGroup",
     resourceType: "Custom::FoundationRuntimeLogGroup",
-    properties: { LogGroupName: logGroupName },
+    description: `${args.instance.displayName} creates the runtime's live log group when missing`,
+    logGroupName,
   });
-  // The function needs its permission before CloudFormation invokes it.
-  ensureLogGroup.node.addDependency(role);
   const filter = new logs.MetricFilter(stack, "ConfigLoadFailureMetricFilter", {
     logGroup: logs.LogGroup.fromLogGroupName(stack, "AgentLiveLogs", logGroupName),
     filterPattern: logs.FilterPattern.any(
@@ -1512,11 +1579,193 @@ export function addConfigLoadAlarm(
   return alarm;
 }
 
+/**
+ * A custom resource that creates `logGroupName` when it is missing and leaves
+ * it alone when it exists (or when the stack is deleted), so a metric filter
+ * can attach to a group that AWS, not CloudFormation, creates on first use.
+ * The handler (`runtimeLogGroupHandler`, in the release-signed gateway bundle)
+ * accepts only an AgentCore runtime's or a Lambda's group, and the role may
+ * create exactly this one.
+ */
+function ensureLogGroupExists(
+  stack: cdk.Stack,
+  args: {
+    /** Construct id prefix: `<id>Role`, `<id>Function`, and `<id>` for the resource. */
+    id: string;
+    sid: string;
+    resourceType: string;
+    description: string;
+    logGroupName: string;
+  },
+): cdk.CustomResource {
+  const role = new iam.Role(stack, `${args.id}Role`, {
+    assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+    description: args.description,
+    managedPolicies: [
+      iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+    ],
+  });
+  role.addToPolicy(
+    new iam.PolicyStatement({
+      sid: args.sid,
+      actions: ["logs:CreateLogGroup"],
+      resources: [
+        `arn:${stack.partition}:logs:${stack.region}:${stack.account}:log-group:${args.logGroupName}`,
+      ],
+    }),
+  );
+  const ensureFunction = new lambda.Function(stack, `${args.id}Function`, {
+    runtime: lambda.Runtime.NODEJS_22_X,
+    handler: "index.runtimeLogGroupHandler",
+    code: lambdaCode(stack, "gateway"),
+    role,
+    timeout: cdk.Duration.seconds(30),
+    memorySize: 128,
+  });
+  const ensureLogGroup = new cdk.CustomResource(stack, args.id, {
+    serviceToken: ensureFunction.functionArn,
+    resourceType: args.resourceType,
+    properties: { LogGroupName: args.logGroupName },
+  });
+  // The function needs its permission before CloudFormation invokes it.
+  ensureLogGroup.node.addDependency(role);
+  return ensureLogGroup;
+}
+
+/**
+ * The CRM proxy's log codes that mean a company's own CRM (`crm.provider`
+ * kind `http`) needs a person. Each is one metric filter on the proxy's log
+ * group and one alarm on the instance's alarm topic; the log line itself
+ * carries only fixed words (the op, the status class, which `/meta` check
+ * failed), never a record or a reply body.
+ */
+export const CRM_PROVIDER_ALARMS = [
+  {
+    event: "crm_proxy",
+    code: "tenant_mismatch",
+    name: "TenantMismatch",
+    description:
+      "The CRM answered as a different tenant from crm.provider.expectedTenant, so the CRM proxy refused the reply and the CRM tools fail closed. Check that the key written with crm-key was issued for that tenant, and that expectedTenant is right.",
+  },
+  {
+    event: "crm_proxy",
+    code: "upstream_unauthorized",
+    name: "UpstreamUnauthorized",
+    description:
+      "The CRM refused the CRM proxy's key (401), even after the proxy re-read it: revoked, expired or wrong. Issue a new key in the CRM and run foundation-deploy crm-key; the proxy picks it up on its next call.",
+  },
+  {
+    event: "crm_proxy",
+    code: "upstream_forbidden",
+    name: "UpstreamForbidden",
+    description:
+      "The CRM answered 403: a scope the key lacks, the CRM's kill switch, or a WAF in front of it blocking the proxy. Check the key's scopes, the switch and the WAF's logs.",
+  },
+  {
+    event: "crm_proxy",
+    code: "unconfigured",
+    name: "Unconfigured",
+    description:
+      "The CRM proxy is unconfigured, so every CRM tool fails closed: no key written yet (run foundation-deploy crm-key), or the CRM's /meta does not match the deployment. The log line's check field names which: contract, statuses, activity_types, batch_size or operations.",
+  },
+  {
+    event: "crm_proxy_warning",
+    code: "ledger_kept",
+    name: "LedgerKept",
+    description:
+      "A draft's outreach reservation was kept because the CRM's answer was unknown (a timeout, a 5xx, a 429 or a reply without the contract header). The weekly cap counts it, failing closed. Check in the CRM whether that draft was logged.",
+  },
+  {
+    event: "crm_proxy_warning",
+    code: "policy_mismatch",
+    name: "PolicyMismatch",
+    description:
+      "The CRM's own policy in /meta differs from the deployment's capabilities.crm (the log line's fields name which). Each side enforces its own, so the stricter wins; align the two.",
+  },
+] as const;
+
+/**
+ * Alarms on the CRM proxy's log group for a company's own CRM: one per
+ * {@link CRM_PROVIDER_ALARMS} entry, on the instance's alarm topic.
+ *
+ * Lambda creates `/aws/lambda/<function>` on the first invocation, and a
+ * proxy that ran before (on the DynamoDB provider) already has one that
+ * CloudFormation does not own, so the group is ensured by a custom resource
+ * exactly as the runtime's live group is.
+ *
+ * Five minutes, except `policy_mismatch`: it is logged at every `/meta` check
+ * for as long as the two policies differ, so an hour keeps it from
+ * re-notifying after every quiet gap.
+ */
+export function addCrmProviderAlarms(
+  stack: cdk.Stack,
+  args: { instance: Instance; functionName: string; alarmAction: cloudwatch.IAlarmAction },
+): cloudwatch.Alarm[] {
+  const logGroupName = `/aws/lambda/${args.functionName}`;
+  const ensureLogGroup = ensureLogGroupExists(stack, {
+    id: "CrmProxyLogGroup",
+    sid: "CreateCrmProxyLogGroup",
+    resourceType: "Custom::FoundationLambdaLogGroup",
+    description: `${args.instance.displayName} creates the CRM proxy's log group when missing`,
+    logGroupName,
+  });
+  const logGroup = logs.LogGroup.fromLogGroupName(stack, "CrmProxyLogs", logGroupName);
+  return CRM_PROVIDER_ALARMS.map((entry) => {
+    const filter = new logs.MetricFilter(stack, `CrmProxy${entry.name}MetricFilter`, {
+      logGroup,
+      filterPattern: logs.FilterPattern.all(
+        logs.FilterPattern.stringValue("$.event", "=", entry.event),
+        logs.FilterPattern.stringValue("$.code", "=", entry.code),
+      ),
+      metricNamespace: `Foundation/${args.instance.naming.prefix}`,
+      metricName: `CrmProxy${entry.name}`,
+      metricValue: "1",
+    });
+    filter.node.addDependency(ensureLogGroup);
+    const alarm = new cloudwatch.Alarm(stack, `CrmProxy${entry.name}Alarm`, {
+      alarmDescription: `${args.instance.displayName} CRM proxy logged ${entry.code}. ${entry.description}`,
+      metric: filter.metric({
+        statistic: "Sum",
+        period: cdk.Duration.minutes(entry.code === "policy_mismatch" ? 60 : 5),
+      }),
+      threshold: 1,
+      evaluationPeriods: 1,
+      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+    });
+    alarm.addAlarmAction(args.alarmAction);
+    return alarm;
+  });
+}
+
+/**
+ * The partition holding the outreach cap ledger, the only items the CRM
+ * proxy's role may touch with the `http` provider. Kept equal to
+ * `outreachLedgerPartition` in the CRM capability's `proxy/ledger.ts` (a test
+ * pins it); not imported, so the CDK app does not load the proxy's AWS SDK.
+ */
+export function crmOutreachLedgerPartition(tenantId: string): string {
+  return `TENANT#${tenantId}#OUTREACH`;
+}
+
+/**
+ * The release a synth deploys, for the CRM proxy's User-Agent:
+ * `-c foundationVersion`, which the deploy tool passes, else the release
+ * being deployed. Absent on a bare synth, which the proxy tolerates.
+ */
+function releaseVersionContext(scope: Construct): string | undefined {
+  const explicit = String(scope.node.tryGetContext("foundationVersion") ?? "");
+  const version = explicit !== "" ? explicit : releaseSource(scope)?.version;
+  return version !== undefined && FOUNDATION_VERSION_RE.test(version) ? version : undefined;
+}
+
 interface ProvisionedCrmConfig {
   channels: string[];
-  statuses: string[];
+  statuses: CrmStatusesByType;
   activityTypes: string[];
   maxBatchSize: number;
+  statusPolicy: CrmStatusPolicy;
+  deletes: boolean;
   policyFingerprint: string;
   /** Absent when no status is eligible for outreach. */
   outreach?: CrmOutreachConfig;
@@ -1526,10 +1775,12 @@ interface ProvisionedCrmConfig {
 function crmConfigForProvisioning(configPath: string): ProvisionedCrmConfig {
   const config = parseInstanceConfig(readFileSync(configPath, "utf8"));
   const crm = config.capabilities.crm;
+  // Each record type needs a status for the records an upsert creates.
   const missing = [
     ...(crm.enabled ? [] : ["capabilities.crm.enabled"]),
     ...(crm.channels.length > 0 ? [] : ["capabilities.crm.channels"]),
-    ...(crm.statuses.length > 0 ? [] : ["capabilities.crm.statuses"]),
+    ...(crm.statuses.company.length > 0 ? [] : ["capabilities.crm.statuses.company"]),
+    ...(crm.statuses.contact.length > 0 ? [] : ["capabilities.crm.statuses.contact"]),
     ...(crm.activityTypes.length > 0 ? [] : ["capabilities.crm.activityTypes"]),
   ];
   if (missing.length > 0)
@@ -1538,9 +1789,11 @@ function crmConfigForProvisioning(configPath: string): ProvisionedCrmConfig {
     );
   return {
     channels: [...crm.channels],
-    statuses: [...crm.statuses],
+    statuses: { company: [...crm.statuses.company], contact: [...crm.statuses.contact] },
     activityTypes: [...crm.activityTypes],
     maxBatchSize: crm.maxBatchSize,
+    statusPolicy: crm.statusPolicy,
+    deletes: crm.deletes,
     policyFingerprint: crmPolicyFingerprint(crm),
     ...(crmOutreachConfigured(crm.outreach) ? { outreach: crm.outreach } : {}),
     timezone: config.timezone,
@@ -1672,7 +1925,7 @@ export function assertLambdaEnvironmentBudget(values: Readonly<Record<string, st
   }
   if (bytes > LAMBDA_ENVIRONMENT_MAX_BYTES) {
     throw new Error(
-      `Gateway Lambda environment needs an estimated ${bytes} bytes; the AWS limit is ${LAMBDA_ENVIRONMENT_MAX_BYTES}. Shorten job prompts or reduce configured values.`,
+      `A Lambda environment needs an estimated ${bytes} bytes; the AWS limit is ${LAMBDA_ENVIRONMENT_MAX_BYTES}. Shorten job prompts or reduce configured values.`,
     );
   }
 }