@bongos/core 1.17.0

package/src/bongos/metrics.js

@@ -0,0 +1,286 @@
+// src/bongos/metrics.js — zero-dependency Prometheus exporter (task #1680, V4.R28a).
+//
+// The foundation slice of the observability dashboard (R28 / task 263): a
+// /metrics endpoint the droplet's Prometheus scrapes, feeding the Grafana
+// dashboards that land in task 263. We hand-roll the Prometheus text exposition
+// format rather than add `prom-client` — the project's bootstrapped posture
+// keeps package.json deps minimal, and the format is small + easy to test.
+//
+// CORE-SAFE: lives under src/bongos/ so it's held to the core↔host import boundary
+// (scripts/gds/fitness.js §1) — it imports only ./pool + ../build-info, nothing
+// from the game runtime, so a non-game Cloud Bongos instance runs it unchanged.
+//
+// WHAT IT EXPOSES
+//   - process/runtime: uptime, RSS, heap, CPU (counter), event-loop lag, build_info
+//   - HTTP (from httpMiddleware): gds_http_requests_total{method,route,status} +
+//     gds_http_request_duration_seconds histogram — route normalized to a
+//     low-cardinality template so /api/gds/tasks/1380 and /…/1381 share a series.
+//     Gives error-rate + 4xx/5xx per route. 401/403 also bump gds_auth_failures_total.
+//   - DB gauges (collected at scrape, read-only — never instruments the gate-floor
+//     ship pipeline): tasks-by-status, claims (all-time + active), builders-by-rank,
+//     per-active-builder shipped-tasks + credits.
+//
+// ACCESS: /metrics is NOT public. authorizeScrape() allows (a) a local Prometheus
+// scrape — loopback remote address with no proxy header — and (b) a Bearer
+// METRICS_TOKEN for a remote scrape. Everything else gets a 404.
+
+'use strict';
+
+const { pool } = require('./pool');
+
+const HIST_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+// --- registry -------------------------------------------------------------
+// counters:   name -> { help, series: Map(labelKey -> { labels, value }) }
+// histograms: name -> { help, series: Map(labelKey -> { labels, buckets:int[], sum, count }) }
+const counters = new Map();
+const histograms = new Map();
+
+function labelKey(labels) {
+  const keys = Object.keys(labels).sort();
+  return keys.map((k) => `${k}=${labels[k]}`).join(',');
+}
+
+function escapeLabelValue(v) {
+  return String(v).replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
+}
+
+function renderLabels(labels) {
+  const keys = Object.keys(labels);
+  if (keys.length === 0) return '';
+  return '{' + keys.map((k) => `${k}="${escapeLabelValue(labels[k])}"`).join(',') + '}';
+}
+
+function incCounter(name, help, labels = {}, by = 1) {
+  let c = counters.get(name);
+  if (!c) { c = { help, series: new Map() }; counters.set(name, c); }
+  const key = labelKey(labels);
+  const s = c.series.get(key);
+  if (s) s.value += by;
+  else c.series.set(key, { labels, value: by });
+}
+
+function observeHistogram(name, help, labels, value) {
+  let h = histograms.get(name);
+  if (!h) { h = { help, series: new Map() }; histograms.set(name, h); }
+  const key = labelKey(labels);
+  let s = h.series.get(key);
+  if (!s) { s = { labels, buckets: new Array(HIST_BUCKETS.length).fill(0), sum: 0, count: 0 }; h.series.set(key, s); }
+  s.count += 1;
+  s.sum += value;
+  for (let i = 0; i < HIST_BUCKETS.length; i++) {
+    if (value <= HIST_BUCKETS[i]) s.buckets[i] += 1;
+  }
+}
+
+// --- event-loop lag sampler (unref'd so it never holds the process open) ---
+let _lagSeconds = 0;
+const _LAG_INTERVAL_MS = 1000;
+const _lagTimer = setInterval(() => {
+  const start = process.hrtime.bigint();
+  setImmediate(() => {
+    const drift = Number(process.hrtime.bigint() - start) / 1e9;
+    _lagSeconds = drift > 0 ? drift : 0;
+  });
+}, _LAG_INTERVAL_MS);
+if (_lagTimer.unref) _lagTimer.unref();
+
+// --- route normalization (bounds label cardinality) -----------------------
+function normalizeRoute(p) {
+  if (!p || p === '/') return '/';
+  const parts = p.split('/').filter(Boolean).slice(0, 6).map((seg) => {
+    if (/^\d+$/.test(seg)) return ':id';
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(seg)) return ':uuid';
+    // Any embedded 8+ hex run = a content-hashed asset (atlas-89d47b50.png) or
+    // an opaque token — collapse so per-deploy asset names don't grow cardinality.
+    // Route words in this namespace (tasks/claims/resolve/…) have no 8-hex run.
+    if (/[0-9a-f]{8,}/i.test(seg)) return ':hash';
+    return seg;
+  });
+  return '/' + parts.join('/');
+}
+
+// --- HTTP middleware ------------------------------------------------------
+function httpMiddleware() {
+  return (req, res, next) => {
+    // Don't count the scrape itself or the liveness ping — pure noise.
+    if (req.path === '/metrics' || req.path === '/healthz') return next();
+    const start = process.hrtime.bigint();
+    res.on('finish', () => {
+      const route = normalizeRoute(req.path);
+      const method = req.method;
+      const status = res.statusCode;
+      incCounter('gds_http_requests_total', 'Total HTTP requests by method, normalized route, and status code.',
+        { method, route, status: String(status) });
+      const dur = Number(process.hrtime.bigint() - start) / 1e9;
+      observeHistogram('gds_http_request_duration_seconds', 'HTTP request duration in seconds.',
+        { method, route }, dur);
+      if (status === 401 || status === 403) {
+        incCounter('gds_auth_failures_total', 'HTTP responses denied for auth reasons (401/403).',
+          { code: String(status) });
+      }
+    });
+    next();
+  };
+}
+
+// --- access gate for the scrape -------------------------------------------
+function authorizeScrape(req) {
+  const get = (h) => (typeof req.get === 'function' ? req.get(h) : (req.headers || {})[h]);
+  const token = process.env.METRICS_TOKEN;
+  if (token && get('authorization') === `Bearer ${token}`) return true;
+  // A local Prometheus scrapes 127.0.0.1:3000 directly (no proxy hop), so a
+  // loopback remote address with NO forwarding header is the local agent.
+  // Public traffic arrives via Caddy, which always sets X-Forwarded-For.
+  const xff = get('x-forwarded-for') || get('x-real-ip');
+  const ra = (req.socket && req.socket.remoteAddress) || req.ip || '';
+  const loopback = ra === '127.0.0.1' || ra === '::1' || ra === '::ffff:127.0.0.1';
+  return !!loopback && !xff;
+}
+
+// --- text rendering -------------------------------------------------------
+function renderCounterText(name, help, series) {
+  const out = [`# HELP ${name} ${help}`, `# TYPE ${name} counter`];
+  for (const s of series) out.push(`${name}${renderLabels(s.labels)} ${s.value}`);
+  return out.join('\n');
+}
+
+function renderGaugeText(name, help, series) {
+  const out = [`# HELP ${name} ${help}`, `# TYPE ${name} gauge`];
+  for (const s of series) out.push(`${name}${renderLabels(s.labels)} ${s.value}`);
+  return out.join('\n');
+}
+
+function renderHistogram(name, h) {
+  const out = [`# HELP ${name} ${h.help}`, `# TYPE ${name} histogram`];
+  for (const s of h.series.values()) {
+    let cumulative = 0;
+    for (let i = 0; i < HIST_BUCKETS.length; i++) {
+      cumulative += s.buckets[i];
+      const le = HIST_BUCKETS[i];
+      out.push(`${name}_bucket${renderLabels({ ...s.labels, le: String(le) })} ${cumulative}`);
+    }
+    out.push(`${name}_bucket${renderLabels({ ...s.labels, le: '+Inf' })} ${s.count}`);
+    out.push(`${name}_sum${renderLabels(s.labels)} ${s.sum}`);
+    out.push(`${name}_count${renderLabels(s.labels)} ${s.count}`);
+  }
+  return out.join('\n');
+}
+
+function buildInfoSafe() {
+  try {
+    const { buildInfo } = require('../build-info');
+    const bi = buildInfo() || {};
+    return { version: String(bi.commit || bi.version || 'unknown').slice(0, 40) };
+  } catch {
+    return { version: 'unknown' };
+  }
+}
+
+// DB-derived gauges. Read-only; pass a client for tests. Resilient: a failure
+// here must not 500 the scrape (the caller wraps it), so the in-process metrics
+// always render even if Postgres is briefly unreachable.
+async function collectDbGauges(p = pool) {
+  const blocks = [];
+
+  const tasks = await p.query('SELECT status, count(*)::int AS n FROM tasks GROUP BY status');
+  blocks.push(renderGaugeText('gds_tasks', 'Tasks by lifecycle status.',
+    tasks.rows.map((r) => ({ labels: { status: r.status }, value: r.n }))));
+
+  const claims = await p.query(
+    "SELECT count(*)::int AS total, count(*) FILTER (WHERE released_at IS NULL)::int AS active FROM claims");
+  blocks.push(renderGaugeText('gds_claims_total', 'All-time claim count (monotonic — use for claim rate).',
+    [{ labels: {}, value: claims.rows[0].total }]));
+  blocks.push(renderGaugeText('gds_claims_active', 'Currently active (unreleased) claims.',
+    [{ labels: {}, value: claims.rows[0].active }]));
+
+  const builders = await p.query('SELECT rank, count(*)::int AS n FROM builders GROUP BY rank');
+  blocks.push(renderGaugeText('gds_builders', 'Builders by rank.',
+    builders.rows.map((r) => ({ labels: { rank: r.rank }, value: r.n }))));
+
+  const perBuilder = await p.query(
+    `SELECT b.github_login,
+            b.total_credits::int AS credits,
+            (SELECT count(*) FROM tasks t WHERE t.shipped_by = b.id AND t.status = 'shipped')::int AS shipped
+       FROM builders b
+      WHERE b.status = 'active'`);
+  blocks.push(renderGaugeText('gds_builder_shipped_tasks', 'Shipped tasks per active builder.',
+    perBuilder.rows.map((r) => ({ labels: { builder: r.github_login }, value: r.shipped }))));
+  blocks.push(renderGaugeText('gds_builder_credits', 'Total credits per active builder.',
+    perBuilder.rows.map((r) => ({ labels: { builder: r.github_login }, value: r.credits }))));
+
+  return blocks.join('\n');
+}
+
+// Full exposition document. `p` injectable for tests.
+async function render(p = pool) {
+  const out = [];
+  const mem = process.memoryUsage();
+  const cpu = process.cpuUsage(); // microseconds, cumulative since start
+
+  out.push(renderGaugeText('gds_process_uptime_seconds', 'Process uptime in seconds.',
+    [{ labels: {}, value: process.uptime() }]));
+  out.push(renderGaugeText('gds_process_resident_memory_bytes', 'Resident set size in bytes.',
+    [{ labels: {}, value: mem.rss }]));
+  out.push(renderGaugeText('gds_process_heap_used_bytes', 'V8 heap used in bytes.',
+    [{ labels: {}, value: mem.heapUsed }]));
+  out.push(renderGaugeText('gds_process_heap_total_bytes', 'V8 heap total in bytes.',
+    [{ labels: {}, value: mem.heapTotal }]));
+  out.push(renderCounterText('gds_process_cpu_user_seconds_total', 'Total user CPU seconds.',
+    [{ labels: {}, value: cpu.user / 1e6 }]));
+  out.push(renderCounterText('gds_process_cpu_system_seconds_total', 'Total system CPU seconds.',
+    [{ labels: {}, value: cpu.system / 1e6 }]));
+  out.push(renderGaugeText('gds_nodejs_eventloop_lag_seconds', 'Sampled event-loop lag in seconds.',
+    [{ labels: {}, value: _lagSeconds }]));
+  out.push(renderGaugeText('gds_build_info', 'Deployed build info (constant 1; data in labels).',
+    [{ labels: { version: buildInfoSafe().version, node: process.version }, value: 1 }]));
+
+  for (const [name, c] of counters) out.push(renderCounterText(name, c.help, [...c.series.values()]));
+  for (const [name, h] of histograms) out.push(renderHistogram(name, h));
+
+  try {
+    out.push(await collectDbGauges(p));
+    out.push(renderGaugeText('gds_db_scrape_ok', '1 if the last DB-gauge scrape succeeded, 0 otherwise.',
+      [{ labels: {}, value: 1 }]));
+  } catch {
+    out.push(renderGaugeText('gds_db_scrape_ok', '1 if the last DB-gauge scrape succeeded, 0 otherwise.',
+      [{ labels: {}, value: 0 }]));
+  }
+
+  return out.filter(Boolean).join('\n') + '\n';
+}
+
+function metricsHandler() {
+  return async (req, res) => {
+    if (!authorizeScrape(req)) {
+      res.status(404).type('text/plain').send('not found');
+      return;
+    }
+    try {
+      const body = await render();
+      res.set('Content-Type', 'text/plain; version=0.0.4; charset=utf-8').send(body);
+    } catch {
+      res.status(500).type('text/plain').send('# metrics render error\n');
+    }
+  };
+}
+
+// Test seam — wipe the in-process registry between cases.
+function __resetForTests() {
+  counters.clear();
+  histograms.clear();
+  _lagSeconds = 0;
+}
+
+module.exports = {
+  incCounter,
+  observeHistogram,
+  normalizeRoute,
+  httpMiddleware,
+  authorizeScrape,
+  collectDbGauges,
+  render,
+  metricsHandler,
+  HIST_BUCKETS,
+  __resetForTests,
+};

package/src/bongos/middleware/audit.js

@@ -0,0 +1,274 @@
+// src/bongos/middleware/audit.js — append-only audit log for authenticated writes
+// (V3.R35 / #256).
+//
+// Wire-up: mounted INSIDE the /api/gds sub-router by routes.js, AFTER the JSON
+// body parser and AFTER each route's auth middleware has run (the middleware
+// fires on res 'finish', so by then auth either populated req.builder or sent
+// a 401 — both cases are handled below).
+//
+// What it captures:
+//   - Every authenticated POST/PATCH/PUT/DELETE that the /api/gds router
+//     served. Reads (GET) are explicitly skipped — they're high-volume and
+//     low-signal for forensics.
+//   - The redacted request body, the response status the client actually saw,
+//     IP, User-Agent.
+//
+// Redaction:
+//   - Walks the parsed JSON body recursively. Any KEY whose lower-cased name
+//     contains 'token', 'password', 'key', or 'secret' has its value replaced
+//     with the literal string '<redacted>'. Recurses into nested objects AND
+//     arrays. Non-plain values (numbers, booleans, strings) are not deepened.
+//   - Top-level primitives (the rare API that does `app.use(express.text())`
+//     and POSTs a raw string) just get the body stringified into
+//     { _value: <body> } so the column always carries an object.
+//
+// CRITICAL fail-safety properties (verified by tests/audit_middleware.mjs):
+//   1. The middleware NEVER throws upward. The only way it can affect the
+//      request path is by populating req.* — and it does not. We attach to
+//      res.on('finish'), which runs after the response has been sent.
+//   2. If logging fails (DB down, schema mismatch, jsonb shape error, anything)
+//      the error is caught, logged to console.error, and swallowed. The user
+//      already got their response; the audit miss is a known acceptable
+//      degradation per the design.
+//   3. The 'finish' handler does its DB work in a fire-and-forget Promise so
+//      the response is never delayed by audit I/O.
+//
+// Why not a Postgres trigger? — Two reasons. (a) Several writable surfaces
+// (e.g. session cookies, OAuth callbacks) don't touch a single canonical
+// table, so per-table triggers would miss them. (b) The route-shaped log
+// ('/tasks/:id', 'POST', the redacted body) is what makes the R67 security
+// view useful; that information is lost at the SQL layer.
+
+const db = require('../db');
+
+const REDACTION_TOKENS = ['token', 'password', 'key', 'secret'];
+const REDACTED = '<redacted>';
+
+// Audit-body byte cap (SR-17 / task 997). The middleware stores a copy of every
+// authenticated write body in audit_log. Routes that mount their own large body
+// parser (POST /sessions, /memory/sync — well above the 64 KB global cap) could
+// therefore write an UNBOUNDED second copy of a multi-MB payload here, doubling
+// the disk-fill pressure of the primary write. We cap the SERIALIZED stored body
+// to MAX_AUDIT_BODY_BYTES and replace an over-cap body with a small marker object
+// that preserves the redacted prefix + the original size — enough for forensics,
+// bounded on disk. 8 KB is generous for ordinary writes (task patches, claims,
+// cost rows are all far under) while ensuring a fat upload can't bloat audit_log.
+const MAX_AUDIT_BODY_BYTES = 8 * 1024;
+
+// shouldRedactKey — case-insensitive substring match against the redaction
+// vocabulary. Exported for the test suite.
+function shouldRedactKey(key) {
+  if (typeof key !== 'string') return false;
+  const lower = key.toLowerCase();
+  return REDACTION_TOKENS.some((tok) => lower.includes(tok));
+}
+
+// redactBody — returns a NEW value with sensitive fields replaced. Does not
+// mutate the input. Pure + exported for unit tests.
+//
+// Object  → new object, recursing into each value; sensitive keys → '<redacted>'.
+// Array   → new array, recursing into each element. (Array indices aren't keys
+//           in the redaction sense — we redact only by KEY name, not by
+//           position.)
+// Other   → returned unchanged.
+//
+// Guards against:
+//   - Cyclic structures (would otherwise infinitely recurse — we limit depth).
+//   - Non-plain objects (Buffer, Date, etc.) — we copy them by reference; the
+//     jsonb serializer will stringify or skip as appropriate. We don't try to
+//     deeply normalize because the request body in Express is always a plain
+//     object (express.json output).
+function redactBody(value, depth = 0) {
+  if (depth > 32) return REDACTED; // pathological nesting → redact wholesale
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => redactBody(v, depth + 1));
+  }
+  if (typeof value === 'object') {
+    // Skip non-plain objects (we never see Date/Buffer in express.json output,
+    // but be defensive).
+    if (value.constructor && value.constructor !== Object) {
+      // For non-plain objects we can't safely walk: stringify shape.
+      try {
+        return JSON.parse(JSON.stringify(value));
+      } catch (_) {
+        return REDACTED;
+      }
+    }
+    const out = {};
+    for (const k of Object.keys(value)) {
+      if (shouldRedactKey(k)) {
+        out[k] = REDACTED;
+      } else {
+        out[k] = redactBody(value[k], depth + 1);
+      }
+    }
+    return out;
+  }
+  // Primitive — return as-is.
+  return value;
+}
+
+// normalizeBody — coerce whatever req.body is into a plain object suitable for
+// jsonb storage. Wraps non-object payloads in { _value }.
+function normalizeBody(body) {
+  if (body === undefined || body === null) return {};
+  if (Array.isArray(body)) return { _value: body };
+  if (typeof body === 'object') return body;
+  return { _value: body };
+}
+
+// truncateForAudit — bound the SERIALIZED size of the (already-redacted) body
+// we persist (SR-17). If the body serializes within MAX_AUDIT_BODY_BYTES it's
+// stored verbatim. If it's over, we replace it with a small marker object that
+// keeps a redacted prefix + the original byte count, so the row is still
+// forensically useful but the on-disk footprint is bounded. Pure + exported for
+// tests. Never throws — a serialization failure falls back to the marker.
+function truncateForAudit(body, maxBytes = MAX_AUDIT_BODY_BYTES) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(body);
+  } catch (_) {
+    return { _audit_truncated: true, _reason: 'unserializable' };
+  }
+  if (serialized === undefined) return body; // undefined → nothing to store
+  const bytes = Buffer.byteLength(serialized, 'utf8');
+  if (bytes <= maxBytes) return body;
+  // Keep a head slice for context. Slice on the serialized string (not the
+  // object) so the cap is a hard byte bound regardless of body shape; the
+  // prefix is already redacted because we serialized the redacted body.
+  const prefix = serialized.slice(0, maxBytes);
+  return {
+    _audit_truncated: true,
+    _original_bytes: bytes,
+    _marker: `…[truncated ${bytes - maxBytes} bytes of ${bytes}]`,
+    _prefix: prefix,
+  };
+}
+
+// clientIp — prefer Express's resolved req.ip (which honors 'trust proxy', set
+// in server.js so x-forwarded-for from Cloudflare → Caddy is respected) and
+// fall back to the raw socket address.
+function clientIp(req) {
+  if (req.ip) return req.ip;
+  const sock = req.socket || req.connection;
+  return sock && sock.remoteAddress ? sock.remoteAddress : null;
+}
+
+// routePattern — return the matched route pattern (e.g. '/tasks/:id') rather
+// than the concrete URL ('/tasks/256'). When the request didn't hit a route
+// (e.g. 404 from the router), fall back to req.path.
+function routePattern(req) {
+  if (req.route && req.route.path) {
+    // baseUrl carries '/api/gds' plus any sub-router prefix; combining them
+    // yields the full pattern. trim trailing slash for tidiness.
+    const base = (req.baseUrl || '').replace(/\/+$/, '');
+    const tail = req.route.path === '/' ? '' : req.route.path;
+    const combined = `${base}${tail}` || '/';
+    return combined;
+  }
+  if (req.originalUrl) {
+    // Strip query string.
+    return String(req.originalUrl).split('?')[0];
+  }
+  return req.path || '/';
+}
+
+// isAuditableMethod — POST/PATCH/PUT/DELETE only. Per spec: reads are NOT
+// logged.
+function isAuditableMethod(method) {
+  return method === 'POST' || method === 'PATCH' || method === 'PUT' || method === 'DELETE';
+}
+
+// auditMiddleware — Express middleware factory. The factory pattern matches
+// what other middleware factories in the GDS do.
+//
+// Optional opts:
+//   insertFn   — alternative insert function (used in tests to inject a
+//                throwing implementation and prove fail-safety).
+function auditMiddleware(opts = {}) {
+  const insert = typeof opts.insertFn === 'function' ? opts.insertFn : db.insertAuditLog;
+
+  return function audit(req, res, next) {
+    // Fast-path: never instrument reads. (Express normalizes method to upper.)
+    if (!isAuditableMethod(req.method)) return next();
+
+    // Snapshot the inputs NOW. By the time 'finish' fires, downstream handlers
+    // could have mutated req.body (e.g. an upsert helper that pops fields off
+    // the payload). We want the audit row to reflect what the CLIENT sent.
+    let snapshotBody;
+    try {
+      // Redact FIRST (so the truncation prefix is already scrubbed), then cap
+      // the serialized size so a large upload can't write an unbounded second
+      // copy into audit_log (SR-17).
+      snapshotBody = truncateForAudit(redactBody(normalizeBody(req.body)));
+    } catch (err) {
+      // redaction failures are themselves audit-failures: log + continue.
+      // We still attach the finish handler so a row goes in WITH an empty body.
+      console.error('[audit] redact_failed', err);
+      snapshotBody = { _redact_failed: true };
+    }
+    const ip = clientIp(req);
+    const userAgent = req.headers['user-agent'] || null;
+    const method = req.method;
+
+    // Attach the finish hook. 'finish' fires AFTER the response headers + body
+    // have been flushed to the kernel, so we cannot block the user response by
+    // doing work here. 'close' also fires on aborted requests; we do NOT log
+    // on close to keep the stream interpretable as "completed responses only".
+    let alreadyLogged = false;
+    res.on('finish', () => {
+      if (alreadyLogged) return; // belt-and-braces; 'finish' fires once
+      alreadyLogged = true;
+
+      // Skip rows where auth didn't pass — by spec we log AUTHENTICATED writes
+      // only. requireBuilder sends 401 + populates nothing; in that case
+      // req.builder is undefined.
+      const builder = req.builder;
+      if (!builder || builder.id === undefined || builder.id === null) return;
+
+      // Snapshot route AFTER routing has finished — the matched route is only
+      // populated after Express finds the handler. This is the reason we
+      // can't compute the route up front.
+      const route = routePattern(req);
+      const status = res.statusCode;
+
+      // Fire-and-forget. Wrapping in Promise.resolve().then(...).catch(...)
+      // gives us the swallow guarantee for both sync throws and async
+      // rejections.
+      Promise.resolve()
+        .then(() =>
+          insert({
+            builderId: builder.id,
+            route,
+            method,
+            requestBodyRedacted: snapshotBody,
+            responseStatus: status,
+            ip,
+            userAgent,
+          })
+        )
+        .catch((err) => {
+          // SWALLOW. Audit failures must not surface to the caller and must
+          // not affect future requests. Console-error is the only effect.
+          console.error('[audit] insert_failed', {
+            route,
+            method,
+            status,
+            err: err && err.message ? err.message : String(err),
+          });
+        });
+    });
+
+    next();
+  };
+}
+
+module.exports = {
+  auditMiddleware,
+  redactBody,
+  shouldRedactKey,
+  truncateForAudit,
+  // Exposed for testing only.
+  _internals: { normalizeBody, routePattern, isAuditableMethod, REDACTED, MAX_AUDIT_BODY_BYTES },
+};

package/src/bongos/middleware/error-envelope.js

@@ -0,0 +1,93 @@
+// src/bongos/middleware/error-envelope.js — the central error contract (task 1989, R02).
+//
+// Two pieces that make the R01 envelope (src/bongos/api-errors.js, ADR 0116) the
+// guaranteed shape of every API failure:
+//
+//   1. attachFail — a tiny response decorator, mounted EARLY. It hangs a
+//      `res.fail(code, status?, details?)` helper on every response so a handler
+//      can emit the envelope in one call instead of hand-rolling
+//      `res.status(n).json({error:'x'})`. Status defaults from the registry; an
+//      explicit numeric status wins (so a site keeping its current status can).
+//
+//   2. errorEnvelopeHandler — the Express 4-arg error handler, mounted LAST
+//      (after every feature + module router). It is the safety net: any thrown
+//      ApiError, any `next(err)`, and body-parser failures (malformed JSON,
+//      oversized body) all come out as the envelope instead of Express's default
+//      HTML/text error page.
+//
+// BACKWARD-COMPATIBLE by design. It adds a helper and a trailing net; it changes
+// no existing response. Handlers that already answer directly (the ~219 ad-hoc
+// sites, and _helpers.asyncHandler which catches + responds itself) keep working
+// untouched until the R04 sweep migrates them onto res.fail / thrown ApiError.
+
+'use strict';
+
+const { ApiError, isApiError, envelope, statusForCode } = require('../api-errors');
+
+// attachFail — decorate res with fail(). Mounted once, before the routers.
+function attachFail(req, res, next) {
+  // res.fail(code)                      → registry status, message = code
+  // res.fail(code, 409)                 → explicit status
+  // res.fail(code, 409, details)        → with structured details
+  // res.fail(code, { status, message, details }) → object form
+  res.fail = function fail(code, statusOrOpts, details) {
+    let status;
+    let message;
+    let det = details;
+    if (statusOrOpts && typeof statusOrOpts === 'object') {
+      status = statusOrOpts.status;
+      message = statusOrOpts.message;
+      if (statusOrOpts.details !== undefined) det = statusOrOpts.details;
+    } else if (statusOrOpts !== undefined) {
+      status = statusOrOpts;
+    }
+    const httpStatus = statusForCode(code, status);
+    if (res.headersSent) return res;
+    return res.status(httpStatus).json(envelope(code, message, det));
+  };
+  next();
+}
+
+// Map an Express/body-parser/http-errors error to a canonical registry code.
+// Body-parser tags parse failures with err.type; http-errors carries a numeric
+// status/statusCode. We translate those to the envelope so a malformed request
+// gets a machine-readable code, not a stack-trace HTML page.
+function codeForFrameworkError(err) {
+  if (!err) return null;
+  if (err.type === 'entity.too.large') return { code: 'payload_too_large', status: 413 };
+  if (err.type === 'entity.parse.failed' || err instanceof SyntaxError) {
+    return { code: 'bad_json', status: 400 };
+  }
+  const status = err.status || err.statusCode;
+  if (Number.isInteger(status) && status >= 400 && status < 600) {
+    // A framework error already carrying a status (e.g. from http-errors). Give
+    // it a category-appropriate generic code; the message stays generic.
+    const code = status >= 500 ? 'internal_error' : 'bad_request';
+    return { code, status };
+  }
+  return null;
+}
+
+// errorEnvelopeHandler — the trailing 4-arg net. MUST be mounted last.
+function errorEnvelopeHandler(err, req, res, next) {
+  // Response already begun — hand back to Express's default finisher; we can't
+  // rewrite a partially-sent response.
+  if (res.headersSent) return next(err);
+
+  if (isApiError(err)) {
+    return res.status(err.status).json(envelope(err));
+  }
+
+  const framework = codeForFrameworkError(err);
+  if (framework) {
+    return res.status(framework.status).json(envelope(framework.code));
+  }
+
+  // Anything else is an unexpected server fault. Log with a stable tag (so it's
+  // greppable in prod logs) and answer a leak-free internal envelope — the raw
+  // message/stack is never sent to the client.
+  console.error('[gds] unhandled', req && req.method, req && req.originalUrl, err);
+  return res.status(500).json(envelope('internal_error'));
+}
+
+module.exports = { attachFail, errorEnvelopeHandler, ApiError };