@caelo-cms/provisioning 0.11.12 → 0.11.14

package/src/audit-job-setup.test.ts

@@ -91,7 +91,7 @@ describe("ensureAuditJob", () => {
     for (const c of bucketGrants) expect(flag(c, "condition")).toBe("None");
   });
 
-  it("grants the job only results-create, build-read (gcp) and logs", async () => {
+  it("grants the job only results-create, read of the staging bucket and logs", async () => {
     const { run, calls } = fakeGcloud();
     const r = await ensureAuditJob(TARGET, { run, sleep: async () => {} });
     expect(r.ok).toBe(true);
@@ -102,10 +102,6 @@ describe("ensureAuditJob", () => {
         "storage buckets add-iam-policy-binding gs://acme-caelo-production-staging",
         "roles/storage.objectViewer",
       ],
-      [
-        "storage buckets add-iam-policy-binding gs://acme-caelo-production-static",
-        "roles/storage.objectViewer",
-      ],
       ["projects add-iam-policy-binding acme", "roles/logging.logWriter"],
     ]);
     for (const g of job) {
@@ -151,7 +147,7 @@ describe("ensureAuditJob", () => {
     expect(flag(deploy, "max-retries")).toBe("0");
     expect(flag(deploy, "parallelism")).toBe("15");
     expect(flag(deploy, "set-env-vars")).toBe(
-      `CAELO_PROVIDER=gcp,CAELO_AUDIT_RESULTS_BUCKET=${RESULTS},CAELO_STAGING_BUCKET=acme-caelo-production-staging,CAELO_STATIC_BUCKET=acme-caelo-production-static`,
+      `CAELO_PROVIDER=gcp,CAELO_AUDIT_RESULTS_BUCKET=${RESULTS},CAELO_STAGING_BUCKET=acme-caelo-production-staging`,
     );
     const line = deploy.join(" ");
     for (const banned of ["--network", "--subnet", "--vpc", "--set-secrets", "--update-secrets"]) {
@@ -206,16 +202,20 @@ describe("ensureAuditJob", () => {
     expect(deployOf(calls)).toBeUndefined();
   });
 
-  it("on gcp-firebase reads no bucket: the task audits the public preview channel", async () => {
+  it("#1330 — on gcp-firebase reads the staging bucket too: no preview channel any more", async () => {
     const { run, calls } = fakeGcloud();
     await ensureAuditJob({ ...TARGET, provider: "gcp-firebase" }, { run, sleep: async () => {} });
     const job = grants(calls).filter((g) => g.member === AUDIT);
-    expect(job.map((g) => g.role)).toEqual([
-      "roles/storage.objectCreator",
-      "roles/logging.logWriter",
+    expect(job.map((g) => [g.where, g.role])).toEqual([
+      [`storage buckets add-iam-policy-binding gs://${RESULTS}`, "roles/storage.objectCreator"],
+      [
+        "storage buckets add-iam-policy-binding gs://acme-caelo-production-staging",
+        "roles/storage.objectViewer",
+      ],
+      ["projects add-iam-policy-binding acme", "roles/logging.logWriter"],
     ]);
     expect(flag(deployOf(calls), "set-env-vars")).toBe(
-      `CAELO_PROVIDER=gcp-firebase,CAELO_AUDIT_RESULTS_BUCKET=${RESULTS}`,
+      `CAELO_PROVIDER=gcp-firebase,CAELO_AUDIT_RESULTS_BUCKET=${RESULTS},CAELO_STAGING_BUCKET=acme-caelo-production-staging`,
     );
   });
 

package/src/audit-job-setup.ts

@@ -22,10 +22,12 @@
  *
  *   - `roles/storage.objectCreator` on the audit results bucket — create
  *     only: it can neither read results back nor overwrite one;
- *   - on `gcp` only, `roles/storage.objectViewer` on the staging and static
- *     buckets: it serves the staged build to its own browser, as the admin's
- *     audit does (admin-core quality/staged-origin.ts). gcp-firebase audits
- *     the public preview channel and needs no bucket;
+ *   - `roles/storage.objectViewer` on the staging bucket: it serves the
+ *     staged build to its own browser from the served build slot, which
+ *     holds the complete build (#1330, admin-core quality/staged-origin.ts),
+ *     so Lighthouse never goes through the staging gateway (#875). Both
+ *     providers since #1330 (gcp-firebase had no bucket and audited the
+ *     preview channel before); no read on the static bucket any more;
  *   - `roles/logging.logWriter`.
  *
  * Nothing else: no Secret Manager, no Cloud SQL, and no VPC egress, so the
@@ -231,18 +233,16 @@ export async function ensureAuditJob(
   }
   done.push(`bucket ${resultsUrl} (results deleted after 1 day)`);
 
-  // 3. Bucket grants: the job creates results and (gcp) reads the build;
+  // 3. Bucket grants: the job creates results and reads the staged build;
   //    the admin reads results.
   const bucketGrants: { bucket: string; member: string; role: string; why: string }[] = [
     { bucket: results, member, role: "roles/storage.objectCreator", why: "tasks write results" },
-    ...(provider === "gcp"
-      ? (["staging", "static"] as const).map((b) => ({
-          bucket: gcpBucketName(projectId, env, b),
-          member,
-          role: "roles/storage.objectViewer",
-          why: "tasks serve the staged build to their browser",
-        }))
-      : []),
+    {
+      bucket: gcpBucketName(projectId, env, "staging"),
+      member,
+      role: "roles/storage.objectViewer",
+      why: "tasks serve the staged build to their browser",
+    },
     {
       bucket: results,
       member: runSaMember,
@@ -295,12 +295,7 @@ export async function ensureAuditJob(
   const envVars = [
     `CAELO_PROVIDER=${provider}`,
     `CAELO_AUDIT_RESULTS_BUCKET=${results}`,
-    ...(provider === "gcp"
-      ? [
-          `CAELO_STAGING_BUCKET=${gcpBucketName(projectId, env, "staging")}`,
-          `CAELO_STATIC_BUCKET=${gcpBucketName(projectId, env, "static")}`,
-        ]
-      : []),
+    `CAELO_STAGING_BUCKET=${gcpBucketName(projectId, env, "staging")}`,
   ];
   const deploy = await run([
     "run",

package/src/caddy-redirects.docker.test.ts

@@ -9,9 +9,10 @@
  *   imported;
  * - a container started like the Compose service (same Caddyfile shape,
  *   same `/srv/caelo` mount, same reload-loop command and snippet glob)
- *   answers redirected paths on the live and the staging host with the
- *   planned status + Location — query kept, case-sensitive, the live page
- *   wins, 410 for gone;
+ *   answers redirected paths on the live host with the planned status +
+ *   Location — query kept, case-sensitive, the live page wins, 410 for
+ *   gone — and serves nothing of output/staging on the staging host (#1330:
+ *   that is the staging gateway's);
  * - the reload loop picks up a deploy's new snippet, a snippet Caddy
  *   rejects leaves the previous redirects live, and the next good snippet
  *   is picked up again.
@@ -147,7 +148,7 @@ describe.skipIf(!dockerUp)(`self-hosted redirects through ${CADDY_IMAGE}`, () =>
         ownerEmail: "owner@example.test",
         tls: "internal",
         publicSiteRoot: `${SITE_OUTPUT_ROOT}/output/production/current`,
-        stagingSiteRoot: `${SITE_OUTPUT_ROOT}/output/staging/current`,
+        stagingGatewayUpstream: "caelo-staging-gateway:8091",
         adminUpstream: COMPOSE_ADMIN_UPSTREAM,
         gatewayUpstream: COMPOSE_GATEWAY_UPSTREAM,
         mcpAuthProxyUpstream: COMPOSE_MCP_AUTH_PROXY_UPSTREAM,
@@ -246,7 +247,11 @@ describe.skipIf(!dockerUp)(`self-hosted redirects through ${CADDY_IMAGE}`, () =>
     expectRedirect("/hop1", 301, "/blog/");
     expectRedirect("/Case", 301, "/about/");
     expectRedirect("/q?dropped=1", 301, "/about?ref=old");
-    expectRedirect("/staged-old", 301, "/blog/", STAGING);
+    // #1330 — Caddy serves no staged file and answers no staging redirect:
+    // the staging host goes to the staging gateway (not running here, so
+    // Caddy answers 502), whatever lies in output/staging.
+    expect(probe(STAGING, "/staged-old").status).toBe(502);
+    expect(probe(STAGING, "/index.html").status).toBe(502);
     expect(probe(LIVE, "/gone").status).toBe(410);
     // Exact, case-sensitive: /case is not /Case.
     expect(probe(LIVE, "/case").status).toBe(404);

package/src/caddy-redirects.test.ts

@@ -24,7 +24,7 @@ const caddyfile = generateCaddyfile({
   ownerEmail: "owner@example.com",
   tls: "acme",
   publicSiteRoot: "/srv/caelo/output/production/current",
-  stagingSiteRoot: "/srv/caelo/output/staging/current",
+  stagingGatewayUpstream: "caelo-staging-gateway:8091",
   adminUpstream: COMPOSE_ADMIN_UPSTREAM,
   gatewayUpstream: COMPOSE_GATEWAY_UPSTREAM,
   mcpAuthProxyUpstream: COMPOSE_MCP_AUTH_PROXY_UPSTREAM,
@@ -41,13 +41,13 @@ function block(host: string): string {
 }
 
 describe("Caddyfile — redirects (#587)", () => {
-  it("each public vhost imports the redirect snippet of the build it serves", () => {
+  it("the live vhost imports the redirect snippet of the build it serves", () => {
     expect(block("example.com")).toContain(
       "  root * /srv/caelo/output/production/current\n  import /srv/caelo/output/production/current/_redirects.caddy*\n",
     );
-    expect(block("staging.example.com")).toContain(
-      "import /srv/caelo/output/staging/current/_redirects.caddy*",
-    );
+    // #1330 — staging's redirects are the staging gateway's (from the
+    // staging projection), not Caddy's.
+    expect(block("staging.example.com")).not.toContain("_redirects.caddy");
     expect(block("admin.example.com")).not.toContain("_redirects.caddy");
   });
 
@@ -67,6 +67,8 @@ describe("Compose — Caddy picks up new redirects (#587)", () => {
     caeloSecretKek: "0".repeat(64),
     dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
     internalSecret: "i".repeat(48),
+    stagingHost: "staging.example.com",
+    stagingGateSecret: "g".repeat(64),
     diskSize: "20Gi",
     ports: { http: 80, https: 443 },
     project: "caelo-example-com",

package/src/caddy-validate.test.ts

@@ -64,7 +64,7 @@ const base: CaddyfileSpec = {
   ownerEmail: "owner@example.com",
   tls: "acme",
   publicSiteRoot: "/srv/caelo/output/production/current",
-  stagingSiteRoot: "/srv/caelo/output/staging/current",
+  stagingGatewayUpstream: "caelo-staging-gateway:8091",
   adminUpstream: COMPOSE_ADMIN_UPSTREAM,
   gatewayUpstream: COMPOSE_GATEWAY_UPSTREAM,
   mcpAuthProxyUpstream: COMPOSE_MCP_AUTH_PROXY_UPSTREAM,

package/src/caddy.test.ts

@@ -20,7 +20,7 @@ const spec: CaddyfileSpec = {
   ownerEmail: "owner@example.com",
   tls: "acme",
   publicSiteRoot: "/srv/caelo/output/production/current",
-  stagingSiteRoot: "/srv/caelo/output/staging/current",
+  stagingGatewayUpstream: "caelo-staging-gateway:8091",
   adminUpstream: COMPOSE_ADMIN_UPSTREAM,
   gatewayUpstream: COMPOSE_GATEWAY_UPSTREAM,
   mcpAuthProxyUpstream: COMPOSE_MCP_AUTH_PROXY_UPSTREAM,
@@ -96,9 +96,12 @@ describe("Caddyfile upstreams (#707)", () => {
     expect(out).not.toContain("localhost");
     expect(out).not.toContain("127.0.0.1");
     expect(block(out, "admin.example.com")).toContain("reverse_proxy caelo-admin:5173");
-    for (const host of ["example.com", "staging.example.com"]) {
-      expect(block(out, host)).toContain("handle /api/* {\n    reverse_proxy caelo-gateway:8090\n");
-    }
+    expect(block(out, "example.com")).toContain(
+      "handle /api/* {\n    reverse_proxy caelo-gateway:8090\n",
+    );
+    // #1330 — the staging host goes to the staging gateway, every path.
+    expect(block(out, "staging.example.com")).toContain("reverse_proxy caelo-staging-gateway:8091");
+    expect(block(out, "staging.example.com")).not.toContain("caelo-gateway:8090");
   });
 
   it("does not route /admin/* on the public site (the admin routes from / on its own host)", () => {
@@ -123,12 +126,15 @@ describe("Caddyfile static site (#566)", () => {
     );
   });
 
-  it("serves production and staging from their own roots; only staging is noindex", () => {
+  it("serves production from its root; staging only through the staging gateway, noindex", () => {
     const out = generateCaddyfile(spec);
     expect(block(out, "example.com")).toContain("root * /srv/caelo/output/production/current");
     expect(block(out, "example.com")).not.toContain("X-Robots-Tag");
     const staging = block(out, "staging.example.com");
-    expect(staging).toContain("root * /srv/caelo/output/staging/current");
+    // #1330 — no second path to the staged files: Caddy serves none of them.
+    expect(staging).not.toContain("root *");
+    expect(staging).not.toContain("file_server");
+    expect(staging).not.toContain("output/staging");
     expect(staging).toContain('header X-Robots-Tag "noindex"');
   });
 });

package/src/caddy.ts

@@ -15,6 +15,9 @@
  *     #           MCP-Auth-Proxy on its own host, never the site's origin)
  *     # public  → /api/* → <gatewayUpstream>; everything else is the
  *     #           static site (try_files + file_server, 404 → /404.html)
+ *     # staging → reverse_proxy <stagingGatewayUpstream> for every path
+ *     #           (#1330: the staging gateway serves the staged build
+ *     #           behind the staging gate, and staging's own /api)
  *   }
  *
  * Upstreams are `host:port` as seen FROM CADDY. In the Compose install
@@ -27,7 +30,10 @@
  * run in CI) — issue #566 shipped a `try_files` nested inside
  * `file_server { }`, which Caddy 2.11 refuses, so no vhost came up.
  *
- * Staging vhosts force `X-Robots-Tag: noindex`.
+ * Staging vhosts force `X-Robots-Tag: noindex`. Caddy serves no staging
+ * file itself (#1330): the staging gateway mounts the staged builds
+ * read-only, and Caddy has no other path to them, so nothing reaches a
+ * staged page without passing the gate.
  *
  * Public vhosts import the redirect snippet of the build they serve
  * (`_redirects.caddy`, #587); the Caddy container reloads itself when a
@@ -91,7 +97,8 @@ export interface CaddyfileSpec {
   readonly ownerEmail: string;
   readonly tls: CaddyTlsMode;
   readonly publicSiteRoot: string; // absolute path inside the Caddy container
-  readonly stagingSiteRoot: string;
+  /** #1330 — `host:port` of the staging gateway as Caddy reaches it (Compose: `caelo-staging-gateway:8091`). */
+  readonly stagingGatewayUpstream: string;
   /** `host:port` of the admin as Caddy reaches it (Compose: `caelo-admin:5173`). */
   readonly adminUpstream: string;
   /** `host:port` of the API gateway as Caddy reaches it (Compose: `caelo-gateway:8090`). */
@@ -173,7 +180,7 @@ function assertSafeCaddyToken(label: string, value: string, kind: "address" | "t
 export function generateCaddyfile(spec: CaddyfileSpec): string {
   assertSafeCaddyToken("ownerEmail", spec.ownerEmail, "token");
   assertSafeCaddyToken("publicSiteRoot", spec.publicSiteRoot, "token");
-  assertSafeCaddyToken("stagingSiteRoot", spec.stagingSiteRoot, "token");
+  assertSafeCaddyToken("stagingGatewayUpstream", spec.stagingGatewayUpstream, "token");
   assertSafeCaddyToken("adminUpstream", spec.adminUpstream, "token");
   assertSafeCaddyToken("gatewayUpstream", spec.gatewayUpstream, "token");
   assertSafeCaddyToken("mcpAuthProxyUpstream", spec.mcpAuthProxyUpstream, "token");
@@ -232,12 +239,24 @@ function vhost(d: CaddyDomainSpec, spec: CaddyfileSpec): string {
   header X-Content-Type-Options "${NOSNIFF}"
   reverse_proxy ${spec.mcpAuthProxyUpstream}
 }
+`;
+  }
+  if (d.env === "staging") {
+    // #1330 — every path to the staging gateway: it runs the gate first and
+    // serves the staged build and staging's /api itself. The #891 security
+    // headers stay on as a second layer over the gateway's own.
+    return `${d.hostname} {${noindex}
+  header X-Content-Type-Options "${NOSNIFF}"
+  @svg path *.svg
+  header @svg Content-Security-Policy "${SVG_DOCUMENT_CSP}"
+  reverse_proxy ${spec.stagingGatewayUpstream}
+}
 `;
   }
   // public — API routes go to the gateway, the rest is the static site.
   // `try_files` is its own directive (a rewrite), never a file_server
   // subdirective (#566).
-  const root = d.env === "staging" ? spec.stagingSiteRoot : spec.publicSiteRoot;
+  const root = spec.publicSiteRoot;
   // #587 — the redirects table of the build this vhost serves.
   return `${d.hostname} {${noindex}
   root * ${root}

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)`,
   );
 }