@caelo-cms/provisioning 0.11.9 → 0.11.11

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

@@ -0,0 +1,305 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1328 — the services an upgrade to the MCP-Auth-Proxy release creates on
+ * installs whose stack predates them (mcp-auth-proxy-setup.ts): the proxy's
+ * account and its two secret grants, the gcp-firebase data gateway copied
+ * from the old gateway service, and the gcp proxy service.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { GcloudResult } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import {
+  cloneServiceSpec,
+  ensureReleaseServices,
+  gcpProxyDeployArgs,
+  type ReleaseServicesTarget,
+} from "./mcp-auth-proxy-setup.js";
+import { MCP_AUTH_PROXY_TIMEOUT_SECONDS } from "./stack-contract.js";
+
+const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+
+/** Answers by the longest matching command prefix; anything else is an error. */
+function fakeGcloud(answers: Record<string, GcloudResult>) {
+  const calls: string[] = [];
+  const run: GcloudRunner = async (args) => {
+    const line = args.join(" ");
+    calls.push(line);
+    const key = Object.keys(answers)
+      .filter((k) => line.startsWith(k))
+      .sort((a, b) => b.length - a.length)[0];
+    return key ? (answers[key] as GcloudResult) : fail(`unexpected: ${line}`);
+  };
+  return { run, calls };
+}
+
+const IMAGE = "europe-west1-docker.pkg.dev/caelo-website/caelo-cms-images";
+const PROXY_SA = "caelo-production-mcp-proxy-sa@acme.iam.gserviceaccount.com";
+
+const firebase: ReleaseServicesTarget = {
+  provider: "gcp-firebase",
+  projectId: "acme",
+  region: "europe-west1",
+  env: "production",
+  domain: "acme.com",
+  mcpAuthProxyImageRef: `${IMAGE}/mcp-auth-proxy@sha256:${"c".repeat(64)}`,
+};
+const gcp: ReleaseServicesTarget = { ...firebase, provider: "gcp" };
+
+/** The old gateway service as `gcloud run services describe --format=json` shows it. */
+const OLD_GATEWAY = {
+  apiVersion: "serving.knative.dev/v1",
+  kind: "Service",
+  metadata: {
+    name: "caelo-production-gateway-bbb",
+    namespace: "123456",
+    uid: "u-1",
+    resourceVersion: "AAY",
+    generation: 42,
+    creationTimestamp: "2026-01-01T00:00:00Z",
+    selfLink:
+      "/apis/serving.knative.dev/v1/namespaces/123456/services/caelo-production-gateway-bbb",
+    labels: {
+      "cloud.googleapis.com/location": "europe-west1",
+      "goog-terraform-provisioned": "true",
+      team: "web",
+    },
+    annotations: {
+      "run.googleapis.com/ingress": "all",
+      "run.googleapis.com/ingress-status": "all",
+      "serving.knative.dev/creator": "someone@acme.com",
+      "serving.knative.dev/lastModifier": "someone@acme.com",
+      "run.googleapis.com/operation-id": "op-1",
+      "run.googleapis.com/client-name": "gcloud",
+    },
+  },
+  spec: {
+    template: {
+      metadata: {
+        name: "caelo-production-gateway-bbb-00042-abc",
+        labels: {
+          "client.knative.dev/nonce": "n",
+          "run.googleapis.com/startupProbeType": "Default",
+        },
+        annotations: {
+          "autoscaling.knative.dev/maxScale": "10",
+          "run.googleapis.com/network-interfaces": '[{"network":"caelo-production-vpc"}]',
+          "run.googleapis.com/vpc-access-egress": "private-ranges-only",
+          "run.googleapis.com/client-name": "gcloud",
+          "run.googleapis.com/client-version": "500.0.0",
+        },
+      },
+      spec: {
+        serviceAccountName: "caelo-production-gateway-sa@acme.iam.gserviceaccount.com",
+        timeoutSeconds: 3600,
+        containers: [
+          {
+            image: `${IMAGE}/gateway@sha256:${"b".repeat(64)}`,
+            env: [
+              { name: "CAELO_PROVIDER", value: "gcp-firebase" },
+              {
+                name: "PUBLIC_DATABASE_PASSWORD",
+                valueFrom: {
+                  secretKeyRef: { name: "caelo-production-public-role-password", key: "latest" },
+                },
+              },
+            ],
+          },
+        ],
+      },
+    },
+    traffic: [{ revisionName: "caelo-production-gateway-bbb-00041-old", percent: 100 }],
+  },
+  status: {
+    url: "https://caelo-production-gateway-bbb-xyz.a.run.app",
+    latestReadyRevisionName: "x",
+  },
+};
+
+describe("cloneServiceSpec", () => {
+  const clone = JSON.parse(
+    cloneServiceSpec(JSON.stringify(OLD_GATEWAY), "caelo-production-data-gateway"),
+  );
+
+  it("names the copy and drops the source's identity, status and tool stamps", () => {
+    expect(clone.metadata).toEqual({
+      name: "caelo-production-data-gateway",
+      labels: { team: "web" },
+      annotations: { "run.googleapis.com/ingress": "all" },
+    });
+    expect(clone.status).toBeUndefined();
+    expect(clone.spec.template.metadata.name).toBeUndefined();
+    expect(clone.spec.template.metadata.labels).toEqual({});
+    expect(clone.spec.template.metadata.annotations).toEqual({
+      "autoscaling.knative.dev/maxScale": "10",
+      "run.googleapis.com/network-interfaces": '[{"network":"caelo-production-vpc"}]',
+      "run.googleapis.com/vpc-access-egress": "private-ranges-only",
+    });
+  });
+
+  it("keeps the configuration — image, env, secrets, account, timeout — and routes all traffic to the new revision", () => {
+    expect(clone.spec.template.spec).toEqual(OLD_GATEWAY.spec.template.spec);
+    expect(clone.spec.traffic).toEqual([{ percent: 100, latestRevision: true }]);
+    expect(clone.apiVersion).toBe("serving.knative.dev/v1");
+    expect(clone.kind).toBe("Service");
+  });
+
+  it("refuses to copy a service that runs no gateway image (the proxy the old service became)", () => {
+    const proxy = structuredClone(OLD_GATEWAY);
+    (proxy.spec.template.spec.containers[0] as { image: string }).image =
+      `${IMAGE}/mcp-auth-proxy@sha256:${"c".repeat(64)}`;
+    expect(() => cloneServiceSpec(JSON.stringify(proxy), "x")).toThrow("not a Caelo gateway image");
+  });
+});
+
+describe("gcpProxyDeployArgs", () => {
+  it("deploys the proxy load-balancer-only, public, at zero instances, without a VPC, with its two secrets", () => {
+    const args = gcpProxyDeployArgs(gcp);
+    expect(args.slice(0, 3)).toEqual(["run", "deploy", "caelo-production-mcp-auth-proxy"]);
+    expect(args).toContain(`--image=${gcp.mcpAuthProxyImageRef}`);
+    expect(args).toContain(`--service-account=${PROXY_SA}`);
+    expect(args).toContain("--ingress=internal-and-cloud-load-balancing");
+    expect(args).toContain("--allow-unauthenticated");
+    expect(args).toContain("--min-instances=0");
+    expect(args).toContain("--cpu-throttling");
+    expect(args).toContain(`--timeout=${MCP_AUTH_PROXY_TIMEOUT_SECONDS}`);
+    expect(args.some((a) => a.startsWith("--network") || a.startsWith("--vpc"))).toBe(false);
+    expect(args).toContain(
+      "--set-env-vars=CAELO_PROVIDER=gcp,CAELO_REMOTE_MCP=available,CAELO_TRUSTED_PROXY_HOPS=2,CAELO_OPERATOR_OAUTH_CLIENT_FILE=/secrets/operator-oauth-client/client.json,CAELO_ADMIN_URL=https://admin.acme.com,CAELO_MCP_PUBLIC_URL=https://acme.com",
+    );
+    expect(args).toContain(
+      "--set-secrets=CAELO_MCP_OAUTH_SEAL_KEY=caelo-production-mcp-oauth-seal-key:latest,/secrets/operator-oauth-client/client.json=caelo-production-operator-oauth-client:latest",
+    );
+    // Nothing that would hand it a database: no URL, no password.
+    expect(args.join(" ")).not.toMatch(/DATABASE|public-role-password|postgres-password/);
+  });
+});
+
+/** The account and its two grants, as a fresh install answers them. */
+const accountAndGrants = {
+  [`iam service-accounts describe ${PROXY_SA}`]: fail("NOT_FOUND: does not exist"),
+  "iam service-accounts create caelo-production-mcp-proxy-sa": ok(),
+  "secrets add-iam-policy-binding": ok(),
+};
+
+describe("ensureReleaseServices", () => {
+  it("gcp-firebase: creates the account, grants exactly its two secrets and copies the old gateway", async () => {
+    const written: string[] = [];
+    let cleaned = false;
+    const { run, calls } = fakeGcloud({
+      ...accountAndGrants,
+      "run services describe caelo-production-data-gateway": fail("NOT_FOUND: could not be found"),
+      "run services list": ok("caelo-production-gateway-bbb\n"),
+      "run services describe caelo-production-gateway-bbb": ok(JSON.stringify(OLD_GATEWAY)),
+      "run services replace": ok(),
+    });
+    const outcomes = await ensureReleaseServices(firebase, {
+      run,
+      writeSpecFile: (json) => {
+        written.push(json);
+        return {
+          path: "/tmp/spec.json",
+          cleanup: () => {
+            cleaned = true;
+          },
+        };
+      },
+    });
+    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "present", "applied"]);
+    expect(calls.filter((c) => c.startsWith("secrets add-iam-policy-binding"))).toEqual([
+      `secrets add-iam-policy-binding caelo-production-mcp-oauth-seal-key --project=acme --member=serviceAccount:${PROXY_SA} --role=roles/secretmanager.secretAccessor --condition=None --quiet`,
+      `secrets add-iam-policy-binding caelo-production-operator-oauth-client --project=acme --member=serviceAccount:${PROXY_SA} --role=roles/secretmanager.secretAccessor --condition=None --quiet`,
+    ]);
+    // Never a project role.
+    expect(calls.some((c) => c.startsWith("projects add-iam-policy-binding"))).toBe(false);
+    // The copy's source is the service the proxy prefix finds — the old gateway.
+    expect(calls).toContain(
+      "run services list --region europe-west1 --project acme --filter metadata.name~^caelo-production-gateway --format=value(metadata.name)",
+    );
+    expect(JSON.parse(written[0] as string).metadata.name).toBe("caelo-production-data-gateway");
+    expect(calls).toContain(
+      "run services replace /tmp/spec.json --region=europe-west1 --project=acme --quiet",
+    );
+    expect(cleaned).toBe(true);
+    // No new image is deployed: the copy runs what serves today.
+    expect(calls.some((c) => c.startsWith("run deploy"))).toBe(false);
+  });
+
+  it("gcp-firebase: a data gateway that exists already is left alone", async () => {
+    const { run, calls } = fakeGcloud({
+      [`iam service-accounts describe ${PROXY_SA}`]: ok(`${PROXY_SA}\n`),
+      "secrets add-iam-policy-binding": ok(),
+      "run services describe caelo-production-data-gateway": ok("caelo-production-data-gateway\n"),
+    });
+    const outcomes = await ensureReleaseServices(firebase, { run });
+    expect(outcomes.map((o) => o.status)).toEqual(["present", "present", "present", "present"]);
+    expect(calls.some((c) => c.includes("replace") || c.includes("create"))).toBe(false);
+  });
+
+  it("gcp-firebase: refuses to copy when the old service already runs the proxy image", async () => {
+    const proxy = structuredClone(OLD_GATEWAY);
+    (proxy.spec.template.spec.containers[0] as { image: string }).image =
+      `${IMAGE}/mcp-auth-proxy@sha256:${"c".repeat(64)}`;
+    const { run, calls } = fakeGcloud({
+      ...accountAndGrants,
+      "run services describe caelo-production-data-gateway": fail("NOT_FOUND: could not be found"),
+      "run services list": ok("caelo-production-gateway-bbb\n"),
+      "run services describe caelo-production-gateway-bbb": ok(JSON.stringify(proxy)),
+    });
+    const outcomes = await ensureReleaseServices(firebase, { run });
+    const last = outcomes.at(-1);
+    expect(last?.status).toBe("failed");
+    expect(last?.error).toContain("Re-run the installer");
+    expect(calls.some((c) => c.startsWith("run services replace"))).toBe(false);
+  });
+
+  it("gcp: deploys the proxy service with the release's image when it is missing", async () => {
+    const { run, calls } = fakeGcloud({
+      ...accountAndGrants,
+      "run services describe caelo-production-mcp-auth-proxy": fail(
+        "NOT_FOUND: could not be found",
+      ),
+      "run deploy caelo-production-mcp-auth-proxy": ok(),
+    });
+    const outcomes = await ensureReleaseServices(gcp, { run });
+    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "present", "applied"]);
+    expect(calls).toContain(gcpProxyDeployArgs(gcp).join(" "));
+  });
+
+  it("gcp: an existing proxy service is not deployed again", async () => {
+    const { run, calls } = fakeGcloud({
+      [`iam service-accounts describe ${PROXY_SA}`]: ok(`${PROXY_SA}\n`),
+      "secrets add-iam-policy-binding": ok(),
+      "run services describe caelo-production-mcp-auth-proxy": ok(
+        "caelo-production-mcp-auth-proxy\n",
+      ),
+    });
+    const outcomes = await ensureReleaseServices(gcp, { run });
+    expect(outcomes.at(-1)?.status).toBe("present");
+    expect(calls.some((c) => c.startsWith("run deploy"))).toBe(false);
+  });
+
+  it("stops before any service when a grant fails (Cloud Run would refuse the revision)", async () => {
+    const { run, calls } = fakeGcloud({
+      ...accountAndGrants,
+      "secrets add-iam-policy-binding caelo-production-operator-oauth-client": fail(
+        "PERMISSION_DENIED: secretmanager.secrets.setIamPolicy",
+      ),
+    });
+    const outcomes = await ensureReleaseServices(gcp, { run });
+    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "failed"]);
+    expect(calls.some((c) => c.startsWith("run "))).toBe(false);
+  });
+
+  it("stops at once when the account cannot be read", async () => {
+    const { run, calls } = fakeGcloud({
+      [`iam service-accounts describe ${PROXY_SA}`]: fail("PERMISSION_DENIED"),
+    });
+    const outcomes = await ensureReleaseServices(firebase, { run });
+    expect(outcomes).toHaveLength(1);
+    expect(outcomes[0]?.status).toBe("failed");
+    expect(calls).toHaveLength(1);
+  });
+});

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",