pgserve 2.4.0 → 2.6.0

package/src/cosign/trust-store.js

@@ -0,0 +1,250 @@
+/**
+ * User-extensible cosign trust store at `~/.pgserve/trust/identities.json`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3
+ * (the `pgserve trust add/list/remove` CLI surface).
+ *
+ * Hardcoded trust roots live in `src/cosign/trust-list.js` and ship in the
+ * binary; operators cannot remove or override them. This module owns the
+ * separate, mutable layer where operators add their own publishers (e.g.
+ * a private fork of pgserve, an internal release workflow).
+ *
+ * File format (v1):
+ *   {
+ *     "schemaVersion": 1,
+ *     "entries": [
+ *       {
+ *         "id":             "<short-stable-id>",
+ *         "publisher":      "<package-json-pgserve-publisher>",
+ *         "issuer":         "<oidc-issuer-url>",
+ *         "identityRegexp": "<sigstore-cert-identity-regexp>",
+ *         "description":    "<human-readable, optional>",
+ *         "addedAt":        "<iso-8601>"
+ *       }
+ *     ]
+ *   }
+ *
+ * Write semantics: atomic via tmp-file + rename, file mode 0600.
+ * Read semantics: missing file or empty contents → `{ schemaVersion: 1, entries: [] }`.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TRUSTED_IDENTITIES, listHardcodedTrust } from './trust-list.js';
+
+const SCHEMA_VERSION = 1;
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+const TRUST_FILE_NAME = 'identities.json';
+
+export function getTrustDir(homeDir = os.homedir()) {
+  return path.join(homeDir, '.pgserve', 'trust');
+}
+
+export function getTrustFilePath(homeDir = os.homedir()) {
+  return path.join(getTrustDir(homeDir), TRUST_FILE_NAME);
+}
+
+function emptyStore() {
+  return { schemaVersion: SCHEMA_VERSION, entries: [] };
+}
+
+/**
+ * Read the user trust store. Returns the parsed object on success, or an
+ * empty store if the file is missing. Throws on parse failure / bad shape.
+ */
+export function readTrustStore({ homeDir = os.homedir() } = {}) {
+  const file = getTrustFilePath(homeDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyStore();
+    throw err;
+  }
+  if (!raw.trim()) return emptyStore();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(`pgserve trust store at ${file} is not valid JSON: ${err.message}`);
+    e.code = 'ETRUSTSTORE';
+    throw e;
+  }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.entries)) {
+    const e = new Error(`pgserve trust store at ${file} is missing the entries array`);
+    e.code = 'ETRUSTSTORE';
+    throw e;
+  }
+  if (parsed.schemaVersion !== SCHEMA_VERSION) {
+    const e = new Error(
+      `pgserve trust store schemaVersion ${parsed.schemaVersion} unsupported (expected ${SCHEMA_VERSION})`,
+    );
+    e.code = 'ETRUSTSTORE';
+    throw e;
+  }
+  // Per-entry shape check. Without this, a manually-edited
+  // identities.json containing `{"entries":[{}]}` would slip past the
+  // store-level guard and crash the formatter in `pgserve trust list`
+  // with a generic TypeError on first field access — losing the
+  // documented exit-2 ("malformed store") path. Fail fast here with
+  // the same ETRUSTSTORE code so downstream callers (the CLI command,
+  // `pgserve verify`, future provisioner) can branch on it uniformly.
+  for (let i = 0; i < parsed.entries.length; i++) {
+    const e = parsed.entries[i];
+    if (!e || typeof e !== 'object'
+        || typeof e.id !== 'string' || e.id.length === 0
+        || typeof e.issuer !== 'string' || e.issuer.length === 0
+        || typeof e.identityRegexp !== 'string' || e.identityRegexp.length === 0) {
+      const err = new Error(
+        `pgserve trust store at ${file}: entries[${i}] is missing required fields ` +
+          `(id, issuer, identityRegexp)`,
+      );
+      err.code = 'ETRUSTSTORE';
+      throw err;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Atomically write the trust store. Creates the directory if absent.
+ */
+export function writeTrustStore(store, { homeDir = os.homedir() } = {}) {
+  if (!store || typeof store !== 'object' || !Array.isArray(store.entries)) {
+    throw new Error('writeTrustStore: store must be { schemaVersion, entries }');
+  }
+  const dir = getTrustDir(homeDir);
+  const file = getTrustFilePath(homeDir);
+  fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+  const tmp = `${file}.tmp.${process.pid}`;
+  const payload = JSON.stringify({ schemaVersion: SCHEMA_VERSION, entries: store.entries }, null, 2) + '\n';
+  fs.writeFileSync(tmp, payload, { mode: FILE_MODE });
+  fs.renameSync(tmp, file);
+  try {
+    fs.chmodSync(file, FILE_MODE);
+  } catch {
+    /* best-effort on platforms that ignore mode */
+  }
+}
+
+/**
+ * Validate a single user entry candidate. Throws on bad shape.
+ * Returns the normalized entry (trimmed strings, computed addedAt).
+ */
+export function validateEntry(candidate) {
+  if (!candidate || typeof candidate !== 'object') {
+    throw new Error('trust entry must be an object');
+  }
+  const required = ['id', 'issuer', 'identityRegexp'];
+  for (const key of required) {
+    const v = candidate[key];
+    if (typeof v !== 'string' || v.length === 0) {
+      throw new Error(`trust entry field "${key}" must be a non-empty string`);
+    }
+  }
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(candidate.id)) {
+    throw new Error(
+      `trust entry id "${candidate.id}" must match /^[a-z0-9][a-z0-9._-]{0,63}$/i`,
+    );
+  }
+  // Normalize id to lowercase. The regex accepts upper-case (/i flag) so
+  // operators can paste pretty identifiers, but storage + lookup are
+  // case-insensitive — otherwise an entry typed "Foo" could shadow a
+  // hardcoded "foo" silently. Normalizing once on write keeps the
+  // hardcoded-shadow check simple and makes `trust remove FOO` idempotent
+  // with `trust add foo`.
+  const normalizedId = candidate.id.toLowerCase();
+  // Validate the identityRegexp parses as JS regex (cosign uses a similar
+  // RE2-ish dialect; this catches the obvious garbage while letting valid
+  // sigstore patterns through).
+  try {
+    new RegExp(candidate.identityRegexp);
+  } catch (err) {
+    throw new Error(`trust entry identityRegexp is not a valid regex: ${err.message}`);
+  }
+  return {
+    id: normalizedId,
+    publisher: typeof candidate.publisher === 'string' ? candidate.publisher : '',
+    issuer: candidate.issuer,
+    identityRegexp: candidate.identityRegexp,
+    description: typeof candidate.description === 'string' ? candidate.description : '',
+    addedAt: typeof candidate.addedAt === 'string' && candidate.addedAt
+      ? candidate.addedAt
+      : new Date().toISOString(),
+  };
+}
+
+function isHardcodedId(id) {
+  // Compare lowercase-against-lowercase. validateEntry normalizes new
+  // user entries to lowercase; hardcoded ids in TRUSTED_IDENTITIES
+  // already use lowercase by convention, but we lowercase both sides to
+  // make the predicate symmetric and immune to a typo in the hardcoded
+  // table from leaking through.
+  const needle = id.toLowerCase();
+  return TRUSTED_IDENTITIES.some((e) => e.id.toLowerCase() === needle);
+}
+
+/**
+ * Add a user trust entry. Refuses to shadow a hardcoded id.
+ * Returns the normalized entry that was written.
+ */
+export function addUserTrust(candidate, opts = {}) {
+  const entry = validateEntry(candidate);
+  if (isHardcodedId(entry.id)) {
+    const e = new Error(
+      `cannot add "${entry.id}" — id collides with a hardcoded trust root and would shadow it`,
+    );
+    e.code = 'ETRUSTSHADOW';
+    throw e;
+  }
+  const store = readTrustStore(opts);
+  const existing = store.entries.findIndex((x) => x.id === entry.id);
+  if (existing >= 0) {
+    store.entries[existing] = entry;
+  } else {
+    store.entries.push(entry);
+  }
+  writeTrustStore(store, opts);
+  return entry;
+}
+
+/**
+ * Remove a user trust entry by id. Refuses to remove hardcoded entries.
+ * Returns true on success, false if the id was not in the user store.
+ */
+export function removeUserTrust(id, opts = {}) {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('removeUserTrust: id must be a non-empty string');
+  }
+  // Lowercase normalization mirrors validateEntry — `trust remove FOO`
+  // must find the entry that `trust add foo` (or `trust add Foo`) wrote.
+  const normalizedId = id.toLowerCase();
+  if (isHardcodedId(normalizedId)) {
+    const e = new Error(`cannot remove "${normalizedId}" — hardcoded trust roots are not removable`);
+    e.code = 'ETRUSTHARDCODED';
+    throw e;
+  }
+  const store = readTrustStore(opts);
+  const before = store.entries.length;
+  store.entries = store.entries.filter((x) => x.id !== normalizedId);
+  if (store.entries.length === before) return false;
+  writeTrustStore(store, opts);
+  return true;
+}
+
+/**
+ * Combined view: hardcoded entries followed by user entries, each tagged
+ * with `source` and `removable`. Used by `pgserve trust list`.
+ */
+export function listAllTrust(opts = {}) {
+  const hardcoded = listHardcodedTrust();
+  const store = readTrustStore(opts);
+  const user = store.entries.map((entry) => ({ ...entry, source: 'user', removable: true }));
+  return [...hardcoded, ...user];
+}
+
+export const __testInternals = Object.freeze({ SCHEMA_VERSION, FILE_MODE, DIR_MODE });

package/src/cosign/verify-binary.js

@@ -0,0 +1,277 @@
+/**
+ * Cosign keyless OIDC binary verifier.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+ *
+ * Per Decision P5 (locked), we shell out to the `cosign` CLI rather than
+ * vendoring sigstore-rs. Verification model:
+ *
+ *   - Each binary distributed by an automagik release ships with a
+ *     paired Sigstore bundle file at `<binary>.bundle` (modern keyless
+ *     OIDC attestation, JSON-encoded).
+ *   - We invoke `cosign verify-blob --bundle <bundle>
+ *     --certificate-identity-regexp <re> --certificate-oidc-issuer <iss>
+ *     <binary>` — once per entry in the trust list.
+ *   - First entry that exits 0 wins. We return its identity + tier.
+ *   - If every entry fails, we surface the most-specific cosign diagnostic
+ *     (the last exit) so the operator knows which trust root we tried.
+ *
+ * Resolution of the cosign executable:
+ *   1. Caller-supplied `cosignBin` (used by tests + `--cosign-bin` flag)
+ *   2. `cosign` on `$PATH`
+ *   3. Cached static binary at `~/.pgserve/bin/cosign`
+ *   4. Download official static binary from sigstore release (offline by
+ *      default — only triggered when `allowFetch: true` is passed)
+ *
+ * Returns a tagged union:
+ *   { ok: true,  identity, tier, sha256, cosignBin, bundle }
+ *   { ok: false, reason, detail?, identityChain? }
+ */
+
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TRUSTED_IDENTITIES } from './trust-list.js';
+
+export const COSIGN_TIER = 'cosign_signed';
+export const COSIGN_BIN_DIR = path.join(os.homedir(), '.pgserve', 'bin');
+export const COSIGN_BIN_FILE = path.join(COSIGN_BIN_DIR, process.platform === 'win32' ? 'cosign.exe' : 'cosign');
+
+const COSIGN_RELEASE_VERSION = 'v2.2.4';
+const COSIGN_RELEASE_BASE = `https://github.com/sigstore/cosign/releases/download/${COSIGN_RELEASE_VERSION}`;
+
+/**
+ * Compute sha256 of a file. Returns lowercase hex.
+ */
+export function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  const buf = fs.readFileSync(filePath);
+  hash.update(buf);
+  return hash.digest('hex');
+}
+
+/**
+ * Resolve the sidecar bundle path for a given binary path. Convention:
+ * `<binary>.bundle`. Operators that publish detached `.sig` + `.cert` can
+ * regenerate a bundle with `cosign sign-blob --bundle <path>.bundle`; we
+ * intentionally only support the bundle form to keep the surface narrow.
+ */
+export function resolveBundlePath(binaryPath) {
+  return `${binaryPath}.bundle`;
+}
+
+/**
+ * Resolve which `cosign` executable to use. Returns a string path or null
+ * if no cosign is available and `allowFetch: false`.
+ *
+ * PATH probing is implemented in-process (rather than shelling out to
+ * `which` / `where`) so the resolver works inside test harnesses that
+ * scrub PATH down to a single stub directory.
+ */
+export function resolveCosignBin({ cosignBin, allowFetch = false } = {}) {
+  if (cosignBin && fs.existsSync(cosignBin)) return cosignBin;
+
+  const fromPath = lookupOnPath(process.platform === 'win32' ? 'cosign.exe' : 'cosign');
+  if (fromPath) return fromPath;
+
+  // Cached static binary.
+  if (fs.existsSync(COSIGN_BIN_FILE)) return COSIGN_BIN_FILE;
+
+  if (!allowFetch) return null;
+
+  try {
+    return fetchCosignBin();
+  } catch {
+    return null;
+  }
+}
+
+function lookupOnPath(name) {
+  const PATH = process.env.PATH || '';
+  if (!PATH) return null;
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const dirs = PATH.split(sep).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, name);
+    try {
+      const stat = fs.statSync(candidate);
+      if (stat.isFile()) {
+        // On POSIX, ensure it's executable; on Windows, file existence is enough.
+        if (process.platform === 'win32') return candidate;
+        if ((stat.mode & 0o111) !== 0) return candidate;
+      }
+    } catch {
+      // missing or stat error — try next dir
+    }
+  }
+  return null;
+}
+
+/**
+ * Download the official cosign static binary into `~/.pgserve/bin/cosign`.
+ * Synchronous — used by `pgserve verify` when no cosign is on PATH and the
+ * operator opts into the fetch (see Decision P5: "if cosign not on PATH,
+ * pgserve install shells out to a downloader to fetch the official static
+ * binary into ~/.pgserve/bin/cosign").
+ *
+ * Network-dependent. Throws on failure. Tests stub via `cosignBin` instead
+ * of this code path.
+ */
+export function fetchCosignBin({
+  releaseBase = COSIGN_RELEASE_BASE,
+  targetFile = COSIGN_BIN_FILE,
+  targetDir = COSIGN_BIN_DIR,
+} = {}) {
+  fs.mkdirSync(targetDir, { recursive: true, mode: 0o755 });
+  const assetName = pickCosignAssetName();
+  const url = `${releaseBase}/${assetName}`;
+  const tmp = `${targetFile}.tmp.${process.pid}`;
+  downloadToFileSync(url, tmp);
+  fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, targetFile);
+  return targetFile;
+}
+
+function pickCosignAssetName() {
+  const arch = process.arch === 'x64' ? 'amd64' : process.arch === 'arm64' ? 'arm64' : process.arch;
+  if (process.platform === 'darwin') return `cosign-darwin-${arch}`;
+  if (process.platform === 'win32') return `cosign-windows-${arch}.exe`;
+  return `cosign-linux-${arch}`;
+}
+
+function downloadToFileSync(url, destPath) {
+  // Node has no built-in synchronous HTTP. We fall back to spawning curl
+  // since this only runs once per host (cached afterward) and curl is
+  // ubiquitous on the supported platforms.
+  const curl = spawnSync('curl', ['-fsSL', '-o', destPath, url], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (curl.status === 0) return;
+  // Fallback: try wget.
+  const wget = spawnSync('wget', ['-qO', destPath, url], { stdio: ['ignore', 'pipe', 'pipe'] });
+  if (wget.status === 0) return;
+  throw new Error(
+    `cosign-verify: failed to download cosign from ${url} (curl exit ${curl.status}, wget exit ${wget?.status ?? 'n/a'})`,
+  );
+}
+
+/**
+ * Verify a binary with cosign.
+ *
+ * @param {string} binaryPath
+ * @param {object} [options]
+ * @param {string} [options.cosignBin]   override cosign executable
+ * @param {string} [options.bundlePath]  override bundle sidecar path
+ * @param {Array}  [options.trustList]   override hardcoded TRUSTED_IDENTITIES
+ * @param {boolean}[options.allowFetch]  allow fetching the cosign binary if missing
+ * @returns {{ ok: true, identity, tier, sha256, cosignBin, bundle, identityChain }
+ *         | { ok: false, reason, detail?, identityChain? }}
+ */
+export function verifyBinary(binaryPath, options = {}) {
+  if (typeof binaryPath !== 'string' || binaryPath.length === 0) {
+    return { ok: false, reason: 'invalid-args', detail: 'binaryPath required' };
+  }
+  if (!fs.existsSync(binaryPath)) {
+    return { ok: false, reason: 'binary-missing', detail: binaryPath };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(binaryPath);
+  } catch (err) {
+    return { ok: false, reason: 'binary-unreadable', detail: err.message };
+  }
+  if (!stat.isFile()) {
+    return { ok: false, reason: 'binary-not-a-file', detail: binaryPath };
+  }
+
+  const bundlePath = options.bundlePath || resolveBundlePath(binaryPath);
+  if (!fs.existsSync(bundlePath)) {
+    return {
+      ok: false,
+      reason: 'bundle-missing',
+      detail: `expected sigstore bundle at ${bundlePath} (run \`cosign sign-blob --bundle ${bundlePath} ${binaryPath}\` to attest)`,
+    };
+  }
+
+  const trustList = options.trustList || TRUSTED_IDENTITIES;
+  if (!Array.isArray(trustList) || trustList.length === 0) {
+    return { ok: false, reason: 'empty-trust-list' };
+  }
+
+  const cosignBin = resolveCosignBin({
+    cosignBin: options.cosignBin,
+    allowFetch: options.allowFetch === true,
+  });
+  if (!cosignBin) {
+    return {
+      ok: false,
+      reason: 'cosign-missing',
+      detail:
+        'no `cosign` binary on $PATH or in ~/.pgserve/bin/cosign — install cosign or rerun with --allow-fetch',
+    };
+  }
+
+  const sha256 = sha256File(binaryPath);
+  const identityChain = [];
+  let lastFailure = null;
+
+  for (const identity of trustList) {
+    if (!identity || !identity.id || !identity.issuer || !identity.identityRegexp) {
+      identityChain.push({ id: identity?.id || '<malformed>', status: 'skipped' });
+      continue;
+    }
+    const result = invokeCosign({
+      cosignBin,
+      bundlePath,
+      binaryPath,
+      identity,
+    });
+    if (result.ok) {
+      identityChain.push({ id: identity.id, status: 'matched' });
+      return {
+        ok: true,
+        identity: identity.id,
+        publisher: identity.publisher,
+        tier: COSIGN_TIER,
+        sha256,
+        cosignBin,
+        bundle: bundlePath,
+        identityChain,
+      };
+    }
+    identityChain.push({ id: identity.id, status: 'rejected', exitCode: result.exitCode });
+    lastFailure = result;
+  }
+
+  return {
+    ok: false,
+    reason: 'no-trust-match',
+    detail: lastFailure?.stderr || 'cosign rejected the binary against every trust root',
+    identityChain,
+  };
+}
+
+function invokeCosign({ cosignBin, bundlePath, binaryPath, identity }) {
+  const args = [
+    'verify-blob',
+    '--bundle', bundlePath,
+    '--certificate-identity-regexp', identity.identityRegexp,
+    '--certificate-oidc-issuer', identity.issuer,
+    binaryPath,
+  ];
+  const proc = spawnSync(cosignBin, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (proc.status === 0) {
+    return { ok: true, stdout: proc.stdout || '' };
+  }
+  return {
+    ok: false,
+    exitCode: typeof proc.status === 'number' ? proc.status : -1,
+    stderr: (proc.stderr || proc.stdout || '').trim().slice(0, 4096),
+  };
+}

package/src/gc/audit-log.js

@@ -0,0 +1,150 @@
+/**
+ * Append-only audit log writer for `pgserve gc`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * The wish acceptance criteria require gc to "audit-log every drop" so
+ * that an operator can answer "why did my database disappear?" days
+ * later. We keep the format intentionally boring: one JSON object per
+ * line at `~/.pgserve/audit/gc-<YYYY-MM-DD>.log`, opened with O_APPEND
+ * so multiple gc runs on the same day interleave cleanly.
+ *
+ * One JSON object per event so logs are streamable through tools that
+ * expect JSON-lines (jq, fluent-bit, vector, etc.) without a second
+ * parser. UTC date in the filename so log rotation across timezones is
+ * deterministic.
+ *
+ * Permissions: dir 0700, file 0600 — same posture as the cosign cache
+ * tokens. Audit logs may name databases that contain sensitive tenant
+ * identifiers; tightening file mode is cheap insurance.
+ *
+ * Pure-ish: filesystem I/O is the side effect. No postgres, no network.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const AUDIT_DIR_NAME = 'audit';
+export const AUDIT_FILE_PREFIX = 'gc-';
+export const AUDIT_FILE_MODE = 0o600;
+export const AUDIT_DIR_MODE = 0o700;
+
+/**
+ * @typedef {Object} GcAuditEvent
+ * @property {string}  ts            ISO 8601 timestamp with ms.
+ * @property {'drop'|'skip'|'error'|'start'|'finish'} action
+ * @property {string=} fingerprint   pgserve_meta.fingerprint
+ * @property {string=} database      database name acted on
+ * @property {string=} role          role name acted on
+ * @property {string=} reason        finding.reason from orphan detection
+ *                                   ('missing_db' | 'missing_path' | …)
+ *                                   or a free-form skip / error reason.
+ * @property {string=} detail        operator-facing detail line.
+ * @property {string=} dryRun        present when --dry-run; the audit
+ *                                   line then records what *would* have
+ *                                   happened.
+ */
+
+export function getAuditDir({ homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.pgserve', AUDIT_DIR_NAME);
+}
+
+/**
+ * Build the audit-file path for a given UTC date. Defaults to "today".
+ */
+export function getAuditFilePath({ homeDir = os.homedir(), date = new Date() } = {}) {
+  const yyyyMmDd = formatUtcDate(date);
+  return path.join(getAuditDir({ homeDir }), `${AUDIT_FILE_PREFIX}${yyyyMmDd}.log`);
+}
+
+function formatUtcDate(date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+    throw new TypeError('formatUtcDate: date must be a valid Date');
+  }
+  const yyyy = String(date.getUTCFullYear()).padStart(4, '0');
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(date.getUTCDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/**
+ * Append a single gc audit event. Returns the line that was written
+ * (without the trailing newline) so callers can mirror it to stdout.
+ *
+ * @param {GcAuditEvent} event
+ * @param {object} [opts]
+ * @param {string} [opts.homeDir]   override for tests
+ * @param {Date}   [opts.date]      override for tests; defaults to now
+ */
+export function writeGcAudit(event, opts = {}) {
+  if (!event || typeof event !== 'object') {
+    throw new TypeError('writeGcAudit: event must be an object');
+  }
+  if (typeof event.action !== 'string' || event.action.length === 0) {
+    throw new TypeError('writeGcAudit: event.action is required');
+  }
+  const dir = getAuditDir(opts);
+  const file = getAuditFilePath(opts);
+  fs.mkdirSync(dir, { recursive: true, mode: AUDIT_DIR_MODE });
+  // mkdirSync's `mode` only applies on creation. If the audit dir was
+  // previously created with a looser umask (older gc versions, manual
+  // mkdir -p, restored backup) it stays at whatever mode it had —
+  // tighten it to 0700 to match the file-side belt-and-suspenders.
+  try {
+    fs.chmodSync(dir, AUDIT_DIR_MODE);
+  } catch {
+    /* best-effort on platforms that ignore chmod */
+  }
+  // ts must be the canonical ISO 8601 string unless the caller supplied
+  // a non-empty string (correlation-id use case). The spread MUST come
+  // first so a stray `ts: undefined` / `ts: 0` / `ts: new Date()` from
+  // the caller cannot silently overwrite our generated value — JS
+  // object-spread precedence means later keys win. (Earlier shape had
+  // this inverted with a wrong comment claiming the spread "doesn't
+  // overwrite" — it does.)
+  const enriched = {
+    ...event,
+    ts: typeof event.ts === 'string' && event.ts ? event.ts : new Date().toISOString(),
+  };
+  const line = JSON.stringify(enriched);
+  fs.appendFileSync(file, line + '\n', { mode: AUDIT_FILE_MODE });
+  // appendFileSync's `mode` only applies on file creation; chmod the
+  // existing file to be safe in case it was previously created with a
+  // looser umask (older gc versions, manual touches, etc.).
+  try {
+    fs.chmodSync(file, AUDIT_FILE_MODE);
+  } catch {
+    /* best-effort on platforms that ignore chmod */
+  }
+  return line;
+}
+
+/**
+ * Read all events for a single UTC date. Returns parsed objects; lines
+ * that fail to parse are returned as `{ malformed: true, raw: <line> }`
+ * so a corrupt earlier write doesn't make the rest of the file
+ * unreadable. Missing file → empty array.
+ */
+export function readGcAuditDay({ homeDir = os.homedir(), date = new Date() } = {}) {
+  const file = getAuditFilePath({ homeDir, date });
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (line.length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      out.push({ malformed: true, raw: line });
+    }
+  }
+  return out;
+}
+
+export const __testInternals = Object.freeze({ formatUtcDate });