@bongos/core 1.18.19 → 1.19.2

package/modules/security/migrations/security_001_tool_scans.sql

@@ -0,0 +1,145 @@
+-- security_001_tool_scans.sql — the durable record of an external-artifact scan.
+--
+-- One row per `/scan-before-install` run, so a scan is queryable across builders
+-- rather than living only in one session's chat and one file on one laptop. The
+-- builder most likely to install a shiny new tool is the newest one, so the read
+-- side of this table exists to let one builder's scan warn the next.
+--
+-- STRUCTURE ONLY, NEVER TARGET CONTENT. The row carries the verdict, the tier,
+-- the pinned SHA, the content hash, per-severity counts, and one-line finding
+-- claims — never quoted bytes from the artifact. Two reasons: a scanned artifact
+-- is hostile input, and anything stored here is later rendered to whoever reads
+-- the table, so a quoted payload would make this table a delivery mechanism for
+-- the very injection the scan exists to catch. The `findings_summary` size cap
+-- below is the DB-layer half of that rule; the route validates it too.
+--
+-- AN ABORTED SCAN IS RECORDABLE. `completion` distinguishes a finished scan from
+-- one that died (clone timeout, cap exceeded, host resolved private). That is
+-- deliberate: a scan that produced no verdict must be visible as "aborted, here
+-- is why" rather than being indistinguishable from silence — otherwise a failed
+-- scan reads like a clean one.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is security_-prefixed, there is no down-migration, and the filename is
+-- security_-prefixed (ADR 0108 §5) so its stem never collides across repos.
+-- `scripts/migrate.sh` discovers + applies this when the security module is
+-- enabled (default:true). Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS security_tool_scans (
+  id                    bigserial PRIMARY KEY,
+
+  -- What was scanned. target_url is the https URL as validated; target_host is
+  -- split out so "have we seen anything from this host" is an index-able question.
+  target_url            text NOT NULL,
+  target_host           text,
+  -- 'repo' (a plain GitHub repo) | 'plugin' | 'marketplace'. Text plus a CHECK
+  -- rather than a Postgres enum TYPE: the constraint pins today's known kinds
+  -- fail-closed, and widening to a new kind is a one-line constraint change in a
+  -- later security_* migration — not an enum-type migration.
+  artifact_kind         text NOT NULL,
+
+  -- The pinned commit. NULL only when the scan aborted before resolving HEAD.
+  -- A branch or tag is never an install source; only this SHA is.
+  resolved_sha          text,
+  -- sha256 over the sorted (path, kind, size, sha256) manifest. The dedupe key
+  -- for "we already scanned these exact bytes", and what the install offer
+  -- re-checks so the artifact cannot change between scanning and installing.
+  content_hash          text,
+  file_count            integer,
+  total_bytes           bigint,
+
+  -- Thoroughness the scan ran at. The low tier can never reach a clean verdict,
+  -- so tier is load-bearing context for reading `verdict`, not decoration.
+  tier                  text NOT NULL,
+  -- clean | caution | dangerous. NULL when completion <> 'complete' — an
+  -- unfinished scan has no verdict, and must never be read as a passing one.
+  verdict               text,
+  completion            text NOT NULL DEFAULT 'complete',
+  -- the abort's finding code (clone_timeout, cap_max_bytes, host_resolves_private…)
+  abort_code            text,
+
+  findings_critical     integer NOT NULL DEFAULT 0,
+  findings_high         integer NOT NULL DEFAULT 0,
+  findings_medium       integer NOT NULL DEFAULT 0,
+  findings_low          integer NOT NULL DEFAULT 0,
+  -- One-line claims only (code, severity, file, short message). The full report
+  -- with evidence lives in the builder's own user directory, never here and
+  -- never in the repo: a scan report is a timestamped accusation about a named
+  -- third party, and docs/ is a public AGPL tree indexed by /recall.
+  findings_summary      jsonb NOT NULL DEFAULT '[]'::jsonb,
+
+  -- What the builder did with the verdict: none | install_command_printed |
+  -- sanitized_copy | rebuild_spec | declined. Note the scanner never installs;
+  -- the strongest value here is that a command was PRINTED for the user to run.
+  action_taken          text,
+  -- engine version that produced this row, so an old row is never mistaken for
+  -- a verdict the current detector set would reach.
+  engine_version        text NOT NULL,
+
+  scanned_by_builder_id bigint REFERENCES builders(id) ON DELETE SET NULL,
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT security_tool_scans_completion_chk
+    CHECK (completion IN ('complete', 'aborted', 'incomplete')),
+  CONSTRAINT security_tool_scans_verdict_chk
+    CHECK (verdict IS NULL OR verdict IN ('clean', 'caution', 'dangerous')),
+  -- A finished scan must carry a verdict, and an unfinished one must not. This is
+  -- the invariant that keeps "the scan died" from ever being read as "it passed".
+  CONSTRAINT security_tool_scans_verdict_completion_chk
+    CHECK ((completion = 'complete') = (verdict IS NOT NULL)),
+  CONSTRAINT security_tool_scans_tier_chk
+    CHECK (tier IN ('low', 'default', 'high', 'xhigh', 'max')),
+  CONSTRAINT security_tool_scans_artifact_kind_chk
+    CHECK (artifact_kind IN ('repo', 'plugin', 'marketplace')),
+  CONSTRAINT security_tool_scans_action_chk
+    CHECK (action_taken IS NULL OR action_taken IN
+      ('none', 'install_command_printed', 'sanitized_copy', 'rebuild_spec', 'declined')),
+  CONSTRAINT security_tool_scans_counts_chk
+    CHECK (findings_critical >= 0 AND findings_high >= 0
+       AND findings_medium >= 0 AND findings_low >= 0),
+  -- Defense in depth with the route's own cap: a hostile artifact must not be
+  -- able to push unbounded text through a summary field into every future reader.
+  CONSTRAINT security_tool_scans_summary_size_chk
+    CHECK (length(findings_summary::text) <= 65536),
+  -- The summary is a LIST of one-line claims — pinning the shape at the DB layer
+  -- means a scalar or object smuggled past the route can never land.
+  CONSTRAINT security_tool_scans_summary_shape_chk
+    CHECK (jsonb_typeof(findings_summary) = 'array'),
+  CONSTRAINT security_tool_scans_url_len_chk
+    CHECK (length(target_url) <= 2048)
+);
+
+-- "Have these exact bytes been scanned before?" — the dedupe lookup. Partial: an
+-- aborted scan never produced a content_hash, and those NULLs are dead weight.
+CREATE INDEX IF NOT EXISTS security_tool_scans_content_hash_idx
+  ON security_tool_scans (content_hash)
+  WHERE content_hash IS NOT NULL;
+
+-- "What has this builder scanned lately?" — the scanner's own history.
+CREATE INDEX IF NOT EXISTS security_tool_scans_scanner_idx
+  ON security_tool_scans (scanned_by_builder_id, created_at DESC);
+
+-- "Anything scanned from this host?" — cheap reputation lookup across builders.
+CREATE INDEX IF NOT EXISTS security_tool_scans_host_idx
+  ON security_tool_scans (target_host, created_at DESC)
+  WHERE target_host IS NOT NULL;
+
+-- Rows ARE mutated after insert (action_taken is recorded once the builder acts
+-- on the verdict), so updated_at needs a real trigger — without one it silently
+-- equals created_at forever. Idempotent: OR REPLACE + DROP IF EXISTS.
+CREATE OR REPLACE FUNCTION security_tool_scans_touch_updated_at() RETURNS trigger AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS security_tool_scans_updated_at ON security_tool_scans;
+CREATE TRIGGER security_tool_scans_updated_at
+  BEFORE UPDATE ON security_tool_scans
+  FOR EACH ROW EXECUTE FUNCTION security_tool_scans_touch_updated_at();
+
+COMMIT;

package/modules/security/module.json

@@ -1,10 +1,10 @@
 {
   "key": "security",
   "title": "Security (red-team · bounty)",
-  "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule.",
+  "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule. Also owns the scan-before-install surface (goal 1000055): the artifact-scan engine (quarantine/manifest/mirror) and the security_tool_scans record — POST Metic+, GET every rank.",
   "coreVersion": "^1.8.0",
   "default": true,
-  "contributes": { "routes": ["reports"] },
+  "contributes": { "routes": ["reports", "scans"], "migrations": true },
   "provides": ["security"],
   "consumes": []
 }

package/modules/security/routes/reports.js

@@ -62,7 +62,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports',
     api.requireBuilder,
-    api.requireRank('metic', 'archon'),
+    api.requirePermission('security.report.file'),
     async (req, res) => {
       if (validateOrRespond(req, res, {
         target:         { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
@@ -99,11 +99,15 @@ module.exports = function buildSecurityReportsRouter() {
   // lifecycle bucket (open / repro_attempted / confirmed / disputed /
   // fixed / wontfix); omitted = all.
   //
-  // rank: archon — adjudication surface; reading every builder's reports.
+  // rank: metic+archon — adjudication surface; reading every builder's reports.
+  // BV1.R105 left this on requireRank because `security.report.adjudicate` was declared
+  // over the adjudication WRITES + /security/docs CRUD, not over this read. ADR 0157
+  // extends that atom's guards to name GET /security/reports and lowers its floor
+  // archon→metic, so the mapping now exists and the audience is the working rank.
   router.get(
     '/security/reports',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       const status = req.query.status ? String(req.query.status) : null;
       if (status && !security.VULN_STATUSES.includes(status)) {
@@ -135,7 +139,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/confirm',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       // drachmae_awarded is OPTIONAL and deliberately UNTYPED here: the handler
       // accepts a number, a stringified number, '' and null alike, and the inline
@@ -174,7 +178,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/dispute',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
@@ -199,7 +203,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/fix',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
@@ -225,7 +229,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/link-fix',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       // task_id is REQUIRED but untyped: the handler accepts a number or a
       // stringified number and coerces below, so a type would narrow the live

package/modules/security/routes/scans.js

@@ -0,0 +1,115 @@
+// modules/security/routes/scans.js — the scan-record surface (task 1002547,
+// goal 1000055): POST one row per /scan-before-install run, GET the rows for a
+// content hash so one builder's scan warns the next.
+//
+// Rank shape, deliberately asymmetric:
+//   * WRITE is Metic+ — a verdict-shaped write is a trust-shaped write; a row
+//     here tells every future reader "these bytes were judged X".
+//   * READ is every rank — the builder most likely to install a shiny new tool
+//     is the newest one, and the warning must reach exactly them.
+//
+// A Xenos who runs a scan still gets a DEFINED path (below), not a dead-end:
+// the refusal names what they keep (report file + chat summary) and what to do
+// next, so the degraded experience is a documented contract, not a mystery 403.
+//
+// Same idioms as reports.js next door: doorway-only requires, validateOrRespond
+// schema, res.fail codes, factory export mounted via module.json contributes.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const scanStore = require('../scan-store');
+const { validateOrRespond } = api;
+
+// Interposed BEFORE api.requireRank so a Xenos gets the documented degraded
+// path instead of the generic rank refusal. Anyone Metic+ falls through to the
+// real gate (which fitness/route-rank-check reads as this route's rank).
+function xenosDegradedPath(req, res, next) {
+  if (api.rankMeetsThreshold(req.builder?.rank, 'metic')) return next();
+  return res.fail('scan_row_requires_metic', 403, {
+    degraded_path:
+      'Your scan itself is unaffected — keep the report file in your user directory and the chat summary. ' +
+      'What your rank cannot do is write the SHARED scan record other builders query. ' +
+      'Ask any Metic+ builder to POST this scan, or re-run the record step after promotion.',
+    kept: ['report_file', 'chat_summary'],
+    not_recorded: ['gds_scan_row'],
+  });
+}
+
+module.exports = function buildSecurityScansRouter() {
+  const router = express.Router();
+
+  // POST /api/bongos/security/scans — record one scan run.
+  //
+  // Body: structure only, never quoted target content — the deep checks
+  // (one-line claims, fence-marker rejection, scrubbing, verdict/completion
+  // coupling) live in scanStore.normalizeScanPayload; the schema here rejects
+  // unknown/typo'd top-level fields (strict default) and pins basic shapes.
+  //
+  // rank: metic+archon — a verdict-shaped write is a trust-shaped write.
+  router.post(
+    '/security/scans',
+    api.requireBuilder,
+    xenosDegradedPath,
+    api.requireRank('metic', 'archon'),
+    async (req, res) => {
+      if (validateOrRespond(req, res, {
+        target_url:        { required: true, type: 'string', maxLength: 2048, minLength: 9 },
+        artifact_kind:     { required: true, type: 'string', enum: [...scanStore.ARTIFACT_KINDS] },
+        resolved_sha:      { type: 'string', maxLength: 40 },
+        content_hash:      { type: 'string', maxLength: 64 },
+        file_count:        { type: 'integer', min: 0 },
+        total_bytes:       { type: 'integer', min: 0 },
+        tier:              { required: true, type: 'string', enum: [...scanStore.TIERS] },
+        verdict:           { type: 'string', enum: [...scanStore.VERDICTS] },
+        completion:        { required: true, type: 'string', enum: [...scanStore.COMPLETIONS] },
+        abort_code:        { type: 'string', maxLength: 64 },
+        findings_critical: { type: 'integer', min: 0 },
+        findings_high:     { type: 'integer', min: 0 },
+        findings_medium:   { type: 'integer', min: 0 },
+        findings_low:      { type: 'integer', min: 0 },
+        findings_summary:  { type: 'array' },
+        action_taken:      { type: 'string', enum: [...scanStore.ACTIONS] },
+        engine_version:    { required: true, type: 'string', maxLength: 64, minLength: 1 },
+      })) return;
+
+      const norm = scanStore.normalizeScanPayload(req.body);
+      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+
+      try {
+        const scan = await scanStore.insertScan(norm.value, req.builder.id);
+        res.status(201).json({ ok: true, scan });
+      } catch (err) {
+        console.error('[gds] POST /security/scans', err);
+        res.fail('scan_record_failed', 500);
+      }
+    }
+  );
+
+  // GET /api/bongos/security/scans?content_hash=<64 hex>
+  //
+  // "Have these exact bytes been scanned before, and what did the scan say?"
+  // Newest first. Rows carry structure only, so reading them can never expose
+  // the reader to the scanned artifact's content.
+  //
+  // rank: any-builder — deliberately open to every rank (see header).
+  router.get(
+    '/security/scans',
+    api.requireBuilder,
+    async (req, res) => {
+      const contentHash = String(req.query.content_hash || '').toLowerCase();
+      if (!/^[0-9a-f]{64}$/.test(contentHash)) {
+        return res.fail('bad_content_hash', 400, { expected: '64 lowercase hex chars' });
+      }
+      try {
+        const scans = await scanStore.findScans({ contentHash });
+        res.set('Cache-Control', 'no-store');
+        res.json({ scans });
+      } catch (err) {
+        console.error('[gds] GET /security/scans', err);
+        res.fail('scan_list_failed', 500);
+      }
+    }
+  );
+
+  return router;
+};

package/modules/security/scan-store.js

@@ -0,0 +1,214 @@
+// modules/security/scan-store.js — the security_tool_scans domain (task
+// 1002547, goal 1000055): one durable, queryable row per /scan-before-install
+// run, so one builder's scan warns the next.
+//
+// STRUCTURE ONLY, NEVER TARGET CONTENT. Everything stored here is later
+// rendered to whoever reads the table, so a quoted payload would make this
+// table a delivery mechanism for the very injection the scan exists to catch.
+// The normalize step therefore rejects anything shaped like quoted content —
+// multi-line messages, unknown item keys, fence-marked strings, oversized
+// summaries — and scrubs dangerous codepoints out of what remains. The DB's
+// own constraints (size cap, array shape, verdict/completion coupling) are the
+// second layer of the same rule.
+//
+// AN ABORTED SCAN IS RECORDABLE. completion='aborted'/'incomplete' with no
+// verdict is a first-class row — a scan that died must be visible as "died,
+// here is why", never laundered into a verdict or lost.
+//
+// The pure seam (normalizeScanPayload) is exported for the DB-free unit gate;
+// insertScan/findScans are the thin SQL on top. Pool reaches through the
+// published doorway; the scrub is an intra-module require of the vendored
+// fence-local (a module never requires a sibling module or a core internal).
+
+'use strict';
+
+const { pool } = require('../../src/module-api');
+const { scrubUntrusted, FENCE_MARKER } = require('./artifact-scan/fence-local');
+
+// Mirrors of the DB CHECK constraints — enforced here first so a bad payload
+// gets a clean 400 with a named code instead of a raw constraint violation.
+const TIERS = Object.freeze(['low', 'default', 'high', 'xhigh', 'max']);
+const VERDICTS = Object.freeze(['clean', 'caution', 'dangerous']);
+const COMPLETIONS = Object.freeze(['complete', 'aborted', 'incomplete']);
+const ARTIFACT_KINDS = Object.freeze(['repo', 'plugin', 'marketplace']);
+const ACTIONS = Object.freeze(['none', 'install_command_printed', 'sanitized_copy', 'rebuild_spec', 'declined']);
+const SEVERITIES = Object.freeze(['critical', 'high', 'medium', 'low']);
+
+// One-line claims only. maxSerializedBytes stays under the DB's 65536 cap so
+// the route rejects before the constraint ever fires.
+const SUMMARY_LIMITS = Object.freeze({
+  maxItems: 200,
+  maxCodeChars: 64,
+  maxFileChars: 300,
+  maxMessageChars: 300,
+  maxSerializedBytes: 60000,
+});
+const SUMMARY_ITEM_KEYS = Object.freeze(['code', 'severity', 'file', 'message']);
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const SHA_GIT = /^[0-9a-f]{7,40}$/i;
+
+const fail = (code, detail) => ({ ok: false, code, detail: detail ?? null });
+
+// Scrub + one-line + length + no-fence-marker checks for one summary string.
+// Returns { ok, value } | { ok:false, code }.
+function cleanSummaryString(raw, maxChars) {
+  const s = scrubUntrusted(raw);
+  if (/[\r\n]/.test(s)) return fail('summary_not_one_line');
+  if (s.length > maxChars) return fail('summary_string_too_long', { limit: maxChars });
+  if (s.includes(FENCE_MARKER)) return fail('summary_quoted_content');
+  return { ok: true, value: s };
+}
+
+function nonNegInt(v) {
+  return Number.isInteger(v) && v >= 0;
+}
+
+// Validate + normalize one scan payload into the exact column shape insertScan
+// writes. Pure — no DB, no I/O — so the whole contract is unit-testable.
+// target_host is DERIVED from the validated URL; a caller-supplied host field
+// is deliberately ignored (never trust the label over the address).
+function normalizeScanPayload(body) {
+  const b = body || {};
+
+  let url;
+  try {
+    url = new URL(String(b.target_url));
+  } catch {
+    return fail('bad_target_url');
+  }
+  if (url.protocol !== 'https:') return fail('bad_target_url', { reason: 'https only' });
+  if (String(b.target_url).length > 2048) return fail('bad_target_url', { reason: 'too long' });
+  // Embedded userinfo (https://ghp_xxx@github.com/…) would persist a live
+  // credential into a row EVERY rank can read. Refuse it outright — and store
+  // the parsed serialization below, never the caller's raw string, so nothing
+  // the URL parser did not vouch for can reach the table.
+  if (url.username || url.password) return fail('bad_target_url', { reason: 'credentials in URL are never stored' });
+
+  if (!ARTIFACT_KINDS.includes(b.artifact_kind)) return fail('bad_artifact_kind', { allowed: ARTIFACT_KINDS });
+  if (!TIERS.includes(b.tier)) return fail('bad_tier', { allowed: TIERS });
+  if (!COMPLETIONS.includes(b.completion)) return fail('bad_completion', { allowed: COMPLETIONS });
+
+  const hasVerdict = b.verdict !== undefined && b.verdict !== null;
+  if (hasVerdict && !VERDICTS.includes(b.verdict)) return fail('bad_verdict', { allowed: VERDICTS });
+  // The invariant that keeps "the scan died" from ever being read as "it
+  // passed": complete ⟺ verdict present. Same rule the DB enforces.
+  if ((b.completion === 'complete') !== hasVerdict) return fail('verdict_completion_mismatch');
+
+  if (b.resolved_sha != null && !SHA_GIT.test(String(b.resolved_sha))) return fail('bad_resolved_sha');
+  if (b.content_hash != null && !HEX64.test(String(b.content_hash))) return fail('bad_content_hash');
+
+  if (b.action_taken != null && !ACTIONS.includes(b.action_taken)) return fail('bad_action_taken', { allowed: ACTIONS });
+  if (typeof b.engine_version !== 'string' || b.engine_version.length === 0 || b.engine_version.length > 64) {
+    return fail('bad_engine_version');
+  }
+  if (b.abort_code != null && (typeof b.abort_code !== 'string' || b.abort_code.length > 64)) {
+    return fail('bad_abort_code');
+  }
+
+  if (b.file_count != null && !nonNegInt(b.file_count)) return fail('bad_counts', { field: 'file_count' });
+  if (b.total_bytes != null && !nonNegInt(b.total_bytes)) return fail('bad_counts', { field: 'total_bytes' });
+  const counts = {};
+  for (const sev of ['critical', 'high', 'medium', 'low']) {
+    const v = b[`findings_${sev}`] ?? 0;
+    if (!nonNegInt(v)) return fail('bad_counts', { field: `findings_${sev}` });
+    counts[sev] = v;
+  }
+
+  const rawSummary = b.findings_summary ?? [];
+  if (!Array.isArray(rawSummary)) return fail('summary_not_array');
+  if (rawSummary.length > SUMMARY_LIMITS.maxItems) return fail('summary_too_many_items', { limit: SUMMARY_LIMITS.maxItems });
+  const summary = [];
+  for (const item of rawSummary) {
+    if (item == null || typeof item !== 'object' || Array.isArray(item)) return fail('summary_bad_item');
+    for (const key of Object.keys(item)) {
+      if (!SUMMARY_ITEM_KEYS.includes(key)) return fail('summary_unknown_key', { key });
+    }
+    if (!SEVERITIES.includes(item.severity)) return fail('summary_bad_severity', { allowed: SEVERITIES });
+    const code = cleanSummaryString(String(item.code ?? ''), SUMMARY_LIMITS.maxCodeChars);
+    if (!code.ok) return code;
+    const file = cleanSummaryString(String(item.file ?? ''), SUMMARY_LIMITS.maxFileChars);
+    if (!file.ok) return file;
+    const message = cleanSummaryString(String(item.message ?? ''), SUMMARY_LIMITS.maxMessageChars);
+    if (!message.ok) return message;
+    summary.push({ code: code.value, severity: item.severity, file: file.value, message: message.value });
+  }
+  const serialized = JSON.stringify(summary);
+  if (Buffer.byteLength(serialized, 'utf8') > SUMMARY_LIMITS.maxSerializedBytes) {
+    return fail('summary_too_large', { limit: SUMMARY_LIMITS.maxSerializedBytes });
+  }
+
+  if (url.href.length > 2048) return fail('bad_target_url', { reason: 'too long' });
+
+  return {
+    ok: true,
+    value: {
+      target_url: url.href,
+      target_host: url.hostname,
+      artifact_kind: b.artifact_kind,
+      resolved_sha: b.resolved_sha != null ? String(b.resolved_sha).toLowerCase() : null,
+      content_hash: b.content_hash != null ? String(b.content_hash) : null,
+      file_count: b.file_count ?? null,
+      total_bytes: b.total_bytes ?? null,
+      tier: b.tier,
+      verdict: hasVerdict ? b.verdict : null,
+      completion: b.completion,
+      abort_code: b.abort_code ?? null,
+      findings_critical: counts.critical,
+      findings_high: counts.high,
+      findings_medium: counts.medium,
+      findings_low: counts.low,
+      findings_summary: summary,
+      action_taken: b.action_taken ?? null,
+      engine_version: b.engine_version,
+    },
+  };
+}
+
+// ---------- SQL (thin — everything above already validated) ----------
+
+async function insertScan(value, scannedByBuilderId) {
+  const { rows } = await pool.query(
+    `INSERT INTO security_tool_scans
+       (target_url, target_host, artifact_kind, resolved_sha, content_hash,
+        file_count, total_bytes, tier, verdict, completion, abort_code,
+        findings_critical, findings_high, findings_medium, findings_low,
+        findings_summary, action_taken, engine_version, scanned_by_builder_id)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19)
+     RETURNING *`,
+    [
+      value.target_url, value.target_host, value.artifact_kind, value.resolved_sha, value.content_hash,
+      value.file_count, value.total_bytes, value.tier, value.verdict, value.completion, value.abort_code,
+      value.findings_critical, value.findings_high, value.findings_medium, value.findings_low,
+      JSON.stringify(value.findings_summary), value.action_taken, value.engine_version, scannedByBuilderId,
+    ]
+  );
+  return rows[0];
+}
+
+// "Have these exact bytes been scanned before?" — the read every rank gets.
+// Explicit projection: exactly the columns the any-rank read surface intends,
+// so a future column addition never widens this boundary by default.
+async function findScans({ contentHash, limit = 20 }) {
+  const { rows } = await pool.query(
+    `SELECT id, target_url, target_host, artifact_kind, resolved_sha, content_hash,
+            file_count, total_bytes, tier, verdict, completion, abort_code,
+            findings_critical, findings_high, findings_medium, findings_low,
+            findings_summary, action_taken, engine_version, scanned_by_builder_id,
+            created_at, updated_at
+       FROM security_tool_scans
+      WHERE content_hash = $1
+      ORDER BY created_at DESC
+      LIMIT $2`,
+    [contentHash, Math.min(limit, 100)]
+  );
+  return rows;
+}
+
+module.exports = {
+  normalizeScanPayload,
+  insertScan,
+  findScans,
+  TIERS, VERDICTS, COMPLETIONS, ARTIFACT_KINDS, ACTIONS, SEVERITIES,
+  SUMMARY_LIMITS,
+};