@bongos/core 1.17.0

package/modules/security/secret-scrub.js

@@ -0,0 +1,201 @@
+'use strict';
+
+// modules/security/secret-scrub.js — the transcript-grade SECRET scrubber.
+//
+// HOME (task 1211 / GDS-V4 R72): these pure functions were extracted verbatim from
+// scripts/gds/ship.js so they can be reused without requiring ship.js — which pulls
+// in the grader, Discord, sound, and session machinery at load and is unsafe to
+// require in a bare CI job (the public-mirror export pipeline runs in GitHub Actions
+// with no session/sound/grader present). ship.js now requires + re-exports these, so
+// its public surface and tests/scrubber_corpus.mjs are unchanged. The security module
+// is the right home — secret redaction is a security primitive, and it publishes to
+// the open-source mirror as methodology (ADR 0098 allowlists modules/security/).
+//
+// This is the "imported, never re-typed" doctrine (gate-review.js; the publish-manifest
+// reuse rule): one copy of the secret SHAPES, consumed by ship.js's transcript scrubber
+// AND the public-mirror redactor (scripts/gds/mirror-redact.js) — so a new provider key
+// shape is added once and both paths get it.
+//
+// scrubSecrets — redact known secret shapes (ADR 0022) + any literal values in
+// `extraSecrets` + a high-entropy catch-all. Pure + exported for unit tests.
+//
+// TRANSCRIPT-GRADE (task 1003, gates the full-transcript capture task; completes
+// the open token-redaction of task 723). Today we store only thin, content-light
+// snippets, so a missed secret has a tiny surface. Once full transcripts are
+// captured (every file read, command output, pasted value), the scrubber is the
+// ONLY thing standing between a credential and the BFG corpus — so it is built
+// RECALL-FIRST: per ADR 0022 a missed secret is a credential compromise, while
+// over-redacting a non-secret in a BFG digest is merely cosmetic. When in doubt,
+// redact.
+//
+// Four layers, applied in order (each assumes the next will fail):
+//   1. literal dynamic values (this run's GDS token, Anthropic key, env secrets)
+//   2. multi-line PEM private-key blocks
+//   3. single-line KNOWN shapes (provider key prefixes, our gds_/pms_ tokens,
+//      Authorization headers, JWTs, credentialed DSNs, Apple app-passwords)
+//   4. secret-ish ASSIGNMENTS (recognised key + >=8-char value)
+//   5. HIGH-ENTROPY sweep over whatever survived — the catch-all for an UNKNOWN
+//      secret shape, which is the whole point of going transcript-grade.
+const REDACTED = '<redacted>';
+
+// Known secret SHAPES (ADR 0022), hoisted to module scope so they compile once
+// rather than per scrubSecrets() call (called O(turns) at ship time).
+const SECRET_PATTERNS = [
+  /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, // PEM private keys (RSA/EC/DSA/OPENSSH/PGP)
+  /\bsk-ant-[A-Za-z0-9_-]{16,}\b/g, // Anthropic API keys
+  /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, // GitHub tokens
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, // GitHub fine-grained PATs
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, // Slack tokens
+  /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, // Stripe secret / restricted keys
+  /\bwhsec_[A-Za-z0-9]{16,}\b/g, // Stripe webhook signing secrets
+  /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key IDs
+  /\bAIza[0-9A-Za-z_-]{35}\b/g, // Google API keys
+  // A gds_/pms_-PREFIXED bearer value (a legacy/possible-future token shape).
+  // NB the CURRENT GDS session token is a bare 64-hex string (auth.js:
+  // crypto.randomBytes(32).toString('hex')) with NO prefix — that real token is
+  // caught by the "token": assignment, the Authorization/Bearer header pattern,
+  // the live-token literal, and the hex entropy rule below; this pattern is the
+  // belt-and-suspenders for a prefixed value (ADR 0022 lists gds_session/pms_session).
+  /\b(?:gds|pms)_[A-Za-z0-9._-]{16,}\b/g,
+  // Apple app-specific password (used by notarization / the MAC_* CI secrets):
+  // four 4-letter lowercase groups, e.g. abcd-efgh-ijkl-mnop.
+  /\b[a-z]{4}-[a-z]{4}-[a-z]{4}-[a-z]{4}\b/g,
+  // Authorization headers — any scheme (Bearer/Basic/Token/…) or a bare credential.
+  /\bAuthorization\s*[:=]\s*["']?(?:Bearer|Basic|Token|Digest|Negotiate)?\s*[A-Za-z0-9._~+/=-]{8,}/gi,
+  // Bearer tokens anywhere (so "Bearer xxx" without the header word is caught too).
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/gi,
+  // JWTs (three base64url segments) — covers most generic bearer-style tokens.
+  /\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\b/g,
+  // Connection-string DSNs that embed credentials (scheme://user:pass@host).
+  /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqps?|https?):\/\/[^\s:'"/@]+:[^\s'"@]+@[^\s'")]+/gi,
+];
+// Generic secret ASSIGNMENTS: a recognised secret-ish key (with optional affixes,
+// so `access_token` / `GITHUB_TOKEN` / `client_secret` / a JSON `"token":` field
+// all match) + a >=8-char value. Redacts only the value (keeps the key name) so a
+// custom/high-entropy token surfaced as `API_KEY=...` / `"password": "..."` is
+// caught even when it matches no known prefix. Requires a recognised key word so
+// ordinary prose isn't nuked; the entropy sweep below is the unkeyed catch-all.
+const SECRET_ASSIGNMENT_RE =
+  /([A-Za-z0-9_-]*(?:api[_-]?key|secret|token|password|passwd|pwd|passphrase|access[_-]?key|private[_-]?key|client[_-]?secret|credential|session|cookie|bearer)[A-Za-z0-9_-]*)(["']?\s*[:=]\s*["']?)([^\s"',;]{8,})/gi;
+
+// shannonEntropy — bits per character. Pure; exported for tuning/tests.
+function shannonEntropy(str) {
+  if (!str) return 0;
+  const freq = Object.create(null);
+  for (const ch of str) freq[ch] = (freq[ch] || 0) + 1;
+  const n = str.length;
+  let H = 0;
+  for (const k in freq) {
+    const p = freq[k] / n;
+    H -= p * Math.log2(p);
+  }
+  return H;
+}
+
+// charClasses — how many of {lower, upper, digit, special} a token spans. A
+// generated token usually mixes 3+; an English word or plain identifier mixes 1–2.
+function charClasses(s) {
+  let c = 0;
+  if (/[a-z]/.test(s)) c++;
+  if (/[A-Z]/.test(s)) c++;
+  if (/[0-9]/.test(s)) c++;
+  if (/[^A-Za-z0-9]/.test(s)) c++;
+  return c;
+}
+
+// looksHighEntropySecret — recall-first verdict for ONE candidate token (a
+// maximal base64url/hex run). Redact when long AND random-looking by any of
+// three independent signals, so an UNKNOWN secret shape still gets caught:
+//   A. clearly random base64-ish: H >= 4.0 over >= 20 chars
+//   B. a generated mixed token:   H >= 3.7, >= 20 chars, >= 3 char classes
+//   C. a long hex blob (hash/key): all-hex, >= 32 chars, H >= 3.0
+// The cost is real and accepted: a 40-char git SHA matches rule C and is
+// redacted — but a 40-hex GitHub OAuth client secret (ADR 0022, in scope) is
+// shape-identical to a SHA, and a missed secret is a compromise while a redacted
+// SHA in a BFG digest is only cosmetic. Recall wins (Lars, 2026-06-13).
+function looksHighEntropySecret(tok) {
+  const n = tok.length;
+  if (n < 20) return false;
+  const H = shannonEntropy(tok);
+  if (H >= 4.0) return true; // A
+  if (H >= 3.7 && charClasses(tok) >= 3) return true; // B
+  if (n >= 32 && /^[0-9a-fA-F]+$/.test(tok) && H >= 3.0) return true; // C
+  return false;
+}
+
+// A candidate is a maximal run of base64url / hex chars (the encodings real
+// tokens use: GitHub/Slack/JWT/our gds_ tokens are base64url; hashes/keys are
+// hex). Deliberately EXCLUDES '/', '+', '=' so file paths and standard-base64
+// blobs aren't swallowed whole into one giant high-entropy candidate (which
+// over-redacted doc/code paths). A raw standard-base64 secret with '+//=' that
+// is NOT key-assigned and NOT a known env literal can split below the 20-char
+// floor and slip the entropy net — but layers 1–4 (literal env values, PEM,
+// known shapes, key=value assignments) already cover the realistic ways such a
+// value reaches a transcript.
+const ENTROPY_CANDIDATE_RE = /[A-Za-z0-9_-]{20,}/g;
+function redactHighEntropy(text) {
+  return text.replace(ENTROPY_CANDIDATE_RE, (tok) => (looksHighEntropySecret(tok) ? REDACTED : tok));
+}
+
+// ENV secret collection — literal secret VALUES from the process env, so they are
+// redacted wherever they appear even with no recognizable shape (Apple/MAC_* CI
+// secrets, a baked GDS_TOKEN, GITHUB_TOKEN, DO_API_TOKEN, …). Key match mirrors
+// SECRET_ASSIGNMENT_RE's vocabulary, plus a few provider prefixes whose secret
+// values don't themselves contain a secret word. Values < 8 chars are skipped
+// (scrubSecrets ignores shorter literals anyway). Exported for tests.
+const ENV_SECRET_KEY_RE =
+  /(?:api[_-]?key|secret|token|password|passwd|pwd|passphrase|access[_-]?key|private[_-]?key|client[_-]?secret|credential|cookie)/i;
+const ENV_SECRET_PREFIX_RE = /^(?:gds_|pms_|mac_|apple|anthropic|stripe|cf_|cloudflare|do_token|digitalocean)/i;
+function collectEnvSecrets(env = process.env) {
+  const out = [];
+  for (const [k, v] of Object.entries(env || {})) {
+    if (typeof v !== 'string' || v.length < 8) continue;
+    if (ENV_SECRET_KEY_RE.test(k) || ENV_SECRET_PREFIX_RE.test(k)) out.push(v);
+  }
+  return out;
+}
+
+function scrubSecrets(text, extraSecrets = []) {
+  if (typeof text !== 'string' || text.length === 0) return text;
+  let out = text;
+  // Literal dynamic secrets first (longest first so a substring can't shadow a
+  // longer secret). Only redact reasonably long literals to avoid nuking
+  // common short strings.
+  const literals = (Array.isArray(extraSecrets) ? extraSecrets : [])
+    .filter((s) => typeof s === 'string' && s.length >= 8)
+    .sort((a, b) => b.length - a.length);
+  for (const secret of literals) {
+    out = out.split(secret).join(REDACTED);
+  }
+  for (const re of SECRET_PATTERNS) {
+    out = out.replace(re, REDACTED);
+  }
+  out = out.replace(SECRET_ASSIGNMENT_RE, (m, key, sep, value) =>
+    // Self-reference guard (task 1688): a value equal to its own key is never a
+    // credential — it's a code/SQL self-assignment like `SET tokens_saved_est =
+    // tokens_saved_est + $2`, where the "_token" substring in the COLUMN name trips
+    // the keyword. Skipping it keeps such a column intact with ZERO recall loss on a
+    // real `key = <secret>` (a secret never equals its key name). "Recall wins"
+    // (2026-06-13) is preserved — no real-secret shape stops being redacted.
+    (key.toLowerCase() === value.toLowerCase()) ? m : `${key}${sep}${REDACTED}`);
+  // Catch-all LAST: an unkeyed, unknown-shape, high-entropy token. The earlier
+  // layers have already collapsed known secrets to "<redacted>" (no candidate),
+  // so this only sweeps what survived.
+  out = redactHighEntropy(out);
+  return out;
+}
+
+module.exports = {
+  REDACTED,
+  SECRET_PATTERNS,
+  SECRET_ASSIGNMENT_RE,
+  shannonEntropy,
+  charClasses,
+  looksHighEntropySecret,
+  ENTROPY_CANDIDATE_RE,
+  redactHighEntropy,
+  ENV_SECRET_KEY_RE,
+  ENV_SECRET_PREFIX_RE,
+  collectEnvSecrets,
+  scrubSecrets,
+};

package/modules/security/security.js

@@ -0,0 +1,294 @@
+// GDS security — the red-team bounty payout table (V3.R65 / #284).
+//
+// Carved into modules/security/ in BV1.R79 (ADR 0093 §1) — security-the-FEATURE
+// (red-team / vulnerability reports + bounty, rank-gated Metic+). security-the-
+// PROPERTY (the permission-path / route-rank / trust-boundary machinery) is NOT
+// here — it stays kernel (02-module-map §5). OTB byte-identical: only the pool
+// require() path changed (now the doorway).
+//
+// One place defines how many drachmae a builder earns for finding and reporting
+// a vulnerability, keyed by severity. This module is the SINGLE SOURCE OF TRUTH
+// for those numbers: the /builders hall renders them under "Red-team rewards",
+// and R68 (auto-confirmation of a vulnerability_report awards drachmae) reads
+// them here rather than re-deriving its own constants.
+//
+// Unit convention: "drachmae" is the project's in-world currency, stored as
+// integer `delta` in credit_log (see migrations/003_pms.sql). So the payout
+// for each severity is a plain integer count of drachmae — the same unit a
+// task's credits_reward is denominated in. (The "10c / 50c" shorthand in the
+// task spec maps to 10 / 50 drachmae; there is no sub-drachma "cent".)
+//
+// TUNABILITY (done-when): the four amounts are DEFAULTS. An Archon can override
+// any of them per-environment without a code change via:
+//
+//   GDS_BOUNTY_LOW       (default 10)
+//   GDS_BOUNTY_MEDIUM    (default 50)
+//   GDS_BOUNTY_HIGH      (default 200)
+//   GDS_BOUNTY_CRITICAL  (default 1000)
+//
+// Each is parsed as a non-negative integer; a missing/invalid/negative value
+// falls back to its default (so a typo in the env can never zero out or
+// negative-pay a bounty silently). Rationale for the tier amounts: ADR 0019.
+//
+// The env is read once at module load. Changing an env var takes effect on the
+// next process restart (consistent with every other GDS env knob — see
+// scripts/gds/onboarding-config.js windowDays()).
+
+// Carved into modules/security/ (BV1.R79 / ADR 0093 §1): the shared Postgres
+// pool reaches through the published doorway — a module never requires a core
+// internal (the security-the-FEATURE / red-team-reports + bounty slice;
+// security-the-PROPERTY stays kernel per 02-module-map §5).
+const { pool } = require('../../src/module-api');
+
+// Ordered low → critical so render code can iterate deterministically.
+const SEVERITIES = ['low', 'medium', 'high', 'critical'];
+
+// Adjudication lifecycle for a vulnerability_report (matches the CHECK in
+// migration 030). Ordered roughly in workflow order so render code can iterate.
+const VULN_STATUSES = ['open', 'repro_attempted', 'confirmed', 'disputed', 'fixed', 'wontfix'];
+
+// Default drachmae per severity. Overridable per-env (see header).
+const DEFAULT_BOUNTY = Object.freeze({
+  low: 10,
+  medium: 50,
+  high: 200,
+  critical: 1000,
+});
+
+// Human-readable one-liners shown next to each tier in the hall.
+const SEVERITY_BLURB = Object.freeze({
+  low: 'Cosmetic or low-impact — info leak with no exploit path, minor misconfig.',
+  medium: 'A real flaw needing specific conditions — limited-scope auth or data issue.',
+  high: 'Serious — privilege escalation, broad data exposure, or auth bypass.',
+  critical: 'Catastrophic — remote code execution, full account/rank takeover, treasury drain.',
+});
+
+// Env var name for a given severity, e.g. low → GDS_BOUNTY_LOW.
+function envName(severity) {
+  return `GDS_BOUNTY_${String(severity).toUpperCase()}`;
+}
+
+// Resolve one severity's payout: env override if a valid non-negative integer,
+// otherwise the default. Mirrors onboarding-config.js windowDays() validation.
+function resolveAmount(severity) {
+  const raw = process.env[envName(severity)];
+  if (raw !== undefined && raw !== '') {
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= 0) return n;
+  }
+  return DEFAULT_BOUNTY[severity];
+}
+
+// Build the live payout map { low, medium, high, critical }, env applied.
+function bountyTable() {
+  const out = {};
+  for (const sev of SEVERITIES) out[sev] = resolveAmount(sev);
+  return out;
+}
+
+// Richer shape for rendering: ordered rows with amount + whether the live value
+// differs from the shipped default + the blurb. The hall and any future status
+// surface read this so they don't each re-implement the env merge.
+function bountyTableDetailed() {
+  return SEVERITIES.map((sev) => {
+    const amount = resolveAmount(sev);
+    return {
+      severity: sev,
+      drachmae: amount,
+      default_drachmae: DEFAULT_BOUNTY[sev],
+      overridden: amount !== DEFAULT_BOUNTY[sev],
+      env_var: envName(sev),
+      blurb: SEVERITY_BLURB[sev],
+    };
+  });
+}
+
+// -------------------------------------------------------------------------
+// vulnerability_reports — the red-team bounty intake table (V3.R63 / #282,
+// migration 030). The bounty payout table above answers "how much for a
+// confirmed report of severity X"; these helpers answer "store / read the
+// reports themselves". A confirmed report's severity maps directly onto a
+// bountyTable() amount (same four tiers) — R68 wires the payout.
+// -------------------------------------------------------------------------
+
+// Columns selected for any report read. Kept in one place so the own/all
+// readers return identical shapes.
+const VULN_COLUMNS = `id, reporter_builder_id, target, severity, title, description,
+       repro_steps_md, status, confirmed_at, fixed_at, fix_task_id,
+       drachmae_awarded, reported_at`;
+
+// File a new vulnerability_report. Validates severity against the bounty
+// tiers (the DB CHECK is the backstop; this gives a clean error first).
+// Returns the inserted row. Throws { code: 'INVALID_SEVERITY', severity } on a
+// bad tier.
+async function createVulnerabilityReport({
+  reporterBuilderId,
+  target,
+  severity,
+  title,
+  description = null,
+  reproStepsMd = null,
+}) {
+  if (!SEVERITIES.includes(severity)) {
+    throw { code: 'INVALID_SEVERITY', severity, allowed: SEVERITIES };
+  }
+  const { rows } = await pool.query(
+    `INSERT INTO vulnerability_reports
+       (reporter_builder_id, target, severity, title, description, repro_steps_md)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     RETURNING ${VULN_COLUMNS}`,
+    [reporterBuilderId, target, severity, title, description, reproStepsMd]
+  );
+  return rows[0];
+}
+
+// Read vulnerability reports with an explicit own-vs-all scope.
+//
+// Access model (done-when): a builder reads their OWN reports; an Archon reads
+// ALL. The own/all distinction is a single `scope` parameter here, NOT an
+// embedded rank check — the rank gate lives at the route layer (R67 will build
+// the Archon path). Structuring it this way means R67 just passes scope:'all'
+// after its requireRank('archon') passes, and the own path needs no change.
+//
+//   listVulnerabilityReports({ scope: 'own', builderId })  → that builder's reports
+//   listVulnerabilityReports({ scope: 'all' })             → every report (Archon use)
+//
+// `scope: 'own'` REQUIRES builderId; omitting it throws rather than silently
+// leaking every report. Optional `status` narrows either scope.
+async function listVulnerabilityReports({ scope = 'own', builderId = null, status = null } = {}) {
+  if (scope !== 'own' && scope !== 'all') {
+    throw { code: 'INVALID_SCOPE', scope, allowed: ['own', 'all'] };
+  }
+  if (scope === 'own' && (builderId === null || builderId === undefined)) {
+    throw { code: 'BUILDER_ID_REQUIRED' };
+  }
+  const params = [];
+  const where = [];
+  if (scope === 'own') {
+    params.push(builderId);
+    where.push(`reporter_builder_id = $${params.length}`);
+  }
+  if (status) {
+    params.push(status);
+    where.push(`status = $${params.length}`);
+  }
+  const sql =
+    `SELECT ${VULN_COLUMNS} FROM vulnerability_reports` +
+    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+    ` ORDER BY reported_at DESC, id DESC`;
+  const { rows } = await pool.query(sql, params);
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// Adjudication (V3.R66 / #285). Archon-only state transitions on a report.
+// The route layer enforces the rank gate; these helpers are kind-specific
+// so the audit trail and the response shape are consistent across actions.
+// -------------------------------------------------------------------------
+
+// Flip a report to 'confirmed', stamp confirmed_at, set drachmae_awarded
+// (defaults to the bounty table amount for the report's severity if not
+// supplied). Idempotent — re-confirming a 'confirmed' report just updates
+// drachmae_awarded if a different amount is supplied; the stamped timestamp
+// is preserved (coalesce).
+async function confirmVulnerabilityReport(id, { drachmaeAwarded = null } = {}) {
+  // Look up the row so we can resolve the bounty default if needed.
+  const { rows: existingRows } = await pool.query(
+    `SELECT ${VULN_COLUMNS} FROM vulnerability_reports WHERE id = $1`,
+    [id]
+  );
+  if (existingRows.length === 0) {
+    throw { code: 'REPORT_NOT_FOUND', id };
+  }
+  const existing = existingRows[0];
+  // If the caller didn't specify drachmae, fall back to the severity's
+  // bounty (live, env-aware).
+  const amount =
+    drachmaeAwarded === null || drachmaeAwarded === undefined
+      ? bountyTable()[existing.severity] ?? null
+      : drachmaeAwarded;
+  const { rows } = await pool.query(
+    `UPDATE vulnerability_reports
+        SET status = 'confirmed',
+            confirmed_at = COALESCE(confirmed_at, now()),
+            drachmae_awarded = $2
+      WHERE id = $1
+      RETURNING ${VULN_COLUMNS}`,
+    [id, amount]
+  );
+  return rows[0];
+}
+
+// Flip a report to 'disputed'. Does not touch confirmed_at / fixed_at —
+// disputes can happen post-confirm-attempt and the original stamps are
+// audit-relevant. drachmae_awarded is cleared (nothing to pay).
+async function disputeVulnerabilityReport(id) {
+  const { rows } = await pool.query(
+    `UPDATE vulnerability_reports
+        SET status = 'disputed',
+            drachmae_awarded = NULL
+      WHERE id = $1
+      RETURNING ${VULN_COLUMNS}`,
+    [id]
+  );
+  if (rows.length === 0) throw { code: 'REPORT_NOT_FOUND', id };
+  return rows[0];
+}
+
+// Flip a report to 'fixed', stamp fixed_at if not already set. Preserves
+// any existing fix_task_id (use linkVulnerabilityReportFix to attach one).
+async function markVulnerabilityReportFixed(id) {
+  const { rows } = await pool.query(
+    `UPDATE vulnerability_reports
+        SET status = 'fixed',
+            fixed_at = COALESCE(fixed_at, now())
+      WHERE id = $1
+      RETURNING ${VULN_COLUMNS}`,
+    [id]
+  );
+  if (rows.length === 0) throw { code: 'REPORT_NOT_FOUND', id };
+  return rows[0];
+}
+
+// Attach a fix-task to a report. Doesn't change status — a confirmed report
+// can have a fix task linked while still being worked. Throws if the
+// referenced task doesn't exist (the FK on fix_task_id enforces this; we
+// surface the violation as a structured error first).
+async function linkVulnerabilityReportFix(id, fixTaskId) {
+  if (!Number.isInteger(fixTaskId) || fixTaskId <= 0) {
+    throw { code: 'INVALID_FIX_TASK_ID', fixTaskId };
+  }
+  // Pre-check the task exists so we get a clean error rather than a 23503.
+  const { rows: taskRows } = await pool.query(
+    `SELECT id FROM tasks WHERE id = $1`,
+    [fixTaskId]
+  );
+  if (taskRows.length === 0) {
+    throw { code: 'FIX_TASK_NOT_FOUND', fixTaskId };
+  }
+  const { rows } = await pool.query(
+    `UPDATE vulnerability_reports
+        SET fix_task_id = $2
+      WHERE id = $1
+      RETURNING ${VULN_COLUMNS}`,
+    [id, fixTaskId]
+  );
+  if (rows.length === 0) throw { code: 'REPORT_NOT_FOUND', id };
+  return rows[0];
+}
+
+module.exports = {
+  SEVERITIES,
+  VULN_STATUSES,
+  DEFAULT_BOUNTY,
+  SEVERITY_BLURB,
+  envName,
+  bountyTable,
+  bountyTableDetailed,
+  createVulnerabilityReport,
+  listVulnerabilityReports,
+  confirmVulnerabilityReport,
+  disputeVulnerabilityReport,
+  markVulnerabilityReportFixed,
+  linkVulnerabilityReportFix,
+};

package/modules/sessions/CLAUDE.md

@@ -0,0 +1,39 @@
+# `sessions` module — session-records corpus, BFG, session-pulse
+
+> A CORE-domain carve (BV1.R82, [ADR 0093](../../docs/adr/<redacted>.md) §1) — the seventh tranche-2 domain extracted from the GDS core, after onboarding (R81). `default: true` — every instance records its builders' sessions for the BFG, so it mounts unconditionally unless an instance disables it.
+
+Owns the **session_records corpus** + its data plane (the `/sessions` upload + the Archon-gated cross-builder search/deep-dive), the **BFG** cross-builder "read-the-room" scorer ([ADR 0026](../../docs/adr/<redacted>.md) §6B), and the **session-pulse / stale-claim** heartbeat helpers.
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.10.0`). It must **never** `require()` a core internal (`../../src/bongos/db`, `../../src/bongos/auth`, `../../src/bongos/pool`, …) directly, and **never** another module. Core, in turn, must never `require()` a file in here — the route mount left `src/bongos/routes.js`; `moduleLoader.mountModuleRoutes` discovers + mounts it now. Both directions are enforced by the BV1.R44/R45 fitness checks.
+
+## No port (the memory shape, not the economy shape)
+
+Unlike economy / security / builder-settings / onboarding, sessions registers **no kernel port** (`provides: []`) — exactly like `memory`. **Core never calls back into sessions:** the ship-time session-digest write is an **HTTP POST** to this module's own `/sessions` route (`scripts/gds/ship.js` → `POST /api/gds/sessions`), not a `require`. So there is nothing for a port to expose. The session-records db slice moved here cleanly with its sole consumer (the route).
+
+The **one outward edge** is the economy **`reward`** kernel port this module *consumes* (resolves, never imports): `upsertSessionRecordWithReward` (in `db.js`) and `POST /sessions` (in `routes/sessions.js`) both `seams.resolveOptional('reward')` — to award the cost-plus session token reward inside the upsert transaction (passing the tx `client`) and to sum the drachmae credited for the owned task(s). That is the kernel-mediated module↔module seam (ADR 0083 / 0093 §2).
+
+## Files
+
+| File | What |
+|---|---|
+| `db.js` | the `session_records` db slice — `upsertSessionRecord[WithReward]` (the token-reward txn resolves the `reward` port), `searchSessions` / `summarizeSessions` / `getSessionById` / `listSessionsByBuilder`, `filterTaskIdsClaimedBy`, the ORDER-BY whitelist + limit/offset clamps + the shared filter clause. Reaches Postgres via the doorway `pool` + `withTx`. |
+| `bfg.js` | the BFG's PURE scorers (`scoreInteractionQuality` / `scoreMemoryQuality`) + extractors + the thin `gatherInteractionSignals` DB gatherer (ADR 0026 §6B). Reads via the doorway (`pool`, `getBuilderById`, `builderRollingAvgGrade`). |
+| `pulse.js` | session-pulse + stale-claim heartbeat helpers (`recordPulse` / `sweepStaleClaims` / `getStaleClaimsForBuilder`). The CLI shell stays at `scripts/gds/pulse.js` and requires this lib directly. |
+| `routes/sessions.js` | `/sessions` (upload — carries its own 4 MB `express.json`; core `routes.js` still skips the global parser for that path), `/sessions/search` + `/sessions/:id` (Archon-gated cross-builder, fail-closed audited), `/sessions/mine`. |
+
+## Tables (owned, not moved)
+
+`session_records` (+ its migrations) was created before the module system and stays in core `migrations/` (the schema-migrations stem-key makes a later relocation a no-op). The module owns the *queries*; any **new** session migration belongs in `modules/sessions/migrations/` namespaced `sessions_*` (the additive rule). The `session_pulses` table (migration 006) is likewise shared-schema; pulse.js owns its queries.
+
+## NOT in this module
+
+- **`session_logs`** — the per-claim session LOG (the ship-time handoff record, `sealSessionLog`) stays in core `db.js` (lifecycle): it's written inside the claim/ship transaction and read by `routes/claims.js`/`builders.js`. Distinct from `session_records` (the BFG transcript corpus).
+- **`builder_sessions`** — the AUTH token table (`createSession`/`lookupSession`/…) is kernel (auth), not this domain.
+- **cost / reconcileSessionCosts** — the cost ledger + the session-cost reconciler graduated to [`modules/economy/`](../economy/CLAUDE.md) at BV1.R77. `scripts/gds/session-cost.js` (the SessionEnd cost hook) stays a CLI and posts to `/cost`.
+- **the session-domain CLIs** — `session.js`, `session-eval.js` (the 6D evaluator), `session-digest.js`, `session-cost.js`, `backfill-sessions.js`, `bfg-principal-token.js`, `repo-metrics.js`, `pulse.js` travel with the domain but stay under `scripts/` (a command travels with its domain — design 02§1). They're outside the kernel boundary, so `session-eval.js`'s sibling read of `modules/builder-settings/wandering-prefs` is fine (not a cross-module import — fitness scans `src/` + `modules/`, not `scripts/`).
+
+## Tests
+
+`tests/session_search.mjs` (ORDER-BY/clamp guards), `tests/session_caps.mjs` (SR-17 disk-fill bounds — route + db, with the `reward` port registered), `tests/session_eval.mjs` + `tests/session_506_regression.mjs` (the evaluator), `tests/session_digest.mjs` + `tests/session_records.mjs` (the ship-time digest), `tests/bfg*.mjs` (the scorers), `tests/backfill_sessions.mjs` import from `modules/sessions/…` or exercise it. `bfg`/`bfg_write`/`session_records`/`backfill_sessions` are DB-dependent (the `INTEGRATION` set in `run-unit-tests.js`).