pgserve 1.2.0 → 2.0.0

package/src/gc.js

@@ -0,0 +1,351 @@
+/**
+ * pgserve GC — 3-layer lifecycle sweep (Group 5).
+ *
+ * Decides which user databases to reap based on:
+ *   1. `persist=true` — exempt from GC, audited as `db_persist_honored`.
+ *   2. Liveness — if `liveness_pid` points at a running process, slide
+ *      `last_connection_at` forward to "now" (the peer is alive, the row is
+ *      a heartbeat) and never reap.
+ *   3. TTL — peer is gone AND `now - last_connection_at > ttlMs` (default
+ *      24h) → `DROP DATABASE`, delete the meta row, audit reap event.
+ *
+ * Audit reap event is `db_reaped_liveness` when the row had a non-null
+ * liveness_pid that is now dead, otherwise `db_reaped_ttl` (the row never
+ * registered a liveness_pid — pure idle expiry).
+ *
+ * `installSweepTriggers(daemon, …)` wires the three call sites:
+ *   - boot: a single sweep right after the daemon is listening, with a
+ *     summary log line so operators see GC activity at startup.
+ *   - hourly `setInterval` (configurable via `intervalMs`).
+ *   - on-connect sampling: subscribe to the daemon's `'accept'` event and
+ *     fire `gcSweep` async at rate 1/N where `N = max(1, dbCount/10)`. The
+ *     listener never awaits the sweep, so accept latency is unaffected.
+ */
+
+import { audit, AUDIT_EVENTS } from './audit.js';
+import { forEachReapable, deleteMetaRow, touchLastConnection } from './control-db.js';
+
+const TTL_MS_DEFAULT = 24 * 60 * 60 * 1000;
+const HOURLY_MS = 60 * 60 * 1000;
+
+/**
+ * Default liveness probe — POSIX `kill(pid, 0)` returns 0 if the process is
+ * alive, throws ESRCH if gone, EPERM if owned by another user (still alive).
+ *
+ * @param {number|null|undefined} pid
+ * @returns {boolean}
+ */
+function defaultIsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * @typedef {object} GcSweepOptions
+ * @property {{query: Function}} adminClient — pgserve admin DB connection
+ * @property {{adminPool: any, createdDatabases?: Set<string>}} [pgManager] —
+ *   optional; used to evict from the in-process createdDatabases cache after
+ *   a successful DROP. Tests can omit; gcSweep always falls back to the
+ *   adminClient's `query()` for the actual DROP.
+ * @property {number|Date} [now]
+ * @property {number} [ttlMs] — defaults to 24h
+ * @property {boolean} [dryRun] — when true, never DROP / DELETE / audit reap
+ * @property {(pid: number|null|undefined) => boolean} [isProcessAlive]
+ * @property {{warn?: Function, info?: Function, error?: Function, debug?: Function}} [logger]
+ */
+
+/**
+ * @typedef {object} GcSweepResult
+ * @property {number} examined
+ * @property {number} reaped
+ * @property {number} kept
+ * @property {number} persistSkipped
+ * @property {number} aliveSkipped
+ * @property {string[]} reapedNames
+ */
+
+/**
+ * Run one GC sweep. Returns counts so callers can log a summary or assert
+ * in tests.
+ *
+ * @param {GcSweepOptions} opts
+ * @returns {Promise<GcSweepResult>}
+ */
+export async function gcSweep({
+  adminClient,
+  pgManager = null,
+  now = new Date(),
+  ttlMs = TTL_MS_DEFAULT,
+  dryRun = false,
+  isProcessAlive = defaultIsProcessAlive,
+  logger,
+} = {}) {
+  if (!adminClient) throw new Error('gcSweep: adminClient required');
+
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) throw new Error('gcSweep: now must be Date or numeric ms');
+
+  const result = {
+    examined: 0,
+    reaped: 0,
+    kept: 0,
+    persistSkipped: 0,
+    aliveSkipped: 0,
+    reapedNames: [],
+  };
+
+  // Snapshot so we don't iterate while we DELETE — pg's async iterator
+  // protocols vary across drivers, but materialising 240 rows is cheap and
+  // sidesteps any cursor-vs-DELETE quirks.
+  const candidates = [];
+  for await (const row of forEachReapable(adminClient)) {
+    candidates.push(row);
+  }
+
+  for (const row of candidates) {
+    result.examined += 1;
+
+    // Persist=true rows never appear from forEachReapable (the query filters
+    // them out), but if the schema changes that contract we still defend
+    // here — and emit the audit event the wish promises.
+    if (row.persist) {
+      result.persistSkipped += 1;
+      result.kept += 1;
+      if (!dryRun) {
+        audit(AUDIT_EVENTS.DB_PERSIST_HONORED, {
+          database: row.databaseName,
+          fingerprint: row.fingerprint,
+        });
+      }
+      continue;
+    }
+
+    const livenessPid = row.livenessPid;
+    const hadLivenessPid = Number.isInteger(livenessPid) && livenessPid > 0;
+    const alive = hadLivenessPid && isProcessAlive(livenessPid);
+
+    if (alive) {
+      result.aliveSkipped += 1;
+      result.kept += 1;
+      if (!dryRun) {
+        // Slide the window: an alive process means the row is effectively
+        // current, even if the pgserve_meta last_connection_at value lags.
+        try {
+          await touchLastConnection(adminClient, {
+            databaseName: row.databaseName,
+            livenessPid,
+          });
+        } catch (err) {
+          logger?.warn?.(
+            { err: err?.message || String(err), database: row.databaseName },
+            'gcSweep: touchLastConnection failed for live row (non-fatal)',
+          );
+        }
+      }
+      continue;
+    }
+
+    const lastMs = row.lastConnectionAt instanceof Date
+      ? row.lastConnectionAt.getTime()
+      : Number(row.lastConnectionAt);
+    const ageMs = Number.isFinite(lastMs) ? nowMs - lastMs : Infinity;
+
+    if (ageMs <= ttlMs) {
+      result.kept += 1;
+      continue;
+    }
+
+    if (dryRun) {
+      result.reaped += 1;
+      result.reapedNames.push(row.databaseName);
+      continue;
+    }
+
+    try {
+      await dropDatabaseSafely(adminClient, row.databaseName, logger);
+      pgManager?.createdDatabases?.delete(row.databaseName);
+      await deleteMetaRow(adminClient, row.databaseName);
+      const reapEvent = hadLivenessPid
+        ? AUDIT_EVENTS.DB_REAPED_LIVENESS
+        : AUDIT_EVENTS.DB_REAPED_TTL;
+      audit(reapEvent, {
+        database: row.databaseName,
+        fingerprint: row.fingerprint,
+        last_connection_at: row.lastConnectionAt instanceof Date
+          ? row.lastConnectionAt.toISOString()
+          : row.lastConnectionAt,
+        liveness_pid: livenessPid ?? null,
+        age_ms: Number.isFinite(ageMs) ? ageMs : null,
+      });
+      result.reaped += 1;
+      result.reapedNames.push(row.databaseName);
+    } catch (err) {
+      logger?.error?.(
+        { err: err?.message || String(err), database: row.databaseName },
+        'gcSweep: failed to reap database',
+      );
+    }
+  }
+
+  return result;
+}
+
+async function dropDatabaseSafely(adminClient, databaseName, logger) {
+  const escaped = `"${databaseName.replace(/"/g, '""')}"`;
+  // Terminate any lingering backends so DROP DATABASE doesn't refuse with
+  // 55006 (object_in_use). The peer's pgserve daemon socket is already gone
+  // (liveness dead) but Postgres can hold idle backends a while longer.
+  try {
+    await adminClient.query(
+      `SELECT pg_terminate_backend(pid)
+       FROM pg_stat_activity
+       WHERE datname = $1 AND pid <> pg_backend_pid()`,
+      [databaseName],
+    );
+  } catch (err) {
+    logger?.debug?.(
+      { err: err?.message || String(err), database: databaseName },
+      'gcSweep: pg_terminate_backend failed (non-fatal)',
+    );
+  }
+  await adminClient.query(`DROP DATABASE IF EXISTS ${escaped}`);
+}
+
+/**
+ * Wire the three sweep call sites onto a running daemon.
+ *
+ * Returns a `{stop()}` handle so tests (and `daemon.stop()`) can detach.
+ *
+ * @param {object} daemon — PgserveDaemon instance
+ * @param {object} [opts]
+ * @param {{query: Function}} [opts.adminClient] — defaults to daemon._adminClient
+ * @param {number} [opts.intervalMs] — hourly default; pass 0 to disable
+ * @param {number} [opts.ttlMs]
+ * @param {(pid: number) => boolean} [opts.isProcessAlive]
+ * @param {() => Promise<number>|number} [opts.getDbCount] — defaults to a
+ *   COUNT(*) query against pgserve_meta
+ * @param {boolean} [opts.bootSweep=true]
+ * @returns {{stop: () => Promise<void>, sweep: () => Promise<GcSweepResult>}}
+ */
+export function installSweepTriggers(daemon, opts = {}) {
+  const adminClient = opts.adminClient || daemon._adminClient;
+  if (!adminClient) {
+    throw new Error('installSweepTriggers: daemon has no admin client');
+  }
+  const intervalMs = opts.intervalMs == null ? HOURLY_MS : opts.intervalMs;
+  const ttlMs = opts.ttlMs == null ? TTL_MS_DEFAULT : opts.ttlMs;
+  const logger = daemon.logger;
+  const pgManager = daemon.pgManager;
+  const isProcessAlive = opts.isProcessAlive || defaultIsProcessAlive;
+  const getDbCount = opts.getDbCount || (async () => {
+    try {
+      const r = await adminClient.query('SELECT count(*)::int AS n FROM pgserve_meta');
+      return r.rows?.[0]?.n ?? 0;
+    } catch {
+      return 0;
+    }
+  });
+
+  let stopped = false;
+  let inflight = false;
+  let lastDbCount = 0;
+
+  const runSweep = async () => {
+    if (stopped) return null;
+    if (inflight) return null;
+    inflight = true;
+    try {
+      const res = await gcSweep({
+        adminClient,
+        pgManager,
+        now: new Date(),
+        ttlMs,
+        isProcessAlive,
+        logger,
+      });
+      lastDbCount = Math.max(0, lastDbCount - res.reaped);
+      return res;
+    } catch (err) {
+      logger?.error?.(
+        { err: err?.message || String(err) },
+        'gcSweep failed',
+      );
+      return null;
+    } finally {
+      inflight = false;
+    }
+  };
+
+  let timer = null;
+  if (intervalMs > 0) {
+    timer = setInterval(() => {
+      void runSweep();
+    }, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  const acceptListener = () => {
+    // Sample 1/N where N = max(1, ceil(dbCount/10)). Always async and
+    // detached so accept latency isn't blocked.
+    const n = Math.max(1, Math.ceil(lastDbCount / 10));
+    if (n === 1 || Math.random() * n < 1) {
+      setImmediate(() => {
+        if (stopped) return;
+        // Refresh count opportunistically before each sweep so on-connect
+        // sampling tracks the live row count without polling.
+        Promise.resolve(getDbCount())
+          .then((c) => { lastDbCount = Number(c) || 0; })
+          .then(runSweep)
+          .catch(() => { /* swallowed by runSweep */ });
+      });
+    }
+  };
+  daemon.on?.('accept', acceptListener);
+
+  const handle = {
+    sweep: runSweep,
+    async stop() {
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      daemon.off?.('accept', acceptListener);
+    },
+  };
+
+  if (opts.bootSweep !== false) {
+    // Boot sweep + count refresh + summary log. Detached so we don't block
+    // start() — the daemon is already listening at this point.
+    setImmediate(async () => {
+      try {
+        lastDbCount = Number(await getDbCount()) || 0;
+        const res = await runSweep();
+        if (res) {
+          logger?.info?.(
+            {
+              examined: res.examined,
+              reaped: res.reaped,
+              kept: res.kept,
+              persist_skipped: res.persistSkipped,
+              alive_skipped: res.aliveSkipped,
+            },
+            'pgserve GC: boot sweep complete',
+          );
+        }
+      } catch (err) {
+        logger?.warn?.(
+          { err: err?.message || String(err) },
+          'pgserve GC: boot sweep failed',
+        );
+      }
+    });
+  }
+
+  return handle;
+}

package/src/index.js

@@ -13,6 +13,17 @@ export { RestoreManager } from './restore.js';
 export { Dashboard } from './dashboard.js';
 export { StatsCollector } from './stats-collector.js';
 export { StatsDashboard } from './stats-dashboard.js';
+export {
+  PgserveDaemon,
+  startDaemon,
+  stopDaemon,
+  resolveControlSocketDir,
+  resolveControlSocketPath,
+  resolvePidLockPath,
+  resolveLibpqCompatPath,
+  acquirePidLock,
+  isProcessAlive,
+} from './daemon.js';
 
 // Default export
 export { startMultiTenantServer as default } from './router.js';

package/src/protocol.js

@@ -133,6 +133,137 @@ export function extractDatabaseName(data) {
   }
 }
 
+/**
+ * Extract `application_name` from a startup message buffer. Returns null when
+ * absent or when the buffer is malformed (callers fall back to no-auth).
+ *
+ * @param {Buffer} data
+ * @returns {string|null}
+ */
+export function extractApplicationName(data) {
+  try {
+    const params = parseStartupMessage(data, /* fastPath */ false);
+    return typeof params.application_name === 'string' ? params.application_name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return a new startup-message buffer with the `database` parameter replaced
+ * by `newDbName`. All other parameters (and their order) are preserved by
+ * default; pass `dropParams: ['application_name', ...]` to strip noisy
+ * fields the daemon would rather not forward to PG verbatim. The 4-byte
+ * length prefix at the start of the buffer is recomputed.
+ *
+ * Group 6 uses this on TCP-authenticated connections so a peer that presents
+ * a token for fingerprint X is forced into fingerprint X's database, even
+ * if the libpq client requested a different one.
+ *
+ * @param {Buffer} data — original startup message
+ * @param {string} newDbName
+ * @param {{dropParams?: string[]}} [opts]
+ * @returns {Buffer}
+ */
+export function rewriteDatabaseName(data, newDbName, opts = {}) {
+  if (!Buffer.isBuffer(data)) throw new Error('rewriteDatabaseName: buffer required');
+  if (typeof newDbName !== 'string' || newDbName.length === 0) {
+    throw new Error('rewriteDatabaseName: non-empty newDbName required');
+  }
+  const length = data.readInt32BE(0);
+  const version = data.readInt32BE(4);
+  const drop = new Set(opts.dropParams || []);
+
+  // Walk parameters; build a list of (key, value) pairs replacing 'database'.
+  const pairs = [];
+  let offset = 8;
+  let sawDatabase = false;
+  while (offset < length - 1) {
+    const keyEnd = data.indexOf(0, offset);
+    if (keyEnd === -1 || keyEnd >= length) break;
+    const key = data.toString('utf8', offset, keyEnd);
+    offset = keyEnd + 1;
+    const valueEnd = data.indexOf(0, offset);
+    if (valueEnd === -1 || valueEnd >= length) break;
+    const value = data.toString('utf8', offset, valueEnd);
+    offset = valueEnd + 1;
+    if (drop.has(key)) continue;
+    if (key === 'database') {
+      pairs.push(['database', newDbName]);
+      sawDatabase = true;
+    } else {
+      pairs.push([key, value]);
+    }
+  }
+  if (!sawDatabase) pairs.push(['database', newDbName]);
+
+  // Compute new buffer size: 4 (length) + 4 (version) + sum(key+1 + value+1) + 1 (terminator).
+  let bodyLen = 0;
+  for (const [k, v] of pairs) {
+    bodyLen += Buffer.byteLength(k, 'utf8') + 1 + Buffer.byteLength(v, 'utf8') + 1;
+  }
+  const total = 4 + 4 + bodyLen + 1;
+  const out = Buffer.alloc(total);
+  out.writeInt32BE(total, 0);
+  out.writeInt32BE(version, 4);
+  let cur = 8;
+  for (const [k, v] of pairs) {
+    cur += out.write(k, cur, 'utf8');
+    out[cur++] = 0;
+    cur += out.write(v, cur, 'utf8');
+    out[cur++] = 0;
+  }
+  out[cur++] = 0; // final terminator
+  return out;
+}
+
+/**
+ * Build a PostgreSQL ErrorResponse (`'E'`) frame.
+ *
+ * Used by the daemon to reject cross-fingerprint connection attempts
+ * with SQLSTATE `28P01 invalid_authorization_specification` before the
+ * peer's startup message ever reaches the underlying PG instance.
+ *
+ * Frame layout (PG protocol v3):
+ *   'E' (1 byte) | length (4 bytes, includes itself) | <fields...> | '\0'
+ *
+ * Each field: type-byte | utf8 string | '\0'
+ * Required fields per PG docs: 'S' (Severity), 'C' (SQLSTATE), 'M' (Message).
+ * 'V' (localized severity, server >= 9.6) is included for parity with the
+ * frames real Postgres emits — psql / pg drivers parse both transparently.
+ *
+ * @param {{severity?: string, sqlstate: string, message: string}} args
+ * @returns {Buffer}
+ */
+export function buildErrorResponse({ severity = 'FATAL', sqlstate, message }) {
+  if (typeof sqlstate !== 'string' || sqlstate.length !== 5) {
+    throw new TypeError('buildErrorResponse: sqlstate must be a 5-character string');
+  }
+  if (typeof message !== 'string' || message.length === 0) {
+    throw new TypeError('buildErrorResponse: message must be a non-empty string');
+  }
+  const field = (typeChar, value) => {
+    const valBytes = Buffer.byteLength(value, 'utf8');
+    const buf = Buffer.alloc(1 + valBytes + 1);
+    buf.writeUInt8(typeChar.charCodeAt(0), 0);
+    buf.write(value, 1, 'utf8');
+    buf.writeUInt8(0, 1 + valBytes);
+    return buf;
+  };
+  const body = Buffer.concat([
+    field('S', severity),
+    field('V', severity),
+    field('C', sqlstate),
+    field('M', message),
+    Buffer.from([0]),
+  ]);
+  const frameLength = 4 + body.length;
+  const header = Buffer.alloc(5);
+  header.writeUInt8(0x45, 0); // 'E'
+  header.writeUInt32BE(frameLength, 1);
+  return Buffer.concat([header, body]);
+}
+
 // Pre-allocated buffer pool for startup message parsing (avoids allocation per connection)
 const STARTUP_BUFFER_SIZE = 8192; // Max startup message is typically < 1KB
 const bufferPool = [];

package/src/router.js

@@ -12,6 +12,14 @@
  * - Memory mode (default) or persistent storage
  *
  * PERFORMANCE: Uses Bun.listen() and Bun.connect() for 2-3x throughput improvement
+ *
+ * v2 NOTE: The MultiTenantRouter is the **direct-embed** path — callers that
+ * spawn their own PostgresManager and bind a TCP port get a per-pid Unix
+ * socket from `pgManager.getSocketPath()` (preserved by PR #24). The new
+ * **daemon** path (`src/daemon.js`) binds a singleton control socket at
+ * `$XDG_RUNTIME_DIR/pgserve/control.sock` and is the v2 default for the
+ * `pgserve daemon` CLI subcommand. Both paths coexist; direct-embed callers
+ * are not affected by daemon mode.
  */
 
 import fs from 'fs';

package/src/tenancy.js

@@ -0,0 +1,75 @@
+/**
+ * pgserve tenancy — fingerprint-to-database name resolution + kill-switch.
+ *
+ * Group 4 wires the kernel-rooted fingerprint (Group 3) to the per-tenant
+ * Postgres database. Each `(fingerprint, name)` pair maps deterministically
+ * to a database called `app_<sanitized-name>_<12hex>` (≤63 chars, the PG
+ * identifier limit).
+ *
+ * Sanitization rules (per WISH §Group 4):
+ *   - non-[a-z0-9] runs collapse to a single `_`
+ *   - lowercased
+ *   - truncated to 30 chars (so `app_<30>_<12>` ≤ 47 chars, well under 63)
+ *
+ * The kill switch (`PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT=1`) is read
+ * once per process via `isFingerprintEnforcementDisabled()`. The daemon
+ * logs a deprecation warning at boot when the env var is observed; the
+ * audit event `enforcement_kill_switch_used` fires on every bypassed
+ * cross-fingerprint connection.
+ */
+
+export const KILL_SWITCH_ENV = 'PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT';
+
+const NAME_TRUNCATE = 30;
+const MAX_DB_IDENT = 63;
+
+/**
+ * Collapse non-alphanumeric runs to a single `_`, lowercase, truncate.
+ *
+ * Empty or null names fall back to `'anon'` so we always emit a usable
+ * database identifier — a peer with no resolvable package name still
+ * deserves a tenant DB, just one that visibly says "anonymous".
+ *
+ * @param {string|null|undefined} name
+ * @returns {string}
+ */
+export function sanitizeName(name) {
+  const raw = (typeof name === 'string' ? name : '').toLowerCase();
+  const collapsed = raw.replace(/[^a-z0-9]+/g, '_');
+  if (!collapsed || collapsed === '_') return 'anon';
+  return collapsed.slice(0, NAME_TRUNCATE);
+}
+
+/**
+ * Build the canonical per-tenant database name `app_<sanitized>_<fingerprint>`.
+ *
+ * Throws if fingerprint is not the documented 12 lowercase-hex blob —
+ * any caller that managed to slip a malformed fingerprint through deserves
+ * a loud failure rather than a silent identifier mismatch later.
+ *
+ * @param {{name: string|null|undefined, fingerprint: string}} args
+ * @returns {string}
+ */
+export function resolveTenantDatabaseName({ name, fingerprint }) {
+  if (!/^[0-9a-f]{12}$/.test(fingerprint || '')) {
+    throw new Error(`resolveTenantDatabaseName: fingerprint must be 12 hex chars, got "${fingerprint}"`);
+  }
+  const sanitized = sanitizeName(name);
+  const ident = `app_${sanitized}_${fingerprint}`;
+  if (ident.length > MAX_DB_IDENT) {
+    // Truncation already bounds sanitized to 30; the fingerprint adds 12;
+    // the prefix `app_` adds 4 + two underscores = 48. We are safe by
+    // construction, but assert anyway: a future change to NAME_TRUNCATE
+    // must not silently produce >63-char identifiers.
+    throw new Error(`resolveTenantDatabaseName: identifier "${ident}" exceeds ${MAX_DB_IDENT} chars`);
+  }
+  return ident;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function isFingerprintEnforcementDisabled(env = process.env) {
+  return env[KILL_SWITCH_ENV] === '1';
+}

package/src/tokens.js

@@ -0,0 +1,102 @@
+/**
+ * pgserve TCP bearer-token helpers (Group 6).
+ *
+ * Tokens are random 256-bit secrets shown to the operator exactly once
+ * (the output of `pgserve daemon issue-token`). Only their sha256 hash
+ * is persisted in `pgserve_meta.allowed_tokens`. Verification therefore
+ * compares hashes, never cleartext.
+ *
+ * Token id: short hex prefix used for revocation by humans
+ * (`pgserve daemon revoke-token <id>`). It is also persisted alongside
+ * the hash so `tcp_token_used` audit events can name which credential
+ * authorised the connection without leaking the secret.
+ *
+ * Wire format on the TCP path: peers pass an `application_name` shaped
+ * `?fingerprint=<12hex>&token=<bearer>` (a leading `?` is tolerated so
+ * libpq URL-style strings round-trip cleanly). Both keys are required;
+ * any missing or extra-long value is treated as auth-fail by the
+ * daemon's accept hook, never bubbling further.
+ */
+
+import crypto from 'crypto';
+
+const TOKEN_BYTES = 32;       // 256 bits — plenty of entropy
+const TOKEN_ID_BYTES = 6;     // 12 hex chars — collision-bound at ~10^14
+const MAX_TOKEN_LEN = 256;    // sanity guard for parse path
+const FP_RE = /^[0-9a-f]{12}$/;
+
+/**
+ * Mint a fresh `(id, cleartext, hash)` triple. The cleartext is meant to
+ * leave this process exactly once (printed to stdout by `issue-token`);
+ * only the hash gets stored.
+ *
+ * @returns {{id: string, cleartext: string, hash: string}}
+ */
+export function mintToken() {
+  const id = crypto.randomBytes(TOKEN_ID_BYTES).toString('hex');
+  const cleartext = crypto.randomBytes(TOKEN_BYTES).toString('hex');
+  const hash = hashToken(cleartext);
+  return { id, cleartext, hash };
+}
+
+/**
+ * Sha256 of the bearer token in lowercase hex. Centralised so daemon
+ * accept code, issue-token CLI, and tests cannot drift.
+ *
+ * @param {string} cleartext
+ * @returns {string}
+ */
+export function hashToken(cleartext) {
+  if (typeof cleartext !== 'string' || cleartext.length === 0) {
+    throw new Error('hashToken: non-empty string required');
+  }
+  return crypto.createHash('sha256').update(cleartext).digest('hex');
+}
+
+/**
+ * Parse `?fingerprint=<12hex>&token=<bearer>` — or its prefix-less form —
+ * out of an `application_name` startup parameter.
+ *
+ * Returns `null` for any malformed input. Caller never inspects details
+ * beyond presence: the daemon emits a single `tcp_token_denied` audit
+ * event regardless of which validation step failed, to deny the peer
+ * any oracle that distinguishes "unknown fingerprint" from "wrong token".
+ *
+ * @param {string|undefined|null} applicationName
+ * @returns {{fingerprint: string, token: string} | null}
+ */
+export function parseTcpAuth(applicationName) {
+  if (typeof applicationName !== 'string' || applicationName.length === 0) return null;
+  if (applicationName.length > MAX_TOKEN_LEN + 64) return null;
+  const stripped = applicationName.startsWith('?') ? applicationName.slice(1) : applicationName;
+  const params = new Map();
+  for (const segment of stripped.split('&')) {
+    const eq = segment.indexOf('=');
+    if (eq <= 0) continue;
+    const key = segment.slice(0, eq);
+    const val = segment.slice(eq + 1);
+    if (key && val) params.set(key, val);
+  }
+  const fingerprint = params.get('fingerprint');
+  const token = params.get('token');
+  if (!fingerprint || !token) return null;
+  if (!FP_RE.test(fingerprint)) return null;
+  if (token.length === 0 || token.length > MAX_TOKEN_LEN) return null;
+  return { fingerprint, token };
+}
+
+/**
+ * Constant-time string compare. Bearer-token verification path uses this
+ * after sha256 to avoid leaking length-mismatch via timing.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function timingSafeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  if (a.length !== b.length) return false;
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  return crypto.timingSafeEqual(bufA, bufB);
+}