@caelo-cms/provisioning 0.11.12 → 0.11.14

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.

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 18: 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)", () => {
-    expect(INFRA_CONTRACT_VERSION).toBe(18);
+  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");
@@ -38,6 +38,8 @@ describe("infrastructure contract steps", () => {
     expect(INFRA_CONTRACT_STEPS[16]).toContain("#1328");
     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", () => {
@@ -48,6 +50,6 @@ describe("infrastructure contract steps", () => {
   });
 
   it("names a version a newer release added by number", () => {
-    expect(infraStepsText(18, 19)).toBe("infrastructure step 19 (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 = 18;
+export const INFRA_CONTRACT_VERSION = 20;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -150,6 +150,25 @@ export const INFRA_CONTRACT_VERSION = 18;
 //       on the admin. The new admin runs its periodic work and plugin workers
 //       only on that tick, so an in-cloud upgrader must not roll an install
 //       onto it before the tick exists.
+//  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
@@ -175,6 +194,8 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   16: "the MCP sign-in service as its own Cloud Run service with its own account (no database access), the visitor gateway as its own service on Firebase installs, and on Google Cloud load-balancer installs the sign-in service's backend and Cloud Armor rule (#1328)",
   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)",
 };
 
 /**