@clear-capabilities/agentic-security-scanner 0.170.0 → 0.172.0

package/src/context-intelligence/controls.js

@@ -0,0 +1,194 @@
+//
+// Security-relevant facts inside ONE symbol's source: authentication / authorization / ownership / tenant controls,
+// and the sensitive operations they have to precede.
+//
+// EVIDENCE DISCIPLINE. Every fact says how it was established:
+//   evidence 'observed'  the text itself shows it (a decorator, a comparison of a resource field with the principal,
+//                        a query whose filter mentions the principal)
+//   evidence 'inferred'  only a NAME suggests it (`requireAdmin(...)`); the callee's body was not shown to reject
+// A name is never promoted to 'observed'. Nothing here decides that code is safe; it decides what must NOT be
+// dropped from a context bundle, and what the model is told was seen.
+//
+// This module is deliberately pattern-based and says so: it exists to be conservative about what it keeps, not
+// to prove anything. The packer never removes a symbol that contains any fact reported here.
+
+export const CONTROL_KINDS = Object.freeze(['authentication', 'authorization-role', 'ownership', 'tenant-scope']);
+
+const DECORATOR = /^\s*@(?:login_required|permission_required|user_passes_test|PreAuthorize|PostAuthorize|Secured|RolesAllowed|Authorize|Authenticated|authenticated|requires_auth|requires_roles|jwt_required|auth_required|has_role|roles_required|admin_required|staff_member_required|csrf_protect|UseGuards|Roles|Permissions|RequirePermission)\b/;
+// A QUALIFIED principal reference names where the identity came from (the session, the authenticated user object).
+// A BARE identifier (`userId`, `orgId`) may just as well have been copied out of the URL, so it is only ever INFERRED.
+const QUALIFIED_PRINCIPAL = /(?:\breq\.user\b|\brequest\.user\b|\bcurrent_?[Uu]ser\b|\bsession\.user\b|\bsession\[['"]user|\bprincipal\b|\bctx\.user\b|\bauth\.user\b|\bg\.user\b|\bres\.locals\.user\b|\bSecurityContext\w*|\bgetPrincipal\b|\bauthUser\b|\bcurrentUserId\b|\bauthId\b|\breq\.auth\b|\brequest\.auth\b)/;
+const BARE_PRINCIPAL = /(?:\buserId\b|\buser_id\b|\btenantId\b|\btenant_id\b|\borgId\b|\borg_id\b|\buid\b|\bme\.id\b)/;
+// Request-supplied values are attacker-controlled by definition; blank them before looking for a principal reference.
+const UNTRUSTED_ACCESSOR = /\b(?:req|request)\.(?:params|query|body|args|form|json|headers|cookies|values|data)\b(?:\.\w+|\[[^\]]*\])?|\b(?:params|query|body)\[[^\]]*\]|\bparams\.\w+|\brequest\.(?:GET|POST)\b(?:\.get\([^)]*\)|\[[^\]]*\])?|\bparam\s+["'][\w-]+["']/g;
+function principalIn(text, extra = null) {
+  const noReq = text.replace(UNTRUSTED_ACCESSOR, ' ');
+  // a column name inside a SQL string (`org_id`) is not a reference to the principal; look only outside string literals
+  const code = noReq.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '""');
+  if (QUALIFIED_PRINCIPAL.test(code) || /\bsession\[['"]user/.test(noReq)) return 'qualified';
+  if (extra && extra.test(code)) return 'qualified';
+  if (BARE_PRINCIPAL.test(code)) return 'bare';
+  return null;
+}
+
+// Dependency-injected principals (FastAPI-style): a signature parameter bound to an auth-looking dependency holds the
+// authenticated principal, so `user.id` in the body is the principal and not an arbitrary local.
+const DEP_PARAM = /(\w+)\s*(?::[^=,)]*?)?=\s*(?:Depends|Security)\(\s*([\w.]+)|(\w+)\s*:\s*Annotated\[[^\]]*?(?:Depends|Security)\(\s*([\w.]+)/g;
+const PRINCIPAL_DEP = /(?:user|auth|principal|session|token|account|member|identity|credential)/i;
+export function dependencyParams(signatureText) {
+  const out = [];
+  let m;
+  DEP_PARAM.lastIndex = 0;
+  while ((m = DEP_PARAM.exec(signatureText))) out.push({ param: m[1] || m[3], dependency: m[2] || m[4] });
+  return out;
+}
+export function signatureText(lines, declLine, maxLines = 12) {
+  let t = '';
+  for (let i = declLine - 1; i < Math.min(lines.length, declLine - 1 + maxLines); i++) { t += ' ' + lines[i]; if (/\)\s*(?:->[^:]*)?:\s*(?:#.*)?$/.test(lines[i])) break; }
+  return t;
+}
+const OWNER_FIELD = /(?:owner|tenant|org(?:anization)?|account|created_?by|author|user_?id|userId|team|workspace)/i;
+const COMPARE = /(?:===|!==|==|!=|\.equals\(|\bis not\b|\bis\b|\bnot in\b|\bin\b|\.includes\(|\.has\()/;
+const REJECT = /(?:\breturn\b|\bthrow\b|\braise\b|\babort\b|\bexit\b|\b40[0-9]\b|\bforbidden\b|\bunauthori[sz]ed\b|\bHttpError\b|\breject\b|\bnot_?allowed\b|\bdeny\b|\bdenied\b|throwError|\bfinish\b|\bhalt\b|\bPermissionDenied\b|\bAccessDenied\b|status\()/i;
+
+const AUTH_NAME = /(?:^|[.:])(?:(?:require|ensure|check|assert|verify|validate|enforce|authori[sz]e|authenticate|protect|guard|must|need|has|is|can|cannot|allow)\w*(?:auth|login|session|token|jwt|user|perm|role|admin|owner|access|tenant|scope|member|polic|abilit|credential|principal)\w*|authori[sz]e\w*|authenticate\w*|isAuthenticated|requireAuth\w*|requireUser|requireAdmin|requireAuthId|can|cannot|ability\.\w+|policy\.\w+|hasRole|hasPermission|isAdmin|isOwner|checkOwner\w*|ownedBy|belongsTo)$/i;
+
+const SENSITIVE_NAME = /(?:^|[.:])(?:query|queryOne|queryRow|exec|execute|executeQuery|raw|rawQuery|prepare|find|findAll|findOne|findById|findByPk|findUnique|findFirst|findMany|get|getById|getBy|select|selectList|selectFirst|insert|insertOne|insertMany|insert_|update|updateOne|updateMany|upsert|delete|deleteOne|deleteMany|remove|destroy|save|create|createMany|aggregate|runDB|writeFile|writeFileSync|appendFile|unlink|rm|rmdir|spawn|spawnSync|execSync|execFile|system|popen|fetch|request|post|put|patch)$/i;
+const DB_RECEIVER = /(?:^|\b)(?:db|database|conn|connection|pool|client|cursor|session|repo|repository|dao|model|models|collection|table|prisma|knex|sequelize|orm|store|objects|manager|em|entityManager|mongo|redis|cache|conn|stmt|statement|fs|child_process|cp|axios|http|https|requests|httpx|got|superagent|Database|Persist|Yesod|System)\b/;
+const SQL_TEXT = /\b(?:select\s[\s\S]{1,120}\sfrom|insert\s+into|update\s+\w+\s+set|delete\s+from)\b/i;
+const HS_SENSITIVE = /(?:^|\.)(?:runDB|selectList|selectFirst|getBy|getJust|insert_?|insertEntity|update|updateWhere|delete|deleteWhere|replace|upsert|query|query_|execute|execute_|readFile|writeFile|callProcess|readProcess)$|^(?:Database\.|System\.Process\.|System\.Directory\.)/;
+
+const WRITE_VERB = /(?:insert|update|upsert|delete|remove|destroy|save|create|write|append|unlink|rm|exec|spawn|system|popen|post|put|patch|replace)/i;
+
+function kindOfAuthName(name) {
+  const n = name.toLowerCase();
+  if (/(?:owner|ownedby|belongsto)/.test(n)) return 'ownership';
+  if (/(?:tenant|org|scope|member|workspace|team)/.test(n)) return 'tenant-scope';
+  if (/(?:role|admin|perm|polic|abilit|^can|\.can|cannot|allow)/.test(n)) return 'authorization-role';
+  return 'authentication';
+}
+
+/**
+ * The text of the statement that starts on line `ln`: from that line until its parentheses balance (capped). A query
+ * filter is judged on its OWN statement; looking at neighbouring lines is how a guard written on the next line gets
+ * mistaken for a filter on the query above it.
+ */
+function statementAt(lines, ln, maxLines = 12) {
+  let depth = 0;
+  let text = '';
+  for (let i = ln - 1; i < Math.min(lines.length, ln - 1 + maxLines); i++) {
+    const s = lines[i];
+    text += ' ' + s;
+    for (const c of s) { if (c === '(') depth++; else if (c === ')') depth--; }
+    if (depth <= 0) break;
+  }
+  return text;
+}
+
+function clip(s) { return s.trim().slice(0, 160); }
+
+/**
+ * Facts for one symbol.
+ *   symbol  graph symbol (id, file, startLine, endLine, declLine)
+ *   lines   the FILE's lines (0-based array)
+ * Returns [{ symbolId, line, category:'control'|'sensitive', kind, subkind, evidence, basis, rejectionSeen, text }]
+ */
+export function analyzeSymbolText(symbol, lines, { haskell = false } = {}) {
+  const out = [];
+  const seen = new Set();
+  const depParams = symbol.declLine ? dependencyParams(signatureText(lines, symbol.declLine)).filter(d => PRINCIPAL_DEP.test(d.dependency)) : [];
+  const extraPrincipal = depParams.length ? new RegExp(`\\b(?:${depParams.map(d => d.param).join('|')})\\b\\s*(?:\\.|\\[)`) : null;
+  const push = (f) => {
+    const key = `${f.line}|${f.category}|${f.kind}|${f.basis}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ symbolId: symbol.id, ...f });
+  };
+
+  for (let ln = symbol.startLine; ln <= symbol.endLine; ln++) {
+    const raw = lines[ln - 1];
+    if (raw === undefined) break;
+    const t = raw.trim();
+    if (t === '' || /^(?:\/\/|#(?!\[)|--|\/\*|\*)/.test(t)) continue;
+
+    // decorators / annotations that sit above the declaration are guards in their own right
+    if (ln < (symbol.declLine || symbol.startLine) + 1 && DECORATOR.test(raw)) {
+      const kind = /role|perm|PreAuthorize|PostAuthorize|Secured|RolesAllowed|admin|staff|Roles|Permissions|RequirePermission/i.test(raw) ? 'authorization-role' : 'authentication';
+      push({ line: ln, category: 'control', kind, subkind: null, evidence: 'observed', basis: 'decorator', rejectionSeen: true, text: clip(raw) });
+      continue;
+    }
+
+    // a declaration line is not a call: `function requireUser(` names a function, it does not invoke one
+    const isDeclLine = ln === symbol.declLine && /(?:\bfunction\b|\bdef\b|=>|^\s*(?:async\s+)?[\w$.]+\s*[=:]\s*(?:async\s*)?(?:function|\()|^\s*(?:public|private|protected|static|func|fun)\b)/.test(raw);
+
+    // calls on this line
+    const calls = [];
+    const re = /([A-Za-z_$][\w$]*(?:(?:\.|::)[A-Za-z_$][\w$]*)*)\s*\(/g;
+    let m;
+    if (!isDeclLine) { while ((m = re.exec(raw))) calls.push(m[1]); }
+    if (haskell && !isDeclLine) {
+      const hre = /\b([A-Z][\w.]*\.[a-z][\w']*|[a-z][\w']*)\b/g;
+      while ((m = hre.exec(raw))) if (AUTH_NAME.test(m[1]) || HS_SENSITIVE.test(m[1])) calls.push(m[1]);
+    }
+    for (const name of calls) {
+      if (AUTH_NAME.test(name) && !/^(?:if|for|while|switch|catch|function)$/.test(name)) {
+        const rej = REJECT.test(lines.slice(ln - 1, ln + 3).join(' ')) || /^(?:require|ensure|enforce|assert|authori[sz]e|authenticate|protect)/i.test(name.split(/[.:]/).pop());
+        push({ line: ln, category: 'control', kind: kindOfAuthName(name), subkind: null, evidence: 'inferred', basis: 'call-name', rejectionSeen: rej, text: clip(raw) });
+      }
+      const last = name.split(/[.:]/).pop();
+      const recv = name.includes('.') ? name.slice(0, name.lastIndexOf('.')) : '';
+      const isSens = haskell
+        ? HS_SENSITIVE.test(name)
+        : (SENSITIVE_NAME.test(name) && (DB_RECEIVER.test(recv) || /^(?:query|queryOne|queryRow|execute|executeQuery|rawQuery|findOne|findById|findByPk|findUnique|findFirst|findMany|insertOne|insertMany|updateOne|updateMany|deleteOne|deleteMany|runDB|writeFile|writeFileSync|appendFile|unlink|spawn|spawnSync|execSync|execFile|upsert)$/.test(last)));
+      if (isSens) {
+        const verb = WRITE_VERB.test(last) ? 'write' : 'read';
+        const sub = /(?:writeFile|appendFile|unlink|rm|rmdir)/i.test(last) ? 'filesystem'
+          : /(?:spawn|exec|system|popen|callProcess|readProcess)/i.test(last) && !/execute|query/i.test(last) ? 'process'
+          : /(?:fetch|request|axios|http|got|superagent|requests|httpx)/i.test(name) ? 'external-call'
+          : `data-${verb}`;
+        push({ line: ln, category: 'sensitive', kind: sub, subkind: verb, evidence: 'observed', basis: 'call-name', rejectionSeen: null, text: clip(raw) });
+        // a data operation whose own statement mentions the principal and an owner/tenant field is scoped by it
+        const stmt = statementAt(lines, ln);
+        const pr = sub.startsWith('data-') && OWNER_FIELD.test(stmt) ? principalIn(stmt, extraPrincipal) : null;
+        if (pr) {
+          push({ line: ln, category: 'control', kind: /tenant|org|workspace|team|account/i.test(stmt) ? 'tenant-scope' : 'ownership', subkind: null, evidence: pr === 'qualified' ? 'observed' : 'inferred', basis: pr === 'qualified' ? 'query-filter' : 'query-filter-bare-identifier', rejectionSeen: null, text: clip(raw) });
+        }
+      }
+    }
+    if (SQL_TEXT.test(raw)) {
+      const verb = /\b(?:insert|update|delete)\b/i.test(raw) ? 'write' : 'read';
+      push({ line: ln, category: 'sensitive', kind: `data-${verb}`, subkind: verb, evidence: 'observed', basis: 'sql-text', rejectionSeen: null, text: clip(raw) });
+      const stmt = statementAt(lines, ln);
+      const pr = OWNER_FIELD.test(stmt) ? principalIn(stmt, extraPrincipal) : null;
+      if (pr) {
+        push({ line: ln, category: 'control', kind: /tenant|org|workspace|team|account/i.test(stmt) ? 'tenant-scope' : 'ownership', subkind: null, evidence: pr === 'qualified' ? 'observed' : 'inferred', basis: pr === 'qualified' ? 'query-filter' : 'query-filter-bare-identifier', rejectionSeen: null, text: clip(raw) });
+      }
+    }
+
+    // a resource field compared with the principal: the ownership check itself
+    const cmpPr = COMPARE.test(raw) && OWNER_FIELD.test(raw) && /\b(?:if|unless|assert|when|guard|require|expect|where|elif|&&|\|\|)\b|\?/.test(raw) ? principalIn(raw, extraPrincipal) : null;
+    if (cmpPr) {
+      const rej = REJECT.test(lines.slice(ln - 1, ln + 3).join(' '));
+      push({ line: ln, category: 'control', kind: /tenant|org|workspace|team|account/i.test(raw) ? 'tenant-scope' : 'ownership', subkind: null, evidence: cmpPr === 'qualified' ? 'observed' : 'inferred', basis: cmpPr === 'qualified' ? 'comparison' : 'comparison-bare-identifier', rejectionSeen: rej, text: clip(raw) });
+    }
+  }
+  // A function whose NAME says it is a guard and whose BODY shows a rejection path is a guard function. This is
+  // 'inferred' (the name) with the rejection read from the body; a name alone never counts as rejecting.
+  if (symbol.kind === undefined || symbol.kind === 'function') {
+    const nm = String(symbol.name || '');
+    if (nm && !nm.startsWith('<') && AUTH_NAME.test(nm)) {
+      const body = lines.slice(symbol.startLine - 1, symbol.endLine).join('\n');
+      if (REJECT.test(body)) push({ line: symbol.declLine || symbol.startLine, category: 'control', kind: kindOfAuthName(nm), subkind: null, evidence: 'inferred', basis: 'guard-function', rejectionSeen: true, text: clip(lines[(symbol.declLine || symbol.startLine) - 1] || '') });
+    }
+  }
+  out.sort((a, b) => a.line - b.line || (a.category < b.category ? -1 : a.category > b.category ? 1 : 0) || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0) || (a.basis < b.basis ? -1 : 1));
+  return out;
+}
+
+/** True when a fact set contains anything the packer must never drop. */
+export function isSecuritySignificant(facts) {
+  return facts.length > 0;
+}
+
+const TELEMETRY_NAME = /(?:^|[.:_])(?:log(?:ger)?|logging|metrics?|telemetry|statsd|trace|tracing|span|instrument|monitor|analytics|track(?:ing)?|debug|audit_?log_?noop|format_?(?:date|time|currency|number)|pretty|humanize)\w*$/i;
+export function looksLikeTelemetry(name) { return TELEMETRY_NAME.test(String(name || '')); }

package/src/context-intelligence/diff.js

@@ -0,0 +1,97 @@
+//
+// Incremental invalidation and route diffs.
+//
+// Invalidation is by RECOMPUTATION, not by prediction: the symbol graph is rebuilt from the current snapshot (cheap,
+// local, no model) and every bundle is content-addressed. A review is reused only when the bundle it was made from has
+// exactly the same context hash, so:
+//   * a change to a shared authorization middleware changes the text of every route that includes it, so all of their
+//     hashes change and all of their cached reviews are invalidated, though no handler file was touched;
+//   * an unrelated edit leaves untouched bundles byte-identical, so their reviews are cache hits;
+//   * a dirty worktree or a different branch is a different snapshot, so a review of another state is never replayed
+//     as current.
+// There is no optimistic reuse path: if the previous index cannot be read or verified, everything is a miss.
+import { readStoreJson, readManifest } from './store.js';
+
+/** symbol / file -> the entry points whose bundles include it. Used to EXPLAIN invalidation, never to skip a rebuild. */
+export function reverseDependencies(manifests) {
+  const bySymbol = new Map();
+  const byFile = new Map();
+  for (const m of manifests) {
+    for (const s of m.reachableSymbols) {
+      if (!bySymbol.has(s.symbolId)) bySymbol.set(s.symbolId, new Set());
+      bySymbol.get(s.symbolId).add(m.entrypointId);
+      if (!byFile.has(s.file)) byFile.set(s.file, new Set());
+      byFile.get(s.file).add(m.entrypointId);
+    }
+  }
+  const toObj = (map) => Object.fromEntries([...map.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([k, v]) => [k, [...v].sort()]));
+  return { symbols: toObj(bySymbol), files: toObj(byFile) };
+}
+
+function routeKey(m) { return `${m.entrypoint.kind}|${m.entrypoint.method}|${m.entrypoint.path}|${m.entrypoint.registrationSite.file}`; }
+const ctlKey = (c) => `${c.kind}|${c.file}|${c.line}|${c.evidence}|${c.basis}`;
+const sensKey = (s) => `${s.kind}|${s.file}|${s.basis}`;
+const unkKey = (u) => `${u.reason}|${u.calleeName}|${u.site.split(':')[0]}`;
+const symKey = (s) => `${s.symbolId}|${s.spanHash}`;
+
+function setDiff(a, b) {
+  const A = new Set(a), B = new Set(b);
+  return { added: [...B].filter(x => !A.has(x)).sort(), removed: [...A].filter(x => !B.has(x)).sort() };
+}
+
+/** Diff two sets of manifests (each an array). */
+export function diffManifestSets(fromManifests, toManifests) {
+  const from = new Map(fromManifests.map(m => [routeKey(m), m]));
+  const to = new Map(toManifests.map(m => [routeKey(m), m]));
+  const added = [], removed = [], changed = [], unchanged = [];
+  for (const [k, m] of [...to.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const prev = from.get(k);
+    if (!prev) { added.push({ route: `${m.entrypoint.method} ${m.entrypoint.path}`.trim(), file: m.entrypoint.registrationSite.file, integrity: m.context.integrity }); continue; }
+    if (prev.contextHash === m.contextHash) { unchanged.push(k); continue; }
+    const controls = setDiff(prev.controls.map(ctlKey), m.controls.map(ctlKey));
+    const sensitive = setDiff(prev.sensitiveOperations.map(sensKey), m.sensitiveOperations.map(sensKey));
+    const unknowns = setDiff(prev.unknowns.filter(u => u.material).map(unkKey), m.unknowns.filter(u => u.material).map(unkKey));
+    const deps = setDiff(prev.reachableSymbols.map(symKey), m.reachableSymbols.map(symKey));
+    const protection = {};
+    for (const dim of Object.keys(m.protection)) {
+      const a = prev.protection?.[dim]?.state; const b = m.protection[dim].state;
+      if (a !== b) protection[dim] = { from: a || null, to: b };
+    }
+    changed.push({
+      route: `${m.entrypoint.method} ${m.entrypoint.path}`.trim(), file: m.entrypoint.registrationSite.file,
+      contextHash: { from: prev.contextHash, to: m.contextHash },
+      integrity: { from: prev.context.integrity, to: m.context.integrity },
+      authControlChanges: controls, newSensitiveOperations: sensitive.added, removedSensitiveOperations: sensitive.removed,
+      unknownEdgeChanges: unknowns, dependencyChanges: { addedOrChangedSymbols: deps.added.length, removedOrChangedSymbols: deps.removed.length }, protectionChanges: protection,
+    });
+  }
+  for (const [k, m] of [...from.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    if (!to.has(k)) removed.push({ route: `${m.entrypoint.method} ${m.entrypoint.path}`.trim(), file: m.entrypoint.registrationSite.file });
+  }
+  return { added, removed, changed, unchangedCount: unchanged.length };
+}
+
+/**
+ * Cache accounting against the stored index: for each current bundle, is the same context hash already stored, and if
+ * not, why (new route, or which previous hash it replaced).
+ */
+export function cacheReport(root, currentManifests, { hasReview = () => false } = {}) {
+  const idx = readStoreJson(root, 'index.json');
+  const previous = new Map();
+  let indexStatus = 'missing';
+  if (idx.ok && idx.value && Array.isArray(idx.value.entrypoints)) {
+    indexStatus = 'ok';
+    for (const e of idx.value.entrypoints) previous.set(e.entrypointId, e.contextHash);
+  } else if (!idx.ok && idx.code === 'corrupt-json') indexStatus = 'corrupt';
+  const rep = { indexStatus, hits: 0, misses: 0, invalidated: 0, newRoutes: 0, reviewCacheHits: 0, details: [] };
+  for (const m of currentManifests) {
+    const stored = readManifest(root, m.contextHash);
+    const prevHash = previous.get(m.entrypointId);
+    if (stored.ok && stored.value.manifestHash === m.manifestHash) rep.hits++;
+    else rep.misses++;
+    if (prevHash === undefined) { rep.newRoutes++; }
+    else if (prevHash !== m.contextHash) { rep.invalidated++; rep.details.push({ entrypointId: m.entrypointId, route: `${m.entrypoint.method} ${m.entrypoint.path}`.trim(), previous: prevHash, current: m.contextHash }); }
+    if (hasReview(m)) rep.reviewCacheHits++;
+  }
+  return rep;
+}

package/src/context-intelligence/entrypoints.js

@@ -0,0 +1,336 @@
+//
+// Entry points -> exact handler symbols.
+//
+// There is NO second route detector here. HTTP routes come from the engine's own route scan (`scanRoutes`) and, for
+// Haskell, from the existing web model (`analyzeHaskellWeb`); non-HTTP surfaces come from the existing entry-point
+// inventory. What this module adds is the join the context packer needs and the existing records do not carry: which
+// declaration is the handler, which middleware wraps it, and an honest disposition for every route.
+//
+// Every detected entry point ends in exactly ONE disposition:
+//   resolved             handler is a known declaration and nothing about how it is wired is in doubt
+//   partially_resolved   a handler (or a registration block) is known, but something is not: a middleware that does
+//                        not resolve, a handler matched by name only, a router whose mount point is not visible
+//   unresolved           no handler could be identified; the manifest still exists and says so
+//   excluded_by_policy   deliberately not processed (operator exclusion, or the entry-point cap)
+import { hashOf } from './canonical.js';
+import { callStatement, inlineBlockSpan, splitArgs } from './spans.js';
+import { dependencyParams, signatureText } from './controls.js';
+import { buildEntrypointInventory } from '../posture/entrypoint-inventory.js';
+
+export const DISPOSITIONS = Object.freeze(['resolved', 'partially_resolved', 'unresolved', 'excluded_by_policy']);
+export const ENTRYPOINT_KINDS = Object.freeze(['http', 'webhook', 'queue', 'cron', 'upload', 'cli']);
+
+const JS_FILE = /\.(?:js|jsx|mjs|cjs|ts|tsx)$/i;
+const HS_FILE = /\.l?hs$/i;
+const INLINE_FN = /^(?:async\s+)?(?:function\b|\([^)]*\)\s*(?::\s*[\w<>\[\]|. ]+)?\s*=>|[A-Za-z_$][\w$]*\s*=>|\\)/;
+const IDENT_CHAIN = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*/;
+
+function lastSeg(n) { const p = String(n).split(/[.:]/); return p[p.length - 1]; }
+
+function globToRe(g) {
+  const esc = String(g).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '\0').replace(/\*/g, '[^/]*').replace(/\0/g, '.*');
+  return new RegExp(`^${esc}$`);
+}
+
+function symbolIndexes(graph) {
+  const byFile = new Map();
+  const byName = new Map();
+  const byId = new Map();
+  const imports = new Map();
+  for (const i of graph.imports || []) { if (!imports.has(i.file)) imports.set(i.file, []); imports.get(i.file).push(i); }
+  for (const s of graph.symbols) {
+    byId.set(s.id, s);
+    if (!byFile.has(s.file)) byFile.set(s.file, []);
+    byFile.get(s.file).push(s);
+    if (s.kind === 'function' && !s.name.startsWith('<')) {
+      for (const key of new Set([s.name, lastSeg(s.name)])) {
+        if (!byName.has(key)) byName.set(key, []);
+        byName.get(key).push(s);
+      }
+    }
+  }
+  for (const arr of byFile.values()) arr.sort((a, b) => a.declLine - b.declLine || (a.id < b.id ? -1 : 1));
+  return { byFile, byName, byId, imports };
+}
+
+/** Resolve a referenced name to a symbol: same-file exact, then project-unique by name (low confidence). */
+function resolveName(name, file, idx) {
+  // an import statement binds the name to a specific module: that beats any project-wide guess
+  const imp = (idx.imports.get(file) || []).find(i => i.local === name.split('.')[0]);
+  if (imp && imp.kind === 'repo') {
+    const member = name.includes('.') ? name.split('.').pop() : (imp.member === '*' || imp.member === 'default' ? name : imp.member);
+    const hit = (idx.byName.get(member) || []).filter(s => s.file === imp.target);
+    if (hit.length === 1) return { symbol: hit[0], resolution: 'resolved', via: 'import' };
+  }
+  const exact = (idx.byName.get(name) || []).filter(s => s.file === file);
+  if (exact.length === 1) return { symbol: exact[0], resolution: 'resolved' };
+  if (exact.length > 1) return { symbol: null, resolution: 'ambiguous', candidates: exact.map(s => s.id) };
+  const key = lastSeg(name);
+  const all = idx.byName.get(name) || idx.byName.get(key) || [];
+  if (all.length === 1) return { symbol: all[0], resolution: 'name-match' };
+  if (all.length > 1) return { symbol: null, resolution: 'ambiguous', candidates: all.slice(0, 5).map(s => s.id) };
+  return { symbol: null, resolution: 'unresolved' };
+}
+
+/** `X.use(...)` registrations in a JS/TS file: the global / prefix middleware a route can inherit. */
+function collectUses(fileContents) {
+  const uses = [];
+  for (const [file, text] of Object.entries(fileContents)) {
+    if (!JS_FILE.test(file)) continue;
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const m = /^\s*([A-Za-z_$][\w$]*)\.use\s*\(/.exec(lines[i]);
+      if (!m) continue;
+      const st = callStatement(lines, i + 1);
+      if (!st) continue;
+      const args = splitArgs(st.text);
+      let prefix = '/';
+      let rest = args;
+      const q = args[0] && /^(['"`])(.*)\1$/.exec(args[0]);
+      if (q) { prefix = q[2]; rest = args.slice(1); }
+      const names = rest.map(a => { const id = IDENT_CHAIN.exec(a.replace(/^\[|\]$/g, '')); return id ? { name: id[0], text: a } : { name: null, text: a }; });
+      uses.push({ file, line: i + 1, receiver: m[1], prefix, args: names });
+    }
+  }
+  return uses;
+}
+
+function routeKey(r) { return `${r.file}|${r.line}|${r.method}|${r.path}`; }
+
+async function collectRoutes(fileContents) {
+  const { scanRoutes } = await import('../engine.js');
+  const { analyzeHaskellWeb } = await import('../language/haskell-web.js');
+  const routes = [];
+  const seen = new Set();
+  const add = (r) => { const k = routeKey(r); if (!seen.has(k)) { seen.add(k); routes.push(r); } };
+  const hs = {};
+  for (const file of Object.keys(fileContents).sort()) {
+    if (HS_FILE.test(file)) { hs[file] = fileContents[file]; continue; }
+    let found = [];
+    try { found = scanRoutes(file, fileContents[file]) || []; } catch { found = []; }
+    for (const r of found) add({ ...r, language: 'generic' });
+  }
+  if (Object.keys(hs).length) {
+    let web = null;
+    try { web = analyzeHaskellWeb(hs); } catch { web = null; }
+    if (web) for (const r of web.routes) add({ method: r.method, path: r.path, framework: r.framework, file: r.file, line: r.line, hasAuth: r.auth.status === 'authenticated', language: 'haskell', handler: r.handler, webModel: { auth: r.auth, role: r.role, ownership: r.ownership, idLookups: r.idLookups, csrf: r.csrf, sensitive: r.sensitive, uploads: r.uploads } });
+  }
+  return routes;
+}
+
+function resolveHandler(route, ctx) {
+  const { fileContents, idx, graph } = ctx;
+  const lines = fileContents[route.file].split('\n');
+  const reasons = [];
+  const out = { handlerSymbol: null, handlerKind: 'unknown', rootSpan: null, middleware: [], reasons, confidence: 'none' };
+  const fileSyms = idx.byFile.get(route.file) || [];
+
+  if (route.language === 'haskell') {
+    const h = route.handler || {};
+    if (h.kind === 'named' && h.name) {
+      const r = resolveName(h.name, route.file, idx);
+      if (r.symbol) { out.handlerSymbol = r.symbol.id; out.handlerKind = 'named'; out.confidence = r.resolution === 'resolved' ? 'exact' : 'name-match'; if (r.resolution !== 'resolved') reasons.push('handler-matched-by-name-only'); }
+      else reasons.push(`handler-${r.resolution}`);
+    } else if (h.kind === 'inline') {
+      out.handlerKind = 'inline';
+      out.rootSpan = { file: route.file, ...inlineBlockSpan(lines, route.line) };
+      const enclosing = fileSyms.filter(s => s.kind === 'function' && s.startLine <= route.line && s.endLine >= route.line).sort((a, b) => (b.startLine - a.startLine))[0];
+      out.handlerSymbol = enclosing ? enclosing.id : null;
+      out.confidence = enclosing ? 'inline-block' : 'none';
+      if (!enclosing) reasons.push('inline-handler-without-enclosing-declaration');
+    } else {
+      reasons.push('handler-not-statically-known');
+      // the manifest still shows where the route is registered, so the gap is inspectable rather than absent
+      out.rootSpan = { file: route.file, ...inlineBlockSpan(lines, route.line) };
+    }
+    return out;
+  }
+
+  const rawLine = lines[route.line - 1] || '';
+  if (/^\s*@/.test(rawLine)) {
+    // decorator / annotation style: the handler is the next declaration
+    const decl = fileSyms.filter(s => s.kind === 'function' && s.declLine >= route.line && s.declLine <= route.line + 12).sort((a, b) => a.declLine - b.declLine)[0];
+    if (decl) {
+      out.handlerSymbol = decl.id; out.handlerKind = 'decorated'; out.confidence = 'exact';
+      // dependency-injected guards in the signature (`user=Depends(require_user)`) run before the body
+      for (const d of dependencyParams(signatureText(lines, decl.declLine))) {
+        const r = resolveName(d.dependency, route.file, idx);
+        out.middleware.push({ name: d.dependency, symbolId: r.symbol ? r.symbol.id : null, resolution: r.resolution, line: decl.declLine, dependency: true, param: d.param });
+        if (!r.symbol) reasons.push(`dependency-${r.resolution}:${d.dependency}`);
+        else if (r.resolution === 'name-match') reasons.push(`dependency-matched-by-name-only:${d.dependency}`);
+      }
+    }
+    else reasons.push('decorated-handler-not-found');
+    return out;
+  }
+
+  const st = JS_FILE.test(route.file) ? callStatement(lines, route.line) : null;
+  if (!st) {
+    // not a call-style registration we can parse: fall back to the enclosing declaration, flagged
+    const enclosing = fileSyms.filter(s => s.kind === 'function' && s.startLine <= route.line && s.endLine >= route.line).sort((a, b) => b.startLine - a.startLine)[0];
+    if (enclosing) { out.handlerSymbol = enclosing.id; out.handlerKind = 'enclosing'; out.confidence = 'enclosing'; reasons.push('registration-form-not-parsed'); }
+    else reasons.push('registration-form-not-parsed');
+    return out;
+  }
+  out.rootSpan = { file: route.file, startLine: route.line, endLine: st.endLine, precision: 'brace' };
+  const args = splitArgs(st.text).slice(1); // drop the path
+  const flat = [];
+  for (const a of args) {
+    if (a.startsWith('[') && a.endsWith(']')) flat.push(...splitArgs(`(${a.slice(1, -1)})`));
+    else flat.push(a);
+  }
+  if (!flat.length) { reasons.push('registration-has-no-handler-argument'); return out; }
+  const last = flat[flat.length - 1];
+  for (let i = 0; i < flat.length - 1; i++) {
+    const a = flat[i];
+    if (INLINE_FN.test(a)) { out.middleware.push({ name: '<inline>', symbolId: null, resolution: 'inline', line: route.line }); continue; }
+    const id = IDENT_CHAIN.exec(a);
+    if (!id) { out.middleware.push({ name: null, text: a.slice(0, 80), symbolId: null, resolution: 'unresolved', line: route.line }); reasons.push('middleware-not-an-identifier'); continue; }
+    const r = resolveName(id[0], route.file, idx);
+    out.middleware.push({ name: id[0], symbolId: r.symbol ? r.symbol.id : null, resolution: r.resolution, line: route.line, factory: /\(/.test(a) });
+    if (!r.symbol) reasons.push(`middleware-${r.resolution}:${id[0]}`);
+    else if (r.resolution === 'name-match') reasons.push(`middleware-matched-by-name-only:${id[0]}`);
+  }
+  if (INLINE_FN.test(last)) {
+    const cands = fileSyms.filter(s => s.kind === 'function' && s.name.startsWith('<anon>') === false && false);
+    const anon = fileSyms.filter(s => s.id.includes('::<anon>@') && s.declLine >= route.line && s.declLine <= st.endLine);
+    const outermost = anon.filter(a => !anon.some(b => b !== a && b.startLine <= a.startLine && b.endLine >= a.endLine && (b.startLine < a.startLine || b.endLine > a.endLine)));
+    void cands;
+    const pick = outermost.sort((a, b) => a.declLine - b.declLine || (a.id < b.id ? -1 : 1)).pop();
+    if (pick) { out.handlerSymbol = pick.id; out.handlerKind = 'inline'; out.confidence = 'exact'; }
+    else reasons.push('inline-handler-not-in-ir');
+  } else {
+    const id = IDENT_CHAIN.exec(last);
+    if (!id) { reasons.push('handler-not-an-identifier'); }
+    else {
+      const r = resolveName(id[0], route.file, idx);
+      if (r.symbol) { out.handlerSymbol = r.symbol.id; out.handlerKind = 'named'; out.confidence = r.resolution === 'resolved' ? 'exact' : 'name-match'; if (r.resolution !== 'resolved') reasons.push('handler-matched-by-name-only'); }
+      else reasons.push(`handler-${r.resolution}:${id[0]}`);
+    }
+  }
+  void graph;
+  return out;
+}
+
+function pathMatchesPrefix(routePath, prefix) {
+  if (prefix === '/' || prefix === '') return true;
+  const p = prefix.replace(/\/+$/, '');
+  return routePath === p || routePath.startsWith(p + '/') || routePath.startsWith(p);
+}
+
+/**
+ * Build the entry-point records.
+ *   config.entrypointKinds, config.exclude (globs on file or route path), config.maxEntrypoints
+ */
+export async function collectEntrypoints({ fileContents, graph, config = {} }) {
+  const kinds = new Set(config.entrypointKinds && config.entrypointKinds.length ? config.entrypointKinds : ['http']);
+  const idx = symbolIndexes(graph);
+  const uses = collectUses(fileContents);
+  const exclude = (config.exclude || []).map(globToRe);
+  const cap = Number.isInteger(config.maxEntrypoints) && config.maxEntrypoints > 0 ? config.maxEntrypoints : 5000;
+  const ctx = { fileContents, idx, graph };
+  const records = [];
+
+  if (kinds.has('http') || kinds.has('webhook')) {
+    for (const route of await collectRoutes(fileContents)) {
+      const isWebhook = /webhook/i.test(route.path || '');
+      if (isWebhook && !kinds.has('webhook') && !kinds.has('http')) continue;
+      const h = resolveHandler(route, ctx);
+      const reasons = [...h.reasons];
+      const middleware = [...h.middleware];
+      // inherited middleware registered with `X.use(...)` on the same receiver, earlier in the same file
+      if (JS_FILE.test(route.file)) {
+        const lines = fileContents[route.file].split('\n');
+        const recvM = /([A-Za-z_$][\w$]*)\.(?:get|post|put|patch|delete|all|options|head|route)\s*\(/.exec(lines[route.line - 1] || '');
+        const receiver = recvM ? recvM[1] : null;
+        for (const u of uses) {
+          if (u.file !== route.file || u.line >= route.line || u.receiver !== receiver) continue;
+          if (!pathMatchesPrefix(String(route.path || ''), u.prefix)) continue;
+          for (const a of u.args) {
+            if (!a.name) { middleware.push({ name: null, text: a.text.slice(0, 80), symbolId: null, resolution: 'unresolved', line: u.line, scope: u.prefix, inherited: true }); reasons.push('inherited-middleware-not-an-identifier'); continue; }
+            const r = resolveName(a.name, u.file, idx);
+            middleware.push({ name: a.name, symbolId: r.symbol ? r.symbol.id : null, resolution: r.resolution, line: u.line, scope: u.prefix, inherited: true });
+            if (!r.symbol) reasons.push(`inherited-middleware-${r.resolution}:${a.name}`);
+          }
+        }
+        if (receiver && /^(?:router|routes?|r|api|\w*Router)$/i.test(receiver) && !uses.some(u => u.receiver !== receiver && u.args.some(a => a.name === receiver))) {
+          reasons.push('router-mount-not-resolved');
+        }
+      }
+      const authScheme = route.webModel
+        ? { status: route.webModel.auth.status, kind: route.webModel.auth.kind || null, basis: 'haskell-web-model', role: route.webModel.role.status, ownership: route.webModel.ownership || null, idLookups: route.webModel.idLookups || [], csrf: !!route.webModel.csrf }
+        : { status: route.hasAuth ? 'authenticated' : 'none', basis: 'route-scan-heuristic', note: 'authentication seen near the registration; says nothing about ownership' };
+      const base = {
+        kind: isWebhook ? 'webhook' : 'http',
+        method: String(route.method || 'GET'),
+        pathTemplate: String(route.path || ''),
+        framework: route.framework || null,
+        language: route.language === 'haskell' ? 'haskell' : (JS_FILE.test(route.file) ? 'javascript' : (route.file.split('.').pop())),
+        registrationSite: { file: route.file, line: route.line },
+        handlerSymbol: h.handlerSymbol,
+        handlerKind: h.handlerKind,
+        handlerConfidence: h.confidence,
+        rootSpan: h.rootSpan,
+        middleware,
+        authScheme,
+        externalDependencies: [],
+        resolutionReasons: [...new Set(reasons)].sort(),
+      };
+      records.push(base);
+    }
+  }
+
+  // non-HTTP surfaces from the existing inventory
+  const wantInv = ['queue', 'cron', 'upload', 'cli', 'webhook'].filter(k => kinds.has(k));
+  if (wantInv.length) {
+    const inv = buildEntrypointInventory(fileContents, { routes: [] });
+    for (const e of inv.entrypoints) {
+      if (!wantInv.includes(e.type)) continue;
+      const fileSyms = idx.byFile.get(e.file) || [];
+      const enclosing = fileSyms.filter(s => s.kind === 'function' && s.startLine <= e.line && s.endLine >= e.line).sort((a, b) => b.startLine - a.startLine)[0];
+      records.push({
+        kind: e.type, method: '', pathTemplate: e.name, framework: null,
+        language: JS_FILE.test(e.file) ? 'javascript' : e.file.split('.').pop(),
+        registrationSite: { file: e.file, line: e.line },
+        handlerSymbol: enclosing ? enclosing.id : null,
+        handlerKind: enclosing ? 'enclosing' : 'unknown', handlerConfidence: enclosing ? 'enclosing' : 'none',
+        rootSpan: null, middleware: [],
+        authScheme: { status: e.trust === 'authenticated' ? 'authenticated' : 'none', basis: 'inventory-heuristic' },
+        externalDependencies: [],
+        resolutionReasons: enclosing ? ['non-http-handler-is-enclosing-declaration'] : ['no-enclosing-declaration'],
+      });
+    }
+  }
+
+  // ids, dispositions
+  records.sort((a, b) =>
+    (a.registrationSite.file < b.registrationSite.file ? -1 : a.registrationSite.file > b.registrationSite.file ? 1 : 0) ||
+    (a.registrationSite.line - b.registrationSite.line) || (a.method < b.method ? -1 : 1) || (a.pathTemplate < b.pathTemplate ? -1 : a.pathTemplate > b.pathTemplate ? 1 : 0));
+  const ord = new Map();
+  records.forEach((r, i) => {
+    const hname = r.handlerSymbol || `@${r.registrationSite.line}`;
+    const stem = hashOf({ k: r.kind, m: r.method, p: r.pathTemplate, f: r.registrationSite.file, h: r.handlerSymbol ? r.handlerSymbol : null });
+    const n = (ord.get(stem) || 0) + 1;
+    ord.set(stem, n);
+    r.id = `ep:${stem.slice(0, 20)}${n > 1 ? `-${n}` : ''}`;
+    r.label = `${r.method ? r.method + ' ' : ''}${r.pathTemplate}`.trim() || r.kind;
+    void hname;
+    let disposition;
+    const excluded = exclude.some(re => re.test(r.registrationSite.file) || re.test(r.pathTemplate));
+    if (excluded) { disposition = 'excluded_by_policy'; r.resolutionReasons = [...r.resolutionReasons, 'excluded-by-operator-pattern']; }
+    else if (i >= cap) { disposition = 'excluded_by_policy'; r.resolutionReasons = [...r.resolutionReasons, 'max-entrypoints-cap']; }
+    else if (!r.handlerSymbol && !r.rootSpan) disposition = 'unresolved';
+    else if (!r.handlerSymbol) disposition = 'partially_resolved';
+    else if (r.resolutionReasons.length) disposition = 'partially_resolved';
+    else disposition = 'resolved';
+    r.disposition = disposition;
+  });
+  return records;
+}
+
+/** Counts per disposition. Every entry point is in exactly one bucket, so the buckets always sum to the total. */
+export function countDispositions(records) {
+  const c = { total: records.length, resolved: 0, partially_resolved: 0, unresolved: 0, excluded_by_policy: 0 };
+  for (const r of records) c[r.disposition]++;
+  return c;
+}