@wtfalch/foundry 0.37.0 → 0.39.0

package/dist/plan/signin-db-tls.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The certificate authority and server certificate of a company's sign-in
+ * database (#746). One CA serves the whole platform and is created once; each
+ * company's database gets its own server certificate, signed by it, for the
+ * database's internal hostname. Both are held in `@wtfalch/keys` as one JSON
+ * value each (`{ cert, key }`), so a CA is never half written.
+ *
+ * Node has no certificate builder, so the DER is written here: ECDSA P-256,
+ * SHA-256, X.509 v3, only the extensions Postgres clients check.
+ */
+/** The platform's one CA, held as JSON `{ cert, key }` (PEM strings). */
+export declare const SIGNIN_DB_CA_REF = "signin-db:platform:ca";
+/** The recorded id of the server certificate's expiry (milliseconds since the epoch), so the planner can renew it. Not a secret. */
+export declare const SIGNIN_DB_CERT_NOT_AFTER_SCOPE_KEY = "signin_db_cert_not_after";
+/** Recorded id of the database app. */
+export declare const SIGNIN_DB_APP_SCOPE_KEY = "signin_db_app";
+/**
+ * Recorded once ZITADEL's DSN names the TLS database: from then on the sign-in step
+ * provisions this database and never the Coolify one.
+ */
+export declare const SIGNIN_DB_TLS_SCOPE_KEY = "signin_db_tls";
+/**
+ * Recorded while ZITADEL has been started on the TLS database and not yet seen healthy there: the
+ * planner then plans the sign-in step, which starts ZITADEL again and clears it (#746).
+ */
+export declare const SIGNIN_DB_ZITADEL_PENDING_SCOPE_KEY = "signin_db_zitadel_pending";
+/** A server certificate with less than this left is issued again. */
+export declare const SIGNIN_DB_CERT_RENEW_WINDOW_MS: number;
+export interface SigninDbKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+export interface SigninDbTlsRuntime {
+    /** Called with every secret before it is stored or used, so no message or audit row can carry it. */
+    onSecret?: (value: string) => void;
+    now?: () => number;
+}
+export interface PemPair {
+    certPem: string;
+    keyPem: string;
+}
+export interface ServerCert extends PemPair {
+    /** Milliseconds since the epoch. */
+    notAfter: number;
+    /** True when this call made a new certificate. */
+    issued: boolean;
+}
+/**
+ * The platform's CA: the held one, else a new one stored under
+ * {@link SIGNIN_DB_CA_REF}. A held value that cannot be read, or whose
+ * certificate does not match its key, is an error and is never replaced: a
+ * company's database may already trust it. The value read back after a store
+ * is the one used, so two applies at once end with the same CA.
+ */
+export declare function ensureSigninDbCa(keys: SigninDbKeys, runtime?: SigninDbTlsRuntime, 
+/** A company already has a database or certificate made under the CA: a lost CA is then an error, never made again. */
+inUse?: boolean): Promise<PemPair>;
+/**
+ * The server certificate held under `ref` for `host`, issued again when it is
+ * missing, unreadable, for another host, signed by another CA, or has less
+ * than {@link SIGNIN_DB_CERT_RENEW_WINDOW_MS} left. The read-back after a
+ * store is the one used.
+ */
+export declare function ensureSigninDbServerCert(keys: SigninDbKeys, ca: PemPair, ref: string, host: string, runtime?: SigninDbTlsRuntime): Promise<ServerCert>;
+/**
+ * Whether the recorded server certificate expires within the renew window.
+ * Nothing recorded (a company not on the TLS database) is never due.
+ */
+export declare function signinDbCertDue(recordedIds: Readonly<Record<string, string>>, now: number): boolean;

package/dist/plan/signin-db-tls.js

@@ -0,0 +1,255 @@
+import { X509Certificate, createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign, } from 'node:crypto';
+/**
+ * The certificate authority and server certificate of a company's sign-in
+ * database (#746). One CA serves the whole platform and is created once; each
+ * company's database gets its own server certificate, signed by it, for the
+ * database's internal hostname. Both are held in `@wtfalch/keys` as one JSON
+ * value each (`{ cert, key }`), so a CA is never half written.
+ *
+ * Node has no certificate builder, so the DER is written here: ECDSA P-256,
+ * SHA-256, X.509 v3, only the extensions Postgres clients check.
+ */
+/** The platform's one CA, held as JSON `{ cert, key }` (PEM strings). */
+export const SIGNIN_DB_CA_REF = 'signin-db:platform:ca';
+/** The recorded id of the server certificate's expiry (milliseconds since the epoch), so the planner can renew it. Not a secret. */
+export const SIGNIN_DB_CERT_NOT_AFTER_SCOPE_KEY = 'signin_db_cert_not_after';
+/** Recorded id of the database app. */
+export const SIGNIN_DB_APP_SCOPE_KEY = 'signin_db_app';
+/**
+ * Recorded once ZITADEL's DSN names the TLS database: from then on the sign-in step
+ * provisions this database and never the Coolify one.
+ */
+export const SIGNIN_DB_TLS_SCOPE_KEY = 'signin_db_tls';
+/**
+ * Recorded while ZITADEL has been started on the TLS database and not yet seen healthy there: the
+ * planner then plans the sign-in step, which starts ZITADEL again and clears it (#746).
+ */
+export const SIGNIN_DB_ZITADEL_PENDING_SCOPE_KEY = 'signin_db_zitadel_pending';
+/** A server certificate with less than this left is issued again. */
+export const SIGNIN_DB_CERT_RENEW_WINDOW_MS = 30 * 24 * 3_600_000;
+const SERVER_CERT_VALIDITY_MS = 365 * 24 * 3_600_000;
+const CA_VALIDITY_MS = 10 * 365 * 24 * 3_600_000;
+/** The CA's subject. */
+const CA_COMMON_NAME = 'foundry sign-in database CA';
+// ---- DER ---------------------------------------------------------------------
+const der = (tag, ...parts) => {
+    const body = Buffer.concat(parts);
+    const n = body.length;
+    const len = n < 0x80
+        ? Buffer.from([n])
+        : n < 0x100
+            ? Buffer.from([0x81, n])
+            : Buffer.from([0x82, n >> 8, n & 0xff]);
+    return Buffer.concat([Buffer.from([tag]), len, body]);
+};
+const seq = (...p) => der(0x30, ...p);
+const set = (...p) => der(0x31, ...p);
+const octets = (b) => der(0x04, b);
+const bool = (v) => der(0x01, Buffer.from([v ? 0xff : 0x00]));
+const int = (n) => {
+    const raw = typeof n === 'number' ? Buffer.from([n]) : n;
+    return der(0x02, raw[0] !== undefined && raw[0] >= 0x80 ? Buffer.concat([Buffer.from([0]), raw]) : raw);
+};
+const oid = (dotted) => {
+    const [a = 0, b = 0, ...rest] = dotted.split('.').map(Number);
+    const bytes = [a * 40 + b];
+    for (const n of rest) {
+        const chunk = [n & 0x7f];
+        for (let v = n >> 7; v > 0; v >>= 7)
+            chunk.unshift((v & 0x7f) | 0x80);
+        bytes.push(...chunk);
+    }
+    return der(0x06, Buffer.from(bytes));
+};
+const utf8 = (s) => der(0x0c, Buffer.from(s, 'utf8'));
+/** RFC 5280 4.1.2.5: UTCTime up to the year 2049, GeneralizedTime from 2050. */
+const utc = (ms) => {
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    const year = d.getUTCFullYear();
+    const rest = `${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}Z`;
+    return year >= 2050
+        ? der(0x18, Buffer.from(`${year}${rest}`))
+        : der(0x17, Buffer.from(`${p(year % 100)}${rest}`));
+};
+const name = (cn) => seq(set(seq(oid('2.5.4.3'), utf8(cn))));
+const extension = (id, critical, value) => seq(oid(id), ...(critical ? [bool(true)] : []), octets(value));
+const ECDSA_SHA256 = '1.2.840.10045.4.3.2';
+const pem = (label, derBytes) => {
+    const lines = derBytes.toString('base64').match(/.{1,64}/g) ?? [];
+    return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----\n`;
+};
+/** The hash of the 65-byte public point, the way RFC 5280 names a key. */
+const keyId = (publicKey) => createHash('sha1')
+    .update(publicKey.export({ type: 'spki', format: 'der' }).subarray(-65))
+    .digest();
+function certificate(input) {
+    const serial = randomBytes(16);
+    // 0x40 bit set, 0x80 clear: positive, and no leading zero byte (DER rejects a padded INTEGER).
+    serial[0] = ((serial[0] ?? 0) & 0x3f) | 0x40;
+    const sigAlg = seq(oid(ECDSA_SHA256));
+    const tbs = seq(der(0xa0, int(2)), int(serial), sigAlg, name(input.issuer), seq(utc(input.notBefore), utc(input.notAfter)), name(input.subject), Buffer.from(input.publicKey.export({ type: 'spki', format: 'der' })), der(0xa3, seq(...input.extensions)));
+    const signature = sign('sha256', tbs, input.signingKey);
+    return pem('CERTIFICATE', seq(tbs, sigAlg, der(0x03, Buffer.concat([Buffer.from([0]), signature]))));
+}
+const subjectKeyId = (publicKey) => extension('2.5.29.14', false, octets(keyId(publicKey)));
+const authorityKeyId = (publicKey) => extension('2.5.29.35', false, seq(der(0x80, keyId(publicKey))));
+function newKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    return {
+        publicKey,
+        privateKey,
+        keyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+    };
+}
+// ---- the CA ------------------------------------------------------------------
+function newCa(now) {
+    const { publicKey, privateKey, keyPem } = newKeyPair();
+    const certPem = certificate({
+        subject: CA_COMMON_NAME,
+        issuer: CA_COMMON_NAME,
+        publicKey,
+        signingKey: privateKey,
+        notBefore: now - 3_600_000,
+        notAfter: now + CA_VALIDITY_MS,
+        extensions: [
+            extension('2.5.29.19', true, seq(bool(true), int(0))),
+            extension('2.5.29.15', true, der(0x03, Buffer.from([0x01, 0x06]))),
+            subjectKeyId(publicKey),
+        ],
+    });
+    return { certPem, keyPem };
+}
+function readPair(held) {
+    if (!held)
+        return null;
+    try {
+        const parsed = JSON.parse(held);
+        if (typeof parsed.cert !== 'string' || typeof parsed.key !== 'string')
+            return null;
+        return { certPem: parsed.cert, keyPem: parsed.key };
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `pair` is a certificate with its own private key. */
+function pairMatches(pair) {
+    try {
+        return new X509Certificate(pair.certPem).checkPrivateKey(createPrivateKey(pair.keyPem));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The platform's CA: the held one, else a new one stored under
+ * {@link SIGNIN_DB_CA_REF}. A held value that cannot be read, or whose
+ * certificate does not match its key, is an error and is never replaced: a
+ * company's database may already trust it. The value read back after a store
+ * is the one used, so two applies at once end with the same CA.
+ */
+export async function ensureSigninDbCa(keys, runtime = {}, 
+/** A company already has a database or certificate made under the CA: a lost CA is then an error, never made again. */
+inUse = false) {
+    const held = await keys.resolve(SIGNIN_DB_CA_REF);
+    if (held) {
+        const pair = readPair(held);
+        if (!pair)
+            throw new Error('the held sign-in database CA cannot be read; it is not replaced');
+        runtime.onSecret?.(pair.keyPem);
+        if (!pairMatches(pair)) {
+            throw new Error('the held sign-in database CA is not a certificate with its own key; it is not replaced');
+        }
+        return pair;
+    }
+    if (inUse) {
+        throw new Error(`the sign-in database CA (${SIGNIN_DB_CA_REF}) is not held, but a company's database already trusts it; a new CA would break every company's sign-in, so none is made. Restore the CA from the keys backup (docs/runbooks/signin-db-tls.md, "A lost CA")`);
+    }
+    if (!keys.put)
+        throw new Error('the host cannot store the sign-in database CA: heldKeys has no put');
+    const created = newCa((runtime.now ?? Date.now)());
+    runtime.onSecret?.(created.keyPem);
+    await keys.put(SIGNIN_DB_CA_REF, JSON.stringify({ cert: created.certPem, key: created.keyPem }));
+    const stored = readPair(await keys.resolve(SIGNIN_DB_CA_REF));
+    if (!stored)
+        throw new Error('the sign-in database CA was stored but cannot be read back');
+    runtime.onSecret?.(stored.keyPem);
+    return stored;
+}
+// ---- the server certificate ----------------------------------------------------
+function newServerCert(ca, host, now) {
+    const { publicKey, keyPem } = newKeyPair();
+    const caCert = new X509Certificate(ca.certPem);
+    const notAfter = now + SERVER_CERT_VALIDITY_MS;
+    const certPem = certificate({
+        subject: host,
+        issuer: CA_COMMON_NAME,
+        publicKey,
+        signingKey: createPrivateKey(ca.keyPem),
+        notBefore: now - 3_600_000,
+        notAfter,
+        extensions: [
+            extension('2.5.29.19', true, seq()),
+            extension('2.5.29.15', true, der(0x03, Buffer.from([0x07, 0x80]))),
+            extension('2.5.29.37', false, seq(oid('1.3.6.1.5.5.7.3.1'))),
+            extension('2.5.29.17', false, seq(der(0x82, Buffer.from(host, 'ascii')))),
+            subjectKeyId(publicKey),
+            authorityKeyId(caCert.publicKey),
+        ],
+    });
+    return { certPem, keyPem, notAfter };
+}
+/** Whether a held server certificate can still be used: right host, our CA, a matching key, and more than the renew window left. */
+function reusable(pair, ca, host, now) {
+    try {
+        const cert = new X509Certificate(pair.certPem);
+        const notAfter = cert.validToDate.getTime();
+        const ok = cert.checkPrivateKey(createPrivateKey(pair.keyPem)) &&
+            cert.checkHost(host) === host &&
+            cert.verify(createPublicKey(ca.certPem)) &&
+            notAfter - now > SIGNIN_DB_CERT_RENEW_WINDOW_MS &&
+            cert.validFromDate.getTime() <= now;
+        return ok ? notAfter : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The server certificate held under `ref` for `host`, issued again when it is
+ * missing, unreadable, for another host, signed by another CA, or has less
+ * than {@link SIGNIN_DB_CERT_RENEW_WINDOW_MS} left. The read-back after a
+ * store is the one used.
+ */
+export async function ensureSigninDbServerCert(keys, ca, ref, host, runtime = {}) {
+    const now = (runtime.now ?? Date.now)();
+    const held = readPair(await keys.resolve(ref));
+    if (held) {
+        runtime.onSecret?.(held.keyPem);
+        const notAfter = reusable(held, ca, host, now);
+        if (notAfter !== null)
+            return { ...held, notAfter, issued: false };
+    }
+    if (!keys.put)
+        throw new Error('the host cannot store the sign-in database certificate: heldKeys has no put');
+    const created = newServerCert(ca, host, now);
+    runtime.onSecret?.(created.keyPem);
+    await keys.put(ref, JSON.stringify({ cert: created.certPem, key: created.keyPem }));
+    const stored = readPair(await keys.resolve(ref));
+    if (!stored)
+        throw new Error('the sign-in database certificate was stored but cannot be read back');
+    runtime.onSecret?.(stored.keyPem);
+    const notAfter = reusable(stored, ca, host, now);
+    if (notAfter === null)
+        throw new Error('the stored sign-in database certificate is not usable');
+    return { ...stored, notAfter, issued: true };
+}
+/**
+ * Whether the recorded server certificate expires within the renew window.
+ * Nothing recorded (a company not on the TLS database) is never due.
+ */
+export function signinDbCertDue(recordedIds, now) {
+    const notAfter = Number(recordedIds[SIGNIN_DB_CERT_NOT_AFTER_SCOPE_KEY]);
+    return (Number.isFinite(notAfter) && notAfter > 0 && notAfter - now < SIGNIN_DB_CERT_RENEW_WINDOW_MS);
+}

package/dist/plan/signin-db.d.ts

@@ -0,0 +1,114 @@
+import type { CoolifyPort } from './executor.js';
+import { SIGNIN_DB_BACKUP_TASK_SCOPE_KEY, type SigninDbBackupPort } from './signin-db-backup.js';
+import { SIGNIN_DB_APP_SCOPE_KEY, SIGNIN_DB_TLS_SCOPE_KEY, type SigninDbKeys, type SigninDbTlsRuntime } from './signin-db-tls.js';
+/**
+ * A company's sign-in database as foundry's own image (#746). Coolify 4.4.2
+ * cannot turn on a database's TLS and mounts files root-owned, so Postgres
+ * would refuse a mounted key. The database is therefore a Dockerfile app: the
+ * pinned `postgres` image, an entrypoint that writes the certificate and key
+ * from env to files owned by `postgres` with mode 0600, and Postgres started
+ * with `ssl=on`. ZITADEL connects with `sslmode=verify-full` and the CA.
+ */
+export { SIGNIN_DB_APP_SCOPE_KEY, SIGNIN_DB_BACKUP_TASK_SCOPE_KEY, SIGNIN_DB_TLS_SCOPE_KEY };
+export declare const SIGNIN_DB_PORT = "5432";
+export declare const SIGNIN_DB_USER = "zitadel";
+export declare const SIGNIN_DB_NAME = "zitadel";
+/** Where the official image keeps its data (`PGDATA`); the volume is mounted here. */
+export declare const SIGNIN_DB_DATA_DIR = "/var/lib/postgresql/data";
+/** Where ZITADEL's container finds the CA (a Coolify file mount: the CA is public, and its image has no shell to write it). */
+export declare const SIGNIN_DB_CA_MOUNT = "/etc/signin-db/ca.crt";
+export declare const SIGNIN_DB_ENV: {
+    readonly user: "POSTGRES_USER";
+    readonly password: "POSTGRES_PASSWORD";
+    readonly database: "POSTGRES_DB";
+    readonly cert: "SIGNIN_DB_TLS_CERT_B64";
+    readonly key: "SIGNIN_DB_TLS_KEY_B64";
+};
+/** How long one Coolify call of these steps may take: the client has no timeout of its own. */
+export declare const SIGNIN_DB_CALL_TIMEOUT_MS = 60000;
+/** `work`, or an error naming `what` after {@link SIGNIN_DB_CALL_TIMEOUT_MS}. The call itself is not cancelled. */
+export declare function boundedCall<T>(work: Promise<T>, what: string): Promise<T>;
+/** The port with every method bounded by {@link boundedCall}. */
+export declare function withCallTimeout<T extends object>(port: T): T;
+/**
+ * The entrypoint, one line each. No line holds a single quote: the Dockerfile
+ * writes each one inside single quotes. The key file is written by `printf` to
+ * a path only root can reach and then handed to `postgres` with mode 0600, the
+ * check Postgres makes before it loads a key.
+ */
+export declare function signinDbStartScript(): string[];
+/**
+ * The inline Dockerfile. `local` connections stay trusted (inside the container only, as in the
+ * official image); every network connection must be TLS with a password, so a client that skips
+ * TLS is refused by the server, not only by the client's own setting.
+ */
+export declare function signinDbDockerfile(): string;
+/** ZITADEL's DSN: the whole chain is checked, host name included. A secret (it holds the password). */
+export declare function signinDbDsn(host: string, password: string): string;
+type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'raw'> & Partial<Pick<CoolifyPort, 'listStorages' | 'createPersistentStorage' | 'createFileStorage'>>;
+export interface SigninDbRuntime extends SigninDbTlsRuntime {
+    sleep?: (ms: number) => Promise<void>;
+    /** How long a new or redeployed database may take to report healthy (default 5 minutes). */
+    signinDbTimeoutMs?: number;
+}
+/**
+ * Polls until Coolify reports the app `running:healthy`. A healthy status read before the app was
+ * ever seen leaving it could be the container being replaced, so it counts only after two polls in
+ * a row. Throws at the deadline; the message names the app and its last status.
+ */
+export declare function waitHealthy(coolify: Pick<CoolifyPort, 'getApplication'>, appId: string, runtime: SigninDbRuntime, label: string, what?: string): Promise<void>;
+/** Makes a Dockerfile app on the first usable server, without a domain: the caller's `create`. */
+export declare function dockerfileAppCreator(coolify: Pick<CoolifyPort, 'listServers' | 'createDockerfileApplication'>, o: {
+    projectUuid: string;
+    environment: {
+        name: string;
+        uuid: string;
+    };
+    name: string;
+    description: string;
+}): (dockerfile: string) => Promise<{
+    uuid: string;
+}>;
+export interface ProvisionSigninDbInput {
+    coolify: Coolify;
+    keys: SigninDbKeys | undefined;
+    runtime: SigninDbRuntime;
+    /** The Coolify name and internal hostname of the database app. */
+    name: string;
+    internalHost: string;
+    /** The volume's name. */
+    volumeName: string;
+    /** The ref the server certificate is held under. */
+    serverCertRef: string;
+    /** The company's slug: the nightly dump's folder in the bucket. */
+    slug: string;
+    /** The host's bucket and key ports. Without them the database is not created. */
+    backup: SigninDbBackupPort | undefined;
+    /** The company's own backup bucket. */
+    backupBucket: string;
+    /** The company's recorded ids when the step started. */
+    recorded: Readonly<Record<string, string>>;
+    label: string;
+    create(dockerfile: string): Promise<{
+        uuid: string;
+    }>;
+    environment: {
+        id: number;
+    };
+    record(key: string, id: string): Promise<void>;
+}
+/**
+ * Brings the TLS database up and returns ZITADEL's DSN: the CA and server certificate (held in
+ * keys), the app with its data volume and no domain, its env (the password minted once and read
+ * back after), and a deploy when the app is new, stopped or its env changed. Returns after the
+ * database reports healthy. A secret (password, key) goes only to the app's env and to
+ * `runtime.onSecret`.
+ */
+export declare function provisionSigninDb(input: ProvisionSigninDbInput): Promise<{
+    appId: string;
+    dsn: string;
+    ca: string;
+    password: string;
+}>;
+/** Mounts the CA on ZITADEL's app, once. The CA is public and never changes, so an existing mount is left alone. */
+export declare function ensureSigninDbCaFile(port: Coolify, zitadelAppId: string, caPem: string, label: string): Promise<void>;