pgserve 1.1.10 → 1.2.0

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/package.json

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

package/src/postgres.js

@@ -444,8 +444,20 @@ export class PostgresManager {
 
   /**
    * Start the embedded PostgreSQL instance
+   *
+   * Re-entry guard: if a previous start() left `this.process` or stale state
+   * behind, refuse silently rather than leaking another socketDir/databaseDir.
+   * Callers must call stop() first if they want to restart.
    */
   async start() {
+    if (this.process) {
+      this.logger?.warn(
+        { pid: this.process.pid, socketDir: this.socketDir },
+        'PostgresManager.start() called while already started — returning existing instance'
+      );
+      return this;
+    }
+
     // Get binary paths (may extract bundled binaries on first run)
     this.binaries = await getBinaryPaths();
 
@@ -773,12 +785,33 @@ export class PostgresManager {
       readStream(this.process.stdout);
 
       // Handle process exit
+      //
+      // When the postgres subprocess exits (normal stop OR crash), we must
+      // null `this.process` AND `this.socketDir`/`this.databaseDir` so that
+      // subsequent `getSocketPath()` calls do not return a path to a directory
+      // that no longer exists. This is the issue #24 root cause: the router
+      // was receiving stale socketPaths pointing to cleaned-up tmp dirs.
+      //
+      // NOTE: we do NOT null socketDir here if `stop()` is in flight, because
+      // stop() already handles cleanup+null. We only need to self-heal when
+      // the exit is unexpected (external kill, crash, OOM).
       this.process.exited.then((code) => {
         processExited = true;
         if (!started) {
           reject(new Error(`PostgreSQL exited with code ${code} before starting: ${startupOutput}`));
         }
         this.process = null;
+        // On unexpected exit (not via stop()), reset cached paths so that
+        // getSocketPath() returns null and callers can fall back to TCP
+        // or force a fresh start().
+        if (!this._stopping) {
+          this.socketDir = null;
+          this.databaseDir = null;
+          this.logger?.warn(
+            { code },
+            'PostgreSQL subprocess exited unexpectedly — socketDir/databaseDir reset'
+          );
+        }
       });
 
       // Method 1: TCP connection polling (preferred, works on Linux/macOS)
@@ -1294,8 +1327,19 @@ export class PostgresManager {
 
   /**
    * Stop the PostgreSQL instance
+   *
+   * Cleanup order matters: we null `this.socketDir`/`this.databaseDir` AFTER
+   * the rmSync so any concurrent `getSocketPath()` call either sees the old
+   * path (while it still exists) or null (after cleanup) — never a path
+   * pointing to a deleted directory.
+   *
+   * The `_stopping` flag tells the process.exited handler to NOT redundantly
+   * null the paths (avoids a race where start() called immediately after
+   * stop() sees nulls that stop() was about to set anyway).
    */
   async stop() {
+    this._stopping = true;
+
     // Close admin pool first (Bun.sql)
     if (this.adminPool) {
       await this.adminPool.close();
@@ -1340,6 +1384,16 @@ export class PostgresManager {
         }
       }
     }
+
+    // Reset cached paths UNCONDITIONALLY after cleanup so getSocketPath()
+    // returns null for anyone still holding a reference to this instance.
+    // This is the core fix for issue #24.
+    this.socketDir = null;
+    if (!this.persistent) {
+      this.databaseDir = null;
+    }
+    this.createdDatabases.clear();
+    this._stopping = false;
   }
 
   /**

package/src/router.js

@@ -14,6 +14,7 @@
  * PERFORMANCE: Uses Bun.listen() and Bun.connect() for 2-3x throughput improvement
  */
 
+import fs from 'fs';
 import { PostgresManager } from './postgres.js';
 import { SyncManager } from './sync.js';
 import { RestoreManager } from './restore.js';
@@ -28,6 +29,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 +240,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 +264,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 +282,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 +307,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 +355,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 +373,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 +411,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 +431,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/tests/multi-tenant.test.js

@@ -161,6 +161,170 @@ test('Multi-tenant router - multiple databases isolated', async () => {
   cleanup();
 });
 
+test('Router - pre-handshake buffer is bounded (issue #18 root cause #2)', async () => {
+  // Regression test for issue #18: without a bound on state.buffer, a
+  // client that sends garbage and never completes the PG startup would
+  // grow router memory unbounded (traced to the production 74 GiB VmSize).
+  // After fix, the router must close the connection once the buffer
+  // exceeds MAX_STARTUP_BUFFER_SIZE (1 MiB).
+  cleanup();
+
+  const router = await startMultiTenantServer({
+    port: 15546,
+    baseDir: testDataDir,
+    logLevel: 'warn',
+  });
+
+  const net = await import('net');
+  const sock = net.connect(15546, '127.0.0.1');
+  await new Promise((resolve) => sock.once('connect', resolve));
+
+  const garbage = Buffer.alloc(256 * 1024, 0x41); // 256 KiB of 'A'
+  let closed = false;
+  sock.on('close', () => { closed = true; });
+
+  // Send 5 × 256 KiB = 1.25 MiB, exceeding the 1 MiB cap.
+  for (let i = 0; i < 5 && !closed; i++) {
+    await new Promise((resolve) => sock.write(garbage, resolve));
+  }
+
+  // Wait up to 2s for the proxy to close the connection.
+  const deadline = Date.now() + 2000;
+  while (!closed && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  expect(closed).toBe(true);
+  sock.destroy();
+
+  await router.stop();
+  cleanup();
+});
+
+test('Router - socket state has startupInProgress flag (issue #18 root cause #1)', async () => {
+  // White-box regression test for the reentrancy guard. Without
+  // state.startupInProgress, two data events arriving during the first
+  // processStartupMessage() await would launch concurrent async tasks
+  // that race to assign state.pgSocket, leaking the loser. This test
+  // verifies the flag is wired into the state object.
+  cleanup();
+
+  const router = await startMultiTenantServer({
+    port: 15547,
+    baseDir: testDataDir,
+    logLevel: 'warn',
+  });
+
+  const net = await import('net');
+  const sock = net.connect(15547, '127.0.0.1');
+  await new Promise((resolve) => sock.once('connect', resolve));
+
+  // Router tracks client sockets in this.connections; introspect to pull
+  // the state object and confirm the flag exists and defaults to false.
+  // On some platforms (macOS in particular) the client-side 'connect'
+  // event fires slightly before the server-side handleSocketOpen runs,
+  // so poll until the router has registered the connection rather than
+  // asserting synchronously.
+  const deadline = Date.now() + 2000;
+  while (router.connections.size === 0 && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  expect(router.connections.size).toBeGreaterThan(0);
+  const bunSocket = [...router.connections][0];
+  const state = router.socketState.get(bunSocket);
+  expect(state).toBeDefined();
+  expect(state.startupInProgress).toBe(false);
+
+  sock.destroy();
+  await router.stop();
+  cleanup();
+});
+
+test('PostgresManager - stop() nulls socketDir/databaseDir (issue #24)', async () => {
+  // Regression test for issue #24: router used to cache stale socketPath
+  // pointing to a directory that stop() had already rmSync'd. After fix,
+  // stop() nulls socketDir/databaseDir UNCONDITIONALLY so subsequent
+  // getSocketPath() returns null (forcing TCP fallback in the router).
+  cleanup();
+
+  const { PostgresManager } = await import('../src/postgres.js');
+  const { createLogger } = await import('../src/logger.js');
+  const pg = new PostgresManager({
+    port: 15543,
+    logger: createLogger({ level: 'warn' }),
+  });
+
+  await pg.start();
+  const socketPathBeforeStop = pg.getSocketPath();
+  expect(socketPathBeforeStop).not.toBeNull();
+  expect(fs.existsSync(pg.socketDir)).toBe(true);
+
+  await pg.stop();
+
+  // CORE ASSERTION: socketDir must be nulled after stop
+  expect(pg.socketDir).toBeNull();
+  expect(pg.getSocketPath()).toBeNull();
+  // databaseDir nulled only in memory mode (persistent mode keeps user-owned path)
+  expect(pg.databaseDir).toBeNull();
+  // And the dir on disk must actually be gone
+  // (socketPathBeforeStop points inside the deleted socketDir)
+  const staleSocketDir = path.dirname(socketPathBeforeStop);
+  expect(fs.existsSync(staleSocketDir)).toBe(false);
+});
+
+test('PostgresManager - start()+stop()+start() yields fresh socketDir (issue #24)', async () => {
+  // Regression test for issue #24: pgManager.start() called after stop()
+  // must produce a FRESH socketDir (different path). Without the fix, a
+  // re-entry guard was missing and socketDir could leak across restarts.
+  cleanup();
+
+  const { PostgresManager } = await import('../src/postgres.js');
+  const { createLogger } = await import('../src/logger.js');
+  const pg = new PostgresManager({
+    port: 15544,
+    logger: createLogger({ level: 'warn' }),
+  });
+
+  await pg.start();
+  const socketDir1 = pg.socketDir;
+  expect(socketDir1).not.toBeNull();
+
+  await pg.stop();
+  expect(pg.socketDir).toBeNull();
+
+  await pg.start();
+  const socketDir2 = pg.socketDir;
+  expect(socketDir2).not.toBeNull();
+  expect(socketDir2).not.toBe(socketDir1);
+  expect(fs.existsSync(socketDir2)).toBe(true);
+
+  await pg.stop();
+});
+
+test('PostgresManager - double start() is a no-op (issue #24 re-entry guard)', async () => {
+  // Without the guard, a second start() would overwrite socketDir/databaseDir
+  // and leak the previous tmp dir (the "1,457 stale sock dirs" symptom).
+  cleanup();
+
+  const { PostgresManager } = await import('../src/postgres.js');
+  const { createLogger } = await import('../src/logger.js');
+  const pg = new PostgresManager({
+    port: 15545,
+    logger: createLogger({ level: 'warn' }),
+  });
+
+  await pg.start();
+  const socketDir1 = pg.socketDir;
+
+  // Second start() should silently return the same instance without
+  // reassigning socketDir/databaseDir.
+  const result = await pg.start();
+  expect(result).toBe(pg);
+  expect(pg.socketDir).toBe(socketDir1);
+
+  await pg.stop();
+});
+
 test('Multi-tenant router - instance reuse', async () => {
   cleanup();
 

package/.github/release.yml

@@ -1,30 +0,0 @@
-# GitHub Release Notes Configuration
-# Automatically generates release notes from merged PRs
-# See: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
-
-changelog:
-  exclude:
-    labels:
-      - ignore-for-changelog
-      - internal
-      - bot
-    authors:
-      - github-actions[bot]
-  categories:
-    - title: "Features"
-      labels:
-        - feature
-        - enhancement
-    - title: "Bug Fixes"
-      labels:
-        - bug
-        - fix
-    - title: "Breaking Changes"
-      labels:
-        - breaking
-    - title: "Dependencies"
-      labels:
-        - dependencies
-    - title: "Other Changes"
-      labels:
-        - "*"