@caelo-cms/provisioning 0.11.8 → 0.11.10

package/src/self-hosted-db-tls.ts

@@ -0,0 +1,287 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1338 (gateway hardening L6) — verify-full TLS between the self-hosted
+ * Compose services and their Postgres.
+ *
+ * The admin and the gateway reach Postgres over the Compose network as
+ * `postgres:5432`. With `sslmode=verify-full` they need a server
+ * certificate for exactly that host name, signed by a CA they trust. No
+ * public CA issues a certificate for `postgres`, so every install makes its
+ * own: an ECDSA P-256 CA, generated once and kept in `.caelo/postgres-tls/`
+ * (like the install's other secrets in `.caelo/`), and a server certificate
+ * it signs. The CA certificate is mounted read-only into the admin and the
+ * gateway at shared `SELF_HOSTED_CA_FILE`; the server key only into
+ * Postgres.
+ *
+ * Generated with `node:crypto` and a minimal DER encoder below, so an
+ * install needs neither openssl on the host nor a new dependency (§3).
+ * Postgres reads ECDSA keys; Bun's TLS verifies the chain and the host.
+ *
+ * Re-runs keep what exists (the CA never changes once made, so no client
+ * ever needs a new trust anchor); a server certificate that is missing,
+ * does not chain to the CA, does not name `postgres`, or expires within a
+ * year is re-issued from the stored CA key.
+ */
+
+import {
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  type KeyObject,
+  randomBytes,
+  sign,
+  X509Certificate,
+} from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The directory under `.caelo/` that holds the install's database TLS files. */
+export const SELF_HOSTED_TLS_DIR = "postgres-tls";
+
+/** The host name the services dial Postgres by on the Compose network. */
+export const SELF_HOSTED_DB_HOST = "postgres";
+
+/** File names inside {@link SELF_HOSTED_TLS_DIR}. */
+export const SELF_HOSTED_TLS_FILES = {
+  caCert: "ca.crt",
+  caKey: "ca.key",
+  serverCert: "server.crt",
+  serverKey: "server.key",
+} as const;
+
+const YEAR_MS = 365 * 24 * 3600 * 1000;
+const CA_VALIDITY_YEARS = 30;
+const SERVER_VALIDITY_YEARS = 10;
+/** A server certificate closer than this to its end is re-issued. */
+const RENEW_BEFORE_MS = YEAR_MS;
+
+// ---------------------------------------------------------------------------
+// Minimal DER (X.690) — only what an X.509 v3 certificate needs.
+// ---------------------------------------------------------------------------
+
+function derLength(n: number): Buffer {
+  if (n < 0x80) return Buffer.from([n]);
+  const bytes: number[] = [];
+  for (let v = n; v > 0; v = Math.floor(v / 256)) bytes.unshift(v & 0xff);
+  return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+function tlv(tag: number, value: Buffer): Buffer {
+  return Buffer.concat([Buffer.from([tag]), derLength(value.length), value]);
+}
+
+const seq = (...items: Buffer[]) => tlv(0x30, Buffer.concat(items));
+const set = (...items: Buffer[]) => tlv(0x31, Buffer.concat(items));
+const explicit = (n: number, inner: Buffer) => tlv(0xa0 + n, inner);
+const octets = (b: Buffer) => tlv(0x04, b);
+/** A BIT STRING; `unused` trailing bits of the last byte (DER: minimal for named bits). */
+const bitString = (b: Buffer, unused = 0) => tlv(0x03, Buffer.concat([Buffer.from([unused]), b]));
+const utf8 = (s: string) => tlv(0x0c, Buffer.from(s, "utf8"));
+const bool = (v: boolean) => tlv(0x01, Buffer.from([v ? 0xff : 0]));
+
+function integer(b: Buffer): Buffer {
+  let v = b;
+  while (v.length > 1 && v[0] === 0 && (v[1] ?? 0) < 0x80) v = v.subarray(1);
+  if ((v[0] ?? 0) >= 0x80) v = Buffer.concat([Buffer.from([0]), v]);
+  return tlv(0x02, v);
+}
+
+function oid(dotted: string): Buffer {
+  const parts = dotted.split(".").map(Number);
+  const out: number[] = [40 * (parts[0] ?? 0) + (parts[1] ?? 0)];
+  for (const p of parts.slice(2)) {
+    const chunk: number[] = [p & 0x7f];
+    for (let v = Math.floor(p / 128); v > 0; v = Math.floor(v / 128))
+      chunk.unshift(0x80 | (v & 0x7f));
+    out.push(...chunk);
+  }
+  return tlv(0x06, Buffer.from(out));
+}
+
+/** UTCTime until 2049, GeneralizedTime from 2050 (RFC 5280 §4.1.2.5). */
+function time(d: Date): Buffer {
+  const iso = d.toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  return d.getUTCFullYear() < 2050
+    ? tlv(0x17, Buffer.from(`${iso.slice(2)}Z`))
+    : tlv(0x18, Buffer.from(`${iso}Z`));
+}
+
+const ECDSA_SHA256 = seq(oid("1.2.840.10045.4.3.2"));
+const name = (cn: string) => seq(set(seq(oid("2.5.4.3"), utf8(cn))));
+const extension = (id: string, critical: boolean, value: Buffer) =>
+  seq(oid(id), ...(critical ? [bool(true)] : []), octets(value));
+
+interface CertSpec {
+  readonly subject: string;
+  readonly issuer: string;
+  readonly publicKey: KeyObject;
+  readonly signingKey: KeyObject;
+  readonly notBefore: Date;
+  readonly notAfter: Date;
+  readonly ca: boolean;
+  /** DNS subjectAltNames (server certificates). */
+  readonly dnsNames?: readonly string[];
+}
+
+function certificatePem(spec: CertSpec): string {
+  const spki = spec.publicKey.export({ type: "spki", format: "der" });
+  const exts = [
+    extension("2.5.29.19", true, spec.ca ? seq(bool(true)) : seq()),
+    // keyCertSign + cRLSign for the CA; digitalSignature for the server.
+    extension(
+      "2.5.29.15",
+      true,
+      spec.ca ? bitString(Buffer.from([0x06]), 1) : bitString(Buffer.from([0x80]), 7),
+    ),
+    ...(spec.ca
+      ? []
+      : [
+          extension("2.5.29.37", false, seq(oid("1.3.6.1.5.5.7.3.1"))),
+          extension(
+            "2.5.29.17",
+            false,
+            seq(...(spec.dnsNames ?? []).map((n) => tlv(0x82, Buffer.from(n, "ascii")))),
+          ),
+        ]),
+  ];
+  const tbs = seq(
+    explicit(0, integer(Buffer.from([2]))),
+    integer(Buffer.concat([Buffer.from([0x01]), randomBytes(15)])),
+    ECDSA_SHA256,
+    name(spec.issuer),
+    seq(time(spec.notBefore), time(spec.notAfter)),
+    name(spec.subject),
+    spki,
+    explicit(3, seq(...exts)),
+  );
+  const signature = sign("sha256", tbs, { key: spec.signingKey, dsaEncoding: "der" });
+  const der = seq(tbs, ECDSA_SHA256, bitString(signature));
+  const b64 = der.toString("base64").replace(/.{64}/g, "$&\n").replace(/\n$/, "");
+  return `-----BEGIN CERTIFICATE-----\n${b64}\n-----END CERTIFICATE-----\n`;
+}
+
+/** The PEM files of an install's database TLS. */
+export interface DatabaseTlsFiles {
+  readonly caCert: string;
+  readonly caKey: string;
+  readonly serverCert: string;
+  readonly serverKey: string;
+}
+
+function newKeyPair() {
+  return generateKeyPairSync("ec", { namedCurve: "P-256" });
+}
+
+/** A server certificate for {@link SELF_HOSTED_DB_HOST}, signed by the CA. */
+function issueServer(
+  ca: { cert: string; key: KeyObject },
+  now: Date,
+): Pick<DatabaseTlsFiles, "serverCert" | "serverKey"> {
+  const server = newKeyPair();
+  const caSubject = new X509Certificate(ca.cert).subject.replace(/^CN=/, "");
+  return {
+    serverCert: certificatePem({
+      subject: SELF_HOSTED_DB_HOST,
+      issuer: caSubject,
+      publicKey: server.publicKey,
+      signingKey: ca.key,
+      notBefore: new Date(now.getTime() - 3600 * 1000),
+      notAfter: new Date(now.getTime() + SERVER_VALIDITY_YEARS * YEAR_MS),
+      ca: false,
+      dnsNames: [SELF_HOSTED_DB_HOST],
+    }),
+    serverKey: server.privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  };
+}
+
+/** A fresh CA and a server certificate it signed. */
+export function generateDatabaseTls(now: Date = new Date()): DatabaseTlsFiles {
+  const ca = newKeyPair();
+  const caCert = certificatePem({
+    subject: "Caelo self-hosted database CA",
+    issuer: "Caelo self-hosted database CA",
+    publicKey: ca.publicKey,
+    signingKey: ca.privateKey,
+    notBefore: new Date(now.getTime() - 3600 * 1000),
+    notAfter: new Date(now.getTime() + CA_VALIDITY_YEARS * YEAR_MS),
+    ca: true,
+  });
+  return {
+    caCert,
+    caKey: ca.privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    ...issueServer({ cert: caCert, key: ca.privateKey }, now),
+  };
+}
+
+/** Why `serverCert` must be re-issued, or null when it is fine. */
+export function serverCertProblem(caCert: string, serverCert: string, now: Date): string | null {
+  try {
+    const ca = new X509Certificate(caCert);
+    const server = new X509Certificate(serverCert);
+    if (!server.verify(ca.publicKey)) return "it is not signed by the install's CA";
+    if (server.checkHost(SELF_HOSTED_DB_HOST) !== SELF_HOSTED_DB_HOST) {
+      return `it does not name ${SELF_HOSTED_DB_HOST}`;
+    }
+    if (Date.parse(server.validTo) - now.getTime() < RENEW_BEFORE_MS) {
+      return `it expires ${server.validTo}`;
+    }
+    return null;
+  } catch (e) {
+    return `it does not parse (${e instanceof Error ? e.message : String(e)})`;
+  }
+}
+
+/**
+ * Make sure `<caeloDir>/postgres-tls/` holds the install's CA and a valid
+ * server certificate; returns what it did (empty when nothing changed).
+ * The CA is created once and never replaced.
+ */
+export function ensureSelfHostedDbTls(caeloDir: string, now: Date = new Date()): string[] {
+  const dir = join(caeloDir, SELF_HOSTED_TLS_DIR);
+  const path = (f: keyof typeof SELF_HOSTED_TLS_FILES) => join(dir, SELF_HOSTED_TLS_FILES[f]);
+  // The CA key and the server key are secrets; the certificates are not,
+  // but every container reads them through a bind mount, so 0644.
+  const write = (f: keyof typeof SELF_HOSTED_TLS_FILES, content: string) =>
+    writeFileSync(path(f), content, { mode: f.endsWith("Key") ? 0o600 : 0o644 });
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const done: string[] = [];
+  if (!existsSync(path("caCert")) || !existsSync(path("caKey"))) {
+    if (existsSync(path("caCert")) !== existsSync(path("caKey"))) {
+      throw new Error(
+        `${dir} holds only half of the database CA (${SELF_HOSTED_TLS_FILES.caCert} / ${SELF_HOSTED_TLS_FILES.caKey}). Restore the missing file from your backup of .caelo/, or delete both to make a new CA (every service is re-created with it on the next \`cms-provision up\`).`,
+      );
+    }
+    const files = generateDatabaseTls(now);
+    for (const f of Object.keys(SELF_HOSTED_TLS_FILES) as (keyof typeof SELF_HOSTED_TLS_FILES)[]) {
+      write(f, files[f]);
+    }
+    done.push(
+      `created the install's database CA and the server certificate for ${SELF_HOSTED_DB_HOST}`,
+    );
+    return done;
+  }
+  const caCert = readFileSync(path("caCert"), "utf8");
+  const problem = existsSync(path("serverCert"))
+    ? serverCertProblem(caCert, readFileSync(path("serverCert"), "utf8"), now)
+    : "it is missing";
+  if (problem === null && existsSync(path("serverKey"))) return done;
+  const key = createPrivateKey(readFileSync(path("caKey"), "utf8"));
+  const issued = issueServer({ cert: caCert, key }, now);
+  write("serverCert", issued.serverCert);
+  write("serverKey", issued.serverKey);
+  done.push(`re-issued the database server certificate (${problem ?? "its key was missing"})`);
+  return done;
+}
+
+/**
+ * SHA-256 (hex) of the install's database server certificate, which the
+ * Compose file carries on the Postgres service so a renewed certificate
+ * recreates it (compose.ts `dbTlsServerCertSha256`).
+ *
+ * @throws when the certificate is missing: call {@link ensureSelfHostedDbTls} first.
+ */
+export function selfHostedDbTlsServerCertSha256(caeloDir: string): string {
+  const cert = readFileSync(join(caeloDir, SELF_HOSTED_TLS_DIR, SELF_HOSTED_TLS_FILES.serverCert));
+  return createHash("sha256").update(cert).digest("hex");
+}

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.test.ts

@@ -1,9 +1,14 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import {
+  applyPublicRoleLimits,
   convergeSelfHostedRoles,
   decideUp,
+  PUBLIC_ROLE_LIMITS,
+  publicRoleLimitsScript,
   roleConvergenceScript,
   selfHostedBootstrapScript,
 } from "./self-hosted-roles.js";
@@ -126,3 +131,52 @@ describe("decideUp — `cms-provision up` never switches URLs onto unapplied pas
     expect(d).toMatchObject({ kind: "proceed", markConverged: false });
   });
 });
+
+describe("public_role's limits (#1338, H3)", () => {
+  const statements = [
+    `ALTER ROLE public_role CONNECTION LIMIT ${PUBLIC_ROLE_LIMITS.connectionLimit};`,
+    `ALTER ROLE public_role SET statement_timeout = '${PUBLIC_ROLE_LIMITS.statementTimeout}';`,
+    `ALTER ROLE public_role SET idle_in_transaction_session_timeout = '${PUBLIC_ROLE_LIMITS.idleInTransactionSessionTimeout}';`,
+    `ALTER ROLE public_role SET work_mem = '${PUBLIC_ROLE_LIMITS.workMem}';`,
+  ];
+
+  it("are set on the first start, on every `up`, and alone before an upgrade's migrations", () => {
+    for (const script of [
+      selfHostedBootstrapScript({ agent: false }),
+      roleConvergenceScript(PASSWORDS),
+      publicRoleLimitsScript(),
+    ]) {
+      for (const st of statements) expect(script).toContain(st);
+    }
+    // The pre-migration script touches nothing else (no role drop, no grant).
+    expect(publicRoleLimitsScript().split("\n").filter(Boolean)).toEqual([
+      "\\set ON_ERROR_STOP on",
+      ...statements,
+    ]);
+  });
+
+  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 applyPublicRoleLimits({
+      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

@@ -38,6 +38,46 @@ export const AGENT_DB_ROLE = "caelo_agent";
 const APP_ROLES = ["admin_role", "public_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 publicRoleLimitsScript}).
+ */
+export const PUBLIC_ROLE_LIMITS = {
+  connectionLimit: 30,
+  statementTimeout: "5s",
+  idleInTransactionSessionTimeout: "15s",
+  workMem: "1MB",
+} as const;
+
+/** The statements that apply {@link PUBLIC_ROLE_LIMITS} (idempotent). */
+function publicRoleLimitsSql(): string[] {
+  const l = PUBLIC_ROLE_LIMITS;
+  return [
+    `ALTER ROLE public_role CONNECTION LIMIT ${l.connectionLimit};`,
+    `ALTER ROLE public_role SET statement_timeout = '${l.statementTimeout}';`,
+    `ALTER ROLE public_role SET idle_in_transaction_session_timeout = '${l.idleInTransactionSessionTimeout}';`,
+    `ALTER ROLE public_role SET work_mem = '${l.workMem}';`,
+  ];
+}
+
+/**
+ * The psql script (superuser) that applies only {@link PUBLIC_ROLE_LIMITS}.
+ * The self-hosted upgrade runs it BEFORE the migrations: their role audit
+ * refuses public_role without the limits, and 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 publicRoleLimitsScript(): string {
+  return ["\\set ON_ERROR_STOP on", ...publicRoleLimitsSql(), ""].join("\n");
+}
+
 /** How a role's password appears in the SQL: a literal, or a psql variable. */
 type PasswordSql = (role: AppRole | typeof AGENT_DB_ROLE) => string;
 
@@ -52,6 +92,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",
@@ -143,6 +184,23 @@ ${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 publicRoleLimitsScript} 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 applyPublicRoleLimits(deps: {
+  readonly probe: () => Promise<boolean>;
+  readonly psql: SuperuserPsql;
+}): Promise<ConvergeOutcome> {
+  if (!(await deps.probe())) {
+    return { ok: false, reachable: false, error: "the Postgres container is not running" };
+  }
+  const r = await deps.psql(publicRoleLimitsScript());
+  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. */