pgserve 1.2.0 → 2.0.1

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

package/tests/audit.test.js

@@ -0,0 +1,189 @@
+/**
+ * Tests for src/audit.js — JSONL writer with rotation + syslog target.
+ *
+ * Tests use temp dirs under /tmp; nothing touches the user's real
+ * `~/.pgserve/audit.log`. The syslog test stubs `logger` via PATH so we
+ * don't depend on (or pollute) the host's syslog daemon.
+ */
+
+import { test, expect, beforeEach, afterEach } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  audit,
+  configureAudit,
+  readAuditTarget,
+  AUDIT_EVENTS,
+  _internals,
+} from '../src/audit.js';
+
+let scratchDir;
+
+beforeEach(() => {
+  scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-audit-test-'));
+  configureAudit({
+    logFile: path.join(scratchDir, 'audit.log'),
+    target: 'file',
+  });
+});
+
+afterEach(() => {
+  try {
+    fs.rmSync(scratchDir, { recursive: true, force: true });
+  } catch { /* noop */ }
+});
+
+test('audit() appends a JSON line per event', () => {
+  audit(AUDIT_EVENTS.DB_CREATED, { fingerprint: 'abc123def456', db: 'app_demo_abc123def456' });
+  audit(AUDIT_EVENTS.CONNECTION_ROUTED, { fingerprint: 'abc123def456', peer_pid: 1234 });
+
+  const logFile = path.join(scratchDir, 'audit.log');
+  const lines = fs.readFileSync(logFile, 'utf8').trim().split('\n');
+  expect(lines.length).toBe(2);
+  const r1 = JSON.parse(lines[0]);
+  expect(r1.event).toBe('db_created');
+  expect(r1.fingerprint).toBe('abc123def456');
+  expect(typeof r1.ts).toBe('string');
+  expect(new Date(r1.ts).toString()).not.toBe('Invalid Date');
+
+  const r2 = JSON.parse(lines[1]);
+  expect(r2.event).toBe('connection_routed');
+  expect(r2.peer_pid).toBe(1234);
+});
+
+test('audit() refuses unknown events', () => {
+  expect(() => audit('definitely_not_a_real_event', {})).toThrow(/unknown event/);
+});
+
+test('audit() creates the parent directory if missing', () => {
+  const nested = path.join(scratchDir, 'nested', 'sub', 'audit.log');
+  audit(AUDIT_EVENTS.DB_CREATED, { fingerprint: 'a'.repeat(12) }, { logFile: nested });
+  expect(fs.existsSync(nested)).toBe(true);
+});
+
+test('all v2.0 event names are exported (incl. Group 6 tcp_*)', () => {
+  expect(Object.values(AUDIT_EVENTS).sort()).toEqual([
+    'connection_denied_fingerprint_mismatch',
+    'connection_routed',
+    'db_created',
+    'db_persist_honored',
+    'db_reaped_liveness',
+    'db_reaped_ttl',
+    'enforcement_kill_switch_used',
+    'tcp_token_denied',
+    'tcp_token_issued',
+    'tcp_token_used',
+  ]);
+});
+
+test('rotation kicks in once existing file crosses 50 MB', () => {
+  const logFile = path.join(scratchDir, 'audit.log');
+  // Use a sparse file to simulate a 50 MB log without writing 50 MB.
+  const fd = fs.openSync(logFile, 'w');
+  fs.ftruncateSync(fd, _internals.ROTATE_THRESHOLD_BYTES);
+  fs.closeSync(fd);
+
+  audit(AUDIT_EVENTS.DB_CREATED, { fingerprint: 'r'.repeat(12) });
+
+  // Original file rotated to .1, fresh file holds the new line.
+  expect(fs.existsSync(`${logFile}.1`)).toBe(true);
+  const fresh = fs.readFileSync(logFile, 'utf8');
+  expect(fresh.trim().split('\n').length).toBe(1);
+  expect(JSON.parse(fresh.trim()).event).toBe('db_created');
+
+  // The rotated file is the original 50 MB sparse file.
+  expect(fs.statSync(`${logFile}.1`).size).toBe(_internals.ROTATE_THRESHOLD_BYTES);
+});
+
+test('rotation cascades up to KEEP files and drops the eldest', () => {
+  const logFile = path.join(scratchDir, 'audit.log');
+  // Pre-populate audit.log.1 ... audit.log.5 with distinct markers.
+  for (let i = 1; i <= _internals.ROTATE_KEEP; i++) {
+    fs.writeFileSync(`${logFile}.${i}`, `slot-${i}\n`);
+  }
+  // And the live audit.log just under threshold.
+  const fd = fs.openSync(logFile, 'w');
+  fs.ftruncateSync(fd, _internals.ROTATE_THRESHOLD_BYTES);
+  fs.closeSync(fd);
+
+  audit(AUDIT_EVENTS.DB_CREATED, { fingerprint: 'q'.repeat(12) });
+
+  // .5 (was "slot-5") dropped; .4 → .5; .3 → .4; .2 → .3; .1 → .2; live → .1.
+  expect(fs.readFileSync(`${logFile}.5`, 'utf8').trim()).toBe('slot-4');
+  expect(fs.readFileSync(`${logFile}.4`, 'utf8').trim()).toBe('slot-3');
+  expect(fs.readFileSync(`${logFile}.3`, 'utf8').trim()).toBe('slot-2');
+  expect(fs.readFileSync(`${logFile}.2`, 'utf8').trim()).toBe('slot-1');
+  expect(fs.statSync(`${logFile}.1`).size).toBe(_internals.ROTATE_THRESHOLD_BYTES);
+});
+
+test('audit({target:"syslog"}) spawns logger -t pgserve-audit', async () => {
+  // Stub `logger` by prepending a temp shim to PATH.
+  const shimDir = path.join(scratchDir, 'shim');
+  fs.mkdirSync(shimDir, { recursive: true });
+  const marker = path.join(scratchDir, 'logger-calls.txt');
+  const shimPath = path.join(shimDir, 'logger');
+  fs.writeFileSync(
+    shimPath,
+    `#!/usr/bin/env bash
+# Capture argv to a marker file so the test can verify the spawn.
+printf '%s\\n' "$*" >> "${marker}"
+`,
+    { mode: 0o755 },
+  );
+
+  const oldPath = process.env.PATH;
+  process.env.PATH = `${shimDir}:${oldPath}`;
+  try {
+    audit(
+      AUDIT_EVENTS.CONNECTION_ROUTED,
+      { fingerprint: 's'.repeat(12) },
+      { target: 'syslog' },
+    );
+    // logger is spawned async; poll briefly for the marker.
+    const deadline = Date.now() + 2000;
+    while (!fs.existsSync(marker) && Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 25));
+    }
+    expect(fs.existsSync(marker)).toBe(true);
+    const contents = fs.readFileSync(marker, 'utf8');
+    expect(contents).toContain('-t pgserve-audit');
+    expect(contents).toContain('"event":"connection_routed"');
+  } finally {
+    process.env.PATH = oldPath;
+  }
+});
+
+test('audit({target:"syslog"}) swallows missing logger binary', () => {
+  // Point PATH at an empty dir → `logger` cannot be found → no throw.
+  const empty = path.join(scratchDir, 'empty');
+  fs.mkdirSync(empty);
+  const oldPath = process.env.PATH;
+  process.env.PATH = empty;
+  try {
+    expect(() =>
+      audit(
+        AUDIT_EVENTS.CONNECTION_ROUTED,
+        { fingerprint: 'z'.repeat(12) },
+        { target: 'syslog' },
+      ),
+    ).not.toThrow();
+  } finally {
+    process.env.PATH = oldPath;
+  }
+});
+
+test('readAuditTarget reads pgserve.audit.target from package.json', () => {
+  const pkgFile = path.join(scratchDir, 'package.json');
+  fs.writeFileSync(
+    pkgFile,
+    JSON.stringify({ name: 'demo', pgserve: { audit: { target: 'syslog' } } }),
+  );
+  expect(readAuditTarget(pkgFile)).toBe('syslog');
+
+  fs.writeFileSync(pkgFile, JSON.stringify({ name: 'demo' }));
+  expect(readAuditTarget(pkgFile)).toBe('file');
+
+  // Missing file → file (default).
+  expect(readAuditTarget(path.join(scratchDir, 'missing.json'))).toBe('file');
+});