pgserve 2.3.0 → 2.5.0

package/src/commands/uninstall.js

@@ -0,0 +1,241 @@
+/**
+ * `autopg uninstall` — Tier A teardown of the rootless pm2 supervisor.
+ *
+ * Group 1 of the canonical-pgserve-pm2-supervision wish. Idempotent.
+ *
+ * Removes:
+ *   - pm2 entry `autopg-server` (the postmaster, registered by `autopg install`)
+ *   - pm2 entry `autopg-ui`     (the console SPA, registered by `autopg install`)
+ *   - the supervisor record in `~/.autopg/admin.json` (the four supervisor
+ *     fields managed by `src/lib/admin-json.js` — preserves the scrypt
+ *     Basic-Auth scheme so a re-install can keep the same admin password).
+ *
+ * Preserves:
+ *   - the data directory under `~/.autopg/data/`
+ *   - `~/.autopg/config.json`
+ *   - `admin.json` auth fields (scheme/salt/hash/createdAt/rotatedAt/...)
+ *
+ * Writes one JSONL audit-log entry to `<configDir>/audit.log`.
+ *
+ * Idempotent contract: running uninstall twice in a row is a no-op on the
+ * second call. After uninstall, a subsequent `autopg install` succeeds
+ * without a Tier-B-refusal false positive — `assertSupervisor` treats a
+ * missing supervisor field as "host is free to install".
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  ADMIN_FILE_MODE,
+  getAdminFilePath,
+  readAdminJson,
+} from '../lib/admin-json.js';
+
+export const TIER_A_PM2_PROCESSES = Object.freeze(['autopg-server', 'autopg-ui']);
+export const SUPERVISOR_FIELDS = Object.freeze([
+  'supervisor',
+  'socketDir',
+  'port',
+  'installedAt',
+]);
+
+function getConfigDir() {
+  return (
+    process.env.AUTOPG_CONFIG_DIR
+    || process.env.PGSERVE_CONFIG_DIR
+    || path.join(os.homedir(), '.autopg')
+  );
+}
+
+function pm2IsAvailable() {
+  try {
+    execFileSync('pm2', ['--version'], {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function pm2GetProcess(name) {
+  try {
+    const out = execFileSync('pm2', ['jlist'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const list = JSON.parse(out);
+    return list.find((p) => p && p.name === name) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Always-attempt pm2 delete. `pm2 delete <missing>` exits non-zero but the
+ * call is idempotent server-side, so any non-zero exit is treated as
+ * "already absent" rather than a hard failure. We snapshot pm2 jlist
+ * BEFORE the delete to report whether the entry actually existed.
+ */
+function tearDownPm2(name) {
+  if (!pm2IsAvailable()) {
+    return { name, removed: false, status: 'pm2-missing' };
+  }
+  const before = pm2GetProcess(name);
+  const res = spawnSync('pm2', ['delete', name], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10_000,
+  });
+  if (res.status === 0) {
+    return {
+      name,
+      removed: !!before,
+      status: before ? 'removed' : 'already-absent',
+    };
+  }
+  return {
+    name,
+    removed: false,
+    status: 'already-absent',
+    exitCode: res.status,
+  };
+}
+
+/**
+ * Atomically clear the supervisor fields from admin.json. Preserves all
+ * other fields (notably the scrypt Basic-Auth scheme written by
+ * `cli-install.cjs`'s `writeAdminFile`). Removes the file entirely if
+ * clearing leaves an empty object.
+ *
+ * Returns { changed, file, hadSupervisor }.
+ */
+function clearSupervisorRecord(configDir) {
+  const file = getAdminFilePath(configDir);
+  const existing = readAdminJson({ configDir });
+  if (!existing) {
+    return { changed: false, file, hadSupervisor: false };
+  }
+  const hadSupervisor = SUPERVISOR_FIELDS.some((k) => k in existing);
+  if (!hadSupervisor) {
+    return { changed: false, file, hadSupervisor: false };
+  }
+  const cleared = { ...existing };
+  for (const field of SUPERVISOR_FIELDS) {
+    delete cleared[field];
+  }
+  if (Object.keys(cleared).length === 0) {
+    try {
+      fs.unlinkSync(file);
+    } catch (err) {
+      if (err && err.code !== 'ENOENT') throw err;
+    }
+    return { changed: true, file, hadSupervisor: true };
+  }
+  const tmp = `${file}.tmp.${process.pid}`;
+  const json = `${JSON.stringify(cleared, null, 2)}\n`;
+  fs.writeFileSync(tmp, json, { mode: ADMIN_FILE_MODE });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, ADMIN_FILE_MODE);
+  return { changed: true, file, hadSupervisor: true };
+}
+
+function appendAuditLog(configDir, payload) {
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  }
+  const file = path.join(configDir, 'audit.log');
+  const record = {
+    ts: new Date().toISOString(),
+    event: 'autopg_uninstall',
+    ...payload,
+  };
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+
+function emit(level, msg, silent) {
+  if (silent) return;
+  const stream = level === 'err' ? process.stderr : process.stdout;
+  stream.write(`autopg: ${msg}\n`);
+}
+
+/**
+ * Run the uninstall flow. Returns a numeric exit code.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.configDir] — override the autopg config dir (used
+ *   by tests; production code should leave this undefined and let env vars
+ *   resolve).
+ * @param {boolean} [opts.silent] — suppress stdout/stderr writes.
+ */
+export function runUninstall(opts = {}) {
+  const configDir = opts.configDir || getConfigDir();
+  const silent = opts.silent === true;
+
+  const pm2Available = pm2IsAvailable();
+  if (!pm2Available) {
+    emit(
+      'err',
+      'pm2 not found in PATH; skipping pm2 teardown (admin.json supervisor record will still be cleared).',
+      silent,
+    );
+  }
+
+  const pm2Results = TIER_A_PM2_PROCESSES.map((name) => tearDownPm2(name));
+
+  let supervisorClear;
+  try {
+    supervisorClear = clearSupervisorRecord(configDir);
+  } catch (err) {
+    emit('err', `failed to clear supervisor record in admin.json: ${err.message}`, silent);
+    return 1;
+  }
+
+  try {
+    appendAuditLog(configDir, {
+      pm2Available,
+      pm2: pm2Results,
+      supervisorRecord: {
+        changed: supervisorClear.changed,
+        hadSupervisor: supervisorClear.hadSupervisor,
+        file: supervisorClear.file,
+      },
+    });
+  } catch {
+    // Audit must never break uninstall.
+  }
+
+  const removed = pm2Results.filter((r) => r.removed).map((r) => r.name);
+  const absent = pm2Results.filter((r) => r.status === 'already-absent').map((r) => r.name);
+
+  if (removed.length === 0 && !supervisorClear.changed) {
+    emit(
+      'out',
+      `not registered under pm2 (${TIER_A_PM2_PROCESSES.join(', ')}); nothing to uninstall`,
+      silent,
+    );
+    return 0;
+  }
+
+  if (removed.length > 0) {
+    emit(
+      'out',
+      `uninstalled pm2 entries: ${removed.join(', ')} (data dir preserved at ${path.join(configDir, 'data')})`,
+      silent,
+    );
+  }
+  if (absent.length > 0 && removed.length > 0) {
+    emit('out', `(already absent: ${absent.join(', ')})`, silent);
+  }
+  if (supervisorClear.changed) {
+    emit('out', `cleared supervisor record from ${supervisorClear.file}`, silent);
+  } else if (removed.length > 0) {
+    emit('out', `no supervisor record to clear in ${supervisorClear.file}`, silent);
+  }
+  return 0;
+}

package/src/commands/verify.js

@@ -0,0 +1,360 @@
+/**
+ * `pgserve verify <binary-path>` — cosign-keyless-OIDC verification.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+ *
+ * Flow:
+ *   1. Resolve target binary, compute realpath + sha256 + size + mtime.
+ *   2. Look up the HMAC-signed cache at `$XDG_STATE_HOME/pgserve/verified/
+ *      <fingerprint>.token`. If valid (HMAC matches, sliding expiry not
+ *      lapsed, binary attestation matches mtime/size) → short-circuit.
+ *   3. Otherwise call `verifyBinary()` (cosign verify-blob against the
+ *      hardcoded trust list per `src/cosign/trust-list.js`).
+ *   4. On success: persist the cache token (mode 0600). On failure: emit
+ *      a diagnostic and exit non-zero.
+ *
+ * Flags:
+ *   --json                 — emit machine-readable result on stdout
+ *   --skip-sigstore        — bypass cosign and consult the operator's
+ *                            offline trust file. Refuses unless the file
+ *                            records at least one offline-cosign-key entry
+ *                            (managed by G3's `pgserve trust add`).
+ *   --bundle <path>        — override the sigstore bundle sidecar path
+ *   --cosign-bin <path>    — override the cosign executable
+ *   --allow-fetch          — let cosign be fetched if missing on PATH
+ *   --no-cache             — never read or write the verified-cache token
+ *
+ * Exit codes:
+ *   0  — verified (fresh or cache hit)
+ *   2  — verification failed (cosign rejected, tampered binary, ...)
+ *   3  — invocation problem (--skip-sigstore without pretrusted key,
+ *         missing binary, missing bundle, no cosign on PATH, ...)
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  buildTokenPayload,
+  computeBinaryAttestation,
+  deleteCacheToken,
+  getStateDir,
+  readCacheToken,
+  touchCacheToken,
+  writeCacheToken,
+} from '../cosign/cache-token.js';
+import { sha256File, verifyBinary } from '../cosign/verify-binary.js';
+
+const EXIT_OK = 0;
+const EXIT_VERIFY_FAILED = 2;
+const EXIT_INVOCATION = 3;
+
+/**
+ * Compute the cache fingerprint for a binary. We use the realpath +
+ * sha256 first 32 chars so two distinct binaries get distinct cache
+ * entries even if they share a directory layout, while keeping the
+ * filename short enough to be readable in `ls`.
+ */
+export function computeFingerprint(binaryRealpath, sha256) {
+  return `${path.basename(binaryRealpath).replace(/[^A-Za-z0-9._-]/g, '_')}.${sha256.slice(0, 16)}`;
+}
+
+function getTrustFilePath() {
+  if (process.env.PGSERVE_TRUST_FILE) return process.env.PGSERVE_TRUST_FILE;
+  const home = process.env.HOME || os.homedir();
+  return path.join(home, '.pgserve', 'trust', 'identities.json');
+}
+
+/**
+ * Load the operator-managed offline trust file. G3's `pgserve trust add
+ * --offline-cosign-key` writes to this path; in G4 we only consume it.
+ *
+ * Expected shape:
+ *   {
+ *     offlineKeys: [
+ *       { id: '<short-id>', publisher: '<package>', keyFingerprint: '...',
+ *         addedAt: '<ISO>' },
+ *       ...
+ *     ]
+ *   }
+ */
+function readOfflineTrust() {
+  const file = getTrustFilePath();
+  if (!fs.existsSync(file)) return { ok: false, reason: 'trust-file-missing', file };
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return { ok: false, reason: 'trust-file-unreadable', detail: err.message, file };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, reason: 'trust-file-malformed', detail: err.message, file };
+  }
+  const keys = Array.isArray(doc?.offlineKeys) ? doc.offlineKeys : null;
+  if (!keys || keys.length === 0) {
+    return { ok: false, reason: 'no-offline-keys', file };
+  }
+  return { ok: true, keys, file };
+}
+
+function parseArgs(args) {
+  const opts = {
+    binaryPath: null,
+    json: false,
+    skipSigstore: false,
+    bundlePath: null,
+    cosignBin: null,
+    allowFetch: false,
+    noCache: false,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--skip-sigstore') opts.skipSigstore = true;
+    else if (a === '--allow-fetch') opts.allowFetch = true;
+    else if (a === '--no-cache') opts.noCache = true;
+    else if (a === '--bundle') opts.bundlePath = args[++i];
+    else if (a === '--cosign-bin') opts.cosignBin = args[++i];
+    else if (a === '--help' || a === '-h') {
+      printHelp(process.stdout);
+      return { exit: EXIT_OK };
+    } else if (a.startsWith('-')) {
+      process.stderr.write(`pgserve verify: unknown option ${JSON.stringify(a)}\n`);
+      return { exit: EXIT_INVOCATION };
+    } else if (opts.binaryPath === null) {
+      opts.binaryPath = a;
+    } else {
+      process.stderr.write(`pgserve verify: unexpected positional argument ${JSON.stringify(a)}\n`);
+      return { exit: EXIT_INVOCATION };
+    }
+  }
+  if (!opts.binaryPath) {
+    printHelp(process.stderr);
+    return { exit: EXIT_INVOCATION };
+  }
+  return { opts };
+}
+
+function printHelp(stream) {
+  stream.write(`pgserve verify <binary-path> [options]
+
+Verify a binary against the cosign keyless OIDC trust list. On success,
+persists an HMAC-signed cache token so subsequent invocations short-circuit
+the cosign call until the binary changes (mtime/size) or the sliding
+expiry lapses (1h idle / 7d max).
+
+Options:
+  --json                 Emit a machine-readable JSON result on stdout
+  --skip-sigstore        Bypass cosign — requires \`pgserve trust add\` (G3)
+  --bundle <path>        Override the sigstore bundle sidecar path
+                         (default: <binary>.bundle)
+  --cosign-bin <path>    Override the cosign executable
+  --allow-fetch          Allow downloading cosign if missing
+  --no-cache             Never read or write the verified-cache token
+  --help, -h             Show this help
+
+Exit codes:
+  0  Verified (fresh or cache hit)
+  2  Verification failed
+  3  Invocation problem (missing binary/bundle/cosign/pretrusted key)
+`);
+}
+
+function emit({ json }, payload) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    return;
+  }
+  if (payload.ok) {
+    const tag = payload.cached ? 'cached' : 'verified';
+    process.stdout.write(`pgserve verify: ${tag} ${payload.binary} as ${payload.identity} (${payload.tier})\n`);
+    if (payload.cached === false) {
+      process.stdout.write(`pgserve verify: cache token written → ${payload.cacheFile}\n`);
+    }
+    return;
+  }
+  process.stderr.write(`pgserve verify: FAILED — ${payload.reason}${payload.detail ? `: ${payload.detail}` : ''}\n`);
+  if (payload.identityChain && payload.identityChain.length > 0) {
+    process.stderr.write(`pgserve verify: trust roots tried: ${JSON.stringify(payload.identityChain)}\n`);
+  }
+}
+
+/**
+ * Run the verify command. `argv` is the bare argument list AFTER the
+ * `verify` token. Returns an integer exit code.
+ */
+export function runVerify(argv) {
+  const parsed = parseArgs(argv);
+  if (parsed.exit !== undefined) return parsed.exit;
+  const opts = parsed.opts;
+
+  const binaryPath = path.resolve(opts.binaryPath);
+  if (!fs.existsSync(binaryPath)) {
+    emit(opts, { ok: false, reason: 'binary-missing', detail: binaryPath });
+    return EXIT_INVOCATION;
+  }
+
+  let attestation;
+  try {
+    attestation = computeBinaryAttestation(binaryPath);
+  } catch (err) {
+    emit(opts, { ok: false, reason: 'binary-attestation-failed', detail: err.message });
+    return EXIT_INVOCATION;
+  }
+  const sha256 = sha256File(binaryPath);
+  const fingerprint = computeFingerprint(attestation.realpath, sha256);
+
+  // ── Cache lookup ─────────────────────────────────────────────────────
+  if (!opts.noCache) {
+    const cache = readCacheToken(fingerprint, { binaryAttestation: attestation });
+    if (cache.ok) {
+      // PR #79 P1 security fix: honor the requested tier strictly. Without
+      // this gate, a token written under `--skip-sigstore` (tier:self_signed)
+      // would be accepted on a subsequent run WITHOUT `--skip-sigstore`,
+      // letting the operator bypass cosign verification entirely. The fix:
+      // - default invocation (no --skip-sigstore) requires tier:cosign_signed
+      // - --skip-sigstore invocation requires tier:self_signed
+      // Mismatched-tier cache hits are treated as cache misses (fall through
+      // to re-verify under the requested tier).
+      const cachedTier = cache.payload.tier;
+      const expectedTier = opts.skipSigstore ? 'self_signed' : 'cosign_signed';
+      if (cachedTier === expectedTier) {
+        // Tier matches — bump lastUsedAt and return.
+        touchCacheToken(cache.payload, {});
+        emit(opts, {
+          ok: true,
+          cached: true,
+          binary: binaryPath,
+          identity: cache.payload.identity,
+          tier: cachedTier,
+          sha256: cache.payload.sha256 || sha256,
+          cacheFile: cache.file,
+        });
+        return EXIT_OK;
+      }
+      // Tier mismatch — fall through. Do NOT delete the cache token: the
+      // existing token is valid for its own tier; we just need a fresh
+      // verification under the currently-requested tier.
+    }
+    // Stale binary attestation invalidates the cache so the new fingerprint
+    // wins. We delete defensively when the binary changed under us.
+    if (cache.reason === 'binary-changed') {
+      deleteCacheToken(fingerprint, {});
+    }
+  }
+
+  // ── --skip-sigstore path ─────────────────────────────────────────────
+  if (opts.skipSigstore) {
+    const trust = readOfflineTrust();
+    if (!trust.ok) {
+      emit(opts, {
+        ok: false,
+        reason: 'skip-sigstore-without-pretrusted-key',
+        detail:
+          `--skip-sigstore requires an offline trust entry. None found (${trust.reason}). `
+          + 'Operators must run `pgserve trust add --offline-cosign-key '
+          + '<key-file> --identity <id>` once Group 3 of the singleton wish ships. '
+          + `Trust file path: ${trust.file}`,
+      });
+      return EXIT_INVOCATION;
+    }
+    // Operator vouched for the binary via an offline-cosign-key entry; we
+    // record it as `self_signed` tier (NOT cosign_signed — this is a less
+    // strong attestation than a Sigstore OIDC chain).
+    const identity = trust.keys[0].id;
+    const payload = buildTokenPayload({
+      fingerprint,
+      binary: attestation,
+      identity,
+      tier: 'self_signed',
+      sha256,
+    });
+    let cacheFile = null;
+    if (!opts.noCache) {
+      try {
+        cacheFile = writeCacheToken(payload, {});
+      } catch (err) {
+        emit(opts, { ok: false, reason: 'cache-write-failed', detail: err.message });
+        return EXIT_VERIFY_FAILED;
+      }
+    }
+    emit(opts, {
+      ok: true,
+      cached: false,
+      binary: binaryPath,
+      identity,
+      tier: 'self_signed',
+      sha256,
+      cacheFile,
+      skipSigstore: true,
+    });
+    return EXIT_OK;
+  }
+
+  // ── Cosign path ──────────────────────────────────────────────────────
+  const result = verifyBinary(binaryPath, {
+    cosignBin: opts.cosignBin || process.env.PGSERVE_COSIGN_BIN || undefined,
+    bundlePath: opts.bundlePath || undefined,
+    allowFetch: opts.allowFetch === true,
+  });
+
+  if (!result.ok) {
+    emit(opts, {
+      ok: false,
+      reason: result.reason,
+      detail: result.detail,
+      identityChain: result.identityChain,
+    });
+    if (result.reason === 'binary-missing'
+        || result.reason === 'binary-unreadable'
+        || result.reason === 'binary-not-a-file'
+        || result.reason === 'bundle-missing'
+        || result.reason === 'cosign-missing'
+        || result.reason === 'empty-trust-list'
+        || result.reason === 'invalid-args') {
+      return EXIT_INVOCATION;
+    }
+    return EXIT_VERIFY_FAILED;
+  }
+
+  let cacheFile = null;
+  if (!opts.noCache) {
+    try {
+      const payload = buildTokenPayload({
+        fingerprint,
+        binary: attestation,
+        identity: result.identity,
+        tier: result.tier,
+        sha256: result.sha256,
+      });
+      cacheFile = writeCacheToken(payload, {});
+    } catch (err) {
+      emit(opts, { ok: false, reason: 'cache-write-failed', detail: err.message });
+      return EXIT_VERIFY_FAILED;
+    }
+  }
+  emit(opts, {
+    ok: true,
+    cached: false,
+    binary: binaryPath,
+    identity: result.identity,
+    publisher: result.publisher,
+    tier: result.tier,
+    sha256: result.sha256,
+    cacheFile,
+    bundle: result.bundle,
+    cosignBin: result.cosignBin,
+  });
+  return EXIT_OK;
+}
+
+// Convenience export so tests can introspect paths without re-implementing.
+export const _internals = {
+  computeFingerprint,
+  getStateDir,
+  getTrustFilePath,
+};