@caelo-cms/provisioning 0.11.9 → 0.11.11

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

@@ -6,7 +6,11 @@ import {
   COMPOSE_ADMIN_UPSTREAM,
   COMPOSE_APP_SERVICES,
   COMPOSE_GATEWAY_UPSTREAM,
+  COMPOSE_MCP_AUTH_PROXY_SERVICE,
+  COMPOSE_MCP_AUTH_PROXY_UPSTREAM,
   COMPOSE_POOL_BUDGET,
+  COMPOSE_SCHEDULER_SERVICE,
+  COMPOSE_SCHEDULER_TICK_URL,
   type ComposeSpec,
   composeProjectName,
   generateDockerCompose,
@@ -20,8 +24,9 @@ const GATEWAY = `ghcr.io/caelo-cms/gateway@sha256:${"b".repeat(64)}`;
 const base: Omit<ComposeSpec, "images"> = {
   domain: "example.com",
   postgresPassword: "pgpw",
-  rolePasswords: { admin: "adminpw", public: "publicpw" },
+  rolePasswords: { admin: "adminpw", public: "publicpw", publicStaging: "ps" },
   caeloSecretKek: "0".repeat(64),
+  dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
   internalSecret: "i".repeat(48),
   anthropicApiKey: "sk-ant-x",
   diskSize: "20Gi",
@@ -53,6 +58,7 @@ describe("self-hosted Compose — internal secret (#770)", () => {
     expect(() =>
       generateDockerCompose({
         ...base,
+        dbTlsServerCertSha256: "abababababababababababababababababababababababababababababababab",
         internalSecret: "short",
         images: { mode: "release", admin: ADMIN, gateway: GATEWAY },
       }),
@@ -68,10 +74,23 @@ describe("self-hosted Compose — connection budget (#1254)", () => {
 
   it("starts Postgres with the max_connections the budget is computed from", () => {
     expect(service(yaml, "postgres")).toContain(
-      'command: ["postgres", "-c", "max_connections=100"]',
+      'command: ["postgres", "-c", "max_connections=100", ',
     );
   });
 
+  it("serves TLS with the install's own certificate, never a key it does not own (#1338)", () => {
+    const pg = service(yaml, "postgres");
+    expect(pg).toContain('"-c", "ssl=on"');
+    expect(pg).toContain("- ./postgres-tls/server.crt:/caelo-tls/server.crt:ro");
+    expect(pg).toContain("- ./postgres-tls/server.key:/caelo-tls/server.key:ro");
+    // The bind mount keeps the host's owner; Postgres only reads its own key.
+    expect(pg).toContain("install -o postgres -g postgres -m 0600 /caelo-tls/server.key");
+    expect(pg).toContain('exec docker-entrypoint.sh \\"$$@\\"');
+    // Only Postgres sees the server key; the CA key never leaves .caelo/.
+    expect(yaml.replace(pg, "")).not.toContain("server.key");
+    expect(yaml).not.toContain("ca.key");
+  });
+
   it("sizes the admin's two pools and the gateway's one", () => {
     expect(service(yaml, "caelo-admin")).toContain(
       `      CAELO_DB_POOL_MAX: "${COMPOSE_POOL_BUDGET.budget.adminPoolMax}"`,
@@ -82,6 +101,26 @@ describe("self-hosted Compose — connection budget (#1254)", () => {
   });
 });
 
+describe("self-hosted Compose — database certificate renewal (#1338)", () => {
+  const render = (digest: string) =>
+    generateDockerCompose({
+      ...base,
+      dbTlsServerCertSha256: digest,
+      images: { mode: "release", admin: ADMIN, gateway: GATEWAY },
+    });
+
+  it("carries the server certificate's digest on Postgres, so a renewal recreates it", () => {
+    const before = service(render("a".repeat(64)), "postgres");
+    const after = service(render("c".repeat(64)), "postgres");
+    expect(before).toContain(`CAELO_DB_TLS_SERVER_CERT_SHA256: "${"a".repeat(64)}"`);
+    expect(after).not.toBe(before);
+  });
+
+  it("refuses a value that is no SHA-256 digest", () => {
+    expect(() => render("not-a-digest")).toThrow("dbTlsServerCertSha256");
+  });
+});
+
 describe("self-hosted Compose — release images (#696)", () => {
   const yaml = generateDockerCompose({
     ...base,
@@ -104,10 +143,13 @@ describe("self-hosted Compose — release images (#696)", () => {
   it("mounts the bootstrap-token, site output + media dirs, never .caelo/ with its secrets", () => {
     const admin = service(yaml, "caelo-admin");
     expect(admin).toContain(
-      "    volumes:\n      - ./bootstrap:/app/.caelo\n      - ./output:/srv/caelo\n      - ./media:/data/media",
+      "    volumes:\n      - ./bootstrap:/app/.caelo\n      - ./output:/srv/caelo\n      - ./media:/data/media\n      - ./postgres-tls/ca.crt:/etc/caelo/db-ca/self-hosted-ca.pem:ro",
     );
     expect(yaml).not.toMatch(/- \.\/?:/);
-    expect(service(yaml, "caelo-gateway")).not.toContain("volumes:");
+    // The gateway mounts the database CA (#1338) and nothing else.
+    expect(service(yaml, "caelo-gateway")).toContain(
+      "    volumes:\n      - ./postgres-tls/ca.crt:/etc/caelo/db-ca/self-hosted-ca.pem:ro\n    restart:",
+    );
     expect(admin).toContain('CAELO_OUTPUT_ROOT: "/srv/caelo"');
     expect(admin).toContain('MEDIA_ROOT_DIR: "/data/media"');
     expect(service(yaml, "caddy")).toContain("- ./output:/srv/caelo:ro");
@@ -116,10 +158,10 @@ describe("self-hosted Compose — release images (#696)", () => {
   it("keeps the env + secret wiring of each service", () => {
     const admin = service(yaml, "caelo-admin");
     expect(admin).toContain(
-      'ADMIN_DATABASE_URL: "postgres://admin_role:adminpw@postgres:5432/cms_admin"',
+      'ADMIN_DATABASE_URL: "postgres://admin_role:adminpw@postgres:5432/cms_admin?sslmode=verify-full&sslrootcert=/etc/caelo/db-ca/self-hosted-ca.pem"',
     );
     expect(admin).toContain(
-      'PUBLIC_ADMIN_DATABASE_URL: "postgres://admin_role:adminpw@postgres:5432/cms_public"',
+      'PUBLIC_ADMIN_DATABASE_URL: "postgres://admin_role:adminpw@postgres:5432/cms_public?sslmode=verify-full&sslrootcert=/etc/caelo/db-ca/self-hosted-ca.pem"',
     );
     expect(admin).toContain(`CAELO_SECRET_KEK: "${"0".repeat(64)}"`);
     expect(admin).toContain('CAELO_SITE_URL: "https://example.com"');
@@ -307,3 +349,135 @@ describe("self-hosted Compose — the host update agent (#696 Phase 4c)", () =>
     ).toThrow(/between 1024 and 65535/);
   });
 });
+
+describe("self-hosted Compose — the MCP-Auth-Proxy (#1328)", () => {
+  const PROXY = `ghcr.io/caelo-cms/mcp-auth-proxy@sha256:${"c".repeat(64)}`;
+  const yaml = generateDockerCompose({
+    ...base,
+    images: { mode: "release", admin: ADMIN, gateway: GATEWAY, "mcp-auth-proxy": PROXY },
+  });
+  const proxy = service(yaml, COMPOSE_MCP_AUTH_PROXY_SERVICE);
+
+  it("runs the digest-pinned release image on the port Caddy proxies to", () => {
+    expect(proxy).toContain(`image: ${PROXY}`);
+    expect(proxy).toContain('MCP_AUTH_PROXY_PORT: "8095"');
+    expect(COMPOSE_MCP_AUTH_PROXY_UPSTREAM).toBe("caelo-mcp-auth-proxy:8095");
+  });
+
+  it("says remote MCP is unavailable here and trusts Caddy as the one hop", () => {
+    expect(proxy).toContain('CAELO_REMOTE_MCP: "unavailable"');
+    expect(proxy).toContain('CAELO_TRUSTED_PROXY_HOPS: "1"');
+    expect(proxy).toContain('CAELO_PROVIDER: "self-hosted"');
+  });
+
+  it("gets no database URL, no secret, no mount and no dependency on Postgres", () => {
+    expect(proxy).not.toMatch(/DATABASE|PASSWORD|SECRET|KEK|postgres:\/\/|volumes:|depends_on/);
+    expect(proxy).not.toContain("adminpw");
+    expect(proxy).not.toContain("publicpw");
+  });
+
+  it("runs locked down: read-only root, no capabilities, no privilege escalation", () => {
+    expect(proxy).toContain("read_only: true");
+    expect(proxy).toContain('cap_drop: ["ALL"]');
+    expect(proxy).toContain('security_opt: ["no-new-privileges:true"]');
+  });
+
+  it("is absent for a release recorded before the proxy shipped", () => {
+    const old = generateDockerCompose({
+      ...base,
+      images: { mode: "release", admin: ADMIN, gateway: GATEWAY },
+    });
+    expect(old).not.toContain(COMPOSE_MCP_AUTH_PROXY_SERVICE);
+    expect(old).toContain("\n\nvolumes:\n");
+  });
+
+  it("runs the checkout's proxy in dev mode", () => {
+    const dev = generateDockerCompose({ ...base, images: { mode: "dev" } });
+    expect(service(dev, COMPOSE_MCP_AUTH_PROXY_SERVICE)).toContain(
+      "command: bun run apps/mcp-auth-proxy/src/server.ts",
+    );
+  });
+
+  it("refuses a proxy image that is not a digest-pinned GHCR reference", () => {
+    expect(() =>
+      generateDockerCompose({
+        ...base,
+        images: {
+          mode: "release",
+          admin: ADMIN,
+          gateway: GATEWAY,
+          "mcp-auth-proxy": "ghcr.io/caelo-cms/mcp-auth-proxy:latest",
+        },
+      }),
+    ).toThrow(/mcp-auth-proxy image/);
+  });
+});
+
+describe("self-hosted Compose — the scheduler tick (#1140)", () => {
+  const yaml = generateDockerCompose({
+    ...base,
+    images: { mode: "release", admin: ADMIN, gateway: GATEWAY },
+  });
+  const scheduler = service(yaml, COMPOSE_SCHEDULER_SERVICE);
+
+  it("runs the admin image's clock against the admin's tick endpoint", () => {
+    expect(scheduler).toContain(`image: ${ADMIN}`);
+    expect(scheduler).toContain(
+      'command: ["bun", "--bun", "/app/packages/admin-core/src/scheduler/clock.ts"]',
+    );
+    expect(COMPOSE_SCHEDULER_TICK_URL).toBe("http://caelo-admin:5173/api/internal/scheduler/tick");
+    expect(scheduler).toContain(`CAELO_SCHEDULER_TICK_URL: "${COMPOSE_SCHEDULER_TICK_URL}"`);
+    expect(scheduler).toContain("depends_on: [caelo-admin]");
+  });
+
+  it("ticks every 5 minutes by default and follows the knob", () => {
+    expect(scheduler).toContain('CAELO_SCHEDULER_INTERVAL_MINUTES: "5"');
+    const fast = generateDockerCompose({
+      ...base,
+      schedulerIntervalMinutes: 1,
+      images: { mode: "release", admin: ADMIN, gateway: GATEWAY },
+    });
+    expect(service(fast, COMPOSE_SCHEDULER_SERVICE)).toContain(
+      'CAELO_SCHEDULER_INTERVAL_MINUTES: "1"',
+    );
+  });
+
+  it("refuses an interval outside 1-15 minutes", () => {
+    for (const bad of [0, 16, 2.5]) {
+      expect(() =>
+        generateDockerCompose({
+          ...base,
+          schedulerIntervalMinutes: bad,
+          images: { mode: "release", admin: ADMIN, gateway: GATEWAY },
+        }),
+      ).toThrow("schedulerIntervalMinutes");
+    }
+  });
+
+  it("holds only the internal secret it signs with: no database, no KEK, no mount", () => {
+    expect(scheduler).toContain(`CAELO_INTERNAL_SECRET: "${"i".repeat(48)}"`);
+    expect(scheduler).not.toMatch(/DATABASE|PASSWORD|KEK|postgres:\/\/|volumes:/);
+    expect(scheduler).not.toContain("adminpw");
+    expect(scheduler).not.toContain("0".repeat(64));
+  });
+
+  it("runs locked down: read-only root, no capabilities, no privilege escalation", () => {
+    expect(scheduler).toContain("read_only: true");
+    expect(scheduler).toContain('cap_drop: ["ALL"]');
+    expect(scheduler).toContain('security_opt: ["no-new-privileges:true"]');
+  });
+
+  it("runs the checkout's clock in dev mode", () => {
+    const dev = generateDockerCompose({ ...base, images: { mode: "dev" } });
+    expect(service(dev, COMPOSE_SCHEDULER_SERVICE)).toContain(
+      "command: bun run packages/admin-core/src/scheduler/clock.ts",
+    );
+  });
+
+  it("is part of every rendered Compose file, so an upgrade of an older install adds it", () => {
+    // self-hosted-upgrade.ts rolls onto renderCompose(<new images>), which is
+    // this generator: the next upgrade of an install without the service
+    // writes a Compose file that has it, and `docker compose up -d` starts it.
+    expect(yaml).toContain(`\n  ${COMPOSE_SCHEDULER_SERVICE}:\n`);
+  });
+});

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

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { afterEach, describe, expect, it } from "bun:test";
+import { X509Certificate } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ensureSelfHostedDbTls,
+  generateDatabaseTls,
+  SELF_HOSTED_DB_HOST,
+  SELF_HOSTED_TLS_DIR,
+  serverCertProblem,
+} from "./self-hosted-db-tls.js";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+function tempDir(): string {
+  const d = mkdtempSync(join(tmpdir(), "caelo-db-tls-"));
+  dirs.push(d);
+  return d;
+}
+
+describe("generateDatabaseTls", () => {
+  it("makes a CA and a server certificate for `postgres` that chains to it", () => {
+    const files = generateDatabaseTls();
+    const ca = new X509Certificate(files.caCert);
+    const server = new X509Certificate(files.serverCert);
+    expect(ca.ca).toBe(true);
+    expect(server.ca).toBe(false);
+    expect(ca.verify(ca.publicKey)).toBe(true);
+    expect(server.verify(ca.publicKey)).toBe(true);
+    expect(server.checkHost(SELF_HOSTED_DB_HOST)).toBe(SELF_HOSTED_DB_HOST);
+    expect(server.checkHost("evil.example")).toBeUndefined();
+    expect(server.issuer).toBe(ca.subject);
+    expect(serverCertProblem(files.caCert, files.serverCert, new Date())).toBeNull();
+  });
+
+  it("passes a real TLS handshake with host-name verification (Bun's TLS)", async () => {
+    // The same check a verify-full Postgres client makes: the chain must end
+    // at the CA we pass, and the certificate must name the host dialled.
+    // `localhost` stands in for `postgres` (resolvable here), via the same
+    // generator path.
+    const files = generateDatabaseTls();
+    using server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      tls: { cert: files.serverCert, key: files.serverKey },
+      fetch: () => new Response("ok"),
+    });
+    const url = `https://127.0.0.1:${server.port}/`;
+    // Right CA + the certificate's host name (SNI/verify against `postgres`).
+    const ok = await fetch(url, {
+      tls: {
+        ca: files.caCert,
+        checkServerIdentity: (_host, cert) =>
+          cert.subjectaltname === `DNS:${SELF_HOSTED_DB_HOST}`
+            ? undefined
+            : new Error(`unexpected SAN ${cert.subjectaltname}`),
+      },
+    });
+    expect(await ok.text()).toBe("ok");
+    // Another CA: the chain does not verify.
+    await expect(fetch(url, { tls: { ca: generateDatabaseTls().caCert } })).rejects.toThrow();
+  });
+});
+
+describe("ensureSelfHostedDbTls", () => {
+  it("creates the files once, keys 0600, and keeps them on a re-run", () => {
+    const caelo = tempDir();
+    expect(ensureSelfHostedDbTls(caelo)).toHaveLength(1);
+    const dir = join(caelo, SELF_HOSTED_TLS_DIR);
+    expect(statSync(join(dir, "ca.key")).mode & 0o777).toBe(0o600);
+    expect(statSync(join(dir, "server.key")).mode & 0o777).toBe(0o600);
+    const ca = readFileSync(join(dir, "ca.crt"), "utf8");
+    const server = readFileSync(join(dir, "server.crt"), "utf8");
+    expect(ensureSelfHostedDbTls(caelo)).toEqual([]);
+    expect(readFileSync(join(dir, "ca.crt"), "utf8")).toBe(ca);
+    expect(readFileSync(join(dir, "server.crt"), "utf8")).toBe(server);
+  });
+
+  it("re-issues a server certificate near its end from the same CA", () => {
+    const caelo = tempDir();
+    ensureSelfHostedDbTls(caelo);
+    const dir = join(caelo, SELF_HOSTED_TLS_DIR);
+    const ca = readFileSync(join(dir, "ca.crt"), "utf8");
+    const later = new Date(Date.now() + 9.5 * 365 * 24 * 3600 * 1000);
+    const done = ensureSelfHostedDbTls(caelo, later);
+    expect(done[0]).toMatch(/re-issued.*expires/);
+    expect(readFileSync(join(dir, "ca.crt"), "utf8")).toBe(ca);
+    const fresh = readFileSync(join(dir, "server.crt"), "utf8");
+    expect(serverCertProblem(ca, fresh, later)).toBeNull();
+  });
+
+  it("re-issues a server certificate another CA signed", () => {
+    const caelo = tempDir();
+    ensureSelfHostedDbTls(caelo);
+    const dir = join(caelo, SELF_HOSTED_TLS_DIR);
+    writeFileSync(join(dir, "server.crt"), generateDatabaseTls().serverCert);
+    expect(ensureSelfHostedDbTls(caelo)[0]).toMatch(/not signed by the install's CA/);
+  });
+
+  it("refuses half a CA instead of silently replacing the trust anchor", () => {
+    const caelo = tempDir();
+    ensureSelfHostedDbTls(caelo);
+    rmSync(join(caelo, SELF_HOSTED_TLS_DIR, "ca.key"));
+    expect(() => ensureSelfHostedDbTls(caelo)).toThrow(/only half of the database CA/);
+  });
+});

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");
+}