@moondeck/station 0.0.0-stage → 1.0.0

package/lib/safe-http.ts

@@ -0,0 +1,364 @@
+/**
+ * ADR-154 §11: the one SSRF rule for every request to an MCP server, or to an
+ * endpoint discovered from it, whoever sends it — the sign-in box (probe,
+ * discovery, registration, code exchange), the broker (refresh) and the
+ * runner's gateway (every call a task makes).
+ *
+ * - The URL is `https`, with no userinfo.
+ * - The name is resolved immediately before the request is sent, and the
+ *   request is refused if any A or AAAA answer is not a global unicast
+ *   address (`isPublicAddress`): one private answer rejects the whole
+ *   answer, so a rebinding record cannot win by mixing one in.
+ * - It connects to the vetted address while keeping the hostname for SNI and
+ *   certificate checks, so nothing can re-resolve the name between the check
+ *   and the connect.
+ * - It follows no redirect: a 3xx is the answer, for the caller to refuse.
+ * - It bounds the connect and header time, the request body, an idle gap in
+ *   the response and the number of connections in flight — never a stream's
+ *   total life or bytes, since MCP streams over SSE and streamable HTTP. A
+ *   caller that buffers a body (discovery, token responses) bounds its size
+ *   and, through an abort signal, its total time.
+ */
+
+import type { LookupAddress } from "node:dns";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpsRequest, type RequestOptions } from "node:https";
+import type { IncomingMessage } from "node:http";
+import { isIP, type LookupFunction } from "node:net";
+
+import { isPublicAddress } from "./secrets-proxy/address";
+
+export type SafeHttpRefusalReason =
+  | "url"
+  | "resolve_failed"
+  | "non_public_address"
+  | "too_many_connections"
+  | "request_too_large"
+  | "response_too_large"
+  | "timeout"
+  | "connection_failed";
+
+/** A request the rule refused, or one that failed before an answer. */
+export class SafeHttpRefusal extends Error {
+  constructor(
+    readonly reason: SafeHttpRefusalReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "SafeHttpRefusal";
+  }
+}
+
+export interface SafeHttpLimits {
+  /** Resolve, TCP and TLS, together. */
+  connectMs: number;
+  /** From the request sent to the response's headers. */
+  headersMs: number;
+  /** The longest gap between two pieces of the response body. */
+  idleMs: number;
+  maxRequestBodyBytes: number;
+}
+
+export const DEFAULT_SAFE_HTTP_LIMITS: SafeHttpLimits = {
+  connectMs: 10_000,
+  headersMs: 60_000,
+  idleMs: 5 * 60_000,
+  maxRequestBodyBytes: 4 * 1024 * 1024,
+};
+
+/** The most requests one process has in flight under this rule. */
+export const MAX_SAFE_HTTP_CONNECTIONS = 64;
+
+export interface SafeHttpDeps {
+  /** Every address the name resolves to. */
+  resolveHost?: (hostname: string) => Promise<string[]>;
+  /** Tests only: which addresses count as public. */
+  isPublic?: (address: string) => boolean;
+  /** Tests only: extra trusted roots, PEM. */
+  ca?: string[];
+}
+
+export interface SafeHttpRequest {
+  url: string;
+  method?: "GET" | "POST" | "DELETE";
+  headers?: Record<string, string>;
+  body?: string | Uint8Array;
+  /** Ends the exchange, whatever phase it is in (a buffered call's total
+   *  deadline). A stream's own reader may leave it unset. */
+  signal?: AbortSignal;
+}
+
+/** The response as it arrives: headers now, the body as a stream. */
+export interface SafeHttpResponse {
+  status: number;
+  headers: IncomingMessage["headers"];
+  body: IncomingMessage;
+}
+
+let inFlight = 0;
+
+async function defaultResolve(hostname: string): Promise<string[]> {
+  const answers: LookupAddress[] = await dnsLookup(hostname, { all: true, verbatim: true });
+  return answers.map((answer) => answer.address);
+}
+
+/** The URL, if the rule accepts its shape: https, a host, no userinfo. */
+export function parseSafeUrl(raw: string): URL | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.hostname === "") {
+    return null;
+  }
+  return url;
+}
+
+function tooLong(): SafeHttpRefusal {
+  return new SafeHttpRefusal("timeout", "the exchange took too long");
+}
+
+async function vet(
+  hostname: string,
+  limits: SafeHttpLimits,
+  deps: SafeHttpDeps,
+  signal?: AbortSignal,
+): Promise<{ address: string; family: 4 | 6 }> {
+  const isPublic = deps.isPublic ?? isPublicAddress;
+  // A bracketed IPv6 literal arrives with its brackets.
+  const bare = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  if (signal?.aborted) throw tooLong();
+  let answers: string[];
+  if (isIP(bare) !== 0) {
+    answers = [bare];
+  } else {
+    let timer: NodeJS.Timeout | undefined;
+    let onAbort: (() => void) | undefined;
+    try {
+      answers = await Promise.race([
+        (deps.resolveHost ?? defaultResolve)(bare),
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(() => reject(new Error("resolve timed out")), limits.connectMs);
+          timer.unref();
+        }),
+        // The caller's deadline ends the lookup too, not only what follows.
+        new Promise<never>((_resolve, reject) => {
+          if (!signal) return;
+          onAbort = () => reject(tooLong());
+          signal.addEventListener("abort", onAbort, { once: true });
+          if (signal.aborted) onAbort();
+        }),
+      ]);
+    } catch {
+      if (signal?.aborted) throw tooLong();
+      throw new SafeHttpRefusal("resolve_failed", `could not resolve ${bare}`);
+    } finally {
+      clearTimeout(timer);
+      if (onAbort) signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  if (signal?.aborted) throw tooLong();
+  if (!Array.isArray(answers) || answers.length === 0) {
+    throw new SafeHttpRefusal("resolve_failed", `${bare} has no address`);
+  }
+  for (const address of answers) {
+    if (typeof address !== "string" || !isPublic(address)) {
+      throw new SafeHttpRefusal("non_public_address", `${bare} resolves to an address that is not public`);
+    }
+  }
+  const address = answers[0]!;
+  return { address, family: isIP(address) === 6 ? 6 : 4 };
+}
+
+/**
+ * The rule for a URL nothing here will fetch (an authorization page handed
+ * to the browser): https, no userinfo, and every address its name resolves
+ * to public. Throws `SafeHttpRefusal` otherwise.
+ */
+export async function vetPublicUrl(
+  raw: string,
+  limits: SafeHttpLimits = DEFAULT_SAFE_HTTP_LIMITS,
+  deps: SafeHttpDeps = {},
+  signal?: AbortSignal,
+): Promise<void> {
+  const url = parseSafeUrl(raw);
+  if (!url) throw new SafeHttpRefusal("url", "only https URLs without userinfo are allowed");
+  await vet(url.hostname, limits, deps, signal);
+}
+
+/**
+ * Send one request under the rule. Resolves with the response once its
+ * headers arrive; the body streams, with an idle bound but no total one.
+ * Throws `SafeHttpRefusal` for anything the rule refuses or that fails first.
+ */
+export async function safeRequest(
+  request: SafeHttpRequest,
+  limits: SafeHttpLimits = DEFAULT_SAFE_HTTP_LIMITS,
+  deps: SafeHttpDeps = {},
+): Promise<SafeHttpResponse> {
+  const url = parseSafeUrl(request.url);
+  if (!url) throw new SafeHttpRefusal("url", "only https URLs without userinfo are allowed");
+  if (request.signal?.aborted) throw tooLong();
+  const body =
+    request.body === undefined
+      ? undefined
+      : typeof request.body === "string"
+        ? Buffer.from(request.body, "utf8")
+        : Buffer.from(request.body);
+  if (body && body.byteLength > limits.maxRequestBodyBytes) {
+    throw new SafeHttpRefusal("request_too_large", "the request body is too large");
+  }
+  if (inFlight >= MAX_SAFE_HTTP_CONNECTIONS) {
+    throw new SafeHttpRefusal("too_many_connections", "too many requests in flight");
+  }
+  inFlight += 1;
+  let released = false;
+  const release = (): void => {
+    if (released) return;
+    released = true;
+    inFlight -= 1;
+  };
+  try {
+    const target = await vet(url.hostname, limits, deps, request.signal);
+    const lookup: LookupFunction = (_hostname, options, callback) => {
+      if (options.all === true) callback(null, [{ address: target.address, family: target.family }]);
+      else callback(null, target.address, target.family);
+    };
+    const servername = isIP(url.hostname.replace(/^\[|\]$/g, "")) === 0 ? url.hostname : undefined;
+    const options: RequestOptions = {
+      host: url.hostname,
+      port: url.port === "" ? 443 : Number(url.port),
+      path: `${url.pathname}${url.search}`,
+      method: request.method ?? (body ? "POST" : "GET"),
+      headers: {
+        ...request.headers,
+        ...(body ? { "content-length": String(body.byteLength) } : {}),
+      },
+      lookup,
+      ...(servername ? { servername } : {}),
+      // A connection per request: nothing pooled, nothing re-resolved.
+      agent: false,
+      rejectUnauthorized: true,
+      ...(deps.ca ? { ca: deps.ca } : {}),
+    };
+    return await new Promise<SafeHttpResponse>((resolve, reject) => {
+      const req = httpsRequest(options);
+      let settled = false;
+      const onAbort = (): void => fail(tooLong());
+      const fail = (error: SafeHttpRefusal): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(connectTimer);
+        request.signal?.removeEventListener("abort", onAbort);
+        req.destroy();
+        release();
+        reject(error);
+      };
+      const connectTimer = setTimeout(
+        () => fail(new SafeHttpRefusal("timeout", "the connection took too long")),
+        limits.connectMs,
+      );
+      connectTimer.unref();
+      request.signal?.addEventListener("abort", onAbort, { once: true });
+      let headersTimer: NodeJS.Timeout | undefined;
+      req.once("socket", (socket) => {
+        socket.once("secureConnect", () => {
+          clearTimeout(connectTimer);
+          headersTimer = setTimeout(
+            () => fail(new SafeHttpRefusal("timeout", "the server took too long to answer")),
+            limits.headersMs,
+          );
+          headersTimer.unref();
+        });
+      });
+      req.once("error", (error) => {
+        clearTimeout(connectTimer);
+        clearTimeout(headersTimer);
+        fail(new SafeHttpRefusal("connection_failed", error.message));
+      });
+      req.once("response", (response) => {
+        clearTimeout(connectTimer);
+        clearTimeout(headersTimer);
+        if (settled) {
+          response.destroy();
+          return;
+        }
+        settled = true;
+        request.signal?.removeEventListener("abort", onAbort);
+        // Idle, never total: a stream may run as long as it keeps talking.
+        response.socket.setTimeout(limits.idleMs, () => {
+          response.destroy(new SafeHttpRefusal("timeout", "the response went idle"));
+        });
+        // A caller's deadline still ends the body it is reading.
+        request.signal?.addEventListener("abort", () => response.destroy(tooLong()), { once: true });
+        response.once("close", release);
+        resolve({ status: response.statusCode ?? 0, headers: response.headers, body: response });
+      });
+      // A listener added after the signal fired never runs: check it too,
+      // once every handler is in place (a destroyed request still errors).
+      if (request.signal?.aborted) {
+        onAbort();
+        return;
+      }
+      if (body) req.end(body);
+      else req.end();
+    });
+  } catch (error) {
+    release();
+    if (error instanceof SafeHttpRefusal) throw error;
+    throw new SafeHttpRefusal("connection_failed", error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** Read a whole response body, refusing one larger than `maxBytes`. */
+export async function readSafeBody(response: SafeHttpResponse, maxBytes: number): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    const piece = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array);
+    size += piece.byteLength;
+    if (size > maxBytes) {
+      response.body.destroy();
+      throw new SafeHttpRefusal("response_too_large", "the response is too large");
+    }
+    chunks.push(piece);
+  }
+  return Buffer.concat(chunks);
+}
+
+/** A buffered JSON exchange (discovery, registration, token endpoints):
+ *  the status and the parsed body, or null when it is not JSON. */
+export async function safeJson(
+  request: SafeHttpRequest,
+  options: {
+    maxResponseBytes?: number;
+    limits?: SafeHttpLimits;
+    deps?: SafeHttpDeps;
+    /** The whole exchange, connect to last byte. */
+    deadlineMs?: number;
+  } = {},
+): Promise<{ status: number; json: unknown }> {
+  const signal =
+    request.signal ?? (options.deadlineMs !== undefined ? AbortSignal.timeout(Math.max(1, options.deadlineMs)) : undefined);
+  const response = await safeRequest(
+    { ...request, headers: { accept: "application/json", ...request.headers }, ...(signal ? { signal } : {}) },
+    options.limits,
+    options.deps,
+  );
+  let raw: Buffer;
+  try {
+    raw = await readSafeBody(response, options.maxResponseBytes ?? 256 * 1024);
+  } catch (error) {
+    if (error instanceof SafeHttpRefusal) throw error;
+    throw new SafeHttpRefusal(signal?.aborted ? "timeout" : "connection_failed", "the response did not complete");
+  }
+  let json: unknown = null;
+  try {
+    json = JSON.parse(raw.toString("utf8"));
+  } catch {
+    json = null;
+  }
+  return { status: response.status, json };
+}

package/lib/secrets-proxy/address.ts

@@ -0,0 +1,95 @@
+/**
+ * Which upstream addresses the secrets proxy may dial (ADR-153 §3, rule 6).
+ *
+ * A proxied request carries a real secret, so its destination must be the
+ * public API the key is bound to — never something only the runner can
+ * reach (its loopback, the Docker bridge, a cloud metadata endpoint, the
+ * tailnet). The runner resolves the domain itself, and one non-public
+ * address anywhere in the answer rejects the whole answer, so a rebinding
+ * record cannot win by mixing a private address in with a public one.
+ *
+ * IPv6 is an allow-list (global unicast 2000::/3 only) minus special-purpose
+ * blocks; everything that embeds an IPv4 address (mapped, compatible,
+ * NAT64, 6to4, Teredo) is refused outright rather than unpacked.
+ */
+
+import { BlockList, isIP } from "node:net";
+
+const DENIED_IPV4: ReadonlyArray<readonly [string, number]> = [
+  ["0.0.0.0", 8], // "this network"
+  ["10.0.0.0", 8], // RFC 1918
+  ["100.64.0.0", 10], // CGNAT (RFC 6598) — Tailscale lives here
+  ["127.0.0.0", 8], // loopback
+  ["169.254.0.0", 16], // link-local, incl. cloud metadata
+  ["172.16.0.0", 12], // RFC 1918
+  ["192.0.0.0", 24], // IETF protocol assignments
+  ["192.0.2.0", 24], // TEST-NET-1
+  ["192.88.99.0", 24], // deprecated 6to4 relay anycast
+  ["192.168.0.0", 16], // RFC 1918
+  ["198.18.0.0", 15], // benchmarking
+  ["198.51.100.0", 24], // TEST-NET-2
+  ["203.0.113.0", 24], // TEST-NET-3
+  ["224.0.0.0", 4], // multicast
+  ["240.0.0.0", 4], // reserved, incl. 255.255.255.255
+];
+
+const DENIED_IPV6: ReadonlyArray<readonly [string, number]> = [
+  ["::ffff:0:0", 96], // IPv4-mapped
+  ["2001::", 23], // IETF protocol assignments, incl. Teredo 2001::/32
+  ["2001:db8::", 32], // documentation
+  ["2002::", 16], // 6to4
+  ["3fff::", 20], // documentation (RFC 9637)
+];
+
+// Two lists, never one: BlockList compares IPv4 against IPv6 rules through
+// the mapped form, so a `::ffff:0:0/96` rule in a shared list denies EVERY
+// IPv4 address (checked live on Node 22.11).
+const deniedIpv4 = new BlockList();
+for (const [network, prefix] of DENIED_IPV4) deniedIpv4.addSubnet(network, prefix, "ipv4");
+const deniedIpv6 = new BlockList();
+for (const [network, prefix] of DENIED_IPV6) deniedIpv6.addSubnet(network, prefix, "ipv6");
+
+// Loopback, unspecified, ULA fc00::/7, link-local fe80::/10, multicast
+// ff00::/8, NAT64 64:ff9b::/96 and IPv4-compatible ::/96 all fall outside.
+const globalUnicast = new BlockList();
+globalUnicast.addSubnet("2000::", 3, "ipv6");
+
+export function isPublicAddress(ip: string): boolean {
+  // isIP accepts zone ids (`fe80::1%eth0`); BlockList would quietly miss them.
+  if (typeof ip !== "string" || ip.includes("%")) return false;
+  try {
+    switch (isIP(ip)) {
+      case 4:
+        return !deniedIpv4.check(ip, "ipv4");
+      case 6:
+        return globalUnicast.check(ip, "ipv6") && !deniedIpv6.check(ip, "ipv6");
+      default:
+        return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+// Internal custom connections add only these explicitly approved destinations.
+// Do not change the public proxy's policy or unwrap IPv4 embedded in IPv6.
+const internalIpv4 = new BlockList();
+for (const [network, prefix] of [["10.0.0.0", 8], ["172.16.0.0", 12], ["192.168.0.0", 16], ["100.64.0.0", 10]] as const) internalIpv4.addSubnet(network, prefix, "ipv4");
+const metadataIpv4 = new BlockList();
+metadataIpv4.addAddress("100.100.100.200", "ipv4"); // Alibaba Cloud metadata within CGNAT
+const internalIpv6 = new BlockList();
+internalIpv6.addSubnet("fc00::", 7, "ipv6");
+const metadataIpv6 = new BlockList();
+metadataIpv6.addAddress("fd00:ec2::254", "ipv6");
+export function isInternalConnectionAddress(ip: string): boolean {
+  if (typeof ip !== "string" || !/^[0-9a-fA-FxX:.]+$/.test(ip)) return false;
+  // WHATWG URL canonicalization normalizes decimal/octal/hex IPv4 spellings.
+  let normalized: string;
+  try { normalized = new URL(`http://${ip.includes(":") ? `[${ip}]` : ip}`).hostname.replace(/^\[|\]$/g, ""); } catch { return false; }
+  if (isPublicAddress(normalized)) return true;
+  switch (isIP(normalized)) {
+    case 4: return internalIpv4.check(normalized, "ipv4") && !metadataIpv4.check(normalized, "ipv4");
+    case 6: return internalIpv6.check(normalized, "ipv6") && !metadataIpv6.check(normalized, "ipv6");
+    default: return false;
+  }
+}

package/lib/secrets-proxy/audit.ts

@@ -0,0 +1,30 @@
+/**
+ * The secrets proxy's audit log (ADR-153 §3 rule 8), next to
+ * mcp-audit.jsonl. The engine already keeps values, placeholders, paths and
+ * queries out of every entry; this only appends.
+ *
+ * It THROWS when a line cannot be written. An injection is recorded before
+ * its value leaves, and the engine refuses the request when that record
+ * fails; refusals and skips go through the engine's best-effort wrapper.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const SECRETS_PROXY_AUDIT_FILE = "secrets-proxy-audit.jsonl";
+
+export function createAuditWriter(logsDir: string): (entry: Record<string, unknown>) => void {
+  const file = join(logsDir, SECRETS_PROXY_AUDIT_FILE);
+  return (entry) => {
+    const line = `${JSON.stringify(entry)}\n`;
+    try {
+      appendFileSync(file, line, { mode: 0o600 });
+    } catch (error) {
+      // A logs dir removed under a running runner (a cleanup job) must not
+      // refuse every proxied request until a restart: recreate and retry once.
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      mkdirSync(logsDir, { recursive: true, mode: 0o700 });
+      appendFileSync(file, line, { mode: 0o600 });
+    }
+  };
+}

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