@caelo-cms/provisioning 0.11.13 → 0.11.14

package/src/gcp-url-map.test.ts

@@ -46,6 +46,7 @@ describe("gcp stack URL map (Pulumi mocks)", () => {
       {
         domain: "example.com",
         adminDomain: "admin.example.com",
+        stagingHost: "staging.example.com",
         staticBackend: "bucket-id",
         gatewayBackend: "gateway-id",
         adminBackend: "admin-id",
@@ -61,6 +62,8 @@ describe("gcp stack URL map (Pulumi mocks)", () => {
     expect(hostRules).toEqual([
       { hosts: ["example.com"], pathMatcher: PUBLIC_PATH_MATCHER },
       { hosts: ["admin.example.com"], pathMatcher: "admin" },
+      // #1330 — the staging host, its matcher moved to the staging gateway by the CLI.
+      { hosts: ["staging.example.com"], pathMatcher: "staging" },
     ]);
     expect(pathMatchers).toEqual([
       {
@@ -70,7 +73,20 @@ describe("gcp stack URL map (Pulumi mocks)", () => {
         pathRules: [{ paths: [...GCP_GATEWAY_PATHS], service: "gateway-id" }],
       },
       { name: "admin", defaultService: "admin-id" },
+      // #1330 — fails closed until the CLI routes it to the staging gateway:
+      // a redirect, never a backend (above all not the static bucket).
+      {
+        name: "staging",
+        defaultUrlRedirect: {
+          hostRedirect: "example.com",
+          pathRedirect: "/",
+          httpsRedirect: true,
+          redirectResponseCode: "FOUND",
+          stripQuery: true,
+        },
+      },
     ]);
+    expect(JSON.stringify(pathMatchers?.[2])).not.toContain("bucket-id");
     expect(registered.find((r) => r.name === "caelo-production-url-map")?.type).toBe(
       "gcp:compute/uRLMap:URLMap",
     );
@@ -115,16 +131,24 @@ describe("gcp stack URL map (Pulumi mocks)", () => {
     const { SITE_URL_MAP_IGNORE_CHANGES, siteUrlMapArgs, PUBLIC_PATH_MATCHER } = await import(
       "./gcp-url-map.js"
     );
-    expect(SITE_URL_MAP_IGNORE_CHANGES).toEqual(["pathMatchers[0].pathRules"]);
+    expect(SITE_URL_MAP_IGNORE_CHANGES).toEqual([
+      "pathMatchers[0].pathRules",
+      // #1330 — the staging matcher's target is the CLI's.
+      "pathMatchers[2].defaultService",
+      "pathMatchers[2].defaultUrlRedirect",
+    ]);
     const args = siteUrlMapArgs({
       domain: "d",
       adminDomain: "a.d",
+      stagingHost: "s.d",
       staticBackend: "s",
       gatewayBackend: "g",
       adminBackend: "a",
     });
-    // Index 0 must stay the public matcher, or the ignore would hit the admin's.
+    // Index 0 must stay the public matcher, or the ignore would hit the admin's;
+    // index 2 the staging one (the CLI writes it last, staging-gateway-setup.ts).
     expect((args.pathMatchers as { name: string }[])[0]?.name).toBe(PUBLIC_PATH_MATCHER);
+    expect((args.pathMatchers as { name: string }[])[2]?.name).toBe("staging");
   });
 });
 

package/src/gcp-url-map.ts

@@ -26,16 +26,28 @@ import type * as pulumi from "@pulumi/pulumi";
 /** Name of the site host's path matcher. */
 export const PUBLIC_PATH_MATCHER = "public";
 
+/** #1330 — name of the staging host's path matcher (gcp-names.ts stagingGatewayEdgeNames). */
+export const STAGING_PATH_MATCHER = "staging";
+
 /**
  * The URL map's `ignoreChanges`: the public path matcher (index 0, see
- * {@link siteUrlMapArgs}) holds the admin-managed redirect rules.
+ * {@link siteUrlMapArgs}) holds the admin-managed redirect rules, and the
+ * staging matcher's (index 2) target is the CLI's: the stack creates it as a
+ * redirect, and staging-gateway-setup.ts ensureStagingGatewayEdge (#1330)
+ * replaces that with the staging gateway's backend once it exists.
  */
-export const SITE_URL_MAP_IGNORE_CHANGES: readonly string[] = ["pathMatchers[0].pathRules"];
+export const SITE_URL_MAP_IGNORE_CHANGES: readonly string[] = [
+  "pathMatchers[0].pathRules",
+  "pathMatchers[2].defaultService",
+  "pathMatchers[2].defaultUrlRedirect",
+];
 
 /** Inputs of {@link siteUrlMapArgs}. */
 export interface SiteUrlMapInputs {
   readonly domain: string;
   readonly adminDomain: string;
+  /** #1330 — the protected staging site's host. */
+  readonly stagingHost: string;
   readonly staticBackend: pulumi.Input<string>;
   readonly gatewayBackend: pulumi.Input<string>;
   readonly adminBackend: pulumi.Input<string>;
@@ -43,9 +55,17 @@ export interface SiteUrlMapInputs {
 
 /**
  * The URL map's arguments: the site host to the static bucket with `/api/*`
- * to the gateway; the admin host to the IAP-gated admin. The public path
- * matcher comes first — {@link SITE_URL_MAP_IGNORE_CHANGES} addresses it by
- * index.
+ * to the gateway; the admin host to the IAP-gated admin; (#1330) the staging
+ * host, every path, to the staging gateway. The public path matcher comes
+ * first and the staging one third — {@link SITE_URL_MAP_IGNORE_CHANGES}
+ * addresses them by index.
+ *
+ * The staging matcher fails closed until the staging gateway's backend
+ * exists (it is the CLI's, created after the first `up`): it serves nothing
+ * at all, it redirects every staging request to the live site's home page.
+ * Never a backend — above all never the static bucket — so a failed edge
+ * step can never show a file on the staging host. The CLI then routes it to
+ * the staging gateway, and the stack leaves it there.
  */
 export function siteUrlMapArgs(i: SiteUrlMapInputs): gcp.compute.URLMapArgs {
   return {
@@ -53,6 +73,7 @@ export function siteUrlMapArgs(i: SiteUrlMapInputs): gcp.compute.URLMapArgs {
     hostRules: [
       { hosts: [i.domain], pathMatcher: PUBLIC_PATH_MATCHER },
       { hosts: [i.adminDomain], pathMatcher: "admin" },
+      { hosts: [i.stagingHost], pathMatcher: STAGING_PATH_MATCHER },
     ],
     pathMatchers: [
       {
@@ -68,6 +89,16 @@ export function siteUrlMapArgs(i: SiteUrlMapInputs): gcp.compute.URLMapArgs {
         name: "admin",
         defaultService: i.adminBackend,
       },
+      {
+        name: STAGING_PATH_MATCHER,
+        defaultUrlRedirect: {
+          hostRedirect: i.domain,
+          pathRedirect: "/",
+          httpsRedirect: true,
+          redirectResponseCode: "FOUND",
+          stripQuery: true,
+        },
+      },
     ],
   };
 }

package/src/index.test.ts

@@ -18,7 +18,7 @@ describe("Caddyfile generator", () => {
     const out = generateCaddyfile({
       ownerEmail: "owner@example.com",
       publicSiteRoot: "/srv/caelo/output/production/current",
-      stagingSiteRoot: "/srv/caelo/output/staging/current",
+      stagingGatewayUpstream: "caelo-staging-gateway:8091",
       tls: "acme",
       adminUpstream: "caelo-admin:5173",
       gatewayUpstream: "caelo-gateway:8090",
@@ -46,7 +46,7 @@ describe("Caddyfile generator", () => {
     const out = generateCaddyfile({
       ownerEmail: "x@y.z",
       publicSiteRoot: "/srv/caelo/output/production/current",
-      stagingSiteRoot: "/srv/caelo/output/staging/current",
+      stagingGatewayUpstream: "caelo-staging-gateway:8091",
       tls: "acme",
       adminUpstream: "caelo-admin:5173",
       gatewayUpstream: "caelo-gateway:8090",
@@ -62,7 +62,7 @@ describe("Caddy cache policy for content-hashed assets", () => {
   const spec = {
     ownerEmail: "owner@example.com",
     publicSiteRoot: "/srv/caelo/output/production/current",
-    stagingSiteRoot: "/srv/caelo/output/staging/current",
+    stagingGatewayUpstream: "caelo-staging-gateway:8091",
     tls: "acme",
     adminUpstream: "caelo-admin:5173",
     gatewayUpstream: "caelo-gateway:8090",
@@ -156,6 +156,8 @@ describe("docker-compose generator", () => {
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
+      stagingHost: "staging.example.com",
+      stagingGateSecret: "g".repeat(64),
       anthropicApiKey: "sk-ant-…",
       diskSize: "20Gi",
       images: RELEASE_IMAGES,
@@ -179,6 +181,8 @@ describe("docker-compose generator", () => {
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
+      stagingHost: "staging.example.com",
+      stagingGateSecret: "g".repeat(64),
       diskSize: "20Gi",
       images: RELEASE_IMAGES,
       ports: { http: 80, https: 443 },
@@ -205,6 +209,8 @@ describe("docker-compose generator", () => {
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
+      stagingHost: "staging.example.com",
+      stagingGateSecret: "g".repeat(64),
       diskSize: "1Gi",
       images: RELEASE_IMAGES,
       ports: { http: 80, https: 443 },

package/src/infra-contract.test.ts

@@ -20,8 +20,8 @@ describe("infrastructure contract steps", () => {
     );
   });
 
-  it("is at 19: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8), converge job (9), remote MCP (10), Google sign-in (11), project-level sign-in client (12), edge security headers (13), capture job (14), database verify-full TLS (15), MCP-Auth-Proxy (16), staging database (17), scheduler tick (18), scheduler tick as JSON (19)", () => {
-    expect(INFRA_CONTRACT_VERSION).toBe(19);
+  it("is at 20: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8), converge job (9), remote MCP (10), Google sign-in (11), project-level sign-in client (12), edge security headers (13), capture job (14), database verify-full TLS (15), MCP-Auth-Proxy (16), staging database (17), scheduler tick (18), scheduler tick as JSON (19), staging gateway (20)", () => {
+    expect(INFRA_CONTRACT_VERSION).toBe(20);
     expect(INFRA_CONTRACT_STEPS[3]).toContain("#633");
     expect(INFRA_CONTRACT_STEPS[4]).toContain("#587");
     expect(INFRA_CONTRACT_STEPS[5]).toContain("#635");
@@ -39,6 +39,7 @@ describe("infrastructure contract steps", () => {
     expect(INFRA_CONTRACT_STEPS[17]).toContain("#1329");
     expect(INFRA_CONTRACT_STEPS[18]).toContain("#1140");
     expect(INFRA_CONTRACT_STEPS[19]).toContain("JSON");
+    expect(INFRA_CONTRACT_STEPS[20]).toContain("#1330");
   });
 
   it("lists the pending steps oldest first", () => {
@@ -49,6 +50,6 @@ describe("infrastructure contract steps", () => {
   });
 
   it("names a version a newer release added by number", () => {
-    expect(infraStepsText(19, 20)).toBe("infrastructure step 20 (see that release's notes)");
+    expect(infraStepsText(20, 21)).toBe("infrastructure step 21 (see that release's notes)");
   });
 });

package/src/infra-contract.ts

@@ -22,7 +22,7 @@
  * whose app-roll references infrastructure an install does not have yet fails
  * at roll time, after migrations ran.
  */
-export const INFRA_CONTRACT_VERSION = 19;
+export const INFRA_CONTRACT_VERSION = 20;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -153,6 +153,22 @@ export const INFRA_CONTRACT_VERSION = 19;
 //  19 — the scheduler workflow's tick is a JSON POST. Without a content type
 //       SvelteKit refused every tick of contract 18 with 403, so no periodic
 //       work ran. The workflow source is only deployed by a converge.
+//  20 — #1330/#1331: the staging gateway (converge release 2 of the gateway
+//       hardening). Its service account (secretAccessor on
+//       public-staging-role-password only, log/metric writer), its Cloud Run
+//       service `caelo-<env>-staging-gateway` (the gateway's image,
+//       CAELO_GATEWAY_ENVIRONMENT=staging, allUsers invoker: the gate is its
+//       own), object viewer on the staging bucket — on gcp-firebase a new
+//       private bucket, which the admin may write (CAELO_STAGING_BUCKET) —
+//       and its edge: on gcp-firebase a second Hosting site with one `**`
+//       rewrite and the staging host as its custom domain, the old Cloud Run
+//       domain mapping deleted; on gcp a serverless NEG, backend service,
+//       managed certificate and URL-map host rule. The live gateway loses
+//       CAELO_STAGING_GATE_SECRET (the gate key reaches the staging gateway
+//       through the staging projection) and the MCP-Auth-Proxy its interim
+//       forwarder. New service, account, bucket, IAM and edge resources the
+//       in-cloud upgrader may not create, and the app-roll rolls four
+//       services from now on.
 
 /**
  * What each contract version adds, in operator terms — the upgrader's
@@ -179,6 +195,7 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   17: "the staging site's own database and its gateway login, kept apart from the live data (#1329)",
   18: "the scheduler tick that runs the admin's periodic work and plugin workers every few minutes: its service account, workflow and Cloud Scheduler job, and its IAP access (#1140)",
   19: "the scheduler tick sent as a JSON request, because the admin refused every tick before (#1140)",
+  20: "the staging gateway that serves the staged site behind the staging gate on every address: its service, service account and grants, the private staging bucket, and the staging host's own route (a second Firebase Hosting site, or a host rule and certificate on the load balancer); the live gateway no longer holds the staging gate key (#1330, #1331)",
 };
 
 /**

package/src/lifecycle.ts

@@ -20,7 +20,6 @@ import { join } from "node:path";
 import { provisioningUpgradeCommand } from "@caelo-cms/shared";
 import { cancel, confirm, isCancel, log, note, select, spinner } from "@clack/prompts";
 import { bold, cyan, dim, green, red, yellow } from "kleur/colors";
-import { stagingDomainState } from "./admin-domain.js";
 import { activeAccount, checkGcloudAuth, gcloud } from "./gcloud.js";
 import { type GcloudRunner, realSleep } from "./gcloud-retry.js";
 import { GCP_STACK_ENV } from "./gcp-names.js";
@@ -70,12 +69,7 @@ import {
   resolveBackend,
 } from "./state-backend.js";
 import { acquireStateLock, realSyncGcloud, releaseOnSignal } from "./state-store.js";
-import {
-  type AppRollPlan,
-  type ReleaseImage,
-  ROLL_ORDER,
-  type RollSlug,
-} from "./upgrade/app-roll.js";
+import type { AppRollPlan, RollSlug } from "./upgrade/app-roll.js";
 import { restoreCommand, takeSqlBackup } from "./upgrade/backup.js";
 import { findServiceUrl, lookupFailure, resolveGcpResourceName } from "./upgrade/gcp-lookup.js";
 import { createIapHealthProbe, type HealthProbe } from "./upgrade/health.js";
@@ -85,12 +79,10 @@ import {
   canonicalReleaseTag,
   ensureCosignAvailable,
   fetchLatestReleaseTag,
-  RELEASE_REGISTRY,
-  releaseImageRef,
   releaseTag,
   releaseVersionForDigest,
   resolveOpsImageRef,
-  resolveTagDigest,
+  resolveReleaseImages,
   verifyCosignAll,
 } from "./upgrade/release-images.js";
 import { clackReporter } from "./upgrade/reporter.js";
@@ -464,32 +456,6 @@ export async function upgradeCommand(opts: UpgradeOpts = {}): Promise<void> {
   );
 }
 
-/**
- * Resolve both release images' digests from the public registry. Via the
- * registry's anonymous V2 API, not `gcloud artifacts docker tags list`: that
- * needs IAM read on Caelo's registry project, which operators don't have.
- */
-async function resolveReleaseImages(
-  tag: string,
-): Promise<{ ok: true; images: Record<RollSlug, ReleaseImage> } | { ok: false; error: string }> {
-  const images: Partial<Record<RollSlug, ReleaseImage>> = {};
-  for (const slug of ROLL_ORDER) {
-    const res = await resolveTagDigest(slug, tag);
-    if (!res.ok) {
-      const r = RELEASE_REGISTRY;
-      return {
-        ok: false,
-        error:
-          `Couldn't resolve image digest for ${slug}:${tag}: the public registry returned ${res.reason}.\n` +
-          `Verify the tag exists at https://${r.region}-docker.pkg.dev/${r.project}/${r.repo}/${slug}:${tag}\n` +
-          "(latest releases live at https://github.com/caelo-cms/caelo-cms/releases — pass --version vX.Y.Z to pin.)",
-      };
-    }
-    images[slug] = { digest: res.digest, imageRef: releaseImageRef(slug, res.digest) };
-  }
-  return { ok: true, images: images as Record<RollSlug, ReleaseImage> };
-}
-
 /**
  * `upgrade`'s step of the keyless provisioner migration (#696,
  * provisioner-identity.ts) — a converge step (upgrade/converge.ts runs it
@@ -686,22 +652,12 @@ async function upgradeLockedInstall(
   // #696 — upgrade never moves Pulumi state; it says how to.
   const stateNotice = localStateNotice(meta);
   if (stateNotice) note(stateNotice, "Pulumi state is on this machine");
-  if (ok && provider === "gcp-firebase") {
-    // #650 — staging builds render the staging host; the gateway serves it
-    // once it is mapped. Only an install without the mapping is told to run
-    // `staging-domain enable`.
-    const staging = await stagingDomainState({ projectId, region, stagingHost, run });
-    if (staging.status === "mapped") {
-      log.info(`Protected staging site: https://${stagingHost}/`);
-    } else {
-      const unknown =
-        staging.status === "unknown"
-          ? ` (could not check whether ${bold(stagingHost)} is mapped: ${staging.reason})`
-          : "";
-      log.info(
-        `Protected staging site: run ${bold("cms-provision staging-domain enable")} once to serve the staging host${unknown} (it maps the host the admin uses — ${bold(stagingHost)} unless changed there —, turns on password protection, prints the login and the DNS record). Host and access: admin → Settings → Domains / Staging access.`,
-      );
-    }
+  if (ok) {
+    // #1330 — the converge routed the staging host to the staging gateway
+    // and printed its DNS records (Settings → Updates shows them as well).
+    log.info(
+      `Protected staging site: https://${stagingHost}/ — served by the staging gateway behind the staging gate. Password protection and other access: admin → Settings → Staging access (or ${bold("cms-provision staging-domain enable")}).`,
+    );
   }
   return ok;
 }

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

@@ -44,8 +44,17 @@ const firebase: ReleaseServicesTarget = {
   region: "europe-west1",
   env: "production",
   domain: "acme.com",
+  stagingHost: "staging.acme.com",
   mcpAuthProxyImageRef: `${IMAGE}/mcp-auth-proxy@sha256:${"c".repeat(64)}`,
+  gatewayImageRef: `${IMAGE}/gateway@sha256:${"b".repeat(64)}`,
 };
+
+/**
+ * The outcomes of the #1328 part; the staging gateway's (#1330) come after
+ * them and are covered by staging-gateway-setup.test.ts.
+ */
+const proxyPart = (outcomes: readonly { id: string; status: string }[]) =>
+  outcomes.filter((o) => !/staging gateway/.test(o.id)).map((o) => o.status);
 const gcp: ReleaseServicesTarget = { ...firebase, provider: "gcp" };
 
 /** The old gateway service as `gcloud run services describe --format=json` shows it. */
@@ -210,7 +219,7 @@ describe("ensureReleaseServices", () => {
         };
       },
     });
-    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "present", "applied"]);
+    expect(proxyPart(outcomes)).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`,
@@ -237,7 +246,7 @@ describe("ensureReleaseServices", () => {
       "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(proxyPart(outcomes)).toEqual(["present", "present", "present", "present"]);
     expect(calls.some((c) => c.includes("replace") || c.includes("create"))).toBe(false);
   });
 
@@ -267,7 +276,7 @@ describe("ensureReleaseServices", () => {
       "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(proxyPart(outcomes)).toEqual(["applied", "present", "present", "applied"]);
     expect(calls).toContain(gcpProxyDeployArgs(gcp).join(" "));
   });
 
@@ -280,7 +289,7 @@ describe("ensureReleaseServices", () => {
       ),
     });
     const outcomes = await ensureReleaseServices(gcp, { run });
-    expect(outcomes.at(-1)?.status).toBe("present");
+    expect(proxyPart(outcomes).at(-1)).toBe("present");
     expect(calls.some((c) => c.startsWith("run deploy"))).toBe(false);
   });
 
@@ -292,7 +301,7 @@ describe("ensureReleaseServices", () => {
       ),
     });
     const outcomes = await ensureReleaseServices(gcp, { run });
-    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "failed"]);
+    expect(proxyPart(outcomes)).toEqual(["applied", "present", "failed"]);
     expect(calls.some((c) => c.startsWith("run "))).toBe(false);
   });
 
@@ -320,7 +329,7 @@ describe("ensureReleaseServices", () => {
         pauses.push(ms);
       },
     });
-    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "present", "present"]);
+    expect(proxyPart(outcomes)).toEqual(["applied", "present", "present", "present"]);
     expect(pauses.length).toBe(2);
     expect(calls.filter((c) => c.startsWith("secrets add-iam-policy-binding"))).toHaveLength(2);
   });

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

@@ -49,6 +49,7 @@ import {
   serviceSecrets,
 } from "./stack-contract.js";
 import { listFlag } from "./stack-converge.js";
+import { ensureStagingGatewayFromLiveGateway } from "./staging-gateway-setup.js";
 import { lookupFailure, resolveGcpResourceName } from "./upgrade/gcp-lookup.js";
 
 /** The install the services are ensured on. */
@@ -61,8 +62,15 @@ export interface ReleaseServicesTarget {
   readonly domain: string;
   /** The release's digest-pinned MCP-Auth-Proxy image (`…/mcp-auth-proxy@sha256:…`). */
   readonly mcpAuthProxyImageRef: string;
+  /** #1330 — the release's digest-pinned gateway image, which the staging gateway runs too. */
+  readonly gatewayImageRef: string;
+  /** #1330 — the staging host (install.json `stagingDomain`). */
+  readonly stagingHost: string;
 }
 
+/** What the `gcp` proxy's own service needs. */
+export type ProxyServiceTarget = Omit<ReleaseServicesTarget, "gatewayImageRef" | "stagingHost">;
+
 export interface ReleaseServicesDeps {
   readonly run?: GcloudRunner;
   /** Writes a service spec for `gcloud run services replace`; returns its path and a cleanup. */
@@ -95,6 +103,10 @@ export async function ensureReleaseServices(
       ? await ensureDataGatewayService(target, run, deps.writeSpecFile ?? writeTempSpec)
       : await ensureMcpAuthProxyServiceGcp(target, run),
   );
+  if (outcomes.some((o) => o.status === "failed")) return outcomes;
+  outcomes.push(
+    ...(await ensureStagingGatewayFromLiveGateway(target, { run, sleep: deps.sleep ?? realSleep })),
+  );
   return outcomes;
 }
 
@@ -317,7 +329,7 @@ function gcpProxyEnv(target: Pick<ReleaseServicesTarget, "env" | "domain">): Clo
  * 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[] {
+export function gcpProxyDeployArgs(target: ProxyServiceTarget): 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}`] : []));
@@ -356,7 +368,7 @@ export function gcpProxyDeployArgs(target: ReleaseServicesTarget): string[] {
  * app-roll moves it onto each release's image after that.
  */
 export async function ensureMcpAuthProxyServiceGcp(
-  target: ReleaseServicesTarget,
+  target: ProxyServiceTarget,
   run: GcloudRunner,
 ): Promise<EnsureOutcome> {
   const name = fixedCloudRunServiceName("gcp", target.env, "mcp-auth-proxy") as string;

package/src/release-manifest.ts

@@ -254,7 +254,7 @@ export function manifestServiceImages(m: Pick<ReleaseManifest, "version" | "dige
   | {
       readonly ok: true;
       readonly images: Readonly<
-        Record<"admin" | "gateway" | "mcp-auth-proxy", ManifestServiceImage>
+        Record<"admin" | "gateway" | "staging-gateway" | "mcp-auth-proxy", ManifestServiceImage>
       >;
     }
   | { readonly ok: false; readonly error: string } {
@@ -274,6 +274,8 @@ export function manifestServiceImages(m: Pick<ReleaseManifest, "version" | "dige
     images: {
       admin: image("admin", m.digests.admin),
       gateway: image("gateway", m.digests.gateway),
+      // #1330 — the staging gateway runs the live gateway's image.
+      "staging-gateway": image("gateway", m.digests.gateway),
       "mcp-auth-proxy": image("mcp-auth-proxy", proxy),
     },
   };

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

@@ -96,6 +96,7 @@ describe("remote-MCP identity as stack config (#1082)", () => {
     expect(remoteMcpIdentityStackEnv(undefined)).toEqual({
       admin: [],
       gateway: [],
+      "staging-gateway": [],
       "mcp-auth-proxy": [],
     });
   });

package/src/remote-mcp.test.ts

@@ -413,6 +413,7 @@ const firebase: RemoteMcpTarget = {
   services: {
     admin: "caelo-production-admin-aaa",
     gateway: "caelo-production-data-gateway",
+    "staging-gateway": "caelo-production-staging-gateway",
     "mcp-auth-proxy": "caelo-production-gateway-bbb",
   },
 };
@@ -606,7 +607,10 @@ describe("checkRemoteMcpIdentityEnv (#1082)", () => {
       ),
     });
     const r = await checkRemoteMcpIdentityEnv(firebase, identity, { run });
-    expect(r).toEqual({ ok: true, drift: { admin: [], gateway: [], "mcp-auth-proxy": [] } });
+    expect(r).toEqual({
+      ok: true,
+      drift: { admin: [], gateway: [], "staging-gateway": [], "mcp-auth-proxy": [] },
+    });
     expect(calls.some((c) => c.startsWith("run services update"))).toBe(false);
   });
 

package/src/remote-mcp.ts

@@ -345,8 +345,17 @@ export async function checkRemoteMcpIdentityEnv(
 ): Promise<RemoteMcpResult<{ readonly drift: Record<CloudRunSlug, EnvChange[]> }>> {
   const run = deps.run ?? defaultGcloud;
   const desired = remoteMcpIdentityEnv(identity);
-  const drift: Record<CloudRunSlug, EnvChange[]> = { admin: [], gateway: [], "mcp-auth-proxy": [] };
+  const drift: Record<CloudRunSlug, EnvChange[]> = {
+    admin: [],
+    gateway: [],
+    "staging-gateway": [],
+    "mcp-auth-proxy": [],
+  };
   for (const slug of CLOUD_RUN_SLUGS) {
+    // Nothing to check where the identity names nothing (the visitor
+    // gateways), and the staging gateway is the CLI's (#1330), not the
+    // stack's: it may not exist yet right after a first `up`.
+    if (desired[slug].length === 0) continue;
     const described = await describeService(target, target.services[slug], run);
     if (!described.ok) return described;
     const plan = planEnvUpdate(liveContainerEnv(described.json), desired[slug]);

package/src/runtime-secrets.test.ts

@@ -323,7 +323,12 @@ describe("rotateRuntimeSecret", () => {
     projectId: "acme",
     region: "europe-west1",
     env: "production",
-    services: { admin: "adm-svc", gateway: "gw-svc", "mcp-auth-proxy": "px-svc" },
+    services: {
+      admin: "adm-svc",
+      gateway: "gw-svc",
+      "staging-gateway": "stg-svc",
+      "mcp-auth-proxy": "px-svc",
+    },
     sqlInstance: "caelo-production-pg-1",
   };
   const ref = (name: string, secret: string, version = "latest") => ({
@@ -347,6 +352,10 @@ describe("rotateRuntimeSecret", () => {
     "run services describe gw-svc": [
       service([ref("PUBLIC_DATABASE_PASSWORD", "public-role-password")]),
     ],
+    // #1330 — the staging gateway reads its own login password.
+    "run services describe stg-svc": [
+      service([ref("PUBLIC_DATABASE_PASSWORD", "public-staging-role-password")]),
+    ],
     // #1328 — the proxy reads none of the rotatable database secrets.
     "run services describe px-svc": [
       service([ref("CAELO_MCP_OAUTH_SEAL_KEY", "mcp-oauth-seal-key")]),

package/src/runtime-secrets.ts

@@ -30,6 +30,8 @@ import {
   gcpSecretId,
   mcpAuthProxyServiceAccountEmail,
   mcpAuthProxyServiceAccountId,
+  stagingGatewayServiceAccountEmail,
+  stagingGatewayServiceAccountId,
 } from "./gcp-names.js";
 import {
   CLI_GENERATED_SECRETS,
@@ -123,6 +125,25 @@ export function ensureMcpAuthProxyServiceAccount(
   );
 }
 
+/**
+ * #1330 — create the staging gateway's run SA unless it exists. Its rights:
+ * `secretAccessor` on `public-staging-role-password` (runtimeSecretBindings),
+ * the log and metric writer, and object viewer on the staging bucket
+ * (staging-gateway-setup.ts) — nothing of the live site's.
+ */
+export function ensureStagingGatewayServiceAccount(
+  install: { readonly projectId: string; readonly env: string },
+  deps: RuntimeDeps = {},
+): Promise<EnsureOutcome> {
+  return ensureServiceAccount(
+    install.projectId,
+    stagingGatewayServiceAccountId(install.env),
+    stagingGatewayServiceAccountEmail(install.projectId, install.env),
+    `Caelo ${install.env} staging gateway`,
+    deps,
+  );
+}
+
 async function ensureServiceAccount(
   projectId: string,
   accountId: string,

package/src/self-hosted-backup.test.ts

@@ -109,12 +109,12 @@ describe("backupSelfHosted", () => {
     expect(out).toEqual({ ok: true, path: to });
     expect(probe(r.calls.map((c) => c.cmd))).toEqual([
       "exec -T postgres pg_isready -U caelo",
-      "stop caelo-admin caelo-gateway",
+      "stop caelo-admin caelo-gateway caelo-staging-gateway",
       "exec -T postgres pg_dumpall -U caelo --globals-only",
       "exec -T postgres pg_dump -U caelo -Fc cms_admin",
       "exec -T postgres pg_dump -U caelo -Fc cms_public",
       "run --rm --no-deps -T --entrypoint tar caelo-admin -C / -cf - srv/caelo data/media",
-      "up -d caelo-admin caelo-gateway",
+      "up -d caelo-admin caelo-gateway caelo-staging-gateway",
       "exec -T caelo-admin bun -e <probe>",
       "exec -T caelo-gateway bun -e <probe>",
     ]);
@@ -146,7 +146,9 @@ describe("backupSelfHosted", () => {
       ...quiet,
     });
     expect(out.ok).toBe(false);
-    expect(r.calls.map((c) => c.cmd)).toContain("up -d caelo-admin caelo-gateway");
+    expect(r.calls.map((c) => c.cmd)).toContain(
+      "up -d caelo-admin caelo-gateway caelo-staging-gateway",
+    );
   });
 
   it("refuses when Postgres is not running and changes nothing", async () => {
@@ -194,7 +196,7 @@ describe("restoreSelfHosted", () => {
     const out = await restoreSelfHosted(archive, restoreDeps(r));
     expect(out.ok).toBe(true);
     expect(probe(r.calls.map((c) => c.cmd))).toEqual([
-      "stop caelo-admin caelo-gateway",
+      "stop caelo-admin caelo-gateway caelo-staging-gateway",
       "up -d --wait postgres",
       "exec -T postgres psql -U caelo -d postgres -v ON_ERROR_STOP=1 -c DROP DATABASE IF EXISTS cms_admin WITH (FORCE) -c DROP DATABASE IF EXISTS cms_public WITH (FORCE)",
       "<converge roles>",