@caelo-cms/provisioning 0.10.48 → 0.10.50

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

@@ -35,9 +35,12 @@ const POLICY: StoredUpdatePolicy = {
   windowEnd: null,
   windowTimezone: "UTC",
   soakHours: 24,
+  securitySoakHours: 2,
   paused: false,
   pausedReason: null,
   pausedAt: null,
+  pausedUntil: null,
+  pausedByOwner: false,
   updatedAt: "2026-10-13T00:00:00Z",
 };
 
@@ -57,6 +60,7 @@ interface Row {
   readonly manifest?: ReleaseManifestResult;
   readonly installed?: InstalledState;
   readonly trigger?: "manual" | "auto";
+  readonly autoBasis?: "security" | "patch" | "minor";
   readonly policy?: StoredUpdatePolicy;
   readonly target?: string;
   /** "proceed" or `<status>/<code>`. */
@@ -109,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 },
@@ -157,6 +183,39 @@ const ROWS: readonly Row[] = [
     manifest: verified({ security: true, advisories: ["GHSA-abcd-efgh-ijkm"] }),
     expect: "proceed",
   },
+  {
+    name: "automatic 'security' flag without a published advisory",
+    trigger: "auto",
+    policy: { ...POLICY, autoMinor: false, autoPatch: false },
+    manifest: verified({ security: true, advisories: [] }),
+    expect: "refused/policy",
+  },
+  {
+    name: "queued as a security fix, signed manifest says it is not one",
+    trigger: "auto",
+    autoBasis: "security",
+    expect: "refused/policy",
+    reasonContains: "names no published security advisory",
+  },
+  {
+    name: "queued as a security fix, signed manifest agrees",
+    trigger: "auto",
+    autoBasis: "security",
+    manifest: verified({ security: true, advisories: ["GHSA-abcd-efgh-ijkm"] }),
+    expect: "proceed",
+  },
+  {
+    name: "automatic, Owner pause already over",
+    trigger: "auto",
+    policy: {
+      ...POLICY,
+      paused: true,
+      pausedByOwner: true,
+      pausedAt: "2026-10-12T00:00:00Z",
+      pausedUntil: "2026-10-13T00:00:00Z",
+    },
+    expect: "proceed",
+  },
   {
     name: "automatic, outside the window",
     trigger: "auto",
@@ -175,7 +234,11 @@ const ROWS: readonly Row[] = [
 describe("assessUpgradeRequest — refusal matrix", () => {
   it.each(ROWS.map((r) => [r.name, r] as const))("%s", (_name, row) => {
     const d = assessUpgradeRequest({
-      request: { targetVersion: row.target ?? "0.11.0", trigger: row.trigger ?? "manual" },
+      request: {
+        targetVersion: row.target ?? "0.11.0",
+        trigger: row.trigger ?? "manual",
+        autoBasis: row.autoBasis ?? null,
+      },
       manifest: row.manifest ?? verified(),
       installed: row.installed ?? INSTALLED,
       policy: row.policy ?? POLICY,

package/src/upgrader-assess.ts

@@ -30,6 +30,7 @@
  * | contract (destructive) migrations, automatic run    | refused           |
  * | contract migrations, Owner's click                  | proceed + warning |
  * | automatic run the update policy does not allow      | refused           |
+ * | automatic "security" run, signed manifest disagrees | refused           |
  *
  * Self-hosted installs (the host agent, #696 Phase 4c) have no separately
  * converged infrastructure: their Compose file, roles and bootstrap script
@@ -40,11 +41,13 @@
  */
 
 import {
+  type AutoUpdateBasis,
   autoInstallRefusal,
   type PlatformUpdateTrigger,
   type StoredUpdatePolicy,
   updateKind,
 } from "@caelo-cms/shared";
+import { infraStepsText } from "./infra-contract.js";
 import {
   assessAutoInstall,
   channelForVersion,
@@ -119,7 +122,12 @@ const stop = (
 
 /** Decide what the job does with a request. See the file comment for the matrix. */
 export function assessUpgradeRequest(input: {
-  readonly request: { readonly targetVersion: string; readonly trigger: PlatformUpdateTrigger };
+  readonly request: {
+    readonly targetVersion: string;
+    readonly trigger: PlatformUpdateTrigger;
+    /** Why the admin's scheduler queued an automatic request (Phase 5). */
+    readonly autoBasis?: AutoUpdateBasis | null;
+  };
   readonly manifest: ReleaseManifestResult;
   readonly installed: InstalledState;
   readonly policy: StoredUpdatePolicy;
@@ -187,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,
     );
   }
@@ -228,6 +236,16 @@ export function assessUpgradeRequest(input: {
     if (refusal) {
       return stop("refused", "policy", `Not installed automatically: ${refusal}.`, manifest);
     }
+    // The scheduler read the manifest unverified; it may only have used the
+    // security fix's shorter soak period if the SIGNED manifest backs it.
+    if (request.autoBasis === "security" && assessment.kind !== "security") {
+      return stop(
+        "refused",
+        "policy",
+        `Not installed automatically: v${target} was queued as a security fix, but its signed release information names no published security advisory. Install it from Settings → Updates.`,
+        manifest,
+      );
+    }
   }
   return { kind: "proceed", manifest, warnings };
 }

package/src/upgrader-job.test.ts

@@ -53,9 +53,12 @@ const POLICY: StoredUpdatePolicy = {
   windowEnd: null,
   windowTimezone: "UTC",
   soakHours: 24,
+  securitySoakHours: 2,
   paused: false,
   pausedReason: null,
   pausedAt: null,
+  pausedUntil: null,
+  pausedByOwner: false,
   updatedAt: "2026-10-13T00:00:00Z",
 };
 

package/src/upgrader-job.ts

@@ -33,6 +33,7 @@
  */
 
 import type {
+  AutoUpdateBasis,
   PlatformUpdateEventLevel,
   PlatformUpdatePhase,
   PlatformUpdateTrigger,
@@ -61,6 +62,8 @@ export interface ClaimedUpdate {
   readonly id: string;
   readonly targetVersion: string;
   readonly trigger: PlatformUpdateTrigger;
+  /** Why the admin's scheduler queued an automatic request; null for the Owner's. */
+  readonly autoBasis?: AutoUpdateBasis | null;
   readonly policy: StoredUpdatePolicy;
 }
 

package/src/url-map-redirects-access.test.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #587 — `cms-provision upgrade` gives older `gcp` installs the admin's
+ * URL-map redirects role: create or update the custom role, undelete a
+ * soft-deleted one, bind it to the admin's run SA.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { GcloudResult } from "./gcloud.js";
+import { ensureUrlMapRedirectsAccess } from "./url-map-redirects-access.js";
+
+const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+
+/** The gcloud verb of a call (`projects add-iam-policy-binding` has it second). */
+const verb = (c: string[]) => (c[0] === "projects" ? c[1] : c[2]);
+
+function runner(answer: (args: string[]) => GcloudResult) {
+  const calls: string[][] = [];
+  return {
+    calls,
+    run: async (args: string[]) => {
+      calls.push(args);
+      return answer(args);
+    },
+  };
+}
+
+const PERMS =
+  "--permissions=compute.urlMaps.list,compute.urlMaps.get,compute.urlMaps.update,compute.backendBuckets.use,compute.backendServices.use,compute.globalOperations.get";
+const BIND = [
+  "projects",
+  "add-iam-policy-binding",
+  "p1",
+  "--member=serviceAccount:caelo-production-run-sa@p1.iam.gserviceaccount.com",
+  "--role=projects/p1/roles/caelo_production_urlMapRedirects",
+  "--condition=None",
+  "--quiet",
+  "--format=none",
+];
+
+describe("ensureUrlMapRedirectsAccess", () => {
+  it("creates the role when missing, then binds it", async () => {
+    const r = runner((a) => (a[2] === "describe" ? fail("NOT_FOUND") : ok()));
+    const out = await ensureUrlMapRedirectsAccess({
+      projectId: "p1",
+      env: "production",
+      run: r.run,
+    });
+    expect(out).toEqual({ ok: true, role: "projects/p1/roles/caelo_production_urlMapRedirects" });
+    expect(r.calls[1]?.slice(0, 5)).toEqual([
+      "iam",
+      "roles",
+      "create",
+      "caelo_production_urlMapRedirects",
+      "--project=p1",
+    ]);
+    expect(r.calls[1]).toContain(PERMS);
+    expect(r.calls[2]).toEqual(BIND);
+  });
+
+  it("updates an existing role to the current permissions (no drift)", async () => {
+    const r = runner((a) => (a[2] === "describe" ? ok('{"name":"x"}') : ok()));
+    await ensureUrlMapRedirectsAccess({ projectId: "p1", env: "production", run: r.run });
+    expect(r.calls.map(verb)).toEqual(["describe", "update", "add-iam-policy-binding"]);
+    expect(r.calls[1]).toContain(PERMS);
+  });
+
+  it("undeletes a soft-deleted role first", async () => {
+    const r = runner((a) => (a[2] === "describe" ? ok('{"deleted":true}') : ok()));
+    await ensureUrlMapRedirectsAccess({ projectId: "p1", env: "production", run: r.run });
+    expect(r.calls.map(verb)).toEqual(["describe", "undelete", "update", "add-iam-policy-binding"]);
+  });
+
+  it("reports a failure instead of throwing", async () => {
+    const r = runner((a) =>
+      a[2] === "describe" ? fail("NOT_FOUND") : fail("PERMISSION_DENIED: iam.roles.create"),
+    );
+    expect(
+      await ensureUrlMapRedirectsAccess({ projectId: "p1", env: "production", run: r.run }),
+    ).toEqual({
+      ok: false,
+      error:
+        "create projects/p1/roles/caelo_production_urlMapRedirects: PERMISSION_DENIED: iam.roles.create",
+    });
+  });
+});

package/src/url-map-redirects-access.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The admin's URL-map redirects role (#587) on `gcp` installs. The installer
+ * (wizards/gcp.ts) and `cms-provision upgrade` both call
+ * {@link ensureUrlMapRedirectsAccess}, so new and older installs get the same
+ * custom role + binding. The stack does not declare it: a role id exists once
+ * per project, so a stack-created role would collide with one upgrade made.
+ *
+ *   1. project custom role {@link urlMapRedirectsRoleId} with exactly
+ *      {@link URL_MAP_REDIRECTS_PERMISSIONS} (created, or updated to that
+ *      permission set; undeleted first if it was soft-deleted)
+ *   2. that role for the admin's run SA on the project
+ *
+ * Both steps are idempotent. Without them Confirm-publish fails with a 403
+ * when it writes the redirects into the URL map.
+ */
+
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud-retry.js";
+import {
+  runServiceAccountEmail,
+  URL_MAP_REDIRECTS_PERMISSIONS,
+  urlMapRedirectsRoleId,
+} from "./gcp-names.js";
+
+/** Ensure the custom role and the admin's binding; never throws for gcloud. */
+export async function ensureUrlMapRedirectsAccess(opts: {
+  readonly projectId: string;
+  readonly env: string;
+  readonly run?: GcloudRunner;
+  readonly sleep?: Sleep;
+}): Promise<{ ok: true; role: string } | { ok: false; error: string }> {
+  const run = opts.run ?? defaultGcloud;
+  const sleep = opts.sleep ?? realSleep;
+  const project = `--project=${opts.projectId}`;
+  const roleId = urlMapRedirectsRoleId(opts.env);
+  const role = `projects/${opts.projectId}/roles/${roleId}`;
+  const permissions = `--permissions=${URL_MAP_REDIRECTS_PERMISSIONS.join(",")}`;
+
+  const describe = await run(["iam", "roles", "describe", roleId, project, "--format=json"]);
+  if (describe.ok) {
+    const live = JSON.parse(describe.stdout) as { deleted?: boolean };
+    if (live.deleted) {
+      const undelete = await run(["iam", "roles", "undelete", roleId, project, "--quiet"]);
+      if (!undelete.ok) return { ok: false, error: `undelete ${role}: ${undelete.stderr.trim()}` };
+    }
+    const update = await run([
+      "iam",
+      "roles",
+      "update",
+      roleId,
+      project,
+      permissions,
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!update.ok) return { ok: false, error: `update ${role}: ${update.stderr.trim()}` };
+  } else {
+    const create = await run([
+      "iam",
+      "roles",
+      "create",
+      roleId,
+      project,
+      "--title=Caelo admin: URL-map redirects",
+      "--description=Lets the Caelo admin write the redirects table into the site's URL map (#587).",
+      permissions,
+      "--stage=GA",
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!create.ok) return { ok: false, error: `create ${role}: ${create.stderr.trim()}` };
+  }
+
+  // A just-created role takes a few seconds to become bindable.
+  const bind = await runWithRetry(run, sleep, [
+    "projects",
+    "add-iam-policy-binding",
+    opts.projectId,
+    `--member=serviceAccount:${runServiceAccountEmail(opts.projectId, opts.env)}`,
+    `--role=${role}`,
+    "--condition=None",
+    "--quiet",
+    "--format=none",
+  ]);
+  if (!bind.ok) return { ok: false, error: `grant ${role}: ${bind.stderr.trim()}` };
+  return { ok: true, role };
+}

package/src/wizard.ts

@@ -222,8 +222,10 @@ export async function runWizard(opts: WizardOptions = {}): Promise<void> {
       });
       break;
     case "self-hosted":
+      // The self-hosted install runs on the Docker host itself, from the
+      // directory that should hold `.caelo/` — not from this wizard.
       cancel(
-        `Self-hosted wizard is the existing \`cms-provision init\` flow. Run \`${selfCommand("init", "--domain", "...", "--owner-email", "...")}\` for now; wizard polish lands in a follow-up commit.`,
+        `Run this on the Docker host, in the directory that should hold the install:\n  ${selfCommand("--provider", "self-hosted", "--domain", domain, "--owner-email", ownerEmail)}`,
       );
       process.exit(0);
       break;

package/src/wizards/gcp.ts

@@ -99,6 +99,7 @@ import {
   PROVISIONER_ACCOUNT_ID,
   provisionerServiceAccountEmail,
 } from "../provisioner-identity.js";
+import { revokePublicRoleMemberships } from "../public-role-isolation.js";
 import { decideRegion, detectCliRegion, installableRegions, suggestRegion } from "../regions.js";
 import type { RunMode } from "../run-mode.js";
 import { selfCommand } from "../self-command.js";
@@ -120,6 +121,7 @@ import {
   verifyCosignAll,
 } from "../upgrade/release-images.js";
 import { ensureUpgraderJob, resolveUpgraderTarget } from "../upgrader-setup.js";
+import { ensureUrlMapRedirectsAccess } from "../url-map-redirects-access.js";
 import { estimateGcpCost } from "./gcp-cost.js";
 import { promptProjectId } from "./gcp-prompts.js";
 import { GCP_STACK_KNOB_DEFAULTS, pulumiUpGcp, readStackOutput } from "./gcp-pulumi.js";
@@ -430,6 +432,17 @@ export async function runGcpConverge(opts: GcpConvergeOpts): Promise<void> {
   // P21 ship 3 — shared with `cms-provision upgrade`. Aborts the
   // wizard with a clear error if migrations fail (vs. silently
   // continuing with a half-migrated DB).
+  // === 10.9. public_role out of cloudsqlsuperuser (#633) ===
+  // The stack creates public_role through the Cloud SQL Admin API, which
+  // makes it a member of cloudsqlsuperuser. Revoked before migrations: the
+  // migration job's role audit verifies it and fails the install otherwise.
+  await stepPublicRoleIsolation(projectId);
+
+  // === 10.95. The admin may write redirects into the URL map (#587) ===
+  // Confirm-publish writes the redirects table into the load balancer's URL
+  // map; the custom role is the CLI's, not the stack's (url-map-redirects-access.ts).
+  if (provider === "gcp") await stepUrlMapRedirectsAccess(projectId);
+
   phase("Applying database migrations");
   {
     const { runMigrationsViaCloudRunJob } = await import("../migration-runner.js");
@@ -886,6 +899,41 @@ async function stepGrantBaseRoles(
   markStepDone(installId, stepName, { granted });
 }
 
+/**
+ * Revoke the database roles the Cloud SQL Admin API gave `public_role`
+ * (cloudsqlsuperuser, #633). Idempotent, so it runs on every wizard pass;
+ * the migration job's role audit verifies the result.
+ */
+async function stepPublicRoleIsolation(projectId: string): Promise<void> {
+  const s = spinner();
+  s.start("Removing public_role from the Cloud SQL superuser group...");
+  const r = await revokePublicRoleMemberships({ projectId, env: GCP_STACK_ENV });
+  if (r.status === "failed") {
+    s.stop(red(`Failed: ${r.error ?? ""}`));
+    log.error("Re-run the wizard once the cause is fixed (this step is idempotent).");
+    cancel("Aborted.");
+    process.exit(1);
+  }
+  s.stop(green("public_role holds no database roles"));
+}
+
+/**
+ * The admin's custom role for writing the redirects table into the URL map
+ * (#587). Idempotent, so it runs on every wizard pass.
+ */
+async function stepUrlMapRedirectsAccess(projectId: string): Promise<void> {
+  const s = spinner();
+  s.start("Letting the admin serve redirects from the load balancer...");
+  const r = await ensureUrlMapRedirectsAccess({ projectId, env: GCP_STACK_ENV });
+  if (!r.ok) {
+    s.stop(red(`Failed: ${r.error}`));
+    log.error("Re-run the wizard once the cause is fixed (this step is idempotent).");
+    cancel("Aborted.");
+    process.exit(1);
+  }
+  s.stop(green(`Redirects role ready (${r.role})`));
+}
+
 /**
  * Give `gateway_role` (created by migration 0248) its password from the
  * `gateway-role-password` secret (#613). public_role already has its own:

package/stacks/aws/index.ts

@@ -11,8 +11,9 @@
  *     - Bootstrap script runs as a one-shot ECS task post-create.
  *  3. S3 buckets: caelo-media + caelo-static (per env).
  *  4. CloudFront distribution with two origins (S3 static + ALB-fronted ECS).
- *     Static files are served as files — no edge compute on the request
- *     path (CLAUDE.md §11.B Tier 1).
+ *     Static files are served as files (CLAUDE.md §11.B Tier 1); the only
+ *     edge code is the redirects table's CloudFront Function, a KeyValueStore
+ *     lookup that runs before the origin (#587).
  *  5. ECS Fargate cluster + four services (admin, gateway, orchestrator, runner).
  *  6. Secrets Manager entries (postgres-password, anthropic-api-key, ...).
  *  7. Route 53 hosted zone + ACM certs per (domain, locale).
@@ -26,6 +27,7 @@
  * is to wire those env vars to AWS-native resources.
  */
 
+import { cloudFrontRedirectFunctionCode } from "@caelo-cms/shared";
 import * as aws from "@pulumi/aws";
 import * as awsx from "@pulumi/awsx";
 import * as pulumi from "@pulumi/pulumi";
@@ -225,6 +227,27 @@ const cert = new aws.acm.Certificate(
   { provider: usEast1Provider },
 );
 
+// === 6b. Redirects at the edge (#587) ===
+// The redirects table: a CloudFront Function on viewer-request answers each
+// redirected path from a KeyValueStore before the S3 origin is asked
+// (redirect-emit-cloudfront.ts in @caelo-cms/shared). The deploy writes
+// the store, so redirects change without republishing the function.
+// FIXME(issue #749): the S3 static publisher is still a stub (#5); until
+// it writes the store, the function finds no keys and every request passes
+// through to the origin.
+const redirectKvs = new aws.cloudfront.KeyValueStore(`${namePrefix}-redirects`, {
+  name: `${namePrefix}-redirects`,
+  comment: `Caelo ${env} redirects table (#587)`,
+});
+const redirectFunction = new aws.cloudfront.Function(`${namePrefix}-redirects`, {
+  name: `${namePrefix}-redirects`,
+  runtime: "cloudfront-js-2.0",
+  comment: `Caelo ${env}: answer the redirects table at the edge (#587)`,
+  publish: true,
+  code: redirectKvs.arn.apply((arn) => cloudFrontRedirectFunctionCode(kvsIdFromArn(arn))),
+  keyValueStoreAssociations: [redirectKvs.arn],
+});
+
 // === 7. CloudFront distribution ===
 const distribution = new aws.cloudfront.Distribution(`${namePrefix}-cdn`, {
   enabled: true,
@@ -252,6 +275,7 @@ const distribution = new aws.cloudfront.Distribution(`${namePrefix}-cdn`, {
     minTtl: 0,
     defaultTtl: 60,
     maxTtl: 86400,
+    functionAssociations: [{ eventType: "viewer-request", functionArn: redirectFunction.arn }],
   },
   orderedCacheBehaviors: [
     {
@@ -421,6 +445,7 @@ export const edgeLogSinkUrlOut = out.edgeLogSinkUrl;
 export const providerOut = out.provider;
 export const environmentOut = out.environment;
 export const cloudfrontDomainOut = distribution.domainName;
+export const redirectKvsArnOut = redirectKvs.arn;
 export const ecsClusterArnOut = cluster.arn;
 export const rdsAddressOut = db.address;
 
@@ -429,3 +454,10 @@ export const rdsAddressOut = db.address;
 // state via `pulumi.secret(...)`. Operators retrieve via
 // `pulumi stack output --show-secrets`.
 export const bootstrapTokenExpiresAtOut = tokenInfo.expiresAt;
+
+/** A KeyValueStore's id: the last segment of its ARN. */
+function kvsIdFromArn(arn: string): string {
+  const id = arn.slice(arn.lastIndexOf("/") + 1);
+  if (!id || id === arn) throw new Error(`not a CloudFront KeyValueStore ARN: ${arn}`);
+  return id;
+}

package/stacks/azure/index.ts

@@ -269,6 +269,18 @@ const siteDomain = new azure.cdn.AFDCustomDomain(`${namePrefix}-fd-domain`, {
   tlsSettings: { certificateType: "ManagedCertificate", minimumTlsVersion: "TLS12" },
 });
 
+// #587 — the redirects table as rules-engine rules on the static route
+// (redirect-emit-front-door.ts in @caelo-cms/shared): Front Door answers
+// them at the edge before the Blob origin. The deploy owns the rules; the
+// stack only creates the rule set and attaches it.
+// FIXME(issue #750): the Blob static publisher is still a stub (#6); until
+// it writes the rules, the set stays empty and no redirect is served.
+const redirectRuleSet = new azure.cdn.RuleSet(`${namePrefix}-fd-redirects`, {
+  resourceGroupName: rg.name,
+  profileName: frontDoor.name,
+  ruleSetName: "caeloRedirects",
+});
+
 new azure.cdn.Route(
   `${namePrefix}-fd-route`,
   {
@@ -278,6 +290,7 @@ new azure.cdn.Route(
     routeName: "static",
     originGroup: { id: staticOriginGroup.id },
     customDomains: [{ id: siteDomain.id }],
+    ruleSets: [{ id: redirectRuleSet.id }],
     patternsToMatch: ["/*"],
     // Without a cache configuration Front Door does not cache the route at
     // all; static files are edge-cached per their Cache-Control (§11.B