pgserve 1.1.10 → 2.0.0

package/Makefile

@@ -28,15 +28,13 @@ help: ## Show this help
 	@echo "$(CYAN)Embedded PostgreSQL server with multi-tenant support$(RESET)"
 	@echo ""
 	@echo "$(BOLD)Quick Commands:$(RESET)"
-	@echo "  $(PURPLE)release-rc$(RESET)     Create RC release locally"
-	@echo "  $(PURPLE)release-stable$(RESET) Promote RC to stable"
 	@echo "  $(PURPLE)test-local$(RESET)     Test server locally"
 	@echo "  $(PURPLE)pm2-start$(RESET)      Start server with PM2"
 	@echo ""
-	@echo "$(BOLD)CI/CD Workflow:$(RESET)"
-	@echo "  1. Create PR with changes"
-	@echo "  2. Add 'rc' label → auto-publishes to npm @next"
-	@echo "  3. Add 'stable' label → promotes to npm @latest"
+	@echo "$(BOLD)Releasing:$(RESET)"
+	@echo "  Manual: bump locally with 'npm version patch|minor|major', PR to main."
+	@echo "  Bot:    'gh workflow run release.yml -f bump=patch' (or minor/major)."
+	@echo "  Skip:   any commit message starting with [skip ci] is ignored."
 	@echo ""
 	@echo "$(BOLD)Build Executables:$(RESET)"
 	@echo "  $(PURPLE)build$(RESET)          Build for current platform"
@@ -211,35 +209,19 @@ clean-dist: ## Clean build artifacts
 	@echo "$(GREEN)✅ Dist cleaned!$(RESET)"
 
 # ==========================================
-# 🚀 CI/CD Release (Automated)
+# 🚀 Releasing
 # ==========================================
-# Releases are triggered by GitHub Actions when PRs are merged with labels:
-#   - 'rc' label → Creates RC release (1.0.8 → 1.0.9-rc.1)
-#   - 'stable' label → Promotes RC to stable (1.0.9-rc.1 → 1.0.9)
+# Releases are driven by .github/workflows/release.yml on push to main.
 #
-# See .github/workflows/release.yml for full automation.
+#   Manual:  bump locally with `npm version patch|minor|major`, commit, PR
+#            to main. Merge -> release fires automatically.
+#   Bot:     `gh workflow run release.yml -f bump=patch` (or minor/major).
+#            The bot bumps, tags, builds binaries, publishes to npm via OIDC.
+#   Skip:    any commit message starting with [skip ci] is ignored.
+#
+# There are no Make targets for releases — versioning is intentionally
+# centralized in CI to keep the local-vs-prod workflow paths identical.
 # ==========================================
-.PHONY: release-rc release-stable release-dry
-
-release-rc: ## Create RC release locally (for testing)
-	@echo "$(CYAN)🔢 Creating RC release...$(RESET)"
-	@node scripts/release.cjs --action bump-rc
-	@echo ""
-	@echo "$(GREEN)✅ RC release created!$(RESET)"
-	@echo "$(YELLOW)Push with: git push && git push --tags$(RESET)"
-
-release-stable: ## Promote RC to stable locally (for testing)
-	@echo "$(CYAN)🎉 Promoting to stable...$(RESET)"
-	@node scripts/release.cjs --action promote
-	@echo ""
-	@echo "$(GREEN)✅ Stable release created!$(RESET)"
-	@echo "$(YELLOW)Push with: git push && git push --tags$(RESET)"
-
-release-dry: ## Dry-run release (no changes)
-	@echo "$(CYAN)🔍 Dry-run release...$(RESET)"
-	@node scripts/release.cjs --action bump-rc --dry-run
-	@echo ""
-	@echo "$(GREEN)✅ Dry-run complete (no changes made)$(RESET)"
 
 # ==========================================
 # 📦 Manual Publish (Deprecated)
@@ -254,19 +236,14 @@ publish-dry: pre-publish ## Dry-run publish (test without actually publishing)
 	@echo "$(GREEN)✅ Dry-run successful!$(RESET)"
 	@echo "$(YELLOW)To actually publish, run: make publish$(RESET)"
 
-publish: ## ⚠️ [DEPRECATED] Use PR labels instead
+publish: ## ⚠️ [DEPRECATED] Releases run from CI on push to main
 	@echo ""
 	@echo "$(YELLOW)$(BOLD)╔═══════════════════════════════════════════════════════════════╗$(RESET)"
 	@echo "$(YELLOW)$(BOLD)║  ⚠️  Manual publish is DEPRECATED                            ║$(RESET)"
 	@echo "$(YELLOW)$(BOLD)║                                                               ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║  Use PR labels for automated releases:                       ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║    • Add 'rc' label → RC release (npm @next)                 ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║    • Add 'stable' label → Promote to stable (npm @latest)   ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║                                                               ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║  Local testing:                                              ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║    make release-rc      Create RC locally                    ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║    make release-stable  Promote locally                      ║$(RESET)"
-	@echo "$(YELLOW)$(BOLD)║    make release-dry     Dry-run (no changes)                 ║$(RESET)"
+	@echo "$(YELLOW)$(BOLD)║  Releases are driven by .github/workflows/release.yml:       ║$(RESET)"
+	@echo "$(YELLOW)$(BOLD)║    Manual: npm version patch|minor|major, commit, PR to main ║$(RESET)"
+	@echo "$(YELLOW)$(BOLD)║    Bot:    gh workflow run release.yml -f bump=patch         ║$(RESET)"
 	@echo "$(YELLOW)$(BOLD)╚═══════════════════════════════════════════════════════════════╝$(RESET)"
 	@echo ""
 

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/SECURITY.md

@@ -0,0 +1,109 @@
+# Security Policy
+
+`pgserve` is maintained by [Automagik](https://automagik.dev). We take the security of this package seriously and appreciate responsible disclosure from the community.
+
+---
+
+## Reporting a Vulnerability
+
+**Please do not open public issues for security reports.**
+
+Send private reports to one of the following channels:
+
+| Channel | Address | Best for |
+|---------|---------|----------|
+| Security email | `privacidade@namastex.ai` | Anything security-related, including coordinated disclosure |
+| DPO (privacy + security officer) | `dpo@khal.ai` | Privacy, LGPD, data protection concerns |
+| Private GitHub advisory | [Report via GitHub](https://github.com/namastexlabs/pgserve/security/advisories/new) | Preferred for CVE assignment and coordinated release |
+
+**PGP** available on request.
+
+### Response SLA
+
+- Acknowledgement: **within 2 business hours** (UTC-3).
+- Initial triage and severity assessment: **within 24 hours**.
+- Fix or mitigation plan: **within 7 days** for critical/high severity.
+- Public disclosure: coordinated with reporter, typically within 30 days of fix.
+
+We will credit reporters publicly (with their permission) in the released advisory.
+
+---
+
+## Supported Versions
+
+| Version line | Status |
+|--------------|--------|
+| `1.1.10` and later clean releases | ✅ Supported — current |
+| `1.1.11` – `1.1.14` | ❌ **COMPROMISED — do not use** |
+| `1.1.0` – `1.1.9` | ⚠️ Legacy — security patches only |
+| `1.0.x` and earlier | ❌ End of life |
+
+Always install from the current stable line. Pin explicit versions in your `package.json` and avoid `latest` for supply-chain sensitive packages.
+
+---
+
+## Past Incidents
+
+### 2026-04 — CanisterWorm supply-chain compromise
+
+Between 2026-04-21 (~22:14 UTC) and 2026-04-22 (~14:00 UTC), versions `1.1.11`, `1.1.12`, `1.1.13`, and `1.1.14` were published to npm by a threat actor after a developer GitHub OAuth token was exfiltrated. The malicious versions contained a `TeamPCP` payload in `scripts/check-env.js` that executed via `postinstall` to harvest local credentials.
+
+- **Exposure window:** ~16 hours
+- **Detection-to-containment:** under 20 hours
+- **Current status:** malicious versions `npm unpublish`-ed and no longer installable
+
+**If you installed versions `1.1.11` – `1.1.14` between April 21–22, 2026, assume your machine is compromised.** Follow the remediation guide linked below.
+
+**Resources:**
+- 📖 [Full incident response manual](https://github.com/namastexlabs/genie-dpo/blob/main/knowledge/canisterworm-incident-response.md)
+- 🌐 [Public advisory (English)](https://automagik.dev/security)
+- 🌐 [Aviso público (Português)](https://automagik.dev/seguranca)
+- 🛡️ [GitHub Security Advisories](https://github.com/namastexlabs/pgserve/security/advisories) for this repository
+
+A full public post-mortem will be published within 30 days of containment.
+
+---
+
+## Acknowledgments
+
+We thank the researchers and organizations that identified and tracked this incident:
+
+- [**Socket Research Team**](https://socket.dev/blog/namastex-npm-packages-compromised-canisterworm) — primary discovery and continued tracking at [socket.dev/supply-chain-attacks/canistersprawl](https://socket.dev/supply-chain-attacks/canistersprawl).
+- **Endor Labs**, **Kodem Security**, **BleepingComputer**, **The Register**, **CSO Online**, **GBHackers**, **Cybersecurity News** — for coverage, analysis, and technical breakdowns that helped defenders respond quickly.
+
+We also thank the Automagik team that ran the end-to-end response during the incident window, and the broader open-source community whose scrutiny, tools, and unfiltered feedback keep this ecosystem healthy. We will keep earning it.
+
+---
+
+## Our Commitments
+
+Effective 2026-04-23, all `pgserve` releases are governed by:
+
+- **Provenance attestation** — every publication is signed with `npm --provenance` and verifiable via Sigstore.
+- **OIDC trusted publishing** — migrating to GitHub Actions OIDC publish, eliminating long-lived npm tokens. (in progress)
+- **Mandatory 2FA** on every maintainer account with publish rights.
+- **Environment protection** — production publishes require manual approval from a second maintainer.
+- **Quarterly token audit** — scope and permission review.
+- **External pentest** — scheduled ahead of the original roadmap.
+
+---
+
+## Hardening Recommendations for Consumers
+
+- Pin explicit versions, not `latest`: `"pgserve": "1.1.10"`.
+- Use `npm ci` in CI. It enforces lockfile-based installs by default.
+- Evaluate `--ignore-scripts` per-package for untrusted dependencies. The current `pgserve` release does not require any lifecycle script to function.
+- Verify package provenance: `npm view pgserve --json | jq '.dist.attestations'`.
+- Monitor advisories: subscribe to GitHub security alerts for this repository.
+
+---
+
+## Contact
+
+- **Security & incidents:** `privacidade@namastex.ai`
+- **Data Protection Officer (DPO):** Cezar Vasconcelos — `dpo@khal.ai`
+- **Security disclosure page:** [automagik.dev/security](https://automagik.dev/security)
+
+Namastex Labs Serviços em Tecnologia Ltda · CNPJ 46.156.854/0001-62
+
+*Last updated: 2026-04-23 · v1.0*

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