pgserve 1.2.0 → 2.0.1

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/Makefile

@@ -79,13 +79,13 @@ bench: ## Run benchmarks
 .PHONY: test-local
 test-local: ## Test server locally
 	@echo "$(CYAN)🧪 Testing server...$(RESET)"
-	@./bin/pglite-server.js start ./data/test-local --port 12050 --log info &
+	@./bin/postgres-server.js start ./data/test-local --port 12050 --log info &
 	@TESTPID=$$!; \
 	sleep 3; \
-	./bin/pglite-server.js list; \
-	./bin/pglite-server.js health --port 12050; \
+	./bin/postgres-server.js list; \
+	./bin/postgres-server.js health --port 12050; \
 	kill $$TESTPID 2>/dev/null || true; \
-	./bin/pglite-server.js cleanup
+	./bin/postgres-server.js cleanup
 	@echo "$(GREEN)✅ Server test passed!$(RESET)"
 
 # ==========================================
@@ -152,7 +152,7 @@ check-version: ## Check if version tag exists
 
 check-files: ## Check required files exist
 	@echo "$(CYAN)🔍 Checking required files...$(RESET)"
-	@for file in package.json README.md LICENSE src/index.js bin/pglite-server.js; do \
+	@for file in package.json README.md LICENSE src/index.js bin/postgres-server.js; do \
 		if [ ! -f "$$file" ]; then \
 			echo "$(RED)❌ Missing required file: $$file$(RESET)"; \
 			exit 1; \
@@ -172,26 +172,26 @@ $(DIST_DIR):
 
 build: $(DIST_DIR) ## Build standalone executable for current platform
 	@echo "$(CYAN)🔨 Building standalone executable...$(RESET)"
-	@bun build --compile bin/pglite-server.js --outfile $(DIST_DIR)/pgserve
+	@bun build --compile bin/postgres-server.js --outfile $(DIST_DIR)/pgserve
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve$(RESET)"
 
 build-linux: $(DIST_DIR) ## Build for Linux (x64 + arm64)
 	@echo "$(CYAN)🐧 Building for Linux...$(RESET)"
-	@bun build --compile --target=bun-linux-x64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-linux-x64
-	@bun build --compile --target=bun-linux-arm64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-linux-arm64
+	@bun build --compile --target=bun-linux-x64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-linux-x64
+	@bun build --compile --target=bun-linux-arm64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-linux-arm64
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-linux-x64$(RESET)"
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-linux-arm64$(RESET)"
 
 build-macos: $(DIST_DIR) ## Build for macOS (x64 + arm64)
 	@echo "$(CYAN)🍎 Building for macOS...$(RESET)"
-	@bun build --compile --target=bun-darwin-x64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-darwin-x64
-	@bun build --compile --target=bun-darwin-arm64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-darwin-arm64
+	@bun build --compile --target=bun-darwin-x64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-darwin-x64
+	@bun build --compile --target=bun-darwin-arm64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-darwin-arm64
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-darwin-x64$(RESET)"
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-darwin-arm64$(RESET)"
 
 build-windows: $(DIST_DIR) ## Build for Windows (x64)
 	@echo "$(CYAN)🪟 Building for Windows...$(RESET)"
-	@bun build --compile --target=bun-windows-x64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-windows-x64.exe
+	@bun build --compile --target=bun-windows-x64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-windows-x64.exe
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-windows-x64.exe$(RESET)"
 
 build-all: build-linux build-macos build-windows ## Build for all platforms
@@ -254,7 +254,7 @@ publish: ## ⚠️ [DEPRECATED] Releases run from CI on push to main
 clean: ## Clean generated files
 	@echo "$(CYAN)🧹 Cleaning...$(RESET)"
 	@rm -rf data/test-* data/genieos-local
-	@./bin/pglite-server.js cleanup
+	@./bin/postgres-server.js cleanup
 	@echo "$(GREEN)✅ Cleaned!$(RESET)"
 
 clean-all: clean ## Deep clean (including node_modules)

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,8 +170,212 @@ 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
 
+Daemon-first apps can let the first caller install/start the singleton and
+then connect through the Unix socket. The daemon derives the app identity
+from kernel peer credentials and routes it to that app's signed fingerprint
+database.
+
+```javascript
+import { daemonClientOptions, ensureDaemon } from 'pgserve';
+import postgres from 'postgres';
+
+await ensureDaemon({
+  dataDir: `${process.env.HOME}/.pgserve/data`,
+  logLevel: 'warn',
+});
+
+const sql = postgres(daemonClientOptions());
+await sql`SELECT current_database()`;
+```
+
+The classic TCP router API remains available for explicit v1-compatible
+embedded servers:
+
 ```javascript
 import { startMultiTenantServer } from 'pgserve';
 
@@ -325,10 +531,10 @@ CREATE EXTENSION IF NOT EXISTS vector;
   <tr>
     <th>Scenario</th>
     <th>SQLite</th>
-    <th>PGlite</th>
     <th>PostgreSQL</th>
-    <th>pgserve</th>
-    <th>pgserve --ram</th>
+    <th>pgserve 1.2.0</th>
+    <th>pgserve v2</th>
+    <th>pgserve v2 --ram</th>
   </tr>
   <tr>
     <td><b>Concurrent Writes</b> (10 agents)</td>
@@ -361,10 +567,10 @@ CREATE EXTENSION IF NOT EXISTS vector;
 <table>
   <tr>
     <th>Metric</th>
-    <th>PGlite</th>
     <th>PostgreSQL</th>
-    <th>pgserve</th>
-    <th>pgserve --ram</th>
+    <th>pgserve 1.2.0</th>
+    <th>pgserve v2</th>
+    <th>pgserve v2 --ram</th>
   </tr>
   <tr>
     <td><b>Vector INSERT</b> (1000 × 1536-dim)</td>
@@ -413,7 +619,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
     <td>117</td>
   </tr>
   <tr>
-    <td>PGlite</td>
+    <td>pgserve 1.2.0</td>
     <td>305</td>
     <td>65</td>
     <td>100%</td>
@@ -431,7 +637,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
     <td>1,067</td>
   </tr>
   <tr>
-    <td>pgserve</td>
+    <td>pgserve v2</td>
     <td>2,145</td>
     <td>149</td>
     <td>100%</td>
@@ -440,7 +646,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
     <td>1,347</td>
   </tr>
   <tr>
-    <td><b>pgserve --ram</b></td>
+    <td><b>pgserve v2 --ram</b></td>
     <td><b>3,541</b></td>
     <td><b>381</b></td>
     <td><b>100%</b></td>

package/bin/pgserve-wrapper.cjs

@@ -61,19 +61,19 @@ if (!bunPath) {
 // then exits instantly with:
 //   Error: Bun's postinstall script was not run.
 //
-// pglite-server.js's TCP readiness poll can't distinguish this from a slow
+// postgres-server.js's TCP readiness poll can't distinguish this from a slow
 // startup, so users see a confusing 30s timeout. Detect the specific error
 // here, attempt the documented self-heal once (`node install.js`), and retry.
 // If self-heal also fails, surface the real error instead of hanging later.
 ensureBunHealthy(bunPath);
 
-const scriptPath = path.join(__dirname, 'pglite-server.js');
+const scriptPath = path.join(__dirname, 'postgres-server.js');
 
 /**
  * Verify the selected bun binary can execute. If it fails with the known
  * "postinstall script was not run" signature, attempt a one-shot repair via
  * the bun npm package's install.js. Throws (with a useful message) rather
- * than letting pglite-server.js hang on the TCP readiness poll for 30s.
+ * than letting postgres-server.js hang on the TCP readiness poll for 30s.
  */
 function ensureBunHealthy(bunExe) {
   const probe = probeBun(bunExe);