pgserve 1.2.0 → 2.0.0

package/src/admin-client.js

@@ -0,0 +1,171 @@
+/**
+ * Admin DB client — small Bun.SQL wrapper exposing the `{query, end}`
+ * surface that `src/control-db.js` expects.
+ *
+ * The daemon and the `pgserve daemon issue-token / revoke-token` CLI
+ * subcommands both need a privileged connection to the underlying
+ * Postgres instance owned by `PostgresManager`. The pg npm module is
+ * a devDependency only (it backs the test harness); rather than promote
+ * it to runtime we wrap Bun.SQL — which is shipped with the runtime —
+ * in the parameterised-query interface control-db.js documents.
+ *
+ * Connection target:
+ *   - Local Unix socket when `socketDir` is provided (the daemon's
+ *     hot path) — drops the bytes onto the kernel-local socket.
+ *   - TCP fallback when `socketDir` is null (e.g. CI hosts without
+ *     the embedded socket directory present).
+ *
+ * The CLI side reads the daemon's discovery file at
+ * `${controlSocketDir}/admin.json` to learn `{socketDir, port}`.
+ */
+
+import { SQL } from 'bun';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * @param {object} args
+ * @param {string|null} [args.socketDir] — accepted for parity with the
+ *   embedded-postgres callers but unused; Bun.SQL's startup auth path
+ *   does not currently traverse `pg_hba.conf` Unix-socket trust rules
+ *   against `embedded-postgres`, so we always go TCP for admin work.
+ *   Keeping the parameter avoids a churning call-site signature.
+ * @param {string} [args.host='127.0.0.1']
+ * @param {number} args.port
+ * @param {string} [args.database='postgres']
+ * @param {string} [args.user='postgres']
+ * @param {string} [args.password='postgres']
+ * @param {number} [args.max=2]
+ * @returns {Promise<{query: (text: string, params?: any[]) => Promise<{rows: any[], rowCount: number}>, end: () => Promise<void>, sql: any}>}
+ */
+export async function createAdminClient({
+  socketDir: _socketDir = null,
+  host = '127.0.0.1',
+  port,
+  database = 'postgres',
+  user = 'postgres',
+  password = 'postgres',
+  max = 2,
+} = {}) {
+  if (typeof port !== 'number') throw new Error('createAdminClient: port required');
+  const sql = new SQL({
+    hostname: host,
+    port,
+    database,
+    username: user,
+    password,
+    max,
+    // TODO #38: investigate GC perf for 240-orphan sweep on shared CI runners;
+    // bumped 10s→30s during Felipe deadline 2026-04-29 to unblock pgserve v2.0 ship.
+    idleTimeout: 30,
+  });
+  // Light probe so a misconfigured daemon fails loudly here rather than at
+  // first query.
+  await sql`SELECT 1`;
+  return {
+    sql,
+    async query(text, params = []) {
+      // control-db.js is written for the pg npm module's contract, which
+      // requires JSON-stringified payloads bound to JSONB parameters.
+      // Bun.SQL goes the other way: it stringifies JS objects when they
+      // hit JSONB columns, but a JS string headed for `::jsonb` is sent
+      // as a JSON string literal (i.e. `"\"..."\"` rather than the array
+      // it represents). Bridge the impedance mismatch here so the same
+      // call sites work against either driver.
+      const adapted = params.map(coerceJsonbParam);
+      const rows = await sql.unsafe(text, adapted);
+      // Bun returns an Array of plain objects with `count` set on it; turn
+      // JSONB columns back into JS values so control-db.js's parseTokens
+      // sees the array-of-objects shape it would receive from pg.
+      const out = Array.from(rows).map(decodeJsonColumns);
+      return { rows: out, rowCount: rows.count ?? rows.length ?? 0 };
+    },
+    async end() {
+      try { await sql.close(); } catch { /* swallow */ }
+    },
+  };
+}
+
+/**
+ * Strings shaped like a JSON array or object are unwrapped so Bun.SQL's
+ * automatic JSONB serialiser sees the JS value (not a quoted JSON string).
+ * Anything else is passed through untouched. This mirrors what node-pg
+ * does implicitly when the column type is JSONB.
+ */
+function coerceJsonbParam(p) {
+  if (typeof p !== 'string') return p;
+  const trimmed = p.trim();
+  if (trimmed.length === 0) return p;
+  const first = trimmed[0];
+  if (first !== '[' && first !== '{') return p;
+  try {
+    return JSON.parse(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Bun.SQL returns JSONB values as the JSON text rather than parsed JS.
+ * Re-parse the obvious cases so callers expecting node-pg's auto-decoded
+ * shape get arrays/objects.
+ */
+function decodeJsonColumns(row) {
+  const out = {};
+  for (const key of Object.keys(row)) {
+    const v = row[key];
+    if (typeof v === 'string' && (v.startsWith('[') || v.startsWith('{'))) {
+      try { out[key] = JSON.parse(v); } catch { out[key] = v; }
+    } else {
+      out[key] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Daemon-side: write a small JSON file that issue-token / revoke-token
+ * subcommands read to find the admin socket.
+ *
+ * @param {object} args
+ * @param {string} args.controlSocketDir
+ * @param {string|null} args.socketDir — PG socket directory (nullable on Windows)
+ * @param {number} args.port
+ * @returns {string} the absolute path to the discovery file
+ */
+export function writeAdminDiscovery({ controlSocketDir, socketDir, port }) {
+  const file = path.join(controlSocketDir, 'admin.json');
+  const payload = {
+    socketDir,
+    port,
+    host: socketDir ? null : '127.0.0.1',
+    pid: process.pid,
+    written_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(file, JSON.stringify(payload), { mode: 0o600 });
+  return file;
+}
+
+/**
+ * CLI-side: read the daemon's discovery file.
+ *
+ * @param {string} controlSocketDir
+ * @returns {{socketDir: string|null, port: number, host: string|null}}
+ */
+export function readAdminDiscovery(controlSocketDir) {
+  const file = path.join(controlSocketDir, 'admin.json');
+  const raw = fs.readFileSync(file, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * CLI-side: best-effort cleanup at daemon shutdown.
+ *
+ * @param {string} controlSocketDir
+ */
+export function removeAdminDiscovery(controlSocketDir) {
+  const file = path.join(controlSocketDir, 'admin.json');
+  try { fs.unlinkSync(file); } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+}

package/src/audit.js

@@ -0,0 +1,168 @@
+/**
+ * pgserve audit log — JSONL writer with in-process rotation + syslog tier.
+ *
+ * Tier 1 (default): `~/.pgserve/audit.log`, rotated 50 MB × 5 files.
+ * Tier 2 (opt-in):  local syslog via `logger -t pgserve-audit`, one spawn per event.
+ * Tier 3 (HTTP webhook): deferred to v2.1.
+ *
+ * Configuration source-of-truth is the active package.json's
+ * `pgserve.audit.target` field; the daemon (Group 3) resolves it per peer
+ * and threads the value through `audit(event, fields, { target })`.
+ *
+ * The event names defined for v2.0 (one row per audit() call):
+ *   db_created
+ *   db_reaped_ttl
+ *   db_reaped_liveness
+ *   db_persist_honored
+ *   connection_routed
+ *   connection_denied_fingerprint_mismatch
+ *   enforcement_kill_switch_used
+ *   tcp_token_issued
+ *   tcp_token_used
+ *   tcp_token_denied
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawn } from 'child_process';
+
+export const AUDIT_EVENTS = Object.freeze({
+  DB_CREATED: 'db_created',
+  DB_REAPED_TTL: 'db_reaped_ttl',
+  DB_REAPED_LIVENESS: 'db_reaped_liveness',
+  DB_PERSIST_HONORED: 'db_persist_honored',
+  CONNECTION_ROUTED: 'connection_routed',
+  CONNECTION_DENIED_FINGERPRINT_MISMATCH: 'connection_denied_fingerprint_mismatch',
+  ENFORCEMENT_KILL_SWITCH_USED: 'enforcement_kill_switch_used',
+  TCP_TOKEN_ISSUED: 'tcp_token_issued',
+  TCP_TOKEN_USED: 'tcp_token_used',
+  TCP_TOKEN_DENIED: 'tcp_token_denied',
+});
+
+const VALID_EVENTS = new Set(Object.values(AUDIT_EVENTS));
+
+const ROTATE_THRESHOLD_BYTES = 50 * 1024 * 1024; // 50 MB
+const ROTATE_KEEP = 5;
+
+let DEFAULT_LOG_DIR = path.join(os.homedir(), '.pgserve');
+let DEFAULT_LOG_PATH = path.join(DEFAULT_LOG_DIR, 'audit.log');
+let DEFAULT_TARGET = process.env.PGSERVE_AUDIT_TARGET || 'file';
+
+/**
+ * Override the default log path. Used by tests and by the daemon if it
+ * needs to redirect audit output (e.g. when XDG_DATA_HOME is set).
+ *
+ * @param {{logFile?: string, target?: 'file'|'syslog'}} cfg
+ */
+export function configureAudit(cfg = {}) {
+  if (cfg.logFile) {
+    DEFAULT_LOG_PATH = cfg.logFile;
+    DEFAULT_LOG_DIR = path.dirname(cfg.logFile);
+  }
+  if (cfg.target) {
+    DEFAULT_TARGET = cfg.target;
+  }
+}
+
+/**
+ * Read pgserve.audit.target from a package.json (returns 'file' if absent).
+ * Group 3 calls this per-peer once it has resolved the peer's package.json.
+ *
+ * @param {string} packageJsonPath
+ * @returns {'file'|'syslog'}
+ */
+export function readAuditTarget(packageJsonPath) {
+  try {
+    const raw = fs.readFileSync(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    const target = pkg?.pgserve?.audit?.target;
+    if (target === 'syslog') return 'syslog';
+    return 'file';
+  } catch {
+    return 'file';
+  }
+}
+
+/**
+ * Write one audit event.
+ *
+ * @param {string} event — one of AUDIT_EVENTS values
+ * @param {Record<string, unknown>} [fields] — event-specific payload
+ * @param {object} [opts]
+ * @param {'file'|'syslog'} [opts.target]
+ * @param {string} [opts.logFile]
+ */
+export function audit(event, fields = {}, opts = {}) {
+  if (!VALID_EVENTS.has(event)) {
+    throw new Error(`audit: unknown event "${event}". Allowed: ${[...VALID_EVENTS].join(', ')}`);
+  }
+  const record = {
+    ts: new Date().toISOString(),
+    event,
+    ...fields,
+  };
+  const line = JSON.stringify(record);
+  const target = opts.target || DEFAULT_TARGET;
+
+  if (target === 'syslog') {
+    writeSyslog(line);
+    return;
+  }
+  writeFile(line, opts.logFile || DEFAULT_LOG_PATH);
+}
+
+function writeFile(line, logFile) {
+  const dir = path.dirname(logFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  rotateIfNeeded(logFile, Buffer.byteLength(line, 'utf8') + 1 /* newline */);
+  fs.appendFileSync(logFile, line + '\n', { mode: 0o600 });
+}
+
+function rotateIfNeeded(logFile, incomingBytes) {
+  let size = 0;
+  try {
+    size = fs.statSync(logFile).size;
+  } catch {
+    return; // file does not exist yet
+  }
+  if (size + incomingBytes <= ROTATE_THRESHOLD_BYTES) return;
+
+  // Cascade .N → .(N+1), drop the eldest.
+  const oldest = `${logFile}.${ROTATE_KEEP}`;
+  if (fs.existsSync(oldest)) {
+    fs.unlinkSync(oldest);
+  }
+  for (let i = ROTATE_KEEP - 1; i >= 1; i--) {
+    const src = `${logFile}.${i}`;
+    const dst = `${logFile}.${i + 1}`;
+    if (fs.existsSync(src)) fs.renameSync(src, dst);
+  }
+  fs.renameSync(logFile, `${logFile}.1`);
+}
+
+function writeSyslog(line) {
+  // logger -t <tag> is POSIX-standard; spawn detached, do not block.
+  // Stderr/stdout discarded — audit must never throw at call sites.
+  try {
+    const child = spawn('logger', ['-t', 'pgserve-audit', line], {
+      stdio: 'ignore',
+      detached: false,
+    });
+    child.on('error', () => { /* logger missing — swallow */ });
+  } catch {
+    // ENOENT / EACCES — swallow; audit must never break the daemon.
+  }
+}
+
+/**
+ * Internal: expose rotation constants so tests can drive coverage cleanly
+ * without depending on actual 50 MB writes.
+ */
+export const _internals = Object.freeze({
+  ROTATE_THRESHOLD_BYTES,
+  ROTATE_KEEP,
+  rotateIfNeeded,
+});

package/src/control-db.js

@@ -0,0 +1,313 @@
+/**
+ * pgserve control DB — `pgserve_meta` schema + accessors.
+ *
+ * The pgserve daemon owns a control database (the "admin DB"). This module
+ * defines the `pgserve_meta` table that records every user database the
+ * daemon provisions per peer fingerprint, plus the small set of accessors
+ * the daemon (Wave 2+) and GC sweep (Group 5) call against it.
+ *
+ * Schema (see DESIGN.md §9 + Group 6 token migration):
+ *   database_name      TEXT PRIMARY KEY
+ *   fingerprint        TEXT NOT NULL          -- 12 hex chars from sha256
+ *   peer_uid           INTEGER NOT NULL
+ *   package_realpath   TEXT                   -- NULL for script fallback
+ *   created_at         TIMESTAMPTZ DEFAULT now()
+ *   last_connection_at TIMESTAMPTZ DEFAULT now()
+ *   liveness_pid       INTEGER
+ *   persist            BOOLEAN DEFAULT false
+ *   allowed_tokens     JSONB DEFAULT '[]'     -- Group 6: bearer tokens for TCP path
+ *
+ * Each `allowed_tokens` entry is `{id, hash, issued_at}` where `hash` is the
+ * sha256 of the bearer token (the cleartext is shown to the operator once
+ * during `pgserve daemon issue-token` and never persisted).
+ *
+ * Client contract: any object exposing
+ *   `query(text: string, params?: unknown[]) => Promise<{ rows: object[] }>`
+ * (matches `pg.Client` / `pg.Pool` directly; trivial to wrap Bun.SQL).
+ */
+
+import { timingSafeEqual } from './tokens.js';
+
+const REAPABLE_QUERY = `
+  SELECT database_name, fingerprint, last_connection_at, liveness_pid, persist
+  FROM pgserve_meta
+  WHERE persist = false
+  ORDER BY last_connection_at ASC
+`;
+
+/**
+ * Create the `pgserve_meta` table if it does not already exist.
+ * Safe to call repeatedly — used at daemon boot and in tests.
+ *
+ * @param {{query: Function}} client
+ * @returns {Promise<void>}
+ */
+export async function ensureMetaSchema(client) {
+  await client.query(`
+    CREATE TABLE IF NOT EXISTS pgserve_meta (
+      database_name      TEXT PRIMARY KEY,
+      fingerprint        TEXT NOT NULL,
+      peer_uid           INTEGER NOT NULL,
+      package_realpath   TEXT,
+      created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
+      last_connection_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      liveness_pid       INTEGER,
+      persist            BOOLEAN NOT NULL DEFAULT false,
+      allowed_tokens     JSONB NOT NULL DEFAULT '[]'::jsonb
+    )
+  `);
+  // Group 6 migration: existing v2-pre-tcp installs predate allowed_tokens.
+  // ADD COLUMN IF NOT EXISTS lets the first daemon boot after upgrade fold
+  // the new column into a populated table without operator intervention.
+  await client.query(`
+    ALTER TABLE pgserve_meta
+    ADD COLUMN IF NOT EXISTS allowed_tokens JSONB NOT NULL DEFAULT '[]'::jsonb
+  `);
+  await client.query(`
+    CREATE INDEX IF NOT EXISTS pgserve_meta_fingerprint_idx
+    ON pgserve_meta (fingerprint)
+  `);
+}
+
+/**
+ * Insert (or upsert) a row marking a freshly-created user DB.
+ *
+ * @param {{query: Function}} client
+ * @param {object} row
+ * @param {string} row.databaseName
+ * @param {string} row.fingerprint
+ * @param {number} row.peerUid
+ * @param {string|null} [row.packageRealpath]
+ * @param {number|null} [row.livenessPid]
+ * @param {boolean} [row.persist]
+ */
+export async function recordDbCreated(client, {
+  databaseName,
+  fingerprint,
+  peerUid,
+  packageRealpath = null,
+  livenessPid = null,
+  persist = false,
+}) {
+  if (!databaseName) throw new Error('recordDbCreated: databaseName required');
+  if (!fingerprint) throw new Error('recordDbCreated: fingerprint required');
+  if (typeof peerUid !== 'number') throw new Error('recordDbCreated: peerUid must be number');
+
+  await client.query(
+    `
+    INSERT INTO pgserve_meta
+      (database_name, fingerprint, peer_uid, package_realpath, liveness_pid, persist)
+    VALUES ($1, $2, $3, $4, $5, $6)
+    ON CONFLICT (database_name) DO UPDATE SET
+      fingerprint        = EXCLUDED.fingerprint,
+      peer_uid           = EXCLUDED.peer_uid,
+      package_realpath   = EXCLUDED.package_realpath,
+      liveness_pid       = EXCLUDED.liveness_pid,
+      persist            = EXCLUDED.persist,
+      last_connection_at = now()
+    `,
+    [databaseName, fingerprint, peerUid, packageRealpath, livenessPid, persist],
+  );
+}
+
+/**
+ * Slide the connection window: bump last_connection_at and refresh
+ * liveness_pid on every accept for an existing fingerprint.
+ *
+ * @param {{query: Function}} client
+ * @param {{databaseName: string, livenessPid?: number|null}} args
+ */
+export async function touchLastConnection(client, { databaseName, livenessPid = null }) {
+  if (!databaseName) throw new Error('touchLastConnection: databaseName required');
+  await client.query(
+    `
+    UPDATE pgserve_meta
+    SET last_connection_at = now(),
+        liveness_pid       = $2
+    WHERE database_name = $1
+    `,
+    [databaseName, livenessPid],
+  );
+}
+
+/**
+ * Set the persist flag for a database (true = exempt from GC).
+ *
+ * @param {{query: Function}} client
+ * @param {string} databaseName
+ * @param {boolean} value
+ */
+export async function markPersist(client, databaseName, value) {
+  if (!databaseName) throw new Error('markPersist: databaseName required');
+  await client.query(
+    `UPDATE pgserve_meta SET persist = $2 WHERE database_name = $1`,
+    [databaseName, !!value],
+  );
+}
+
+/**
+ * Async iterator over candidate DBs for the GC sweep.
+ * Skips persist=true rows entirely (they are never reaped).
+ *
+ * Group 5 consumes this and applies its liveness/TTL policy.
+ *
+ * @param {{query: Function}} client
+ * @param {{now?: Date}} [opts] — `now` accepted for caller symmetry; the
+ *   policy decision (TTL elapsed?) lives in Group 5, not here.
+ * @returns {AsyncIterable<{
+ *   databaseName: string,
+ *   fingerprint: string,
+ *   lastConnectionAt: Date,
+ *   livenessPid: number|null,
+ *   persist: boolean,
+ * }>}
+ */
+export async function* forEachReapable(client, _opts = {}) {
+  const result = await client.query(REAPABLE_QUERY);
+  for (const row of result.rows) {
+    yield {
+      databaseName: row.database_name,
+      fingerprint: row.fingerprint,
+      lastConnectionAt: row.last_connection_at,
+      livenessPid: row.liveness_pid,
+      persist: row.persist,
+    };
+  }
+}
+
+/**
+ * Delete a row after the user DB has been DROPped. Group 5 helper.
+ *
+ * @param {{query: Function}} client
+ * @param {string} databaseName
+ */
+export async function deleteMetaRow(client, databaseName) {
+  await client.query(`DELETE FROM pgserve_meta WHERE database_name = $1`, [databaseName]);
+}
+
+// ---------------------------------------------------------------------------
+// Group 6: TCP bearer-token CRUD
+//
+// `allowed_tokens` is a JSONB array on pgserve_meta. Each entry is shaped
+// `{id, hash, issued_at}` where `hash` is sha256 of the cleartext bearer
+// token. Tokens are scoped to the `database_name` row's `fingerprint`; a
+// fingerprint without a row cannot have tokens issued (the peer must have
+// connected over the Unix socket at least once so its DB exists).
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up the metadata row for a fingerprint. Returns null if the fingerprint
+ * has not yet been provisioned (the peer never connected via Unix socket).
+ *
+ * @param {{query: Function}} client
+ * @param {string} fingerprint — 12 hex chars
+ * @returns {Promise<{databaseName: string, fingerprint: string, peerUid: number, allowedTokens: Array<{id: string, hash: string, issued_at: string}>} | null>}
+ */
+export async function findRowByFingerprint(client, fingerprint) {
+  if (!fingerprint) throw new Error('findRowByFingerprint: fingerprint required');
+  const r = await client.query(
+    `SELECT database_name, fingerprint, peer_uid, allowed_tokens
+     FROM pgserve_meta WHERE fingerprint = $1 LIMIT 1`,
+    [fingerprint],
+  );
+  if (r.rows.length === 0) return null;
+  const row = r.rows[0];
+  return {
+    databaseName: row.database_name,
+    fingerprint: row.fingerprint,
+    peerUid: row.peer_uid,
+    allowedTokens: parseTokens(row.allowed_tokens),
+  };
+}
+
+function parseTokens(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append a hashed bearer token to a fingerprint's allowed list.
+ *
+ * @param {{query: Function}} client
+ * @param {{fingerprint: string, tokenId: string, tokenHash: string}} args
+ * @returns {Promise<{databaseName: string}>}
+ * @throws if the fingerprint has no pgserve_meta row
+ */
+export async function addAllowedToken(client, { fingerprint, tokenId, tokenHash }) {
+  if (!fingerprint) throw new Error('addAllowedToken: fingerprint required');
+  if (!tokenId) throw new Error('addAllowedToken: tokenId required');
+  if (!tokenHash) throw new Error('addAllowedToken: tokenHash required');
+
+  const row = await findRowByFingerprint(client, fingerprint);
+  if (!row) {
+    const err = new Error(
+      `addAllowedToken: no pgserve_meta row for fingerprint ${fingerprint}; ` +
+      `peer must connect once via Unix socket before tokens can be issued`,
+    );
+    err.code = 'EUNKNOWNFINGERPRINT';
+    throw err;
+  }
+
+  const entry = {
+    id: tokenId,
+    hash: tokenHash,
+    issued_at: new Date().toISOString(),
+  };
+  await client.query(
+    `UPDATE pgserve_meta
+     SET allowed_tokens = allowed_tokens || $2::jsonb
+     WHERE database_name = $1`,
+    [row.databaseName, JSON.stringify([entry])],
+  );
+  return { databaseName: row.databaseName };
+}
+
+/**
+ * Remove a token by its id from any fingerprint's allowed list. Returns the
+ * number of rows affected.
+ *
+ * @param {{query: Function}} client
+ * @param {string} tokenId
+ * @returns {Promise<number>}
+ */
+export async function revokeAllowedToken(client, tokenId) {
+  if (!tokenId) throw new Error('revokeAllowedToken: tokenId required');
+  // jsonb_path_query_array would be cleaner but isn't on every PG; the array
+  // filter via SELECT/UPDATE works on any version >= 12.
+  const r = await client.query(
+    `UPDATE pgserve_meta
+     SET allowed_tokens = COALESCE((
+       SELECT jsonb_agg(elem)
+       FROM jsonb_array_elements(allowed_tokens) elem
+       WHERE elem->>'id' <> $1
+     ), '[]'::jsonb)
+     WHERE allowed_tokens @> jsonb_build_array(jsonb_build_object('id', $1::text))`,
+    [tokenId],
+  );
+  return r.rowCount ?? r.rows?.length ?? 0;
+}
+
+/**
+ * Verify a presented bearer-token hash against a fingerprint's allowed list.
+ * Returns the matched token id (so audit events can attribute the connection)
+ * plus the resolved database name on success, or null if the token is unknown.
+ *
+ * @param {{query: Function}} client
+ * @param {{fingerprint: string, tokenHash: string}} args
+ * @returns {Promise<{tokenId: string, databaseName: string} | null>}
+ */
+export async function verifyToken(client, { fingerprint, tokenHash }) {
+  if (!fingerprint) throw new Error('verifyToken: fingerprint required');
+  if (!tokenHash) throw new Error('verifyToken: tokenHash required');
+  const row = await findRowByFingerprint(client, fingerprint);
+  if (!row) return null;
+  const match = row.allowedTokens.find((t) => timingSafeEqual(t.hash, tokenHash));
+  if (!match) return null;
+  return { tokenId: match.id, databaseName: row.databaseName };
+}