pgserve 1.1.10 → 2.0.0

package/src/router.js

@@ -12,8 +12,17 @@
  * - 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';
 import { PostgresManager } from './postgres.js';
 import { SyncManager } from './sync.js';
 import { RestoreManager } from './restore.js';
@@ -28,6 +37,14 @@ const SSL_REQUEST_CODE = 80877103;
 const GSSAPI_REQUEST_CODE = 80877104;
 const CANCEL_REQUEST_CODE = 80877102;
 
+// Maximum size for the pre-handshake startup buffer. A legitimate PG
+// startup message is at most a few hundred bytes; anything approaching
+// 1 MiB is a runaway client or an attempted buffer-growth DoS. Bound
+// this to stop the proxy from accumulating gigabytes of orphaned data
+// when a client sends garbage and the handshake never completes.
+// (Issue #18 root cause #2 — unbounded growth at state.buffer.)
+const MAX_STARTUP_BUFFER_SIZE = 1024 * 1024; // 1 MiB
+
 /**
  * Attempt to write a pending buffer to a target socket.
  * Returns remaining unwritten bytes, or null if fully flushed.
@@ -231,6 +248,12 @@ export class MultiTenantRouter extends EventEmitter {
       pgSocket: null,
       dbName: null,
       handshakeComplete: false,
+      // startupInProgress serializes processStartupMessage() against async
+      // reentrancy — without it, every data event fired while the previous
+      // processStartupMessage() is still awaiting createDatabase() would
+      // launch another async task on the same state, racing to overwrite
+      // state.pgSocket and leaking the losers (issue #18 root cause #1).
+      startupInProgress: false,
       pendingToPg: null,
       pendingToClient: null
     });
@@ -249,9 +272,13 @@ export class MultiTenantRouter extends EventEmitter {
 
     // If handshake complete, forward to PostgreSQL
     if (state.handshakeComplete && state.pgSocket) {
-      // If there's already pending data, append to it
+      // If there's already pending data, append and re-pause.
+      // (Re-pause is defensive: client should already be paused from the
+      //  earlier partial-write, but kernel-buffered data can still arrive
+      //  before the pause takes effect — issue #18 root cause #3.)
       if (state.pendingToPg) {
         state.pendingToPg = Buffer.concat([state.pendingToPg, data]);
+        socket.pause();
         return;
       }
       const written = state.pgSocket.write(data);
@@ -263,7 +290,20 @@ export class MultiTenantRouter extends EventEmitter {
       return;
     }
 
-    // Buffer data for startup message parsing
+    // Buffer data for startup message parsing.
+    // Bound the pre-handshake buffer so a client that never completes its
+    // startup (or sends garbage) cannot grow state.buffer without limit —
+    // the 74 GiB VmSize in the production deadlock report traces to this
+    // path (issue #18 root cause #2).
+    const incomingSize = state.buffer ? state.buffer.length + data.byteLength : data.byteLength;
+    if (incomingSize > MAX_STARTUP_BUFFER_SIZE) {
+      this.logger.warn(
+        { incomingSize, limit: MAX_STARTUP_BUFFER_SIZE },
+        'Pre-handshake buffer exceeded limit — closing connection'
+      );
+      socket.end();
+      return;
+    }
     if (state.buffer) {
       state.buffer = Buffer.concat([state.buffer, data]);
     } else {
@@ -275,9 +315,17 @@ export class MultiTenantRouter extends EventEmitter {
   }
 
   /**
-   * Process PostgreSQL startup message and establish proxy connection
+   * Process PostgreSQL startup message and establish proxy connection.
+   *
+   * Guarded against async reentrancy: multiple data events arriving while
+   * the first processStartupMessage() is still awaiting createDatabase()
+   * or Bun.connect() must not launch concurrent tasks on the same state —
+   * they would race to assign state.pgSocket, leaking the losing sockets
+   * and double-writing the startup message (issue #18 root cause #1).
    */
   async processStartupMessage(socket, state) {
+    if (state.startupInProgress) return;
+
     const buffer = state.buffer;
     if (!buffer || buffer.length < 8) return; // Need at least length + protocol
 
@@ -315,6 +363,11 @@ export class MultiTenantRouter extends EventEmitter {
     const dbName = extractDatabaseName(startupMessage);
     state.dbName = dbName;
 
+    // Claim the reentrancy guard BEFORE the first await so subsequent data
+    // events (buffered into state.buffer by handleSocketData) cannot launch
+    // a second async task on the same state.
+    state.startupInProgress = true;
+
     try {
       // Auto-provision database if needed
       if (this.autoProvision) {
@@ -328,9 +381,13 @@ export class MultiTenantRouter extends EventEmitter {
       // Shared handler for pgSocket (used by both unix and TCP paths)
       const pgHandler = {
         data(_pgSocket, pgData) {
-          // Forward PostgreSQL response to client with backpressure
+          // Forward PostgreSQL response to client with backpressure.
+          // Re-pause defensively when pendingToClient already exists —
+          // kernel-buffered PG data can arrive before the earlier pause()
+          // takes effect (issue #18 root cause #3).
           if (state.pendingToClient) {
             state.pendingToClient = Buffer.concat([state.pendingToClient, pgData]);
+            _pgSocket.pause();
             return;
           }
           const written = socket.write(pgData);
@@ -362,9 +419,18 @@ export class MultiTenantRouter extends EventEmitter {
         }
       };
 
-      if (socketPath) {
+      // Safety net for issue #24: if socketPath points to a directory that was
+      // cleaned up (e.g. pgManager was stopped+started, or the PG subprocess
+      // exited unexpectedly and socketDir was reset to null but a stale cached
+      // path is still hanging around), fall back to TCP instead of Bun.connect
+      // hanging on a missing unix socket.
+      const useUnix = socketPath && fs.existsSync(socketPath);
+      if (useUnix) {
         state.pgSocket = await Bun.connect({ unix: socketPath, socket: pgHandler });
       } else {
+        if (socketPath && !useUnix) {
+          this.logger.warn({ socketPath, dbName }, 'Unix socket path stale — falling back to TCP');
+        }
         state.pgSocket = await Bun.connect({ hostname: '127.0.0.1', port: this.pgPort, socket: pgHandler });
       }
 
@@ -373,6 +439,13 @@ export class MultiTenantRouter extends EventEmitter {
       this.logger.error({ dbName, err: error }, 'Connection error');
       socket.end();
       this.emit('connection-error', { error, dbName });
+    } finally {
+      // Release the reentrancy guard whether handshake succeeded or not.
+      // If it succeeded, handshakeComplete is now true and further data
+      // events will bypass processStartupMessage anyway (handleSocketData
+      // takes the handshakeComplete path). If it failed, socket.end()
+      // has been called and the connection is tearing down.
+      state.startupInProgress = false;
     }
   }
 

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