@caelo-cms/provisioning 0.10.52 → 0.10.55

package/src/cli-routing.ts

@@ -48,3 +48,134 @@ export function resolveCliRoute(argv: readonly string[], handlerNames: Iterable<
 export function initDelegatesToWizard(provider: string): boolean {
   return provider !== "self-hosted";
 }
+
+/** One documented `cms-provision` sub-command (the usage text and the public CLI reference). */
+export interface CliCommandDoc {
+  /** The sub-command as typed, e.g. `upgrade` or `state migrate`. */
+  readonly name: string;
+  /** Arguments and flags in usage notation; empty when it takes none. */
+  readonly args: string;
+  /** One sentence for an operator: what it does and when to run it. */
+  readonly summary: string;
+}
+
+/**
+ * The documented sub-commands, in usage order. The single source for both
+ * the usage text `cms-provision --help` prints ({@link cliUsage}) and the
+ * provisioning CLI page of the developer reference mirrored into the docs
+ * on every release (scripts/docs-reference.ts, #828), so the two never
+ * drift. Internal entry points (`install-job`, `agent`, the
+ * `*-self-hosted` aliases) are deliberately absent.
+ */
+export const CLI_COMMANDS: readonly CliCommandDoc[] = [
+  {
+    name: "init",
+    args: "--domain <d> --owner-email <e> [--staging-domain <host>] [--version x.y.z] [--tls acme|internal] [--http-port 80] [--https-port 443]",
+    summary:
+      "Self-hosted only: write the install's config with fresh secrets, verify the signed release images and start the Docker Compose stack; prints the Owner setup link. Cloud providers run the wizard instead.",
+  },
+  {
+    name: "up",
+    args: "",
+    summary:
+      "Self-hosted only: converge the database roles, re-emit the Compose file and Caddyfile, and (re)start the stack.",
+  },
+  {
+    name: "migrate",
+    args: "",
+    summary:
+      "Self-hosted only: apply the database migrations with the admin image the install runs. Idempotent.",
+  },
+  {
+    name: "status",
+    args: "[--install <id|domain|all>]",
+    summary: "Show the install's health and its estimated monthly cost.",
+  },
+  {
+    name: "upgrade",
+    args: "[--version x.y.z] [--channel stable|rc|beta] [--region <r>] [--skip-verify] [--skip-health-check] [--install <id|domain|all>]",
+    summary:
+      "Roll the install to a newer release (latest stable by default) after verifying the image signatures.",
+  },
+  {
+    name: "backup",
+    args: "[--to <file>] [--install <id|domain|all>]",
+    summary:
+      "Take a backup now: an on-demand Cloud SQL backup on cloud installs, an archive of the databases, published site and media on self-hosted.",
+  },
+  {
+    name: "restore",
+    args: "--from <backup.tar.gz> --yes",
+    summary:
+      "Self-hosted only: replace both databases, the published site and the media with a backup archive. Destructive.",
+  },
+  {
+    name: "rotate-secret",
+    args: "<name>",
+    summary: "Rotate one of the install's runtime secrets; run without a name to list them.",
+  },
+  {
+    name: "truncate",
+    args: "",
+    summary:
+      "Delete all content and history while keeping users, roles, providers, domains and settings. Destructive.",
+  },
+  {
+    name: "destroy",
+    args: "",
+    summary: "Permanently delete the install and every resource it created. Asks twice.",
+  },
+  {
+    name: "regenerate-caddy",
+    args: "",
+    summary: "Self-hosted only: re-emit the Caddyfile from the install's domains and reload Caddy.",
+  },
+  {
+    name: "admin-domain",
+    args: "enable",
+    summary:
+      "gcp-firebase: bind admin.<domain> to the admin and wait for its TLS certificate (resumable).",
+  },
+  {
+    name: "staging-domain",
+    args: "enable [--staging-domain <host>] [--rotate-staging-password] [--show-staging-password]",
+    summary:
+      "gcp-firebase: bind the protected staging host and set up its basic auth; prints the credentials on the first run.",
+  },
+  {
+    name: "owner-reset",
+    args: "[--install <id>] [--email <addr>]",
+    summary:
+      "Print a one-time password-reset link for a locked-out Owner on installs whose admin cannot send email.",
+  },
+  {
+    name: "state migrate",
+    args: "[--install <id|domain>] [--to remote|local] [--dry-run] [--yes]",
+    summary: "Move the install's Pulumi state into (or out of) the install's own cloud project.",
+  },
+  {
+    name: "attach",
+    args: "--project <gcp-project-id>",
+    summary: "Set up this machine to manage an existing install whose state lives in its project.",
+  },
+  {
+    name: "pulumi-output-sync",
+    args: "",
+    summary:
+      "Copy the stack outputs into the admin so its DNS and settings pages show current values; run after a manual `pulumi up`.",
+  },
+  {
+    name: "version",
+    args: "",
+    summary: "Print the CLI's version.",
+  },
+];
+
+/** The text `cms-provision --help` prints, built from {@link CLI_COMMANDS}. */
+export function cliUsage(): string {
+  return (
+    `Usage: cms-provision [wizard] [--provider <name> --domain <d> [--staging-domain <host>] --owner-email <e> --region <r>] [--local|--install-job] | <${CLI_COMMANDS.map((c) => c.name).join("|")}> [options]\n` +
+    "With several installs on this machine, pick one with --install <install-id or domain> (status, upgrade and backup also take --install all); in a terminal you are asked otherwise.\n" +
+    "Pass --no-wizard with no sub-command to print this usage instead of the wizard."
+  );
+}

package/src/cli.ts

@@ -51,12 +51,13 @@ import { generateBootstrapToken } from "./bootstrap-token.js";
 import {
   type CaddyDomainSpec,
   type CaddyTlsMode,
+  caddyTokenProblem,
   generateCaddyfile,
   selfHostedAdminHost,
   selfHostedSeedDomains,
 } from "./caddy.js";
 import { redactCredentials } from "./checkpoint-secrets.js";
-import { initDelegatesToWizard, resolveCliRoute } from "./cli-routing.js";
+import { cliUsage, initDelegatesToWizard, resolveCliRoute } from "./cli-routing.js";
 import {
   BOOTSTRAP_DIR,
   COMPOSE_ADMIN_UPSTREAM,
@@ -71,6 +72,7 @@ import {
   SITE_OUTPUT_ROOT,
   selfHostedSiteUrl,
 } from "./compose.js";
+import { tightenPrivateTree, writePrivateFile } from "./private-file.js";
 import { selfCommand } from "./self-command.js";
 import {
   bunHostRunner,
@@ -192,8 +194,8 @@ function loadProvider(): Provider {
 }
 
 function saveProvider(provider: Provider): void {
-  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true });
-  writeFileSync(PROVIDER_PATH, JSON.stringify({ provider }, null, 2));
+  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true, mode: 0o700 });
+  writePrivateFile(PROVIDER_PATH, JSON.stringify({ provider }, null, 2));
 }
 
 /**
@@ -224,6 +226,20 @@ function randomSecret(bytes = 32): string {
 
 function loadConfig(): CaeloConfig | null {
   if (!existsSync(CONFIG_PATH)) return null;
+  // Every command that works on an install reads its config first, so this
+  // is where an install made by an older CLI loses its world-readable
+  // secrets (#888) — not only once each file happens to be rewritten.
+  tightenPrivateTree(
+    CAELO_DIR,
+    [BOOTSTRAP_DIR, "backups"],
+    [
+      "config.json",
+      "provider.json",
+      "internal-secret.json",
+      "docker-compose.yml",
+      `${BOOTSTRAP_DIR}/pending-token.json`,
+    ],
+  );
   const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as CaeloConfig;
   // #707 — settings added later, back-filled (and stored) with what every
   // install ran before they existed, so `upgrade` / `agent` render the same
@@ -238,8 +254,8 @@ function loadConfig(): CaeloConfig | null {
 }
 
 function saveConfig(c: CaeloConfig): void {
-  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(c, null, 2));
+  if (!existsSync(CAELO_DIR)) mkdirSync(CAELO_DIR, { recursive: true, mode: 0o700 });
+  writePrivateFile(CONFIG_PATH, JSON.stringify(c, null, 2));
 }
 
 function arg(name: string): string | undefined {
@@ -248,9 +264,9 @@ function arg(name: string): string | undefined {
   return process.argv[idx + 1];
 }
 
-/** Fresh passwords for the three application roles. */
+/** Fresh passwords for the two application roles. */
 function newRolePasswords(): RolePasswords {
-  return { admin: randomSecret(32), public: randomSecret(32), gateway: randomSecret(32) };
+  return { admin: randomSecret(32), public: randomSecret(32) };
 }
 
 function emitConfig(cfg: CaeloConfig, extraDomains: CaddyDomainSpec[] = []): void {
@@ -293,7 +309,7 @@ function emitConfig(cfg: CaeloConfig, extraDomains: CaddyDomainSpec[] = []): voi
  * operator-added domains only `up` / `regenerate-caddy` read back).
  */
 function emitComposeFiles(cfg: CaeloConfig): void {
-  writeFileSync(COMPOSE_PATH, renderCompose(cfg, installImages(cfg)), { mode: 0o600 });
+  writePrivateFile(COMPOSE_PATH, renderCompose(cfg, installImages(cfg)));
   // No secrets (it reads the passwords from the container's environment),
   // and the postgres user inside the container must be able to read it.
   writeFileSync(
@@ -527,6 +543,19 @@ async function init(): Promise<void> {
     console.error(`--staging-domain: ${stagingProblem}`);
     process.exit(2);
   }
+  // The Caddyfile check would only fire in emitConfig, after config.json is
+  // written — and a re-run then stops at "config already exists".
+  for (const [flag, value, kind] of [
+    ["--domain", domain, "address"],
+    ["--staging-domain", stagingArg, "address"],
+    ["--owner-email", ownerEmail, "token"],
+  ] as const) {
+    const problem = value === undefined ? null : caddyTokenProblem(value, kind);
+    if (problem) {
+      console.error(`${flag} ${JSON.stringify(value)}: ${problem}.`);
+      process.exit(2);
+    }
+  }
   // #696 — the prebuilt release images, resolved to digests and
   // cosign-verified BEFORE anything is written, so a failed check leaves no
   // half-made install. `--dev` (contributors only) runs this checkout instead.
@@ -589,7 +618,7 @@ async function init(): Promise<void> {
   // staging file.
   const tok = generateBootstrapToken();
   mkdirSync(resolve(CAELO_DIR, BOOTSTRAP_DIR), { recursive: true, mode: 0o700 });
-  writeFileSync(PENDING_TOKEN_PATH, JSON.stringify(tok, null, 2), { mode: 0o600 });
+  writePrivateFile(PENDING_TOKEN_PATH, JSON.stringify(tok, null, 2));
 
   // P15.1 — mint the shared HMAC secret for /api/internal/* endpoints.
   // Same secret is read by:
@@ -601,7 +630,7 @@ async function init(): Promise<void> {
   // internal-secret`.
   const internalSecret = randomSecret(48);
   const internalSecretPath = resolve(CAELO_DIR, "internal-secret.json");
-  writeFileSync(internalSecretPath, JSON.stringify({ secret: internalSecret }, null, 2));
+  writePrivateFile(internalSecretPath, JSON.stringify({ secret: internalSecret }, null, 2));
   // #696 Phase 4c — the update agent (Linux + systemd): the fresh volume's
   // bootstrap.sh creates its database login on Postgres's first start.
   const { reportAgentSetup, setUpAgent } = await import("./agent/command.js");
@@ -979,6 +1008,7 @@ async function upgradeSelfHostedCommand(opts: {
       caeloDir: CAELO_DIR,
       runner: bunHostRunner,
       renderCompose: (images) => renderCompose(cfg, images),
+      convergeRoles: agentContext(cfg).convergeRoles,
       log: {
         step: (m) => console.log(`\n==> ${m}`),
         info: (m) => console.log(`    ${m}`),
@@ -1534,10 +1564,6 @@ if (route.kind === "handler" || route.kind === "wizard") {
     process.exit(1);
   }
 } else {
-  console.log(
-    "Usage: cms-provision [wizard] [--provider <name> --domain <d> [--staging-domain <host>] --owner-email <e> --region <r>] [--local|--install-job] | <init|up|migrate|status|upgrade|backup|restore|rotate-secret|truncate|destroy|regenerate-caddy|admin-domain|staging-domain|owner-reset|state migrate|attach|pulumi-output-sync|version> [options]\n" +
-      "With several installs on this machine, pick one with --install <install-id or domain> (status, upgrade and backup also take --install all); in a terminal you are asked otherwise.\n" +
-      "Pass --no-wizard with no sub-command to print this usage instead of the wizard.",
-  );
+  console.log(cliUsage());
   process.exit(cmd && !cmd.startsWith("-") ? 2 : 0);
 }

package/src/compose.ts

@@ -29,7 +29,13 @@
 
 import { CADDY_REDIRECTS_FILE } from "@caelo-cms/shared";
 import { caddyRedirectReloadCommand } from "./caddy-redirects.js";
-import { ADMIN_MEMORY_DEFAULT, memoryQuantityMiB, publicSiteUrl } from "./stack-contract.js";
+import {
+  ADMIN_MEMORY_DEFAULT,
+  GATEWAY_TRUSTED_PROXY_HOPS,
+  memoryQuantityMiB,
+  publicSiteUrl,
+  TRUSTED_PROXY_HOPS_ENV,
+} from "./stack-contract.js";
 import { ghcrRepository, isImageDigest, type ReleaseService } from "./upgrade/release-images.js";
 
 /** The admin + gateway release images, each `ghcr.io/caelo-cms/<svc>@sha256:…`. */
@@ -160,13 +166,14 @@ export function ghcrImageDigest(service: ReleaseService, ref: string): string |
 
 /**
  * The application roles' passwords (bootstrap.sh creates the roles with
- * them). One per role, so the gateway — which gets only the public and
- * gateway logins — never holds admin_role's (#613, CLAUDE.md §2).
+ * them). One per role, so the gateway — which gets only the public login —
+ * never holds admin_role's (#613, #635, CLAUDE.md §2). An install's
+ * config.json from before #635 still carries a `gateway` entry; it is
+ * ignored.
  */
 export interface RolePasswords {
   readonly admin: string;
   readonly public: string;
-  readonly gateway: string;
 }
 
 export interface ComposeSpec {
@@ -254,7 +261,6 @@ services:
       POSTGRES_DB: caelo
       ADMIN_ROLE_PASSWORD: "${escapeYaml(spec.rolePasswords.admin)}"
       PUBLIC_ROLE_PASSWORD: "${escapeYaml(spec.rolePasswords.public)}"
-      GATEWAY_ROLE_PASSWORD: "${escapeYaml(spec.rolePasswords.gateway)}"
 ${postgresAgent(spec.agent)}    volumes:
       - caelo-pg:/var/lib/postgresql/data
       - ./bootstrap.sh:/docker-entrypoint-initdb.d/00_bootstrap.sh:ro
@@ -392,6 +398,8 @@ ${serviceRuntime(spec.images, "gateway", "bun run apps/api-gateway/src/server.ts
       # CLAUDE.md §2: the public side has no path to the authoring database).
       PUBLIC_DATABASE_URL: "${dbUrl("public_role", spec.rolePasswords.public, "cms_public")}"
       GATEWAY_PORT: "${COMPOSE_GATEWAY_PORT}"
+      # Caddy is the one proxy in front (client-ip.ts in the gateway).
+      ${TRUSTED_PROXY_HOPS_ENV}: "${GATEWAY_TRUSTED_PROXY_HOPS["self-hosted"]}"
       NODE_ENV: production`;
 }
 

package/src/gateway-credentials.test.ts

@@ -2,7 +2,6 @@
 
 import { describe, expect, it } from "bun:test";
 import {
-  ensureGatewayRolePassword,
   findSqlInstance,
   gatewayMovesPublicRole,
   planPublicRoleSwitch,
@@ -52,7 +51,6 @@ const target = { projectId: "acme", env: "production", sqlInstance: "caelo-produ
 const SECRETS = {
   "postgres-password": "admin-pw",
   "public-role-password": "public-pw",
-  "gateway-role-password": "gateway-pw",
 };
 const secretRef = (secret: string): LiveEnvValue => ({
   kind: "secret",
@@ -66,7 +64,6 @@ const BEFORE_613 = new Map<string, LiveEnvValue>([
 ]);
 const AFTER_613 = new Map<string, LiveEnvValue>([
   ["PUBLIC_DATABASE_PASSWORD", secretRef("public-role-password")],
-  ["GATEWAY_DATABASE_PASSWORD", secretRef("gateway-role-password")],
 ]);
 
 describe("gatewayMovesPublicRole", () => {
@@ -85,32 +82,6 @@ describe("gatewayMovesPublicRole", () => {
   });
 });
 
-describe("ensureGatewayRolePassword", () => {
-  it("sets gateway_role from its secret through the API, never on argv", async () => {
-    const { run, lines } = fakeGcloud(SECRETS);
-    const sql = fakeSqlApi();
-    const r = await ensureGatewayRolePassword(target, {
-      run,
-      http: sql.http,
-      sleep: async () => {},
-    });
-    expect(r.status).toBe("applied");
-    expect(sql.set).toEqual(["gateway_role gateway-pw"]);
-    expect(lines.some((l) => l.includes("gateway-pw"))).toBe(false);
-  });
-
-  it("fails, naming the secret, when the secret can't be read", async () => {
-    const { run } = fakeGcloud({});
-    const r = await ensureGatewayRolePassword(target, {
-      run,
-      http: fakeSqlApi().http,
-      sleep: async () => {},
-    });
-    expect(r.status).toBe("failed");
-    expect(r.error).toContain("caelo-production-gateway-role-password");
-  });
-});
-
 describe("planPublicRoleSwitch", () => {
   it("first upgrade: moves public_role onto its own password before the gateway rolls", async () => {
     const { run } = fakeGcloud(SECRETS);

package/src/gateway-credentials.ts

@@ -2,28 +2,22 @@
 
 /**
  * Moving an existing install's API gateway off admin_role (issue #613),
- * as `cms-provision upgrade` does it. The env side — the per-role password
- * secrets in, ADMIN_DATABASE_* out (and, since #635, GATEWAY_DATABASE_* out
- * too: the gateway has no cms_admin login at all) — rides the gateway's
- * roll (stack-contract.ts). gateway_role keeps getting its password until
- * the contract release drops the role, because the previous release's
- * gateway logs in with it until it is rolled. The database side is ordered around
- * that roll so /api/* keeps working:
+ * as `cms-provision upgrade` does it. The env side — public_role's own
+ * password secret in, every cms_admin credential out (#613, #635) — rides
+ * the gateway's roll (stack-contract.ts). The database side is ordered
+ * around that roll so /api/* keeps working:
  *
- *   1. after migrations (which create `gateway_role` without a password):
- *      `gateway_role` gets its password. Nothing uses the role yet, so this
- *      is safe at any point before the gateway rolls.
- *   2. right before the gateway rolls: `public_role` moves off admin_role's
+ *   1. right before the gateway rolls: `public_role` moves off admin_role's
  *      password onto its own. Only the gateway logs in as public_role, so
  *      the window in which the old revision cannot open NEW public
  *      connections is the roll itself (open connections stay up).
- *   3. if the gateway's roll fails and it is rolled back: `public_role`
+ *   2. if the gateway's roll fails and it is rolled back: `public_role`
  *      goes back to the password the prior revision reads, so the rollback
  *      leaves a working gateway, not a locked-out one.
  *
  * On every later upgrade the gateway already reads public_role's own
- * secret: step 2 then re-applies the same value (a no-op for clients) and
- * step 3 has nothing to undo.
+ * secret: step 1 then re-applies the same value (a no-op for clients) and
+ * step 2 has nothing to undo.
  */
 
 import { gcloud as defaultGcloud } from "./gcloud.js";
@@ -60,22 +54,14 @@ export interface GatewayCredentialDeps {
   readonly http?: HttpFetch;
 }
 
-/** Step 1: `gateway_role`'s password from its secret. */
-export function ensureGatewayRolePassword(
-  target: DatabaseRoleTarget,
-  deps: GatewayCredentialDeps = {},
-): Promise<EnsureOutcome> {
-  return ensureDatabaseRolePassword(target, "gateway_role", deps);
-}
-
-/** Steps 2 and 3 for one roll of the gateway. */
+/** Steps 1 and 2 for one roll of the gateway. */
 export interface PublicRoleSwitch {
   /** Whether this roll moves public_role off admin_role's password. */
   readonly moves: boolean;
-  /** Step 2 — run right before the gateway's `services update`. */
+  /** Step 1 — run right before the gateway's `services update`. */
   beforeGatewayRoll(): Promise<EnsureOutcome>;
   /**
-   * Step 3 — run when the gateway's roll failed and it goes back to its
+   * Step 2 — run when the gateway's roll failed and it goes back to its
    * prior revision. Returns what happened, for the operator.
    */
   afterGatewayRollFailed(): Promise<string>;

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

@@ -126,7 +126,7 @@ describe("self-hosted: the generated compose gateway service (#635)", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: "superpw",
-      rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
+      rolePasswords: { admin: "adminpw", public: "publicpw" },
       caeloSecretKek: "0".repeat(64),
       diskSize: "20Gi",
       images: {
@@ -148,7 +148,12 @@ describe("self-hosted: the generated compose gateway service (#635)", () => {
     expect(gateway).not.toMatch(/^ {4}(secrets|env_file|volumes):/m);
     const env = gateway.slice(gateway.indexOf("    environment:"));
     const keys = [...env.matchAll(/^ {6}([A-Z_][A-Z0-9_]*):/gm)].map((m) => m[1]);
-    expect(keys.sort()).toEqual(["GATEWAY_PORT", "NODE_ENV", "PUBLIC_DATABASE_URL"]);
+    expect(keys.sort()).toEqual([
+      "CAELO_TRUSTED_PROXY_HOPS",
+      "GATEWAY_PORT",
+      "NODE_ENV",
+      "PUBLIC_DATABASE_URL",
+    ]);
     expect(out).not.toMatch(/^secrets:/m);
   });
 });

package/src/gcp-names.ts

@@ -69,7 +69,7 @@ export function staticPublisherServiceAccountId(env: string): string {
 export function gcpBucketName(
   projectId: string,
   env: string,
-  bucket: "media" | "static" | "staging",
+  bucket: "media" | "static" | "staging" | "audit-results",
 ): string {
   return `${projectId}-${gcpNamePrefix(env)}-${bucket}`;
 }
@@ -120,6 +120,33 @@ export function upgraderJobResource(projectId: string, region: string, env: stri
   return `projects/${projectId}/locations/${region}/jobs/${upgraderJobName(env)}`;
 }
 
+/**
+ * #875 — Cloud Run job that runs the quality audit's Lighthouse runs in
+ * parallel, one task per run (audit-job-setup.ts).
+ */
+export function auditJobName(env: string): string {
+  return `${gcpNamePrefix(env)}-audit`;
+}
+
+/** Full resource name of the audit job, as the admin's env carries it. */
+export function auditJobResource(projectId: string, region: string, env: string): string {
+  return `projects/${projectId}/locations/${region}/jobs/${auditJobName(env)}`;
+}
+
+/**
+ * Account id of the audit job's own service account: reads the staged
+ * build, creates audit results, writes logs — nothing else
+ * (audit-job-setup.ts).
+ */
+export function auditServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-audit`;
+}
+
+/** Email of the audit job's service account. */
+export function auditServiceAccountEmail(projectId: string, env: string): string {
+  return `${auditServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
 /**
  * Account id of the upgrader job's own service account: may roll the two
  * Cloud Run services, run the migration job and back up Cloud SQL, never

package/src/index.test.ts

@@ -115,7 +115,7 @@ describe("docker-compose generator", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: "supersecret",
-      rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
+      rolePasswords: { admin: "adminpw", public: "publicpw" },
       caeloSecretKek: "0".repeat(64),
       anthropicApiKey: "sk-ant-…",
       diskSize: "20Gi",
@@ -136,7 +136,7 @@ describe("docker-compose generator", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: "supersecret",
-      rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
+      rolePasswords: { admin: "adminpw", public: "publicpw" },
       caeloSecretKek: "0".repeat(64),
       diskSize: "20Gi",
       images: RELEASE_IMAGES,
@@ -150,16 +150,17 @@ describe("docker-compose generator", () => {
     expect(gateway).not.toMatch(
       /ADMIN_DATABASE|GATEWAY_DATABASE|cms_admin|admin_role|gateway_role|adminpw|gatewaypw|supersecret|CAELO_SECRET_KEK/,
     );
-    // bootstrap.sh still creates the three roles from these (gateway_role
-    // until the contract release drops it).
-    expect(out).toContain('GATEWAY_ROLE_PASSWORD: "gatewaypw"');
+    // bootstrap.sh creates the two application roles from these (#635: no
+    // gateway_role).
+    expect(out).toContain('PUBLIC_ROLE_PASSWORD: "publicpw"');
+    expect(out).not.toContain("GATEWAY_ROLE_PASSWORD");
   });
 
   it("escapes secrets containing quotes safely", () => {
     const out = generateDockerCompose({
       domain: "example.com",
       postgresPassword: 'pa"ss',
-      rolePasswords: { admin: "a", public: "b", gateway: "g" },
+      rolePasswords: { admin: "a", public: "b" },
       caeloSecretKek: "0".repeat(64),
       diskSize: "1Gi",
       images: RELEASE_IMAGES,

package/src/infra-contract.test.ts

@@ -20,12 +20,13 @@ describe("infrastructure contract steps", () => {
     );
   });
 
-  it("is at 6: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6)", () => {
-    expect(INFRA_CONTRACT_VERSION).toBe(6);
+  it("is at 8: 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)", () => {
+    expect(INFRA_CONTRACT_VERSION).toBe(8);
     expect(INFRA_CONTRACT_STEPS[3]).toContain("#633");
     expect(INFRA_CONTRACT_STEPS[4]).toContain("#587");
     expect(INFRA_CONTRACT_STEPS[5]).toContain("#635");
     expect(INFRA_CONTRACT_STEPS[6]).toContain("#799");
+    expect(INFRA_CONTRACT_STEPS[7]).toContain("#845");
   });
 
   it("lists the pending steps oldest first", () => {
@@ -36,6 +37,6 @@ describe("infrastructure contract steps", () => {
   });
 
   it("names a version a newer release added by number", () => {
-    expect(infraStepsText(6, 7)).toBe("infrastructure step 7 (see that release's notes)");
+    expect(infraStepsText(8, 9)).toBe("infrastructure step 9 (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 = 6;
+export const INFRA_CONTRACT_VERSION = 8;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -45,6 +45,17 @@ export const INFRA_CONTRACT_VERSION = 6;
 //       into the bucket lists it first; without the binding the in-cloud
 //       upgrader fails at its state lock, so it must not run before the
 //       converge grants it.
+//   7 — #845: the gateway refuses to boot without CAELO_TRUSTED_PROXY_HOPS
+//       (which X-Forwarded-For entry is the visitor). A plain env var, but
+//       the in-cloud upgrader rolls with the env contract of the release it
+//       runs from (the installed one), which does not set it — so the new
+//       gateway would not start. The operator-identity upgrade runs the new
+//       release's contract and sets it.
+//   8 — #875: the quality-audit job, its service account, the audit results
+//       bucket and their grants, plus CAELO_AUDIT_JOB /
+//       CAELO_AUDIT_RESULTS_BUCKET on the admin. The new admin fans every
+//       Stage audit out to that job, and the app-roll moves the job's image,
+//       so it must exist before an in-cloud upgrader rolls onto it.
 
 /**
  * What each contract version adds, in operator terms — the upgrader's
@@ -58,6 +69,8 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   4: "the admin's permission to serve redirects from the load balancer (#587)",
   5: "the gateway's cms_admin login removed from its env and IAM (#635)",
   6: "the upgrader's permission to list its ops bucket (#799)",
+  7: "the gateway's trusted proxy hop count, CAELO_TRUSTED_PROXY_HOPS (#845)",
+  8: "the quality-audit job, its service account, results bucket and grants (#875)",
 };
 
 /**