@caelo-cms/provisioning 0.10.47 → 0.10.49

package/src/checkpoint-secrets.test.ts

@@ -0,0 +1,380 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #656 — progress.json / install.json never hold secret material, and
+ * `upgrade` / wizard re-runs scrub what earlier installers stored. Every
+ * credential below is a fake fixture.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { CAELO_VERSION } from "@caelo-cms/shared";
+import {
+  assertNoCheckpointSecrets,
+  assertNoSecrets,
+  checkpointableOutputs,
+  findCheckpointSecrets,
+  findSecrets,
+  redactCredentials,
+  rotationHints,
+  scrubProgressFile,
+} from "./checkpoint-secrets.js";
+import { databaseUrls } from "./stack-contract.js";
+
+const FAKE_PW = "fakePw0rdForTests123";
+const legacyAdminUrl = `postgresql://admin_role:${FAKE_PW}@10.1.2.3:5432/cms_admin?sslmode=require`;
+const legacyPublicUrl = `postgresql://public_role:${FAKE_PW}@10.1.2.3:5432/cms_public?sslmode=require`;
+const setupLink = "https://admin.acme.test/setup?token=fakeSetupToken0123456789";
+
+/** What `pulumi up` returns on the current stacks, secret flags included. */
+const stackOutputs = {
+  adminDatabaseUrlOut: { value: databaseUrls("10.1.2.3").admin, secret: false },
+  publicDatabaseUrlOut: { value: databaseUrls("10.1.2.3").public, secret: false },
+  gatewayDatabaseUrlOut: { value: databaseUrls("10.1.2.3").gateway, secret: false },
+  bootstrapUrlOut: { value: setupLink, secret: false },
+  bootstrapTokenExpiresAtOut: { value: "2026-10-13T00:00:00.000Z", secret: false },
+  providerOut: { value: "gcp", secret: false },
+  lbIpOut: { value: "203.0.113.7", secret: false },
+  adminDomainOut: { value: "admin.acme.test", secret: false },
+  adminCloudRunUrlOut: { value: "https://caelo-admin-x.a.run.app", secret: false },
+  dnsRecordsRequiredOut: {
+    value: [{ hostname: "acme.test", type: "A", value: "203.0.113.7", purpose: "site" }],
+    secret: false,
+  },
+  // A future output Pulumi marks secret, whatever its name or shape.
+  someFutureOut: { value: "opaque", secret: true },
+};
+
+/** A progress.json as installers before #576 / #656 wrote it. */
+const legacyProgress = {
+  lastCompletedStep: "pulumi-up-acme",
+  updatedAt: "2026-10-01T00:00:00.000Z",
+  steps: {
+    "project-acme": { existed: true },
+    "sa-acme": { created: true, saEmail: "caelo-provisioner@acme.iam.gserviceaccount.com" },
+    "sa-key-acme": { path: "/home/op/.caelo-gcp-acme/secrets/sa-key.json" },
+    "pulumi-up-acme": {
+      outputs: {
+        adminDatabaseUrlOut: legacyAdminUrl,
+        publicDatabaseUrlOut: legacyPublicUrl,
+        bootstrapUrlOut: setupLink,
+        providerOut: "gcp",
+        lbIpOut: "203.0.113.7",
+        adminDomainOut: "admin.acme.test",
+      },
+    },
+  },
+};
+
+describe("findSecrets", () => {
+  it("flags URLs carrying a password and names the database user", () => {
+    const found = findSecrets(legacyProgress);
+    expect(found).toContainEqual({
+      path: "steps.pulumi-up-acme.outputs.adminDatabaseUrlOut",
+      kind: "credential-url",
+      user: "admin_role",
+    });
+    expect(found).toContainEqual({
+      path: "steps.pulumi-up-acme.outputs.publicDatabaseUrlOut",
+      kind: "credential-url",
+      user: "public_role",
+    });
+    expect(found).toContainEqual({
+      path: "steps.pulumi-up-acme.outputs.bootstrapUrlOut",
+      kind: "token-url",
+    });
+    // Findings name where, never what.
+    expect(JSON.stringify(found)).not.toContain(FAKE_PW);
+  });
+
+  it("does not flag the password-less database URLs the stacks export today", () => {
+    expect(findSecrets(databaseUrls("10.1.2.3"))).toEqual([]);
+  });
+
+  it("flags secret-named keys holding a value, not markers or look-alikes", () => {
+    expect(findSecrets({ postgresPassword: "x" })).toEqual([
+      { path: "postgresPassword", kind: "secret-key" },
+    ]);
+    expect(findSecrets({ caeloSecretKekOut: "x", anthropic_api_key: "y" })).toHaveLength(2);
+    expect(findSecrets({ bootstrapTokenExpiresAtOut: "2026-10-13", hasToken: false })).toEqual([]);
+  });
+});
+
+describe("checkpointableOutputs", () => {
+  it("drops secret-flagged outputs and the setup link, keeps what resume and DNS need", () => {
+    const kept = checkpointableOutputs(stackOutputs);
+    expect(Object.keys(kept)).not.toContain("someFutureOut");
+    expect(Object.keys(kept)).not.toContain("bootstrapUrlOut");
+    expect(kept.dnsRecordsRequiredOut).toEqual(stackOutputs.dnsRecordsRequiredOut.value);
+    expect(kept.adminDomainOut).toBe("admin.acme.test");
+    expect(kept.bootstrapTokenExpiresAtOut).toBe("2026-10-13T00:00:00.000Z");
+    expect(findSecrets(kept)).toEqual([]);
+  });
+
+  it("drops a database URL that carries a password even when Pulumi did not mark it secret", () => {
+    const kept = checkpointableOutputs({
+      adminDatabaseUrlOut: { value: legacyAdminUrl, secret: false },
+    });
+    expect(kept).toEqual({});
+  });
+});
+
+describe("checkpoint guard (regression #656)", () => {
+  it("refuses a payload with a credential URL without echoing the secret", () => {
+    let message = "";
+    try {
+      assertNoSecrets({ outputs: { adminDatabaseUrlOut: legacyAdminUrl } }, "progress.json");
+    } catch (e) {
+      message = e instanceof Error ? e.message : String(e);
+    }
+    expect(message).toContain("outputs.adminDatabaseUrlOut: credential-url");
+    expect(message).not.toContain(FAKE_PW);
+  });
+
+  it("accepts every payload shape the wizard checkpoints", () => {
+    const payloads = [
+      { existed: true },
+      { created: true },
+      { billingAccountId: "000000-000000-000000" },
+      { count: 12 },
+      { existed: true, saEmail: "sa@acme.iam.gserviceaccount.com" },
+      { granted: ["roles/run.admin"] },
+      { path: "/home/op/.caelo-gcp-acme/secrets/sa-key.json" },
+      { outputs: checkpointableOutputs(stackOutputs) },
+      { skipped: "exists" },
+      { bucket: "caelo-production-static-acme" },
+      { adapter: "cloudflare" },
+    ];
+    for (const p of payloads) expect(() => assertNoSecrets(p, "progress.json")).not.toThrow();
+  });
+
+  it("every markStepDone call site in the CLI uses a reviewed payload key", () => {
+    // A new checkpoint payload must be added here on purpose, after checking
+    // it holds no secret. `outputs` must come from pulumiUpGcp, which returns
+    // only checkpointableOutputs().
+    const reviewed = new Set([
+      "existed",
+      "created",
+      "billingAccountId",
+      "count",
+      "saEmail",
+      "granted",
+      "path",
+      "outputs",
+      "skipped",
+      "bucket",
+      "adapter",
+    ]);
+    const files = [
+      ...readdirSync(import.meta.dir).map((f) => join(import.meta.dir, f)),
+      ...readdirSync(join(import.meta.dir, "wizards")).map((f) =>
+        join(import.meta.dir, "wizards", f),
+      ),
+    ].filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"));
+    const keys: string[] = [];
+    for (const file of files) {
+      const src = readFileSync(file, "utf8");
+      for (const m of src.matchAll(/markStepDone\([^,]+,[^,]+,\s*\{([^}]*)\}/g)) {
+        for (const part of (m[1] ?? "").split(",")) {
+          const key = part.split(":")[0]?.trim();
+          if (key) keys.push(key);
+        }
+      }
+    }
+    expect(keys.length).toBeGreaterThan(0);
+    expect(keys.filter((k) => !reviewed.has(k))).toEqual([]);
+    const gcp = readFileSync(join(import.meta.dir, "wizards", "gcp.ts"), "utf8");
+    expect(gcp).toContain("markStepDone(installId, stepName, { outputs: result.outputs })");
+    const up = readFileSync(join(import.meta.dir, "wizards", "gcp-pulumi.ts"), "utf8");
+    expect(up).toContain("outputs: checkpointableOutputs(result.outputs)");
+  });
+});
+
+describe("checkpoints of projects with secret-sounding ids (codex review)", () => {
+  it("treats step names as identifiers, not secret fields", () => {
+    const checkpoint = {
+      lastCompletedStep: "project-acme-token",
+      updatedAt: "t",
+      steps: { "project-acme-token": { existed: true }, "billing-acme-secret": { count: 1 } },
+    };
+    expect(findCheckpointSecrets(checkpoint)).toEqual([]);
+    expect(() => assertNoCheckpointSecrets(checkpoint, "progress.json")).not.toThrow();
+    // Payloads under such steps are still inspected.
+    expect(
+      findCheckpointSecrets({ steps: { "project-acme-token": { url: legacyAdminUrl } } }),
+    ).toEqual([
+      { path: "steps.project-acme-token.url", kind: "credential-url", user: "admin_role" },
+    ]);
+  });
+});
+
+describe("scrubProgressFile", () => {
+  const withFile = (contents: unknown, run: (path: string) => void) => {
+    const dir = mkdtempSync(join(tmpdir(), "caelo-scrub-"));
+    try {
+      const path = join(dir, "progress.json");
+      writeFileSync(path, JSON.stringify(contents), { mode: 0o644 });
+      run(path);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+
+  it("removes the secrets, keeps every completed step, and leaves the file 0600", () => {
+    withFile(legacyProgress, (path) => {
+      const { removed } = scrubProgressFile(path);
+      expect(removed.map((f) => f.kind).sort()).toEqual([
+        "credential-url",
+        "credential-url",
+        "token-url",
+      ]);
+      const text = readFileSync(path, "utf8");
+      expect(text).not.toContain(FAKE_PW);
+      expect(text).not.toContain("token=");
+      const after = JSON.parse(text);
+      // Wizard re-runs resume: every step is still recorded as done.
+      expect(Object.keys(after.steps)).toEqual(Object.keys(legacyProgress.steps));
+      expect(after.lastCompletedStep).toBe("pulumi-up-acme");
+      expect(after.steps["pulumi-up-acme"].outputs).toEqual({
+        providerOut: "gcp",
+        lbIpOut: "203.0.113.7",
+        adminDomainOut: "admin.acme.test",
+      });
+      expect(statSync(path).mode & 0o777).toBe(0o600);
+      expect(readdirSync(join(path, "..")).filter((f) => f.includes(".tmp-"))).toEqual([]);
+      // Idempotent.
+      expect(scrubProgressFile(path).removed).toEqual([]);
+    });
+  });
+
+  it("keeps the completed-step markers of a project whose id sounds secret", () => {
+    const cp = {
+      lastCompletedStep: "pulumi-up-acme-token",
+      updatedAt: "t",
+      steps: {
+        "project-acme-token": { existed: true },
+        "pulumi-up-acme-token": { outputs: { adminDatabaseUrlOut: legacyAdminUrl, lbIpOut: "1" } },
+      },
+    };
+    withFile(cp, (path) => {
+      expect(scrubProgressFile(path).removed).toHaveLength(1);
+      const after = JSON.parse(readFileSync(path, "utf8"));
+      expect(after.steps).toEqual({
+        "project-acme-token": { existed: true },
+        "pulumi-up-acme-token": { outputs: { lbIpOut: "1" } },
+      });
+    });
+  });
+
+  it("leaves a clean file untouched and a missing one alone", () => {
+    withFile(
+      { lastCompletedStep: "x", steps: { x: { created: true } }, updatedAt: "t" },
+      (path) => {
+        const before = readFileSync(path, "utf8");
+        expect(scrubProgressFile(path).removed).toEqual([]);
+        expect(readFileSync(path, "utf8")).toBe(before);
+        expect(scrubProgressFile(`${path}.missing`).removed).toEqual([]);
+      },
+    );
+  });
+});
+
+describe("rotationHints", () => {
+  it("names the rotate-secret command for each leaked role password", () => {
+    const hints = rotationHints(
+      [
+        { path: "a", kind: "credential-url", user: "admin_role" },
+        { path: "b", kind: "credential-url", user: "public_role" },
+        { path: "c", kind: "credential-url", user: "gateway_role" },
+        { path: "d", kind: "credential-url", user: "admin_role" },
+      ],
+      "gcp-acme",
+    );
+    expect(hints).toEqual([
+      `admin_role's password was stored in progress.json. Rotate it: bunx @caelo-cms/provisioning@${CAELO_VERSION} rotate-secret postgres-password --install gcp-acme`,
+      `public_role's password was stored in progress.json. Rotate it: bunx @caelo-cms/provisioning@${CAELO_VERSION} rotate-secret public-role-password --install gcp-acme`,
+      `gateway_role's password was stored in progress.json. Rotate it: bunx @caelo-cms/provisioning@${CAELO_VERSION} rotate-secret gateway-role-password --install gcp-acme`,
+    ]);
+  });
+
+  it("says the setup link needs no rotation", () => {
+    const [hint] = rotationHints([{ path: "a", kind: "token-url" }], "gcp-acme");
+    expect(hint).toContain("nothing to rotate");
+  });
+});
+
+describe("redactCredentials", () => {
+  it("masks URL passwords and leaves the rest readable", () => {
+    const out = redactCredentials(`connect failed: ${legacyAdminUrl} (timeout)`);
+    expect(out).not.toContain(FAKE_PW);
+    expect(out).toContain("postgresql://admin_role:***@10.1.2.3:5432/cms_admin");
+    expect(redactCredentials("https://admin.acme.test/x")).toBe("https://admin.acme.test/x");
+  });
+});
+
+describe("install dir end to end (regression #656)", () => {
+  it("a wizard's checkpoints leave no secret outside secrets/; legacy files are scrubbed; secrets are refused", () => {
+    // installRoot() resolves ~ via os.homedir(), read once at process start —
+    // drive install-state in a child process with its own HOME.
+    const home = mkdtempSync(join(tmpdir(), "caelo-install-656-"));
+    const installId = "gcp-acme";
+    const root = join(home, `.caelo-${installId}`);
+    try {
+      mkdirSync(root, { recursive: true });
+      writeFileSync(join(root, "progress.json"), JSON.stringify(legacyProgress), {
+        mode: 0o600,
+      });
+      const mod = resolve(import.meta.dir, "install-state.ts");
+      const sec = resolve(import.meta.dir, "checkpoint-secrets.ts");
+      const script = `
+        const m = await import(${JSON.stringify(mod)});
+        const s = await import(${JSON.stringify(sec)});
+        const id = ${JSON.stringify(installId)};
+        const lines = m.scrubInstallProgress(id);
+        m.markStepDone(id, "sa-acme", { created: true, saEmail: "sa@acme.iam.gserviceaccount.com" });
+        m.markStepDone(id, "pulumi-up-acme", { outputs: s.checkpointableOutputs(${JSON.stringify(stackOutputs)}) });
+        let refused = "";
+        try {
+          m.markStepDone(id, "bad", { url: ${JSON.stringify(legacyAdminUrl)} });
+        } catch (e) { refused = e.message; }
+        console.log(JSON.stringify({ lines, refused, done: m.isStepDone(id, "project-acme") }));
+      `;
+      const child = Bun.spawnSync([process.execPath, "-e", script], {
+        env: { ...process.env, HOME: home },
+        stderr: "pipe",
+      });
+      expect(new TextDecoder().decode(child.stderr)).toBe("");
+      expect(child.exitCode).toBe(0);
+      const result = JSON.parse(new TextDecoder().decode(child.stdout));
+      expect(result.done).toBe(true);
+      expect(result.refused).toContain("credential-url");
+      expect(result.refused).not.toContain(FAKE_PW);
+      expect(result.lines.join("\n")).toContain(
+        "rotate-secret postgres-password --install gcp-acme",
+      );
+      expect(result.lines.join("\n")).toContain(
+        "rotate-secret public-role-password --install gcp-acme",
+      );
+      // Nothing under the install dir but secrets/ holds secret material.
+      for (const f of readdirSync(root)) {
+        if (f === "secrets" || f === "state") continue;
+        const text = readFileSync(join(root, f), "utf8");
+        expect(findSecrets(JSON.parse(text))).toEqual([]);
+        expect(text).not.toContain(FAKE_PW);
+      }
+      expect(statSync(join(root, "progress.json")).mode & 0o777).toBe(0o600);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  }, 30_000);
+});

package/src/checkpoint-secrets.ts

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Keeps secret material out of the files the CLI writes under
+ * `~/.caelo-<install-id>/` (#656).
+ *
+ * Only `secrets/` may hold secrets (CLAUDE.md §7, §11.C); `progress.json`
+ * and `install.json` are plain bookkeeping that tooling, backups, sync
+ * clients and agents read. Installs from before #576 checkpointed the full
+ * Pulumi outputs, whose database URLs carried admin_role's and
+ * public_role's passwords, and every install so far checkpointed the Owner
+ * setup link with its token. This module
+ *
+ *   - finds secret material in a JSON value ({@link findSecrets}), which
+ *     `markStepDone` / `writeMetadata` use to refuse writing it;
+ *   - removes it from an existing checkpoint ({@link scrubProgressFile}),
+ *     which `upgrade` and wizard re-runs call, and names the secrets to
+ *     rotate ({@link rotationHints});
+ *   - masks credentials in text the CLI prints ({@link redactCredentials}).
+ *
+ * Detection is by shape (a URL with a password, a URL with a token-like
+ * query parameter) and by key name (password, secret, token, ...), so a
+ * future secret output is caught without being listed here.
+ */
+
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { selfCommand } from "./self-command.js";
+import { DATABASE_ROLE_SECRET, type DatabaseRole } from "./stack-contract.js";
+
+/** One place a JSON value holds secret material. Never carries the secret itself. */
+export interface SecretFinding {
+  /** Dotted path to the offending value, e.g. `steps.pulumi-up-acme.outputs.adminDatabaseUrlOut`. */
+  readonly path: string;
+  /**
+   * `credential-url`: a URL whose user-info carries a password.
+   * `token-url`: a URL with a token / secret / password query parameter.
+   * `secret-key`: a key whose name marks its value as secret.
+   */
+  readonly kind: "credential-url" | "token-url" | "secret-key";
+  /** For a credential URL: the user whose password it carries. */
+  readonly user?: string;
+}
+
+/** `scheme://user:password@` — the user-info of a URL that carries a password. */
+const CREDENTIAL_URL = /[a-z][a-z0-9+.-]{0,31}:\/\/([^\s:@/]*):([^\s@/]+)@/gi;
+
+/** A URL query parameter that carries a credential (the Owner setup link's `?token=`). */
+const TOKEN_PARAM =
+  /[?&](?:token|secret|password|passwd|pwd|api[_-]?key|access[_-]?key|sig|signature)=[^&\s#]+/i;
+
+/**
+ * Key names whose value is a secret, after lower-casing, dropping non
+ * alphanumerics and a Pulumi `Out` suffix: `postgresPassword`,
+ * `caeloSecretKek`, `bootstrap_token`, `anthropicApiKey`.
+ */
+const SECRET_KEY = /(password|passwd|passphrase|secret|secretkek|kek|token|apikey|privatekey)$/;
+
+function isSecretKey(key: string): boolean {
+  const k = key
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "")
+    .replace(/out$/, "");
+  return SECRET_KEY.test(k);
+}
+
+function urlUser(raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function stringFindings(value: string, path: string): SecretFinding[] {
+  const found: SecretFinding[] = [];
+  for (const m of value.matchAll(CREDENTIAL_URL)) {
+    found.push({ path, kind: "credential-url", user: urlUser(m[1] ?? "") });
+  }
+  if (found.length === 0 && /:\/\//.test(value) && TOKEN_PARAM.test(value)) {
+    found.push({ path, kind: "token-url" });
+  }
+  return found;
+}
+
+/**
+ * Every place `value` holds secret material.
+ *
+ * @param value any JSON-shaped value (a checkpoint payload, install.json)
+ * @param path the path prefix to report findings under
+ */
+export function findSecrets(value: unknown, path = ""): SecretFinding[] {
+  if (typeof value === "string") return stringFindings(value, path || "(value)");
+  const join = (k: string | number) => (path ? `${path}.${k}` : String(k));
+  if (Array.isArray(value)) return value.flatMap((v, i) => findSecrets(v, join(i)));
+  if (value !== null && typeof value === "object") {
+    return Object.entries(value).flatMap(([k, v]) => {
+      // A secret-named key is only a finding when it holds something; a
+      // null / false / 0 marker is not secret material.
+      if (isSecretKey(k) && v !== null && v !== undefined && v !== "" && typeof v !== "boolean") {
+        return [{ path: join(k), kind: "secret-key" as const }];
+      }
+      return findSecrets(v, join(k));
+    });
+  }
+  return [];
+}
+
+/**
+ * Throw when `value` holds secret material. The message names the paths,
+ * never the values, so the error itself cannot leak them.
+ *
+ * @param what what was about to be written, for the message
+ */
+export function assertNoSecrets(value: unknown, what: string): void {
+  refuseFindings(findSecrets(value), what);
+}
+
+/** {@link assertNoSecrets} for a whole checkpoint (see {@link findCheckpointSecrets}). */
+export function assertNoCheckpointSecrets(checkpoint: unknown, what: string): void {
+  refuseFindings(findCheckpointSecrets(checkpoint), what);
+}
+
+function refuseFindings(found: readonly SecretFinding[], what: string): void {
+  if (found.length === 0) return;
+  throw new Error(
+    `Refusing to write secret material to ${what} (${found.map((f) => `${f.path}: ${f.kind}`).join(", ")}). ` +
+      "Secrets belong in Secret Manager or the install's secrets/ directory; read them at the moment of use instead (#656).",
+  );
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * {@link findSecrets} for a progress.json checkpoint. Its step names are
+ * derived from operator input (`project-<project id>`), so they are
+ * identifiers, not field names: a project called `acme-token` must not read
+ * as a secret. Only the step payloads (and the other top-level fields) are
+ * inspected.
+ */
+export function findCheckpointSecrets(checkpoint: unknown): SecretFinding[] {
+  if (!isRecord(checkpoint)) return findSecrets(checkpoint);
+  const { steps, ...rest } = checkpoint;
+  const inSteps = isRecord(steps)
+    ? Object.entries(steps).flatMap(([name, payload]) => findSecrets(payload, `steps.${name}`))
+    : findSecrets(steps, "steps");
+  return [...findSecrets(rest), ...inSteps];
+}
+
+/** {@link withoutSecrets} for a checkpoint: every step is kept, its payload cleaned. */
+function checkpointWithoutSecrets(checkpoint: unknown): unknown {
+  if (!isRecord(checkpoint)) return withoutSecrets(checkpoint);
+  const { steps, ...rest } = checkpoint;
+  return {
+    ...(withoutSecrets(rest) as Record<string, unknown>),
+    steps: isRecord(steps)
+      ? Object.fromEntries(Object.entries(steps).map(([n, p]) => [n, withoutSecrets(p)]))
+      : withoutSecrets(steps),
+  };
+}
+
+/**
+ * `value` without its secret material: secret-named keys and strings that
+ * hold a credential or token URL are dropped. Everything else is kept.
+ */
+export function withoutSecrets(value: unknown): unknown {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value
+      .filter((v) => typeof v !== "string" || findSecrets(v).length === 0)
+      .map(withoutSecrets);
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (findSecrets({ [k]: v }).length > 0 && (isSecretKey(k) || typeof v === "string")) continue;
+      out[k] = withoutSecrets(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * The Pulumi outputs worth checkpointing: everything except outputs Pulumi
+ * marks secret and anything else that holds secret material (the Owner
+ * setup link). Nothing reads secrets back from the checkpoint; code that
+ * needs one reads the stack (`readStackOutput`) when it needs it.
+ *
+ * @param outputs the stack outputs as the Automation API returns them
+ */
+export function checkpointableOutputs(
+  outputs: Readonly<Record<string, { value: unknown; secret?: boolean }>>,
+): Record<string, unknown> {
+  const kept: Record<string, unknown> = {};
+  for (const [k, o] of Object.entries(outputs)) {
+    if (o.secret) continue;
+    if (findSecrets({ [k]: o.value }).length > 0) continue;
+    kept[k] = o.value;
+  }
+  return kept;
+}
+
+/** Outcome of {@link scrubProgressFile}. */
+export interface ScrubReport {
+  /** What was removed (paths + kinds, never values). Empty when the file was clean or absent. */
+  readonly removed: readonly SecretFinding[];
+}
+
+/**
+ * Remove secret material from a `progress.json` in place. The rewrite is
+ * atomic (temp file in the same directory, then rename) and the result is
+ * mode 0600, so an interrupted scrub never leaves a truncated checkpoint
+ * and wizard re-runs still find every completed step.
+ *
+ * @param path the checkpoint file; a missing file is a no-op
+ */
+export function scrubProgressFile(path: string): ScrubReport {
+  if (!existsSync(path)) return { removed: [] };
+  const checkpoint: unknown = JSON.parse(readFileSync(path, "utf8"));
+  const removed = findCheckpointSecrets(checkpoint);
+  if (removed.length === 0) return { removed };
+  writeJsonAtomic(path, checkpointWithoutSecrets(checkpoint));
+  return { removed };
+}
+
+/**
+ * Write `value` as JSON to `path` atomically with mode 0600: a temp file in
+ * the same directory (so the rename stays on one filesystem), then rename.
+ */
+export function writeJsonAtomic(path: string, value: unknown): void {
+  const tmp = `${path}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+const ROLE_BY_USER = DATABASE_ROLE_SECRET as Readonly<Record<string, string | undefined>>;
+
+/**
+ * What the operator should do about secrets a scrub removed: one line per
+ * affected secret, with the exact command where one exists.
+ *
+ * @param removed the scrub's findings
+ * @param installId the install, named in each command so it acts on the right one
+ */
+export function rotationHints(removed: readonly SecretFinding[], installId: string): string[] {
+  const rotate = (secret: string) => selfCommand("rotate-secret", secret, "--install", installId);
+  const hints = new Set<string>();
+  for (const f of removed) {
+    if (f.kind === "credential-url") {
+      const secret = f.user ? ROLE_BY_USER[f.user as DatabaseRole] : undefined;
+      hints.add(
+        secret
+          ? `${f.user}'s password was stored in progress.json. Rotate it: ${rotate(secret)}`
+          : `A password for database user "${f.user ?? "?"}" was stored in progress.json (${f.path}); change it.`,
+      );
+    } else if (f.kind === "token-url") {
+      hints.add(
+        "The Owner setup link (with its one-time token) was stored in progress.json. It expires 24 hours after it was issued and stops working once the Owner account exists; nothing to rotate.",
+      );
+    } else {
+      hints.add(
+        `A secret value was stored in progress.json (${f.path}). Rotate whatever it belongs to.`,
+      );
+    }
+  }
+  return [...hints];
+}
+
+/**
+ * `text` with every URL password masked (`postgresql://admin_role:***@`),
+ * for anything the CLI prints that could carry one (errors from Pulumi or
+ * gcloud, for instance). Same masking as the API gateway's error log.
+ */
+export function redactCredentials(text: string): string {
+  return text.replace(/([a-z][a-z0-9+.-]{0,31}:\/\/[^\s:@/]*):[^\s@/]+@/gi, "$1:***@");
+}