pgserve 2.4.0 → 2.5.0

package/src/cosign/verify-binary.js

@@ -0,0 +1,277 @@
+/**
+ * Cosign keyless OIDC binary verifier.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+ *
+ * Per Decision P5 (locked), we shell out to the `cosign` CLI rather than
+ * vendoring sigstore-rs. Verification model:
+ *
+ *   - Each binary distributed by an automagik release ships with a
+ *     paired Sigstore bundle file at `<binary>.bundle` (modern keyless
+ *     OIDC attestation, JSON-encoded).
+ *   - We invoke `cosign verify-blob --bundle <bundle>
+ *     --certificate-identity-regexp <re> --certificate-oidc-issuer <iss>
+ *     <binary>` — once per entry in the trust list.
+ *   - First entry that exits 0 wins. We return its identity + tier.
+ *   - If every entry fails, we surface the most-specific cosign diagnostic
+ *     (the last exit) so the operator knows which trust root we tried.
+ *
+ * Resolution of the cosign executable:
+ *   1. Caller-supplied `cosignBin` (used by tests + `--cosign-bin` flag)
+ *   2. `cosign` on `$PATH`
+ *   3. Cached static binary at `~/.pgserve/bin/cosign`
+ *   4. Download official static binary from sigstore release (offline by
+ *      default — only triggered when `allowFetch: true` is passed)
+ *
+ * Returns a tagged union:
+ *   { ok: true,  identity, tier, sha256, cosignBin, bundle }
+ *   { ok: false, reason, detail?, identityChain? }
+ */
+
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TRUSTED_IDENTITIES } from './trust-list.js';
+
+export const COSIGN_TIER = 'cosign_signed';
+export const COSIGN_BIN_DIR = path.join(os.homedir(), '.pgserve', 'bin');
+export const COSIGN_BIN_FILE = path.join(COSIGN_BIN_DIR, process.platform === 'win32' ? 'cosign.exe' : 'cosign');
+
+const COSIGN_RELEASE_VERSION = 'v2.2.4';
+const COSIGN_RELEASE_BASE = `https://github.com/sigstore/cosign/releases/download/${COSIGN_RELEASE_VERSION}`;
+
+/**
+ * Compute sha256 of a file. Returns lowercase hex.
+ */
+export function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  const buf = fs.readFileSync(filePath);
+  hash.update(buf);
+  return hash.digest('hex');
+}
+
+/**
+ * Resolve the sidecar bundle path for a given binary path. Convention:
+ * `<binary>.bundle`. Operators that publish detached `.sig` + `.cert` can
+ * regenerate a bundle with `cosign sign-blob --bundle <path>.bundle`; we
+ * intentionally only support the bundle form to keep the surface narrow.
+ */
+export function resolveBundlePath(binaryPath) {
+  return `${binaryPath}.bundle`;
+}
+
+/**
+ * Resolve which `cosign` executable to use. Returns a string path or null
+ * if no cosign is available and `allowFetch: false`.
+ *
+ * PATH probing is implemented in-process (rather than shelling out to
+ * `which` / `where`) so the resolver works inside test harnesses that
+ * scrub PATH down to a single stub directory.
+ */
+export function resolveCosignBin({ cosignBin, allowFetch = false } = {}) {
+  if (cosignBin && fs.existsSync(cosignBin)) return cosignBin;
+
+  const fromPath = lookupOnPath(process.platform === 'win32' ? 'cosign.exe' : 'cosign');
+  if (fromPath) return fromPath;
+
+  // Cached static binary.
+  if (fs.existsSync(COSIGN_BIN_FILE)) return COSIGN_BIN_FILE;
+
+  if (!allowFetch) return null;
+
+  try {
+    return fetchCosignBin();
+  } catch {
+    return null;
+  }
+}
+
+function lookupOnPath(name) {
+  const PATH = process.env.PATH || '';
+  if (!PATH) return null;
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const dirs = PATH.split(sep).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, name);
+    try {
+      const stat = fs.statSync(candidate);
+      if (stat.isFile()) {
+        // On POSIX, ensure it's executable; on Windows, file existence is enough.
+        if (process.platform === 'win32') return candidate;
+        if ((stat.mode & 0o111) !== 0) return candidate;
+      }
+    } catch {
+      // missing or stat error — try next dir
+    }
+  }
+  return null;
+}
+
+/**
+ * Download the official cosign static binary into `~/.pgserve/bin/cosign`.
+ * Synchronous — used by `pgserve verify` when no cosign is on PATH and the
+ * operator opts into the fetch (see Decision P5: "if cosign not on PATH,
+ * pgserve install shells out to a downloader to fetch the official static
+ * binary into ~/.pgserve/bin/cosign").
+ *
+ * Network-dependent. Throws on failure. Tests stub via `cosignBin` instead
+ * of this code path.
+ */
+export function fetchCosignBin({
+  releaseBase = COSIGN_RELEASE_BASE,
+  targetFile = COSIGN_BIN_FILE,
+  targetDir = COSIGN_BIN_DIR,
+} = {}) {
+  fs.mkdirSync(targetDir, { recursive: true, mode: 0o755 });
+  const assetName = pickCosignAssetName();
+  const url = `${releaseBase}/${assetName}`;
+  const tmp = `${targetFile}.tmp.${process.pid}`;
+  downloadToFileSync(url, tmp);
+  fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, targetFile);
+  return targetFile;
+}
+
+function pickCosignAssetName() {
+  const arch = process.arch === 'x64' ? 'amd64' : process.arch === 'arm64' ? 'arm64' : process.arch;
+  if (process.platform === 'darwin') return `cosign-darwin-${arch}`;
+  if (process.platform === 'win32') return `cosign-windows-${arch}.exe`;
+  return `cosign-linux-${arch}`;
+}
+
+function downloadToFileSync(url, destPath) {
+  // Node has no built-in synchronous HTTP. We fall back to spawning curl
+  // since this only runs once per host (cached afterward) and curl is
+  // ubiquitous on the supported platforms.
+  const curl = spawnSync('curl', ['-fsSL', '-o', destPath, url], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (curl.status === 0) return;
+  // Fallback: try wget.
+  const wget = spawnSync('wget', ['-qO', destPath, url], { stdio: ['ignore', 'pipe', 'pipe'] });
+  if (wget.status === 0) return;
+  throw new Error(
+    `cosign-verify: failed to download cosign from ${url} (curl exit ${curl.status}, wget exit ${wget?.status ?? 'n/a'})`,
+  );
+}
+
+/**
+ * Verify a binary with cosign.
+ *
+ * @param {string} binaryPath
+ * @param {object} [options]
+ * @param {string} [options.cosignBin]   override cosign executable
+ * @param {string} [options.bundlePath]  override bundle sidecar path
+ * @param {Array}  [options.trustList]   override hardcoded TRUSTED_IDENTITIES
+ * @param {boolean}[options.allowFetch]  allow fetching the cosign binary if missing
+ * @returns {{ ok: true, identity, tier, sha256, cosignBin, bundle, identityChain }
+ *         | { ok: false, reason, detail?, identityChain? }}
+ */
+export function verifyBinary(binaryPath, options = {}) {
+  if (typeof binaryPath !== 'string' || binaryPath.length === 0) {
+    return { ok: false, reason: 'invalid-args', detail: 'binaryPath required' };
+  }
+  if (!fs.existsSync(binaryPath)) {
+    return { ok: false, reason: 'binary-missing', detail: binaryPath };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(binaryPath);
+  } catch (err) {
+    return { ok: false, reason: 'binary-unreadable', detail: err.message };
+  }
+  if (!stat.isFile()) {
+    return { ok: false, reason: 'binary-not-a-file', detail: binaryPath };
+  }
+
+  const bundlePath = options.bundlePath || resolveBundlePath(binaryPath);
+  if (!fs.existsSync(bundlePath)) {
+    return {
+      ok: false,
+      reason: 'bundle-missing',
+      detail: `expected sigstore bundle at ${bundlePath} (run \`cosign sign-blob --bundle ${bundlePath} ${binaryPath}\` to attest)`,
+    };
+  }
+
+  const trustList = options.trustList || TRUSTED_IDENTITIES;
+  if (!Array.isArray(trustList) || trustList.length === 0) {
+    return { ok: false, reason: 'empty-trust-list' };
+  }
+
+  const cosignBin = resolveCosignBin({
+    cosignBin: options.cosignBin,
+    allowFetch: options.allowFetch === true,
+  });
+  if (!cosignBin) {
+    return {
+      ok: false,
+      reason: 'cosign-missing',
+      detail:
+        'no `cosign` binary on $PATH or in ~/.pgserve/bin/cosign — install cosign or rerun with --allow-fetch',
+    };
+  }
+
+  const sha256 = sha256File(binaryPath);
+  const identityChain = [];
+  let lastFailure = null;
+
+  for (const identity of trustList) {
+    if (!identity || !identity.id || !identity.issuer || !identity.identityRegexp) {
+      identityChain.push({ id: identity?.id || '<malformed>', status: 'skipped' });
+      continue;
+    }
+    const result = invokeCosign({
+      cosignBin,
+      bundlePath,
+      binaryPath,
+      identity,
+    });
+    if (result.ok) {
+      identityChain.push({ id: identity.id, status: 'matched' });
+      return {
+        ok: true,
+        identity: identity.id,
+        publisher: identity.publisher,
+        tier: COSIGN_TIER,
+        sha256,
+        cosignBin,
+        bundle: bundlePath,
+        identityChain,
+      };
+    }
+    identityChain.push({ id: identity.id, status: 'rejected', exitCode: result.exitCode });
+    lastFailure = result;
+  }
+
+  return {
+    ok: false,
+    reason: 'no-trust-match',
+    detail: lastFailure?.stderr || 'cosign rejected the binary against every trust root',
+    identityChain,
+  };
+}
+
+function invokeCosign({ cosignBin, bundlePath, binaryPath, identity }) {
+  const args = [
+    'verify-blob',
+    '--bundle', bundlePath,
+    '--certificate-identity-regexp', identity.identityRegexp,
+    '--certificate-oidc-issuer', identity.issuer,
+    binaryPath,
+  ];
+  const proc = spawnSync(cosignBin, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (proc.status === 0) {
+    return { ok: true, stdout: proc.stdout || '' };
+  }
+  return {
+    ok: false,
+    exitCode: typeof proc.status === 'number' ? proc.status : -1,
+    stderr: (proc.stderr || proc.stdout || '').trim().slice(0, 4096),
+  };
+}

package/src/lib/runtime-json.js

@@ -0,0 +1,181 @@
+/**
+ * `<socketDir>/runtime.json` — runtime discovery file owned by the
+ * `autopg serve` postmaster wrapper (cutover wish G19).
+ *
+ * Schema:
+ *   {
+ *     socketDir:     "<absolute path>",
+ *     port:          <integer>,    // postgres TCP port
+ *     pid:           <integer>,    // postmaster pid
+ *     autopgPid:     <integer>,    // `autopg serve` wrapper pid
+ *     schemaVersion: 1
+ *   }
+ *
+ * Cohort contract — there is **no `supervisor` field**. The supervisor
+ * (pm2 / systemd-user / launchd / external) is recorded once at install
+ * time in `~/.autopg/admin.json`. Mixing the two creates a synchronization
+ * problem (which file is authoritative when the postmaster restarts under
+ * a new pid?). `writeRuntimeJson()` rejects records carrying a `supervisor`
+ * key so the contract can't drift via a future copy-paste.
+ *
+ * Lifecycle:
+ *   - `writeRuntimeJson()` after the postmaster greets healthy.
+ *   - `clearRuntimeJson()` on graceful shutdown (SIGTERM / SIGINT).
+ *   - On crash the file is left in place. Consumers detect a stale record
+ *     via `process.kill(record.autopgPid, 0)` (no-signal probe).
+ *
+ * Atomic semantics: write to `<file>.tmp.<pid>`, then `fs.renameSync()`.
+ * Mode 0644 so unprivileged peers can `cat <socketDir>/runtime.json`
+ * without sudo — the file carries no secrets, only public discovery info.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const RUNTIME_FILE_NAME = 'runtime.json';
+export const RUNTIME_FILE_MODE = 0o644;
+export const RUNTIME_SCHEMA_VERSION = 1;
+
+export function getRuntimeFilePath(socketDir) {
+  if (typeof socketDir !== 'string' || socketDir.length === 0) {
+    throw new TypeError('runtime-json: socketDir must be a non-empty string');
+  }
+  return path.join(socketDir, RUNTIME_FILE_NAME);
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function validateRecord(record) {
+  if (!isPlainObject(record)) {
+    throw new TypeError('runtime-json: record must be an object');
+  }
+  if (typeof record.socketDir !== 'string' || record.socketDir.length === 0) {
+    throw new TypeError('runtime-json: socketDir must be a non-empty string');
+  }
+  if (!Number.isInteger(record.port) || record.port < 1 || record.port > 65535) {
+    throw new TypeError(`runtime-json: port must be an integer in [1, 65535]; got ${record.port}`);
+  }
+  if (!Number.isInteger(record.pid) || record.pid < 1) {
+    throw new TypeError(`runtime-json: pid must be a positive integer; got ${record.pid}`);
+  }
+  if (!Number.isInteger(record.autopgPid) || record.autopgPid < 1) {
+    throw new TypeError(`runtime-json: autopgPid must be a positive integer; got ${record.autopgPid}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(record, 'supervisor')) {
+    throw new TypeError(
+      'runtime-json: refusing to write `supervisor` into runtime.json — that field '
+      + 'lives only in `~/.autopg/admin.json` (cohort contract).',
+    );
+  }
+}
+
+/**
+ * Read `<socketDir>/runtime.json`. Returns the parsed object on success,
+ * `null` when the file is missing or unreadable. Never throws — callers
+ * treat "missing" and "broken" identically and fall back to admin.json.
+ */
+export function readRuntimeJson(socketDir) {
+  let file;
+  try {
+    file = getRuntimeFilePath(socketDir);
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomic write of the runtime discovery record. Validates shape, refuses
+ * a `supervisor` key (the cohort contract — that field belongs in
+ * admin.json), ensures the parent directory exists, and stamps
+ * `schemaVersion: 1` if the caller didn't.
+ */
+export function writeRuntimeJson(input = {}) {
+  if (!isPlainObject(input)) {
+    throw new TypeError('runtime-json: writeRuntimeJson expects an object argument');
+  }
+  // Reject `supervisor` from the input directly — destructuring would
+  // silently drop it and that's a contract failure we want to surface.
+  if (Object.prototype.hasOwnProperty.call(input, 'supervisor')) {
+    throw new TypeError(
+      'runtime-json: refusing to write `supervisor` into runtime.json — that field '
+      + 'lives only in `~/.autopg/admin.json` (cohort contract).',
+    );
+  }
+  const { socketDir, port, pid, autopgPid, schemaVersion = RUNTIME_SCHEMA_VERSION } = input;
+  const record = { socketDir, port, pid, autopgPid, schemaVersion };
+  validateRecord(record);
+
+  if (!fs.existsSync(socketDir)) {
+    fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+  }
+
+  const file = getRuntimeFilePath(socketDir);
+  const tmp = `${file}.tmp.${process.pid}`;
+  const json = `${JSON.stringify(record, null, 2)}\n`;
+  fs.writeFileSync(tmp, json, { mode: RUNTIME_FILE_MODE });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, RUNTIME_FILE_MODE);
+  return record;
+}
+
+/**
+ * Best-effort delete of `<socketDir>/runtime.json`. Used during graceful
+ * shutdown so consumers immediately observe "no live postmaster" instead
+ * of seeing a stale-pid record they have to probe with `process.kill()`.
+ *
+ * Returns `true` when the file was removed, `false` when it was already
+ * gone or removal failed. Never throws — graceful shutdown must not
+ * regress because of a permission glitch on the runtime file.
+ */
+export function clearRuntimeJson(socketDir) {
+  let file;
+  try {
+    file = getRuntimeFilePath(socketDir);
+  } catch {
+    return false;
+  }
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true when the runtime record points at a process that's alive
+ * on this host. `process.kill(pid, 0)` is a no-signal probe — it raises
+ * ESRCH when the pid is gone and EPERM when we can't signal a foreign
+ * uid (still alive, just not ours). Treat EPERM as "alive" so cross-uid
+ * supervisors (e.g. an operator probing a system-installed pgserve)
+ * don't false-negative.
+ */
+export function isLiveRuntime(record) {
+  if (!isPlainObject(record)) return false;
+  // process.kill(pid, 0) accepts a process group sentinel for pid <= 0
+  // (pid 0 = caller's group, pid -1 = every signalable process). Neither
+  // is a meaningful "live postmaster" answer, so reject anything below 1
+  // before we touch the syscall.
+  const pid = record.autopgPid;
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}

package/src/upgrade/index.js

@@ -20,11 +20,16 @@ import * as plpgsqlResolve from './steps/plpgsql-resolve.js';
 import * as envRefresh from './steps/env-refresh.js';
 import * as consumerSignal from './steps/consumer-signal.js';
 import * as healthValidate from './steps/health-validate.js';
+import * as cosignMetaMigration from './steps/cosign-meta-migration.js';
 
 export const STEPS = [
   { name: 'port-reconcile', impl: portReconcile },
   { name: 'binary-cache-flush', impl: binaryCacheFlush },
   { name: 'plpgsql-resolve', impl: plpgsqlResolve },
+  // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+  // Adds the additive `verified_*` columns to `pgserve_meta`. Runs after
+  // plpgsql-resolve so the extension is available; idempotent per-DB.
+  { name: 'cosign-meta-migration', impl: cosignMetaMigration },
   { name: 'env-refresh', impl: envRefresh },
   { name: 'consumer-signal', impl: consumerSignal },
   { name: 'health-validate', impl: healthValidate },

package/src/upgrade/steps/cosign-meta-migration.js

@@ -0,0 +1,123 @@
+/**
+ * Step — pgserve_meta cosign columns (additive).
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+ *
+ * Adds `verified_at`, `verified_identity`, `verified_tier` to every
+ * `pgserve_meta` table the upgrade step finds. The schema delta is
+ * additive (Decision P4) — pre-cosign rows continue to work, columns are
+ * NULL until Group 3's `pgserve provision` writes them.
+ *
+ * Runs idempotently: `ADD COLUMN IF NOT EXISTS` plus a guarded DO-block
+ * for the CHECK constraint. Re-running on an already-migrated host is a
+ * no-op. If `pgserve_meta` does not exist (fresh install before G3 has
+ * provisioned anything) the step is a SKIP.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import { getMigrationStatements } from '../../cosign/schema.js';
+
+export const name = 'cosign-meta-migration';
+const CANONICAL_PORT = 5432;
+const SYSTEM_DBS = new Set(['template0', 'template1']);
+
+// PR #79 fix: previous implementation used execSync with a template string +
+// JSON.stringify(sql). The migration SQL contains `DO $$ ... $$` blocks; bash
+// expands `$$` to its PID, corrupting the SQL before psql sees it. Switch to
+// spawnSync (shell:false) with the SQL fed through stdin — no shell parsing,
+// no expansion, no injection surface.
+function pgQuery({ db, sql, captureStdout = false, port = CANONICAL_PORT }) {
+  const env = { ...process.env, PGPASSWORD: process.env.PGPASSWORD || 'postgres' };
+  const result = spawnSync(
+    'psql',
+    ['-h', '127.0.0.1', '-p', String(port), '-U', 'postgres', '-d', db, '-At', '-f', '-'],
+    { env, input: sql, stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+  if (result.status !== 0) {
+    const stderr = (result.stderr || Buffer.from('')).toString();
+    const err = new Error(`psql exited ${result.status}: ${stderr.trim()}`);
+    err.status = result.status;
+    err.stderr = stderr;
+    throw err;
+  }
+  const stdout = (result.stdout || Buffer.from('')).toString();
+  return captureStdout ? stdout.trim() : stdout;
+}
+
+function listUserDbs() {
+  const out = pgQuery({
+    db: 'postgres',
+    sql: "SELECT datname FROM pg_database WHERE NOT datistemplate ORDER BY datname",
+    captureStdout: true,
+  });
+  return out ? out.split('\n').filter(Boolean).filter((d) => !SYSTEM_DBS.has(d)) : [];
+}
+
+function pgserveMetaExists(db) {
+  const out = pgQuery({
+    db,
+    sql: "SELECT to_regclass('public.pgserve_meta') IS NOT NULL",
+    captureStdout: true,
+  });
+  return out === 't' || out === 'true';
+}
+
+export async function plan() {
+  let dbs;
+  try {
+    dbs = listUserDbs();
+  } catch (err) {
+    return `cannot enumerate DBs: ${err.message}`;
+  }
+  if (dbs.length === 0) return 'no user DBs — skip';
+  const targets = [];
+  for (const db of dbs) {
+    try {
+      if (pgserveMetaExists(db)) targets.push(db);
+    } catch {
+      // Skip silently — DB might be unreachable, listed but not connectable.
+    }
+  }
+  if (targets.length === 0) return 'no DB hosts pgserve_meta yet — skip';
+  return `would apply additive cosign columns to pgserve_meta in: ${targets.join(', ')}`;
+}
+
+export async function execute({ log, warn }) {
+  let dbs;
+  try {
+    dbs = listUserDbs();
+  } catch (err) {
+    return { status: 'FAIL', detail: `cannot enumerate DBs: ${err.message}` };
+  }
+  if (dbs.length === 0) return { status: 'SKIP', detail: 'no user DBs to migrate' };
+
+  const statements = getMigrationStatements();
+  let migrated = 0;
+  let skipped = 0;
+  for (const db of dbs) {
+    let exists;
+    try {
+      exists = pgserveMetaExists(db);
+    } catch (err) {
+      warn(`[cosign-meta-migration] ${db}: cannot probe pgserve_meta — ${err.message}`);
+      skipped++;
+      continue;
+    }
+    if (!exists) {
+      skipped++;
+      continue;
+    }
+    try {
+      for (const sql of statements) {
+        pgQuery({ db, sql });
+      }
+      log(`[cosign-meta-migration] ${db}: applied ${statements.length} idempotent statement(s)`);
+      migrated++;
+    } catch (err) {
+      warn(`[cosign-meta-migration] ${db}: failed — ${err.message}`);
+      skipped++;
+    }
+  }
+  return { status: 'OK', detail: `migrated ${migrated} DB(s), skipped ${skipped}` };
+}