pgserve 2.4.0 → 2.6.0

package/src/audit/audit.js

@@ -0,0 +1,134 @@
+/**
+ * Structured audit emitter for privilege-changing operations.
+ *
+ * Group 6 of autopg-distribution-cutover. This is the v1 audit surface
+ * consumed by Group 5's `create-app` / `list` / `revoke` / `rotate` and the
+ * LOCK 1 manifest verifier. Distinct from the legacy `src/audit.js` event
+ * stream (DB lifecycle, connection routing): that stream is `event`-keyed
+ * and writes to `~/.autopg/audit.log`; this stream is `op`-keyed and writes
+ * to `~/.autopg/logs/audit.log` with `schemaVersion: 1`.
+ *
+ * Records are JSON Lines. Every emit produces exactly one line. The shape
+ * is fixed at v1 to give the redaction lint a stable target — adding a new
+ * field is a `schemaVersion: 2` migration, not an in-place addition.
+ *
+ * Threat model the redaction lint guards:
+ *   - The audit log will leak. Plan for it.
+ *   - Therefore: no field name may be a secret category, and no value may
+ *     be sourced from `process.env.*PASSWORD*` (or matching token/secret
+ *     patterns). The lint enforces this at every call site.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const AUDIT_SCHEMA_VERSION = 1;
+
+export const AUDIT_OPS = Object.freeze({
+  CREATE_APP: 'create-app',
+  REVOKE: 'revoke',
+  ROTATE: 'rotate',
+  MANIFEST_VERIFY: 'manifest-verify',
+  MANIFEST_VERIFY_BYPASS: 'manifest-verify-bypass',
+  ADOPT_EXISTING_DB: 'adopt-existing-db',
+});
+
+const VALID_OPS = new Set(Object.values(AUDIT_OPS));
+
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+function getConfigDir() {
+  return (
+    process.env.AUTOPG_CONFIG_DIR ||
+    process.env.PGSERVE_CONFIG_DIR ||
+    path.join(os.homedir(), '.autopg')
+  );
+}
+
+function defaultLogPath() {
+  return path.join(getConfigDir(), 'logs', 'audit.log');
+}
+
+let LOG_PATH = defaultLogPath();
+
+/**
+ * Override the audit log path. Tests use this to redirect into a scratch
+ * dir; the daemon may use it if `AUTOPG_CONFIG_DIR` is set after import.
+ *
+ * Pass no argument to reset to the default (re-resolves env vars).
+ *
+ * @param {{logFile?: string}} [cfg]
+ */
+export function configureAuditEmit(cfg = {}) {
+  if (cfg.logFile) {
+    LOG_PATH = cfg.logFile;
+    return;
+  }
+  LOG_PATH = defaultLogPath();
+}
+
+export function getAuditLogPath() {
+  return LOG_PATH;
+}
+
+/**
+ * Emit a single audit record.
+ *
+ * Required: `op`, `actor`. Optional: `app`, `role`, `manifestSha256`,
+ * `sigVerified`, `incidentId`. Unknown fields are passed through verbatim
+ * so call sites stay flexible — but the redaction lint validates that the
+ * payload never contains secret-shaped names or env-sourced secret values.
+ *
+ * Record shape on disk (JSON Lines):
+ *   {"schemaVersion":1,"ts":"<iso>","op":"create-app",...}
+ *
+ * Returns the written record (mostly for tests; production callers ignore).
+ *
+ * @param {object} record
+ * @param {string} record.op - one of AUDIT_OPS
+ * @param {string} [record.actor] - OS user or admin role performing the op
+ * @param {string} [record.app] - target app name
+ * @param {string} [record.role] - target postgres role
+ * @param {string} [record.manifestSha256] - hex sha256 of the verified manifest
+ * @param {boolean} [record.sigVerified] - whether the manifest sig verified
+ * @param {string} [record.incidentId] - present only when bypass was used
+ * @returns {object}
+ */
+export function auditEmit(record) {
+  if (!record || typeof record !== 'object') {
+    throw new Error('auditEmit: record must be an object');
+  }
+  if (typeof record.op !== 'string' || !VALID_OPS.has(record.op)) {
+    throw new Error(
+      `auditEmit: unknown op "${record.op}". Allowed: ${[...VALID_OPS].join(', ')}`
+    );
+  }
+
+  const out = {
+    schemaVersion: AUDIT_SCHEMA_VERSION,
+    ts: new Date().toISOString(),
+    ...record,
+  };
+
+  writeJsonLine(out, LOG_PATH);
+  return out;
+}
+
+function writeJsonLine(record, logFile) {
+  const dir = path.dirname(logFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+  }
+  const fd = fs.openSync(logFile, 'a', FILE_MODE);
+  try {
+    fs.writeSync(fd, JSON.stringify(record) + '\n');
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.chmodSync(logFile, FILE_MODE);
+  } catch { /* best-effort tighten */ }
+}
+

package/src/cli-install.cjs

@@ -34,10 +34,33 @@ const path = require('node:path');
 // promise once at module load and await it from async install paths.
 const _adminJsonModuleP = import('./lib/admin-json.js');
 const _socketDirModuleP = import('./lib/socket-dir.js');
+const _runtimeJsonModuleP = import('./lib/runtime-json.js');
+const _blockedVersionsModuleP = import('./security/blocked-versions.js');
 
 async function loadCohortModules() {
-  const [adminJson, socketDirMod] = await Promise.all([_adminJsonModuleP, _socketDirModuleP]);
-  return { adminJson, socketDirMod };
+  const [adminJson, socketDirMod, runtimeJson, blockedVersions] = await Promise.all([
+    _adminJsonModuleP,
+    _socketDirModuleP,
+    _runtimeJsonModuleP,
+    _blockedVersionsModuleP,
+  ]);
+  return { adminJson, socketDirMod, runtimeJson, blockedVersions };
+}
+
+// pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 5.
+//
+// Resolves the running pgserve version from package.json so `assertNotBlocked`
+// can compare against the compile-time BLOCKED_VERSIONS list before any
+// install/update mutation. We intentionally use the package.json shipped
+// with this binary (`require.resolve` from inside cli-install.cjs) rather
+// than the version on the host filesystem — we want to refuse THIS binary
+// running, not a different binary that might happen to live next door.
+function getCurrentVersion() {
+  try {
+    return require('../package.json').version;
+  } catch (_e) {
+    return undefined;
+  }
 }
 
 // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
@@ -165,6 +188,131 @@ function readConfig() {
   }
 }
 
+// cutover G19: discovery layer used by `autopg port / url / status`.
+//
+// Order of precedence (most-authoritative first):
+//   1. `<socketDir>/runtime.json` — written by the live postmaster at greet
+//      time, removed on graceful shutdown. Carries the *current* port + pid
+//      for an actually-running daemon.
+//   2. `~/.autopg/admin.json` — supervisor record written at install time.
+//      Survives postmaster restarts; doesn't reflect runtime state.
+//   3. `~/.autopg/config.json` — legacy pre-G19 install record. Final
+//      fallback so older installs that haven't been re-installed under v2.4
+//      still discover cleanly.
+//
+// All readers swallow errors — discovery must never throw on a missing or
+// truncated file. Synchronous on purpose: `dispatch()` for status/url/port
+// is sync and the wrapper handles only `Promise OR number` return types.
+function readRuntimeJsonSync(socketDir) {
+  if (typeof socketDir !== 'string' || socketDir.length === 0) return null;
+  const file = path.join(socketDir, 'runtime.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readAdminJsonSync() {
+  const file = path.join(getConfigDir(), ADMIN_FILE_NAME);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCanonicalSocketDir() {
+  // Mirror src/lib/socket-dir.js#resolveSocketDir — pure function, no fs
+  // touch. Inlined here so the sync discovery layer doesn't need a top-
+  // level await on the ESM module.
+  const xdg = process.env.XDG_RUNTIME_DIR;
+  const base = xdg && xdg.length > 0 ? xdg : '/tmp';
+  return path.join(base, 'pgserve');
+}
+
+function isLivePid(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}
+
+/**
+ * Compose a discovery view from runtime.json (preferred), admin.json
+ * (fallback), and config.json (legacy fallback). Returns:
+ *   {
+ *     runtime: { socketDir, port, pid, autopgPid, schemaVersion } | null,
+ *     admin:   { supervisor, socketDir, port, installedAt, ... }    | null,
+ *     config:  { port, dataDir, registeredAt }                       | null,
+ *     // composed view — best effort merge for callers that just want
+ *     // "where do I connect right now?":
+ *     socketDir: <string|null>,
+ *     port:      <number|null>,
+ *     liveAutopg: <boolean>     // true when runtime.json names a live pid
+ *   }
+ */
+function readDiscovery() {
+  const config = readConfig();
+  const admin = readAdminJsonSync();
+  // Prefer the socket dir the supervisor recorded at install time — that's
+  // the path operators configured. Only fall back to the canonical resolver
+  // when the install record is missing (fresh-host case).
+  const socketDir = (admin && typeof admin.socketDir === 'string' && admin.socketDir.length > 0)
+    ? admin.socketDir
+    : resolveCanonicalSocketDir();
+  const runtime = readRuntimeJsonSync(socketDir);
+
+  // PR #80 P2 fix: previous logic treated ANY parsed runtime.json as
+  // authoritative — a malformed-but-JSON file (no port, no socketDir) would
+  // hide later admin.json / config fallbacks because composedPort stayed
+  // null while the precedence chain stopped early. Validate that runtime
+  // actually carries a usable port + socketDir before treating it as live.
+  // Mirrors the admin / config branches' Number.isInteger guard.
+  let composedSocketDir = null;
+  let composedPort = null;
+  const runtimeUsable = runtime
+    && Number.isInteger(runtime.port)
+    && typeof runtime.socketDir === 'string'
+    && runtime.socketDir.length > 0;
+  if (runtimeUsable) {
+    composedSocketDir = runtime.socketDir;
+    composedPort = runtime.port;
+  } else if (admin && Number.isInteger(admin.port)) {
+    composedSocketDir = admin.socketDir ?? socketDir;
+    composedPort = admin.port;
+  } else if (config && Number.isInteger(config.port)) {
+    composedPort = config.port;
+    composedSocketDir = socketDir;
+  }
+
+  return {
+    runtime,
+    admin,
+    config,
+    socketDir: composedSocketDir,
+    port: composedPort,
+    liveAutopg: !!(runtime && isLivePid(runtime.autopgPid)),
+  };
+}
+
 function writeConfig(config) {
   const dir = getConfigDir();
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
@@ -545,7 +693,25 @@ function cmdAuthDispatch(args) {
  * wrapper before this module is required (avoids re-resolving here).
  */
 async function cmdInstall(args, ctx) {
-  const { adminJson, socketDirMod } = await loadCohortModules();
+  const { adminJson, socketDirMod, blockedVersions } = await loadCohortModules();
+
+  // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 5.
+  // Refuse to install if THIS binary's version appears in the compile-time
+  // blocklist. Runs first (before any host-touching work) so the operator
+  // sees a clear `EBLOCKEDVERSION:` diagnostic with the locked reason +
+  // remediation hint, exit code 4 (distinct from generic install failures).
+  const currentVersion = getCurrentVersion();
+  if (currentVersion) {
+    try {
+      blockedVersions.assertNotBlocked(currentVersion);
+    } catch (err) {
+      if (err.code === 'EBLOCKEDVERSION') {
+        process.stderr.write(`${err.message}\n`);
+        process.exit(4);
+      }
+      throw err;
+    }
+  }
 
   // pgserve singleton (v2.4): refuse to install if a different supervisor
   // (Tier B systemd-user / launchd) already owns the host. The cohort
@@ -704,15 +870,20 @@ function writeSupervisorRecord(adminJson, { supervisor, socketDir, port }) {
 /**
  * `pgserve status [--json]`
  *
- * Reports both pm2 state and on-disk config. Exits 0 with status info
- * regardless of running/stopped — operators script around the JSON output.
- * Non-zero only when the config is missing entirely (i.e. pgserve was
- * never installed).
+ * Reports both pm2 state and on-disk discovery (runtime.json → admin.json
+ * → config.json fallback chain). Exits 0 with status info regardless of
+ * running/stopped — operators script around the JSON output. Non-zero
+ * only when nothing was ever installed (no admin.json AND no config.json).
+ *
+ * Cutover G19: surfaces `runtime` (live socket discovery) and `socketDir`
+ * top-level so consumers can pick UDS vs TCP without parsing pm2 jlist.
  */
 function cmdStatus(args) {
   const json = args.includes('--json');
-  const config = readConfig();
-  if (!config) {
+  const discovery = readDiscovery();
+  const { config, admin, runtime } = discovery;
+
+  if (!config && !admin) {
     if (json) {
       process.stdout.write(`${JSON.stringify({ installed: false })}\n`);
     } else {
@@ -720,24 +891,41 @@ function cmdStatus(args) {
     }
     return 1;
   }
+
   const proc = pm2GetProcess(PM2_PROCESS_NAME);
   const status = proc?.pm2_env?.status ?? 'stopped';
   const pid = proc?.pid ?? null;
   const uptimeMs = proc?.pm2_env?.pm_uptime ? Date.now() - proc.pm2_env.pm_uptime : null;
   const restarts = proc?.pm2_env?.restart_time ?? 0;
 
+  const port = discovery.port;
+  const socketDir = discovery.socketDir;
+  const dataDir = config?.dataDir ?? null;
+
   const payload = {
     installed: true,
     name: PM2_PROCESS_NAME,
     status,
     pid,
-    port: config.port,
-    dataDir: config.dataDir,
+    port,
+    socketDir,
+    dataDir,
     logsDir: getLogsDir(),
-    url: `postgres://localhost:${config.port}/postgres`,
+    url: port ? `postgres://localhost:${port}/postgres` : null,
     uptimeMs,
     restarts,
-    registeredAt: config.registeredAt,
+    registeredAt: config?.registeredAt ?? null,
+    supervisor: admin?.supervisor ?? null,
+    runtime: runtime
+      ? {
+          socketDir: runtime.socketDir,
+          port: runtime.port,
+          pid: runtime.pid,
+          autopgPid: runtime.autopgPid,
+          schemaVersion: runtime.schemaVersion,
+          live: discovery.liveAutopg,
+        }
+      : null,
   };
 
   if (json) {
@@ -746,42 +934,53 @@ function cmdStatus(args) {
   }
   process.stdout.write(`name        ${payload.name}\n`);
   process.stdout.write(`status      ${payload.status}${payload.pid ? ` (pid ${payload.pid})` : ''}\n`);
-  process.stdout.write(`port        ${payload.port}\n`);
-  process.stdout.write(`url         ${payload.url}\n`);
-  process.stdout.write(`dataDir     ${payload.dataDir}\n`);
+  if (payload.supervisor) {
+    process.stdout.write(`supervisor  ${payload.supervisor}\n`);
+  }
+  if (payload.port != null) process.stdout.write(`port        ${payload.port}\n`);
+  if (payload.url) process.stdout.write(`url         ${payload.url}\n`);
+  if (payload.socketDir) process.stdout.write(`socketDir   ${payload.socketDir}\n`);
+  if (payload.dataDir) process.stdout.write(`dataDir     ${payload.dataDir}\n`);
   process.stdout.write(`logsDir     ${payload.logsDir}\n`);
+  if (payload.runtime) {
+    process.stdout.write(`runtime     pid=${payload.runtime.pid} autopgPid=${payload.runtime.autopgPid} live=${payload.runtime.live}\n`);
+  } else {
+    process.stdout.write(`runtime     (no runtime.json — postmaster down or never started)\n`);
+  }
   if (payload.uptimeMs != null) {
     const sec = Math.floor(payload.uptimeMs / 1000);
     process.stdout.write(`uptime      ${sec}s\n`);
   }
   process.stdout.write(`restarts    ${payload.restarts}\n`);
-  process.stdout.write(`registered  ${payload.registeredAt}\n`);
+  if (payload.registeredAt) process.stdout.write(`registered  ${payload.registeredAt}\n`);
   return 0;
 }
 
 /**
  * `pgserve url`
  *
- * Discovery API. Prints the canonical connection string. Downstream
+ * Discovery API. Prints the canonical TCP connection string. Downstream
  * installers (genie install, omni install) call this to learn where to
- * connect, instead of hardcoding a port.
+ * connect, instead of hardcoding a port. The TCP form is stable across
+ * Tier A / Tier B / fingerprint-disabled hosts; UDS callers should
+ * resolve `<socketDir>/.s.PGSQL.<port>` from `autopg status --json`.
  */
 function cmdUrl() {
-  const config = readConfig();
-  if (!config) {
+  const discovery = readDiscovery();
+  if (discovery.port == null) {
     fail('not installed (run: pgserve install)');
   }
-  process.stdout.write(`postgres://localhost:${config.port}/postgres\n`);
+  process.stdout.write(`postgres://localhost:${discovery.port}/postgres\n`);
   return 0;
 }
 
-/** `pgserve port` — print the canonical port. */
+/** `pgserve port` — print the canonical port from runtime.json → admin.json → config.json. */
 function cmdPort() {
-  const config = readConfig();
-  if (!config) {
+  const discovery = readDiscovery();
+  if (discovery.port == null) {
     fail('not installed (run: pgserve install)');
   }
-  process.stdout.write(`${config.port}\n`);
+  process.stdout.write(`${discovery.port}\n`);
   return 0;
 }
 
@@ -878,6 +1077,12 @@ function dispatch(subcommand, args, ctx) {
       // dispatcher. dispatch() returns a Promise here; the wrapper
       // already handles both numeric and Promise returns.
       return import('./commands/uninstall.js').then((mod) => mod.runUninstall());
+    case 'doctor':
+      // pgserve-singleton-no-proxy Group 3: read-only V1. Reports the
+      // active supervisor + postmaster reachability + admin.json /
+      // runtime.json health. --fix tiered modes deferred to a follow-up
+      // (SHARED-DESIGN §3.2).
+      return import('./commands/doctor.js').then((mod) => mod.runDoctor(args).then((code) => process.exit(code)));
     case 'status':
       return cmdStatus(args);
     case 'url':
@@ -913,6 +1118,33 @@ function dispatch(subcommand, args, ctx) {
     }
     case 'auth':
       return cmdAuthDispatch(args);
+    case 'verify': {
+      // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+      // `pgserve verify` is a pure-node command (cosign shellout + HMAC
+      // cache token write); routes through the same async-import pattern
+      // as `uninstall` so the ESM module isn't eagerly loaded.
+      return import('./commands/verify.js').then((mod) => mod.runVerify(args));
+    }
+    case 'trust':
+      // pgserve singleton (v2.4) — wish Group 3, second read-only verb.
+      // `pgserve trust add/list/remove` manages the user-extensible cosign
+      // trust store at ~/.pgserve/trust/identities.json. Pure node.
+      // The wrapper handles the numeric-exit-code case; matches the
+      // verify dispatch style so the wrapper, not the verb, owns
+      // process.exit.
+      return import('./commands/trust.js').then((mod) => mod.runTrust(args));
+    case 'gc':
+      // pgserve singleton (v2.4) — wish Group 3, verb 3. `pgserve gc`
+      // sweeps orphaned databases. Default mode is dry-run; --apply
+      // performs the actual DROP. Composes the orphan classifier +
+      // audit-log writer + psql shellout primitives.
+      return import('./commands/gc.js').then((mod) => mod.runGc(args));
+    case 'provision':
+      // pgserve singleton (v2.4) — wish Group 3, verb 4. Idempotent
+      // CREATE ROLE / DATABASE / GRANT + UPSERT pgserve_meta. Honest
+      // idempotency-driven serialization (see provision.js header for
+      // why no advisory lock). Pure node + psql shellout.
+      return import('./commands/provision.js').then((mod) => mod.runProvision(args));
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }