hullproof 0.0.0-stage → 0.5.0

package/src/hooks/install.ts

@@ -0,0 +1,142 @@
+// hullproof hooks install and uninstall: a git pre-commit hook for plain git, a Husky entry, or a pre-commit framework entry.
+// The hook only calls `hullproof hooks run` (src/hooks/run.ts). Only exit code 1 from it blocks a commit; a missing command or an
+// engine error lets the commit through, because the hook must never be the reason a team cannot work. `git commit --no-verify` skips it.
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export type HookMode = 'git' | 'husky' | 'pre-commit';
+export const MARKER_BEGIN = '# >>> hullproof >>>';
+export const MARKER_END = '# <<< hullproof <<<';
+const HOOK_TAG = '# hullproof pre-commit hook';
+
+const sh = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
+const git = (repo: string, ...a: string[]): string | null => {
+  const r = spawnSync('git', ['-C', repo, ...a], { encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+};
+
+export interface Detected { root: string; mode: HookMode; husky: boolean; framework: boolean; hooksPath: string | null; huskyV8: boolean }
+
+export function detect(repo: string): Detected | string {
+  const root = git(repo, 'rev-parse', '--show-toplevel');
+  if (!root) return `${resolve(repo)} is not inside a git repository`;
+  const hooksPath = git(root, 'config', '--get', 'core.hooksPath');
+  let pkgHusky = false;
+  try {
+    const p = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as Record<string, Record<string, string> | undefined>;
+    pkgHusky = !!(p.devDependencies?.husky || p.dependencies?.husky);
+  } catch { /* no package.json */ }
+  const husky = existsSync(join(root, '.husky')) || pkgHusky || (hooksPath ?? '').replace(/^\.\//, '').startsWith('.husky');
+  const framework = existsSync(join(root, '.pre-commit-config.yaml'));
+  return { root, husky, framework, hooksPath, huskyV8: existsSync(join(root, '.husky/_/husky.sh')), mode: husky ? 'husky' : framework ? 'pre-commit' : 'git' };
+}
+
+// How the hook calls the engine: `hullproof` when it is on PATH now, else this very engine through node, by absolute path.
+export function runner(): string {
+  const onPath = spawnSync('sh', ['-c', 'command -v hullproof'], { encoding: 'utf8' });
+  if (onPath.status === 0 && onPath.stdout.trim()) return 'hullproof';
+  let cli = process.argv[1] ?? '';
+  try { cli = realpathSync(cli); } catch { /* keep as given */ }
+  return `${sh(process.execPath)} ${sh(cli)}`;
+}
+
+const callLines = (cmd: string): string[] => [
+  `${cmd} hooks run`,
+  'status=$?',
+  // Only a block (1) stops the commit. 127 (command not found) and any other code let it through.
+  'if [ "$status" -eq 1 ]; then exit 1; fi',
+];
+
+export const plainHook = (cmd: string): string => ['#!/bin/sh', `${HOOK_TAG}. Installed by hullproof hooks install, removed by hullproof hooks uninstall.`, '# Skip it once with: git commit --no-verify', ...callLines(cmd), 'exit 0', ''].join('\n');
+export const huskyBlock = (cmd: string): string => [MARKER_BEGIN, ...callLines(cmd), MARKER_END, ''].join('\n');
+export const frameworkBlock = (cmd: string): string => [
+  `  ${MARKER_BEGIN}`,
+  '  - repo: local',
+  '    hooks:',
+  '      - id: hullproof',
+  '        name: hullproof (secrets and blocking findings in staged files)',
+  `        entry: ${cmd} hooks run`,
+  '        language: system',
+  '        pass_filenames: false',
+  '        always_run: true',
+  `  ${MARKER_END}`, '',
+].join('\n');
+
+export interface InstallResult { code: number; lines: string[] }
+export interface InstallOptions { repo: string; mode: HookMode | null; dryRun: boolean; uninstall: boolean }
+
+const stripBlock = (text: string): string => {
+  const re = new RegExp(`\\n?[ \\t]*${MARKER_BEGIN.replace(/[>]/g, '\\>')}[\\s\\S]*?${MARKER_END.replace(/[<]/g, '\\<')}\\n?`, 'g');
+  return text.replace(re, '\n').replace(/\n{3,}/g, '\n\n');
+};
+
+export function installHooks(o: InstallOptions): InstallResult {
+  const d = detect(o.repo);
+  if (typeof d === 'string') return { code: 2, lines: [`hullproof hooks: ${d}`] };
+  const mode = o.mode ?? d.mode;
+  const lines: string[] = [`hullproof hooks: mode ${mode}${o.mode ? '' : ` (detected: Husky ${d.husky ? 'yes' : 'no'}, pre-commit framework ${d.framework ? 'yes' : 'no'})`}`];
+  const cmd = runner();
+  const write = (path: string, text: string, exec = false): void => {
+    if (o.dryRun) { lines.push(`would write ${path}`); return; }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    if (exec) chmodSync(path, 0o755);
+    lines.push(`wrote ${path}`);
+  };
+
+  if (mode === 'git') {
+    const hooksDir = git(d.root, 'rev-parse', '--git-path', 'hooks');
+    if (!hooksDir) return { code: 2, lines: [...lines, 'hullproof hooks: could not find the git hooks folder'] };
+    const path = resolve(d.root, hooksDir, 'pre-commit');
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (o.uninstall) {
+      if (current === null) lines.push('no pre-commit hook to remove');
+      else if (!current.includes(HOOK_TAG)) return { code: 2, lines: [...lines, `${path} is not a Hullproof hook, so it was left alone`] };
+      else if (o.dryRun) lines.push(`would remove ${path}`);
+      else { rmSync(path); lines.push(`removed ${path}`); }
+      return { code: 0, lines };
+    }
+    if (current !== null && !current.includes(HOOK_TAG)) {
+      return { code: 2, lines: [...lines, `${path} already exists and is not a Hullproof hook. It was not changed.`, 'Add this to it, or use the Husky or pre-commit framework mode:', ...callLines(cmd)] };
+    }
+    write(path, plainHook(cmd), true);
+    return { code: 0, lines };
+  }
+
+  if (mode === 'husky') {
+    const path = join(d.root, '.husky/pre-commit');
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (o.uninstall) {
+      if (current === null || !current.includes(MARKER_BEGIN)) lines.push('no Hullproof entry in .husky/pre-commit');
+      else write(path, stripBlock(current));
+      return { code: 0, lines };
+    }
+    if (current?.includes(MARKER_BEGIN)) { lines.push('.husky/pre-commit already has the Hullproof entry'); return { code: 0, lines }; }
+    const head = current ?? `#!/usr/bin/env sh\n${d.huskyV8 ? '. "$(dirname -- "$0")/_/husky.sh"\n' : ''}`;
+    write(path, `${head.replace(/\n*$/, '\n')}${huskyBlock(cmd)}`, true);
+    return { code: 0, lines };
+  }
+
+  // pre-commit framework
+  const path = join(d.root, '.pre-commit-config.yaml');
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  if (o.uninstall) {
+    if (current === null || !current.includes(MARKER_BEGIN)) lines.push('no Hullproof entry in .pre-commit-config.yaml');
+    else write(path, stripBlock(current));
+    return { code: 0, lines };
+  }
+  if (current?.includes(MARKER_BEGIN)) { lines.push('.pre-commit-config.yaml already has the Hullproof entry'); return { code: 0, lines }; }
+  const block = frameworkBlock(cmd);
+  // The entry is appended at the end of the file, which is only right when `repos:` is the last top level key and a block list.
+  const topKeys = (current ?? '').split('\n').filter((l) => /^[A-Za-z_][\w-]*\s*:/.test(l));
+  const last = topKeys.at(-1) ?? '';
+  const appendable = current === null || (/^repos\s*:\s*$/.test(last) && last === topKeys.find((k) => k.startsWith('repos')));
+  if (!appendable) {
+    return { code: 0, lines: [...lines, 'could not add the entry safely (the file has keys after `repos:` or a flow style list). Add this under `repos:` yourself:', '', block.replace(/^ {2}# .*\n/gm, '')] };
+  }
+  const base = current ?? 'repos:\n';
+  write(path, `${base.replace(/\n*$/, '\n')}${block}`);
+  lines.push('run `pre-commit install` once so the framework runs it on each commit');
+  return { code: 0, lines };
+}

package/src/hooks/run.ts

@@ -0,0 +1,121 @@
+// hullproof hooks run: the fast check the pre-commit hook calls. It looks at the staged files only, for two things: a secret, and a
+// finding of the highest severity (BLOCKER) that a deterministic check or a mapped Semgrep rule raises in a staged file.
+// Nothing leaves the machine: no network, no model, no upload. The staged content is exported from the index into a temporary
+// folder, so the check sees what the commit will hold and not the working tree. Findings in files that are not staged never block.
+// Exit 0 pass, 1 blocked. Any error is reported and lets the commit through (fail open), unless HULLPROOF_HOOK_STRICT=1.
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { makeContext } from '../checks/context.ts';
+import { checkSha, loadChecks, runChecks } from '../checks/run.ts';
+import { discover } from '../discover/discover.ts';
+import { buildFindings, type BuildInput } from '../report/build.ts';
+import { loadKit, readStage, resolveKitDir, type Edition } from '../report/kit.ts';
+import { RULES_DIR } from '../scanners/common.ts';
+import { runScanner } from '../scanners/index.ts';
+import { adapter as gitleaks } from '../scanners/gitleaks.ts';
+import { adapter as semgrep } from '../scanners/semgrep.ts';
+import type { ScanOptions } from '../scanners/types.ts';
+import { SEV_RANK } from '../report/kit.ts';
+import type { CheckResultsFile, FailRecord, Hit, ToolMeta } from '../types/index.ts';
+
+const SOURCE_FILES = /\.(js|mjs|cjs|ts|jsx|tsx|py|rb|php|go|java|kt|swift|yaml|yml|json|sql|tf|html)$/;
+
+export interface HookRun { code: number; lines: string[] }
+export interface HookOptions { repo: string; kit: string | null; semgrep: boolean; log?: (s: string) => void }
+
+const git = (repo: string, args: string[], extra: NodeJS.ProcessEnv = {}): { ok: boolean; out: string } => {
+  // --no-ext-diff and --no-textconv are given where they matter, so a driver named in the repository configuration cannot run.
+  const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', ...extra } });
+  return { ok: r.status === 0, out: r.stdout ?? '' };
+};
+
+export async function runHook(o: HookOptions): Promise<HookRun> {
+  const started = Date.now();
+  const top = git(o.repo, ['rev-parse', '--show-toplevel']);
+  if (!top.ok) return { code: 2, lines: ['hullproof: not inside a git repository'] };
+  const root = top.out.trim();
+  const staged = git(root, ['diff', '--cached', '--name-only', '--diff-filter=ACMR', '--no-ext-diff', '--no-textconv', '-z']).out.split('\0').filter(Boolean).sort();
+  if (staged.length === 0) return { code: 0, lines: [] };
+  const stagedSet = new Set(staged);
+
+  const tmp = mkdtempSync(join(tmpdir(), 'hullproof-hook-'));
+  try {
+    const tree = join(tmp, 'tree');
+    mkdirSync(tree);
+    // The index as it will be committed, exported to a folder; its index file is copied so checks that ask which files git tracks
+    // get the right answer.
+    const exp = git(root, ['checkout-index', '-a', '-f', `--prefix=${tree}/`]);
+    if (!exp.ok) throw new Error('could not read the staged files from the git index');
+    const idxPath = resolve(root, git(root, ['rev-parse', '--git-path', 'index']).out.trim());
+    mkdirSync(join(tree, '.git'));
+    if (existsSync(idxPath)) copyFileSync(idxPath, join(tree, '.git/index'));
+    writeFileSync(join(tree, '.git/HEAD'), 'ref: refs/heads/hook\n');
+
+    const kitDir = resolveKitDir(root, o.kit);
+    const kit = kitDir ? loadKit(kitDir) : null;
+    const edition: Edition = kit?.controls.some((c) => c.edition === 'pro') ? 'pro' : 'free';
+    const stack = discover(tree);
+    const controlsPath = kitDir ? join(kitDir, 'docs/hullproof/security-controls.json') : undefined;
+    const scanOpts = (extra: Partial<ScanOptions> = {}): ScanOptions => ({ repo: tree, out: join(tmp, 'out'), stack, allowNetwork: false, edition, history: false, kit: kitDir, controlsPath, ...extra });
+    const metas: ToolMeta[] = [];
+    const hits: Hit[] = [];
+    const notes: string[] = [];
+    const run = (a: typeof gitleaks, extra: Partial<ScanOptions> = {}): void => {
+      const s = runScanner(a, scanOpts(extra));
+      metas.push(s.meta);
+      hits.push(...s.hits.hits);
+      if (s.meta.status !== 'ran') notes.push(`${a.tool} did not run (${s.meta.status})`);
+    };
+
+    // 1. Secrets, which is the quick part: Gitleaks over the exported tree, kept to the staged files.
+    run(gitleaks);
+    const secretHits = hits.filter((h) => stagedSet.has(h.file));
+    const secretsBlock = blockers(secretHits, EMPTY, kit, edition, tree, metas, stagedSet);
+    if (secretsBlock.length || (secretHits.length && !kit)) {
+      const lines = secretsBlock.length ? render(secretsBlock) : secretHits.map((h) => `  BLOCKER ${h.file}:${h.line}  a secret shaped value (rule ${h.rule_id})`);
+      return done(1, lines, staged.length, started, notes);
+    }
+    if (!kit) return done(0, [], staged.length, started, [...notes, 'no kit was found (pass --kit or set HULLPROOF_KIT), so only secrets were checked']);
+
+    // 2. Blocking findings from the deterministic checks and, when it is on, Semgrep on the staged source files.
+    const sources = staged.filter((f) => SOURCE_FILES.test(f));
+    if (o.semgrep && sources.length) run(semgrep, { targets: sources });
+    const ctx = makeContext(tree, stack, hits, kitDir);
+    const checkDefs = loadChecks();
+    const checks = runChecks(ctx, checkDefs);
+    const found = blockers(hits.filter((h) => stagedSet.has(h.file)), checks, kit, edition, tree, metas, stagedSet, checkDefs);
+    return found.length ? done(1, render(found), staged.length, started, notes) : done(0, [], staged.length, started, notes);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const EMPTY: CheckResultsFile = { schema_version: '1.0.0', commit: null, results: [], not_run: [] };
+type Def = ReturnType<typeof loadChecks>;
+
+// Fail records of BLOCKER severity that point at a staged file. The same record builder the scan uses, so a rule or a check gives
+// the same title, requirement and fix here as in the report.
+function blockers(hits: Hit[], checks: CheckResultsFile, kit: ReturnType<typeof loadKit> | null, edition: Edition, tree: string, metas: ToolMeta[], staged: Set<string>, defs: Def = []): FailRecord[] {
+  if (!kit) return [];
+  const input: BuildInput = {
+    kit, scope: { edition, stage: readStage(tree).stage, stageSource: 'default' }, git: { commit: '0'.repeat(40), tree: '0'.repeat(40), clean: false },
+    checks, hits, metas, checkShas: Object.fromEntries(defs.map((c) => [c.id, checkSha(c)])), rulesDirs: [join(RULES_DIR, 'semgrep')],
+  };
+  const { file } = buildFindings(input);
+  return file.records.filter((r): r is FailRecord => r.kind === 'fail' && SEV_RANK[r.severity] >= SEV_RANK.BLOCKER && r.evidence.some((e) => staged.has(e.file)));
+}
+
+const render = (fs: FailRecord[]): string[] =>
+  fs.flatMap((f) => {
+    const e = f.evidence.find((x) => x.file) ?? f.evidence[0];
+    return [`  ${f.severity} ${e ? `${e.file}:${e.line}` : ''}  ${f.title} (${f.sec_ids.join(', ')})`, `    Fix: ${f.remediation.strategy}`];
+  });
+
+function done(code: number, problems: string[], n: number, started: number, notes: string[]): HookRun {
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
+  const lines = [...(code === 1 ? [`hullproof: BLOCKED, ${problems.filter((l) => l.startsWith('  ')&& !l.startsWith('    ')).length} problem(s) in the staged files`, ...problems] : []), ...notes.map((x) => `hullproof: note: ${x}`),
+    `hullproof: checked ${n} staged file${n === 1 ? '' : 's'} in ${secs}s on this machine, nothing was sent anywhere.${code === 1 ? ' To commit anyway: git commit --no-verify' : ''}`];
+  return { code, lines };
+}

package/src/map/analyze.ts

@@ -0,0 +1,219 @@
+// Reads one handler (or one decorator and wrapper region) and returns its protections, request inputs, data touches and
+// outbound calls. Pattern based; every fact carries a confidence. See docs/PHASE-2-DESIGN.md sections 2 and 6.
+import type { Confidence, DataTouch, InputRead, InputSource, Outbound, Protection, ProtectionKind, Scope } from '../types/index.ts';
+import { scanFile } from '../checks/code/webhook-verify.ts';
+import { EXITS, ifBody } from '../checks/code/shared.ts';
+import type { Lang, Lines } from './lex.ts';
+import { dataTouches, outboundCalls, type Region } from './touches.ts';
+import { taintOf, type Taint } from './taint.ts';
+import type { LocalVocab } from './local-vocab.ts';
+import {
+  AUDIT, AUTH_PACKAGES, RATE, RATE_PACKAGES, ROLE_JS, ROLE_PY, SESSION_JS, SESSION_PY, SIGNATURE, VALIDATION_JS, VALIDATION_PY,
+  type Pattern,
+} from './vocab.ts';
+
+export interface FileView { file: string; text: string; masked: string; lang: Lang; lines: Lines; imports: string }
+export interface Spec {
+  start: number; end: number;              // the handler, parameters included
+  seeds: string[];                          // names that hold request data on entry
+  decorators?: { view: FileView; start: number; end: number; scope: Scope }[]; // decorator, middleware or wrapper text outside the handler body
+  extraCalls?: string[];                    // names to look into besides the calls in the body (the wrapper function, middleware names)
+  gate?: boolean;                           // the region is a middleware or guard: a check that never rejects does not enforce anything
+  returnsJson?: boolean;
+}
+export interface HelperRef { view: FileView; start: number; end: number }
+export interface Helpers { find(name: string, fromFile?: string): HelperRef | null; local?: LocalVocab | null }
+
+export interface Analysis {
+  protections: Protection[]; reads: InputRead[]; data: DataTouch[]; outbound: Outbound[]; taint: Taint;
+}
+
+const usesText = (re: RegExp): boolean => /['"`]/.test(re.source);
+const CONF_RANK: Record<Confidence, number> = { high: 0, medium: 1, low: 2 };
+const minConf = (a: Confidence, b: Confidence): Confidence => (CONF_RANK[a] >= CONF_RANK[b] ? a : b);
+
+function facts(kind: ProtectionKind, pats: Pattern[], view: FileView, from: number, to: number, scope: Scope, upgrade: boolean, viaPrefix = ''): Protection[] {
+  const out: Protection[] = [];
+  const seen = new Set<string>();
+  const masked = view.masked.slice(from, to);
+  const text = view.text.slice(from, to);
+  for (const p of pats) {
+    p.re.lastIndex = 0;
+    const m = p.re.exec(usesText(p.re) ? text : masked);
+    if (!m || seen.has(p.via)) continue;
+    const ln = view.lines.at(from + m.index);
+    if (out.some((o) => o.line === ln)) continue;
+    seen.add(p.via);
+    const conf = upgrade && p.confidence === 'medium' ? 'high' : p.confidence;
+    out.push({ kind, scope, file: view.file, line: ln, via: viaPrefix + p.via, enforced: null, confidence: viaPrefix ? minConf(conf, 'medium') : conf });
+  }
+  return out;
+}
+
+// Whether a failed check provably stops the request. true: the check sits in an if whose body exits, or it is a throwing
+// guard (require..., a decorator). false: it is tested and the body does not exit. null: cannot tell.
+function enforcedFor(view: FileView, at: number, via: string): boolean | null {
+  const { text } = view;
+  const lineStart = text.lastIndexOf('\n', at) + 1;
+  const lineEnd = text.indexOf('\n', at) < 0 ? text.length : text.indexOf('\n', at);
+  const before = text.slice(lineStart, at);
+  if (/^@|decorator|Depends|permission_classes|login/.test(via) && /(^|\n)\s*@|Depends\s*\(|permission_classes/.test(text.slice(lineStart, lineEnd))) return true;
+  const ifAt = /\b(?:if|unless|elif|assert)\b/.exec(before);
+  if (ifAt) {
+    const body = view.lang === 'py' ? text.slice(lineStart + ifAt.index, Math.min(text.length, lineEnd + 400)).split('\n').slice(0, 4).join('\n') : ifBody(text, lineStart + ifAt.index);
+    return EXITS.test(body);
+  }
+  if ((/\b(?:require|ensure|assert)\w*/i.test(via) || /^local (?:auth|role) helper$/.test(via)) && !/=/.test(before)) return true;
+  const lhs = /(?:\b(?:const|let|var|val)\s+)?(\{[^}]*(?:\{[^}]*\}[^}]*)*\}|\[[^\]]*\]|[A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*(?:await\s+)?[\w.$]*\s*$/.exec(before);
+  if (!lhs) return null;
+  const names = [...lhs[1].matchAll(/[A-Za-z_$][\w$]*/g)].map((x) => x[0]).filter((n) => !['const', 'let', 'var', 'data', 'error', 'session'].includes(n) || lhs[1] === n);
+  const rest = text.slice(lineEnd, Math.min(text.length, lineEnd + 1500));
+  for (const n of names) {
+    const guard = view.lang === 'py'
+      ? new RegExp(`\\bif\\s+(?:not\\s+${n}\\b|${n}\\s+is\\s+None|${n}\\s*==\\s*None)`)
+      : new RegExp(`\\bif\\s*\\(\\s*(?:!\\s*${n}\\b|${n}\\s*(?:===?|==)\\s*(?:null|undefined)\\b|!\\s*${n}\\s*\\|\\||!${n}\\?)`);
+    const g = guard.exec(rest);
+    if (!g) continue;
+    const body = view.lang === 'py' ? rest.slice(g.index, g.index + 300).split('\n').slice(0, 4).join('\n') : ifBody(rest, g.index);
+    return EXITS.test(body);
+  }
+  return null;
+}
+
+const READS: [InputSource, RegExp, boolean][] = [
+  ['body', /\b(?:req|request|ctx\.request|c\.req)\s*\.\s*(?:body|json|get_json|data|text)\b|\bawait\s+\w+\.json\s*\(\)|\bJSON\.parse\s*\(\s*(?:raw|body|await)/, false],
+  ['query', /\b(?:req|request)\.(?:query|args|GET|query_params|nextUrl)\b|\bsearchParams\b|\bc\.req\.query\b|\bctx\.query\b|\bparse_qs\b/, false],
+  ['params', /\b(?:req|request|ctx|c\.req)\.params?\b|\bparams\s*[.\[]|\bc\.req\.param\b|\bview_args\b|\bkwargs\b|\bPath\s*\(/, false],
+  ['headers', /\b(?:req|request)\.headers\b|\bheaders\s*\(\s*\)|\bc\.req\.header\b|\bgetHeader\s*\(|\brequest\.META\b/, false],
+  ['cookies', /\b(?:req|request)\.cookies\b|\bcookies\s*\(\s*\)|\bgetCookie\s*\(|\bc\.req\.cookie\b/, false],
+  ['form', /\bformData\b|\brequest\.form\b|\brequest\.POST\b|\bFormData\s*\(|\bmultipart\b/i, false],
+  ['file', /\.get\s*\(\s*['"](?:file|files|upload|image|avatar|attachment|document|photo)s?['"]\s*\)|\bas\s+File\b|\bmulter\b|\breq\.files?\b|\brequest\.files\b|\bformidable\b|\bbusboy\b|\binstanceof\s+File\b|\bUploadFile\b|\brequest\.FILES\b|\.file\s*\(\s*['"]|\bupload\.(?:single|array|fields|any)\b|\bFileInterceptor\b|\bFilesInterceptor\b|\bgetAll\s*\(\s*['"]file/, false],
+];
+function readsOf(view: FileView, from: number, to: number): InputRead[] {
+  const masked = view.masked.slice(from, to);
+  const out: InputRead[] = [];
+  for (const [source, re] of READS) {
+    const m = re.exec(masked);
+    if (m) out.push({ source, line: view.lines.at(from + m.index) });
+  }
+  return out;
+}
+
+const PARSE_CALL = /\bawait\s+\w+\.json\s*\(\)|\b(?:req|request)\.(?:json|get_json)\s*\(|\bJSON\.parse\s*\(|\bjson\.loads\s*\(|\.formData\s*\(\)|\brequest\.(?:json|form)\b/;
+
+// A helper body that turns a request away: an error status, a throw, an abort or a redirect.
+const REJECT = /\b(?:401|403|unauthori[sz]ed|forbidden)\b|\bthrow\b|\braise\b|\babort\s*\(|\bnext\s*\(\s*(?:new\s+)?\w*Error|\bcreateError\b|\bHTTPException\b|\bPermissionDenied\b|\bAuthenticationFailed\b|\bredirect\s*\(|\bstatus\s*\(\s*4\d\d|\bdenyAll\b/i;
+
+const CALL = /(?<![.\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+const SKIP_CALLS = new Set(['if', 'for', 'while', 'switch', 'function', 'return', 'catch', 'await', 'async', 'typeof', 'new', 'super', 'require', 'import', 'print', 'len', 'str', 'int', 'dict', 'list', 'set', 'tuple', 'range', 'isinstance', 'type', 'super', 'sorted', 'map', 'filter', 'json', 'Number', 'String', 'Boolean', 'Array', 'Object', 'Date', 'Promise', 'Error', 'parseInt', 'parseFloat', 'setTimeout', 'fetch', 'def', 'class', 'with', 'except', 'elif', 'lambda', 'not', 'and', 'or']);
+
+export function analyze(view: FileView, spec: Spec, helpers: Helpers): Analysis {
+  const lang = view.lang;
+  const { start, end } = spec;
+  const upgradeSession = AUTH_PACKAGES.test(view.imports);
+  const upgradeRate = RATE_PACKAGES.test(view.imports);
+  const local = helpers.local ?? null;
+  const sessionPats = [...(lang === 'js' ? SESSION_JS : SESSION_PY), ...(local?.auth ? [local.auth] : [])];
+  const rolePats = [...(lang === 'js' ? ROLE_JS : ROLE_PY), ...(local?.role ? [local.role] : [])];
+  const valPats = lang === 'js' ? VALIDATION_JS : VALIDATION_PY;
+
+  const prot: Protection[] = [];
+  const own = (kind: ProtectionKind, pats: Pattern[], upgrade: boolean): void => {
+    for (const f of facts(kind, pats, view, start, end, 'handler', upgrade)) {
+      prot.push({ ...f, enforced: kind === 'session_read' || kind === 'role_check' ? enforcedFor(view, firstIndex(view, start, end, pats, f.via, start), f.via) : null });
+    }
+  };
+  own('session_read', sessionPats, upgradeSession);
+  own('role_check', rolePats, false);
+  own('rate_limit', RATE, upgradeRate);
+  own('input_validation', valPats, false);
+  own('audit_log', AUDIT, false);
+
+  // Signature checks: where it is, whether a failed check stops the request, and whether the body is parsed first.
+  const sig = facts('signature_verify', SIGNATURE, view, start, end, 'handler', false);
+  if (sig.length) {
+    const region = view.text.slice(start, end);
+    const bad = scanFile(view.file, region);
+    const onlyMissing = bad.length > 0 && bad.every((b) => /^no call that checks/.test(b.note));
+    const enforced = bad.length === 0 ? true : onlyMissing ? null : false;
+    const first = sig.reduce((a, b) => (a.line <= b.line ? a : b));
+    const parse = PARSE_CALL.exec(view.masked.slice(start, end));
+    const parseLine = parse ? view.lines.at(start + parse.index) : null;
+    for (const f of sig) prot.push({ ...f, enforced, after_parse: parseLine !== null && parseLine < first.line });
+  }
+
+  // Decorators, middleware and wrappers outside the handler body.
+  const extra = new Set<string>(spec.extraCalls ?? []);
+  for (const d of spec.decorators ?? []) {
+    const dv = d.view;
+    const dl = dv.lang;
+    const keep = (kind: ProtectionKind, pats: Pattern[], up: boolean): void => { for (const f of facts(kind, pats, dv, d.start, d.end, d.scope, up)) prot.push({ ...f, enforced: kind === 'session_read' || kind === 'role_check' ? (f.confidence === 'high' ? true : null) : null }); };
+    keep('session_read', [...(dl === 'js' ? SESSION_JS : SESSION_PY), ...(local?.auth ? [local.auth] : [])], AUTH_PACKAGES.test(dv.imports));
+    keep('role_check', [...(dl === 'js' ? ROLE_JS : ROLE_PY), ...(local?.role ? [local.role] : [])], false);
+    keep('rate_limit', RATE, RATE_PACKAGES.test(dv.imports));
+    keep('input_validation', dl === 'js' ? VALIDATION_JS : VALIDATION_PY, false);
+    keep('audit_log', AUDIT, false);
+    for (const f of facts('signature_verify', SIGNATURE, dv, d.start, d.end, d.scope, false)) prot.push({ ...f, enforced: null });
+    for (const m of dv.masked.slice(d.start, d.end).matchAll(CALL)) if (!SKIP_CALLS.has(m[1])) extra.add(m[1]);
+  }
+
+  // One hop into the repository's own helper functions the handler calls.
+  const have = (k: ProtectionKind): boolean => prot.some((p) => p.kind === k);
+  const names = new Set<string>();
+  for (const m of view.masked.slice(start, end).matchAll(CALL)) if (!SKIP_CALLS.has(m[1])) names.add(m[1]);
+  for (const n of extra) names.add(n);
+  let hops = 0;
+  for (const name of [...names].sort()) {
+    if (hops >= 30) break;
+    const h = helpers.find(name, view.file);
+    if (!h) continue;
+    hops++;
+    const hv = h.view;
+    const hf: [ProtectionKind, Pattern[], boolean][] = [
+      ['session_read', [...(hv.lang === 'js' ? SESSION_JS : SESSION_PY), ...(local?.auth ? [local.auth] : [])], AUTH_PACKAGES.test(hv.imports)],
+      ['role_check', [...(hv.lang === 'js' ? ROLE_JS : ROLE_PY), ...(local?.role ? [local.role] : [])], false], ['rate_limit', RATE, RATE_PACKAGES.test(hv.imports)],
+      ['input_validation', hv.lang === 'js' ? VALIDATION_JS : VALIDATION_PY, false], ['audit_log', AUDIT, false],
+    ];
+    for (const [kind, pats, up] of hf) {
+      if (kind === 'session_read' && have('session_read')) continue;
+      if (have(kind) && kind !== 'audit_log') continue;
+      const found = facts(kind, pats.filter((p) => p.confidence !== 'low'), hv, h.start, h.end, 'handler', up, `helper:${name} `);
+      if (found.length) {
+        const idx = view.masked.slice(start, end).search(new RegExp(`(?<![.\\w$])${name.replace(/\$/g, '\\$')}\\s*\\(`));
+        const at = idx < 0 ? view.lines.at(start) : view.lines.at(start + idx);
+        const rejects = REJECT.test(hv.text.slice(h.start, h.end));
+        const enforced = rejects ? true : spec.gate && (kind === 'session_read' || kind === 'role_check') ? false : null;
+        prot.push({ ...found[0], file: view.file, line: at, via: `helper:${name} ${found[0].via.replace(`helper:${name} `, '')}`, enforced });
+      }
+    }
+  }
+
+  // Taint, then data touches and outbound calls.
+  const maskedBody = view.masked.slice(start, end);
+  const textBody = view.text.slice(start, end);
+  const taint = taintOf(maskedBody, textBody, spec.seeds, lang, local?.auth ? [local.auth] : []);
+  const region: Region = { masked: maskedBody, text: textBody, base: start, line: (i) => view.lines.at(start + i) };
+  const data = dataTouches(region, taint, lang);
+  const outbound = outboundCalls(region, taint, lang, spec.returnsJson ?? true, view.imports);
+
+  // owner_filter: a data touch that names an owner is a protection on that read or write.
+  for (const d of data) if (d.owner_scoped && (d.by_id || d.request_derived || d.op !== 'read')) prot.push({ kind: 'owner_filter', scope: 'handler', file: view.file, line: d.line, via: `${d.store} ${d.target ?? ''}`.trim(), enforced: null, confidence: d.store === 'sql' ? 'medium' : 'medium' });
+
+  prot.sort((a, b) => a.line - b.line || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0) || (a.via < b.via ? -1 : a.via > b.via ? 1 : 0));
+  return { protections: dedupe(prot), reads: readsOf(view, start, end), data, outbound, taint };
+}
+
+function dedupe(ps: Protection[]): Protection[] {
+  const seen = new Set<string>();
+  return ps.filter((p) => { const k = `${p.kind}|${p.scope}|${p.line}|${p.via}`; if (seen.has(k)) return false; seen.add(k); return true; });
+}
+
+// The character index of the first match of the pattern with this `via` inside [from, to), for enforcedFor.
+function firstIndex(view: FileView, from: number, to: number, pats: Pattern[], via: string, fallback: number): number {
+  const p = pats.find((x) => x.via === via);
+  if (!p) return fallback;
+  p.re.lastIndex = 0;
+  const src = usesText(p.re) ? view.text.slice(from, to) : view.masked.slice(from, to);
+  const m = p.re.exec(src);
+  return m ? from + m.index : fallback;
+}