pgserve 2.3.0 → 2.5.0

package/config/logrotate.d/pgserve

@@ -0,0 +1,47 @@
+# pgserve singleton (v2.4) — logrotate config for the pm2 / systemd-user
+# / launchd-supervised postmaster.
+#
+# Postgres' stderr (where pgaudit's audit log lands when the .so is
+# present, and `log_statement=all` lands in the fallback path) is captured
+# by the supervisor and written to:
+#
+#   ~/.autopg/logs/autopg-server-out.log
+#   ~/.autopg/logs/autopg-server-error.log
+#
+# Symbolic ~/ resolves under each operator's HOME — logrotate runs the
+# rules per-user when invoked with `--state ~/.config/logrotate.state`
+# (see the autopg installer hint). The `su` directive is intentionally
+# absent: this config ships as a USER-context drop-in, not a system one.
+# System-wide rotation under a dedicated `autopg` UNIX user is delivered
+# by the separate `autopg-service-install-system` wish (out of scope for
+# v2.4).
+#
+# Copy or symlink to:   /etc/logrotate.d/pgserve  (system-wide)
+# Or use per-user:      ~/.config/logrotate.d/pgserve
+
+~/.autopg/logs/autopg-server-out.log
+~/.autopg/logs/autopg-server-error.log
+~/.pgserve/audit.log
+{
+    # Daily rotation keeps audit/forensic events queryable for ~2 weeks
+    # without burning disk on a long-running dev host.
+    daily
+    rotate 14
+    # Compress yesterday's log on tomorrow's rotation so today's log stays
+    # uncompressed for tail/grep.
+    compress
+    delaycompress
+    # Don't fail when a log file has not been created yet (e.g. fresh
+    # `autopg install` before the postmaster has emitted any output).
+    missingok
+    # Don't fail when a log file is empty.
+    notifempty
+    # Truncate-in-place so pm2 / systemd / launchd's open file handles
+    # keep writing to the rotated file. Avoids the "send SIGHUP and
+    # postgres re-opens" dance which we don't want to trigger from a
+    # supervisor-agnostic rule.
+    copytruncate
+    # File mode 0600: audit lines may include literal SQL (parameter
+    # values, error contexts) — operator-only on a multi-user host.
+    create 0600
+}

package/config/pgaudit.conf

@@ -0,0 +1,31 @@
+# pgserve singleton (v2.4) — pgaudit GUC defaults.
+#
+# Loaded by `src/postgres.js::_startPostgres` when the embedded postgres
+# bundle ships pgaudit.so. The postmaster passes these as `-c key=value`
+# pairs at boot; settings.json `_extra` overrides apply on top via the
+# normal curated < extra precedence.
+#
+# When pgaudit.so is NOT present in the bundle (the current state of the
+# `@embedded-postgres/<plat>-<arch>` packages), postgres.js falls back to
+# `log_statement=all`. The cohort sibling `autopg-distribution-cutover`
+# owns shipping the pgaudit binary; this file documents the GUCs that
+# light up the moment the .so lands.
+
+shared_preload_libraries = 'pgaudit'
+
+# `pgaudit.log = 'all'` is the audit-log breadth contract from the wish.
+# Operators who need a tighter classification (e.g. drop READ to cut log
+# volume on hot read paths) override via:
+#   ~/.autopg/settings.json -> postgres._extra.pgaudit.log = 'write,role,ddl'
+pgaudit.log = 'all'
+
+# Skip pg_catalog reads — they are constant per session and their
+# inclusion floods the audit log without forensic value.
+pgaudit.log_catalog = off
+
+# Audit lines emit on the postmaster's stderr, captured by the supervisor
+# (pm2 -> ~/.autopg/logs/autopg-server-error.log; systemd-user -> journal;
+# launchd -> launchd-managed plist log path). The legacy
+# ~/.pgserve/audit.log path stays rotated by `config/logrotate.d/pgserve`
+# so existing tooling parsing the file keeps working through the
+# migration window.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -11,6 +11,7 @@
   "files": [
     "bin/",
     "src/",
+    "config/",
     "console/dist/",
     "README.md",
     "CHANGELOG.md",
@@ -19,7 +20,6 @@
     "scripts/"
   ],
   "scripts": {
-    "bench": "bun tests/benchmarks/runner.js",
     "test": "bun test tests/**/*.test.js",
     "test:watch": "bun test --watch tests/**/*.test.js",
     "dev": "bun --watch bin/postgres-server.js",
@@ -30,6 +30,7 @@
     "console:dev": "bun build console/src/main.jsx --target browser --define 'process.env.NODE_ENV=\"development\"' --watch --outfile console/dist/app.js",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",
+    "lint:audit": "bun scripts/audit-redaction-lint.js",
     "deadcode": "knip",
     "test:npx": "scripts/test-npx.sh",
     "test:bun-self-heal": "scripts/test-bun-self-heal.sh",

package/scripts/audit-redaction-lint.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env bun
+/**
+ * Audit redaction lint — Group 6, autopg-distribution-cutover.
+ *
+ * Walks every .js / .cjs source under `src/` (excluding `src/audit/audit.js`
+ * itself) and locates every `auditEmit(...)` call. For each call site, the
+ * lint asserts:
+ *
+ *   1. No object-literal key matches /password|secret|token|connection_string|database_url/i.
+ *   2. No value is `process.env.*PASSWORD*|*SECRET*|*TOKEN*|*DATABASE_URL*|*CONNECTION_STRING*`.
+ *   3. No string-literal value looks like a `postgres://user:pass@host/...` URL.
+ *
+ * Failure = exit 1 with file:line per offending site. Clean tree = exit 0.
+ *
+ * The walker is a hand-rolled scanner rather than a full parser: it tracks
+ * string state (single, double, backtick), template-literal nesting, line
+ * comments, block comments, and balanced brace depth. That's enough to
+ * isolate the first object-literal argument of every `auditEmit(...)` call
+ * without pulling in a parser dependency. New AST-flavored rules can be
+ * added by extending `scanRecord()`.
+ *
+ * Usage:
+ *   bun run scripts/audit-redaction-lint.js
+ *   bun run scripts/audit-redaction-lint.js path/to/file.js
+ *   bun run scripts/audit-redaction-lint.js --fixture tests/audit/fixtures
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const REPO_ROOT = path.resolve(import.meta.dir, '..');
+const DEFAULT_ROOT = path.join(REPO_ROOT, 'src');
+const SELF_EXCLUDE = path.join('src', 'audit', 'audit.js');
+
+const FORBIDDEN_KEY_RE = /^(password|secret|token|connection_string|database_url)$/i;
+const ENV_SECRET_RE =
+  /process\.env\.[A-Za-z_][A-Za-z0-9_]*(PASSWORD|SECRET|TOKEN|DATABASE_URL|CONNECTION_STRING)[A-Za-z0-9_]*\b/i;
+const POSTGRES_URL_RE = /\bpostgres(?:ql)?:\/\/[^\s'"]*:[^\s'"@]+@/i;
+
+function listSourceFiles(roots) {
+  const out = [];
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    const stat = fs.statSync(root);
+    if (stat.isFile()) {
+      if (/\.(js|cjs|mjs)$/.test(root)) out.push(root);
+      continue;
+    }
+    walk(root, out);
+  }
+  return out.filter((p) => !p.endsWith(SELF_EXCLUDE));
+}
+
+function walk(dir, out) {
+  for (const name of fs.readdirSync(dir)) {
+    if (name === 'node_modules' || name.startsWith('.')) continue;
+    const full = path.join(dir, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (/\.(js|cjs|mjs)$/.test(name)) {
+      out.push(full);
+    }
+  }
+}
+
+/**
+ * Find every `auditEmit(...)` call in `src` and yield each one's first
+ * argument span (the object literal between `{` and matching `}`), plus
+ * the file-relative line number of the `auditEmit` identifier.
+ */
+function* findAuditEmitCalls(src) {
+  const len = src.length;
+  let i = 0;
+  let line = 1;
+
+  const isIdentChar = (ch) => /[A-Za-z0-9_$]/.test(ch);
+
+  while (i < len) {
+    const ch = src[i];
+
+    // Track newlines for accurate line reporting.
+    if (ch === '\n') { line++; i++; continue; }
+
+    // Skip line comments.
+    if (ch === '/' && src[i + 1] === '/') {
+      while (i < len && src[i] !== '\n') i++;
+      continue;
+    }
+    // Skip block comments.
+    if (ch === '/' && src[i + 1] === '*') {
+      i += 2;
+      while (i < len && !(src[i] === '*' && src[i + 1] === '/')) {
+        if (src[i] === '\n') line++;
+        i++;
+      }
+      i += 2;
+      continue;
+    }
+    // Skip strings.
+    if (ch === '"' || ch === "'" || ch === '`') {
+      i = skipString(src, i, ch, (n) => { line += n; });
+      continue;
+    }
+
+    // Match `auditEmit` as a whole identifier (must be word-boundary-prefixed).
+    if (ch === 'a' && src.startsWith('auditEmit', i)) {
+      const before = src[i - 1];
+      const after = src[i + 'auditEmit'.length];
+      if ((!before || !isIdentChar(before)) && !isIdentChar(after)) {
+        const idLine = line;
+        // Advance past identifier, skip whitespace, expect '('.
+        let j = i + 'auditEmit'.length;
+        while (j < len && /\s/.test(src[j])) {
+          if (src[j] === '\n') line++;
+          j++;
+        }
+        if (src[j] === '(') {
+          // Now find first `{` (the object-literal arg start) before the
+          // matching ')'. Object literals as function args appear directly
+          // after `(` (perhaps after whitespace) — but `auditEmit` callers
+          // pass an object literal by spec, so this is the path we care
+          // about. If we find a `)` first, it's auditEmit() with no
+          // object-literal arg → not redaction-relevant; skip.
+          let k = j + 1;
+          while (k < len) {
+            const c = src[k];
+            if (c === '\n') { line++; k++; continue; }
+            if (/\s/.test(c)) { k++; continue; }
+            if (c === '/' && src[k + 1] === '/') {
+              while (k < len && src[k] !== '\n') k++;
+              continue;
+            }
+            if (c === '/' && src[k + 1] === '*') {
+              k += 2;
+              while (k < len && !(src[k] === '*' && src[k + 1] === '/')) {
+                if (src[k] === '\n') line++;
+                k++;
+              }
+              k += 2;
+              continue;
+            }
+            break;
+          }
+          if (src[k] === '{') {
+            const literalLine = line;
+            const end = findBalanced(src, k, '{', '}', (n) => { line += n; });
+            if (end !== -1) {
+              const literal = src.slice(k, end + 1);
+              yield { call: 'auditEmit', idLine, literalLine, literal };
+              i = end + 1;
+              continue;
+            }
+          }
+        }
+      }
+    }
+
+    i++;
+  }
+}
+
+function skipString(src, i, quote, onNewline) {
+  // Returns the index just past the closing quote.
+  const len = src.length;
+  i++; // open quote
+  while (i < len) {
+    const ch = src[i];
+    if (ch === '\\') { i += 2; continue; }
+    if (ch === '\n') { onNewline(1); i++; continue; }
+    if (ch === quote) { return i + 1; }
+    if (quote === '`' && ch === '$' && src[i + 1] === '{') {
+      // Template literal interpolation — find matching `}`.
+      i = findBalanced(src, i + 1, '{', '}', onNewline);
+      if (i === -1) return len;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return len;
+}
+
+function findBalanced(src, start, open, close, onNewline) {
+  const len = src.length;
+  let depth = 0;
+  let i = start;
+  while (i < len) {
+    const ch = src[i];
+    if (ch === '\n') { onNewline(1); i++; continue; }
+    if (ch === '/' && src[i + 1] === '/') {
+      while (i < len && src[i] !== '\n') i++;
+      continue;
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      i += 2;
+      while (i < len && !(src[i] === '*' && src[i + 1] === '/')) {
+        if (src[i] === '\n') onNewline(1);
+        i++;
+      }
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      i = skipString(src, i, ch, onNewline);
+      continue;
+    }
+    if (ch === open) depth++;
+    else if (ch === close) {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * Walk the captured object-literal source and pull out each top-level key.
+ * Skips nested objects/arrays so a nested `meta: { secret: 'x' }` is still
+ * caught (see scanForNestedSecrets) — but the simple flat-key shape is the
+ * primary check.
+ */
+function extractTopLevelKeys(literal) {
+  // Drop the outer braces.
+  if (literal[0] !== '{' || literal[literal.length - 1] !== '}') return [];
+  const inner = literal.slice(1, -1);
+  const keys = [];
+  let i = 0;
+  let line = 0;
+  const len = inner.length;
+  let depth = 0;
+  let atKeyPosition = true;
+
+  while (i < len) {
+    const ch = inner[i];
+    if (ch === '\n') { line++; i++; continue; }
+    if (ch === '/' && inner[i + 1] === '/') {
+      while (i < len && inner[i] !== '\n') i++;
+      continue;
+    }
+    if (ch === '/' && inner[i + 1] === '*') {
+      i += 2;
+      while (i < len && !(inner[i] === '*' && inner[i + 1] === '/')) {
+        if (inner[i] === '\n') line++;
+        i++;
+      }
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const next = skipString(inner, i, ch, (n) => { line += n; });
+      if (depth === 0 && atKeyPosition) {
+        const raw = inner.slice(i + 1, next - 1);
+        keys.push({ name: raw, line });
+        atKeyPosition = false;
+      }
+      i = next;
+      continue;
+    }
+    if (ch === '{' || ch === '[' || ch === '(') { depth++; atKeyPosition = false; i++; continue; }
+    if (ch === '}' || ch === ']' || ch === ')') { depth--; i++; continue; }
+    if (ch === ',' && depth === 0) { atKeyPosition = true; i++; continue; }
+    if (ch === ':' && depth === 0) { atKeyPosition = false; i++; continue; }
+    if (depth === 0 && atKeyPosition && /[A-Za-z_$]/.test(ch)) {
+      const start = i;
+      while (i < len && /[A-Za-z0-9_$]/.test(inner[i])) i++;
+      const name = inner.slice(start, i);
+      keys.push({ name, line });
+      atKeyPosition = false;
+      continue;
+    }
+    i++;
+  }
+  return keys;
+}
+
+function lintFile(file) {
+  const src = fs.readFileSync(file, 'utf8');
+  const errors = [];
+  const rel = path.relative(REPO_ROOT, file);
+
+  for (const call of findAuditEmitCalls(src)) {
+    const keys = extractTopLevelKeys(call.literal);
+    for (const key of keys) {
+      if (FORBIDDEN_KEY_RE.test(key.name)) {
+        errors.push({
+          file: rel,
+          line: call.literalLine + key.line,
+          message: `auditEmit field "${key.name}" matches forbidden secret pattern (${FORBIDDEN_KEY_RE})`,
+        });
+      }
+    }
+    // Value-side checks run on the whole literal: env-secret references and
+    // postgres:// URLs would be caught here even if buried inside nested
+    // objects.
+    const envMatch = call.literal.match(ENV_SECRET_RE);
+    if (envMatch) {
+      const offset = envMatch.index || 0;
+      const lineOffset = call.literal.slice(0, offset).split('\n').length - 1;
+      errors.push({
+        file: rel,
+        line: call.literalLine + lineOffset,
+        message: `auditEmit value sources from secret env var: ${envMatch[0]}`,
+      });
+    }
+    const urlMatch = call.literal.match(POSTGRES_URL_RE);
+    if (urlMatch) {
+      const offset = urlMatch.index || 0;
+      const lineOffset = call.literal.slice(0, offset).split('\n').length - 1;
+      errors.push({
+        file: rel,
+        line: call.literalLine + lineOffset,
+        message: `auditEmit value contains postgres URL with embedded password: ${urlMatch[0]}…`,
+      });
+    }
+  }
+  return errors;
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  let roots;
+  if (args.length === 0) {
+    roots = [DEFAULT_ROOT];
+  } else {
+    roots = args.map((a) => path.resolve(a));
+  }
+  const files = listSourceFiles(roots);
+  const allErrors = [];
+  for (const f of files) {
+    allErrors.push(...lintFile(f));
+  }
+  if (allErrors.length === 0) {
+    console.log(`audit-redaction-lint: scanned ${files.length} file(s); 0 issues.`);
+    return 0;
+  }
+  for (const err of allErrors) {
+    console.error(`${err.file}:${err.line}: ${err.message}`);
+  }
+  console.error(`audit-redaction-lint: ${allErrors.length} issue(s) across ${files.length} file(s).`);
+  return 1;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv));
+}
+
+export { lintFile, findAuditEmitCalls, extractTopLevelKeys, listSourceFiles };

package/scripts/test-npx.sh

@@ -1,10 +1,15 @@
 #!/bin/bash
 # Test that the package works with npx (simulates fresh user install)
-# This catches path resolution issues that static analysis can't detect
+# This catches path resolution issues that static analysis can't detect.
+#
+# v2.4 contract change (2026-05-08): `pgserve` (no args) now prints help and
+# exits cleanly. The long-running entry is `pgserve postmaster` (or its
+# `pgserve serve` alias). This test invokes the postmaster directly to verify
+# npx-installed bits boot a real PG.
 
 set -e
 
-echo "=== Testing npx compatibility ==="
+echo "=== Testing npx compatibility (v2.4 postmaster entry) ==="
 
 # Create temp directory
 TEST_DIR=$(mktemp -d)
@@ -29,22 +34,39 @@ cd "$TEST_DIR"
 echo '{"name":"test-npx-install","private":true}' > package.json
 npm install "./$PACK_FILE" > /dev/null 2>&1
 
-# Test that it starts (with timeout)
-echo "Testing server startup via npx..."
-timeout 30 npx pgserve --no-cluster --port 15432 > output.log 2>&1 &
+# Verify the bare invocation prints v2.4 help and exits 0 (regression guard
+# for the breaking-cut: pre-v2.4 auto-started a server here).
+echo "Verifying bare 'npx pgserve' prints v2.4 help and exits cleanly..."
+HELP_OUT=$(npx pgserve 2>&1)
+if ! echo "$HELP_OUT" | grep -q "pgserve postmaster"; then
+  echo "✗ Bare 'npx pgserve' output does not match v2.4 help (missing 'pgserve postmaster')"
+  echo "Output:"
+  echo "$HELP_OUT"
+  echo "=== npx test FAILED ==="
+  exit 1
+fi
+echo "✓ Bare invocation prints v2.4 help"
+
+# Test that the postmaster entry starts (with timeout)
+DATA_DIR="$TEST_DIR/data"
+SOCKET_DIR="$TEST_DIR/sock"
+mkdir -p "$DATA_DIR" "$SOCKET_DIR"
+echo "Testing postmaster startup via npx (port 15432)..."
+timeout 30 npx pgserve postmaster --port 15432 --data "$DATA_DIR" --socket-dir "$SOCKET_DIR" > output.log 2>&1 &
 PID=$!
 
-# Wait for ready signal (Server started successfully!)
+# Wait for ready signal — bin/postgres-server.js logs
+# 'pgserve postmaster: ready (Unix socket + TCP)' once both transports are bound.
 for i in {1..60}; do
-  if grep -q "Server started successfully" output.log 2>/dev/null; then
-    echo "✓ Server started successfully via npx"
+  if grep -q "pgserve postmaster: ready" output.log 2>/dev/null; then
+    echo "✓ Postmaster started successfully via npx"
     kill $PID 2>/dev/null || true
     wait $PID 2>/dev/null || true
     echo "=== npx test PASSED ==="
     exit 0
   fi
   if ! kill -0 $PID 2>/dev/null; then
-    echo "✗ Server exited unexpectedly"
+    echo "✗ Postmaster exited unexpectedly"
     cat output.log
     echo "=== npx test FAILED ==="
     exit 1
@@ -54,7 +76,7 @@ done
 
 # Timeout
 kill $PID 2>/dev/null || true
-echo "✗ Server did not start within timeout"
+echo "✗ Postmaster did not start within timeout"
 cat output.log
 echo "=== npx test FAILED ==="
 exit 1

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 */ }
+}
+