@caelo-cms/provisioning 0.11.8 → 0.11.10

package/src/mcp-auth-proxy-setup.ts

@@ -0,0 +1,374 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1328 — the Cloud Run services an upgrade to the MCP-Auth-Proxy release
+ * must find before it plans its rolls, created through gcloud on installs
+ * whose stack predates them (`cms-provision upgrade` and the converge job
+ * never run Pulumi). Run as the operator's or the provisioner's identity,
+ * before the upgrade's plan: each step only ADDS a service, account or grant
+ * that serves no traffic yet, so a failure leaves the running install as it
+ * was (converge release 1 of the hardening plan, #763, is additive).
+ *
+ *   - Both providers: the proxy's own service account and its
+ *     `secretAccessor` on exactly its two secrets — before any service runs
+ *     as it, because Cloud Run checks a revision's secret access at deploy.
+ *   - `gcp-firebase` (E13 a): the visitor gateway's new service
+ *     `caelo-<env>-data-gateway`, a copy of the service that was the gateway
+ *     (same image, env, secrets, VPC, account), so the app-roll can then roll
+ *     it like any other service and turn the old one into the proxy. Copied,
+ *     not built from the contract, so the health baseline sees the release
+ *     that serves today on all three services.
+ *   - `gcp`: the proxy's own service `caelo-<env>-mcp-auth-proxy`, deployed
+ *     with the release's proxy image (there is no older proxy to copy). Its
+ *     load-balancer part is remote-mcp.ts `ensureRemoteMcpEdge`, later in
+ *     the converge.
+ *
+ * Fresh installs get the same from their stack (gcp-firebase) or from the
+ * wizard after the first `pulumi up` (gcp, like the jobs: CLI-owned).
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { gcpSecretId, mcpAuthProxyServiceAccountEmail } from "./gcp-names.js";
+import { type EnsureOutcome, ensureMcpAuthProxyServiceAccount } from "./runtime-secrets.js";
+import {
+  type CloudRunEnvVar,
+  cloudRunServicePrefix,
+  DEFAULT_MCP_AUTH_PROXY_MAX_INSTANCES,
+  fixedCloudRunServiceName,
+  type GcpProvider,
+  MCP_AUTH_PROXY_TIMEOUT_SECONDS,
+  mcpAuthProxyEnvContract,
+  OPERATOR_OAUTH_CLIENT_FILE,
+  remoteMcpIdentity,
+  remoteMcpIdentityEnv,
+  secretFilePath,
+  serviceSecrets,
+} from "./stack-contract.js";
+import { listFlag } from "./stack-converge.js";
+import { lookupFailure, resolveGcpResourceName } from "./upgrade/gcp-lookup.js";
+
+/** The install the services are ensured on. */
+export interface ReleaseServicesTarget {
+  readonly provider: GcpProvider;
+  readonly projectId: string;
+  readonly region: string;
+  /** Pulumi stack name (`production`). */
+  readonly env: string;
+  readonly domain: string;
+  /** The release's digest-pinned MCP-Auth-Proxy image (`…/mcp-auth-proxy@sha256:…`). */
+  readonly mcpAuthProxyImageRef: string;
+}
+
+export interface ReleaseServicesDeps {
+  readonly run?: GcloudRunner;
+  /** Writes a service spec for `gcloud run services replace`; returns its path and a cleanup. */
+  readonly writeSpecFile?: (json: string) => {
+    readonly path: string;
+    readonly cleanup: () => void;
+  };
+}
+
+const NOT_FOUND = /NOT_FOUND|not found|does not exist|could not be found/i;
+
+/** Ensure everything {@link ReleaseServicesTarget} needs; outcomes in order, failures included. */
+export async function ensureReleaseServices(
+  target: ReleaseServicesTarget,
+  deps: ReleaseServicesDeps = {},
+): Promise<EnsureOutcome[]> {
+  const run = deps.run ?? defaultGcloud;
+  const outcomes: EnsureOutcome[] = [];
+  const account = await ensureMcpAuthProxyServiceAccount(target, { run });
+  outcomes.push(account);
+  if (account.status === "failed") return outcomes;
+  outcomes.push(...(await ensureMcpAuthProxySecretAccess(target, run)));
+  if (outcomes.some((o) => o.status === "failed")) return outcomes;
+  outcomes.push(
+    target.provider === "gcp-firebase"
+      ? await ensureDataGatewayService(target, run, deps.writeSpecFile ?? writeTempSpec)
+      : await ensureMcpAuthProxyServiceGcp(target, run),
+  );
+  return outcomes;
+}
+
+/**
+ * `secretAccessor` for the proxy's account on each secret it reads
+ * (stack-contract.ts `serviceSecrets("mcp-auth-proxy")`) and nothing else.
+ * `add-iam-policy-binding` is idempotent; the stack invariants ensure the
+ * same bindings again later in the converge.
+ */
+async function ensureMcpAuthProxySecretAccess(
+  target: Pick<ReleaseServicesTarget, "projectId" | "env">,
+  run: GcloudRunner,
+): Promise<EnsureOutcome[]> {
+  const member = `serviceAccount:${mcpAuthProxyServiceAccountEmail(target.projectId, target.env)}`;
+  const outcomes: EnsureOutcome[] = [];
+  for (const secret of serviceSecrets("mcp-auth-proxy")) {
+    const id = `secretAccessor → MCP-Auth-Proxy on ${secret}`;
+    const r = await run([
+      "secrets",
+      "add-iam-policy-binding",
+      gcpSecretId(target.env, secret),
+      `--project=${target.projectId}`,
+      `--member=${member}`,
+      "--role=roles/secretmanager.secretAccessor",
+      "--condition=None",
+      "--quiet",
+    ]);
+    outcomes.push(
+      r.ok ? { id, status: "present" } : { id, status: "failed", error: r.stderr.trim() },
+    );
+  }
+  return outcomes;
+}
+
+// ===========================================================================
+// gcp-firebase: the data gateway
+// ===========================================================================
+
+/**
+ * The Knative service spec of `serviceJson` (`gcloud run services describe
+ * --format=json`) as a new service named `name`, for `gcloud run services
+ * replace`: the configuration only — image, env, secrets, volumes, VPC,
+ * scaling, account, ingress — without the source's identity (uid, revision
+ * names, status), its tool stamps or its traffic pins.
+ *
+ * @throws when the source is not a gateway image (a re-run must never copy
+ *   the MCP-Auth-Proxy the old service became)
+ */
+export function cloneServiceSpec(serviceJson: string, name: string): string {
+  const svc = JSON.parse(serviceJson) as {
+    apiVersion?: string;
+    kind?: string;
+    metadata?: { labels?: Record<string, string>; annotations?: Record<string, string> };
+    spec?: {
+      template?: {
+        metadata?: { labels?: Record<string, string>; annotations?: Record<string, string> };
+        spec?: { containers?: { image?: string }[] } & Record<string, unknown>;
+      };
+    };
+  };
+  const image = svc.spec?.template?.spec?.containers?.[0]?.image ?? "";
+  if (!/\/gateway[@:]/.test(image)) {
+    throw new Error(
+      `the source service runs ${image || "no image"}, not a Caelo gateway image — the visitor gateway cannot be copied from it`,
+    );
+  }
+  const keepLabels = (labels: Record<string, string> | undefined) =>
+    Object.fromEntries(
+      Object.entries(labels ?? {}).filter(
+        ([k]) =>
+          !k.startsWith("cloud.googleapis.com/") &&
+          !k.startsWith("run.googleapis.com/") &&
+          !k.startsWith("client.knative.dev/") &&
+          !k.startsWith("serving.knative.dev/") &&
+          !k.startsWith("goog-"),
+      ),
+    );
+  // Service-level: only the settings; the rest are server stamps.
+  const KEEP_SERVICE_ANNOTATIONS = [
+    "run.googleapis.com/ingress",
+    "run.googleapis.com/launch-stage",
+  ];
+  const annotations = Object.fromEntries(
+    Object.entries(svc.metadata?.annotations ?? {}).filter(([k]) =>
+      KEEP_SERVICE_ANNOTATIONS.includes(k),
+    ),
+  );
+  const templateAnnotations = Object.fromEntries(
+    Object.entries(svc.spec?.template?.metadata?.annotations ?? {}).filter(
+      ([k]) => k !== "run.googleapis.com/client-name" && k !== "run.googleapis.com/client-version",
+    ),
+  );
+  return JSON.stringify({
+    apiVersion: svc.apiVersion ?? "serving.knative.dev/v1",
+    kind: svc.kind ?? "Service",
+    metadata: { name, labels: keepLabels(svc.metadata?.labels), annotations },
+    spec: {
+      template: {
+        metadata: {
+          labels: keepLabels(svc.spec?.template?.metadata?.labels),
+          annotations: templateAnnotations,
+        },
+        spec: svc.spec?.template?.spec ?? {},
+      },
+      traffic: [{ percent: 100, latestRevision: true }],
+    },
+  });
+}
+
+function writeTempSpec(json: string): { path: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "caelo-service-"));
+  const path = join(dir, "service.json");
+  writeFileSync(path, json, { mode: 0o600 });
+  return { path, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/**
+ * The gcp-firebase data gateway (`caelo-<env>-data-gateway`): present, or
+ * created as a copy of the `caelo-<env>-gateway*` service. Its public invoker
+ * and the admin's `run.viewer` (the Firebase rewrite) follow from the stack
+ * invariants later in the converge.
+ */
+async function ensureDataGatewayService(
+  target: ReleaseServicesTarget,
+  run: GcloudRunner,
+  writeSpecFile: NonNullable<ReleaseServicesDeps["writeSpecFile"]>,
+): Promise<EnsureOutcome> {
+  const name = fixedCloudRunServiceName(target.provider, target.env, "gateway") as string;
+  const id = `Cloud Run service ${name} (the visitor gateway)`;
+  const where = [`--region=${target.region}`, `--project=${target.projectId}`];
+  const existing = await run([
+    "run",
+    "services",
+    "describe",
+    name,
+    ...where,
+    "--format=value(metadata.name)",
+  ]);
+  if (existing.ok) return { id, status: "present" };
+  if (!NOT_FOUND.test(existing.stderr)) {
+    return { id, status: "failed", error: existing.stderr.trim() };
+  }
+  // The source: the service that was the gateway and becomes the proxy.
+  const sourcePrefix = cloudRunServicePrefix(target.provider, target.env, "mcp-auth-proxy");
+  const source = await resolveGcpResourceName(
+    run,
+    "run-service",
+    sourcePrefix,
+    target.projectId,
+    target.region,
+  );
+  if (source.status !== "found") {
+    return {
+      id,
+      status: "failed",
+      error: lookupFailure(source, `${sourcePrefix}* Cloud Run service`, "operator"),
+    };
+  }
+  const described = await run([
+    "run",
+    "services",
+    "describe",
+    source.name,
+    ...where,
+    "--format=json",
+  ]);
+  if (!described.ok) {
+    return { id, status: "failed", error: `describe ${source.name}: ${described.stderr.trim()}` };
+  }
+  let spec: string;
+  try {
+    spec = cloneServiceSpec(described.stdout, name);
+  } catch (e) {
+    return {
+      id,
+      status: "failed",
+      error: `${e instanceof Error ? e.message : String(e)}. Re-run the installer (it creates ${name} from the stack), then upgrade again.`,
+    };
+  }
+  const file = writeSpecFile(spec);
+  try {
+    const replaced = await run(["run", "services", "replace", file.path, ...where, "--quiet"]);
+    return replaced.ok
+      ? { id, status: "applied", detail: `copied from ${source.name}` }
+      : { id, status: "failed", error: replaced.stderr.trim() };
+  } finally {
+    file.cleanup();
+  }
+}
+
+// ===========================================================================
+// gcp: the proxy's service
+// ===========================================================================
+
+/**
+ * The full env the `gcp` proxy is deployed with: its contract plus the
+ * remote-MCP identity it can derive without a lookup (its public origin is
+ * the site's host, the admin's is `admin.<domain>`). The IAP audience is
+ * the admin's alone.
+ */
+function gcpProxyEnv(target: Pick<ReleaseServicesTarget, "env" | "domain">): CloudRunEnvVar[] {
+  const identity = remoteMcpIdentityEnv(
+    remoteMcpIdentity({
+      provider: "gcp",
+      domain: target.domain,
+      // Only the admin's audience uses these; the proxy's env does not.
+      projectNumber: "0",
+      adminBackendServiceId: "0",
+    }),
+  )["mcp-auth-proxy"];
+  return [...mcpAuthProxyEnvContract({ provider: "gcp", env: target.env }), ...identity];
+}
+
+/**
+ * The `gcloud run deploy` argv of the `gcp` proxy: load-balancer-only
+ * ingress (its two hops, stack-contract.ts MCP_AUTH_PROXY_TRUSTED_PROXY_HOPS),
+ * invokable without a Google identity (MCP clients have none), request-based
+ * CPU, no VPC, and its Google sign-in client file as a secret volume.
+ */
+export function gcpProxyDeployArgs(target: ReleaseServicesTarget): string[] {
+  const name = fixedCloudRunServiceName("gcp", target.env, "mcp-auth-proxy") as string;
+  const env = gcpProxyEnv(target);
+  const plain = env.flatMap((e) => ("value" in e ? [`${e.name}=${e.value}`] : []));
+  const secrets = [
+    ...env.flatMap((e) =>
+      "valueSource" in e
+        ? [`${e.name}=${e.valueSource.secretKeyRef.secret}:${e.valueSource.secretKeyRef.version}`]
+        : [],
+    ),
+    `${secretFilePath(OPERATOR_OAUTH_CLIENT_FILE)}=${gcpSecretId(target.env, OPERATOR_OAUTH_CLIENT_FILE.secret)}:${OPERATOR_OAUTH_CLIENT_FILE.version}`,
+  ];
+  return [
+    "run",
+    "deploy",
+    name,
+    `--image=${target.mcpAuthProxyImageRef}`,
+    `--region=${target.region}`,
+    `--project=${target.projectId}`,
+    `--service-account=${mcpAuthProxyServiceAccountEmail(target.projectId, target.env)}`,
+    "--ingress=internal-and-cloud-load-balancing",
+    "--allow-unauthenticated",
+    "--min-instances=0",
+    `--max-instances=${DEFAULT_MCP_AUTH_PROXY_MAX_INSTANCES}`,
+    "--cpu=1",
+    "--memory=512Mi",
+    "--cpu-throttling",
+    `--timeout=${MCP_AUTH_PROXY_TIMEOUT_SECONDS}`,
+    listFlag("--set-env-vars", plain),
+    listFlag("--set-secrets", secrets),
+    "--quiet",
+  ];
+}
+
+/**
+ * The `gcp` proxy service: present, or deployed. Deployed once; the
+ * app-roll moves it onto each release's image after that.
+ */
+export async function ensureMcpAuthProxyServiceGcp(
+  target: ReleaseServicesTarget,
+  run: GcloudRunner,
+): Promise<EnsureOutcome> {
+  const name = fixedCloudRunServiceName("gcp", target.env, "mcp-auth-proxy") as string;
+  const id = `Cloud Run service ${name} (the MCP-Auth-Proxy)`;
+  const existing = await run([
+    "run",
+    "services",
+    "describe",
+    name,
+    `--region=${target.region}`,
+    `--project=${target.projectId}`,
+    "--format=value(metadata.name)",
+  ]);
+  if (existing.ok) return { id, status: "present" };
+  if (!NOT_FOUND.test(existing.stderr)) {
+    return { id, status: "failed", error: existing.stderr.trim() };
+  }
+  const deployed = await run(gcpProxyDeployArgs(target));
+  return deployed.ok
+    ? { id, status: "applied" }
+    : { id, status: "failed", error: deployed.stderr.trim() };
+}

package/src/mcp-iap-stacks.test.ts

@@ -48,7 +48,7 @@ describe.each(["gcp", "gcp-firebase"])("%s stack — MCP through IAP", (provider
       env: "production",
       domain: "d.com",
       region: "r",
-      databaseUrls: databaseUrls("10.0.0.3"),
+      databaseUrls: databaseUrls("db1.p-label.europe-west1.sql-psa.goog"),
     });
     expect(env).toContainEqual({
       name: "CAELO_MCP_IAP_SERVICE_ACCOUNT",

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/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,7 +201,7 @@ 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",
     );
   });
 
@@ -322,7 +322,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 +352,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/pool-budget-stacks.test.ts

@@ -63,7 +63,7 @@ describe("stack pool budgets at the default config", () => {
         adminMaxInstances: 5,
         gatewayMaxInstances: 100,
       }),
-    ).toThrow(/Raise maxConnections/);
+    ).toThrow(/CONNECTION LIMIT, #1338/);
   });
 });
 

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) {

package/src/remote-mcp-stack-config.test.ts

@@ -15,7 +15,7 @@ import {
   adminEnvContract,
   type CloudRunEnvVar,
   databaseUrls,
-  gatewayEnvContract,
+  mcpAuthProxyEnvContract,
   parseRemoteMcpIdentityConfig,
   REMOTE_MCP_ENV,
   REMOTE_MCP_IDENTITY_CONFIG,
@@ -41,24 +41,28 @@ const contractInputs = {
   domain: "viu.one",
   region: "europe-west1",
   stagingHost: "staging.viu.one",
-  databaseUrls: databaseUrls("10.153.0.3"),
+  databaseUrls: databaseUrls("db1.p-label.europe-west1.sql-psa.goog"),
 } as const;
 const contract = {
   admin: adminEnvContract({
     ...contractInputs,
     firebaseSiteId: "caelo-production-site-eb4697",
-    gatewayService: "caelo-production-gateway-6da3bb0",
+    gatewayService: "caelo-production-data-gateway",
   }),
-  gateway: gatewayEnvContract(contractInputs),
+  // #1328 — the broker's identity env is the MCP-Auth-Proxy's, the service
+  // that was the gateway (E13 a), so its URL is the old gateway's.
+  "mcp-auth-proxy": mcpAuthProxyEnvContract(contractInputs),
 };
 
+type IdentitySlug = keyof typeof contract;
+
 /** The env a stack declares for one service, given the config value. */
-function declared(slug: "admin" | "gateway", config: string | undefined): CloudRunEnvVar[] {
+function declared(slug: IdentitySlug, config: string | undefined): CloudRunEnvVar[] {
   return [...contract[slug], ...remoteMcpIdentityStackEnv(config)[slug]];
 }
 
 /** The live services after an installer run plus its old gcloud post-step: gcloud reorders. */
-function live(slug: "admin" | "gateway"): CloudRunEnvVar[] {
+function live(slug: IdentitySlug): CloudRunEnvVar[] {
   return [...contract[slug], ...remoteMcpIdentityEnv(identity)[slug]].reverse();
 }
 
@@ -89,7 +93,11 @@ describe("remote-MCP identity as stack config (#1082)", () => {
 
   it("declares nothing while the config is unset (a fresh install's first up)", () => {
     expect(parseRemoteMcpIdentityConfig(undefined)).toBeNull();
-    expect(remoteMcpIdentityStackEnv(undefined)).toEqual({ admin: [], gateway: [] });
+    expect(remoteMcpIdentityStackEnv(undefined)).toEqual({
+      admin: [],
+      gateway: [],
+      "mcp-auth-proxy": [],
+    });
   });
 
   it("refuses a corrupt or foreign value loudly instead of dropping the vars", () => {
@@ -111,9 +119,11 @@ describe("remote-MCP identity as stack config (#1082)", () => {
         .admin.map((v) => v.name)
         .sort(),
     ).toEqual(Object.values(REMOTE_MCP_ENV).sort());
+    // #1328 — the visitor gateway carries none of it.
+    expect(remoteMcpIdentityStackEnv(serializeRemoteMcpIdentity(identity)).gateway).toEqual([]);
   });
 
-  it.each(["admin", "gateway"] as const)(
+  it.each(["admin", "mcp-auth-proxy"] as const)(
     "%s: with the config the CLI writes, a refreshed plan removes and changes nothing",
     (slug) => {
       const plan = envPlan(declared(slug, serializeRemoteMcpIdentity(identity)), live(slug));
@@ -128,7 +138,7 @@ describe("remote-MCP identity as stack config (#1082)", () => {
       "CAELO_IAP_AUDIENCE",
       "CAELO_MCP_PUBLIC_URL",
     ]);
-    expect(envPlan(declared("gateway", undefined), live("gateway")).removed).toEqual([
+    expect(envPlan(declared("mcp-auth-proxy", undefined), live("mcp-auth-proxy")).removed).toEqual([
       "CAELO_ADMIN_URL",
       "CAELO_MCP_PUBLIC_URL",
     ]);