@caelo-cms/provisioning 0.10.49 → 0.10.51

package/src/staging-admin.ts

@@ -3,51 +3,25 @@
 /**
  * #678 — `staging-domain enable` tells the admin itself what the operator
  * decided, instead of printing "now set the same host in the admin".
- *
- * Why an HTTP call to the admin (and not a one-shot Cloud Run job like the
- * migrations): the call must hand a result BACK — above all the generated
- * basic-auth password, which the CLI prints once. A job can only report
- * through Cloud Logging, which would put the password into the project's
- * logs. The admin endpoint (`POST /api/internal/staging/provision`) answers
- * over TLS straight to this process, and the password is never written
- * anywhere (CLAUDE.md §7, #659).
- *
- * Getting there, as the operator's own gcloud identity — the same path the
- * Power-MCP shim takes (packages/mcp-server/src/ingress-auth.ts):
- *
- *   1. the admin Cloud Run service and its URL;
- *   2. the install's internal secret from Secret Manager (in memory only),
- *      which signs a 5-minute token for scope `staging.provision`;
- *   3. a JWT signed as `caelo-mcp@<project>` through the IAM Credentials
- *      API — the admin's IAP lets that service account in, and every
- *      IAP-allowlisted operator may sign as it (`cms-provision upgrade`
- *      grants it) — so the request passes IAP first, then Caelo's token.
+ * It calls `POST /api/internal/staging/provision` through admin-internal.ts
+ * (IAP as caelo-mcp + the internal token, scope `staging.provision`), because
+ * the answer carries the generated basic-auth password back to the CLI, which
+ * prints it once and never stores it.
  */
 
-import { findService } from "./admin-domain.js";
-import { gcloud as defaultGcloud, type GcloudResult } from "./gcloud.js";
-import { GCP_STACK_ENV, gcpSecretId, mcpIapServiceAccountEmail } from "./gcp-names.js";
-import { mintInternalToken } from "./internal-token.js";
-
-type Run = (args: string[]) => Promise<GcloudResult>;
+import {
+  type AdminInternalDeps,
+  type AdminInternalResult,
+  type AdminInternalTarget,
+  callAdminInternal,
+} from "./admin-internal.js";
 
 /** Token scope the admin endpoint checks (apps/admin …/api/internal/staging/provision). */
 export const STAGING_PROVISION_SCOPE = "staging.provision";
 const ENDPOINT = "/api/internal/staging/provision";
-/** Signed JWTs live at most 1 hour; one call needs a few seconds. */
-const IAP_JWT_LIFETIME_S = 600;
 
-export interface StagingAdminTarget {
-  readonly projectId: string;
-  readonly region: string;
-}
-
-export interface StagingAdminDeps {
-  readonly run?: Run;
-  readonly fetch?: typeof fetch;
-  /** Seconds since epoch (IAP JWT); tests pin it. */
-  readonly now?: () => number;
-}
+export type StagingAdminTarget = AdminInternalTarget;
+export type StagingAdminDeps = AdminInternalDeps;
 
 /** Main's draft pages, as the admin reports them. */
 export interface DraftPages {
@@ -80,7 +54,7 @@ export interface StagingApply {
   readonly draftPages: DraftPages;
 }
 
-export type StagingAdminResult<T> = { ok: true; value: T } | { ok: false; error: string };
+export type StagingAdminResult<T> = AdminInternalResult<T>;
 
 export interface ApplyRequest {
   readonly host?: string;
@@ -110,149 +84,12 @@ async function callStagingAdmin<T>(
   body: Record<string, unknown>,
   deps: StagingAdminDeps,
 ): Promise<StagingAdminResult<T>> {
-  const run = deps.run ?? defaultGcloud;
-  const doFetch = deps.fetch ?? fetch;
-  const scope = [`--region=${target.region}`, `--project=${target.projectId}`];
-
-  const found = await findService(run, scope, "admin");
-  if (!found.ok) return { ok: false, error: found.error };
-  const url = await run([
-    "run",
-    "services",
-    "describe",
-    found.service,
-    ...scope,
-    "--format=value(status.url)",
-  ]);
-  const adminUrl = url.stdout.trim();
-  if (!url.ok || !adminUrl) {
-    return { ok: false, error: `read the admin's URL: ${url.stderr.trim() || "empty"}` };
-  }
-
-  const secretId = gcpSecretId(GCP_STACK_ENV, "internal-secret");
-  const secret = await run([
-    "secrets",
-    "versions",
-    "access",
-    "latest",
-    `--secret=${secretId}`,
-    `--project=${target.projectId}`,
-  ]);
-  const internalSecret = secret.stdout.trim();
-  if (!secret.ok || internalSecret.length < 32) {
-    return {
-      ok: false,
-      error: `read the install's internal secret (${secretId}) from Secret Manager: ${secret.stderr.trim() || "missing or too short"}. Your gcloud account needs secretmanager.versions.access on the project.`,
-    };
-  }
-
-  // Installs from before #678 may not have the IAM Credentials API on;
-  // enabling an enabled API is a no-op (codex review on #681).
-  const api = await run([
-    "services",
-    "enable",
-    "iamcredentials.googleapis.com",
-    `--project=${target.projectId}`,
-  ]);
-  if (!api.ok) {
-    return {
-      ok: false,
-      error: `enable the IAM Credentials API (iamcredentials.googleapis.com), needed to pass the admin's IAP: ${api.stderr.trim()}`,
-    };
-  }
-  const iap = await signIapJwt(run, doFetch, target.projectId, adminUrl, deps.now);
-  if (!iap.ok) return iap;
-
-  const token = await mintInternalToken(internalSecret, STAGING_PROVISION_SCOPE);
-  let res: Response;
-  try {
-    res = await doFetch(`${adminUrl}${ENDPOINT}`, {
-      method: "POST",
-      headers: {
-        authorization: `Bearer ${iap.value}`,
-        "x-caelo-internal-token": token,
-        "content-type": "application/json",
-      },
-      body: JSON.stringify(body),
-    });
-  } catch (e) {
-    return { ok: false, error: `reach the admin at ${adminUrl}: ${String(e)}` };
-  }
-  const text = await res.text();
-  if (res.headers.get("x-goog-iap-generated-response") === "true") {
-    return {
-      ok: false,
-      error: `Google IAP refused the request (HTTP ${res.status}: ${text.trim().slice(0, 200)}) — ${mcpIapServiceAccountEmail(target.projectId)} is not allowed on the admin's IAP yet. Run \`cms-provision upgrade\` (it allowlists that service account), then run this command again.`,
-    };
-  }
-  if (res.status === 404) {
-    return {
-      ok: false,
-      error: `the admin has no ${ENDPOINT} yet (it runs a release from before #678). Run \`cms-provision upgrade\`, then run this command again.`,
-    };
-  }
-  let parsed: { ok?: boolean; error?: string } & Record<string, unknown>;
-  try {
-    parsed = JSON.parse(text) as typeof parsed;
-  } catch {
-    return {
-      ok: false,
-      error: `the admin answered HTTP ${res.status} with a non-JSON body: ${text.slice(0, 200)}`,
-    };
-  }
-  if (!res.ok || parsed.ok !== true) {
-    return {
-      ok: false,
-      error: `the admin refused (HTTP ${res.status}): ${parsed.error ?? text.slice(0, 300)}`,
-    };
-  }
-  return { ok: true, value: parsed as unknown as T };
-}
-
-/** A JWT signed as the install's MCP service account, for the admin's IAP. */
-async function signIapJwt(
-  run: Run,
-  doFetch: typeof fetch,
-  projectId: string,
-  adminUrl: string,
-  now: (() => number) | undefined,
-): Promise<StagingAdminResult<string>> {
-  const access = await run(["auth", "print-access-token"]);
-  const accessToken = access.stdout.trim();
-  if (!access.ok || !accessToken) {
-    return {
-      ok: false,
-      error: `get an access token from gcloud: ${access.stderr.trim() || "empty"}. Run \`gcloud auth login\` with the account you provisioned with.`,
-    };
-  }
-  const serviceAccount = mcpIapServiceAccountEmail(projectId);
-  const iat = now ? now() : Math.floor(Date.now() / 1000);
-  const res = await doFetch(
-    `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${encodeURIComponent(serviceAccount)}:signJwt`,
-    {
-      method: "POST",
-      headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
-      body: JSON.stringify({
-        payload: JSON.stringify({
-          iss: serviceAccount,
-          sub: serviceAccount,
-          aud: `${new URL(adminUrl).origin}/*`,
-          iat,
-          exp: iat + IAP_JWT_LIFETIME_S,
-        }),
-      }),
-    },
+  const r = await callAdminInternal<T>(
+    target,
+    { endpoint: ENDPOINT, scope: STAGING_PROVISION_SCOPE, body, introducedBy: "#678" },
+    deps,
   );
-  if (!res.ok) {
-    const detail = (await res.text().catch(() => "")).slice(0, 300);
-    return {
-      ok: false,
-      error: `sign an IAP token as ${serviceAccount} (HTTP ${res.status}): ${detail} — your account needs roles/iam.serviceAccountTokenCreator on it; \`cms-provision upgrade\` grants it to everyone the admin's IAP lets in.`,
-    };
-  }
-  const { signedJwt } = (await res.json()) as { signedJwt?: string };
-  if (!signedJwt) return { ok: false, error: "IAM signJwt answered without a signedJwt" };
-  return { ok: true, value: signedJwt };
+  return r.ok ? { ok: true, value: r.value.answer } : r;
 }
 
 /**

package/src/tar-entries.test.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bunHostRunner } from "./self-hosted-release.js";
+import { escapesRoot, listTarEntries, normalizeMemberName } from "./tar-entries.js";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "caelo-tar-test-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe("listTarEntries", () => {
+  it("reads files, directories, symlinks and long (>100 byte) names from the host's tar", async () => {
+    const root = join(dir, "src");
+    const long = `${"d".repeat(60)}/${"e".repeat(60)}/${"f".repeat(30)}.txt`;
+    mkdirSync(join(root, long, ".."), { recursive: true });
+    writeFileSync(join(root, long), "x");
+    writeFileSync(join(root, "ä-ü.txt"), "umlaut");
+    symlinkSync("target", join(root, "link"));
+    const out = join(dir, "a.tar");
+    const r = await bunHostRunner.run(["tar", "-cf", out, "-C", root, "."], {
+      env: { COPYFILE_DISABLE: "1" },
+    });
+    expect(r.exitCode).toBe(0);
+    const entries = listTarEntries(readFileSync(out));
+    const byName = new Map(entries.map((e) => [normalizeMemberName(e.name), e]));
+    expect(byName.get(long)?.type).toBe("file");
+    expect(byName.get("ä-ü.txt")?.type).toBe("file");
+    expect(byName.get("d".repeat(60))?.type).toBe("directory");
+    expect(byName.get("link")).toMatchObject({ type: "symlink", linkTarget: "target" });
+  });
+
+  it("refuses a truncated archive instead of skipping members", () => {
+    const header = new Uint8Array(512);
+    header.set(new TextEncoder().encode("a.txt"), 0);
+    header.set(new TextEncoder().encode("00000001000\0"), 124); // 512 bytes of data, none present
+    header[156] = "0".charCodeAt(0);
+    expect(() => listTarEntries(header)).toThrow(/truncated/);
+  });
+});
+
+describe("escapesRoot", () => {
+  it("flags absolute and parent-relative member names", () => {
+    expect(escapesRoot("/etc/passwd")).toBe(true);
+    expect(escapesRoot("srv/caelo/../../app")).toBe(true);
+    expect(escapesRoot("./srv/caelo/a..b")).toBe(false);
+  });
+});

package/src/tar-entries.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Read the member list of a tar archive WITHOUT extracting it, so a restore
+ * can refuse an archive before `tar -x` writes anything (PR #755 review: an
+ * absolute or `../` member, or a member written through a symlink, would
+ * otherwise land outside the target directory).
+ *
+ * Parses ustar headers plus the two extensions GNU tar and bsdtar emit for
+ * long names: GNU `L`/`K` records and pax `x`/`g` records (`path=`,
+ * `linkpath=`). Anything it cannot read is an error, never a skipped member.
+ */
+
+const BLOCK = 512;
+
+export type TarEntryType = "file" | "directory" | "symlink" | "other";
+
+export interface TarEntry {
+  readonly name: string;
+  readonly type: TarEntryType;
+  /** The link target, for symlinks. */
+  readonly linkTarget?: string;
+}
+
+/** Every member of an (uncompressed) tar archive, in archive order. */
+export function listTarEntries(tar: Uint8Array): TarEntry[] {
+  const entries: TarEntry[] = [];
+  let offset = 0;
+  let longName: string | null = null;
+  let longLink: string | null = null;
+  let paxPath: string | null = null;
+  let paxLink: string | null = null;
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK);
+    if (header.every((b) => b === 0)) break; // end-of-archive marker
+    const size = octal(header.subarray(124, 136));
+    const typeflag = String.fromCharCode(header[156] ?? 0);
+    const body = tar.subarray(offset + BLOCK, offset + BLOCK + size);
+    if (body.length < size) throw new Error("truncated tar archive");
+    offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+
+    if (typeflag === "L") {
+      longName = cString(body);
+      continue;
+    }
+    if (typeflag === "K") {
+      longLink = cString(body);
+      continue;
+    }
+    if (typeflag === "x" || typeflag === "g") {
+      const pax = paxRecords(body);
+      if (typeflag === "x") {
+        paxPath = pax.path ?? null;
+        paxLink = pax.linkpath ?? null;
+      }
+      continue;
+    }
+    const prefix = cString(header.subarray(345, 500));
+    const shortName = cString(header.subarray(0, 100));
+    const name = paxPath ?? longName ?? (prefix ? `${prefix}/${shortName}` : shortName);
+    const link = paxLink ?? longLink ?? cString(header.subarray(157, 257));
+    longName = longLink = paxPath = paxLink = null;
+    const type: TarEntryType =
+      typeflag === "0" || typeflag === "\0" || typeflag === "7"
+        ? "file"
+        : typeflag === "5"
+          ? "directory"
+          : typeflag === "2"
+            ? "symlink"
+            : "other";
+    entries.push(type === "symlink" ? { name, type, linkTarget: link } : { name, type });
+  }
+  return entries;
+}
+
+/** `./a/b/` → `a/b`; the archive root (`./`) → "". */
+export function normalizeMemberName(name: string): string {
+  return name.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+}
+
+/** Whether a member name could write outside the extraction directory. */
+export function escapesRoot(name: string): boolean {
+  return name.startsWith("/") || name.split("/").some((part) => part === "..");
+}
+
+function octal(field: Uint8Array): number {
+  const text = cString(field).trim();
+  if (text === "") return 0;
+  if (!/^[0-7]+$/.test(text)) throw new Error(`unreadable tar header size ${JSON.stringify(text)}`);
+  return Number.parseInt(text, 8);
+}
+
+function cString(bytes: Uint8Array): string {
+  const end = bytes.indexOf(0);
+  return new TextDecoder().decode(end === -1 ? bytes : bytes.subarray(0, end));
+}
+
+/** pax records: `<len> <key>=<value>\n`, repeated; `<len>` counts bytes. */
+function paxRecords(body: Uint8Array): Record<string, string> {
+  const out: Record<string, string> = {};
+  const decode = (b: Uint8Array) => new TextDecoder().decode(b);
+  let i = 0;
+  while (i < body.length && body[i] !== 0) {
+    const space = body.indexOf(0x20, i);
+    if (space === -1) throw new Error("unreadable pax header");
+    const len = Number.parseInt(decode(body.subarray(i, space)), 10);
+    if (!Number.isFinite(len) || len <= 0 || i + len > body.length) {
+      throw new Error("unreadable pax header");
+    }
+    const record = decode(body.subarray(space + 1, i + len - 1));
+    const eq = record.indexOf("=");
+    if (eq !== -1) out[record.slice(0, eq)] = record.slice(eq + 1);
+    i += len;
+  }
+  return out;
+}

package/src/upgrade/converge.ts

@@ -5,8 +5,9 @@
  * service accounts, secrets or other cloud resources so the install matches
  * what the release's stacks declare — the gateway's run SA and the
  * CLI-generated runtime secrets, the stack's IAM/CDN/firewall invariants,
- * MCP access through IAP, the gateway's and public_role's database logins,
- * the operator-access sync job, and dropping bindings nothing reads any more.
+ * MCP access through IAP, public_role's Cloud SQL role memberships (#633),
+ * the gateway's and public_role's database logins, the operator-access sync
+ * job, and dropping bindings nothing reads any more.
  *
  * It needs the rights of whoever provisioned the install, so only
  * `cms-provision upgrade` (the operator's own identity) runs it — never the
@@ -33,6 +34,7 @@ import { upgraderServiceAccountEmail } from "../gcp-names.js";
 import type { InstallMetadata } from "../install-state.js";
 import { ensureMcpIapAccess, type IapResource } from "../mcp-iap.js";
 import { ensureOperatorAccessSync, resolveOperatorAccessTarget } from "../operator-access.js";
+import { revokePublicRoleMemberships } from "../public-role-isolation.js";
 import {
   ensureGatewayServiceAccount,
   ensureGeneratedSecrets,
@@ -52,6 +54,7 @@ import {
   removeRetiredIamBindings,
 } from "../stack-converge.js";
 import { ensureUpgraderJob, resolveUpgraderTarget } from "../upgrader-setup.js";
+import { ensureUrlMapRedirectsAccess } from "../url-map-redirects-access.js";
 import type { AppRollHooks, AppRollPlan, RollPlan, RollSlug } from "./app-roll.js";
 import type { UpgradeReporter } from "./reporter.js";
 
@@ -90,8 +93,8 @@ export interface ConvergeDeps {
 
 export interface ConvergeSession {
   /**
-   * Before the app-roll: runtime identities + secrets, stack invariants, MCP
-   * access. False when a step the install cannot work without failed —
+   * Before the app-roll: runtime identities + secrets, stack invariants,
+   * public_role's Cloud SQL role memberships (#633), MCP access. False when a step the install cannot work without failed —
    * nothing app-side changed then.
    */
   beforeAppRoll(): Promise<boolean>;
@@ -195,6 +198,25 @@ export function startConverge(
     return true;
   }
 
+  async function publicRoleIsolation(): Promise<boolean> {
+    // #633 — the Admin API made public_role a member of cloudsqlsuperuser.
+    // Revoked here, before migrations, because the migration job's role
+    // audit is what verifies it and fails the upgrade while it remains.
+    const s = r.step("Removing public_role from the Cloud SQL superuser group...");
+    const outcome = await revokePublicRoleMemberships(
+      { projectId: install.projectId, env: install.env },
+      runDeps,
+    );
+    if (outcome.status === "failed") {
+      s.failed("public_role's role memberships could not be revoked. Aborting upgrade.");
+      r.error(`  ${outcome.error ?? ""}`);
+      r.warn("No traffic was shifted and no migrations ran. Fix the above and re-run.");
+      return false;
+    }
+    s.done(`public_role holds no database roles (${outcome.detail ?? "revoked"})`);
+    return true;
+  }
+
   async function mcpAccess(): Promise<void> {
     // Issue #37 — the MCP service account + its IAP/token-creator bindings.
     // Also what the deep health check signs its IAP credential as. A failure
@@ -227,6 +249,29 @@ export function startConverge(
     leaveUntouched.push(MCP_ENV_VAR);
   }
 
+  async function urlMapRedirectsAccess(): Promise<void> {
+    // #587 — on `gcp` the admin writes the redirects table into the URL map
+    // on Confirm-publish, through a custom role the stack declares. Without
+    // it Confirm-publish fails loudly (403); the rest of the install works,
+    // so a failure here warns.
+    if (install.provider !== "gcp") return;
+    const s = r.step("Ensuring the admin may write redirects into the URL map...");
+    const access = await ensureUrlMapRedirectsAccess({
+      projectId: install.projectId,
+      env: install.env,
+      ...runDeps,
+    });
+    if (access.ok) {
+      s.done(`URL-map redirects role ready (${access.role})`);
+      return;
+    }
+    s.warned(`URL-map redirects role not set up: ${access.error}`);
+    r.warn(
+      "The upgrade continues; Confirm-publish fails with a permission error until this succeeds. Re-run upgrade with an account that may manage IAM roles.",
+    );
+    incomplete = true;
+  }
+
   /** The admin's IAP resource: the service on gcp-firebase, the LB backend on gcp. */
   async function adminIapResource(): Promise<IapResource | null> {
     if (install.provider === "gcp-firebase") {
@@ -372,7 +417,9 @@ export function startConverge(
       if (deps.provisionerIdentity && !(await deps.provisionerIdentity())) return false;
       if (!(await runtimeIdentities())) return false;
       if (!(await stackInvariants())) return false;
+      if (!(await publicRoleIsolation())) return false;
       await mcpAccess();
+      await urlMapRedirectsAccess();
       return true;
     },
 

package/src/upgrade/upgrade.test.ts

@@ -179,6 +179,9 @@ const TARGET: GcpUpgradeTarget = {
   skipHealthCheck: false,
 };
 
+/** The same install on the `gcp` provider (load balancer + URL map). */
+const GCP_TARGET: GcpUpgradeTarget = { ...TARGET, provider: "gcp" };
+
 function upgradeDeps(
   events: string[],
   opts: { overrides?: [RegExp, Answer][]; deep?: HealthOutcome } = {},
@@ -217,7 +220,7 @@ function upgradeDeps(
 
 /** Calls that change IAM, service accounts, secrets or APIs — converge-only. */
 const CONVERGE_WRITE =
-  /add-iam-policy-binding|remove-iam-policy-binding|set-iam-policy|service-accounts create|secrets create|secrets versions add|services enable|roles create|firewall-rules delete/;
+  /add-iam-policy-binding|remove-iam-policy-binding|set-iam-policy|service-accounts create|secrets create|secrets versions add|services enable|roles create|roles update|roles undelete|firewall-rules delete|users assign-roles/;
 /** Calls that move a service or run migrations — app-roll-only. */
 const APP_ROLL_WRITE =
   /^run services update |^run services update-traffic|jobs execute caelo-migrate/;
@@ -383,6 +386,80 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     expect(calls.some((c) => c.includes("remove-iam-policy-binding"))).toBe(false);
   });
 
+  it("revokes public_role's Cloud SQL role memberships before the migrations audit them (#633)", async () => {
+    const events: string[] = [];
+    const { deps, lines } = upgradeDeps(events);
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    const revoke = indexOf(
+      events,
+      /^gcloud sql users assign-roles public_role --instance=caelo-production-pg-abc --type=BUILT_IN --revoke-existing-roles --project=acme/,
+    );
+    expect(indexOf(events, /^gcloud sql backups create/)).toBeLessThan(revoke);
+    expect(revoke).toBeLessThan(indexOf(events, /^migrate /));
+    expect(lines).toContain(
+      "done: public_role holds no database roles (no database roles left on caelo-production-pg-abc)",
+    );
+  });
+
+  it("a refused public_role revoke stops the upgrade before migrations and any roll (#633)", async () => {
+    const events: string[] = [];
+    const { deps, calls, lines } = upgradeDeps(events, {
+      overrides: [[/^sql users assign-roles public_role/, fail("PERMISSION_DENIED: no")]],
+    });
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(false);
+    expect(events.some((e) => e.startsWith("migrate"))).toBe(false);
+    expect(calls.filter((c) => APP_ROLL_WRITE.test(c))).toEqual([]);
+    expect(lines).toContain(
+      "failed: public_role's role memberships could not be revoked. Aborting upgrade.",
+    );
+  });
+
+  it("on gcp, runs both contract steps: the public_role revoke (3) and the URL-map redirects role (4)", async () => {
+    const events: string[] = [];
+    const { deps, lines } = upgradeDeps(events, {
+      overrides: [[/^iam roles describe/, fail("NOT_FOUND: role")]],
+    });
+    expect(await upgradeGcpInstall({ ...GCP_TARGET, infraContractVersion: 4 }, deps)).toBe(true);
+    const revoke = indexOf(events, /^gcloud sql users assign-roles public_role /);
+    const role = indexOf(
+      events,
+      /^gcloud iam roles create caelo_production_urlMapRedirects --project=acme .*--permissions=compute\.urlMaps\.list,/,
+    );
+    const grant = indexOf(
+      events,
+      /^gcloud projects add-iam-policy-binding acme --member=serviceAccount:caelo-production-run-sa@acme\.iam\.gserviceaccount\.com --role=projects\/acme\/roles\/caelo_production_urlMapRedirects /,
+    );
+    expect(revoke).toBeLessThan(indexOf(events, /^migrate /));
+    expect(role).toBeLessThan(grant);
+    expect(grant).toBeLessThan(indexOf(events, /^migrate /));
+    expect(lines).toContain(
+      "done: URL-map redirects role ready (projects/acme/roles/caelo_production_urlMapRedirects)",
+    );
+    // (This fake models gcp-firebase's listings, so gcp-only steps such as
+    // the default-firewall cleanup stay incomplete; the role step is not.)
+    expect(lines.some((l) => l.includes("URL-map redirects role not set up"))).toBe(false);
+  });
+
+  it("on gcp, a refused redirects role leaves the converge incomplete: contract 4 is not recorded", async () => {
+    const events: string[] = [];
+    const { deps, lines, recorded } = upgradeDeps(events, {
+      overrides: [
+        [/^iam roles describe/, fail("NOT_FOUND: role")],
+        [/^iam roles create/, fail("PERMISSION_DENIED: iam.roles.create")],
+      ],
+    });
+    expect(await upgradeGcpInstall({ ...GCP_TARGET, infraContractVersion: 4 }, deps)).toBe(true);
+    expect(lines.some((l) => l.startsWith("warned: URL-map redirects role not set up"))).toBe(true);
+    expect(recorded.contract).toEqual([]);
+  });
+
+  it("on gcp-firebase there is no URL map: no redirects role", async () => {
+    const events: string[] = [];
+    const { deps, calls } = upgradeDeps(events);
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    expect(calls.some((c) => c.includes("urlMapRedirects"))).toBe(false);
+  });
+
   it("runs the keyless-provisioner step as the first converge step; its failure stops before migrations", async () => {
     const events: string[] = [];
     const { deps, calls } = upgradeDeps(events);

package/src/upgrader-assess.test.ts

@@ -113,6 +113,28 @@ const ROWS: readonly Row[] = [
     expect: "needs_cloud_shell/infra-contract",
     reasonContains: "Cloud Shell",
   },
+  {
+    name: "contract 2 → 4 names both pending steps (#633, #587)",
+    manifest: verified({ infraContractVersion: 4 }),
+    installed: { version: "0.10.45", infraContractVersion: 2 },
+    expect: "needs_cloud_shell/infra-contract",
+    reasonContains:
+      "infrastructure contract 2 → 4: public_role out of the Cloud SQL superuser group (#633); the admin's permission to serve redirects from the load balancer (#587)",
+  },
+  {
+    name: "contract 3 → 4 names only the redirects role (#587)",
+    manifest: verified({ infraContractVersion: 4 }),
+    installed: { version: "0.10.45", infraContractVersion: 3 },
+    expect: "needs_cloud_shell/infra-contract",
+    reasonContains:
+      "infrastructure contract 3 → 4: the admin's permission to serve redirects from the load balancer (#587))",
+  },
+  {
+    name: "contract 4 installed, release at 4",
+    manifest: verified({ infraContractVersion: 4 }),
+    installed: { version: "0.10.45", infraContractVersion: 4 },
+    expect: "proceed",
+  },
   {
     name: "never converged at all",
     installed: { version: "0.10.45", infraContractVersion: 0 },

package/src/upgrader-assess.ts

@@ -47,6 +47,7 @@ import {
   type StoredUpdatePolicy,
   updateKind,
 } from "@caelo-cms/shared";
+import { infraStepsText } from "./infra-contract.js";
 import {
   assessAutoInstall,
   channelForVersion,
@@ -194,7 +195,7 @@ export function assessUpgradeRequest(input: {
     return stop(
       "needs_cloud_shell",
       "infra-contract",
-      `v${target} changes this install's cloud setup (infrastructure contract ${infraContractVersion} → ${manifest.infraContractVersion}). The admin may not change cloud permissions, so this release is installed once with your own Google account in Cloud Shell.`,
+      `v${target} changes this install's cloud setup (infrastructure contract ${infraContractVersion} → ${manifest.infraContractVersion}: ${infraStepsText(infraContractVersion, manifest.infraContractVersion)}). The admin may not change cloud permissions, so this release is installed once with your own Google account in Cloud Shell.`,
       manifest,
     );
   }