@runuai/host 0.9.148 → 0.9.150

package/lib/secrets-proxy/ca-store.ts

@@ -0,0 +1,200 @@
+/**
+ * The runner's secrets-proxy CAs, kept across restarts (ADR-153 §3 "The CA").
+ *
+ * A task installs the CA bundle each time its container or VM starts and
+ * trusts exactly that until the next start, so the signer may only ever
+ * change to a CA the tasks already trust. Rotation is therefore an overlap:
+ *  - a CA lives five years and signs every leaf until its last day;
+ *  - inside its last 90 days a successor is minted, and every task started
+ *    from then on installs both (`trusted`);
+ *  - on its last day it retires and the successor signs.
+ * A task last started before its successor existed — one running for more
+ * than 89 days across the switch — trusts only the retiring CA and must be
+ * restarted. That is logged loudly when the successor is minted and again at
+ * the switch; the runner also re-installs the bundle into running tasks when
+ * it changes, which covers every process started after that.
+ *
+ * The certificates are stored in the clear (every task gets a copy anyway);
+ * the private keys are sealed with host-master.key and never leave this
+ * process in any other form.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { writeDurableFileAtomic } from "../env-file";
+import { createCertificateAuthority, loadCertificateAuthority, type CertificateAuthority } from "./ca";
+
+const STORE_VERSION = 1;
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const CA_VALIDITY_DAYS = 5 * 365;
+/** Inside its last 90 days a CA gets a successor, installed alongside it. */
+export const CA_SUCCESSOR_WITHIN_MS = 90 * DAY_MS;
+/** On its last day a CA stops signing and its successor takes over. */
+export const CA_RETIRE_WITHIN_MS = DAY_MS;
+/** Signer and successor: the windows above never leave more alive at once. */
+const MAX_AUTHORITIES = 2;
+
+export interface SealedText {
+  ct: Buffer;
+  nonce: Buffer;
+}
+
+export interface CaStoreDeps {
+  /** Directory for `ca.json` (created 0700). */
+  dir: string;
+  seal(plaintext: string): SealedText;
+  open(ct: Buffer, nonce: Buffer): string;
+  now?(): number;
+  log?: Pick<Console, "warn">;
+}
+
+export interface CertificateAuthorities {
+  /** Signs every leaf: the oldest CA not yet retired. */
+  readonly signer: CertificateAuthority;
+  /** What a starting task installs: the signer and, inside its last 90 days,
+   *  its successor. */
+  readonly trusted: readonly CertificateAuthority[];
+  /** When this set next changes: a successor is due, or the signer retires. */
+  readonly reviewAt: number;
+}
+
+interface StoredAuthority {
+  commonName: string;
+  certificatePem: string;
+  key: { ct: string; nonce: string };
+}
+
+interface StoredCa {
+  v: number;
+  authorities: StoredAuthority[];
+}
+
+function isStoredAuthority(value: unknown): value is StoredAuthority {
+  if (value === null || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  const key = entry.key as Record<string, unknown> | undefined;
+  return (
+    typeof entry.commonName === "string" &&
+    typeof entry.certificatePem === "string" &&
+    key !== undefined &&
+    key !== null &&
+    typeof key.ct === "string" &&
+    typeof key.nonce === "string"
+  );
+}
+
+function isStoredCa(value: unknown): value is StoredCa {
+  if (value === null || typeof value !== "object") return false;
+  const stored = value as Record<string, unknown>;
+  return (
+    stored.v === STORE_VERSION &&
+    Array.isArray(stored.authorities) &&
+    stored.authorities.length >= 1 &&
+    stored.authorities.length <= MAX_AUTHORITIES &&
+    stored.authorities.every(isStoredAuthority)
+  );
+}
+
+const dateOf = (epochMs: number): string => new Date(epochMs).toISOString().slice(0, 10);
+
+/**
+ * Returns the runner's CAs, minting the first one, a successor or (after a
+ * runner was down through a whole overlap) a replacement as the dates call
+ * for, and persisting any change. Throws when a stored CA exists but cannot
+ * be opened or fails validation: that is a broken store, not a reason to
+ * mint a new CA behind every running task's back.
+ */
+export function loadOrCreateCertificateAuthorities(deps: CaStoreDeps): CertificateAuthorities {
+  const now = deps.now ?? Date.now;
+  const log = deps.log ?? console;
+  mkdirSync(deps.dir, { recursive: true, mode: 0o700 });
+  const path = join(deps.dir, "ca.json");
+  const at = now();
+
+  let stored: { authority: CertificateAuthority; record: StoredAuthority }[] = [];
+  if (existsSync(path)) {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!isStoredCa(parsed)) throw new Error("the secrets-proxy CA store is not in a format this runner reads");
+    stored = parsed.authorities.map((record) => ({
+      authority: loadCertificateAuthority({
+        certificatePem: record.certificatePem,
+        privateKeyPem: deps.open(Buffer.from(record.key.ct, "base64"), Buffer.from(record.key.nonce, "base64")),
+        commonName: record.commonName,
+      }),
+      record,
+    }));
+  }
+
+  const mint = (): { authority: CertificateAuthority; record: StoredAuthority } => {
+    // Dated, so the trust store tells a signer and its successor apart.
+    const commonName = `Uai secrets proxy ${dateOf(at)}`;
+    let privateKeyPem = "";
+    const authority = createCertificateAuthority({
+      now: at,
+      commonName,
+      validityDays: CA_VALIDITY_DAYS,
+      onPrivateKey: (privateKey) => {
+        privateKeyPem = String(privateKey.export({ type: "pkcs8", format: "pem" }));
+      },
+    });
+    const sealed = deps.seal(privateKeyPem);
+    return {
+      authority,
+      record: {
+        commonName,
+        certificatePem: authority.certificatePem,
+        key: { ct: sealed.ct.toString("base64"), nonce: sealed.nonce.toString("base64") },
+      },
+    };
+  };
+
+  const live = stored
+    .filter(({ authority }) => at < authority.notAfter - CA_RETIRE_WITHIN_MS)
+    .sort((a, b) => a.authority.notAfter - b.authority.notAfter);
+  let changed = live.length !== stored.length;
+  let newest = live[live.length - 1];
+  if (newest === undefined) {
+    if (stored.length > 0) {
+      log.warn(
+        "[secrets-proxy] the proxy CA reached its last day with no successor (the runner was not running through " +
+          "the overlap); a new CA was created, and every task started before now must be restarted to trust it",
+      );
+    }
+    newest = mint();
+    live.push(newest);
+    changed = true;
+  } else if (changed) {
+    // At most two are stored, so a retirement leaves the successor alone.
+    log.warn(
+      `[secrets-proxy] the proxy CA retired and its successor now signs; tasks last started before ` +
+        `${dateOf(newest.authority.notBefore)} trust only the retired CA and must be restarted`,
+    );
+  }
+  if (at >= newest.authority.notAfter - CA_SUCCESSOR_WITHIN_MS) {
+    const ending = newest.authority.notAfter;
+    live.push(mint());
+    changed = true;
+    log.warn(
+      `[secrets-proxy] the proxy CA expires on ${dateOf(ending)}; a successor was created and tasks started ` +
+        `from now trust both. It takes over on ${dateOf(ending - CA_RETIRE_WITHIN_MS)}: tasks started before ` +
+        "now must be restarted by then",
+    );
+  }
+  if (changed) {
+    const next: StoredCa = { v: STORE_VERSION, authorities: live.map(({ record }) => record) };
+    // Durable: a CA lost to a power cut after tasks installed it would leave
+    // every one of them distrusting the next.
+    writeDurableFileAtomic(path, `${JSON.stringify(next)}\n`);
+  }
+
+  const trusted = live.map(({ authority }) => authority);
+  const signer = trusted[0];
+  const last = trusted[trusted.length - 1];
+  if (signer === undefined || last === undefined) throw new Error("no live secrets-proxy CA");
+  return Object.freeze({
+    signer,
+    trusted: Object.freeze(trusted),
+    reviewAt: Math.min(signer.notAfter - CA_RETIRE_WITHIN_MS, last.notAfter - CA_SUCCESSOR_WITHIN_MS),
+  });
+}

package/lib/secrets-proxy/ca.ts

@@ -0,0 +1,470 @@
+/**
+ * The secrets proxy's certificate authority (ADR-153 §3 "The CA").
+ *
+ * One ECDSA P-256 CA per runner signs short-lived per-domain leaves that the
+ * proxy presents to a task on the domains it declares. Tasks trust this CA;
+ * the proxy's own upstream verification uses public roots, which can never
+ * include it.
+ *
+ * Two rules keep a bug here from turning into a leak:
+ *  - The CA private key is a KeyObject closed over by a signing callback. The
+ *    certificate builder hands it finished TBS bytes and embeds the signature
+ *    it gets back; it never receives key material.
+ *  - Every certificate is parsed back with node:crypto's X509Certificate and
+ *    checked straight after minting (CA-ness, SAN, EKU, issuer, signature,
+ *    key match, validity, serial). Any failure throws, and callers treat a
+ *    throw as "withhold": no handshake is ever answered with a certificate we
+ *    could not prove correct.
+ */
+
+import {
+  X509Certificate,
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign,
+  type KeyObject,
+} from "node:crypto";
+
+import * as der from "./der";
+import { canonicalHostname } from "./hostname";
+
+const OID = {
+  ecdsaWithSha256: "1.2.840.10045.4.3.2",
+  commonName: "2.5.4.3",
+  subjectKeyIdentifier: "2.5.29.14",
+  keyUsage: "2.5.29.15",
+  subjectAltName: "2.5.29.17",
+  basicConstraints: "2.5.29.19",
+  authorityKeyIdentifier: "2.5.29.35",
+  extKeyUsage: "2.5.29.37",
+  serverAuth: "1.3.6.1.5.5.7.3.1",
+} as const;
+
+/** KeyUsage named bits (RFC 5280 §4.2.1.3). */
+const KEY_USAGE = { digitalSignature: 0, keyCertSign: 5, cRLSign: 6 } as const;
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+/** Certificates start five minutes early so a task whose clock runs a little
+ *  behind the runner's (a VM after resume) still accepts a fresh leaf. */
+const BACKDATE_MS = 5 * MINUTE_MS;
+const MAX_CA_VALIDITY_DAYS = 3_650;
+/** The ADR's leaves live 24 h; this is only the ceiling a caller may ask for. */
+const MAX_LEAF_VALIDITY_HOURS = 7 * 24;
+const DEFAULT_LEAF_VALIDITY_HOURS = 24;
+/** Re-mint an hour before expiry, so a leaf is never served in its last
+ *  hour and a long-lived connection never straddles its notAfter — or a
+ *  quarter of the leaf's life when that is shorter (a short validity, or a
+ *  leaf capped by a CA near its own end), so a cached leaf always has a
+ *  usable window rather than being re-minted on every handshake. */
+const LEAF_RENEW_BEFORE_MS = HOUR_MS;
+const DEFAULT_LEAF_CACHE_ENTRIES = 256;
+
+/** Signs a finished TBSCertificate; the only door to a CA key. */
+export type SignTbs = (tbs: Buffer) => Buffer;
+
+export interface CertificateAuthority {
+  readonly certificatePem: string;
+  readonly certificate: X509Certificate;
+  /** The encoded subject Name, reused byte for byte as every leaf's issuer so
+   *  name matching never depends on a re-encoding. */
+  readonly subjectName: Buffer;
+  readonly keyIdentifier: Buffer;
+  readonly notBefore: number;
+  readonly notAfter: number;
+  readonly sign: SignTbs;
+}
+
+export interface LeafCertificate {
+  readonly hostname: string;
+  readonly certificatePem: string;
+  /** PKCS#8 PEM, because tls.createSecureContext does not accept a KeyObject. */
+  readonly privateKeyPem: string;
+  readonly certificate: X509Certificate;
+  readonly notBefore: number;
+  readonly notAfter: number;
+}
+
+interface CertificateFields {
+  serial: Buffer;
+  issuer: Buffer;
+  subject: Buffer;
+  notBefore: number;
+  notAfter: number;
+  publicKey: KeyObject;
+  extensions: readonly Buffer[];
+}
+
+function floorToSecond(ms: number): number {
+  return Math.floor(ms / 1_000) * 1_000;
+}
+
+/** 16 random octets with the top bit cleared: positive without a sign-guard
+ *  octet, under RFC 5280's 20-octet cap, and never zero. */
+function randomSerial(): Buffer {
+  for (;;) {
+    const serial = randomBytes(16);
+    serial[0] = (serial[0] ?? 0) & 0x7f;
+    if (serial.some((octet) => octet !== 0)) return serial;
+  }
+}
+
+/** X.520's ub-common-name: strict X.509 stacks refuse a longer CN. */
+const MAX_COMMON_NAME = 64;
+
+function distinguishedName(commonName: string): Buffer {
+  return der.sequence(
+    der.set(der.sequence(der.objectIdentifier(OID.commonName), der.utf8String(commonName))),
+  );
+}
+
+/** A leaf's subject: CN = hostname when it fits X.520's bound, otherwise an
+ *  empty Name — RFC 5280 §4.2.1.6 then requires a critical SAN, which is
+ *  where every client looks for the name anyway. */
+function leafSubject(hostname: string): { subject: Buffer; sanCritical: boolean } {
+  return hostname.length <= MAX_COMMON_NAME
+    ? { subject: distinguishedName(hostname), sanCritical: false }
+    : { subject: der.sequence(), sanCritical: true };
+}
+
+/** RFC 7093 §2 method 1: the leftmost 160 bits of SHA-256 over the
+ *  subjectPublicKey bits (the uncompressed EC point). */
+function subjectKeyIdentifier(publicKey: KeyObject): Buffer {
+  const jwk = publicKey.export({ format: "jwk" });
+  if (typeof jwk.x !== "string" || typeof jwk.y !== "string") {
+    throw new Error("expected an EC public key");
+  }
+  const point = Buffer.concat([
+    Buffer.from([0x04]),
+    Buffer.from(jwk.x, "base64url"),
+    Buffer.from(jwk.y, "base64url"),
+  ]);
+  return createHash("sha256").update(point).digest().subarray(0, 20);
+}
+
+/** DER omits `critical` when it is the DEFAULT FALSE. */
+function extension(oid: string, critical: boolean, value: Buffer): Buffer {
+  return der.sequence(
+    der.objectIdentifier(oid),
+    ...(critical ? [der.boolean(true)] : []),
+    der.octetString(value),
+  );
+}
+
+function buildCertificate(fields: CertificateFields, signTbs: SignTbs): Buffer {
+  // ecdsa-with-SHA256 takes no parameters, not even NULL (RFC 5758 §3.2).
+  const algorithm = der.sequence(der.objectIdentifier(OID.ecdsaWithSha256));
+  const tbs = der.sequence(
+    der.explicit(0, der.integer(2)), // v3
+    der.integer(fields.serial),
+    algorithm,
+    fields.issuer,
+    der.sequence(der.time(new Date(fields.notBefore)), der.time(new Date(fields.notAfter))),
+    fields.subject,
+    fields.publicKey.export({ type: "spki", format: "der" }),
+    der.explicit(3, der.sequence(...fields.extensions)),
+  );
+  return der.sequence(tbs, algorithm, der.bitString(signTbs(tbs)));
+}
+
+function validityOf(certificate: X509Certificate): { notBefore: number; notAfter: number } {
+  // validFromDate/validToDate only exist from Node 22.10; the string forms
+  // name the same instants on every supported runtime.
+  const from = certificate.validFromDate ?? new Date(certificate.validFrom);
+  const to = certificate.validToDate ?? new Date(certificate.validTo);
+  return { notBefore: from.getTime(), notAfter: to.getTime() };
+}
+
+function checkValidity(
+  failures: string[],
+  certificate: X509Certificate,
+  expected: { notBefore: number; notAfter: number },
+  maxSpanMs: number,
+): void {
+  const { notBefore, notAfter } = validityOf(certificate);
+  if (notBefore !== expected.notBefore || notAfter !== expected.notAfter) {
+    failures.push("validity is not the requested window");
+  }
+  if (!(notAfter > notBefore) || notAfter - notBefore > maxSpanMs) {
+    failures.push("validity is not bounded");
+  }
+}
+
+function checkSerial(failures: string[], certificate: X509Certificate): void {
+  const serial = certificate.serialNumber;
+  if (!/^[0-9A-Fa-f]+$/.test(serial) || BigInt(`0x${serial}`) <= 0n) {
+    failures.push("serial is not a positive integer");
+  }
+}
+
+function extendedKeyUsage(certificate: X509Certificate): readonly string[] {
+  // Node names the EKU list `keyUsage` (newer releases add `extKeyUsage`);
+  // it is undefined when the extension is absent.
+  const renamed = (certificate as { extKeyUsage?: string[] }).extKeyUsage;
+  return renamed ?? certificate.keyUsage ?? [];
+}
+
+function fail(what: string, failures: readonly string[]): void {
+  if (failures.length > 0) {
+    throw new Error(`${what} failed self-validation: ${failures.join("; ")}`);
+  }
+}
+
+/**
+ * Throws unless `certificate` is a self-signed CA certificate for
+ * `privateKey` over exactly the expected window. Exported for tests.
+ */
+export function validateCertificateAuthority(
+  certificate: X509Certificate,
+  expected: { privateKey: KeyObject; notBefore: number; notAfter: number },
+): void {
+  const failures: string[] = [];
+  // `ca` is X509_check_ca() == 1: basicConstraints CA:TRUE, and a keyUsage
+  // that (when present) allows keyCertSign.
+  if (certificate.ca !== true) failures.push("not a CA certificate");
+  // X509_check_issued: names and key ids chain, and the issuer's keyUsage
+  // allows certificate signing — here, of itself.
+  if (!certificate.checkIssued(certificate)) failures.push("not self-issued");
+  if (!certificate.verify(certificate.publicKey)) failures.push("self-signature does not verify");
+  if (!certificate.checkPrivateKey(expected.privateKey)) failures.push("private key does not match");
+  checkValidity(failures, certificate, expected, MAX_CA_VALIDITY_DAYS * DAY_MS + BACKDATE_MS);
+  checkSerial(failures, certificate);
+  fail("certificate authority", failures);
+}
+
+/**
+ * Throws unless `certificate` is a server leaf for exactly `hostname`, issued
+ * and signed by `authority`, matching `privateKey`, over exactly the expected
+ * window. Exported for tests.
+ */
+export function validateLeafCertificate(
+  certificate: X509Certificate,
+  expected: {
+    authority: CertificateAuthority;
+    hostname: string;
+    privateKey: KeyObject;
+    notBefore: number;
+    notAfter: number;
+  },
+): void {
+  const failures: string[] = [];
+  if (certificate.ca !== false) failures.push("leaf is a CA certificate");
+  if (certificate.subjectAltName !== `DNS:${expected.hostname}`) {
+    failures.push("subjectAltName is not exactly the hostname");
+  }
+  if (!extendedKeyUsage(certificate).includes(OID.serverAuth)) {
+    failures.push("extKeyUsage lacks serverAuth");
+  }
+  if (!certificate.checkIssued(expected.authority.certificate)) {
+    failures.push("not issued by the CA");
+  }
+  if (!certificate.verify(expected.authority.certificate.publicKey)) {
+    failures.push("signature does not verify against the CA");
+  }
+  if (!certificate.checkPrivateKey(expected.privateKey)) failures.push("private key does not match");
+  const matched = certificate.checkHost(expected.hostname, {
+    subject: "never",
+    wildcards: false,
+    partialWildcards: false,
+  });
+  if (matched !== expected.hostname) failures.push("hostname verification fails");
+  checkValidity(failures, certificate, expected, MAX_LEAF_VALIDITY_HOURS * HOUR_MS + BACKDATE_MS);
+  checkSerial(failures, certificate);
+  fail("leaf certificate", failures);
+}
+
+export function createCertificateAuthority(options: {
+  now: number;
+  commonName: string;
+  validityDays: number;
+  /** Receives the new key once, for a store to seal; nothing else sees it. */
+  onPrivateKey?: (privateKey: KeyObject) => unknown;
+}): CertificateAuthority {
+  const { now, commonName, validityDays } = options;
+  if (!Number.isFinite(now)) throw new RangeError("now must be a finite epoch-ms value");
+  // X.520 caps commonName at 64 characters.
+  if (typeof commonName !== "string" || commonName.length < 1 || commonName.length > 64) {
+    throw new RangeError("CA common name must be 1..64 characters");
+  }
+  if (!Number.isInteger(validityDays) || validityDays < 1 || validityDays > MAX_CA_VALIDITY_DAYS) {
+    throw new RangeError(`CA validity must be 1..${MAX_CA_VALIDITY_DAYS} days`);
+  }
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const signTbs: SignTbs = (tbs) => sign("sha256", tbs, { key: privateKey, dsaEncoding: "der" });
+  const notBefore = floorToSecond(now - BACKDATE_MS);
+  const notAfter = floorToSecond(now + validityDays * DAY_MS);
+  const subjectName = distinguishedName(commonName);
+  const keyIdentifier = subjectKeyIdentifier(publicKey);
+  const certificate = new X509Certificate(
+    buildCertificate(
+      {
+        serial: randomSerial(),
+        issuer: subjectName,
+        subject: subjectName,
+        notBefore,
+        notAfter,
+        publicKey,
+        extensions: [
+          extension(OID.basicConstraints, true, der.sequence(der.boolean(true), der.integer(0))),
+          extension(
+            OID.keyUsage,
+            true,
+            der.namedBitString([KEY_USAGE.keyCertSign, KEY_USAGE.cRLSign]),
+          ),
+          extension(OID.subjectKeyIdentifier, false, der.octetString(keyIdentifier)),
+        ],
+      },
+      signTbs,
+    ),
+  );
+  validateCertificateAuthority(certificate, { privateKey, notBefore, notAfter });
+  options.onPrivateKey?.(privateKey);
+  return Object.freeze({
+    certificatePem: certificate.toString(),
+    certificate,
+    subjectName,
+    keyIdentifier,
+    notBefore,
+    notAfter,
+    sign: signTbs,
+  });
+}
+
+/**
+ * Rebuilds a CA handle from what a store kept: the certificate, its PKCS#8
+ * private key and the common name it was created with. Everything is
+ * re-validated exactly as at creation (CA-ness, self-signature, key match,
+ * bounded validity, serial), and the subject must be the one this code
+ * encodes for that name, because every leaf embeds it byte for byte as its
+ * issuer. Throws (withhold) on any mismatch.
+ */
+export function loadCertificateAuthority(stored: {
+  certificatePem: string;
+  privateKeyPem: string;
+  commonName: string;
+}): CertificateAuthority {
+  const certificate = new X509Certificate(stored.certificatePem);
+  const privateKey = createPrivateKey(stored.privateKeyPem);
+  const { notBefore, notAfter } = validityOf(certificate);
+  validateCertificateAuthority(certificate, { privateKey, notBefore, notAfter });
+  if (certificate.subject !== `CN=${stored.commonName}`) {
+    throw new Error("stored certificate authority does not carry its recorded name");
+  }
+  const signTbs: SignTbs = (tbs) => sign("sha256", tbs, { key: privateKey, dsaEncoding: "der" });
+  return Object.freeze({
+    certificatePem: certificate.toString(),
+    certificate,
+    subjectName: distinguishedName(stored.commonName),
+    keyIdentifier: subjectKeyIdentifier(certificate.publicKey),
+    notBefore,
+    notAfter,
+    sign: signTbs,
+  });
+}
+
+export function mintLeafCertificate(options: {
+  ca: CertificateAuthority;
+  hostname: string;
+  now: number;
+  validityHours?: number;
+}): LeafCertificate {
+  const { ca, hostname, now, validityHours = DEFAULT_LEAF_VALIDITY_HOURS } = options;
+  if (canonicalHostname(hostname) !== hostname) {
+    throw new Error("leaf hostname must be a canonical DNS name");
+  }
+  if (!Number.isFinite(now)) throw new RangeError("now must be a finite epoch-ms value");
+  if (!(validityHours > 0) || validityHours > MAX_LEAF_VALIDITY_HOURS) {
+    throw new RangeError(`leaf validity must be within (0, ${MAX_LEAF_VALIDITY_HOURS}] hours`);
+  }
+  const notBefore = floorToSecond(now - BACKDATE_MS);
+  // Past the CA's notAfter the chain fails anyway; a leaf never claims more.
+  const notAfter = Math.min(floorToSecond(now + validityHours * HOUR_MS), ca.notAfter);
+  if (now < ca.notBefore || notAfter <= now) {
+    throw new Error("certificate authority is outside its validity window");
+  }
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const { subject, sanCritical } = leafSubject(hostname);
+  const certificate = new X509Certificate(
+    buildCertificate(
+      {
+        serial: randomSerial(),
+        issuer: ca.subjectName,
+        subject,
+        notBefore,
+        notAfter,
+        publicKey,
+        extensions: [
+          // CA:FALSE is the DEFAULT, so DER encodes it as an empty SEQUENCE.
+          extension(OID.basicConstraints, true, der.sequence()),
+          extension(OID.keyUsage, true, der.namedBitString([KEY_USAGE.digitalSignature])),
+          extension(OID.extKeyUsage, false, der.sequence(der.objectIdentifier(OID.serverAuth))),
+          extension(
+            OID.subjectAltName,
+            sanCritical,
+            der.sequence(der.implicit(2, der.ia5String(hostname))),
+          ),
+          extension(OID.subjectKeyIdentifier, false, der.octetString(subjectKeyIdentifier(publicKey))),
+          extension(
+            OID.authorityKeyIdentifier,
+            false,
+            der.sequence(der.implicit(0, der.octetString(ca.keyIdentifier))),
+          ),
+        ],
+      },
+      ca.sign,
+    ),
+  );
+  validateLeafCertificate(certificate, { authority: ca, hostname, privateKey, notBefore, notAfter });
+  return Object.freeze({
+    hostname,
+    certificatePem: certificate.toString(),
+    privateKeyPem: String(privateKey.export({ type: "pkcs8", format: "pem" })),
+    certificate,
+    notBefore,
+    notAfter,
+  });
+}
+
+/** The CA handle the proxy engine takes: leaves minted on demand, cached per
+ *  hostname, and re-minted an hour before they expire. */
+export interface LeafCertificateCache {
+  readonly authority: CertificateAuthority;
+  /** A valid leaf for a canonical hostname. Throws (withhold) when minting or
+   *  self-validation fails. */
+  leafFor(hostname: string): LeafCertificate;
+}
+
+export function createLeafCertificateCache(options: {
+  ca: CertificateAuthority;
+  now?: () => number;
+  validityHours?: number;
+  maxEntries?: number;
+}): LeafCertificateCache {
+  const { ca, now = Date.now, validityHours = DEFAULT_LEAF_VALIDITY_HOURS } = options;
+  const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_LEAF_CACHE_ENTRIES));
+  const leaves = new Map<string, LeafCertificate>();
+  return {
+    authority: ca,
+    leafFor(hostname: string): LeafCertificate {
+      const at = now();
+      const cached = leaves.get(hostname);
+      if (cached !== undefined) {
+        const renewBefore = Math.min(LEAF_RENEW_BEFORE_MS, (cached.notAfter - cached.notBefore) / 4);
+        if (at >= cached.notBefore && at < cached.notAfter - renewBefore) return cached;
+      }
+      leaves.delete(hostname);
+      const leaf = mintLeafCertificate({ ca, hostname, now: at, validityHours });
+      // Only declared domains reach here (the SNI check runs first), so the
+      // cap is a backstop against a pathological declaration, not an LRU.
+      if (leaves.size >= maxEntries) {
+        const oldest = leaves.keys().next();
+        if (oldest.done !== true) leaves.delete(oldest.value);
+      }
+      leaves.set(hostname, leaf);
+      return leaf;
+    },
+  };
+}