pgserve 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to `pgserve` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 2.0.0 — Unreleased
+
+> The release date will replace "Unreleased" when the v2.0.0 release workflow
+> fires. The CHANGELOG is committed ahead of the release trigger so consumers
+> can review the migration plan before the artifact lands on npm.
+
+### Pin guidance (read this first)
+
+Existing v1 consumers should pin `pgserve@^1.x` in their `package.json` until
+they have completed the migration described below. v2 changes the default
+transport (Unix socket, no TCP), the identity model (kernel-rooted
+fingerprint), the database layout (one DB per fingerprint), and the daemon
+process model (singleton). A blind upgrade will break v1 connection strings.
+
+```jsonc
+// package.json — keep v1 until you migrate
+{
+  "dependencies": {
+    "pgserve": "^1.2.0"
+  }
+}
+```
+
+### Breaking changes
+
+- **TCP is no longer the default.** v1 bound `127.0.0.1:8432` for every
+  consumer. v2 binds a Unix control socket at
+  `${XDG_RUNTIME_DIR:-/tmp}/pgserve/control.sock` (mode `0600`, dir mode
+  `0700`) plus a `.s.PGSQL.5432` symlink so libpq clients connect with no
+  host/port/user/password. To keep a TCP listener, opt in explicitly with
+  `--listen <port>` (see "Compat TCP via --listen" in the README).
+- **Fingerprint enforcement is default-ON.** Each connecting peer is
+  identified via `SO_PEERCRED` + the resolved `package.json` `name`,
+  collapsed to a 12-hex fingerprint. The daemon refuses to route a peer
+  into a database that does not match its fingerprint with SQLSTATE
+  `28P01 invalid_authorization — database fingerprint mismatch`. The
+  emergency kill switch is `PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT=1`
+  (deprecated; the daemon emits a stderr warning at boot when the env var
+  is observed).
+- **Database-per-fingerprint isolation.** v1 served arbitrary database
+  names freely. v2 auto-creates `app_<sanitized-name>_<12hex>` for each
+  unique fingerprint on first connect; cross-fingerprint reads are denied.
+  `psql -l` will show one row per consumer rather than the shared pool
+  v1 produced. Monorepo rule: the root `package.json` `name` wins for all
+  packages under it.
+- **Singleton daemon via control socket.** v1 spun up a server per
+  invocation, leaving consumers to coordinate ports themselves. v2
+  enforces one daemon per host: a second `pgserve daemon` exits with
+  `already running, pid N`. Run it under PM2 or systemd (snippets in the
+  README) — there is no PM-managed multi-process mode anymore.
+- **GC sweep emits `db_reaped_ttl` and `db_reaped_liveness` audit events.**
+  Default lifecycle is now ephemeral: a database whose `liveness_pid` is
+  dead AND whose `last_connection_at` is older than 24h is dropped on the
+  next sweep (boot, hourly, sampled on-connect). To opt out, add
+  `pgserve.persist: true` to the consumer's `package.json` — flagged
+  databases are never reaped.
+
+### Migration guide
+
+1. **Connection strings** — drop credentials and the port; switch to the
+   socket form.
+
+   ```diff
+   - postgres://user:pass@localhost:5432/db
+   + postgres:///db?host=${XDG_RUNTIME_DIR:-/tmp}/pgserve
+   ```
+
+   Equivalently, for `psql`:
+
+   ```bash
+   psql -h "${XDG_RUNTIME_DIR:-/tmp}/pgserve" -d myapp
+   ```
+
+2. **Long-lived apps** — anything whose data needs to outlive a 24h idle
+   window (genie state stores, dashboards, anything with state worth
+   keeping) must declare persistence in its `package.json`:
+
+   ```jsonc
+   {
+     "name": "my-long-lived-app",
+     "pgserve": { "persist": true }
+   }
+   ```
+
+   Without this flag, the GC sweep will reap the database after the TTL
+   plus liveness check passes.
+
+3. **Need TCP?** Opt in with `--listen` and use issued tokens. TCP peers
+   cannot use `SO_PEERCRED`, so they must authenticate at connect time.
+
+   ```bash
+   pgserve daemon --listen :5432
+
+   # Issue a bearer token for a known fingerprint (printed once):
+   pgserve daemon issue-token --fingerprint <12hex>
+
+   # TCP clients pass the token via libpq application_name as
+   #   ?fingerprint=<hex>&token=<bearer>
+   # Revoke when done:
+   pgserve daemon revoke-token <token-id>
+   ```
+
+   Without `--listen`, no TCP port is bound — verify with
+   `ss -tlnp | grep -v pgserve` returning no pgserve rows.
+
+4. **Kill switch (emergency only).** If the fingerprint enforcement
+   denies a connection you cannot otherwise unblock, set
+   `PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT=1` for the daemon. The
+   bypassed connection emits an `enforcement_kill_switch_used` audit
+   event; the daemon logs a deprecation warning at boot whenever the
+   variable is observed. The kill switch will be removed in a future
+   major; treat it as a debugging tool, not a production setting.
+
+### New features (group references map to wish execution groups)
+
+- **Group 4 — Database-per-fingerprint + enforcement + kill switch.**
+  Auto-create `app_<name>_<12hex>` on first connect, deny
+  cross-fingerprint reads with SQLSTATE `28P01`, audit event
+  `connection_denied_fingerprint_mismatch`. Sanitizer collapses
+  non-`[a-z0-9]` runs to `_`, lowercases, truncates to 30 chars to keep
+  the resulting DB name ≤ 63 chars.
+- **Group 5 — Lifecycle + persist flag + GC sweep.** Three-layer
+  lifecycle: liveness (peer pid alive), 24h TTL since last connection,
+  and `pgserve.persist: true` override. Sweep runs at daemon boot,
+  hourly, and sampled on-connect at 1/N where N = max(1, dbCount/10).
+  Reaped databases emit `db_reaped_ttl` or `db_reaped_liveness` audit
+  events; the on-connect sweep does not block accept latency past 50 ms
+  P99.
+- **Group 6 — `--listen` opt-in TCP + token auth.** Daemon CLI accepts
+  `--listen [host:]port` (repeatable). Tokens issued via
+  `pgserve daemon issue-token --fingerprint <hex>`, hashed at rest into
+  `pgserve_meta.allowed_tokens`, verified with constant-time compare.
+  New audit events: `tcp_token_issued`, `tcp_token_used`,
+  `tcp_token_denied`. Without `--listen`, no TCP port is bound.
+
+### Compatibility
+
+- Node.js >= 18 (unchanged).
+- Linux x64, macOS ARM64/x64, Windows x64. Windows uses named pipes for
+  the control socket; PM2/systemd snippets are Linux-first.
+- `--ram` (Linux/WSL2 `/dev/shm`), `--pgvector`, `--sync-to`, and the
+  rest of the v1 runtime flags continue to work unchanged.
+
+---

package/README.md

@@ -10,7 +10,7 @@
     <a href="https://discord.gg/xcW8c7fF3R"><img src="https://img.shields.io/discord/1095114867012292758?style=flat-square&color=00D9FF&label=discord" alt="Discord"></a>
   </p>
 
-  <p><em>Zero config, auto-provision databases, unlimited concurrent connections. Just works.</em></p>
+  <p><em>npx pgserve and it just works, no credentials needed. Zero config, auto-provision databases, unlimited concurrent connections.</em></p>
 
   <p>
     <a href="#-quick-start">Quick Start</a> •
@@ -35,6 +35,8 @@ Connect from any PostgreSQL client — databases auto-create on first connection
 psql postgresql://localhost:8432/myapp
 ```
 
+> Note: v2 default is the Unix socket — see [Daemon mode](#daemon-mode). The TCP form above is the v1 compat path.
+
 <br>
 
 ## Features
@@ -168,6 +170,189 @@ pgserve --sync-to "postgresql://user:pass@db.example.com:5432/prod"
 
 <br>
 
+## Daemon mode
+
+`pgserve@2` ships a singleton daemon that binds a Unix control socket
+inside `$XDG_RUNTIME_DIR/pgserve` (fallback `/tmp/pgserve`). One daemon
+per host serves every consumer on the box — no port conflicts, no
+credentials, kernel-rooted identity. Run it under PM2 or systemd so it
+restarts automatically.
+
+```bash
+# Foreground (for debugging)
+pgserve daemon
+
+# Stop a running daemon
+pgserve daemon stop
+```
+
+A second `pgserve daemon` invocation while the first is running exits with
+`already running, pid N`. A daemon killed with `kill -9` leaves an orphan
+PID file + socket; the next `pgserve daemon` boot detects the dead pid and
+cleans both up automatically.
+
+Connect from any libpq client (no host/port/user/password required —
+the daemon authenticates via SO_PEERCRED on accept):
+
+```bash
+psql -h "${XDG_RUNTIME_DIR:-/tmp}/pgserve" -d myapp
+# or via connection URI
+psql "postgresql:///myapp?host=${XDG_RUNTIME_DIR:-/tmp}/pgserve"
+```
+
+### Supervised by PM2
+
+`ecosystem.config.cjs` snippet:
+
+```javascript
+module.exports = {
+  apps: [{
+    name: 'pgserve',
+    script: 'pgserve',
+    args: 'daemon',
+    autorestart: true,
+    max_memory_restart: '1G',
+    env: { XDG_RUNTIME_DIR: '/run/user/1000' },
+  }],
+};
+```
+
+```bash
+pm2 start ecosystem.config.cjs && pm2 save
+```
+
+### Supervised by systemd
+
+`/etc/systemd/user/pgserve.service`:
+
+```ini
+[Unit]
+Description=pgserve daemon
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/env npx pgserve daemon
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable for the current user:
+
+```bash
+systemctl --user enable --now pgserve
+journalctl --user -u pgserve -f
+```
+
+The systemd user unit inherits `XDG_RUNTIME_DIR` automatically; the daemon
+binds `${XDG_RUNTIME_DIR}/pgserve/control.sock` (mode 0600, dir mode 0700)
+plus a `.s.PGSQL.5432` symlink so off-the-shelf PostgreSQL clients connect
+without further configuration.
+
+<br>
+
+## Fingerprint isolation
+
+Each consumer is identified by a **kernel-rooted fingerprint** derived from
+the peer's `SO_PEERCRED` plus the resolved `package.json` `name`, collapsed
+to 12 hex chars. The daemon auto-creates one database per fingerprint —
+`app_<sanitized-name>_<12hex>` — and refuses to route a peer into any other
+database with SQLSTATE `28P01 invalid_authorization — database fingerprint
+mismatch`.
+
+```bash
+# What `psql -l` shows on a host with three consumers:
+$ psql -h "${XDG_RUNTIME_DIR:-/tmp}/pgserve" -l
+        Name           |  Owner   | ...
+-----------------------+----------+----
+ app_genie_a1b2c3d4e5f6 | postgres | ...
+ app_brain_4f3e2d1c0b9a | postgres | ...
+ app_omni_9876543210ab  | postgres | ...
+```
+
+**Monorepo rule:** the **root** `package.json` `name` wins. Every workspace
+under it shares one fingerprint and one database — sub-packages do **not**
+get their own. If you need separate isolation, run them from separate
+checkouts.
+
+**Sanitization:** non-`[a-z0-9]` runs collapse to `_`, lowercased, truncated
+to 30 chars so the final DB name stays within PostgreSQL's 63-char limit.
+A name like `@scope/foo bar` becomes `_scope_foo_bar`.
+
+**Emergency kill switch:** `PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT=1`
+disables enforcement for the daemon process. Use it as a debugging tool
+only — every bypassed connection emits an `enforcement_kill_switch_used`
+audit event and the daemon logs a deprecation warning at boot.
+
+<br>
+
+## Long-running apps: `pgserve.persist`
+
+Default lifecycle is **ephemeral**: a database whose `liveness_pid` is dead
+AND whose `last_connection_at` is older than 24h is dropped on the next GC
+sweep (boot, hourly, sampled on-connect). Reaped DBs emit
+`db_reaped_ttl` or `db_reaped_liveness` audit events.
+
+If your app holds state worth keeping past 24h of idle — genie's wish/agent
+store, internal dashboards, anything you'd be unhappy to lose — declare
+persistence in `package.json`:
+
+```jsonc
+{
+  "name": "my-long-lived-app",
+  "pgserve": { "persist": true }
+}
+```
+
+Persisted databases are **never** reaped, regardless of liveness or TTL.
+Dev workloads with long debug cycles do not normally need this — any new
+connection slides the TTL window forward. Reach for `pgserve.persist` when
+the app is genuinely long-lived (production daemon, dashboard, durable
+agent state), not just for convenience.
+
+<br>
+
+## Compat TCP via `--listen`
+
+TCP is **off by default** in v2. Bring it back only when you need it
+(Kubernetes pods, remote sync, legacy clients that cannot speak Unix
+sockets) by opting in:
+
+```bash
+pgserve daemon --listen :5432
+# Repeatable for multiple binds:
+pgserve daemon --listen :5432 --listen 0.0.0.0:5433
+```
+
+TCP peers cannot use `SO_PEERCRED`, so they **must** authenticate at
+connect time. Issue a bearer token bound to a known fingerprint:
+
+```bash
+# Prints the token ONCE; the daemon stores only its hash.
+pgserve daemon issue-token --fingerprint a1b2c3d4e5f6
+
+# TCP client passes it via libpq application_name:
+#   ?fingerprint=a1b2c3d4e5f6&token=<bearer>
+
+# Revoke when done:
+pgserve daemon revoke-token <token-id>
+```
+
+Audit events: `tcp_token_issued`, `tcp_token_used`, `tcp_token_denied`.
+Tokens are verified with constant-time compare. Without a valid token a
+TCP connection is refused — there is no anonymous TCP path.
+
+Verify no port is bound when `--listen` is **not** set:
+
+```bash
+ss -tlnp | grep pgserve   # no rows expected
+```
+
+<br>
+
 ## API
 
 ```javascript

package/bin/pglite-server.js

@@ -12,6 +12,20 @@ import path from 'path';
 import os from 'os';
 import { startMultiTenantServer } from '../src/index.js';
 import { startClusterServer } from '../src/cluster.js';
+import {
+  PgserveDaemon,
+  stopDaemon,
+  resolveControlSocketDir,
+  resolveControlSocketPath,
+} from '../src/daemon.js';
+import { createAdminClient, readAdminDiscovery } from '../src/admin-client.js';
+import {
+  ensureMetaSchema,
+  addAllowedToken,
+  revokeAllowedToken,
+} from '../src/control-db.js';
+import { mintToken } from '../src/tokens.js';
+import { audit, AUDIT_EVENTS } from '../src/audit.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -25,9 +39,247 @@ process.on('uncaughtException', (error) => {
   process.exit(1);
 });
 
-// Parse CLI arguments
+// Parse CLI arguments — `pgserve daemon [stop]` is dispatched before the
+// classic `pgserve [options]` parser so daemon-mode flags do not collide
+// with router flags.
 const args = process.argv.slice(2);
 
+if (args[0] === 'daemon') {
+  await runDaemonSubcommand(args.slice(1));
+}
+
+async function runDaemonSubcommand(daemonArgs) {
+  if (daemonArgs[0] === 'stop') {
+    const result = stopDaemon();
+    if (result.stopped) {
+      console.log(`pgserve daemon stopped (pid ${result.pid})`);
+      process.exit(0);
+    }
+    if (result.reason === 'no-pid-file') {
+      console.error('pgserve daemon: no PID file found — is the daemon running?');
+      process.exit(1);
+    }
+    if (result.reason === 'stale-pid' || result.reason === 'invalid-pid-file') {
+      console.log(`pgserve daemon: cleaned up stale lock (pid ${result.pid ?? '?'})`);
+      process.exit(0);
+    }
+    if (result.reason === 'timeout') {
+      console.error(`pgserve daemon: pid ${result.pid} did not exit within timeout`);
+      process.exit(1);
+    }
+    console.error(`pgserve daemon stop: ${result.reason}${result.error ? ` (${result.error})` : ''}`);
+    process.exit(1);
+  }
+
+  if (daemonArgs[0] === 'issue-token') {
+    await runIssueTokenSubcommand(daemonArgs.slice(1));
+    return;
+  }
+  if (daemonArgs[0] === 'revoke-token') {
+    await runRevokeTokenSubcommand(daemonArgs.slice(1));
+    return;
+  }
+
+  // `pgserve daemon` (long-running)
+  const opts = parseDaemonArgs(daemonArgs);
+  const daemon = new PgserveDaemon(opts);
+  try {
+    await daemon.start();
+  } catch (err) {
+    if (err.code === 'EALREADYRUNNING') {
+      console.error(`pgserve daemon: already running, pid ${err.pid}`);
+      process.exit(1);
+    }
+    console.error('pgserve daemon: failed to start:', err.message);
+    process.exit(1);
+  }
+  const dir = resolveControlSocketDir();
+  console.log(`
+pgserve daemon — singleton mode
+
+  Control socket: ${resolveControlSocketPath(dir)}
+  PID lock:       ${path.join(dir, 'pgserve.pid')}
+  PG socket:      ${daemon.pgManager.getSocketPath() || '(TCP fallback)'}
+
+  Connect:        psql 'host=${dir} dbname=mydb'
+
+  Press Ctrl+C or send SIGTERM to stop.
+`);
+
+  // Daemon installs its own SIGTERM/SIGINT handlers; just wait forever.
+  await new Promise(() => {});
+}
+
+function parseDaemonArgs(daemonArgs) {
+  const opts = {
+    baseDir: null,
+    useRam: false,
+    logLevel: 'info',
+    autoProvision: true,
+    tcpListens: [],
+  };
+  for (let i = 0; i < daemonArgs.length; i++) {
+    const arg = daemonArgs[i];
+    switch (arg) {
+      case '--data':
+      case '-d':
+        opts.baseDir = daemonArgs[++i];
+        break;
+      case '--ram':
+        opts.useRam = true;
+        break;
+      case '--log':
+      case '-l':
+        opts.logLevel = daemonArgs[++i];
+        break;
+      case '--no-provision':
+        opts.autoProvision = false;
+        break;
+      case '--listen':
+        opts.tcpListens.push(daemonArgs[++i]);
+        break;
+      case '--help':
+        console.log(`
+pgserve daemon — singleton control-socket mode
+
+USAGE:
+  pgserve daemon [options]
+  pgserve daemon stop
+  pgserve daemon issue-token --fingerprint <hex>
+  pgserve daemon revoke-token <id>
+
+OPTIONS:
+  --data <path>   Persistent data directory (default: in-memory)
+  --ram           Use /dev/shm storage (Linux only)
+  --log <level>   Log level: error|warn|info|debug (default: info)
+  --no-provision  Disable auto-provisioning of databases
+  --listen [host:]port  Bind opt-in TCP listener (repeatable)
+  --help          Show this help
+
+The daemon binds $XDG_RUNTIME_DIR/pgserve/control.sock (fallback /tmp/pgserve/control.sock).
+A second invocation while the first is running exits with "already running".
+
+TCP peers (--listen) MUST authenticate via libpq application_name shaped
+"?fingerprint=<12hex>&token=<bearer>". Issue tokens with
+"pgserve daemon issue-token --fingerprint <hex>". Revoke with
+"pgserve daemon revoke-token <id>".
+`);
+        process.exit(0);
+        // falls through (unreachable)
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Unknown daemon option: ${arg}`);
+          process.exit(1);
+        }
+    }
+  }
+  return opts;
+}
+
+async function runIssueTokenSubcommand(args) {
+  let fingerprint = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--fingerprint') fingerprint = args[++i];
+    else if (arg === '--help') {
+      console.log(`
+pgserve daemon issue-token --fingerprint <12hex>
+
+Issues a fresh bearer token for an existing fingerprint. Prints the token
+to stdout exactly once; only the sha256 hash is persisted. Use the printed
+value in libpq application_name shaped "?fingerprint=<hex>&token=<bearer>".
+`);
+      process.exit(0);
+    } else {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    }
+  }
+  if (!fingerprint || !/^[0-9a-f]{12}$/.test(fingerprint)) {
+    console.error('issue-token: --fingerprint <12hex> required');
+    process.exit(1);
+  }
+
+  let admin;
+  try {
+    const dir = resolveControlSocketDir();
+    const disc = readAdminDiscovery(dir);
+    admin = await createAdminClient({ socketDir: disc.socketDir, port: disc.port });
+  } catch (err) {
+    console.error('issue-token: cannot reach running daemon admin socket:', err.message);
+    console.error('Hint: start the daemon first with `pgserve daemon`.');
+    process.exit(1);
+  }
+
+  try {
+    await ensureMetaSchema(admin);
+    const { id, cleartext, hash } = mintToken();
+    const result = await addAllowedToken(admin, {
+      fingerprint,
+      tokenId: id,
+      tokenHash: hash,
+    });
+    audit(AUDIT_EVENTS.TCP_TOKEN_ISSUED, {
+      fingerprint,
+      token_id: id,
+      database: result.databaseName,
+    });
+    console.log('Token issued. Save the bearer value below — it will not be shown again:');
+    console.log('');
+    console.log(`  id:          ${id}`);
+    console.log(`  fingerprint: ${fingerprint}`);
+    console.log(`  database:    ${result.databaseName}`);
+    console.log(`  token:       ${cleartext}`);
+    console.log('');
+    console.log('Use as libpq application_name:');
+    console.log(`  application_name='?fingerprint=${fingerprint}&token=${cleartext}'`);
+    process.exit(0);
+  } catch (err) {
+    if (err.code === 'EUNKNOWNFINGERPRINT') {
+      console.error(`issue-token: fingerprint ${fingerprint} not provisioned yet.`);
+      console.error('Connect once via Unix socket so pgserve creates the database first.');
+      process.exit(2);
+    }
+    console.error('issue-token failed:', err.message);
+    process.exit(1);
+  } finally {
+    try { await admin.end(); } catch { /* swallow */ }
+  }
+}
+
+async function runRevokeTokenSubcommand(args) {
+  if (args.length === 0 || args[0] === '--help') {
+    console.log('Usage: pgserve daemon revoke-token <id>');
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const tokenId = args[0];
+
+  let admin;
+  try {
+    const dir = resolveControlSocketDir();
+    const disc = readAdminDiscovery(dir);
+    admin = await createAdminClient({ socketDir: disc.socketDir, port: disc.port });
+  } catch (err) {
+    console.error('revoke-token: cannot reach running daemon admin socket:', err.message);
+    process.exit(1);
+  }
+
+  try {
+    const affected = await revokeAllowedToken(admin, tokenId);
+    if (affected === 0) {
+      console.error(`revoke-token: no token with id ${tokenId} found`);
+      process.exit(2);
+    }
+    console.log(`Token ${tokenId} revoked (affected ${affected} row${affected === 1 ? '' : 's'})`);
+    process.exit(0);
+  } catch (err) {
+    console.error('revoke-token failed:', err.message);
+    process.exit(1);
+  } finally {
+    try { await admin.end(); } catch { /* swallow */ }
+  }
+}
+
 /**
  * Print usage help
  */

package/eslint.config.js

@@ -17,6 +17,8 @@ export default [
         clearTimeout: 'readonly',
         setInterval: 'readonly',
         clearInterval: 'readonly',
+        setImmediate: 'readonly',
+        clearImmediate: 'readonly',
         URL: 'readonly',
         __dirname: 'readonly',
         // Bun globals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",