@caelo-cms/provisioning 0.11.9 → 0.11.11

package/src/self-hosted-release-resolve.test.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1328 — resolving a self-hosted release: the MCP-Auth-Proxy image is
+ * optional only for a release that has none (the registry says its tag does
+ * not exist), never because the registry could not be asked.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { type HostRunner, resolveVerifiedRelease } from "./self-hosted-release.js";
+
+const D = (c: string) => `sha256:${c.repeat(64)}`;
+
+/** GHCR with a token challenge; `proxy` decides the MCP-Auth-Proxy tag's answer. */
+function ghcr(proxy: "present" | 404 | 503): typeof fetch {
+  return (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    if (url.startsWith("https://ghcr.io/token")) return Response.json({ token: "t" });
+    if (!new Headers(init?.headers).get("authorization")) {
+      return new Response(null, {
+        status: 401,
+        headers: { "www-authenticate": 'Bearer realm="https://ghcr.io/token",service="ghcr.io"' },
+      });
+    }
+    if (url.includes("/caelo-cms/mcp-auth-proxy/")) {
+      if (proxy !== "present") return new Response(null, { status: proxy });
+      return new Response(null, { status: 200, headers: { "docker-content-digest": D("c") } });
+    }
+    const digest = url.includes("/caelo-cms/admin/") ? D("a") : D("b");
+    return new Response(null, { status: 200, headers: { "docker-content-digest": digest } });
+  }) as typeof fetch;
+}
+
+function runner(): HostRunner & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    calls,
+    async run(argv) {
+      calls.push(argv.join(" "));
+      return { exitCode: 0, stdout: "", stderr: "" };
+    },
+  };
+}
+
+describe("resolveVerifiedRelease (#1328)", () => {
+  it("resolves and verifies all three images of a release that ships the proxy", async () => {
+    const r = runner();
+    const res = await resolveVerifiedRelease("0.12.0", { runner: r, fetchImpl: ghcr("present") });
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect(res.images["mcp-auth-proxy"]).toBe(`ghcr.io/caelo-cms/mcp-auth-proxy@${D("c")}`);
+    expect(r.calls.filter((c) => c.startsWith("cosign verify"))).toHaveLength(3);
+  });
+
+  it("a release from before the proxy (its tag does not exist) resolves without it", async () => {
+    const r = runner();
+    const res = await resolveVerifiedRelease("0.11.0", { runner: r, fetchImpl: ghcr(404) });
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect("mcp-auth-proxy" in res.images).toBe(false);
+    expect(res.images.admin).toBe(`ghcr.io/caelo-cms/admin@${D("a")}`);
+    expect(r.calls.filter((c) => c.startsWith("cosign verify"))).toHaveLength(2);
+  });
+
+  it("a registry outage on the proxy tag fails instead of installing without it", async () => {
+    const res = await resolveVerifiedRelease("0.12.0", { runner: runner(), fetchImpl: ghcr(503) });
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.error).toContain("mcp-auth-proxy:0.12.0");
+  });
+});

package/src/self-hosted-release.ts

@@ -6,8 +6,8 @@
  *
  * `.caelo/release.json` is the install metadata for self-hosted (the cloud
  * providers keep theirs in `~/.caelo-<id>/install.json`): the release
- * version, the digest-pinned admin + gateway image references the Compose
- * file runs, and a short history of installs/upgrades/rollbacks. It holds no
+ * version, the digest-pinned image references the Compose file runs (admin,
+ * gateway, and since #1328 the MCP-Auth-Proxy), and a short history of installs/upgrades/rollbacks. It holds no
  * secrets (config.json does), so it is safe to read from tooling and
  * backups; writes refuse secret material like install.json's do.
  *
@@ -27,6 +27,7 @@ import {
   GHCR_NAMESPACE,
   GHCR_REGISTRY,
   RELEASE_SERVICES,
+  type ReleaseService,
   resolveRegistryDigest,
 } from "./upgrade/release-images.js";
 
@@ -103,7 +104,12 @@ export interface ReleaseHistoryEntry {
 export interface SelfHostedRelease {
   /** The release tag the images were resolved from (e.g. `0.10.43`). */
   readonly version: string;
-  readonly images: { readonly admin: string; readonly gateway: string };
+  readonly images: {
+    readonly admin: string;
+    readonly gateway: string;
+    /** #1328 — absent in records of releases from before the MCP-Auth-Proxy. */
+    readonly "mcp-auth-proxy"?: string;
+  };
   readonly installedAt: string;
   /** Newest last; capped at {@link HISTORY_LIMIT}. */
   readonly history: readonly ReleaseHistoryEntry[];
@@ -117,7 +123,17 @@ export function releasePath(caeloDir: string): string {
 
 /** The images of a recorded release, as the Compose generator takes them. */
 export function releaseImages(release: SelfHostedRelease): ReleaseImages {
-  return { mode: "release", admin: release.images.admin, gateway: release.images.gateway };
+  return { mode: "release", ...release.images };
+}
+
+/** The image references of `images`, as release.json stores them. */
+function recordedImages(images: ReleaseImages): SelfHostedRelease["images"] {
+  const proxy = images["mcp-auth-proxy"];
+  return {
+    admin: images.admin,
+    gateway: images.gateway,
+    ...(proxy !== undefined ? { "mcp-auth-proxy": proxy } : {}),
+  };
 }
 
 /**
@@ -131,10 +147,12 @@ export function readRelease(caeloDir: string): SelfHostedRelease | null {
   const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<SelfHostedRelease>;
   const admin = raw.images?.admin ?? "";
   const gateway = raw.images?.gateway ?? "";
+  const proxy = raw.images?.["mcp-auth-proxy"];
   if (
     typeof raw.version !== "string" ||
     !ghcrImageDigest("admin", admin) ||
-    !ghcrImageDigest("gateway", gateway)
+    !ghcrImageDigest("gateway", gateway) ||
+    (proxy !== undefined && !ghcrImageDigest("mcp-auth-proxy", proxy))
   ) {
     throw new Error(
       `${path} is malformed (needs version + digest-pinned ghcr.io/caelo-cms images); fix it or re-run \`${selfCommand("upgrade", "--version", "<x.y.z>")}\`.`,
@@ -142,7 +160,7 @@ export function readRelease(caeloDir: string): SelfHostedRelease | null {
   }
   return {
     version: raw.version,
-    images: { admin, gateway },
+    images: { admin, gateway, ...(proxy !== undefined ? { "mcp-auth-proxy": proxy } : {}) },
     installedAt: raw.installedAt ?? "",
     history: Array.isArray(raw.history) ? raw.history : [],
   };
@@ -162,7 +180,7 @@ export function recordRelease(
   const at = now.toISOString();
   const record: SelfHostedRelease = {
     version: next.version,
-    images: { admin: next.images.admin, gateway: next.images.gateway },
+    images: recordedImages(next.images),
     installedAt:
       prior && prior.version === next.version && entry.outcome === "rolled-back"
         ? prior.installedAt
@@ -195,7 +213,7 @@ export type VerifiedRelease =
   | { readonly ok: false; readonly error: string };
 
 /**
- * Resolve the admin + gateway images of release `tag` in GHCR to digests,
+ * Resolve every release image of `tag` (RELEASE_SERVICES) in GHCR to digests,
  * then cosign-verify each digest against the Caelo release workflow
  * identity (unless `skipVerify`, the escape hatch for forks). The returned
  * references are digest-pinned, so what was verified is exactly what runs.
@@ -209,7 +227,7 @@ export async function resolveVerifiedRelease(
     readonly onProgress?: (message: string) => void;
   },
 ): Promise<VerifiedRelease> {
-  const refs: Partial<Record<"admin" | "gateway", string>> = {};
+  const refs: Partial<Record<ReleaseService, string>> = {};
   for (const service of RELEASE_SERVICES) {
     deps.onProgress?.(`Resolving ${GHCR_REGISTRY}/${GHCR_NAMESPACE}/${service}:${tag}`);
     const r = await resolveRegistryDigest(
@@ -218,6 +236,14 @@ export async function resolveVerifiedRelease(
       tag,
       deps.fetchImpl,
     );
+    if (!r.ok && r.notFound && service === "mcp-auth-proxy") {
+      // #1328 — releases from before the MCP-Auth-Proxy ship no image of it,
+      // and they stay installable and rollback targets: their Compose file
+      // simply has no proxy (ReleaseImages models the absence). Only a
+      // registry verdict that the tag does not exist means that; an outage
+      // still fails below, never silently installs a release without it.
+      continue;
+    }
     if (!r.ok) {
       return {
         ok: false,
@@ -228,10 +254,12 @@ export async function resolveVerifiedRelease(
     }
     refs[service] = ghcrImageRef(service, r.digest);
   }
+  const proxy = refs["mcp-auth-proxy"];
   const images: ReleaseImages = {
     mode: "release",
     admin: refs.admin ?? "",
     gateway: refs.gateway ?? "",
+    ...(proxy ? { "mcp-auth-proxy": proxy } : {}),
   };
   if (deps.skipVerify) return { ok: true, images };
 
@@ -246,13 +274,15 @@ export async function resolveVerifiedRelease(
     };
   }
   for (const service of RELEASE_SERVICES) {
+    const ref = images[service];
+    if (ref === undefined) continue;
     deps.onProgress?.(`Verifying the signature of ${service}`);
-    const v = await deps.runner.run(cosignVerifyArgv(images[service]));
+    const v = await deps.runner.run(cosignVerifyArgv(ref));
     if (v.exitCode !== 0) {
       return {
         ok: false,
         error:
-          `cosign verify FAILED for ${images[service]}: its signature does not match the Caelo release workflow.\n` +
+          `cosign verify FAILED for ${ref}: its signature does not match the Caelo release workflow.\n` +
           "Either the registry was compromised, the image is a fork's, or sigstore had an outage (retry).\n" +
           `cosign: ${v.stderr.trim().slice(0, 500)}`,
       };

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

@@ -26,6 +26,7 @@ const required = [
   "POSTGRES_PORT",
   "ADMIN_ROLE_PASSWORD",
   "PUBLIC_ROLE_PASSWORD",
+  "PUBLIC_STAGING_ROLE_PASSWORD",
   "ADMIN_DATABASE_URL",
   "PUBLIC_DATABASE_URL",
 ] as const;
@@ -63,6 +64,7 @@ const psql: SuperuserPsql = async (script) => {
 const passwords = {
   admin: env.ADMIN_ROLE_PASSWORD as string,
   public: env.PUBLIC_ROLE_PASSWORD as string,
+  publicStaging: env.PUBLIC_STAGING_ROLE_PASSWORD as string,
 };
 
 describe("self-hosted role convergence against Postgres (#613 review, #635)", () => {

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

@@ -1,14 +1,19 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import {
+  applyPreMigrationRoles,
   convergeSelfHostedRoles,
   decideUp,
+  PUBLIC_ROLE_LIMITS,
+  preMigrationRolesScript,
   roleConvergenceScript,
   selfHostedBootstrapScript,
 } from "./self-hosted-roles.js";
 
-const PASSWORDS = { admin: "a'pw", public: "p-pw" };
+const PASSWORDS = { admin: "a'pw", public: "p-pw", publicStaging: "s'pw" };
 
 describe("roleConvergenceScript (#613 review)", () => {
   const script = roleConvergenceScript(PASSWORDS);
@@ -23,13 +28,13 @@ describe("roleConvergenceScript (#613 review)", () => {
     expect(script).not.toContain("CREATE ROLE gateway_role");
   });
 
-  it("drops the former gateway_role with what it holds in both databases, and stops on the first error (#635)", () => {
+  it("drops the former gateway_role with what it holds in every database, and stops on the first error (#635, #1329)", () => {
     expect(script.startsWith("\\set ON_ERROR_STOP on")).toBe(true);
     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.match(/DROP OWNED BY gateway_role/g)).toHaveLength(3);
     expect(script.indexOf("THEN DROP ROLE gateway_role;")).toBeGreaterThan(adminDrop);
     expect(script).not.toContain("caelo_grant_gateway_role");
   });
@@ -126,3 +131,82 @@ describe("decideUp — `cms-provision up` never switches URLs onto unapplied pas
     expect(d).toMatchObject({ kind: "proceed", markConverged: false });
   });
 });
+
+describe("the staging database and its login (#1329)", () => {
+  const staging = [
+    "SELECT 'CREATE ROLE public_staging_role NOINHERIT LOGIN' WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'public_staging_role') \\gexec",
+    "SELECT 'CREATE DATABASE cms_public_staging OWNER admin_role' WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = 'cms_public_staging') \\gexec",
+    "REVOKE ALL ON DATABASE cms_public_staging FROM PUBLIC;",
+    "GRANT CONNECT ON DATABASE cms_public_staging TO public_staging_role, admin_role;",
+    "REVOKE ALL ON DATABASE cms_public_staging FROM public_role;",
+    "REVOKE ALL ON DATABASE cms_public FROM public_staging_role;",
+  ];
+
+  it("are created on the first start, on every `up`, and before an upgrade's migrations", () => {
+    for (const script of [roleConvergenceScript(PASSWORDS), preMigrationRolesScript("s'pw")]) {
+      for (const st of staging) expect(script).toContain(st);
+      expect(script).toContain("ALTER ROLE public_staging_role WITH LOGIN PASSWORD 's''pw';");
+    }
+    const bootstrap = selfHostedBootstrapScript({ agent: false });
+    for (const st of staging) expect(bootstrap).toContain(st);
+    expect(bootstrap).toContain(
+      "ALTER ROLE public_staging_role WITH LOGIN PASSWORD :'public_staging_role_pw';",
+    );
+    expect(bootstrap).toContain('-v public_staging_role_pw="$PUBLIC_STAGING_ROLE_PASSWORD"');
+  });
+
+  it("drops the former gateway_role's leftovers in the staging database too", () => {
+    expect(roleConvergenceScript(PASSWORDS)).toContain("\\connect cms_public_staging");
+  });
+});
+
+describe("the gateway logins' limits (#1338, H3; #1329)", () => {
+  const statements = ["public_role", "public_staging_role"].flatMap((role) => [
+    `ALTER ROLE ${role} CONNECTION LIMIT ${PUBLIC_ROLE_LIMITS.connectionLimit};`,
+    `ALTER ROLE ${role} SET statement_timeout = '${PUBLIC_ROLE_LIMITS.statementTimeout}';`,
+    `ALTER ROLE ${role} SET idle_in_transaction_session_timeout = '${PUBLIC_ROLE_LIMITS.idleInTransactionSessionTimeout}';`,
+    `ALTER ROLE ${role} SET work_mem = '${PUBLIC_ROLE_LIMITS.workMem}';`,
+  ]);
+
+  it("are set on the first start, on every `up`, and before an upgrade's migrations", () => {
+    for (const script of [
+      selfHostedBootstrapScript({ agent: false }),
+      roleConvergenceScript(PASSWORDS),
+      preMigrationRolesScript("s'pw"),
+    ]) {
+      for (const st of statements) expect(script).toContain(st);
+    }
+    // The pre-migration script drops no role and touches no other database:
+    // only the staging database with its login, then the limits.
+    const lines = preMigrationRolesScript("s'pw").split("\n").filter(Boolean);
+    expect(lines[0]).toBe("\\set ON_ERROR_STOP on");
+    expect(lines.slice(-statements.length)).toEqual(statements);
+    expect(lines.some((l) => /DROP|\\connect/.test(l))).toBe(false);
+  });
+
+  it("match the values packages/migrations/src/bootstrap.sh sets (dev, CI, Cloud SQL bootstrap)", () => {
+    const bootstrap = readFileSync(
+      resolve(import.meta.dir, "../../migrations/src/bootstrap.sh"),
+      "utf8",
+    );
+    for (const st of statements) expect(bootstrap).toContain(st);
+  });
+
+  it("refuse to run against a stopped database", async () => {
+    let ran = false;
+    const r = await applyPreMigrationRoles({
+      stagingPassword: "s",
+      probe: async () => false,
+      psql: async () => {
+        ran = true;
+        return { exitCode: 0, stderr: "" };
+      },
+    });
+    expect(r).toEqual({
+      ok: false,
+      reachable: false,
+      error: "the Postgres container is not running",
+    });
+    expect(ran).toBe(false);
+  });
+});

package/src/self-hosted-roles.ts

@@ -13,8 +13,10 @@
  * 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.
+ * gateway has no cms_admin login), with whatever it still holds, and
+ * (#1329) creates the staging database `cms_public_staging` with the
+ * staging gateway's login `public_staging_role` on an install from before
+ * it. Every statement is idempotent.
  *
  * Passwords travel on psql's stdin, never on argv.
  */
@@ -35,12 +37,82 @@ 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"] as const;
+const APP_ROLES = ["admin_role", "public_role", "public_staging_role"] as const;
+
+/** #1329 — the gateway logins that carry {@link PUBLIC_ROLE_LIMITS}: the live and the staging one. */
+const GATEWAY_LOGINS = ["public_role", "public_staging_role"] as const;
 type AppRole = (typeof APP_ROLES)[number];
 
+/**
+ * #1338 (gateway hardening H3) — what bounds public_role, the gateway's
+ * login, on the database: at most this many connections, no statement or
+ * idle transaction that runs away, little sort memory per query. The same
+ * values as packages/migrations/src/bootstrap.sh and the cms_admin
+ * migration that sets them where admin_role may (Cloud SQL); the role audit
+ * (packages/migrations role-audit.ts) refuses an install without them.
+ * Self-hosted admin_role has no CREATEROLE, so the superuser applies them
+ * here — on the volume's first start (bootstrap.sh), on every `up`, and
+ * before the migrations of every upgrade ({@link preMigrationRolesScript}).
+ * Since #1329 the staging gateway's public_staging_role carries the same.
+ */
+export const PUBLIC_ROLE_LIMITS = {
+  connectionLimit: 30,
+  statementTimeout: "5s",
+  idleInTransactionSessionTimeout: "15s",
+  workMem: "1MB",
+} as const;
+
+/** The statements that apply {@link PUBLIC_ROLE_LIMITS} to both gateway logins (idempotent). */
+function publicRoleLimitsSql(): string[] {
+  const l = PUBLIC_ROLE_LIMITS;
+  return GATEWAY_LOGINS.flatMap((role) => [
+    `ALTER ROLE ${role} CONNECTION LIMIT ${l.connectionLimit};`,
+    `ALTER ROLE ${role} SET statement_timeout = '${l.statementTimeout}';`,
+    `ALTER ROLE ${role} SET idle_in_transaction_session_timeout = '${l.idleInTransactionSessionTimeout}';`,
+    `ALTER ROLE ${role} SET work_mem = '${l.workMem}';`,
+  ]);
+}
+
 /** How a role's password appears in the SQL: a literal, or a psql variable. */
 type PasswordSql = (role: AppRole | typeof AGENT_DB_ROLE) => string;
 
+/**
+ * #1329 — the staging database and its gateway login, with each gateway
+ * login on its own database only (the same as bootstrap.sh and cms_admin
+ * migration 0530). Idempotent: an install from before #1329 gets both, an
+ * install that has them gets the password re-applied.
+ */
+function stagingDatabaseSql(password: PasswordSql): string[] {
+  return [
+    "SELECT 'CREATE ROLE public_staging_role NOINHERIT LOGIN' WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'public_staging_role') \\gexec",
+    `ALTER ROLE public_staging_role WITH LOGIN PASSWORD ${password("public_staging_role")};`,
+    "SELECT 'CREATE DATABASE cms_public_staging OWNER admin_role' WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = 'cms_public_staging') \\gexec",
+    "REVOKE ALL ON DATABASE cms_public_staging FROM PUBLIC;",
+    "GRANT CONNECT ON DATABASE cms_public_staging TO public_staging_role, admin_role;",
+    "REVOKE ALL ON DATABASE cms_public_staging FROM public_role;",
+    "REVOKE ALL ON DATABASE cms_public FROM public_staging_role;",
+    "REVOKE ALL ON DATABASE cms_admin FROM public_staging_role;",
+  ];
+}
+
+/**
+ * The psql script (superuser) the self-hosted upgrade runs BEFORE the
+ * migrations: the gateway logins' {@link PUBLIC_ROLE_LIMITS} (#1338) and
+ * (#1329) the staging database with its login. The migrations' role audit
+ * refuses either gateway login without its limits, and the
+ * cms_public_staging run needs the database; the full convergence must
+ * wait until after them (it drops roles a migration retired). Fails when
+ * public_role does not exist — the install's roles were never created.
+ */
+export function preMigrationRolesScript(stagingPassword: string): string {
+  return [
+    "\\set ON_ERROR_STOP on",
+    ...stagingDatabaseSql(() => literal(stagingPassword)),
+    ...publicRoleLimitsSql(),
+    "",
+  ].join("\n");
+}
+
 /**
  * The convergence SQL (psql, as the superuser, connected to any database).
  * `password` renders each role's password; `agent` adds the agent's login.
@@ -52,6 +124,7 @@ function convergenceSql(password: PasswordSql, agent: boolean): string {
       `SELECT 'CREATE ROLE ${role} NOINHERIT LOGIN' WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') \\gexec`,
       `ALTER ROLE ${role} WITH LOGIN PASSWORD ${password(role)};`,
     ]),
+    ...publicRoleLimitsSql(),
     // The upgrader's role (migration 0267 creates it only with CREATEROLE,
     // which the self-hosted admin_role lacks).
     "SELECT 'CREATE ROLE platform_updater NOLOGIN' WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'platform_updater') \\gexec",
@@ -70,11 +143,15 @@ 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;",
+    // #1329 — after the other two databases exist: its revokes name them.
+    ...stagingDatabaseSql(password),
     // #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_public_staging",
+    "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",
     "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 $$;",
@@ -95,6 +172,7 @@ export function roleConvergenceScript(passwords: RolePasswords, agentPassword?:
   const byRole: Record<AppRole, string> = {
     admin_role: passwords.admin,
     public_role: passwords.public,
+    public_staging_role: passwords.publicStaging,
   };
   return convergenceSql(
     (role) => literal(role === AGENT_DB_ROLE ? (agentPassword ?? "") : byRole[role]),
@@ -106,6 +184,7 @@ 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",
+  public_staging_role: "PUBLIC_STAGING_ROLE_PASSWORD",
   [AGENT_DB_ROLE]: "AGENT_ROLE_PASSWORD",
 };
 
@@ -143,6 +222,25 @@ ${convergenceSql((role) => `:'${role}_pw'`, opts.agent)}CAELO_SQL
 /** Runs a psql script as the superuser; resolves to psql's exit code + stderr. */
 export type SuperuserPsql = (script: string) => Promise<{ exitCode: number; stderr: string }>;
 
+/**
+ * Apply {@link preMigrationRolesScript} through the running Postgres
+ * container. Unlike {@link convergeSelfHostedRoles} a stopped database is a
+ * failure: the upgrade runs it right before migrations that need it.
+ */
+export async function applyPreMigrationRoles(deps: {
+  readonly probe: () => Promise<boolean>;
+  readonly psql: SuperuserPsql;
+  /** #1329 — public_staging_role's password from `.caelo/config.json`. */
+  readonly stagingPassword: string;
+}): Promise<ConvergeOutcome> {
+  if (!(await deps.probe())) {
+    return { ok: false, reachable: false, error: "the Postgres container is not running" };
+  }
+  const r = await deps.psql(preMigrationRolesScript(deps.stagingPassword));
+  if (r.exitCode === 0) return { ok: true };
+  return { ok: false, reachable: true, error: r.stderr.trim() || `psql exited ${r.exitCode}` };
+}
+
 export type ConvergeOutcome =
   | { readonly ok: true }
   /** `reachable: false` — the database is not running, nothing was attempted. */

package/src/self-hosted-scheduler-interval.test.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1140 — the self-hosted Pulumi stack and the CLI render the same Compose
+ * file, so the scheduler interval `init` recorded survives a `pulumi up`,
+ * and a disagreeing Pulumi key is refused instead of winning silently.
+ */
+
+import { afterAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  recordedSchedulerIntervalMinutes,
+  selfHostedSchedulerIntervalMinutes,
+} from "./self-hosted-scheduler-interval.js";
+
+const dir = mkdtempSync(join(tmpdir(), "caelo-scheduler-interval-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+function config(name: string, body: string): string {
+  const path = join(dir, name);
+  writeFileSync(path, body);
+  return path;
+}
+
+describe("recordedSchedulerIntervalMinutes", () => {
+  it("reads what init recorded", () => {
+    expect(
+      recordedSchedulerIntervalMinutes(config("a.json", '{"schedulerIntervalMinutes":2}')),
+    ).toBe(2);
+  });
+
+  it("is undefined without a config.json or without the key", () => {
+    expect(recordedSchedulerIntervalMinutes(join(dir, "missing.json"))).toBeUndefined();
+    expect(recordedSchedulerIntervalMinutes(config("b.json", '{"domain":"x"}'))).toBeUndefined();
+  });
+
+  it("refuses a broken file or an out-of-range value", () => {
+    expect(() => recordedSchedulerIntervalMinutes(config("c.json", "{"))).toThrow("not valid JSON");
+    expect(() =>
+      recordedSchedulerIntervalMinutes(config("d.json", '{"schedulerIntervalMinutes":30}')),
+    ).toThrow("between 1 and 15");
+    expect(() =>
+      recordedSchedulerIntervalMinutes(config("e.json", '{"schedulerIntervalMinutes":"2"}')),
+    ).toThrow("not a number");
+  });
+});
+
+describe("selfHostedSchedulerIntervalMinutes", () => {
+  it("keeps the recorded interval when the Pulumi key is unset", () => {
+    expect(selfHostedSchedulerIntervalMinutes(undefined, 2, "config.json")).toBe(2);
+    expect(selfHostedSchedulerIntervalMinutes(undefined, undefined, "config.json")).toBeUndefined();
+  });
+
+  it("takes the Pulumi key on a Pulumi-only install, or when both agree", () => {
+    expect(selfHostedSchedulerIntervalMinutes(3, undefined, "config.json")).toBe(3);
+    expect(selfHostedSchedulerIntervalMinutes(2, 2, "config.json")).toBe(2);
+  });
+
+  it("refuses a Pulumi key that disagrees with the record", () => {
+    expect(() => selfHostedSchedulerIntervalMinutes(5, 2, "config.json")).toThrow(
+      "config.json records 2",
+    );
+  });
+});

package/src/self-hosted-scheduler-interval.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1140 — the self-hosted scheduler interval has two places it can be set:
+ * `cms-provision init --scheduler-interval-minutes` records it in
+ * `.caelo/config.json` (which every CLI render — `up`, `upgrade`, agent
+ * apply — reads), and the Pulumi stack has the config key
+ * `caelo-self-hosted:schedulerIntervalMinutes`. Both rewrite the same
+ * `docker-compose.yml`, so if each read only its own source a `pulumi up`
+ * over a CLI install would silently put the interval back to the default,
+ * and the next CLI `upgrade` would undo a Pulumi-only value the same way.
+ *
+ * The recorded `.caelo/config.json` is the install's one record (the CLI
+ * renders from nothing else), so the stack takes the interval from it; the
+ * Pulumi key may restate it but a different value is refused rather than
+ * one side winning silently (CLAUDE.md §2: no fallbacks).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { parseSchedulerIntervalMinutes } from "./stack-contract.js";
+
+/**
+ * Read the interval `init` recorded in a `.caelo/config.json`.
+ *
+ * @param configPath - the install's `config.json`.
+ * @returns the recorded minutes, or undefined when there is no config.json
+ *   (a Pulumi-only install) or it records no interval (the default).
+ * @throws when the file is not JSON or the recorded value is out of bounds.
+ */
+export function recordedSchedulerIntervalMinutes(configPath: string): number | undefined {
+  if (!existsSync(configPath)) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (e) {
+    throw new Error(`${configPath} is not valid JSON: ${(e as Error).message}`);
+  }
+  const raw =
+    parsed !== null && typeof parsed === "object"
+      ? (parsed as { schedulerIntervalMinutes?: unknown }).schedulerIntervalMinutes
+      : undefined;
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "number") {
+    throw new Error(
+      `${configPath}: schedulerIntervalMinutes ${JSON.stringify(raw)} is not a number of minutes`,
+    );
+  }
+  return parseSchedulerIntervalMinutes(raw, `${configPath}: schedulerIntervalMinutes`);
+}
+
+/**
+ * The interval the self-hosted Pulumi stack renders into the Compose file.
+ *
+ * @param pulumiValue - `caelo-self-hosted:schedulerIntervalMinutes`, if set.
+ * @param recorded - what {@link recordedSchedulerIntervalMinutes} read.
+ * @param configPath - named in the refusal.
+ * @returns the minutes to render; undefined means neither source sets one
+ *   (the generator's default).
+ * @throws when both are set and differ.
+ */
+export function selfHostedSchedulerIntervalMinutes(
+  pulumiValue: number | undefined,
+  recorded: number | undefined,
+  configPath: string,
+): number | undefined {
+  if (pulumiValue === undefined) return recorded;
+  const minutes = parseSchedulerIntervalMinutes(
+    pulumiValue,
+    "caelo-self-hosted:schedulerIntervalMinutes",
+  );
+  if (recorded !== undefined && recorded !== minutes) {
+    throw new Error(
+      `caelo-self-hosted:schedulerIntervalMinutes is ${minutes} but ${configPath} records ${recorded}; ` +
+        "the CLI renders the Compose file from config.json, so the two must agree. " +
+        `Set the Pulumi key to ${recorded}, or remove it (\`pulumi config rm caelo-self-hosted:schedulerIntervalMinutes\`) to use the recorded value.`,
+    );
+  }
+  return minutes;
+}