hullproof 0.0.0-stage → 0.5.0

package/dist/map/touches.js

@@ -0,0 +1,355 @@
+import { closeOf, splitArgs, statementEnd } from './lex.js';
+import { hasSessionValue, identifiers, isTainted } from './taint.js';
+import { OWNER, PRIVILEGED, REDIRECT_GUARD, URL_GUARD } from './vocab.js';
+const clip = (s, n) => (s.length <= n ? s : s.slice(0, n - 1) + '…');
+const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
+// String literals in a region, found from the quotes that mask() keeps.
+function literals(masked, lang) {
+    const out = [];
+    for (let i = 0; i < masked.length; i++) {
+        const c = masked[i];
+        if (c !== '"' && c !== "'" && c !== '`')
+            continue;
+        const triple = lang === 'py' && masked.startsWith(c.repeat(3), i);
+        const close = triple ? masked.indexOf(c.repeat(3), i + 3) : masked.indexOf(c, i + 1);
+        if (close < 0)
+            break;
+        const prefix = lang === 'py' ? masked.slice(Math.max(0, i - 2), i) : '';
+        out.push({ open: i, start: i + (triple ? 3 : 1), end: close, quote: c, fString: /[fF]$/.test(prefix) || /[fF][rRbB]$/.test(prefix) || /[rRbB][fF]$/.test(prefix) });
+        i = close + (triple ? 2 : 0);
+    }
+    return out;
+}
+const SQL_START = /^\s*\(?\s*(SELECT|INSERT\s+INTO|UPDATE|DELETE\s+FROM|REPLACE\s+INTO|WITH\s+\w+\s+AS)\b/i;
+const SQL_ID = /(?:^|[\s(,.])(?:\w+\.)?(?:id|uuid|pk|_id)\s*=\s*(?:\?|\$\d+|:\w+|%s|@\w+|\$\{|\{|'\s*\+|"\s*\+|'\s*$|"\s*$|\s*$)/i;
+const SQL_END = /\b(?:ORDER\s+BY|GROUP\s+BY|LIMIT|RETURNING|OFFSET|HAVING)\b|;/i;
+function sqlTouch(lit, region, t, lang) {
+    const sql = region.text.slice(lit.start, lit.end);
+    const m = SQL_START.exec(sql);
+    if (!m || sql.length < 12)
+        return null;
+    const word = m[1].toUpperCase();
+    const op = word.startsWith('SELECT') || word.startsWith('WITH') ? 'read' : word.startsWith('DELETE') ? 'delete' : 'write';
+    const target = (/\b(?:FROM|INTO|UPDATE)\s+(?:ONLY\s+)?([\w."]+)/i.exec(sql)?.[1] ?? null)?.replace(/"/g, '') ?? null;
+    const w = /\bWHERE\b/i.exec(sql);
+    let where = '';
+    if (w) {
+        const rest = sql.slice(w.index + 5);
+        const e = SQL_END.exec(rest);
+        where = e ? rest.slice(0, e.index) : rest;
+    }
+    const interpolated = lang === 'js' ? lit.quote === '`' && /\$\{/.test(sql) : lit.fString && /\{[^{}]+\}/.test(sql);
+    const interpExprs = lang === 'js' ? [...sql.matchAll(/\$\{([^}]*)\}/g)].map((x) => x[1]) : lit.fString ? [...sql.matchAll(/\{([^{}]+)\}/g)].map((x) => x[1]) : [];
+    // The statement around the literal: back to the previous ";", "{" or "}" and forward to the end of the statement.
+    let begin = lit.open;
+    for (let k = lit.open - 1; k >= 0 && lit.open - k < 700; k--) {
+        const c = region.masked[k];
+        if (c === ';' || c === '{' || c === '}') {
+            begin = k + 1;
+            break;
+        }
+        begin = k;
+    }
+    while (begin < lit.open && /\s/.test(region.masked[begin]))
+        begin++;
+    const end = statementEnd(region.masked, begin);
+    const around = region.masked.slice(begin, end);
+    const concat = /^\s*(?:\+|%|\.format\s*\()/.test(region.masked.slice(lit.end + 1, lit.end + 14)) || /\+\s*$/.test(region.masked.slice(Math.max(0, lit.open - 6), lit.open));
+    const requestDerived = interpExprs.some((e) => isTainted(t, e, lang)) || isTainted(t, around, lang);
+    const rawSql = (interpolated && interpExprs.some((e) => isTainted(t, e, lang))) || (concat && isTainted(t, around, lang));
+    const params = positionalArgs(region, lit, begin, end);
+    const valueTainted = (expr, offset) => {
+        // The value of a column or limit: an interpolation in the text, or the parameter at its placeholder position.
+        const inline = [...expr.matchAll(lang === 'js' ? /\$\{([^}]*)\}/g : /\{([^{}]+)\}/g)].map((x) => x[1]);
+        if (inline.length)
+            return inline.some((e) => isTainted(t, e, lang));
+        const ph = /\?|%s|\$(\d+)/.exec(expr);
+        if (!ph)
+            return false;
+        if (!params)
+            return false;
+        const before = sql.slice(0, offset + ph.index);
+        const idx = ph[1] ? Number(ph[1]) - 1 : (before.match(/\?|%s/g) ?? []).length;
+        return params[idx] !== undefined && isTainted(t, params[idx], lang);
+    };
+    const sets = [];
+    if (op === 'write') {
+        const set = /\bSET\b/i.exec(sql);
+        if (set) {
+            const wh = /\bWHERE\b/i.exec(sql.slice(set.index));
+            const body = sql.slice(set.index + 3, wh ? set.index + wh.index : sql.length);
+            for (const part of splitTopOffsets(body, set.index + 3)) {
+                const cm = /^\s*(?:\w+\.)?"?(\w+)"?\s*=\s*([\s\S]*)$/.exec(part.text);
+                if (cm && PRIVILEGED.test(cm[1]) && valueTainted(cm[2], part.offset + part.text.indexOf(cm[2])))
+                    sets.push(cm[1]);
+            }
+        }
+        else {
+            const ins = /\(([^)]*)\)\s*VALUES\s*\(/i.exec(sql);
+            if (ins) {
+                const cols = ins[1].split(',').map((x) => x.trim().replace(/"/g, ''));
+                const vopen = ins.index + ins[0].length - 1;
+                const vclose = closeIn(sql, vopen);
+                const vals = splitTopOffsets(sql.slice(vopen + 1, vclose), vopen + 1);
+                cols.forEach((c, i) => { if (PRIVILEGED.test(c) && vals[i] && valueTainted(vals[i].text, vals[i].offset))
+                    sets.push(c); });
+            }
+        }
+    }
+    // by_id: the id comparison itself takes a request value (not just any request value somewhere in the statement).
+    let byId = false;
+    if (w) {
+        const idm = new RegExp(SQL_ID.source, 'i').exec(sql.slice(w.index + 5));
+        if (idm) {
+            const eq = idm.index + idm[0].indexOf('=') + 1;
+            const offset = w.index + 5 + eq;
+            byId = valueTainted(sql.slice(offset, offset + 30), offset) || (concat && requestDerived && /=\s*['"]?\s*$/.test(sql.slice(offset - 1, w.index + 5 + idm.index + idm[0].length + 1)));
+        }
+    }
+    let limitFromRequest = false;
+    const lm = /\bLIMIT\s+(\?|%s|\$\d+|:\w+|\$\{[^}]*\}|\{[^{}]*\})/i.exec(sql);
+    if (lm)
+        limitFromRequest = valueTainted(lm[1], lm.index + 6);
+    return {
+        store: 'sql', op, target, line: region.line(lit.open), by_id: byId, limit_from_request: limitFromRequest,
+        request_derived: requestDerived, owner_scoped: OWNER.test(where) && hasSessionValue(t, `${around} ${interpExprs.join(' ')}`), raw_sql: rawSql, sets: [...new Set(sets)].sort(), mass_assign: false, confidence: 'high',
+    };
+}
+function closeIn(s, open) {
+    let depth = 0;
+    for (let i = open; i < s.length; i++) {
+        if (s[i] === '(')
+            depth++;
+        else if (s[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return s.length;
+}
+function splitTopOffsets(s, base) {
+    const out = [];
+    let depth = 0;
+    let from = 0;
+    for (let i = 0; i <= s.length; i++) {
+        const c = s[i];
+        if (c === '(')
+            depth++;
+        else if (c === ')')
+            depth--;
+        if ((c === ',' && depth === 0) || i === s.length) {
+            if (s.slice(from, i).trim())
+                out.push({ text: s.slice(from, i), offset: base + from });
+            from = i + 1;
+        }
+    }
+    return out;
+}
+// The parameter expressions that go with a SQL string, in order: the array or tuple given to run, get, all, execute or query
+// after it (JavaScript), or the second argument of the call that holds it (Python and others).
+function positionalArgs(region, lit, begin, end) {
+    const m = region.masked;
+    const after = /^\s*,?\s*\)?\s*\.\s*(?:run|get|all|execute|query|exec|values|iterate|pluck|raw)\s*\(/.exec(m.slice(lit.end + 1, end));
+    let open = -1;
+    if (after)
+        open = lit.end + 1 + after[0].length - 1;
+    else {
+        // The literal is an argument of a call: execute("...", (a, b)).
+        for (let k = lit.open - 1; k >= begin; k--) {
+            if (m[k] === '(') {
+                open = k;
+                break;
+            }
+            if (m[k] === ')')
+                break;
+        }
+    }
+    if (open < 0)
+        return null;
+    const args = splitArgs(m, open);
+    let rest = args;
+    if (!after)
+        rest = args.filter((a) => a.start > lit.open);
+    if (!rest.length)
+        return null;
+    const first = m.slice(rest[0].start, rest[0].end);
+    if (/^[\[(]/.test(first) && (rest.length === 1 || !after)) {
+        const inner = splitArgs(m, rest[0].start);
+        if (inner.length || /^[\[(]\s*[\])]$/.test(first))
+            return inner.map((a) => region.text.slice(a.start, a.end));
+    }
+    return rest.map((a) => region.text.slice(a.start, a.end));
+}
+const NOT_MODEL = new Set(['Object', 'Array', 'Promise', 'Math', 'JSON', 'Number', 'String', 'Symbol', 'Buffer', 'Date', 'Map', 'Set', 'WeakMap', 'Reflect', 'Proxy', 'Intl', 'URL', 'Error', 'Response', 'NextResponse', 'Request', 'Headers', 'FormData', 'File', 'Blob', 'Boolean', 'RegExp', 'Uint8Array', 'process', 'console', 'React', 'Cache', 'Event', 'AbortController', 'URLSearchParams', 'TextEncoder', 'TextDecoder', 'Atomics', 'BigInt']);
+const OP_WORDS = [[/^(?:find|get|select|count|aggregate|exists|query|read|list|distinct|group|all|filter|exclude|values|first|last|only|defer|order_by|annotate|iterator|one)/i, 'read'], [/^(?:create|insert|update|upsert|save|set|add|bulk|replace|merge|increment|decrement)/i, 'write'], [/^(?:delete|destroy|remove|drop|truncate)/i, 'delete']];
+const opOf = (name) => OP_WORDS.find(([re]) => re.test(name))?.[1] ?? 'unknown';
+function callArgs(region, open) {
+    const c = closeOf(region.masked, open);
+    return region.text.slice(open, c < 0 ? Math.min(region.text.length, open + 400) : c);
+}
+function ormTouch(store, name, target, args, at, region, t, lang, confidence, byIdName) {
+    const op = opOf(name);
+    const derived = isTainted(t, args, lang);
+    let byId = byIdName && derived;
+    // key: value pairs of the argument object (JavaScript) or keyword arguments (Python); a shorthand key is its own value.
+    const pairs = [];
+    if (lang === 'js')
+        for (const m of args.matchAll(/(?:^|[{,\s])([A-Za-z_$][\w$]*)\s*(?::\s*([^,}\n]+)|(?=\s*[,}]))/g))
+            pairs.push([m[1], m[2] ?? m[1]]);
+    else
+        for (const m of args.matchAll(/(?:^|[(,\s])([A-Za-z_]\w*)\s*=\s*([^,)\n]+)/g))
+            pairs.push([m[1], m[2]]);
+    // A shorthand key inside a nested object, as in { where: { id } }, is swallowed by the value of the outer key above.
+    if (lang === 'js')
+        for (const m of args.matchAll(/[{,]\s*([A-Za-z_$][\w$]*)\s*(?=[,}])/g))
+            pairs.push([m[1], m[1]]);
+    for (const [k, v] of pairs)
+        if (/^(?:id|_id|uuid|pk)$/.test(k) && isTainted(t, v, lang))
+            byId = true;
+    const sets = op === 'write' ? pairs.filter(([k, v]) => PRIVILEGED.test(k) && isTainted(t, v, lang)).map(([k]) => k) : [];
+    const limit = pairs.some(([k, v]) => /^(?:take|limit|first|pageSize|page_size|per_page|perPage|size|max|count)$/.test(k) && isTainted(t, v, lang)) || /\.\s*(?:limit|take|range|slice)\s*\(\s*[^)]*\)/.test(args) && [...args.matchAll(/\.\s*(?:limit|take|range|slice)\s*\(([^)]*)\)/g)].some((m) => isTainted(t, m[1], lang));
+    const spread = /\.\.\.\s*([\w$.]+)|\*\*\s*([\w.]+)|data\s*:\s*([\w$.]+)\s*[,}]|\(\s*([\w$.]+)\s*\)\s*$/g;
+    let mass = false;
+    if (op === 'write')
+        for (const m of args.matchAll(spread)) {
+            const v = m[1] ?? m[2] ?? m[3] ?? m[4];
+            if (v && identifiers(v).some((i) => t.names.has(i) && !t.trusted.has(i) && !t.validated.has(i)) && !/^\s*(?:id|where)/.test(v))
+                mass = true;
+        }
+    return { store, op, target, line: region.line(at), by_id: byId, limit_from_request: limit, request_derived: derived, owner_scoped: OWNER.test(args) && hasSessionValue(t, args), raw_sql: false, sets: [...new Set(sets)].sort(), mass_assign: mass, confidence };
+}
+export function dataTouches(region, t, lang) {
+    const out = [];
+    const { masked } = region;
+    for (const lit of literals(masked, lang)) {
+        const d = sqlTouch(lit, region, t, lang);
+        if (d)
+            out.push(d);
+    }
+    const seen = new Set();
+    const add = (m, build) => {
+        const open = m.index + m[0].length - 1;
+        if (seen.has(open))
+            return;
+        const d = build(open);
+        if (d) {
+            seen.add(open);
+            out.push(d);
+        }
+    };
+    if (lang === 'js') {
+        for (const m of masked.matchAll(/\b(prisma|db|client|tx|trx|database|orm)\s*\.\s*([A-Za-z_]\w*)\s*\.\s*(findUnique|findFirst|findMany|findUniqueOrThrow|findFirstOrThrow|create|createMany|update|updateMany|upsert|delete|deleteMany|count|aggregate|groupBy)\s*\(/g))
+            add(m, (open) => ormTouch('prisma', m[3], m[2], callArgs(region, open), m.index, region, t, lang, 'high', false));
+        for (const m of masked.matchAll(/\b([A-Za-z_$][\w$]*)\s*\.\s*(find|findOne|findById|findByPk|findAll|findAndCountAll|findOneOrFail|findOneBy|findBy|findById\w*|findOneAnd\w+|updateOne|updateMany|deleteOne|deleteMany|create|createMany|insertMany|insertOne|bulkCreate|countDocuments|count|aggregate|destroy|update|upsert|save|remove)\s*\(/g)) {
+            const recv = m[1];
+            const modelLike = (/^[A-Z]\w*$/.test(recv) && !NOT_MODEL.has(recv)) || /(?:Model|Collection|Repo|Repository)$/.test(recv);
+            if (!modelLike)
+                continue;
+            add(m, (open) => ormTouch(/Collection$/.test(recv) || /^(?:findOneAnd|insertOne|insertMany|updateOne|deleteOne|countDocuments)/.test(m[2]) ? 'mongo' : 'orm', m[2], recv, callArgs(region, open), m.index, region, t, lang, 'medium', /^findById|^findByPk/.test(m[2])));
+        }
+        for (const m of masked.matchAll(/\.\s*from\s*\(\s*(['"])/g)) {
+            const quoteAt = m.index + m[0].length - 1;
+            const close = masked.indexOf(m[1], quoteAt + 1);
+            const table = region.text.slice(quoteAt + 1, close);
+            const end = statementEnd(masked, m.index); // from the dot of .from(, so the whole chain is read
+            const chain = region.text.slice(close, end);
+            const verb = /\.\s*(select|insert|update|delete|upsert)\s*\(/.exec(chain);
+            if (!verb)
+                continue;
+            const op = verb[1] === 'select' ? 'read' : verb[1] === 'delete' ? 'delete' : 'write';
+            const eqs = [...chain.matchAll(/\.\s*(?:eq|match|in|filter)\s*\(\s*['"]([\w.]+)['"]\s*,\s*([^)]*)\)/g)];
+            const byId = eqs.some((e) => /^(?:id|uuid|_id)$/.test(e[1]) && isTainted(t, e[2], lang));
+            const sets = [];
+            if (op === 'write')
+                for (const c of chain.matchAll(/(?:^|[{,\s])([A-Za-z_]\w*)\s*:/g))
+                    if (PRIVILEGED.test(c[1]))
+                        sets.push(c[1]);
+            out.push({ store: /\.storage\s*\.\s*from/.test(masked.slice(Math.max(0, m.index - 12), m.index + 6)) ? 'object_storage' : 'supabase', op, target: table, line: region.line(m.index), by_id: byId, limit_from_request: [...chain.matchAll(/\.\s*(?:limit|range)\s*\(([^)]*)\)/g)].some((x) => isTainted(t, x[1], lang)), request_derived: isTainted(t, chain, lang), owner_scoped: OWNER.test(chain.replace(/\.\s*(?:select|insert)\s*\([^)]*\)/g, '')) && hasSessionValue(t, chain), raw_sql: false, sets: [...new Set(sets)].sort(), mass_assign: op === 'write' && /\(\s*(?:body|req\.body|await\s+\w+\.json\(\))\s*\)/.test(chain), confidence: 'high' });
+        }
+        for (const m of masked.matchAll(/\b(?:redis|cache|kv)\s*\.\s*(get|set|del|hget|hset|hgetall|incr|expire|setex)\s*\(/g))
+            out.push({ store: 'redis', op: opOf(m[1]), target: null, line: region.line(m.index), by_id: false, limit_from_request: false, request_derived: isTainted(t, callArgs(region, m.index + m[0].length - 1), lang), owner_scoped: false, raw_sql: false, sets: [], mass_assign: false, confidence: 'medium' });
+        for (const m of masked.matchAll(/\bfs(?:\.promises)?\s*\.\s*(readFile|readFileSync|createReadStream|writeFile|writeFileSync|createWriteStream|unlink|unlinkSync|readdir|readdirSync|appendFile|rm|rmSync)\s*\(/g)) {
+            const args = callArgs(region, m.index + m[0].length - 1);
+            out.push({ store: 'filesystem', op: /^(?:read|create.*Read)/.test(m[1]) ? 'read' : /unlink|rm/.test(m[1]) ? 'delete' : 'write', target: null, line: region.line(m.index), by_id: false, limit_from_request: false, request_derived: isTainted(t, args, lang), owner_scoped: false, raw_sql: false, sets: [], mass_assign: false, confidence: 'high' });
+        }
+    }
+    else {
+        for (const m of masked.matchAll(/\b([A-Z]\w*)\s*\.\s*objects\s*\.\s*(get|filter|all|exclude|create|update|delete|get_or_create|update_or_create|bulk_create|values|first|last|count|exists|select_related|prefetch_related)\s*\(/g))
+            add(m, (open) => {
+                // The verb at the end of the chain decides the operation: Note.objects.filter(pk=pk).delete().
+                const chain = region.masked.slice(open, statementEnd(region.masked, m.index));
+                const verb = /\)\s*\.\s*(delete|update|create|bulk_create|bulk_update|update_or_create|get_or_create)\s*\(/.exec(chain);
+                const tail = verb ? region.text.slice(open, open + chain.length) : callArgs(region, open);
+                const d = ormTouch('orm', verb ? verb[1] : m[2], m[1], verb ? tail : callArgs(region, open), m.index, region, t, lang, 'high', false);
+                // A slice such as [:limit] after the query is a limit; it counts when the bound is request data.
+                const slice = [...chain.matchAll(/\[\s*(?:[^\]:]*:)\s*([^\]]+)\]/g)].some((x) => isTainted(t, region.text.slice(open + (x.index ?? 0), open + (x.index ?? 0) + x[0].length), lang));
+                return slice ? { ...d, limit_from_request: true } : d;
+            });
+        for (const m of masked.matchAll(/\bget_object_or_404\s*\(/g))
+            add(m, (open) => ormTouch('orm', 'get', null, callArgs(region, open), m.index, region, t, lang, 'high', false));
+        for (const m of masked.matchAll(/\b([A-Z]\w*)\s*\.\s*query\s*\.\s*(get|get_or_404|filter|filter_by|all|first|first_or_404|delete|one|one_or_none|count)\s*\(/g))
+            add(m, (open) => ormTouch('orm', m[2], m[1], callArgs(region, open), m.index, region, t, lang, 'high', /^get/.test(m[2])));
+        for (const m of masked.matchAll(/\b(?:db\.)?session\s*\.\s*(query|get|add|delete|merge|execute|scalar|scalars)\s*\(/g))
+            add(m, (open) => ormTouch('orm', m[1] === 'query' ? 'select' : m[1], null, callArgs(region, open), m.index, region, t, lang, 'medium', m[1] === 'get'));
+        for (const m of masked.matchAll(/\b(\w*(?:collection|coll|db))\s*\.\s*(find|find_one|insert_one|insert_many|update_one|update_many|delete_one|delete_many|count_documents|aggregate|replace_one)\s*\(/g))
+            add(m, (open) => ormTouch('mongo', m[2], m[1], callArgs(region, open), m.index, region, t, lang, 'medium', false));
+        for (const m of masked.matchAll(/\.\s*table\s*\(\s*['"]([\w.]+)['"]\s*\)/g))
+            out.push({ store: 'supabase', op: 'unknown', target: m[1], line: region.line(m.index), by_id: false, limit_from_request: false, request_derived: false, owner_scoped: false, raw_sql: false, sets: [], mass_assign: false, confidence: 'medium' });
+        for (const m of masked.matchAll(/\b(?:open|os\.remove|os\.unlink|shutil\.\w+|send_from_directory|send_file|Path)\s*\(/g)) {
+            const args = callArgs(region, m.index + m[0].length - 1);
+            out.push({ store: 'filesystem', op: /remove|unlink|rmtree/.test(m[0]) ? 'delete' : 'read', target: null, line: region.line(m.index), by_id: false, limit_from_request: false, request_derived: isTainted(t, args, lang), owner_scoped: false, raw_sql: false, sets: [], mass_assign: false, confidence: 'medium' });
+        }
+    }
+    out.sort((a, b) => a.line - b.line || (a.store < b.store ? -1 : a.store > b.store ? 1 : 0) || ((a.target ?? '') < (b.target ?? '') ? -1 : 1));
+    return out;
+}
+const HTTP_JS = /(?<![.\w$])(?:fetch|ofetch|\$fetch)\s*\(|\b(?:axios|got|ky|needle|superagent|undici|http|https)\s*(?:\.\s*(?:get|post|put|patch|delete|request|head|fetch|stream))?\s*\(|\bnew\s+(?:Request|XMLHttpRequest)\s*\(|\bhttps?\.(?:get|request)\s*\(/g;
+const HTTP_PY = /\b(?:requests|httpx|aiohttp|urllib3?)\s*\.\s*(?:get|post|put|patch|delete|request|head|urlopen|fetch)\s*\(|\burlopen\s*\(|\burllib\.request\.\w+\s*\(|\bhttp\.client\.\w+\s*\(|\bpycurl\b/g;
+// A client object from an HTTP library the file imports: async with httpx.AsyncClient() as client: client.get(url)
+const HTTP_PY_CLIENT = /\b(?:client|session|async_client|http_client|http)\s*\.\s*(?:get|post|put|patch|delete|request|head)\s*\(/g;
+const AI_RE = /\b(?:openai|anthropic|genai|ollama|cohere|mistral|groq|replicate)\s*\.\s*(?:chat\.completions\.create|completions\.create|messages\.create|responses\.create|generate_content|generateContent|chat|generate|invoke|stream|embeddings\.create|images\.generate)\s*\(|\b(?:generateText|streamText|generateObject|streamObject|embed|embedMany)\s*\(|\bChatCompletion\.create\s*\(/g;
+const EMAIL_RE = /\b(?:sendMail|sendEmail|send_mail|send_email)\s*\(|\.emails\s*\.\s*send\s*\(|\bsgMail\s*\.\s*send\s*\(|\bresend\s*\.|\btransporter\s*\.\s*sendMail\s*\(|\bses\s*\.\s*send\w*\s*\(|\bmailgun\b|\bpostmark\b/g;
+const SMS_RE = /\btwilio\b|\bsns\s*\.\s*publish\s*\(|\bsendSms\w*\s*\(|\bsend_sms\w*\s*\(|\bvonage\b/g;
+const PAY_RE = /\bstripe\s*\.\s*\w+\s*\.\s*(?:create|retrieve|update|capture|refund|cancel)\s*\(|\bpaystack\w*\s*\.|\bpaddle\w*\s*\.\s*\w+|\bflutterwave\b|\bgateway\s*\.\s*charge\s*\(/g;
+const PROC_JS = /\b(?:exec|execSync|execFile|execFileSync|spawn|spawnSync|fork)\s*\(|\beval\s*\(|\bnew\s+Function\s*\(|\bvm\.run\w*\s*\(/g;
+const PROC_PY = /\b(?:subprocess\s*\.\s*\w+|os\s*\.\s*(?:system|popen|exec\w*)|eval|exec|commands\.getoutput)\s*\(/g;
+const REDIRECT = /(?<![.\w$])redirect\s*\(|\b(?:NextResponse|Response|res|reply|ctx|c)\s*\.\s*redirect\s*\(|\bHttpResponseRedirect\s*\(|\bRedirectResponse\s*\(|\bres\.(?:writeHead|status)\s*\(\s*30\d|\bhead\s*\(\s*['"]Location['"]|\bset(?:Header)?\s*\(\s*['"]Location['"]/g;
+const REDIRECT_KEY = /(?:^|[{,\s])(redirect|redirectTo|redirect_to|redirectUrl|redirect_url|returnTo|return_to|next|nextUrl|callbackUrl|callback_url|location|url)\s*:\s*([^,}\n]+)/g;
+function firstArg(region, open) {
+    const a = splitArgs(region.masked, open);
+    return a.length ? oneLine(region.text.slice(a[0].start, a[0].end)) : '';
+}
+export function outboundCalls(region, t, lang, returnsJson, imports = '') {
+    const out = [];
+    const fnText = region.text;
+    const add = (kind, re, guard, confidence) => {
+        re.lastIndex = 0;
+        for (const m of region.masked.matchAll(re)) {
+            const open = region.masked.indexOf('(', m.index);
+            const target = open < 0 ? '' : firstArg(region, open);
+            const full = open < 0 ? '' : callArgs(region, open);
+            out.push({ kind, line: region.line(m.index), target: clip(target || oneLine(m[0]), 120), request_derived: kind === 'ai_model' || kind === 'email' || kind === 'sms' || kind === 'payment' ? isTainted(t, full, lang) : isTainted(t, target || full, lang), guarded: guard ? guard.test(fnText) : false, confidence });
+        }
+    };
+    add('http', lang === 'js' ? HTTP_JS : HTTP_PY, URL_GUARD, 'high');
+    if (lang === 'py' && /httpx|aiohttp|requests/.test(imports))
+        add('http', HTTP_PY_CLIENT, URL_GUARD, 'medium');
+    add('ai_model', AI_RE, null, 'medium');
+    add('email', EMAIL_RE, null, 'medium');
+    add('sms', SMS_RE, null, 'medium');
+    add('payment', PAY_RE, null, 'medium');
+    add('process', lang === 'js' ? PROC_JS : PROC_PY, null, 'high');
+    add('redirect', REDIRECT, REDIRECT_GUARD, 'high');
+    if (returnsJson) {
+        for (const m of fnText.matchAll(REDIRECT_KEY)) {
+            if (m[1] === 'url' || m[1] === 'location')
+                continue;
+            out.push({ kind: 'redirect', line: region.line(m.index), target: clip(oneLine(m[2]), 120), request_derived: isTainted(t, m[2], lang), guarded: REDIRECT_GUARD.test(fnText), confidence: 'medium' });
+        }
+    }
+    const seen = new Set();
+    return out.filter((o) => { const k = `${o.kind}:${o.line}:${o.target}`; if (seen.has(k))
+        return false; seen.add(k); return true; })
+        .sort((a, b) => a.line - b.line || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+}

package/dist/map/vocab.js

@@ -0,0 +1,88 @@
+// Packages whose import in a file makes a vocabulary hit in that file high confidence.
+export const AUTH_PACKAGES = /next-auth|@auth\/|@clerk\/|@supabase\/|firebase-admin|firebase\/auth|passport|jsonwebtoken|\bjose\b|@kinde|lucia|better-auth|iron-session|@auth0|express-jwt|koa-jwt|@fastify\/jwt|@fastify\/auth|@nestjs\/passport|@nestjs\/jwt|flask_login|flask_jwt_extended|flask_httpauth|fastapi\.security|django\.contrib\.auth|rest_framework|authlib|python-jose|jwt\b/;
+export const RATE_PACKAGES = /express-rate-limit|rate-limiter-flexible|@upstash\/ratelimit|@nestjs\/throttler|express-slow-down|flask_limiter|slowapi|django_ratelimit|ratelimit|limits\b|fastify-rate-limit|@fastify\/rate-limit|hono-rate-limiter/;
+const p = (re, via, confidence) => ({ re, via, confidence });
+// Session read, JavaScript and TypeScript. A match means the handler asks who the caller is.
+export const SESSION_JS = [
+    p(/\bAuthGuard\s*\(|@UseGuards\s*\([^)]*(?:Auth|Jwt|JWT|Session|Firebase|Clerk|Supabase)\w*Guard/, 'AuthGuard', 'high'),
+    p(/\bgetServerSession\s*\(/, 'getServerSession', 'high'),
+    p(/\b(?:supabase|client|sb)\w*\.auth\.(?:getUser|getSession|getClaims)\s*\(|\bauth\.(?:getUser|getSession)\s*\(/, 'auth.getUser', 'high'),
+    p(/\bgetToken\s*\(\s*\{/, 'getToken', 'high'),
+    p(/\b(?:jwt\.verify|jwtVerify|verifyIdToken|verifySessionCookie|jwt\.decode)\s*\(/, 'jwt verify', 'high'),
+    p(/\bpassport\.authenticate\s*\(/, 'passport.authenticate', 'high'),
+    p(/\b(?:getAuth|clerkClient|currentUser|auth)\s*\(\s*(?:req|request)?\s*\)/, 'auth()', 'medium'),
+    p(/\b(?:req|request)\.(?:user|session|auth)\b|\bctx\.state\.user\b|\bres\.locals\.(?:user|session)\b|\bc\.get\(\s*['"](?:user|session|jwtPayload)/, 'request user', 'medium'),
+    p(/\b(?:require|ensure|assert)(?:Auth|User|Login|Session|Authenticated|SignedIn)\w*\b/, 'require auth', 'medium'),
+    p(/\b(?:is|check)(?:Authenticated|LoggedIn|Auth|Authorized|SignedIn)\w*\b/, 'is authenticated', 'medium'),
+    p(/\b(?:get|find|load|fetch|resolve)?(?:Current|Session|Auth|Logged|Viewer|Signed)(?:In)?User\w*\s*\(|\bcurrentUser\w*\s*\(|\buserFrom(?:Token|Session|Cookie|Request)\w*\s*\(|\bgetUserFrom\w*\s*\(|\bgetViewer\w*\s*\(/, 'current user', 'medium'),
+    p(/\bgetSession\s*\(/, 'getSession', 'medium'),
+    p(/\bauthenticate\w*\s*\(|\bverifyToken\w*\s*\(|\bverifyJwt\w*\s*\(|\bwithAuth\w*\b|\bauthMiddleware\b|\bisAuthorized\s*\(|\bprotect\s*\(/, 'authenticate', 'medium'),
+    p(/\b(?:req|request)\.cookies\.get\s*\(\s*['"][^'"]*(?:session|token|auth|jwt|sid)[^'"]*['"]|\bcookies\s*\(\s*\)\s*\.\s*get\s*\(\s*['"][^'"]*(?:session|token|auth|jwt|sid)[^'"]*['"]|\bcookies\.get\s*\(\s*['"][^'"]*(?:session|token|auth|jwt|sid)/i, 'session cookie read', 'low'),
+    p(/\bheaders?\b[^;\n]{0,40}\bauthorization\b|\bauthorization\b\s*[\]:)]|['"]authorization['"]/i, 'authorization header', 'low'),
+];
+export const SESSION_PY = [
+    p(/@(?:\w+\.)?(?:login_required|jwt_required|auth_required|token_required|permission_required|user_passes_test|authenticated|requires_auth)\b/, 'login decorator', 'high'),
+    p(/\bDepends\s*\(\s*(?:get_current_\w*|oauth2_scheme|get_user\w*|require_\w*|current_\w*|verify_\w*|auth\w*|get_token\w*|\w*(?:auth|token|jwt|bearer)\w*)\s*\)|\bSecurity\s*\(|\bHTTPBearer\b|\bOAuth2PasswordBearer\b/, 'Depends(auth)', 'high'),
+    p(/\b(?:get_jwt_identity|get_jwt|verify_jwt_in_request|jwt\.decode|decode_token)\s*\(/, 'jwt', 'high'),
+    p(/@(?:\w+\.)?(?:authorize\w*|authenticate\w*|api_key_required|requires_api_key)\b/, 'auth decorator by name', 'medium'),
+    p(/@(?:\w+\.)?(?:require_(?:user|login|auth\w*|session|token|member|account|jwt)|ensure_(?:user|login|auth\w*)|login_?required|auth_?required|authenticated_only)\b/, 'login decorator by name', 'medium'),
+    p(/\bpermission_classes\s*=\s*[\[(][^\])]*(?:IsAuthenticated|IsAdminUser|DjangoModelPermissions|IsAuthenticatedOrReadOnly)|\bLoginRequiredMixin\b|\bauthentication_classes\s*=\s*[\[(][^\])]*\w/, 'permission_classes', 'high'),
+    p(/\bcurrent_user\b|\bg\.user\b|\brequest\.user\b|\brequest\.session\b|\bsession\s*\[|\bsession\.get\s*\(|\bauth\.get_user\b|\brequest\.auth\b/, 'current user', 'medium'),
+    p(/\b(?:get|require|ensure)_(?:current_)?(?:user|session)(?!_by_)\w*\s*\(|\bauthenticate\s*\(|\bis_authenticated\b|\bverify_token\w*\s*\(/, 'get user', 'medium'),
+    p(/request\.headers(?:\.get\s*\(\s*|\s*\[\s*)['"]Authorization/i, 'authorization header', 'low'),
+];
+export const ROLE_JS = [
+    p(/\brole\s*(?:===?|!==?)\s*["'`](?:admin|owner|superadmin|staff|moderator|manager)/i, 'role compare', 'high'),
+    p(/["'`](?:admin|owner|superadmin|staff)["'`]\s*(?:===?|!==?)\s*[\w.?]*role|roles?\.(?:includes|some)\(\s*["'`](?:admin|owner|staff)/i, 'role compare', 'high'),
+    p(/@(?:Roles|PreAuthorize|Secured|RolesAllowed|HasRole|RequirePermissions|Permissions)\s*\(/, 'role decorator', 'high'),
+    p(/\b(?:requireRole|require_role|checkRole|withRole|hasRole|hasPermission|hasAnyRole|assertRole|requirePermission|requireAdmin|assertAdmin|ensureAdmin|adminOnly|adminMiddleware|checkAdmin|isSuperAdmin)\w*\b|\b(?:can|ability\.can|authorize)\s*\(|\b(?:isAdmin|is_admin|isStaff|isSuperUser)\b/, 'role check', 'medium'),
+    p(/\bis(?:Accounting|Moderator|Manager|Owner|Superuser|SuperAdmin|Deluxe|Admin)\w*\s*\(/, 'role check', 'medium'),
+];
+export const ROLE_PY = [
+    p(/@(?:\w+\.)?(?:roles_required|role_required|admin_required|staff_member_required|superuser_required|permission_required|user_passes_test|require_role|requires_roles|roles_accepted)\b/, 'role decorator', 'high'),
+    p(/\bDepends\s*\(\s*\w*(?:superuser|admin|staff|moderator)\w*\s*\)/, 'Depends(admin)', 'medium'),
+    p(/@(?:\w+\.)?(?:require_(?:admin|role\w*|permission\w*|staff|superuser|owner)|admin_only|admin_?required|only_admin\w*)\b/, 'role decorator by name', 'medium'),
+    p(/\b(?:IsAdminUser|DjangoModelPermissions|PermissionRequiredMixin|UserPassesTestMixin|IsSuperuser|IsStaff)\b/, 'permission class', 'high'),
+    p(/\.(?:is_staff|is_superuser|is_admin)\b|\bhas_perms?\s*\(|\bcurrent_user\.(?:role|is_admin)|\buser\.role\s*(?:==|!=|in)\b|\brole\s*(?:==|!=)\s*['"](?:admin|staff|owner)/i, 'role compare', 'medium'),
+    p(/\b(?:require|check|assert|ensure)_(?:admin|role|permission|staff|superuser)\w*\s*\(|\bDepends\s*\(\s*(?:require_admin|admin_required|get_admin\w*|check_admin\w*|require_role\w*|get_current_admin\w*)\)/, 'role check', 'medium'),
+];
+export const SIGNATURE = [
+    p(/\b(?:constructEvent|construct_event|constructEventAsync|webhooks\.verify|wh\.verify|Webhook\.construct|verifyWebhook\w*|validateWebhook\w*|verifySignature\w*|verify_signature\w*|validateSignature\w*|validate_signature\w*|checkSignature\w*|verifyHmac\w*|verifyRequestSignature|isValidSignature\w*|svix|verify_webhook\w*)\b/, 'signature verify', 'high'),
+    p(/\b(?:timingSafeEqual|compare_digest|hash_equals|secure_compare|hmac\.Equal)\s*\(|\bcreateHmac\s*\(|\bhmac\.new\s*\(/, 'hmac compare', 'high'),
+    p(/\bverify(?!\w*pass(?:word|wd)?\b)\w*\s*\(\s*(?:raw|body|payload|req|request|signature|sig)\b/i, 'verify call', 'medium'),
+];
+export const RATE = [
+    p(/\b(?:rateLimit|rateLimiter|slowDown|checkRateLimit|withRateLimit|ratelimit|Ratelimit|RateLimiterMemory|RateLimiterRedis|RateLimiter|throttle)\w*\s*[(.]|\b\w*(?:rate_?limit|ratelimit|limiter)\w*\s*\(|\b\w*(?:[lL]imiter|RateLimit|rateLimit|ratelimit|[tT]hrottler?)\w*\b/i, 'rate limit', 'medium'),
+    p(/@(?:Throttle|SkipThrottle|UseGuards\s*\(\s*ThrottlerGuard|\w*limiter\.limit|limiter\.limit|ratelimit|rate_limit|ratelimited|throttle)\b|\bthrottle_classes\s*=|\bThrottlerGuard\b|\bdefault_limits\b|\bDepends\s*\(\s*\w*(?:rate|limit)\w*\s*\)|\blimiter\.limit\s*\(/i, 'rate limit decorator', 'high'),
+];
+export const VALIDATION_JS = [
+    p(/\.(?:safeParse|safeParseAsync|parseAsync|spa)\s*\(/, 'schema parse', 'high'),
+    p(/(?:\b(?!JSON|Date|Number|Math|url|URL|path|qs|querystring|yaml|toml|Intl|parseInt)[A-Za-z_$][\w$]*|\))\.parse\s*\(\s*(?:await\s+)?(?:req|request|body|params|query|input|data|formData|Object\.fromEntries|await)/, 'schema parse', 'high'),
+    p(/\b(?:Joi|joi)\.\w+|\.validateAsync\s*\(|\byup\b|\bvalibot\b|\bajv\b|\bcelebrate\s*\(|\bcheckSchema\s*\(|\bvalidationResult\s*\(|\bvalidateRequest\s*\(|\bvalidateBody\s*\(|\bvalidateOrReject\s*\(|\bplainToInstance\s*\(|\bplainToClass\s*\(|\bTypeBox\b|\bType\.Object\s*\(/, 'validation library', 'high'),
+    p(/\b(?:body|param|query|check|header|cookie)\s*\(\s*['"][\w.\[\]*]+['"]\s*\)\s*\.\s*(?:is\w+|not\w*|trim|escape|exists|notEmpty|optional|matches|isLength|custom)\b/, 'express-validator', 'high'),
+    p(/\.input\s*\(\s*(?:z\.|\w+Schema)/, 'trpc input', 'high'),
+    p(/\bschema\s*:\s*\{|\bschema\s*:\s*\w+Schema\b/, 'route schema', 'medium'),
+    p(/\b(?:validate|sanitize|validateInput|validatePayload|assertValid|isValid\w*)\s*\(/, 'validate call', 'low'),
+];
+export const VALIDATION_PY = [
+    p(/\.(?:model_validate|model_validate_json|parse_obj|parse_raw|validate_python)\s*\(/, 'pydantic', 'high'),
+    p(/\b\w*Schema\s*\(\s*[^)]*\)\s*\.\s*(?:load|validate|loads)\s*\(|\bschema\.(?:load|validate)\s*\(/, 'marshmallow', 'high'),
+    p(/\.(?:is_valid|validate_on_submit|full_clean)\s*\(/, 'form or serializer valid', 'high'),
+    p(/\b(?:validate|jsonschema\.validate|cerberus|voluptuous|wtforms|FlaskForm)\b/, 'validation library', 'medium'),
+];
+export const AUDIT = [
+    p(/\b\w*(?:[aA]udit|ACTIVITY_?LOG|[aA]ctivity_?[lL]og|[sS]ecurity_?[lL]og|[aA]dmin_?[lL]og|[lL]og_?[aA]dmin_?[aA]ction)\w*\b|\b(?:record_?event|log_?event|logActivity|logSecurityEvent|recordEvent)\b/, 'audit log', 'medium'),
+    p(/INSERT\s+INTO\s+(?:\w+\.)?(?:audit|activity|security_events?|admin_log)/i, 'audit insert', 'high'),
+];
+// Privileged column names: setting one of these from request data is the mass assignment weakness (SEC-AUTHZ-004).
+export const PRIVILEGED = /^(?:role|roles|plan|tier|is_?admin|admin|is_?staff|is_?superuser|is_?super_?admin|permissions?|balance|credits?|subscription\w*|entitlements?|email_?verified|verified|account_?type|user_?type|org_?id|tenant_?id|owner_?id|stripe_?customer_?id|price|amount)$/i;
+export const OWNER = /owner|user_?id|userId|tenant|account_?id|accountId|org_?id|orgId|organi[sz]ation|workspace|created_?by|createdBy|author|auth\.uid|current_?user|request\.user|session\.user|\.user\.id|ctx\.user|\buid\b|\bscope\b|policy|member|\.user\b|user\s*=|owner\s*=/i;
+export const ADMIN_PATH = /(^|[\/_.-])(admin|administrator|backoffice|back-office|staff|superuser|internal|manage|management|moderator)([\/_.-]|$)/i;
+export const AUTH_ENDPOINT = /(^|[\/_.-])(login|log-in|signin|sign-in|signup|sign-up|register|registration|logout|log-out|signout|sign-out|reset|forgot|forgotten|password|token|oauth|otp|verify|callback|magic|session|2fa|mfa|authenticate)([\/_.\-:]|$)/i;
+export const PUBLIC_PATH = /^\/(?:api\/|v\d+\/|rest\/)?(health|healthz|ping|status|metrics|ready|readiness|liveness|robots\.txt|favicon\.ico|sitemap\.xml|public|static|assets|docs|openapi|swagger|\.well-known)(\/|$|\.)/i;
+// Guards for allowlist style checks inside one function.
+export const URL_GUARD = /[aA]llow(?:ed)?_?(?:[lL]ist|[hH]osts?|[dD]omains?|[oO]rigins?|[uU]rls?)|\.Hostname\s*\(\)|allow(?:ed)?_?(?:list|hosts?|domains?|origins?|urls?)|ALLOWED_\w+|whitelist|isPrivate|private-?ip|isSafeUrl|isAllowedUrl|validateUrl|assertPublicUrl|safeFetch|ssrf|ip\.isPrivate|ipaddress|is_private|hostname\s*(?:===?|!==?|in)\b|\.hostname\.(?:endsWith|includes|startsWith)|\bnew URL\([^)]*\)\.(?:hostname|host|origin)\s*(?:===?|!==?)|\bhosts?\.(?:has|includes)\(|\bdomains?\.(?:has|includes)\(|netloc\s*(?:==|in|!=)/;
+export const REDIRECT_GUARD = /\b(?:redirect_to|redirect_back|redirect)\s*\(?\s*(?:Routes\.\w+|\w+_(?:path|url)\b)|HasPrefix\(\s*\w+\s*,\s*"\/"|start_with\?\s*\(?\s*['"]\/|\burl_from\s*\(|allow_other_host:\s*false|str_starts_with\s*\(\s*\$\w+\s*,\s*['"]\/|Str::startsWith\(\s*\$\w+\s*,\s*['"]\/|[aA]llowed(?:Redirect|Host|Url)s?\b|startsWith\(\s*['"]\/(?!\/)|allow(?:ed)?_?(?:list|redirects?|hosts?|urls?)|ALLOWED_\w+|whitelist|is_safe_url|url_has_allowed_host_and_scheme|isSafeRedirect|isAllowedRedirect|safe_redirect|safeRedirect|sanitizeRedirect|\.origin\s*(?:===?|!==?)|\.hostname\s*(?:===?|!==?)|\.host\s*(?:===?|!==?)\s*[\w.:]+(?:domain|host|origin)|netloc\s*(?:==|in|!=)|\bnew URL\([^)]*\)\.(?:host|hostname|origin)|startswith\(\s*['"]\//;
+export const SIZE_GUARD = /\bmax:\d+|(?:\.size|\.length|byteLength|content_?length|\.len\b)\s*(?:>=?|<=?)|(?:>=?|<=?)\s*(?:MAX_\w+|\w*[mM]ax\w*)|limits\s*:\s*\{[^}]*fileSize|maxFileSize|max_?file_?size|MAX_CONTENT_LENGTH|FILE_UPLOAD_MAX_MEMORY_SIZE|DATA_UPLOAD_MAX|max_?size|fileSize|MaxFileSizeValidator|maxSize|ParseFilePipe|\bmax_length\b|\bcontent_length_range\b|\blimit\s*:\s*['"]?\d/i;
+export const TYPE_GUARD = /\bmimes:|\bmimetypes:|\|image\b|\bextensions:|(?:mimetype|mime_?type|content_?type|\.type|extname|\.ext\b|splitext)\b[^;\n]{0,80}(?:===|!==|==|!=|\.includes|\.startsWith|\.endsWith|\.match|\bin\b|\.test\()|(?:includes|has|test|startsWith|endsWith)\([^)]*\b(?:mimetype|mime|\.type|ext|content_?type)|fileFilter|allowed(?:Types|Extensions|Mimes?|_extensions|_types)|ALLOWED_\w+|fileTypeFromBuffer|file-type|imghdr|\bmagic\b|secure_filename|FileTypeValidator|ParseFilePipe|\bfiletype\.|python-magic/i;
+export const CLAMP = /Math\.(?:min|max)\s*\(|\bmin\s*\(|\]\s*\.min\b|\.clamp\b|\.min\s*\(|\bclamp\s*\(|\bMAX_\w+|\.max\s*\(\s*\d+|\bmaxLimit\b|\bMAX_PAGE\w*|\bPAGE_SIZE_MAX\w*|le\s*=\s*\d+|\bmax_value\b|Number\.isInteger|\bmax_page_size\b|\bpaginate_by\b|\bPAGE_SIZE\b|\bmaximum\b|\.int\(\)\.max|\.positive\(\)\.max|\.lte\s*\(/;

package/dist/mapping/controls.js

@@ -0,0 +1,34 @@
+// Reads the kit's security-controls.json, the source of truth for requirement IDs, edition and the tests each control
+// ships. The engine never copies it. Path order: the explicit argument, HULLPROOF_CONTROLS, HULLPROOF_KIT, then the Hullproof Free kit
+// in a folder called hullproof-free next to this repository.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const DEFAULT_CONTROLS = fileURLToPath(new URL('../../../hullproof-free/kit/docs/hullproof/security-controls.json', import.meta.url));
+const cache = new Map();
+const CONTROLS_REL = 'docs/hullproof/security-controls.json';
+export const controlsPathFromEnv = () => process.env.HULLPROOF_CONTROLS ?? (process.env.HULLPROOF_KIT ? join(process.env.HULLPROOF_KIT, CONTROLS_REL) : DEFAULT_CONTROLS);
+export function loadControls(path = controlsPathFromEnv()) {
+    if (cache.has(path))
+        return cache.get(path);
+    let out = null;
+    if (existsSync(path)) {
+        const doc = JSON.parse(readFileSync(path, 'utf8'));
+        const byId = new Map(doc.controls.map((c) => [c.id, c]));
+        const ruleToIds = new Map();
+        for (const c of doc.controls)
+            for (const t of c.tests ?? [])
+                ruleToIds.set(t.id, [...(ruleToIds.get(t.id) ?? []), c.id]);
+        out = { path, byId, ruleToIds };
+    }
+    cache.set(path, out);
+    return out;
+}
+// IDs in scope for an edition. Free keeps only IDs the controls file marks free; an ID the file does not list yet
+// (one written in a standard document but not built into the file) is treated as Pro. Without a controls file nothing is filtered.
+export function inEdition(ids, edition, controls) {
+    if (edition === 'pro' || !controls)
+        return ids;
+    return ids.filter((id) => controls.byId.get(id)?.edition === 'free');
+}
+export const notInControls = (ids, controls) => controls ? [...ids].filter((id) => !controls.byId.has(id)) : [];

package/dist/mapping/dependency-policy.js

@@ -0,0 +1,44 @@
+// The dependency gate rule for OSV Scanner advisories (SEC-SUPPLY-002). Configurable. Default, set on
+// 2026-10-10: CRITICAL and HIGH advisories, and any advisory past its fix deadline, fail SEC-SUPPLY-002 and hold the
+// gate; MEDIUM and LOW inside their deadline are reported and do not hold the gate. The two fields for missing data
+// (unknown_as, unknown_published) are an engine addition outside that decision.
+//
+// Severity class comes from the advisory level as in STANDARD.md "Dependency advisories": a CVSS base score
+// (9.0 to 10.0 CRITICAL, 7.0 to 8.9 HIGH, 4.0 to 6.9 MEDIUM, 0.1 to 3.9 LOW), else the GHSA level word.
+// Deadlines are the maximum fix times in the Standard, in calendar days, counted from the advisory's publication date.
+export const DEFAULT_POLICY = {
+    fail_always: ['CRITICAL', 'HIGH'],
+    deadline_days: { CRITICAL: 7, HIGH: 30, MEDIUM: 90, LOW: 180 },
+    unknown_as: 'HIGH',
+    unknown_published: 'fail',
+};
+export function classFromScore(score) {
+    if (score >= 9)
+        return 'CRITICAL';
+    if (score >= 7)
+        return 'HIGH';
+    if (score >= 4)
+        return 'MEDIUM';
+    if (score > 0)
+        return 'LOW';
+    return 'UNKNOWN';
+}
+export function classFromWord(word) {
+    switch ((word ?? '').toUpperCase()) {
+        case 'CRITICAL': return 'CRITICAL';
+        case 'HIGH': return 'HIGH';
+        case 'MODERATE':
+        case 'MEDIUM': return 'MEDIUM';
+        case 'LOW': return 'LOW';
+        default: return 'UNKNOWN';
+    }
+}
+const DAY = 86_400_000;
+const days = (from, to) => Math.floor((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / DAY);
+export function decide(cls, published, asOf, policy = DEFAULT_POLICY) {
+    const eff = cls === 'UNKNOWN' ? policy.unknown_as : cls;
+    const deadline_days = policy.deadline_days[eff];
+    const past_deadline = published === null ? policy.unknown_published === 'fail' : days(published, asOf) > deadline_days;
+    const fail = policy.fail_always.includes(eff) || past_deadline;
+    return { deadline_days, past_deadline, decision: fail ? 'fail' : 'report' };
+}

package/dist/mapping/map.js

@@ -0,0 +1,44 @@
+// Maps one scanner hit to requirement IDs. Order: the rule's own metadata (Semgrep sec_ids), then the controls file's
+// tests[] entry for the rule id, then the tool's table in src/mapping/maps/<tool>.json (exact rule id, then "*").
+// A hit with no mapping keeps sec_ids [] and is marked unmapped; it is never dropped.
+import { readFileSync } from 'node:fs';
+import { globToRegExp, sortUnique } from '../util.js';
+import { inEdition } from './controls.js';
+const tables = new Map();
+export function loadTable(tool) {
+    if (!tables.has(tool)) {
+        tables.set(tool, JSON.parse(readFileSync(new URL(`./maps/${tool}.json`, import.meta.url), 'utf8')));
+    }
+    return tables.get(tool);
+}
+export function mapHit(h, edition, controls) {
+    const all = rawMap(h, controls);
+    const sec_ids = sortUnique(inEdition(all.sec_ids, edition, controls));
+    return sec_ids.length ? { sec_ids, mapped_by: all.mapped_by } : { sec_ids: [], mapped_by: 'none' };
+}
+function rawMap(h, controls) {
+    if (h.metadataSecIds?.length)
+        return { sec_ids: h.metadataSecIds, mapped_by: 'rule metadata' };
+    const fromControls = controls?.ruleToIds.get(h.rule_id);
+    if (fromControls?.length)
+        return { sec_ids: fromControls, mapped_by: 'controls tests' };
+    if (h.tool === 'semgrep')
+        return { sec_ids: [], mapped_by: 'none' };
+    const t = loadTable(h.tool);
+    const exact = t.rows.find((r) => r.rule_id === h.rule_id);
+    const any = t.rows.find((r) => r.rule_id === '*');
+    let ids = exact?.sec_ids ?? any?.sec_ids ?? [];
+    let by = exact ? 'map rule_id' : any ? 'map default' : 'none';
+    if (h.tool === 'gitleaks') {
+        const client = (t.client_code_paths ?? []).some((g) => globToRegExp(g).test(h.file));
+        ids = [...(h.tracked === false ? [] : ids), ...(client ? t.client_code_sec_ids ?? [] : [])];
+        if (!ids.length)
+            by = 'none';
+    }
+    return { sec_ids: ids, mapped_by: by };
+}
+// Every ID a tool can produce through its table (used for not_assessed_sec_ids when the tool does not run).
+export const tableSecIds = (tool) => {
+    const t = loadTable(tool);
+    return sortUnique([...t.rows.flatMap((r) => r.sec_ids), ...(t.client_code_sec_ids ?? [])]);
+};

package/dist/mapping/maps/gitleaks.json

@@ -0,0 +1,12 @@
+{
+  "tool": "gitleaks",
+  "note": "Every Gitleaks rule maps the same way. A hit in a tracked file or in history fails SEC-SECRETS-004. A hit in a file that matches client_code_paths also fails SEC-SECRETS-001, whether tracked or not, because that is where a secret reaches the browser or the app package. A hit in an untracked file outside those paths is kept as an unmapped observation: it is on this machine, not in the repository.",
+  "rows": [
+    {"rule_id": "*", "sec_ids": ["SEC-SECRETS-004"]}
+  ],
+  "client_code_paths": [
+    ".next/static/**", "**/.next/static/**", "public/**", "**/public/**", "static/**", "dist/**", "**/dist/**",
+    "build/**", "**/build/**", "out/**", "**/*.map", "**/*.bundle", "**/*.jsbundle"
+  ],
+  "client_code_sec_ids": ["SEC-SECRETS-001"]
+}

package/dist/mapping/maps/osv-scanner.json

@@ -0,0 +1,7 @@
+{
+  "tool": "osv-scanner",
+  "note": "Decided 2026-10-10 (design question 9): a known vulnerable dependency fails SEC-SUPPLY-002. Whether a given advisory fails or is only reported is set by the dependency policy in src/mapping/dependency-policy.ts.",
+  "rows": [
+    {"rule_id": "*", "sec_ids": ["SEC-SUPPLY-002"]}
+  ]
+}

package/dist/mapping/maps/trivy.json

@@ -0,0 +1,13 @@
+{
+  "tool": "trivy",
+  "note": "One row per Trivy check id. Every id and title here was read from Trivy 0.75.0 JSON output (embedded checks, run with --skip-check-update) on terragoat or on test/fixtures/scanners/app; none is copied from documentation. The title is kept only so a reviewer can check the row; the engine never prints it. A Trivy hit whose id has no row is kept as an unmapped observation.",
+  "rows": [
+    {
+      "rule_id": "DS-0031",
+      "sec_ids": [
+        "SEC-CLOUD-016"
+      ],
+      "trivy_title": "Secrets passed via `build-args` or envs or copied secret files"
+    }
+  ]
+}