@caelo-cms/provisioning 0.10.51 → 0.10.53

package/src/self-hosted-roles.integration.test.ts

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: MPL-2.0
 
 /**
- * #613 review — `cms-provision up` on a self-hosted volume created before
- * the per-role passwords: no `gateway_role`, `public_role` on another
- * password. The convergence script, run as the superuser exactly as `up`
- * runs it (psql, script on stdin), must leave the roles on the configured
- * passwords with the gateway's grants in place — and be safe to re-run.
+ * #613 review, #635 — `cms-provision up` on a self-hosted volume from
+ * before: `public_role` on another password, and the gateway's former
+ * `gateway_role` login still there with its grants. The convergence
+ * script, run as the superuser exactly as `up` runs it (psql, script on
+ * stdin), must leave the roles on the configured passwords and the former
+ * gateway_role gone — and be safe to re-run.
  *
  * Runs against the test database with the passwords the environment already
  * uses, so the other suites' connection URLs keep working afterwards.
@@ -25,9 +26,8 @@ const required = [
   "POSTGRES_PORT",
   "ADMIN_ROLE_PASSWORD",
   "PUBLIC_ROLE_PASSWORD",
-  "GATEWAY_ROLE_PASSWORD",
   "ADMIN_DATABASE_URL",
-  "GATEWAY_DATABASE_URL",
+  "PUBLIC_DATABASE_URL",
 ] as const;
 const missing = required.filter((name) => !env[name]);
 if (missing.length > 0) throw new Error(`${missing.join(", ")} required (see .env.example)`);
@@ -63,19 +63,20 @@ const psql: SuperuserPsql = async (script) => {
 const passwords = {
   admin: env.ADMIN_ROLE_PASSWORD as string,
   public: env.PUBLIC_ROLE_PASSWORD as string,
-  gateway: env.GATEWAY_ROLE_PASSWORD as string,
 };
 
-describe("self-hosted role convergence against Postgres (#613 review)", () => {
-  it("brings a pre-#613 volume to the configured roles, grants and passwords — twice", async () => {
-    // The pre-#613 volume: no gateway_role, public_role on another password.
+describe("self-hosted role convergence against Postgres (#613 review, #635)", () => {
+  it("brings an old volume to the configured roles and passwords, without gateway_role — twice", async () => {
+    // The old volume: the former gateway_role with a cms_admin grant, and
+    // public_role on another password.
     const reset = await psql(
       [
         "\\set ON_ERROR_STOP on",
+        "SELECT 'CREATE ROLE gateway_role NOINHERIT LOGIN' WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'gateway_role') \\gexec",
+        "GRANT CONNECT ON DATABASE cms_admin TO gateway_role;",
         "\\connect cms_admin",
-        "DROP OWNED BY gateway_role;",
+        "GRANT SELECT (gateway_cookie_secret) ON site_settings TO gateway_role;",
         "\\connect postgres",
-        "DROP ROLE gateway_role;",
         "ALTER ROLE public_role WITH PASSWORD 'the-old-shared-password';",
         "",
       ].join("\n"),
@@ -87,36 +88,20 @@ describe("self-hosted role convergence against Postgres (#613 review)", () => {
       expect(r).toEqual({ ok: true });
     }
 
-    // The gateway logs in with its configured password and reads what 0248 grants.
-    const gateway = new SQL(env.GATEWAY_DATABASE_URL as string);
+    // public_role logs in with its configured password again.
+    const pub = new SQL(env.PUBLIC_DATABASE_URL as string);
     try {
-      const rows = (await gateway.begin(async (tx) => {
-        await tx.unsafe("SET LOCAL caelo.actor_kind = 'system'");
-        return tx`SELECT current_user::text AS u, length(gateway_cookie_secret) > 0 AS s FROM site_settings`;
-      })) as { u: string; s: boolean }[];
-      expect(rows[0]).toEqual({ u: "gateway_role", s: true });
+      const [who] = (await pub`SELECT current_user::text AS u`) as { u: string }[];
+      expect(who?.u).toBe("public_role");
     } finally {
-      await gateway.end();
+      await pub.end();
     }
+    // The former gateway_role is gone, with its grants (#635).
     const admin = new SQL(env.ADMIN_DATABASE_URL as string);
     try {
-      const [attrs] = (await admin`
-        SELECT rolcanlogin, rolinherit FROM pg_roles WHERE rolname = 'gateway_role'`) as {
-        rolcanlogin: boolean;
-        rolinherit: boolean;
-      }[];
-      expect(attrs).toEqual({ rolcanlogin: true, rolinherit: false });
-      const policies = (await admin`
-        SELECT policyname::text AS p FROM pg_policies WHERE 'gateway_role' = ANY (roles) ORDER BY 1`) as {
-        p: string;
-      }[];
-      expect(policies.map((p) => p.p)).toEqual([
-        "audit_events_gateway_plugin_only",
-        // #634 (migration 0252): the visitor paths' row limits. The A/B
-        // ones went with the experiment tables (#676, migration 0259).
-        "comment_archive_gateway_approved_only",
-        "rate_limit_buckets_gateway_keys",
-      ]);
+      const roles =
+        (await admin`SELECT 1 FROM pg_roles WHERE rolname = 'gateway_role'`) as unknown[];
+      expect(roles).toEqual([]);
     } finally {
       await admin.end();
     }

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

@@ -8,26 +8,30 @@ import {
   selfHostedBootstrapScript,
 } from "./self-hosted-roles.js";
 
-const PASSWORDS = { admin: "a'pw", public: "p-pw", gateway: "g-pw" };
+const PASSWORDS = { admin: "a'pw", public: "p-pw" };
 
 describe("roleConvergenceScript (#613 review)", () => {
   const script = roleConvergenceScript(PASSWORDS);
 
   it("creates missing roles and (re)sets every role's password, quoted", () => {
-    for (const role of ["admin_role", "public_role", "gateway_role"]) {
+    for (const role of ["admin_role", "public_role"]) {
       expect(script).toContain(
         `WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}')`,
       );
     }
     expect(script).toContain("ALTER ROLE admin_role WITH LOGIN PASSWORD 'a''pw';");
-    expect(script).toContain("ALTER ROLE gateway_role WITH LOGIN PASSWORD 'g-pw';");
+    expect(script).not.toContain("CREATE ROLE gateway_role");
   });
 
-  it("re-applies migration 0248's gateway grants in cms_admin, and stops on the first error", () => {
+  it("drops the former gateway_role with what it holds in both databases, and stops on the first error (#635)", () => {
     expect(script.startsWith("\\set ON_ERROR_STOP on")).toBe(true);
-    expect(script.indexOf("\\connect cms_admin")).toBeLessThan(
-      script.indexOf("PERFORM caelo_grant_gateway_role()"),
-    );
+    const publicDrop = script.indexOf("\\connect cms_public");
+    const adminDrop = script.indexOf("\\connect cms_admin");
+    expect(publicDrop).toBeGreaterThan(-1);
+    expect(adminDrop).toBeGreaterThan(publicDrop);
+    expect(script.match(/DROP OWNED BY gateway_role/g)).toHaveLength(2);
+    expect(script.indexOf("THEN DROP ROLE gateway_role;")).toBeGreaterThan(adminDrop);
+    expect(script).not.toContain("caelo_grant_gateway_role");
   });
 });
 

package/src/self-hosted-roles.ts

@@ -7,13 +7,14 @@
  * bootstrap.sh creates the application roles, but only on the Postgres
  * container's FIRST start (docker-entrypoint-initdb.d). An install created
  * before the per-role passwords has a data volume whose roles have other
- * passwords — and no `gateway_role` at all — so emitting Compose URLs with
- * the new passwords would lock the admin and the gateway out on the next
- * restart. `cms-provision up` therefore runs {@link roleConvergenceScript}
- * through the running container as the Postgres superuser BEFORE it writes
- * the new Compose file: it creates missing roles and databases, sets each
- * role's password to the configured one, and re-applies migration 0248's
- * gateway grants. Every statement is idempotent.
+ * passwords, so emitting Compose URLs with the new passwords would lock the
+ * admin and the gateway out on the next restart. `cms-provision up`
+ * therefore runs {@link roleConvergenceScript} through the running container
+ * as the Postgres superuser BEFORE it writes the new Compose file: it
+ * creates missing roles and databases and sets each role's password to the
+ * configured one. It also drops the former `gateway_role` (#635: the
+ * gateway has no cms_admin login), with whatever it still holds. Every
+ * statement is idempotent.
  *
  * Passwords travel on psql's stdin, never on argv.
  */
@@ -34,7 +35,7 @@ function literal(s: string): string {
 export const AGENT_DB_ROLE = "caelo_agent";
 
 /** The application roles bootstrap.sh and the convergence create. */
-const APP_ROLES = ["admin_role", "public_role", "gateway_role"] as const;
+const APP_ROLES = ["admin_role", "public_role"] as const;
 type AppRole = (typeof APP_ROLES)[number];
 
 /** How a role's password appears in the SQL: a literal, or a psql variable. */
@@ -69,12 +70,14 @@ function convergenceSql(password: PasswordSql, agent: boolean): string {
     "REVOKE ALL ON DATABASE cms_public FROM PUBLIC;",
     "GRANT CONNECT ON DATABASE cms_admin TO admin_role;",
     "GRANT CONNECT ON DATABASE cms_public TO public_role, admin_role;",
+    // #635 — the gateway's former cms_admin login goes, with whatever it
+    // still holds in either database (the superuser may drop what
+    // migration 0285 could only revoke).
+    "\\connect cms_public",
+    "DO $$ BEGIN IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'gateway_role') THEN DROP OWNED BY gateway_role; END IF; END $$;",
     "\\connect cms_admin",
-    // A database that ran migration 0248 before gateway_role existed has no
-    // grants for it yet; one that has not run it yet gets them from it.
-    "DO $$ BEGIN IF EXISTS (SELECT 1 FROM pg_proc WHERE proname = 'caelo_grant_gateway_role') THEN PERFORM caelo_grant_gateway_role(); END IF; END $$;",
-    // Migration 0251's staging-gate grants (issue #650), same convergence.
-    "DO $$ BEGIN IF EXISTS (SELECT 1 FROM pg_proc WHERE proname = 'caelo_grant_gateway_staging_access') THEN PERFORM caelo_grant_gateway_staging_access(); END IF; END $$;",
+    "DO $$ BEGIN IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'gateway_role') THEN DROP OWNED BY gateway_role; END IF; END $$;",
+    "DO $$ BEGIN IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'gateway_role') THEN DROP ROLE gateway_role; END IF; END $$;",
     // Migrations 0267 + 0270 (#696): the upgrader role's grants, applied
     // now that the role exists.
     "DO $$ BEGIN IF EXISTS (SELECT 1 FROM pg_proc WHERE proname = 'caelo_grant_platform_updater') THEN PERFORM caelo_grant_platform_updater(); END IF; END $$;",
@@ -84,7 +87,7 @@ function convergenceSql(password: PasswordSql, agent: boolean): string {
 
 /**
  * The psql script (run as the superuser, connected to any database) that
- * brings roles, databases and the gateway's grants to the configured state.
+ * brings roles and databases to the configured state.
  * Mirrors bootstrap.sh, plus the password reset bootstrap.sh never does.
  * With `agentPassword`, also the host agent's login (#696 Phase 4c).
  */
@@ -92,7 +95,6 @@ export function roleConvergenceScript(passwords: RolePasswords, agentPassword?:
   const byRole: Record<AppRole, string> = {
     admin_role: passwords.admin,
     public_role: passwords.public,
-    gateway_role: passwords.gateway,
   };
   return convergenceSql(
     (role) => literal(role === AGENT_DB_ROLE ? (agentPassword ?? "") : byRole[role]),
@@ -104,7 +106,6 @@ export function roleConvergenceScript(passwords: RolePasswords, agentPassword?:
 const PASSWORD_ENV: Record<AppRole | typeof AGENT_DB_ROLE, string> = {
   admin_role: "ADMIN_ROLE_PASSWORD",
   public_role: "PUBLIC_ROLE_PASSWORD",
-  gateway_role: "GATEWAY_ROLE_PASSWORD",
   [AGENT_DB_ROLE]: "AGENT_ROLE_PASSWORD",
 };
 

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

@@ -19,6 +19,7 @@ import {
   readRelease,
   recordRelease,
 } from "./self-hosted-release.js";
+import type { ConvergeOutcome } from "./self-hosted-roles.js";
 import {
   composePath,
   legacyComposePath,
@@ -121,11 +122,15 @@ beforeEach(() => {
 });
 afterEach(() => rmSync(dir, { recursive: true, force: true }));
 
-function deps(runner: HostRunner) {
+function deps(runner: HostRunner & { calls: string[] }, roles: ConvergeOutcome = { ok: true }) {
   return {
     caeloDir: dir,
     runner,
     renderCompose: render,
+    convergeRoles: async () => {
+      runner.calls.push("converge roles");
+      return roles;
+    },
     log,
     fetchImpl: registry,
     sleep: async () => {},
@@ -151,6 +156,7 @@ describe("upgradeSelfHosted", () => {
       "pull",
       "migrate admin",
       "migrate public",
+      "converge roles",
       "up caelo-admin",
       "health admin",
       "up caelo-gateway",
@@ -269,6 +275,27 @@ describe("upgradeSelfHosted", () => {
     expect(readFileSync(composePath(dir), "utf8")).toBe(render(OLD));
   });
 
+  it("converges the database roles on every upgrade, after the migrations (#635: drops gateway_role)", async () => {
+    const runner = fakeRunner();
+    expect((await upgradeSelfHosted({ version: "0.11.0" }, deps(runner))).ok).toBe(true);
+    const s = steps(runner.calls);
+    expect(s.indexOf("converge roles")).toBeGreaterThan(s.indexOf("migrate public"));
+    expect(s.indexOf("converge roles")).toBeLessThan(s.indexOf("up caelo-admin"));
+  });
+
+  it("restores the Compose file and restarts nothing when the role convergence fails", async () => {
+    const runner = fakeRunner();
+    const r = await upgradeSelfHosted(
+      { version: "0.11.0" },
+      deps(runner, { ok: false, reachable: true, error: "role is busy" }),
+    );
+    expect(r).toMatchObject({ ok: false, stage: "roles", previousRunning: true });
+    if (!r.ok) expect(r.error).toContain("role is busy");
+    expect(steps(runner.calls).some((x) => x.startsWith("up "))).toBe(false);
+    expect(readFileSync(composePath(dir), "utf8")).toBe(render(OLD));
+    expect(readRelease(dir)?.version).toBe("0.10.0");
+  });
+
   it("rolls back to the previous images when the gateway fails its health check", async () => {
     let compose = "";
     const runner = fakeRunner([

package/src/self-hosted-upgrade.ts

@@ -13,9 +13,15 @@
  *      the same `migrate.ts` entrypoint the GCP migrate job runs) while the
  *      old containers keep serving — migrations are expand-only, so the
  *      running release works on the new schema;
- *   5. recreate the admin, health-check it (`/_caelo/health`, which proves
+ *   5. converge the database roles (the same script `cms-provision up`
+ *      runs): bootstrap.sh only runs on the data volume's first start, so a
+ *      role a release retires — #635's gateway_role — is dropped here, on
+ *      every existing install. After the migrations, because the runner
+ *      refuses an install that skipped the release the old role's last user
+ *      was retired in (run-order.ts): past it, nothing running uses it;
+ *   6. recreate the admin, health-check it (`/_caelo/health`, which proves
  *      the DB pool and roles); then the gateway (`/healthz`);
- *   6. record the release in `.caelo/release.json`.
+ *   7. record the release in `.caelo/release.json`.
  * Any failure after step 3 puts the previous Compose file back; once a
  * container was recreated the previous images are started again and
  * health-checked (rollback). The database is never restored automatically:
@@ -52,6 +58,7 @@ import {
   releaseImages,
   resolveVerifiedRelease,
 } from "./self-hosted-release.js";
+import type { ConvergeOutcome } from "./self-hosted-roles.js";
 import { fetchLatestReleaseTag, RELEASE_SERVICES, releaseTag } from "./upgrade/release-images.js";
 
 /** The Compose service names of the two Caelo services. */
@@ -78,6 +85,11 @@ export interface SelfHostedUpgradeDeps {
   /** Renders the Compose file for `images` from the install's config (secrets included). */
   readonly renderCompose: (images: ReleaseImages) => string;
   readonly log: UpgradeLog;
+  /**
+   * Converges the database roles as the Postgres superuser
+   * (`convergeSelfHostedRoles`); drops roles a release retired (#635).
+   */
+  readonly convergeRoles: () => Promise<ConvergeOutcome>;
   readonly fetchImpl?: typeof fetch;
   readonly sleep?: (ms: number) => Promise<void>;
   readonly now?: () => Date;
@@ -116,6 +128,7 @@ type UpgradeStage =
   | "backup"
   | "pull"
   | "migrate"
+  | "roles"
   | "roll-admin"
   | "roll-gateway";
 
@@ -321,7 +334,19 @@ export async function upgradeSelfHosted(
     );
   }
 
-  // 5. Roll admin, then gateway, each health-checked.
+  // 5. Database roles: drops what this release retired (#635 gateway_role).
+  log.step("Converging the database roles");
+  const roles = await deps.convergeRoles();
+  if (!roles.ok) {
+    restoreCompose(file, previousCompose);
+    return fail(
+      "roles",
+      `Could not converge the database roles: ${roles.error}\nThe previous release keeps running; the migrations are applied (expand-only). Fix the cause and re-run the upgrade. Database backup: ${backup.dir}`,
+      true,
+    );
+  }
+
+  // 6. Roll admin, then gateway, each health-checked.
   for (const service of RELEASE_SERVICES) {
     const stage = service === "admin" ? "roll-admin" : "roll-gateway";
     log.phase?.("roll");
@@ -353,7 +378,7 @@ export async function upgradeSelfHosted(
     log.info(`${service} healthy ✓`);
   }
 
-  // 6. Record.
+  // 7. Record.
   log.phase?.("record");
   recordRelease(
     caeloDir,

package/src/stack-contract.test.ts

@@ -158,12 +158,21 @@ describe("gatewayEnvContract", () => {
       CAELO_PROVIDER: "gcp",
       CAELO_ENV: "production",
       MEDIA_STORAGE_URL: "gs://acme-caelo-production-media",
+      // #845 — gcp: the LB appends <client>,<LB IP>.
+      CAELO_TRUSTED_PROXY_HOPS: "2",
       PUBLIC_DATABASE_URL: "postgresql://public_role@10.20.0.3:5432/cms_public?sslmode=require",
       PUBLIC_DATABASE_PASSWORD: "secret:caelo-production-public-role-password:latest",
       CAELO_STAGING_GATE_SECRET: "secret:caelo-production-staging-gate-secret:latest",
     });
   });
 
+  it("#845 — tells the gateway its provider's proxy hop count", () => {
+    // Firebase Hosting / the domain mapping: Cloud Run's front end only.
+    const fb = asRecord(gatewayEnvContract({ ...base, provider: "gcp-firebase" }));
+    expect(fb.CAELO_TRUSTED_PROXY_HOPS).toBe("1");
+    expect(asRecord(gateway).CAELO_TRUSTED_PROXY_HOPS).toBe("2");
+  });
+
   it("#650 — reads the staging host from the database, not its env", () => {
     const fb = asRecord(gatewayEnvContract({ ...base, provider: "gcp-firebase" }));
     expect(fb.CAELO_STAGING_HOST).toBeUndefined();
@@ -223,14 +232,13 @@ describe("database role secrets (#613)", () => {
     expect(DATABASE_ROLE_SECRET).toEqual({
       admin_role: "postgres-password",
       public_role: "public-role-password",
-      gateway_role: "gateway-role-password",
     });
   });
 
-  it("the CLI generates the gateway's role passwords (never seeded from admin_role's)", () => {
-    expect(CLI_GENERATED_SECRETS).toEqual(
-      expect.arrayContaining(["public-role-password", "gateway-role-password"]),
-    );
+  it("the CLI generates the gateway's role password (never seeded from admin_role's)", () => {
+    expect(CLI_GENERATED_SECRETS).toContain("public-role-password");
+    // #635 — the former gateway_role is gone; nothing generates its password.
+    expect(CLI_GENERATED_SECRETS as readonly string[]).not.toContain("gateway-role-password");
   });
 
   it("retires the gateway SA's read access to admin_role's password", () => {
@@ -287,11 +295,7 @@ describe("runtime secrets", () => {
   });
 
   it("every CLI-generated secret is read by some service", () => {
-    // gateway-role-password is read by no service since #635: it only keeps
-    // the legacy gateway_role's password set until the contract release
-    // drops the role (the previous release's gateway logs in with it while
-    // an upgrade rolls).
-    for (const s of CLI_GENERATED_SECRETS.filter((x) => x !== "gateway-role-password")) {
+    for (const s of CLI_GENERATED_SECRETS) {
       expect([...serviceSecrets("admin"), ...serviceSecrets("gateway")]).toContain(s);
     }
   });
@@ -302,7 +306,7 @@ describe("self-hosted compose", () => {
     const yaml = generateDockerCompose({
       domain: "acme.com",
       postgresPassword: "p",
-      rolePasswords: { admin: "a", public: "b", gateway: "g" },
+      rolePasswords: { admin: "a", public: "b" },
       caeloSecretKek: "k",
       diskSize: "10G",
       ports: { http: 80, https: 443 },

package/src/stack-contract.ts

@@ -34,6 +34,7 @@
  * Pure module — the stacks import it from `dist/`.
  */
 
+import type { SupportedProvider } from "./adapter.js";
 import {
   gatewayServiceAccountEmail,
   gcpBucketName,
@@ -237,14 +238,13 @@ export function adminMediaVolumeTemplate(volume: MediaVolumeContract) {
 export type RuntimeSecret =
   | "postgres-password"
   | "public-role-password"
-  | "gateway-role-password"
   | "secret-kek"
   | "internal-secret"
   | "tool-approval-secret"
   | "staging-gate-secret";
 
 /** The Postgres roles Caelo's services log in as, with their passwords. */
-export type DatabaseRole = "admin_role" | "public_role" | "gateway_role";
+export type DatabaseRole = "admin_role" | "public_role";
 
 /**
  * Each database role's password secret — one per role (#613), so the
@@ -256,7 +256,6 @@ export type DatabaseRole = "admin_role" | "public_role" | "gateway_role";
 export const DATABASE_ROLE_SECRET: Readonly<Record<DatabaseRole, RuntimeSecret>> = {
   admin_role: "postgres-password",
   public_role: "public-role-password",
-  gateway_role: "gateway-role-password",
 };
 
 /**
@@ -269,10 +268,9 @@ export const DATABASE_ROLE_SECRET: Readonly<Record<DatabaseRole, RuntimeSecret>>
 export const CLI_GENERATED_SECRETS = [
   "internal-secret",
   "tool-approval-secret",
-  // #613 — the gateway's own role passwords. Generated (never seeded from
+  // #613 — the gateway's own role password. Generated (never seeded from
   // `postgres-password`), so the gateway never learns admin_role's.
   "public-role-password",
-  "gateway-role-password",
   // #650 — the staging access gate's key: signs "Open staging" links and
   // session cookies, derives the crawler credentials. Read by the admin
   // (issues) and the gateway (verifies).
@@ -358,6 +356,42 @@ function commonEnv(inputs: ServiceEnvInputs): CloudRunEnvVar[] {
   ];
 }
 
+/**
+ * The env var telling the gateway which `X-Forwarded-For` entry is the
+ * visitor (apps/api-gateway client-ip.ts): the number of entries the proxies
+ * in front of it append, counting the client's own.
+ */
+export const TRUSTED_PROXY_HOPS_ENV = "CAELO_TRUSTED_PROXY_HOPS";
+
+/**
+ * {@link TRUSTED_PROXY_HOPS_ENV} per provider — a property of each
+ * adapter's topology (CLAUDE.md §11.B), so it is declared here once and every
+ * adapter sets it on its gateway. The gateway refuses to boot without it.
+ * A change to an adapter's path to the gateway must update its entry, or
+ * rate limits pool every visitor (too high) or trust a forgeable entry (too
+ * low).
+ */
+export const GATEWAY_TRUSTED_PROXY_HOPS: Readonly<Record<SupportedProvider, number>> = {
+  // External Application LB appends `<client>,<LB IP>`; the gateway's
+  // ingress is internal-and-LB only, so nothing reaches it around the LB.
+  gcp: 2,
+  // Cloud Run's front end appends its peer. Behind the Firebase Hosting
+  // rewrite that peer is the Hosting CDN edge, and the entry Hosting adds
+  // before it cannot be told apart from a forged one (the service is
+  // invokable on *.run.app too) — so the edge address is the most that can
+  // be trusted. Staging (Cloud Run domain mapping) gets the visitor.
+  "gcp-firebase": 1,
+  // Caddy without `trusted_proxies` replaces the header with its peer; the
+  // gateway is reachable only on the Compose network.
+  "self-hosted": 1,
+  // CloudFront appends the viewer, the ALB appends CloudFront. (No ECS task
+  // definition consumes it yet — see stacks/aws.)
+  aws: 2,
+  // Container Apps ingress appends its peer; the gateway's ingress is
+  // internal to the environment (no Front Door route to it yet).
+  azure: 1,
+};
+
 /**
  * The env of the gateway service. Order is stable so the stacks see no
  * spurious diffs.
@@ -365,6 +399,7 @@ function commonEnv(inputs: ServiceEnvInputs): CloudRunEnvVar[] {
 export function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvVar<V | string>[] {
   return [
     ...commonEnv(inputs),
+    { name: TRUSTED_PROXY_HOPS_ENV, value: String(GATEWAY_TRUSTED_PROXY_HOPS[inputs.provider]) },
     { name: "PUBLIC_DATABASE_URL", value: inputs.databaseUrls.public },
     ...secretEnv("gateway", inputs.env),
   ];

package/src/stack-converge-secrets.test.ts

@@ -344,6 +344,8 @@ describe("upgrading a v0.10.35 install: the gateway leaves admin_role (#613)", (
       "ADMIN_DATABASE_URL",
       // #650 — the staging gate key arrives in the same roll.
       "CAELO_STAGING_GATE_SECRET",
+      // #845 — and which forwarded address is the visitor.
+      "CAELO_TRUSTED_PROXY_HOPS",
       "PUBLIC_DATABASE_PASSWORD",
     ]);
   });

package/src/stack-converge.test.ts

@@ -316,6 +316,8 @@ describe("planContractEnv", () => {
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     expect(plan.services.gateway.flags).toEqual([
+      // The gateway learns which forwarded address is the visitor (#845).
+      "--update-env-vars=CAELO_TRUSTED_PROXY_HOPS=1",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
   });

package/src/state-store.ts

@@ -162,6 +162,15 @@ export class GcsStateStore implements StateStore {
   }
 }
 
+/**
+ * Another run holds the install's state lock. Distinct from every other
+ * lock failure (no access, gcloud missing), which callers must not report
+ * as "busy" — retrying later will not fix those.
+ */
+export class StateLockHeldError extends Error {
+  override readonly name = "StateLockHeldError";
+}
+
 /** `gs://<bucket>/install/state.lock` — see {@link acquireBucketStateLock}. */
 export function bucketStateLockUrl(bucket: string): string {
   return `gs://${bucket}/${OPS_INSTALL_PREFIX}/state.lock`;
@@ -197,7 +206,7 @@ export function acquireBucketStateLock(
   if (!r.ok) {
     if (/PreconditionFailed|412|At least one of the pre-conditions/i.test(r.stderr)) {
       const held = run(["storage", "cat", url]);
-      throw new Error(
+      throw new StateLockHeldError(
         `Another run is changing this install's state (${held.ok ? held.stdout.trim() : url}). Re-run once it has finished; if none is running, remove the stale lock: gcloud storage rm ${url}`,
       );
     }
@@ -221,7 +230,7 @@ export function acquireLocalStateLock(root: string, purpose: string): () => void
     writeFileSync(path, lockBody(purpose), { flag: "wx", mode: 0o600 });
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === "EEXIST") {
-      throw new Error(
+      throw new StateLockHeldError(
         `Another run is changing this install's state (${readFileSync(path, "utf8").trim()}). Re-run once it has finished; if none is running, remove the stale lock: rm ${path}`,
       );
     }

package/src/upgrade/converge.ts

@@ -24,11 +24,7 @@
  * {@link AppRollHooks} the app-roll calls in between, and a part after it.
  */
 
-import {
-  ensureGatewayRolePassword,
-  findSqlInstance,
-  planPublicRoleSwitch,
-} from "../gateway-credentials.js";
+import { findSqlInstance, planPublicRoleSwitch } from "../gateway-credentials.js";
 import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
 import { upgraderServiceAccountEmail } from "../gcp-names.js";
 import type { InstallMetadata } from "../install-state.js";
@@ -291,10 +287,9 @@ export function startConverge(
   }
 
   async function databaseLogins(): Promise<boolean> {
-    // #613 — migration 0248 creates gateway_role without a password; it gets
-    // its secret's value before the gateway rolls onto it. public_role
-    // moves onto its own password right before the gateway's roll.
-    const s = r.step("Ensuring the gateway's database login (gateway_role)...");
+    // #613 — public_role moves onto its own password right before the
+    // gateway's roll. The gateway has no other database login (#635).
+    const s = r.step("Preparing the gateway's database login (public_role)...");
     const sqlInstance = await findSqlInstance(install, { run });
     if (!sqlInstance) {
       s.failed("Could not find the Cloud SQL instance. Aborting upgrade.");
@@ -303,16 +298,7 @@ export function startConverge(
     }
     const roleTarget = { projectId: install.projectId, env: install.env, sqlInstance };
     const roleDeps = { ...runDeps, ...(deps.http ? { http: deps.http } : {}) };
-    const gatewayRole = await ensureGatewayRolePassword(roleTarget, roleDeps);
-    if (gatewayRole.status === "failed") {
-      s.failed("gateway_role could not be given its password. Aborting upgrade.");
-      r.error(`  ${gatewayRole.error ?? ""}`);
-      r.warn(
-        "Migrations ran (0248 creates gateway_role); no traffic was shifted. Fix the above and re-run upgrade.",
-      );
-      return false;
-    }
-    s.done("gateway_role ready");
+    s.done("public_role ready to switch");
     publicRole = planPublicRoleSwitch(roleTarget, service("gateway").liveEnv, roleDeps);
     return true;
   }