@caelo-cms/provisioning 0.11.13 → 0.11.14

package/src/cli.ts

@@ -64,6 +64,7 @@ import {
   COMPOSE_ADMIN_UPSTREAM,
   COMPOSE_GATEWAY_UPSTREAM,
   COMPOSE_MCP_AUTH_PROXY_UPSTREAM,
+  COMPOSE_STAGING_GATEWAY_UPSTREAM,
   type ComposeImages,
   composeProjectName,
   generateDockerCompose,
@@ -111,6 +112,14 @@ interface CaeloConfig {
    * generated before P18 still load — emitConfig() back-fills if missing.
    */
   caeloSecretKek?: string;
+  /**
+   * #650 / #1330 — the staging gate's key (32 hex bytes): signs "Open
+   * staging" links, derives the crawler credentials. Generated once and
+   * persisted here; never re-minted, or every crawler credential stops
+   * working. The admin gets it as CAELO_STAGING_GATE_SECRET and publishes it
+   * to the staging gateway through the staging projection.
+   */
+  stagingGateSecret?: string;
   /**
    * #613 — one password per application role. Optional in the type so
    * config.json files from before still load; `up` back-fills them and
@@ -319,7 +328,7 @@ function writeCaddyfile(cfg: CaeloConfig, extraDomains: CaddyDomainSpec[]): void
     ownerEmail: cfg.ownerEmail,
     tls: cfg.tls,
     publicSiteRoot: `${SITE_OUTPUT_ROOT}/output/production/current`,
-    stagingSiteRoot: `${SITE_OUTPUT_ROOT}/output/staging/current`,
+    stagingGatewayUpstream: COMPOSE_STAGING_GATEWAY_UPSTREAM,
     // Caddy runs in its own container: the Compose service names, never
     // localhost (#707).
     adminUpstream: COMPOSE_ADMIN_UPSTREAM,
@@ -359,6 +368,16 @@ function renderCompose(cfg: CaeloConfig, images: ComposeImages): string {
     throw new Error("config has no rolePasswords — run `cms-provision up`");
   }
   if (!cfg.caeloSecretKek) throw new Error("config has no caeloSecretKek — run `cms-provision up`");
+  // #1330 — back-filled once for installs from before the staging gate
+  // came to self-hosted; persisted before anything uses it.
+  if (!cfg.stagingGateSecret) {
+    cfg.stagingGateSecret = randomSecret(32);
+    saveConfig(cfg);
+  }
+  if (!cfg.stagingDomain) {
+    cfg.stagingDomain = defaultStagingHost(cfg.domain);
+    saveConfig(cfg);
+  }
   if (!cfg.ports || !cfg.composeProject) {
     throw new Error(
       "config has no ports / composeProject — they are back-filled on load; this is a bug",
@@ -369,6 +388,8 @@ function renderCompose(cfg: CaeloConfig, images: ComposeImages): string {
   for (const line of ensureSelfHostedDbTls(CAELO_DIR)) console.log(`  database TLS: ${line}`);
   return generateDockerCompose({
     domain: cfg.domain,
+    stagingHost: cfg.stagingDomain,
+    stagingGateSecret: cfg.stagingGateSecret,
     postgresPassword: cfg.postgresPassword,
     rolePasswords: cfg.rolePasswords,
     caeloSecretKek: cfg.caeloSecretKek,
@@ -1420,7 +1441,7 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     selectInstall,
     writeMetadata,
   } = await import("./install-state.js");
-  const { enableAdminDomain, enableStagingDomain } = await import("./admin-domain.js");
+  const { enableAdminDomain } = await import("./admin-domain.js");
   // Guessing among several installs could map the domain in the wrong project.
   const selected = selectInstall(
     listInstalls().filter((m) => m.projectId),
@@ -1448,13 +1469,10 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     const requested = arg("staging-domain");
     const { normalizeStagingHost, stagingHostProblem } = await import("@caelo-cms/shared");
     let adminHost: string | null = null;
-    if (!requested && meta.provider === "gcp-firebase" && meta.projectId && meta.region) {
+    const google = googleAdminTarget(meta);
+    if (!requested && google) {
       const { inspectStagingAdmin } = await import("./staging-admin.js");
-      const inspected = await inspectStagingAdmin({
-        provider: "gcp-firebase",
-        projectId: meta.projectId,
-        region: meta.region,
-      });
+      const inspected = await inspectStagingAdmin(google);
       if (!inspected.ok) {
         console.error(
           `${command}: could not read the admin's staging host: ${inspected.error}\n` +
@@ -1465,11 +1483,10 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
       adminHost = inspected.value.stagingHost;
     }
     const host = requested ?? adminHost ?? installStagingHost(meta);
-    const problem = stagingHostProblem(
-      host,
-      { liveHosts: [meta.domain, `www.${meta.domain}`], adminHosts: [`admin.${meta.domain}`] },
-      { provider: meta.provider },
-    );
+    const problem = stagingHostProblem(host, {
+      liveHosts: [meta.domain, `www.${meta.domain}`],
+      adminHosts: [`admin.${meta.domain}`],
+    });
     if (problem) {
       console.error(
         requested
@@ -1498,23 +1515,20 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     );
     process.exit(1);
   }
+  if (kind === "staging") {
+    await serveStagingHost(meta, command, retry, { rotatePassword, showPassword });
+    return;
+  }
   if (meta.provider !== "gcp-firebase") {
     console.log(
-      kind === "admin"
-        ? meta.provider === "gcp"
-          ? `Nothing to do: on gcp the load balancer already serves admin.${meta.domain}.`
-          : `admin-domain is for gcp-firebase installs; this one is ${meta.provider}.`
-        : meta.provider === "self-hosted"
-          ? `Recorded staging host ${installStagingHost(meta)}; Caddy serves it after \`cms-provision regenerate-caddy\`.`
-          : `staging-domain is for gcp-firebase installs; on ${meta.provider} the protected staging domain is not available yet (issue #650 follow-up).`,
+      meta.provider === "gcp"
+        ? `Nothing to do: on gcp the load balancer already serves admin.${meta.domain}.`
+        : `admin-domain is for gcp-firebase installs; this one is ${meta.provider}.`,
     );
     return;
   }
   const target = { projectId: meta.projectId, region: meta.region, domain: meta.domain };
-  const r =
-    kind === "admin"
-      ? await enableAdminDomain(target)
-      : await enableStagingDomain({ ...target, stagingHost: installStagingHost(meta) });
+  const r = await enableAdminDomain(target);
   if (r.status === "failed") {
     console.error(`${command}: ${r.error}`);
     process.exit(1);
@@ -1527,56 +1541,7 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     );
     process.exit(3);
   }
-  const mappedTo = kind === "admin" ? "the admin" : "the gateway (protected staging site)";
-  console.log(
-    `${r.hostname} ${r.created ? "is now mapped" : "was already mapped"} to ${mappedTo}.`,
-  );
-  if (kind === "staging") {
-    // #678 — the operator's decision reaches the admin here: the host is
-    // set there, password protection is switched on the first time, and
-    // the password is printed once (never stored by the CLI).
-    const { applyStagingAdmin, describeStagingApply } = await import("./staging-admin.js");
-    const applied = await applyStagingAdmin(
-      { provider: "gcp-firebase", projectId: meta.projectId, region: meta.region },
-      {
-        host: r.hostname,
-        ...(rotatePassword ? { rotateBasicAuth: true } : {}),
-        ...(showPassword ? { revealBasicAuth: true } : {}),
-      },
-    );
-    if (!applied.ok) {
-      console.error(
-        `${command}: ${r.hostname} is mapped, but the admin could not be updated: ${applied.error}\n` +
-          `Run \`${retry}\` again once that is fixed (it is idempotent).`,
-      );
-      process.exit(5);
-    }
-    // Prints the staging basic-auth password ON PURPOSE (#678): the operator
-    // asked for it to be shown once; it is never written to disk or logs.
-    console.log(describeStagingApply(applied.value).join("\n"));
-    // #1058 — and the admin's CAELO_STAGING_HOST, so the provisioned value
-    // agrees with install.json and the stored host (the converge job
-    // refuses an install whose records and admin disagree). After the
-    // provision call: the update starts a new admin revision.
-    const { setAdminStagingHostEnv } = await import("./admin-domain.js");
-    const env = await setAdminStagingHostEnv({
-      projectId: meta.projectId,
-      region: meta.region,
-      stagingHost: r.hostname,
-    });
-    if (env.status === "failed") {
-      console.error(
-        `${command}: ${r.hostname} is mapped and stored in the admin, but its CAELO_STAGING_HOST could not be updated: ${env.error}\n` +
-          `Run \`${retry}\` again once that is fixed (it is idempotent).`,
-      );
-      process.exit(5);
-    }
-    if (env.status === "set") {
-      console.log(
-        `The admin (${env.service}) now runs with CAELO_STAGING_HOST=${r.hostname}${env.previous ? ` (was ${env.previous})` : ""}.`,
-      );
-    }
-  }
+  console.log(`${r.hostname} ${r.created ? "is now mapped" : "was already mapped"} to the admin.`);
   if (r.records.length === 0) {
     console.log(
       `Google has not published the DNS records yet; run \`cms-provision ${command} enable\` again in a minute.`,
@@ -1591,10 +1556,106 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     region: meta.region,
   });
   if (!waited) process.exit(4);
+  console.log(`Admin login: https://${r.hostname}/login`);
+}
+
+/** The admin-internal target of a Google Cloud install, or null for another provider. */
+function googleAdminTarget(
+  meta: import("./install-state.js").InstallMetadata,
+): import("./staging-admin.js").StagingAdminTarget | null {
+  if (!meta.projectId || !meta.region) return null;
+  if (meta.provider === "gcp-firebase") {
+    return { provider: "gcp-firebase", projectId: meta.projectId, region: meta.region };
+  }
+  if (meta.provider === "gcp") {
+    return { provider: "gcp", projectId: meta.projectId, domain: meta.domain };
+  }
+  return null;
+}
+
+/**
+ * #1330 — `staging-domain enable` on a Google Cloud install: route the
+ * staging host to the staging gateway (staging-gateway-setup.ts — the same
+ * step every converge runs), tell the admin the host and switch on password
+ * protection the first time (#678, printing the password once), keep the
+ * admin's CAELO_STAGING_HOST in step (#1058), and print the DNS records.
+ */
+async function serveStagingHost(
+  meta: import("./install-state.js").InstallMetadata,
+  command: string,
+  retry: string,
+  opts: { readonly rotatePassword: boolean; readonly showPassword: boolean },
+): Promise<void> {
+  const { installStagingHost } = await import("./install-state.js");
+  const host = installStagingHost(meta);
+  const google = googleAdminTarget(meta);
+  if (!google || !meta.projectId || !meta.region) {
+    console.log(
+      meta.provider === "self-hosted"
+        ? `Recorded staging host ${host}; the staging gateway serves it behind Caddy after \`cms-provision regenerate-caddy\`.`
+        : `On ${meta.provider} the protected staging site is not available yet: it needs the staging gateway this provider does not run yet (#749 / #750).`,
+    );
+    return;
+  }
+  const { ensureStagingGatewayEdge } = await import("./staging-gateway-setup.js");
+  const { GCP_STACK_ENV } = await import("./gcp-names.js");
+  const edge = await ensureStagingGatewayEdge({
+    provider: meta.provider as "gcp" | "gcp-firebase",
+    projectId: meta.projectId,
+    region: meta.region,
+    env: GCP_STACK_ENV,
+    domain: meta.domain,
+    stagingHost: host,
+  });
+  for (const line of edge.done) console.log(`  ${line}`);
+  if (!edge.ok) {
+    console.error(
+      `${command}: ${host} could not be routed to the staging gateway: ${edge.error}\nRun \`${retry}\` again once that is fixed (it is idempotent); \`cms-provision upgrade\` sets up the staging gateway itself if it is missing.`,
+    );
+    process.exit(1);
+  }
+  const { applyStagingAdmin, describeStagingApply } = await import("./staging-admin.js");
+  const applied = await applyStagingAdmin(google, {
+    host,
+    ...(opts.rotatePassword ? { rotateBasicAuth: true } : {}),
+    ...(opts.showPassword ? { revealBasicAuth: true } : {}),
+  });
+  if (!applied.ok) {
+    console.error(
+      `${command}: ${host} is routed to the staging gateway, but the admin could not be updated: ${applied.error}\nRun \`${retry}\` again once that is fixed (it is idempotent).`,
+    );
+    process.exit(5);
+  }
+  // Prints the staging basic-auth password ON PURPOSE (#678): the operator
+  // asked for it to be shown once; it is never written to disk or logs.
+  console.log(describeStagingApply(applied.value).join("\n"));
+  const { setAdminStagingHostEnv } = await import("./admin-domain.js");
+  const env = await setAdminStagingHostEnv({
+    projectId: meta.projectId,
+    region: meta.region,
+    stagingHost: host,
+  });
+  if (env.status === "failed") {
+    console.error(
+      `${command}: ${host} is routed and stored in the admin, but its CAELO_STAGING_HOST could not be updated: ${env.error}\nRun \`${retry}\` again once that is fixed (it is idempotent).`,
+    );
+    process.exit(5);
+  }
+  if (env.status === "set") {
+    console.log(
+      `The admin (${env.service}) now runs with CAELO_STAGING_HOST=${host}${env.previous ? ` (was ${env.previous})` : ""}.`,
+    );
+  }
+  if (edge.dnsRecords.length > 0) {
+    const width = Math.max(...edge.dnsRecords.map((d) => d.name.length));
+    console.log(
+      `\nSet these DNS records at your registrar (if you have not already; Settings → Updates shows them too):\n${edge.dnsRecords
+        .map((d) => `  ${d.name.padEnd(width)}  ${d.type.padEnd(5)}  ${d.value}`)
+        .join("\n")}`,
+    );
+  }
   console.log(
-    kind === "admin"
-      ? `Admin login: https://${r.hostname}/login`
-      : `Protected staging site: https://${r.hostname}/`,
+    `Protected staging site: https://${host}/ (its certificate is issued once the records resolve)`,
   );
 }
 

package/src/compose.ts

@@ -45,6 +45,8 @@ import {
   publicSiteUrl,
   REMOTE_MCP_MODE,
   REMOTE_MCP_MODE_ENV,
+  STAGING_GATEWAY_TRUSTED_PROXY_HOPS,
+  STAGING_STORAGE_ENV,
   TRUSTED_PROXY_HOPS_ENV,
 } from "./stack-contract.js";
 import { ghcrRepository, isImageDigest, type ReleaseService } from "./upgrade/release-images.js";
@@ -120,6 +122,18 @@ export const MEDIA_ROOT = "/data/media";
 /** The gateway's HTTP port inside the Compose network. */
 export const COMPOSE_GATEWAY_PORT = 8090;
 
+/** #1330 — the staging gateway's HTTP port inside the Compose network. */
+export const COMPOSE_STAGING_GATEWAY_PORT = 8091;
+
+/** #1330 — the Compose service name of the staging gateway. */
+export const COMPOSE_STAGING_GATEWAY_SERVICE = "caelo-staging-gateway";
+
+/**
+ * #1330 — where the staging gateway sees the staged builds: the admin's
+ * `output/staging` (host `.caelo/output/output/staging`), mounted read-only.
+ */
+export const STAGING_GATEWAY_STORAGE_DIR = "/srv/staging";
+
 /** #1328 — the MCP-Auth-Proxy's HTTP port inside the Compose network. */
 export const COMPOSE_MCP_AUTH_PROXY_PORT = 8095;
 
@@ -130,12 +144,17 @@ export const COMPOSE_MCP_AUTH_PROXY_SERVICE = "caelo-mcp-auth-proxy";
  * The Compose services that touch the databases — what `backup` and
  * `restore` stop while they read or rewrite them. Workers run inside the
  * admin (CLAUDE.md §11.B Tier 5); there is no orchestrator or runner
- * service. The MCP-Auth-Proxy (#1328) is deliberately not here: it holds no
+ * service. The staging gateway (#1330) holds the staging database's login.
+ * The MCP-Auth-Proxy (#1328) is deliberately not here: it holds no
  * database login, so it keeps running, and a release from before it has no
  * such service for `up` to start. Its health is checked wherever the
  * install starts (self-hosted-start.ts) or rolls (self-hosted-upgrade.ts).
  */
-export const COMPOSE_APP_SERVICES = ["caelo-admin", "caelo-gateway"] as const;
+export const COMPOSE_APP_SERVICES = [
+  "caelo-admin",
+  "caelo-gateway",
+  COMPOSE_STAGING_GATEWAY_SERVICE,
+] as const;
 
 /**
  * Where Caddy reaches the admin and the gateway: their Compose service
@@ -144,6 +163,7 @@ export const COMPOSE_APP_SERVICES = ["caelo-admin", "caelo-gateway"] as const;
  */
 export const COMPOSE_ADMIN_UPSTREAM = `caelo-admin:${COMPOSE_ADMIN_PORT}`;
 export const COMPOSE_GATEWAY_UPSTREAM = `caelo-gateway:${COMPOSE_GATEWAY_PORT}`;
+export const COMPOSE_STAGING_GATEWAY_UPSTREAM = `${COMPOSE_STAGING_GATEWAY_SERVICE}:${COMPOSE_STAGING_GATEWAY_PORT}`;
 export const COMPOSE_MCP_AUTH_PROXY_UPSTREAM = `${COMPOSE_MCP_AUTH_PROXY_SERVICE}:${COMPOSE_MCP_AUTH_PROXY_PORT}`;
 
 /**
@@ -226,6 +246,15 @@ export interface RolePasswords {
 
 export interface ComposeSpec {
   readonly domain: string;
+  /** #650 — the staging site's host; seeds the admin's staging host setting. */
+  readonly stagingHost: string;
+  /**
+   * #650 / #1330 — the staging gate's key (`.caelo/config.json`
+   * `stagingGateSecret`, generated once): signs "Open staging" links and
+   * derives the crawler credentials. Admin only; the admin publishes it to
+   * the staging gateway through the staging projection.
+   */
+  readonly stagingGateSecret: string;
   /** The Postgres superuser's; only the database container uses it. */
   readonly postgresPassword: string; // generated by cms-provision; persisted in .caelo/secrets
   readonly rolePasswords: RolePasswords;
@@ -378,6 +407,8 @@ ${postgresAgent(spec.agent)}    volumes:
 ${adminService(spec, adminMemoryMiB, env)}
 
 ${gatewayService(spec)}
+
+${stagingGatewayService(spec)}
 ${mcpAuthProxyService(spec.images)}
 ${schedulerService(spec)}
 volumes:
@@ -475,6 +506,12 @@ ${serviceRuntime(
       PUBLIC_STAGING_ADMIN_DATABASE_URL: "${dbUrl("admin_role", spec.rolePasswords.admin, "cms_public_staging")}"
       CAELO_SECRET_KEK: "${escapeYaml(spec.caeloSecretKek)}"
       CAELO_INTERNAL_SECRET: "${escapeYaml(spec.internalSecret)}"
+      # #650 / #1330 — the staging gate's key and the staging host the admin seeds.
+      CAELO_STAGING_GATE_SECRET: "${escapeYaml(spec.stagingGateSecret)}"
+      CAELO_STAGING_HOST: "${escapeYaml(spec.stagingHost)}"
+      # #1330 — the staging gateway on the Compose network: the Stage's
+      # serve check asks it whether it sees the build just written.
+      CAELO_STAGING_GATEWAY_URL: "http://${COMPOSE_STAGING_GATEWAY_UPSTREAM}"
       CAELO_SITE_URL: "${escapeYaml(selfHostedSiteUrl(spec.domain, spec.ports.https))}"
       PORT: "${COMPOSE_ADMIN_PORT}"
       CAELO_OUTPUT_ROOT: "${SITE_OUTPUT_ROOT}"
@@ -505,6 +542,34 @@ ${poolEnvLines("gateway")}
       NODE_ENV: production`;
 }
 
+/**
+ * #1330 — the staging gateway: the gateway's image with
+ * `CAELO_GATEWAY_ENVIRONMENT=staging`. It serves the staged builds, which it
+ * reads from the admin's `output/staging` mounted read-only (no other part
+ * of the output, nothing writable), behind the staging gate, and staging's
+ * own data: `public_staging_role` on `cms_public_staging` is its only
+ * login. Caddy sends every request for the staging host here.
+ */
+function stagingGatewayService(spec: ComposeSpec): string {
+  return `  ${COMPOSE_STAGING_GATEWAY_SERVICE}:
+${serviceRuntime(spec.images, "gateway", "bun run apps/api-gateway/src/server.ts", [
+  DATABASE_CA_MOUNT,
+  `./output/output/staging:${STAGING_GATEWAY_STORAGE_DIR}:ro`,
+])}
+    restart: unless-stopped
+    depends_on:
+      postgres: { condition: service_healthy }
+    environment:
+      PUBLIC_DATABASE_URL: "${dbUrl("public_staging_role", spec.rolePasswords.publicStaging, "cms_public_staging")}"
+      ${GATEWAY_ENVIRONMENT_ENV}: "staging"
+      GATEWAY_PORT: "${COMPOSE_STAGING_GATEWAY_PORT}"
+      ${STAGING_STORAGE_ENV}: "file://${STAGING_GATEWAY_STORAGE_DIR}"
+      # Caddy is the one proxy in front (client-ip.ts in the gateway).
+      ${TRUSTED_PROXY_HOPS_ENV}: "${STAGING_GATEWAY_TRUSTED_PROXY_HOPS["self-hosted"]}"
+${poolEnvLines("gateway")}
+      NODE_ENV: production`;
+}
+
 /**
  * #1328 — the MCP-Auth-Proxy: remote MCP's sign-in broker, its own
  * container so it never shares a process with visitor handlers. Remote MCP

package/src/converge-checkpoint.ts

@@ -49,6 +49,7 @@ export const ConvergeCheckpointSchema = InstallJobStatusSchema.extend({
       admin: z.string().min(1),
       gateway: z.string().min(1),
       // #1328 — absent in a checkpoint an older release wrote.
+      "staging-gateway": z.string().min(1).optional(),
       "mcp-auth-proxy": z.string().min(1).optional(),
     })
     .optional(),

package/src/database-tls-builders.test.ts

@@ -32,6 +32,8 @@ describe("database URL builders (#1338)", () => {
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
+      stagingHost: "staging.example.com",
+      stagingGateSecret: "g".repeat(64),
       diskSize: "20Gi",
       images: {
         mode: "release",
@@ -43,7 +45,7 @@ describe("database URL builders (#1338)", () => {
     });
     const urls = [...yaml.matchAll(/_DATABASE_URL: "([^"]+)"/g)].map((m) => m[1] as string);
     // admin: cms_admin, cms_public, cms_public_staging (#1329); gateway: cms_public.
-    expect(urls).toHaveLength(4);
+    expect(urls).toHaveLength(5);
     for (const url of urls) expect(databaseTlsProblem(url)).toBeNull();
   });
 

package/src/deployed-release.test.ts

@@ -111,6 +111,27 @@ describe("readDeployedImageDigests", () => {
     if (!r.ok) expect(r.error).toContain("not pinned to a digest");
   });
 
+  it("#1330 — accepts a staging gateway on the gateway's image, refuses one on another", async () => {
+    const answers = (staging: string) => ({
+      ...firebaseLists(),
+      "metadata.name~^caelo-production-staging-gateway": [ok("caelo-production-staging-gateway\n")],
+      "describe caelo-production-admin-abc": [ok(`${REG}/admin@${A}`)],
+      "describe caelo-production-data-gateway": [ok(`${REG}/gateway@${B}`)],
+      "describe caelo-production-gateway-def": [ok(`${REG}/mcp-auth-proxy@${C}`)],
+      "describe caelo-production-staging-gateway": [ok(`${REG}/gateway@${staging}`)],
+    });
+    const same = fakeGcloud(answers(B));
+    expect(await readDeployedImageDigests({ ...FIREBASE, run: same.run })).toEqual({
+      ok: true,
+      digests: { admin: A, gateway: B, "mcp-auth-proxy": C },
+    });
+    expect(same.calls.some((c) => c.includes("caelo-production-staging-gateway"))).toBe(true);
+    const other = fakeGcloud(answers(A));
+    const r = await readDeployedImageDigests({ ...FIREBASE, run: other.run });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toContain("the staging gateway runs");
+  });
+
   it("surfaces a gcloud failure", async () => {
     const { run } = fakeGcloud({ "services list": [fail("PERMISSION_DENIED")] });
     const r = await readDeployedImageDigests({ ...FIREBASE, run });

package/src/deployed-release.ts

@@ -21,7 +21,9 @@ import {
   cloudRunServicePrefix,
   type GcpProvider,
   RETIRED_SERVICE_ENV,
+  SERVICE_IMAGE_NAMES,
   SERVICE_SECRET_ENV,
+  type ServiceImageName,
 } from "./stack-contract.js";
 import { liveContainerEnv } from "./stack-converge.js";
 
@@ -35,7 +37,7 @@ async function findDeployedService(
   run: GcloudRunner,
   opts: { provider: GcpProvider; projectId: string; region: string },
   slug: CloudRunSlug,
-): Promise<{ ok: true; name: string } | { ok: false; error: string }> {
+): Promise<{ ok: true; name: string } | { ok: false; error: string; missing: boolean }> {
   const prefix = cloudRunServicePrefix(opts.provider, GCP_STACK_ENV, slug);
   const list = await run([
     "run",
@@ -46,7 +48,8 @@ async function findDeployedService(
     `--filter=metadata.name~^${prefix}`,
     "--format=value(metadata.name)",
   ]);
-  if (!list.ok) return { ok: false, error: `list Cloud Run services: ${list.stderr.trim()}` };
+  if (!list.ok)
+    return { ok: false, error: `list Cloud Run services: ${list.stderr.trim()}`, missing: false };
   const names = list.stdout
     .split("\n")
     .map((s) => s.trim())
@@ -58,6 +61,7 @@ async function findDeployedService(
         names.length === 0
           ? `no ${prefix}* Cloud Run service: the install runs a release from before it (the ${slug} became its own service in #1328). Run \`upgrade\` first: it creates the service and moves the release over.`
           : `expected one ${prefix}* Cloud Run service, found ${names.join(", ")}`,
+      missing: names.length === 0,
     };
   }
   return { ok: true, name: names[0] as string };
@@ -86,7 +90,11 @@ export async function checkDeployedRuntimeEnv(opts: {
   const run = opts.run ?? defaultGcloud;
   for (const slug of CLOUD_RUN_SLUGS) {
     const found = await findDeployedService(run, opts, slug);
-    if (!found.ok) return found;
+    // #1330 — the staging gateway is the CLI's (staging-gateway-setup.ts):
+    // an install from before it gets it after this `up`, so a missing one
+    // runs no release that could mismatch the env.
+    if (!found.ok && slug === "staging-gateway" && found.missing) continue;
+    if (!found.ok) return { ok: false, error: found.error };
     const describe = await run([
       "run",
       "services",
@@ -131,8 +139,14 @@ export async function readDeployedImageDigests(opts: {
   run?: GcloudRunner;
 }): Promise<{ ok: true; digests: ImageDigests } | { ok: false; error: string }> {
   const run = opts.run ?? defaultGcloud;
-  const digests: Record<CloudRunSlug, string> = { admin: "", gateway: "", "mcp-auth-proxy": "" };
-  for (const slug of CLOUD_RUN_SLUGS) {
+  const digests: Record<ServiceImageName, string> = {
+    admin: "",
+    gateway: "",
+    "mcp-auth-proxy": "",
+  };
+  const digestOf = async (
+    slug: CloudRunSlug,
+  ): Promise<{ ok: true; digest: string } | { ok: false; error: string; missing: boolean }> => {
     const found = await findDeployedService(run, opts, slug);
     if (!found.ok) return found;
     const image = await run([
@@ -144,15 +158,36 @@ export async function readDeployedImageDigests(opts: {
       `--project=${opts.projectId}`,
       "--format=value(spec.template.spec.containers[0].image)",
     ]);
-    if (!image.ok) return { ok: false, error: `describe ${found.name}: ${image.stderr.trim()}` };
+    if (!image.ok) {
+      return { ok: false, error: `describe ${found.name}: ${image.stderr.trim()}`, missing: false };
+    }
     const digest = digestFromImageRef(image.stdout);
     if (!digest) {
       return {
         ok: false,
         error: `${found.name} runs '${image.stdout.trim()}', which is not pinned to a digest`,
+        missing: false,
       };
     }
-    digests[slug] = digest;
+    return { ok: true, digest };
+  };
+  // One digest per release image.
+  for (const slug of SERVICE_IMAGE_NAMES) {
+    const d = await digestOf(slug);
+    if (!d.ok) return { ok: false, error: d.error };
+    digests[slug] = d.digest;
+  }
+  // #1330 — the staging gateway runs the gateway's image and rolls with it:
+  // one that runs another image means the services serve two releases, and
+  // the wizard must not record (or deploy) either as "the" release. An
+  // install from before it has none yet (the CLI creates it after `up`).
+  const staging = await digestOf("staging-gateway");
+  if (!staging.ok && !staging.missing) return { ok: false, error: staging.error };
+  if (staging.ok && staging.digest !== digests.gateway) {
+    return {
+      ok: false,
+      error: `the staging gateway runs ${staging.digest}, but the gateway runs ${digests.gateway}: the two must run the same release image. Run \`upgrade\` first — it rolls both onto one release — then re-run the installer.`,
+    };
   }
   return { ok: true, digests };
 }

package/src/gateway-env-isolation.test.ts

@@ -162,6 +162,8 @@ describe("self-hosted: the generated compose gateway service (#635)", () => {
       caeloSecretKek: "0".repeat(64),
       dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
       internalSecret: "i".repeat(48),
+      stagingHost: "staging.example.com",
+      stagingGateSecret: "g".repeat(64),
       diskSize: "20Gi",
       images: {
         mode: "release" as const,

package/src/gcp-names.ts

@@ -15,6 +15,8 @@
  * the CLI's dependencies.
  */
 
+import { createHash } from "node:crypto";
+
 /** The Pulumi stack name the wizard provisions and `upgrade` operates on. */
 export const GCP_STACK_ENV = "production";
 
@@ -87,6 +89,57 @@ export function mcpAuthProxyServiceAccountEmail(projectId: string, env: string):
   return `${mcpAuthProxyServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
 }
 
+/**
+ * #1330 — account id of the service account the staging gateway runs as. It
+ * may read the staging database's login password and the staging bucket,
+ * and nothing else: no live data, no media, no gate key (the gate key
+ * reaches it through the staging projection). Shortened: account ids max
+ * out at 30 characters (`caelo-production-stg-gateway-sa` would be 31).
+ */
+export function stagingGatewayServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-stg-gw-sa`;
+}
+
+/** Email of the service account the staging gateway runs as. */
+export function stagingGatewayServiceAccountEmail(projectId: string, env: string): string {
+  return `${stagingGatewayServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
+/**
+ * #1330 — the `gcp` staging gateway's load-balancer resources, CLI-owned
+ * (staging-gateway-setup.ts): its serverless NEG, its backend service and
+ * the managed certificate for the staging host. None matches a prefix the
+ * other lookups use (`…-waf`, `…-admin-backend`, `…-gateway-backend`,
+ * `…-mcp-auth-proxy-*`).
+ */
+export function stagingGatewayEdgeNames(env: string): {
+  readonly neg: string;
+  readonly backend: string;
+  readonly cert: string;
+  readonly pathMatcher: string;
+} {
+  const prefix = `${gcpNamePrefix(env)}-staging-gateway`;
+  return {
+    neg: `${prefix}-neg`,
+    backend: `${prefix}-backend`,
+    cert: `${gcpNamePrefix(env)}-staging-cert`,
+    pathMatcher: "staging",
+  };
+}
+
+/**
+ * #1330 — the second Firebase Hosting site of a `gcp-firebase` install,
+ * which serves the staging host through a `**` rewrite to the staging
+ * gateway (E13 a of #763). Derived from the live site's id (Hosting site ids
+ * are global, and the live one carries a random suffix): `caelo-<env>-stg-`
+ * plus six hex characters of its SHA-256, so the admin and the converge,
+ * which both know the live site id (`CAELO_FIREBASE_SITE`), name the same
+ * site without storing it anywhere.
+ */
+export function firebaseStagingSiteId(env: string, liveSiteId: string): string {
+  return `${gcpNamePrefix(env)}-stg-${createHash("sha256").update(liveSiteId).digest("hex").slice(0, 6)}`;
+}
+
 /**
  * Account id of the `gcp` stack's static-publisher service account. Account
  * ids max out at 30 chars, so the env is shortened.