@vantageos/backend-doctor 0.2.0 → 0.3.0

package/dist/detectors/source/refusal.d.ts

@@ -1,5 +1,19 @@
 import type { Detector } from "../../engine-types.js";
 import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+/**
+ * The text of every comment in `src`, read by a LEXER rather than by line shape
+ * (Argus REVISE, PR #32 @6b2b6ad). A trailing `// …` after code and a bare line
+ * inside a block comment are comments; a line inside a string or a template
+ * literal is data, even when it starts with `//`. Five states: code, line
+ * comment, block comment, a `'`/`"` string, a template literal.
+ *
+ * Declared limit: a regex literal containing a quote or a backtick (`/"/`,
+ * `` /`/ ``) is read as opening a string. A `'`/`"` state closes at the end of
+ * its line, so the damage stays on that line; a backtick state does not close
+ * at a newline, so a regex literal holding a backtick hides every comment up to
+ * the next backtick. Rare in a handler body; named here, not hidden.
+ */
+export declare function commentsOf(src: string): string;
 export declare function scanR47(files: SrcFile[]): Scan;
 export declare const R47: Detector;
 /** In the form the orchestrator spreads into REGISTRY. */

package/dist/detectors/source/refusal.js

@@ -1,3 +1,4 @@
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
 // a read-only query opener — the function class R-47 governs.
 const QUERY_OPEN = /\b(?:internalQuery|query)\s*\(/;
@@ -55,6 +56,62 @@ function queryBlock(lines, i) {
     }
     return { lines: body, unterminated: seenOpen };
 }
+/**
+ * The text of every comment in `src`, read by a LEXER rather than by line shape
+ * (Argus REVISE, PR #32 @6b2b6ad). A trailing `// …` after code and a bare line
+ * inside a block comment are comments; a line inside a string or a template
+ * literal is data, even when it starts with `//`. Five states: code, line
+ * comment, block comment, a `'`/`"` string, a template literal.
+ *
+ * Declared limit: a regex literal containing a quote or a backtick (`/"/`,
+ * `` /`/ ``) is read as opening a string. A `'`/`"` state closes at the end of
+ * its line, so the damage stays on that line; a backtick state does not close
+ * at a newline, so a regex literal holding a backtick hides every comment up to
+ * the next backtick. Rare in a handler body; named here, not hidden.
+ */
+export function commentsOf(src) {
+    let out = "";
+    let state = "code";
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        const next = src[i + 1];
+        if (state === "code") {
+            if (c === "/" && next === "/") {
+                state = "line";
+                i++;
+            }
+            else if (c === "/" && next === "*") {
+                state = "block";
+                i++;
+            }
+            else if (c === "'" || c === '"' || c === "`") {
+                state = c;
+            }
+        }
+        else if (state === "line") {
+            out += c;
+            if (c === "\n")
+                state = "code";
+        }
+        else if (state === "block") {
+            if (c === "*" && next === "/") {
+                state = "code";
+                i++;
+                out += "\n";
+            }
+            else {
+                out += c;
+            }
+        }
+        else if (c === "\\") {
+            i++;
+        }
+        else if (c === state || (c === "\n" && state !== "`")) {
+            state = "code";
+        }
+    }
+    return out;
+}
 export function scanR47(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -86,6 +143,11 @@ export function scanR47(files) {
                 .map((l) => l.raw)
                 .join("\n");
             const hasRefusal = REFUSAL.test(blockText);
+            // The justification token is a WRITTEN RECORD, so it is read from the
+            // handler's COMMENTS only, found by a lexer (`commentsOf`), never by line
+            // shape. A string or template literal is executing data and never
+            // justifies (Argus REVISE, PR #32 @515ca1f and @6b2b6ad).
+            const commentText = commentsOf(block.lines.map((l) => l.raw).join("\n"));
             for (const st of statements(block.lines)) {
                 const isUnbounded = COLLECT.test(st.text) && !BOUNDED.test(st.text);
                 if (!isUnbounded)
@@ -106,11 +168,22 @@ export function scanR47(files) {
                         note: `${fn}: wide non-index-bounded scan on "${table}" but the handler carries a REFUSAL path (R-16 error contract naming the narrowing args) — the correct R-47 behaviour (the tasks.list SCAN_CAP_EXCEEDED shape)`,
                     });
                 }
+                else if (hasJustificationTokenInText(commentText)) {
+                    // judgement retired (task k179jnhx, §23): flagged — no refusal path;
+                    // the enclosing handler's written JUSTIFIÉ:/JUSTIFIED: token IS the
+                    // accepted remedy record (refuse / tighter index / declared bound),
+                    // decided by presence, never a person's opinion of which is right.
+                    scan.conform.push({
+                        rel: f.rel,
+                        n: st.n,
+                        note: `${fn}: wide, non-index-bounded \`.query("${table}").collect()\` with NO refusal path, but the handler carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                    });
+                }
                 else {
-                    scan.cnj.push({
+                    scan.violate.push({
                         rel: f.rel,
                         n: st.n,
-                        note: `${fn}: wide, non-index-bounded \`.query("${table}").collect()\` in a query with NO refusal path — the read cap can truncate it BEFORE any filter runs, returning a fraction indistinguishable from a full match. The human half is owed: refuse (R-16), add a tighter index, or declare a bound (R-30)? Never a silent green`,
+                        note: `${fn}: wide, non-index-bounded \`.query("${table}").collect()\` in a query with NO refusal path and no written JUSTIFIÉ:/JUSTIFIED: token — the read cap can truncate it BEFORE any filter runs, returning a fraction indistinguishable from a full match. Owes a fix (refuse (R-16) / tighter index / declared bound (R-30)) or a recorded justification`,
                     });
                 }
             }

package/dist/detectors/source/security.js

@@ -23,6 +23,7 @@
 // matched so the branch is provably reachable.
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
+import { siteCount, withCount } from "../../violation-count.js";
 /** The standard all six are pinned against (short hash a9d7877b). */
 export const SOURCE_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
 function emptyScan() {
@@ -60,12 +61,12 @@ function decide(ruleId, id, check, scan, emptyReason) {
     const breakdown = `[conform=${nC} non-conforming=${nV} could-not-judge=${nJ}]`;
     const fmt = (s) => s.slice(0, 3).map((x) => `${x.rel}:${x.n} (${x.note})`).join("; ");
     if (nV > 0) {
-        return {
+        return withCount({
             id,
             anchor: `${scan.violate[0].rel}:${scan.violate[0].n}`,
             state: "non-conforming",
             verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`,
-        };
+        }, siteCount(scan.violate));
     }
     if (nJ > 0) {
         const reason = `${ruleId}: ${nJ} site(s) could not be judged — ${fmt(scan.cnj)}. This is NOT a clean bill. ${breakdown}`;
@@ -107,42 +108,470 @@ function decide(ruleId, id, check, scan, emptyReason) {
 // a 401/403 reject, (c) key on a delivery id. A webhook file with no signature
 // verification is the violation.
 // ---------------------------------------------------------------------------
-const SIG_TOKEN = /createhmac|verify\w*signature|timingsafeequal|\bhmac\b|x-hub-signature|x-gumroad/i;
+// VERIFICATION evidence — a computation over the signature, never the header
+// NAME alone: a route that reads `x-hub-signature-256` and never checks it is
+// unsigned. `crypto.subtle.sign/verify` is the Web Crypto HMAC form VP
+// convex/http.ts `/github/webhook` uses (lines 46-61 at ec61e9d).
+const SIG_TOKEN = /createhmac|verify\w*signature|timingsafeequal|\bhmac\b|crypto\.subtle\.(?:sign|verify)\b/i;
 const FAIL_CLOSED = /status:\s*40[13]\b|\b40[13]\b.*(reject|invalid|missing)|throw .*(unauthori|forbidden)/i;
-const DELIVERY_ID = /orderid|delivery|sale_id|order_id|idempot|event[_.]?id/i;
-function isWebhookFile(f) {
+// A delivery-id KEY, never the bare word: VP http.ts:39 logs "refusing
+// delivery", which is prose in a string, not an idempotency key.
+const DELIVERY_ID = /orderid|delivery[_-]?id|x-github-delivery|sale_id|order_id|idempot|event[_.]?id/i;
+//
+// POPULATION — an INBOUND HTTP webhook entry point, never a file whose name
+// merely contains "webhook". A webhook-named file is judged only when it is
+// reachable from an HTTP request:
+//   (a) it defines an `httpAction(` / `http.route(` itself, OR
+//   (b) a file that defines an `httpAction(` references its module by function
+//       reference (`internal.<module>.<fn>` / `api.<module>.<fn>`) — the route
+//       delegating verification to an internal action (VP `http.ts:693-700` ->
+//       `internal.gumroadWebhook.handleGumroadWebhook`).
+// A webhook-named internalMutation no route reaches (VP 45e40c8
+// `convex/migrations/backfill_webhook_task_origin.ts`, a manual data repair) is
+// NOT an inbound path and is not judged. Reachability is a property of the
+// TREE: a webhook file scanned without the router that reaches it is not judged.
+const HTTP_ENTRY = /\bhttpAction\s*\(|\bhttp\.route\s*\(/;
+const FN_REF = /\b(?:internal|api)\.((?:[A-Za-z_$][\w$]*\.)+)[A-Za-z_$][\w$]*/g;
+function isWebhookNamed(f) {
     return /webhook/i.test(base(f.rel));
 }
-export function scanR21(files) {
-    const scan = emptyScan();
+function definesHttpEntry(f) {
+    return f.lines.some((l) => code(l) && HTTP_ENTRY.test(l.raw));
+}
+/** The convex module path a file registers under (`convex/a/b.ts` -> `a/b`). */
+function convexModuleOf(rel) {
+    const m = /(?:^|\/)convex\/(.+)\.ts$/.exec(rel);
+    return m ? m[1] : undefined;
+}
+/** Module paths (`a/b`) referenced by function reference from HTTP entry files. */
+function httpReachedModules(files) {
+    const out = new Set();
     for (const f of files) {
-        if (!isJudgeable(f) || !isWebhookFile(f))
+        if (!isJudgeable(f) || !definesHttpEntry(f))
             continue;
-        let sigLine = 0;
-        let failClosed = false;
-        let delivery = false;
         for (const l of f.lines) {
             if (!code(l))
                 continue;
-            if (!sigLine && SIG_TOKEN.test(l.raw))
-                sigLine = l.n;
-            if (FAIL_CLOSED.test(l.raw))
-                failClosed = true;
-            if (DELIVERY_ID.test(l.raw))
-                delivery = true;
+            for (const m of l.raw.matchAll(FN_REF))
+                out.add(m[1].slice(0, -1).replace(/\./g, "/"));
+        }
+    }
+    return out;
+}
+function locate(rel, lines) {
+    return lines.map((line) => ({ rel, line }));
+}
+/**
+ * Judge one webhook path (a whole file, or one route's span — possibly spread
+ * over the router and the module its handler is imported from) and push its
+ * site. Evidence sites are anchored in the file the evidence line lives in.
+ */
+function judgeWebhookPath(scan, rel, anchor, locs, label) {
+    let sig;
+    let failClosed = false;
+    let delivery = false;
+    for (const x of locs) {
+        if (!code(x.line))
+            continue;
+        if (!sig && SIG_TOKEN.test(x.line.raw))
+            sig = x;
+        if (FAIL_CLOSED.test(x.line.raw))
+            failClosed = true;
+        if (DELIVERY_ID.test(x.line.raw))
+            delivery = true;
+    }
+    if (!sig) {
+        scan.violate.push({ rel, n: anchor, note: `${label}webhook path with no signature verification (no createHmac / verify*Signature) — fails open` });
+    }
+    else if (!failClosed) {
+        scan.violate.push({ rel: sig.rel, n: sig.line.n, note: `${label}signature verified but no fail-closed 401/403 reject before acting` });
+    }
+    else if (!delivery) {
+        scan.cnj.push({ rel: sig.rel, n: sig.line.n, note: `${label}signature verified + fail-closed, but no delivery-id idempotency key found on this path — deferred, not statically confirmed` });
+    }
+    else {
+        scan.conform.push({ rel: sig.rel, n: sig.line.n, note: `${label}signature verified (createHmac) + fail-closed 401 + delivery-id idempotency` });
+    }
+}
+// ROUTE POPULATION — an `http.route(...)` that receives a third-party webhook,
+// in ANY file, whatever its name (VP convex/http.ts `/github/webhook` was never
+// judged while population was "webhook-named file"). A route is a webhook route
+// when its path names a webhook provider, or its handler reads a signature
+// header / computes a signature. An ordinary JSON API route is not applicable.
+//
+// THE HANDLER IS READ WHEREVER IT LIVES. Inline `httpAction(`, a same-file
+// `const h = httpAction(`, or a handler IMPORTED from another module (named,
+// aliased, namespace or default import, relative specifier) is followed to its
+// declaration; `h.bind(...)` is followed to `h`, and a one-argument wrapper
+// `wrap(h)` to both `wrap` (whose body may verify) and `h`. A route whose
+// handler cannot be read — imported from a module absent from the tree or
+// from a package, an export the module does not declare (a re-export
+// included), a name neither declared nor imported, any other expression
+// (a multi-argument call, a conditional, ...) named verbatim, or no handler
+// property at all — is could-not-judge: its
+// applicability is unknown, and an unjudged route never stays silent (Argus,
+// after #46: `/api/inbound` -> `inboundRelay.ts` reading `x-hub-signature`
+// unverified produced no site at all).
+const WEBHOOK_PATH = /webhook|github|gumroad|stripe/i;
+const SIGNATURE_READ = /x-hub-signature|x-signature|stripe-signature|svix-signature|x-gumroad-signature|webhook-signature|createhmac|verify\w*signature/i;
+const ROUTE_START = /^\s*http\.route\s*\(/;
+const ROUTE_PATH = /\bpath(?:Prefix)?\s*:\s*["'`]([^"'`]+)["'`]/;
+/** The `handler` PROPERTY of the route object (never the word in a string or a path). */
+const HANDLER_KEY = /(?:^|[{,])\s*handler\s*(?:(:)|(?=[,}]|$))/m;
+/** A reference `resolveHandler` can follow: `h` or `ns.member`. */
+const REF = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?$/;
+/** `h.bind(...)` on a reference. */
+const BIND = /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)\.bind\s*\(.*\)$/s;
+/** `wrap(arg)` — a wrapper reference called with exactly one argument. */
+const WRAP = /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)\s*\((.*)\)$/s;
+/** A top-level statement start: column 0, an identifier/keyword (not `}`, `)`, a comment). */
+const TOP_LEVEL = /^[A-Za-z_$@]/;
+/** Lines from index `i` to (excluding) the next top-level statement. */
+function spanFrom(lines, i) {
+    let j = i + 1;
+    while (j < lines.length && !(TOP_LEVEL.test(lines[j].raw) && code(lines[j])))
+        j++;
+    return lines.slice(i, j);
+}
+/**
+ * The source text of a route's `handler` value: from after `handler:` to the
+ * first `,` or closing `}`/`)` at depth 0, strings skipped. Shorthand
+ * `{ handler }` yields "handler". `undefined` when the route names no handler.
+ */
+function handlerExpression(routeSpan) {
+    const text = routeSpan.filter((l) => code(l)).map((l) => l.raw).join("\n");
+    const m = HANDLER_KEY.exec(text);
+    if (!m)
+        return undefined;
+    if (!m[1])
+        return "handler";
+    let depth = 0;
+    let quote = "";
+    let out = "";
+    for (let i = m.index + m[0].length; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            out += c;
+            if (c === "\\") {
+                out += text[++i] ?? "";
+            }
+            else if (c === quote)
+                quote = "";
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`")
+            quote = c;
+        else if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        else if (c === "," && depth === 0)
+            break;
+        out += c;
+    }
+    return out.replace(/\s+/g, " ").trim();
+}
+/** Split a call's argument text on top-level commas. */
+function topLevelArgs(args) {
+    const out = [];
+    let depth = 0;
+    let cur = "";
+    for (const c of args) {
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth--;
+        if (c === "," && depth === 0) {
+            out.push(cur.trim());
+            cur = "";
+        }
+        else
+            cur += c;
+    }
+    if (cur.trim())
+        out.push(cur.trim());
+    return out;
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** The top-level declaration span of `name` in `f` (`default` = `export default`). */
+function declSpan(f, name) {
+    const decl = name === "default"
+        ? /^export\s+default\b/
+        : new RegExp(`^(?:export\\s+)?(?:const|let|var|function|async\\s+function)\\s+${escapeRe(name)}\\b`);
+    const k = f.lines.findIndex((x) => code(x) && decl.test(x.raw));
+    return k >= 0 ? spanFrom(f.lines, k) : undefined;
+}
+/** Normalise `a/./b/../c` (POSIX, relative). */
+function normalisePath(p) {
+    const out = [];
+    for (const seg of p.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..")
+            out.pop();
+        else
+            out.push(seg);
+    }
+    return out.join("/");
+}
+/** The tree file a relative import specifier in `fromRel` names, if scanned. */
+function resolveSpecifier(fromRel, spec, byRel) {
+    if (!spec.startsWith("."))
+        return undefined;
+    const dir = fromRel.includes("/") ? fromRel.slice(0, fromRel.lastIndexOf("/")) : "";
+    const bare = normalisePath(`${dir}/${spec}`).replace(/\.(?:js|mjs|cjs|ts|tsx)$/, "");
+    for (const cand of [`${bare}.ts`, `${bare}.tsx`, `${bare}/index.ts`]) {
+        const hit = byRel.get(cand);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/** Follow a route's `handler: <ref>` to its declaration, in this file or an imported one. */
+function resolveHandler(f, ref, byRel) {
+    const text = f.lines.filter((l) => code(l)).map((l) => l.raw).join("\n");
+    const dot = ref.indexOf(".");
+    let spec;
+    let exported;
+    if (dot >= 0) {
+        const ns = ref.slice(0, dot);
+        exported = ref.slice(dot + 1);
+        spec = new RegExp(`import\\s+\\*\\s+as\\s+${escapeRe(ns)}\\s+from\\s*["'\`]([^"'\`]+)["'\`]`).exec(text)?.[1];
+        if (spec === undefined)
+            return { kind: "unresolved", why: `handler ${ref}: namespace ${ns} is not an import in ${f.rel}` };
+    }
+    else {
+        const local = declSpan(f, ref);
+        if (local)
+            return { kind: "resolved", file: f, span: local };
+        for (const m of text.matchAll(/import\s+(?:type\s+)?([A-Za-z_$][\w$]*\s*,?\s*)?(?:\{([^}]*)\})?\s*from\s*["'`]([^"'`]+)["'`]/g)) {
+            const def = m[1]?.replace(/[\s,]/g, "");
+            if (def === ref) {
+                spec = m[3];
+                exported = "default";
+                break;
+            }
+            for (const entry of (m[2] ?? "").split(",")) {
+                const [orig, alias] = entry.trim().split(/\s+as\s+/);
+                if ((alias ?? orig) === ref && orig) {
+                    spec = m[3];
+                    exported = orig;
+                }
+            }
+            if (spec !== undefined)
+                break;
         }
-        if (!sigLine) {
-            const first = f.lines.find((l) => code(l)) ?? f.lines[0];
-            scan.violate.push({ rel: f.rel, n: first?.n ?? 1, note: "webhook path with no signature verification (no createHmac / verify*Signature) — fails open" });
+        if (spec === undefined || exported === undefined) {
+            return { kind: "unresolved", why: `handler ${ref} is neither declared nor imported in ${f.rel}` };
         }
-        else if (!failClosed) {
-            scan.violate.push({ rel: f.rel, n: sigLine, note: "signature verified but no fail-closed 401/403 reject before acting" });
+    }
+    const target = resolveSpecifier(f.rel, spec, byRel);
+    if (!target)
+        return { kind: "unresolved", why: `handler ${ref} is imported from "${spec}", not in the scanned tree` };
+    // A default export that is an identifier (`export default h;` or
+    // `export { h as default }`) is read on h's own declaration in that module
+    // (Argus REVISE on #48 @77b6b59, blocker 2); the one-line export is not a body.
+    const name = exported === "default" ? (defaultExportIdentifier(target) ?? "default") : (exported ?? ref);
+    const span = declSpan(target, name);
+    if (!span)
+        return { kind: "unresolved", why: `handler ${ref}: ${target.rel} declares no ${name}` };
+    return { kind: "resolved", file: target, span };
+}
+/** The identifier a module default-exports by name, if it does. */
+function defaultExportIdentifier(f) {
+    for (const l of f.lines) {
+        if (!code(l))
+            continue;
+        const bare = /^export\s+default\s+([A-Za-z_$][\w$]*)\s*;?\s*$/.exec(l.raw);
+        if (bare)
+            return bare[1];
+        const named = /^export\s*\{[^}]*?\b([A-Za-z_$][\w$]*)\s+as\s+default\b/.exec(l.raw);
+        if (named)
+            return named[1];
+    }
+    return undefined;
+}
+/** Local binding names this file imports from a RELATIVE specifier (a module of the tree). */
+function relativeImportBindings(f) {
+    const text = f.lines.filter((l) => code(l)).map((l) => l.raw).join("\n");
+    const out = new Set();
+    // One statement per match: the clause never crosses `from` or `;`, so a
+    // package import cannot be swallowed into the next relative one.
+    for (const m of text.matchAll(/\bimport\s+(?!type\b)((?:(?!\bfrom\b)[^;])*?)\s*\bfrom\s*["'`]([^"'`]*)["'`]/g)) {
+        if (!m[2].startsWith("."))
+            continue;
+        const clause = m[1];
+        const ns = /\*\s+as\s+([A-Za-z_$][\w$]*)/.exec(clause);
+        if (ns)
+            out.add(ns[1]);
+        const def = /^\s*([A-Za-z_$][\w$]*)\s*(?:,|$)/.exec(clause);
+        if (def)
+            out.add(def[1]);
+        for (const entry of /\{([^}]*)\}/.exec(clause)?.[1]?.split(",") ?? []) {
+            const [orig, alias] = entry.trim().replace(/^type\s+/, "").split(/\s+as\s+/);
+            if (alias ?? orig)
+                out.add((alias ?? orig).trim());
         }
-        else if (!delivery) {
-            scan.cnj.push({ rel: f.rel, n: sigLine, note: "signature verified + fail-closed, but no delivery-id idempotency key found on this path — deferred, not statically confirmed" });
+    }
+    return out;
+}
+/**
+ * The tree-imported functions an inline `httpAction(` body calls (`h(…)` or
+ * `ns.h(…)` where `h`/`ns` is bound by a relative import). The inline span alone
+ * is not the handler when it delegates (Argus REVISE on #48 @77b6b59, blocker 1).
+ */
+function inlineImportedCallees(f, expr) {
+    const bound = relativeImportBindings(f);
+    const out = [];
+    for (const m of expr.matchAll(/(?<![\w$.])([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)\s*\(/g)) {
+        const callee = m[1];
+        const head = callee.split(".")[0];
+        if (callee === "httpAction" || !bound.has(head) || out.includes(callee))
+            continue;
+        out.push(callee);
+    }
+    return out;
+}
+/** Every http.route in `f` that receives a webhook or whose handler cannot be read. */
+function readRoutes(f, byRel, fileJudged) {
+    const out = [];
+    f.lines.forEach((l, i) => {
+        if (!code(l) || !ROUTE_START.test(l.raw))
+            return;
+        const routeSpan = spanFrom(f.lines, i);
+        const path = routeSpan.map((x) => (code(x) ? ROUTE_PATH.exec(x.raw)?.[1] : undefined)).find((p) => p !== undefined) ?? "";
+        let locs = locate(f.rel, routeSpan);
+        let handlerFile;
+        const expr = handlerExpression(routeSpan);
+        if (expr === undefined) {
+            out.push({ kind: "unresolved", n: l.n, path, why: "no handler property readable on the route" });
+            return;
         }
+        // Which references this expression's body is read through. An inline
+        // `httpAction(` is read on the route span itself PLUS every tree-imported
+        // function its body calls; a bare reference and `ref.bind(...)` are
+        // followed to `ref`; `wrap(ref)` is followed to BOTH the wrapper (which may
+        // verify) and `ref`. Anything else is unreadable.
+        let refs;
+        const inline = /^httpAction\s*\(/.test(expr);
+        if (inline)
+            refs = inlineImportedCallees(f, expr);
+        else if (REF.test(expr))
+            refs = [expr];
+        else if (BIND.test(expr))
+            refs = [BIND.exec(expr)?.[1] ?? ""];
         else {
-            scan.conform.push({ rel: f.rel, n: sigLine, note: "signature verified (createHmac) + fail-closed 401 + delivery-id idempotency" });
+            const w = WRAP.exec(expr);
+            const args = w ? topLevelArgs(w[2]) : [];
+            if (w && args.length === 1 && REF.test(args[0]))
+                refs = [w[1], args[0]];
+            else {
+                out.push({ kind: "unresolved", n: l.n, path, why: `handler expression \`${expr}\` is neither an inline httpAction( nor a reference this instrument follows` });
+                return;
+            }
+        }
+        // An inline body that reads or verifies a signature itself is judged on its
+        // own span; a callee it cannot follow is then extra evidence missed, not the
+        // only evidence. Without that, an unfollowable callee leaves the route unread.
+        const inlineSelfEvident = inline && locs.some((x) => code(x.line) && (SIGNATURE_READ.test(x.line.raw) || SIG_TOKEN.test(x.line.raw)));
+        for (const ref of refs) {
+            const h = resolveHandler(f, ref, byRel);
+            if (h.kind === "unresolved" && inlineSelfEvident)
+                continue;
+            if (h.kind === "unresolved") {
+                out.push({ kind: "unresolved", n: l.n, path, why: refs.length > 1 || ref !== expr ? `handler \`${expr}\`: ${h.why}` : h.why });
+                return;
+            }
+            // The handler lives in a webhook-named file already judged whole.
+            if (h.file !== f && fileJudged.has(h.file.rel)) {
+                out.push({ kind: "judged-whole", n: l.n });
+                return;
+            }
+            if (h.file !== f)
+                handlerFile = handlerFile ? `${handlerFile}, ${h.file.rel}` : h.file.rel;
+            locs = [...locs, ...locate(h.file.rel, h.span)];
+        }
+        if (inline) {
+            if (handlerFile)
+                handlerFile = `${handlerFile} (called from the inline httpAction)`;
+        }
+        else if (refs.length > 0 && expr !== refs[0])
+            handlerFile = `${handlerFile ?? f.rel} (via \`${expr}\`)`;
+        const isWebhook = WEBHOOK_PATH.test(path) || locs.some((x) => code(x.line) && SIGNATURE_READ.test(x.line.raw));
+        if (isWebhook)
+            out.push({ kind: "webhook", n: l.n, path, locs, handlerFile });
+    });
+    return out;
+}
+export function scanR21(files) {
+    const scan = emptyScan();
+    const reached = httpReachedModules(files);
+    const byModule = new Map();
+    const byRel = new Map();
+    for (const f of files) {
+        byRel.set(f.rel, f);
+        const mod = convexModuleOf(f.rel);
+        if (mod !== undefined && isJudgeable(f))
+            byModule.set(mod, f);
+    }
+    const fileJudged = new Set();
+    // (1) webhook-NAMED files reachable from HTTP — judged whole (b271c26).
+    for (const f of files) {
+        if (!isJudgeable(f) || !isWebhookNamed(f))
+            continue;
+        const mod = convexModuleOf(f.rel);
+        if (!definesHttpEntry(f) && !(mod !== undefined && reached.has(mod)))
+            continue;
+        fileJudged.add(f.rel);
+        const first = f.lines.find((l) => code(l)) ?? f.lines[0];
+        judgeWebhookPath(scan, f.rel, first?.n ?? 1, locate(f.rel, f.lines), "");
+    }
+    // (2) webhook ROUTES in any other file — judged at the route, on its span
+    //     plus its handler's declaration wherever that lives.
+    for (const f of files) {
+        if (!isJudgeable(f) || fileJudged.has(f.rel))
+            continue;
+        for (const r of readRoutes(f, byRel, fileJudged)) {
+            if (r.kind === "judged-whole")
+                continue;
+            const label = `route ${r.path || "(no path literal)"}: `;
+            if (r.kind === "unresolved") {
+                scan.cnj.push({ rel: f.rel, n: r.n, note: `${label}${r.why} — handler unreadable, applicability unknown; not judged, never a pass` });
+                continue;
+            }
+            const where = r.handlerFile ? `${label}handler in ${r.handlerFile}; ` : label;
+            // Delegated by function reference to a module that verifies.
+            const delegates = new Set();
+            for (const x of r.locs) {
+                if (!code(x.line))
+                    continue;
+                for (const m of x.line.raw.matchAll(FN_REF))
+                    delegates.add(m[1].slice(0, -1).replace(/\./g, "/"));
+            }
+            const targets = [...delegates].map((d) => byModule.get(d)).filter((t) => t !== undefined);
+            // A delegate already judged whole in (1) carries this route's verdict.
+            if (targets.some((t) => fileJudged.has(t.rel)))
+                continue;
+            const ownSig = r.locs.some((x) => code(x.line) && SIG_TOKEN.test(x.line.raw));
+            const verifier = ownSig ? undefined : targets.find((t) => t.lines.some((l) => code(l) && SIG_TOKEN.test(l.raw)));
+            if (verifier) {
+                judgeWebhookPath(scan, f.rel, r.n, [...r.locs, ...locate(verifier.rel, verifier.lines)], `${where}verification delegated to ${verifier.rel}; `);
+                continue;
+            }
+            // The route hands off to a webhook-NAMED module this tree does not hold:
+            // its verifier is outside the scan, so the route is not judged here
+            // (reachability is a tree property, in both directions).
+            const absentHook = [...delegates].filter((d) => !byModule.has(d) && /webhook/i.test(d));
+            if (!ownSig && absentHook.length > 0) {
+                scan.cnj.push({ rel: f.rel, n: r.n, note: `${where}no signature verification on the route; it delegates to ${absentHook.join(", ")}, not in the scanned tree — not statically confirmable` });
+                continue;
+            }
+            judgeWebhookPath(scan, f.rel, r.n, r.locs, where);
         }
     }
     return scan;
@@ -590,7 +1019,7 @@ export function evalR36(root) {
 function srcDetector(ruleId, id, check, scanFn, emptyReason) {
     return { id, run: (tree) => decide(ruleId, id, check, scanFn(tree.files), emptyReason) };
 }
-export const R21 = srcDetector("R-21", "R-21 webhook signature-verified, idempotent, fail-closed", "a webhook path verifies its signature (createHmac), fails closed 401, keys idempotency on the delivery id", scanR21, "R-21: zero webhook files matched in the scanned tree — cannot certify webhook signature verification. NOT a clean bill.");
+export const R21 = srcDetector("R-21", "R-21 webhook signature-verified, idempotent, fail-closed", "a webhook path verifies its signature (createHmac), fails closed 401, keys idempotency on the delivery id", scanR21, "R-21: zero inbound webhook entry points in the scanned tree (a webhook-named file that defines an httpAction/http.route or that an httpAction reaches by function reference, or an http.route in any file whose path names a webhook provider or whose handler reads a signature header) — cannot certify webhook signature verification. NOT a clean bill.");
 export const R22 = srcDetector("R-22", "R-22 secrets never in source, response, or log", "no secret-shaped literal in source; secrets read from process.env", scanR22, "R-22: zero convex/mcp source lines scanned — cannot certify secret handling. NOT a clean bill.");
 export const R33 = srcDetector("R-33", "R-33 outbound fetch validated as an SSRF surface", "a caller-influenced fetch is guarded by assertBundleUrlSafe before dereference", scanR33, "R-33: zero caller-influenced fetch sites matched (okfBundle*/kb*) — cannot certify the SSRF surface. NOT a clean bill.");
 export const R34 = srcDetector("R-34", "R-34 outbound credential is the backend's own, audience-validated", "inbound JWT audience asserted (VP_CLERK_EXPECTED_AUD); no outbound caller-token passthrough", scanR34, "R-34: zero inbound-JWT or outbound-Authorization sites matched — cannot certify audience/passthrough. NOT a clean bill.");