@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/security.js

@@ -22,7 +22,8 @@
 // abstains (never a silent pass). Every zero-count branch names the real site it
 // matched so the branch is provably reachable.
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+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;
@@ -251,6 +680,181 @@ export function scanR33(files) {
 const INBOUND_JWT = /claims\.(aud|iss)\b|\.iss\b.*mismatch|verify\w*jwt/i;
 const AUD_ASSERT = /VP_CLERK_EXPECTED_AUD|aud claim mismatch|audMatches|expectedAud/i;
 const OUTBOUND_PASSTHROUGH = /["'`]?authorization["'`]?\s*[:=][^,\n]*(headers\.get\(\s*["'`]authorization|req(uest)?\.headers|callerToken|incomingToken|passthrough)/i;
+// An `audience` KEY in the options object of a JWT-verify call is an audience
+// assertion, judged on its VALUE, never on a name list (PR #44 follow-up: VP
+// 30e821b mcp-server/src/auth.ts:882-885 `jwtVerify(token, jwks, { issuer,
+// audience: CLERK_JWT_AUDIENCE })` with `CLERK_JWT_AUDIENCE =
+// process.env.CLERK_JWT_AUDIENCE ?? "convex"` was reported as unasserted).
+//   counts:  a non-empty string literal; a non-empty array literal; an identifier
+//            bound by a module-level `const` to either of those, or to
+//            `process.env.X ?? "<non-empty>"` / `|| "<non-empty>"`
+//   never:   `undefined`, `""`, a const whose fallback is empty, a bare env read
+//            with no fallback (undefined at runtime disables the check in jose)
+const VERIFY_CALL = /\b(?:jwtVerify|jwt\.verify|verifyToken|verify)\s*\(/;
+const NON_EMPTY_LITERAL = /^(?:"[^"]+"|'[^']+'|`[^`$]+`|\[\s*["'`][^\]]*\])$/;
+const ENV_WITH_FALLBACK = /^process\.env\.[A-Za-z0-9_]+\s*(?:\?\?|\|\|)\s*("[^"]+"|'[^']+'|`[^`$]+`)$/;
+function audienceValueCounts(value, f) {
+    const v = value.trim();
+    if (NON_EMPTY_LITERAL.test(v))
+        return true;
+    if (!/^[A-Za-z_$][\w$]*$/.test(v) || v === "undefined")
+        return false;
+    const decl = new RegExp(`^(?:export\\s+)?const\\s+${v}\\s*(?::[^=]+)?=\\s*(.+?);?\\s*$`);
+    for (const l of f.lines) {
+        if (!code(l))
+            continue;
+        const m = decl.exec(l.raw);
+        if (m) {
+            const init = m[1].trim();
+            return NON_EMPTY_LITERAL.test(init) || ENV_WITH_FALLBACK.test(init);
+        }
+    }
+    return false;
+}
+/**
+ * The source with comments blanked to spaces and string/template CONTENTS blanked
+ * to `_` (quotes kept, newlines kept), so offsets line up with the original. All
+ * structural matching runs on this mask; values are sliced from the original.
+ */
+function maskSource(src) {
+    const out = src.split("");
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        const n = src[i + 1];
+        if (c === "/" && n === "/") {
+            while (i < src.length && src[i] !== "\n")
+                out[i++] = " ";
+        }
+        else if (c === "/" && n === "*") {
+            out[i++] = " ";
+            out[i++] = " ";
+            while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) {
+                if (src[i] !== "\n")
+                    out[i] = " ";
+                i++;
+            }
+            if (i < src.length) {
+                out[i++] = " ";
+                out[i++] = " ";
+            }
+        }
+        else if (c === '"' || c === "'" || c === "`") {
+            i++;
+            while (i < src.length && src[i] !== c) {
+                if (src[i] === "\\") {
+                    out[i++] = "_";
+                    if (i < src.length && src[i] !== "\n")
+                        out[i] = "_";
+                    i++;
+                    continue;
+                }
+                if (src[i] !== "\n")
+                    out[i] = "_";
+                i++;
+            }
+            i++;
+        }
+        else
+            i++;
+    }
+    return out.join("");
+}
+/** Index of the bracket closing the one opened at `open` in `masked`, or -1. */
+function closeOf(masked, open) {
+    let depth = 0;
+    for (let i = open; i < masked.length; i++) {
+        const c = masked[i];
+        if (c === "(" || c === "{" || c === "[")
+            depth += 1;
+        else if (c === ")" || c === "}" || c === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Split [from, to) of `masked` on commas at nesting depth 0 → [start, end) spans. */
+function topLevelParts(masked, from, to) {
+    const parts = [];
+    let depth = 0;
+    let start = from;
+    for (let i = from; i < to; i++) {
+        const c = masked[i];
+        if (c === "(" || c === "{" || c === "[")
+            depth += 1;
+        else if (c === ")" || c === "}" || c === "]")
+            depth -= 1;
+        else if (c === "," && depth === 0) {
+            parts.push([start, i]);
+            start = i + 1;
+        }
+    }
+    parts.push([start, to]);
+    return parts;
+}
+/** The `audience` property VALUE of the object literal whose `{` is at `open`
+ * (own properties only, never a nested object's), or undefined. A shorthand
+ * `{ audience }` yields the identifier `audience`. */
+function audienceProp(src, masked, open) {
+    const close = closeOf(masked, open);
+    if (close === -1)
+        return undefined;
+    for (const [st, en] of topLevelParts(masked, open + 1, close)) {
+        const m = /^\s*audience\s*(?::|$)/.exec(masked.slice(st, en));
+        if (!m)
+            continue;
+        const colon = masked.indexOf(":", st);
+        const value = colon !== -1 && colon < en ? src.slice(colon + 1, en) : "audience";
+        return { value: value.trim(), at: st + m[0].indexOf("audience") };
+    }
+    return undefined;
+}
+/**
+ * Line of an `audience` option that belongs to a JWT-verify call's OWN argument
+ * list and whose value counts, or 0. Bound to the call: the scan runs from the
+ * call's `(` to its balanced `)` (strings and comments masked), and the key is
+ * read only (a) as an own property of an object-literal argument, or (b) through
+ * an identifier argument bound by a module-level `const NAME = { … }` holding the
+ * key. An `audience` in a nested call, an unrelated object below the call, a
+ * different call on the same line, a string or a comment is never read
+ * (Eta REVISE #44, mutant A2).
+ */
+function audienceOptionLine(f) {
+    const src = f.lines.map((l) => l.raw).join("\n");
+    const masked = maskSource(src);
+    const lineAt = (idx) => src.slice(0, idx).split("\n").length;
+    const call = new RegExp(VERIFY_CALL.source, "g");
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((m = call.exec(masked)) !== null) {
+        const open = m.index + m[0].length - 1;
+        const close = closeOf(masked, open);
+        if (close === -1)
+            continue;
+        for (const [st, en] of topLevelParts(masked, open + 1, close)) {
+            const arg = masked.slice(st, en);
+            const lead = st + (arg.length - arg.trimStart().length);
+            let prop;
+            if (masked[lead] === "{") {
+                prop = audienceProp(src, masked, lead);
+            }
+            else {
+                const id = /^([A-Za-z_$][\w$]*)\s*$/.exec(arg.trim());
+                if (!id)
+                    continue;
+                const decl = new RegExp(`^(?:export\\s+)?const\\s+${id[1].replace(/\$/g, "\\$")}\\s*(?::[^=\\n]+)?=\\s*\\{`, "m");
+                const d = decl.exec(masked);
+                if (d)
+                    prop = audienceProp(src, masked, d.index + d[0].length - 1);
+            }
+            if (prop && audienceValueCounts(prop.value, f))
+                return lineAt(prop.at);
+        }
+    }
+    return 0;
+}
 export function scanR34(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -269,9 +873,11 @@ export function scanR34(files) {
                 scan.violate.push({ rel: f.rel, n: l.n, note: "outbound Authorization header forwards a caller-supplied token verbatim (token passthrough)" });
             }
         }
+        if (!audAssert)
+            audAssert = audienceOptionLine(f);
         if (inboundLine) {
             if (audAssert) {
-                scan.conform.push({ rel: f.rel, n: audAssert, note: "inbound JWT audience asserted (VP_CLERK_EXPECTED_AUD / aud claim mismatch)" });
+                scan.conform.push({ rel: f.rel, n: audAssert, note: "inbound JWT audience asserted (VP_CLERK_EXPECTED_AUD / aud claim mismatch / a verify call's audience option with a non-empty value)" });
             }
             else {
                 scan.violate.push({ rel: f.rel, n: inboundLine, note: "inbound JWT verified with no audience assertion — accepts a token minted for another party" });
@@ -328,16 +934,57 @@ export function scanR35(files) {
 const LOCKFILES = ["bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
 const WORKFLOW_DIR = ".github/workflows";
 const PUBLISH_HINT = /npm\s+publish|release|publish/i;
+/**
+ * The directories R-36 searches, nearest first: the scanned root, then each
+ * ancestor up to and INCLUDING the git root (the first ancestor holding `.git`).
+ *
+ * The misread this closes: the documented invocation points the doctor at
+ * `<repo>/convex`, while the lockfile and `.github/workflows` are REPOSITORY
+ * artifacts living at the repo root. Reading only `tree.root` reported "no lockfile
+ * — dependencies are not pinned" on a repository with a committed `bun.lock`.
+ *
+ * The walk stops at the git root and never goes above it: a lockfile in some
+ * unrelated parent directory (a home directory, a monorepo host that is not this
+ * repository) does not pin this repository's dependencies. With no `.git` ancestor
+ * at all, only the scanned root itself is read (the pre-fix behaviour) — the walk
+ * is never widened on a guess.
+ */
+export function r36SearchDirs(root) {
+    const chain = [];
+    let dir = resolve(root);
+    for (;;) {
+        chain.push(dir);
+        if (existsSync(join(dir, ".git")))
+            return chain;
+        const up = dirname(dir);
+        if (up === dir)
+            return [resolve(root)];
+        dir = up;
+    }
+}
 export function evalR36(root) {
     const scan = emptyScan();
-    const lock = LOCKFILES.find((n) => existsSync(join(root, n)));
+    const dirs = r36SearchDirs(root);
+    const relTo = (dir, name) => {
+        const r = relative(resolve(root), join(dir, name));
+        return r === "" ? name : r;
+    };
+    let lock;
+    for (const dir of dirs) {
+        const name = LOCKFILES.find((n) => existsSync(join(dir, n)));
+        if (name) {
+            lock = { dir, name };
+            break;
+        }
+    }
     if (!lock) {
-        scan.violate.push({ rel: "(root)", n: 0, note: "no lockfile present — dependencies are not pinned" });
+        scan.violate.push({ rel: "(root)", n: 0, note: `no lockfile present in the scanned root or any ancestor up to the git root (searched: ${dirs.join(", ")}) — dependencies are not pinned` });
     }
     else {
-        scan.conform.push({ rel: lock, n: 1, note: "lockfile present — every dependency pinned by the lockfile" });
+        scan.conform.push({ rel: relTo(lock.dir, lock.name), n: 1, note: "lockfile present — every dependency pinned by the lockfile" });
     }
-    const wfDir = join(root, WORKFLOW_DIR);
+    const wfBase = dirs.find((d) => existsSync(join(d, WORKFLOW_DIR))) ?? resolve(root);
+    const wfDir = join(wfBase, WORKFLOW_DIR);
     let publishFile = "";
     let provenance = false;
     let sawPublish = false;
@@ -348,7 +995,7 @@ export function evalR36(root) {
             const p = join(wfDir, name);
             if (!existsSync(p))
                 continue;
-            publishFile = `${WORKFLOW_DIR}/${name}`;
+            publishFile = relTo(wfBase, `${WORKFLOW_DIR}/${name}`);
             const body = readFileSync(p, "utf8");
             if (PUBLISH_HINT.test(body))
                 sawPublish = true;
@@ -372,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.");