@caelo-cms/provisioning 0.11.9 → 0.11.11

package/src/media-volume.test.ts

@@ -152,7 +152,7 @@ describe("admin media volume contract", () => {
       domain: "acme.com",
       stagingHost: "staging.acme.com",
       region: "europe-west1",
-      databaseUrls: databaseUrls("10.0.0.3"),
+      databaseUrls: databaseUrls("db1.p-label.europe-west1.sql-psa.goog"),
     });
     expect(env).toContainEqual({ name: "MEDIA_ROOT_DIR", value: MEDIA_MOUNT_PATH });
   });

package/src/migration-runner.ts

@@ -24,6 +24,7 @@ import { green, red } from "kleur/colors";
 import { gcloud as defaultGcloud } from "./gcloud.js";
 import type { GcloudRunner } from "./gcloud-retry.js";
 import { GCP_STACK_ENV, gcpSecretId, runServiceAccountEmail } from "./gcp-names.js";
+import { MIGRATION_TARGETS } from "./migration-targets.js";
 import { databaseUrls, SERVICE_SECRET_ENV } from "./stack-contract.js";
 import { liveContainerEnv, liveDatabaseHost } from "./stack-converge.js";
 
@@ -58,15 +59,19 @@ const NEEDS_UPGRADE =
  */
 export function migrationJobEnvArgs(databaseHost: string, env = GCP_STACK_ENV): string[] {
   const urls = databaseUrls(databaseHost);
-  const passwords = (["ADMIN_DATABASE_PASSWORD", "PUBLIC_ADMIN_DATABASE_PASSWORD"] as const).map(
-    (name) => {
-      const secret = SERVICE_SECRET_ENV.admin[name];
-      if (!secret) throw new Error(`the admin env contract has no ${name}`);
-      return `${name}=${gcpSecretId(env, secret)}:latest`;
-    },
-  );
+  const passwords = (
+    [
+      "ADMIN_DATABASE_PASSWORD",
+      "PUBLIC_ADMIN_DATABASE_PASSWORD",
+      "PUBLIC_STAGING_ADMIN_DATABASE_PASSWORD",
+    ] as const
+  ).map((name) => {
+    const secret = SERVICE_SECRET_ENV.admin[name];
+    if (!secret) throw new Error(`the admin env contract has no ${name}`);
+    return `${name}=${gcpSecretId(env, secret)}:latest`;
+  });
   return [
-    `--set-env-vars=ADMIN_DATABASE_URL=${urls.admin},PUBLIC_ADMIN_DATABASE_URL=${urls.publicAdmin}`,
+    `--set-env-vars=ADMIN_DATABASE_URL=${urls.admin},PUBLIC_ADMIN_DATABASE_URL=${urls.publicAdmin},PUBLIC_STAGING_ADMIN_DATABASE_URL=${urls.publicStagingAdmin}`,
     `--set-secrets=${passwords.join(",")}`,
   ];
 }
@@ -300,7 +305,7 @@ export async function runMigrationsViaCloudRunJob(
     sAdmin.stop(green(`Admin config resolved (${migrationImage.slice(-19)})`));
   }
 
-  for (const target of ["admin", "public"] as const) {
+  for (const target of MIGRATION_TARGETS) {
     const s = spinner();
     s.start(`Applying ${target} migrations via one-shot Cloud Run Job...`);
     // Delete-then-create so each invocation runs with the freshest

package/src/migration-targets.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The targets of `packages/migrations/src/migrate.ts`, in the order every
+ * runner applies them — the GCP migration job (migration-runner.ts), the
+ * self-hosted install and upgrade (self-hosted-start.ts,
+ * self-hosted-upgrade.ts) and the self-hosted stack: cms_admin first (its
+ * role audit covers the whole cluster), then the two public databases,
+ * which run the same cms_public files (#1329: cms_public_staging is the
+ * staging site's twin, with its own gateway login).
+ */
+export const MIGRATION_TARGETS = ["admin", "public", "public-staging"] as const;

package/src/operator-access-stacks.test.ts

@@ -45,7 +45,7 @@ describe("admin env contract — operator access", () => {
       domain: "acme.com",
       stagingHost: "staging.acme.com",
       region: "europe-west1",
-      databaseUrls: databaseUrls("10.0.0.3"),
+      databaseUrls: databaseUrls("db1.p-label.europe-west1.sql-psa.goog"),
     });
     expect(env).toContainEqual({
       name: "CAELO_OPERATOR_ACCESS_JOB",

package/src/operator-access.test.ts

@@ -51,7 +51,7 @@ const target: OperatorAccessSyncTarget = {
   imageRef: "europe-west1-docker.pkg.dev/r/admin@sha256:new",
   network: "net",
   subnet: "sub",
-  databaseHost: "10.0.0.3",
+  databaseHost: "db1.p-label.europe-west1.sql-psa.goog",
 };
 
 const roleJson = JSON.stringify({ includedPermissions: [...OPERATOR_ACCESS_ROLE.permissions] });
@@ -201,10 +201,25 @@ describe("ensureOperatorAccessSync", () => {
       "--args=--bun,/app/packages/admin-core/src/security/operator-access/sync-job.ts",
     );
     expect(deploy).toContain(
-      "--set-env-vars=^|^CAELO_OPERATOR_ACCESS_IAP_WEB=cloud_run-europe-west1/services/caelo-production-admin-abc|CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@p.iam.gserviceaccount.com|CAELO_OPERATOR_ACCESS_STATIC_MEMBERS=user:owner@x.com|CAELO_OPERATOR_ACCESS_DB_HOST=10.0.0.3|CAELO_OPERATOR_OAUTH_CLIENT_SECRET=projects/p/secrets/caelo-production-operator-oauth-client",
+      "--set-env-vars=^|^CAELO_OPERATOR_ACCESS_IAP_WEB=cloud_run-europe-west1/services/caelo-production-admin-abc|CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@p.iam.gserviceaccount.com|CAELO_OPERATOR_ACCESS_STATIC_MEMBERS=user:owner@x.com|CAELO_OPERATOR_ACCESS_DB_HOST=db1.p-label.europe-west1.sql-psa.goog|CAELO_OPERATOR_OAUTH_CLIENT_SECRET=projects/p/secrets/caelo-production-operator-oauth-client",
     );
   });
 
+  it("#1140 — tells the job which service accounts keep IAP access (the scheduler tick)", async () => {
+    const { run, calls } = freshInstall();
+    await ensureOperatorAccessSync(
+      { ...target, iapServiceAccounts: ["caelo-production-scheduler@p.iam.gserviceaccount.com"] },
+      { run, sleep: async () => {} },
+    );
+    const deploy = calls.find((c) => c.slice(0, 3).join(" ") === "run jobs deploy") ?? [];
+    const env = deploy.find((a) => a.startsWith("--set-env-vars=")) ?? "";
+    expect(env).toContain(
+      "|CAELO_OPERATOR_ACCESS_IAP_SERVICE_ACCOUNTS=caelo-production-scheduler@p.iam.gserviceaccount.com",
+    );
+    // The static members stay the install's allowlist (converge-job-gcp.ts compares them).
+    expect(env).toContain("|CAELO_OPERATOR_ACCESS_STATIC_MEMBERS=user:owner@x.com|");
+  });
+
   it("#914 — lets the job read exactly the Google sign-in client's secret, nothing else", async () => {
     const { run, lines } = freshInstall();
     await ensureOperatorAccessSync(target, { run, sleep: async () => {} });
@@ -322,7 +337,8 @@ describe("resolveOperatorAccessTarget", () => {
               env: [
                 {
                   name: "ADMIN_DATABASE_URL",
-                  value: "postgresql://admin_role@10.0.0.3:5432/cms_admin",
+                  value:
+                    "postgresql://admin_role@db1.p-label.europe-west1.sql-psa.goog:5432/cms_admin",
                 },
               ],
             },
@@ -351,7 +367,7 @@ describe("resolveOperatorAccessTarget", () => {
         imageRef: "img@sha256:new",
         network: "net",
         subnet: "sub",
-        databaseHost: "10.0.0.3",
+        databaseHost: "db1.p-label.europe-west1.sql-psa.goog",
       },
     });
   });

package/src/operator-access.ts

@@ -218,11 +218,22 @@ export interface OperatorAccessSyncTarget {
    * The job reconciles that binding, so anyone missing here loses it.
    */
   readonly mcpSigners?: readonly string[];
+  /**
+   * #1140 — service accounts (besides caelo-mcp) that keep
+   * `roles/iap.httpsResourceAccessor` on the admin: the scheduler tick's
+   * account (scheduler-setup.ts) calls the admin through IAP. The job
+   * reconciles that binding to exactly its members, so anyone missing here
+   * loses it on the next run. Emails, not `serviceAccount:` members.
+   */
+  readonly iapServiceAccounts?: readonly string[];
 }
 
 /** Env var of the sync job listing {@link OperatorAccessSyncTarget.mcpSigners}. */
 export const MCP_SIGNERS_ENV = "CAELO_OPERATOR_ACCESS_MCP_SIGNERS";
 
+/** #1140 — env var of the sync job listing {@link OperatorAccessSyncTarget.iapServiceAccounts}. */
+export const IAP_SERVICE_ACCOUNTS_ENV = "CAELO_OPERATOR_ACCESS_IAP_SERVICE_ACCOUNTS";
+
 /** #914 — env var of the sync job naming the Google sign-in client's secret. */
 export const OPERATOR_OAUTH_CLIENT_SECRET_ENV = "CAELO_OPERATOR_OAUTH_CLIENT_SECRET";
 
@@ -424,6 +435,9 @@ export async function ensureOperatorAccessSync(
     ...(target.mcpSigners && target.mcpSigners.length > 0
       ? [`${MCP_SIGNERS_ENV}=${target.mcpSigners.join(",")}`]
       : []),
+    ...(target.iapServiceAccounts && target.iapServiceAccounts.length > 0
+      ? [`${IAP_SERVICE_ACCOUNTS_ENV}=${target.iapServiceAccounts.join(",")}`]
+      : []),
   ];
   const deploy = await run([
     "run",

package/src/pool-budget-stack.ts

@@ -14,11 +14,14 @@
 
 import {
   computePoolBudget,
+  DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
   type PoolBudget,
   type PoolBudgetInput,
   poolBudgetEnv,
 } from "@caelo-cms/shared";
 
+export { DEFAULT_STAGING_GATEWAY_MAX_INSTANCES };
+
 /** The adapters that provision a Postgres server. */
 export type BudgetProvider = "gcp" | "gcp-firebase" | "aws" | "azure" | "self-hosted";
 
@@ -84,12 +87,24 @@ export const DEFAULT_MAX_CONNECTIONS: Readonly<Record<BudgetProvider, number>> =
  */
 export const DEFAULT_GATEWAY_MAX_INSTANCES = 10;
 
+/**
+ * Admin instances a GCP or AWS stack lets start (`adminMaxInstances` knob).
+ * Five before #1329; the staging database added the admin's
+ * cms_public_staging pool and the staging gateway to the budget, and on the
+ * default server (100 connections) five instances no longer get the
+ * minimum cms_admin pool. Raising `max_connections` instead was ruled out
+ * for db-f1-micro (docs/dev/connection-budget.md, "#1329").
+ */
+export const DEFAULT_ADMIN_MAX_INSTANCES = 4;
+
 /** The server and scale-out a stack sizes its pools for. */
 export interface StackScale {
   readonly maxConnections: number;
   /** Every instance that opens the admin's pools (admin-side services included). */
   readonly adminMaxInstances: number;
   readonly gatewayMaxInstances: number;
+  /** #1329 — the staging gateway's scale-out ({@link DEFAULT_STAGING_GATEWAY_MAX_INSTANCES}). */
+  readonly stagingGatewayMaxInstances: number;
 }
 
 /** A stack's budget plus the env each service sets from it. */

package/src/pool-budget-stacks.test.ts

@@ -12,8 +12,10 @@ import { resolve } from "node:path";
 import { COMPOSE_POOL_BUDGET } from "./compose.js";
 import {
   type BudgetProvider,
+  DEFAULT_ADMIN_MAX_INSTANCES,
   DEFAULT_GATEWAY_MAX_INSTANCES,
   DEFAULT_MAX_CONNECTIONS,
+  DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
   stackPoolBudget,
 } from "./pool-budget-stack.js";
 
@@ -21,22 +23,39 @@ const stackSource = (provider: string): string =>
   readFileSync(resolve(import.meta.dir, "..", "stacks", provider, "index.ts"), "utf8");
 
 /** Each stack's default scale-out, as its index.ts reads it. */
-const DEFAULT_SCALE: Record<BudgetProvider, { admin: number; gateway: number }> = {
-  gcp: { admin: 5, gateway: DEFAULT_GATEWAY_MAX_INSTANCES },
-  "gcp-firebase": { admin: 5, gateway: DEFAULT_GATEWAY_MAX_INSTANCES },
-  aws: { admin: 5, gateway: DEFAULT_GATEWAY_MAX_INSTANCES },
+const DEFAULT_SCALE: Record<BudgetProvider, { admin: number; gateway: number; staging: number }> = {
+  gcp: {
+    admin: DEFAULT_ADMIN_MAX_INSTANCES,
+    gateway: DEFAULT_GATEWAY_MAX_INSTANCES,
+    staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
+  },
+  "gcp-firebase": {
+    admin: DEFAULT_ADMIN_MAX_INSTANCES,
+    gateway: DEFAULT_GATEWAY_MAX_INSTANCES,
+    staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
+  },
+  aws: {
+    admin: DEFAULT_ADMIN_MAX_INSTANCES,
+    gateway: DEFAULT_GATEWAY_MAX_INSTANCES,
+    staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES,
+  },
   // admin + orchestrator + runner apps, 10 replicas each.
-  azure: { admin: 30, gateway: 10 },
-  "self-hosted": { admin: 1, gateway: 1 },
+  azure: { admin: 30, gateway: 10, staging: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES },
+  "self-hosted": { admin: 1, gateway: 1, staging: 1 },
 };
 
-/** [cms_admin pool per admin instance, connections left unassigned]. */
+/**
+ * [cms_admin pool per admin instance, connections left unassigned]. #1329
+ * added the staging gateway and the admin's cms_public_staging pool; the
+ * GCP and AWS stacks start four admin instances instead of five so the
+ * cms_admin pool stays at five (docs/dev/connection-budget.md).
+ */
 const EXPECTED: Record<BudgetProvider, [number, number]> = {
-  gcp: [5, 1],
-  "gcp-firebase": [5, 1],
-  aws: [5, 3],
-  azure: [7, 12],
-  "self-hosted": [77, 0],
+  gcp: [5, 0],
+  "gcp-firebase": [5, 0],
+  aws: [5, 2],
+  azure: [5, 9],
+  "self-hosted": [72, 0],
 };
 
 describe("stack pool budgets at the default config", () => {
@@ -46,7 +65,10 @@ describe("stack pool budgets at the default config", () => {
         maxConnections: DEFAULT_MAX_CONNECTIONS[provider],
         adminMaxInstances: DEFAULT_SCALE[provider].admin,
         gatewayMaxInstances: DEFAULT_SCALE[provider].gateway,
+        stagingGatewayMaxInstances: DEFAULT_SCALE[provider].staging,
       });
+      expect(budget.reserves.map((r) => r.name)).toContain("staging-gateway");
+      expect(budget.reserves.map((r) => r.name)).toContain("admin-public-staging");
       expect([budget.adminPoolMax, budget.unassigned]).toEqual(EXPECTED[provider]);
       expect(env.admin).toEqual([
         { name: "CAELO_DB_POOL_MAX", value: String(EXPECTED[provider][0]) },
@@ -60,10 +82,11 @@ describe("stack pool budgets at the default config", () => {
     expect(() =>
       stackPoolBudget("gcp", {
         maxConnections: 100,
-        adminMaxInstances: 5,
+        adminMaxInstances: 4,
         gatewayMaxInstances: 100,
+        stagingGatewayMaxInstances: 1,
       }),
-    ).toThrow(/Raise maxConnections/);
+    ).toThrow(/CONNECTION LIMIT, #1338/);
   });
 });
 
@@ -75,6 +98,8 @@ describe("stacks set the budget on their services", () => {
       expect(src).toContain("...poolBudget.env.admin");
       expect(src).toContain("...poolBudget.env.gateway");
       expect(src).toContain("maxInstances: gatewayMaxInstances");
+      expect(src).toContain("stagingGatewayMaxInstances: DEFAULT_STAGING_GATEWAY_MAX_INSTANCES");
+      expect(src).toContain('cfg.get("adminMaxInstances") ?? String(DEFAULT_ADMIN_MAX_INSTANCES)');
       expect(src).not.toContain("maxInstances: 100");
     });
   }

package/src/public-role-isolation.test.ts

@@ -25,7 +25,11 @@ function fake(answers: (line: string) => GcloudResult) {
 describe("revokePublicRoleMembershipsArgs (#633)", () => {
   it("revokes every database role of the built-in public_role user", () => {
     expect(
-      revokePublicRoleMembershipsArgs({ projectId: "acme", sqlInstance: "caelo-production-pg-1" }),
+      revokePublicRoleMembershipsArgs({
+        projectId: "acme",
+        sqlInstance: "caelo-production-pg-1",
+        role: "public_role",
+      }),
     ).toEqual([
       "sql",
       "users",
@@ -40,7 +44,12 @@ describe("revokePublicRoleMembershipsArgs (#633)", () => {
   });
 
   it("grants nothing in exchange (no --database-roles)", () => {
-    const args = revokePublicRoleMembershipsArgs({ projectId: "p", sqlInstance: "i" });
+    const args = revokePublicRoleMembershipsArgs({
+      projectId: "p",
+      sqlInstance: "i",
+      role: "public_staging_role",
+    });
+    expect(args[3]).toBe("public_staging_role");
     expect(args.some((a) => a.startsWith("--database-roles"))).toBe(false);
   });
 });
@@ -48,17 +57,18 @@ describe("revokePublicRoleMembershipsArgs (#633)", () => {
 describe("revokePublicRoleMemberships", () => {
   const install = { projectId: "acme", env: "production", credentials: "operator" } as const;
 
-  it("finds the instance, then revokes", async () => {
+  it("finds the instance, then revokes for both gateway logins (#1329)", async () => {
     const { run, calls } = fake((l) => (l.startsWith("sql instances list") ? ok("pg-1\n") : ok()));
     const r = await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     expect(r).toEqual({
-      id: "public_role database role memberships",
+      id: "gateway logins' database role memberships",
       status: "applied",
-      detail: "no database roles left on pg-1",
+      detail: "public_role and public_staging_role hold no database roles on pg-1",
     });
-    expect(calls[1]).toBe(
+    expect(calls.slice(1)).toEqual([
       "sql users assign-roles public_role --instance=pg-1 --type=BUILT_IN --revoke-existing-roles --project=acme --quiet",
-    );
+      "sql users assign-roles public_staging_role --instance=pg-1 --type=BUILT_IN --revoke-existing-roles --project=acme --quiet",
+    ]);
   });
 
   it("is idempotent: a second run issues the same revoke and succeeds", async () => {
@@ -66,7 +76,7 @@ describe("revokePublicRoleMemberships", () => {
     await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     const again = await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     expect(again.status).toBe("applied");
-    expect(calls[1]).toBe(calls[3] as string);
+    expect(calls.slice(4)).toEqual(calls.slice(1, 3));
   });
 
   it("fails without an instance and never calls the revoke", async () => {

package/src/public-role-isolation.ts

@@ -28,6 +28,9 @@
  * `public_role` is still a member of any role. This step therefore runs
  * BEFORE migrations, on every install pass and every `upgrade`. Idempotent:
  * revoking from a role that has none changes nothing.
+ *
+ * Since #1329 the staging gateway's login `public_staging_role` is an
+ * Admin API user too and gets the same revoke.
  */
 
 import { findSqlInstance } from "./gateway-credentials.js";
@@ -36,16 +39,20 @@ import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud
 import type { EnsureOutcome } from "./runtime-secrets.js";
 import { type GcloudCredentials, lookupFailure } from "./upgrade/gcp-lookup.js";
 
-/** The gcloud call that leaves `public_role` with no database roles. */
+/** The gateway logins the Admin API created, which must hold no database role (#633, #1329). */
+export const GATEWAY_DATABASE_LOGINS = ["public_role", "public_staging_role"] as const;
+
+/** The gcloud call that leaves a gateway login with no database roles. */
 export function revokePublicRoleMembershipsArgs(target: {
   readonly projectId: string;
   readonly sqlInstance: string;
+  readonly role: (typeof GATEWAY_DATABASE_LOGINS)[number];
 }): string[] {
   return [
     "sql",
     "users",
     "assign-roles",
-    "public_role",
+    target.role,
     `--instance=${target.sqlInstance}`,
     "--type=BUILT_IN",
     "--revoke-existing-roles",
@@ -55,8 +62,9 @@ export function revokePublicRoleMembershipsArgs(target: {
 }
 
 /**
- * Revoke every database role the Admin API gave `public_role`. Reports
- * instead of throwing; `failed` names the next step.
+ * Revoke every database role the Admin API gave the gateway logins
+ * ({@link GATEWAY_DATABASE_LOGINS}). Reports instead of throwing; `failed`
+ * names the next step.
  */
 export async function revokePublicRoleMemberships(
   install: {
@@ -67,7 +75,7 @@ export async function revokePublicRoleMemberships(
   deps: { readonly run?: GcloudRunner; readonly sleep?: Sleep } = {},
 ): Promise<EnsureOutcome> {
   const run = deps.run ?? defaultGcloud;
-  const id = "public_role database role memberships";
+  const id = "gateway logins' database role memberships";
   const lookup = await findSqlInstance(install, { run });
   if (lookup.status !== "found") {
     return {
@@ -77,17 +85,23 @@ export async function revokePublicRoleMemberships(
     };
   }
   const sqlInstance = lookup.name;
-  const r = await runWithRetry(
-    run,
-    deps.sleep ?? realSleep,
-    revokePublicRoleMembershipsArgs({ projectId: install.projectId, sqlInstance }),
-  );
-  if (!r.ok) {
-    return {
-      id,
-      status: "failed",
-      error: `gcloud sql users assign-roles public_role --revoke-existing-roles on ${sqlInstance}: ${r.stderr.trim()}. The account running this needs cloudsql.users.update on the project; re-run once it has.`,
-    };
+  for (const role of GATEWAY_DATABASE_LOGINS) {
+    const r = await runWithRetry(
+      run,
+      deps.sleep ?? realSleep,
+      revokePublicRoleMembershipsArgs({ projectId: install.projectId, sqlInstance, role }),
+    );
+    if (!r.ok) {
+      return {
+        id,
+        status: "failed",
+        error: `gcloud sql users assign-roles ${role} --revoke-existing-roles on ${sqlInstance}: ${r.stderr.trim()}. The account running this needs cloudsql.users.update on the project; re-run once it has.`,
+      };
+    }
   }
-  return { id, status: "applied", detail: `no database roles left on ${sqlInstance}` };
+  return {
+    id,
+    status: "applied",
+    detail: `${GATEWAY_DATABASE_LOGINS.join(" and ")} hold no database roles on ${sqlInstance}`,
+  };
 }

package/src/release-contract.ts

@@ -55,6 +55,9 @@ export const INFRA_CONTRACT_PATHS: readonly string[] = [
   "packages/provisioning/src/audit-job-setup.ts",
   // #1217 — the capture job, its service account, bucket and grants.
   "packages/provisioning/src/capture-job-setup.ts",
+  // #1140 — the scheduler tick: its service account, workflow, Cloud
+  // Scheduler job and grants.
+  "packages/provisioning/src/scheduler-setup.ts",
   // #819 — the converge job, its database login and the admin's grant on it.
   "packages/provisioning/src/converge-job-setup.ts",
   // #891 — the edge security headers the stacks attach, and the converge's

package/src/release-manifest.test.ts

@@ -240,6 +240,23 @@ describe("ReleaseManifestSchema", () => {
     const partial = { ...MANIFEST, platformDigests: { admin: d("1"), gateway: d("2") } };
     expect(ReleaseManifestSchema.safeParse(partial).success).toBe(false);
   });
+
+  it("#1328: mcp-auth-proxy is optional (older signed manifests lack it) and checked when present", () => {
+    // The canonical fixture is a pre-#1328 manifest: it names no proxy image.
+    expect("mcp-auth-proxy" in MANIFEST.digests).toBe(false);
+    const digests = { ...MANIFEST.digests, "mcp-auth-proxy": d("4") };
+    const platformDigests = {
+      admin: d("1"),
+      gateway: d("2"),
+      ops: d("3"),
+      "mcp-auth-proxy": d("5"),
+    };
+    const parsed = ReleaseManifestSchema.safeParse({ ...MANIFEST, digests, platformDigests });
+    expect(parsed.success && parsed.data.digests["mcp-auth-proxy"]).toBe(d("4"));
+    expect(parsed.success && parsed.data.platformDigests?.["mcp-auth-proxy"]).toBe(d("5"));
+    const bad = { ...MANIFEST, digests: { ...MANIFEST.digests, "mcp-auth-proxy": "sha256:nope" } };
+    expect(ReleaseManifestSchema.safeParse(bad).success).toBe(false);
+  });
 });
 
 describe("compareImageDigests", () => {
@@ -270,6 +287,14 @@ describe("compareImageDigests", () => {
       { image: "admin", form: "platform", expected: null, actual: d("1") },
     ]);
   });
+
+  it("#1328: a resolved image the manifest does not sign (a pre-proxy release) never matches", () => {
+    expect(compareImageDigests(MANIFEST, { "mcp-auth-proxy": d("4") })).toEqual([
+      { image: "mcp-auth-proxy", form: "index", expected: null, actual: d("4") },
+    ]);
+    const signed = { ...MANIFEST, digests: { ...MANIFEST.digests, "mcp-auth-proxy": d("4") } };
+    expect(compareImageDigests(signed, { "mcp-auth-proxy": d("4") })).toEqual([]);
+  });
 });
 
 describe("assessAutoInstall", () => {

package/src/release-manifest.ts

@@ -35,7 +35,11 @@ import {
   type ReleaseManifest,
 } from "@caelo-cms/shared";
 import { infraStepsText } from "./infra-contract.js";
-import { RELEASE_OIDC_ISSUER, RELEASE_WORKFLOWS_URL } from "./upgrade/release-images.js";
+import {
+  RELEASE_OIDC_ISSUER,
+  RELEASE_WORKFLOWS_URL,
+  releaseImageRef,
+} from "./upgrade/release-images.js";
 
 // The manifest's shape and location live in @caelo-cms/shared (the admin's
 // auto-update scheduler reads them too); re-exported so this module stays
@@ -223,11 +227,58 @@ export interface DigestMismatch {
   readonly image: ReleaseImage;
   /** Which digest differs: the image index, or its linux/amd64 manifest (#1025). */
   readonly form: "index" | "platform";
-  /** The manifest's digest; null when the manifest has no platform digests. */
+  /**
+   * The manifest's digest; null when the manifest names none for this form
+   * (no platform digests, or an image the release predates —
+   * OPTIONAL_RELEASE_IMAGES).
+   */
   readonly expected: string | null;
   readonly actual: string | null;
 }
 
+/** One service's digest-pinned image in the public mirror. */
+export interface ManifestServiceImage {
+  readonly digest: string;
+  readonly imageRef: string;
+}
+
+/**
+ * The images the app-roll moves the Cloud Run services onto, from the signed
+ * manifest's digests — never a registry tag lookup.
+ *
+ * Fails for a manifest without an MCP-Auth-Proxy digest: such a release
+ * predates #1328, and this code rolls three services, so installing it
+ * would leave the proxy on an image of another release.
+ */
+export function manifestServiceImages(m: Pick<ReleaseManifest, "version" | "digests">):
+  | {
+      readonly ok: true;
+      readonly images: Readonly<
+        Record<"admin" | "gateway" | "mcp-auth-proxy", ManifestServiceImage>
+      >;
+    }
+  | { readonly ok: false; readonly error: string } {
+  const proxy = m.digests["mcp-auth-proxy"];
+  if (!proxy) {
+    return {
+      ok: false,
+      error: `the signed manifest of ${m.version} names no mcp-auth-proxy image: that release predates the MCP-Auth-Proxy (#1328) and cannot be installed by this release's upgrader. Install it from a terminal with the version's own CLI (bunx @caelo-cms/provisioning@${m.version} upgrade).`,
+    };
+  }
+  const image = (slug: string, digest: string) => ({
+    digest,
+    imageRef: releaseImageRef(slug, digest),
+  });
+  return {
+    ok: true,
+    images: {
+      admin: image("admin", m.digests.admin),
+      gateway: image("gateway", m.digests.gateway),
+      "mcp-auth-proxy": image("mcp-auth-proxy", proxy),
+    },
+  };
+}
+
 /**
  * Compare the digests a registry resolved for the release's tags with the
  * signed manifest. Only images present in `resolved` (or `resolvedPlatform`)
@@ -246,9 +297,13 @@ export function compareImageDigests(
   const out: DigestMismatch[] = [];
   for (const image of RELEASE_IMAGES) {
     if (image in resolved) {
+      // An image the signed manifest does not name (a release from before
+      // the image existed) can never match: a caller that resolved it is
+      // asking about an image the signature does not cover.
       const actual = resolved[image] ?? null;
-      if (actual !== manifest.digests[image]) {
-        out.push({ image, form: "index", expected: manifest.digests[image], actual });
+      const expected = manifest.digests[image] ?? null;
+      if (actual === null || actual !== expected) {
+        out.push({ image, form: "index", expected, actual });
       }
     }
     if (image in resolvedPlatform) {