pgserve 2.4.0 → 2.5.0

package/src/cli-install.cjs

@@ -34,10 +34,15 @@ 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');
 
 async function loadCohortModules() {
-  const [adminJson, socketDirMod] = await Promise.all([_adminJsonModuleP, _socketDirModuleP]);
-  return { adminJson, socketDirMod };
+  const [adminJson, socketDirMod, runtimeJson] = await Promise.all([
+    _adminJsonModuleP,
+    _socketDirModuleP,
+    _runtimeJsonModuleP,
+  ]);
+  return { adminJson, socketDirMod, runtimeJson };
 }
 
 // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
@@ -165,6 +170,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 });
@@ -704,15 +834,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 +855,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 +898,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;
 }
 
@@ -913,6 +1076,13 @@ 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));
+    }
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }

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,
+};