@vantageos/backend-doctor 0.1.0

package/dist/detectors/source/security.js

@@ -0,0 +1,392 @@
+// The SIX SOURCE-TREE security detectors — R-21, R-22, R-33, R-34, R-35, R-36.
+//
+// Wave-1 detectors consult the ORACLE CSV and IGNORE the tree. These six are a
+// NEW detector kind: they read the REAL backend SOURCE the engine hands each
+// detector in `run(tree)`. Each scans `tree.files` (`.rel` path, `.lines[]` with
+// `.n`, `.raw`, `.comment`) — and, for R-36, reads two co-artifacts at
+// `tree.root` (the lockfile and the publish workflow) the way a runtime detector
+// reads `evals.json` at `runtime.root`.
+//
+// THE LAW (the one that caught R-5): every predicate is derived from the ACTUAL
+// SOURCE the detector opens, NEVER from the standard's prose illustration. The
+// clearest case is R-33: §9a of the pinned standard names `okfBundleNode.ts:916`
+// as a raw UNGUARDED fetch, but the real source at lines 915-916 now reads
+// `const url = assertBundleUrlSafe(args.bundleUrl); const res = await fetch(url)`
+// — the site is GUARDED. The detector derives its predicate from the source, so
+// it reports both okf fetch sites as conform and records that the §9a-illustrated
+// gap is remediated. The stale prose does not override the source.
+//
+// Three states only (present / non-conforming / could-not-judge) — plus `absent`
+// where a scan legitimately finds no applicable site. A could-not-judge ALWAYS
+// carries a machine-readable `reason`; a scan that matched zero applicable sites
+// 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";
+/** 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() {
+    return { conform: [], violate: [], cnj: [] };
+}
+/** basename of a `rel` path, lower-cased. */
+function base(rel) {
+    return (rel.split("/").pop() ?? rel).toLowerCase();
+}
+/** a source file we should judge — never a test or generated file. */
+function isJudgeable(f) {
+    const b = base(f.rel);
+    return !b.endsWith(".test.ts") && !f.rel.includes("__tests__") && !f.rel.includes("_generated/");
+}
+/** an EXECUTING line (not a comment-only line). Predicates must read code, not
+ * prose — this is what makes the neuter-proof land on an executing line. */
+function code(l) {
+    return !l.comment;
+}
+/**
+ * Reduce a scan to ONE engine DetectorResult.
+ *
+ * Precedence for the SOURCE kind: a concrete VIOLATION site is decisive
+ * (non-conforming) — a found bad site is never a silent pass and outranks an
+ * abstain; else any could-not-judge → could-not-judge WITH a reason; else any
+ * conform site → present; else (zero applicable sites) → could-not-judge naming
+ * the empty scan (an instrument that matched nothing has NOT certified a clean
+ * bill). This divergence from the oracle wave's cnj-first order is deliberate:
+ * a source violation is a real file:line, not a denominator question.
+ */
+function decide(ruleId, id, check, scan, emptyReason) {
+    const nC = scan.conform.length;
+    const nV = scan.violate.length;
+    const nJ = scan.cnj.length;
+    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 {
+            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)}.` : ""}`,
+        };
+    }
+    if (nJ > 0) {
+        const reason = `${ruleId}: ${nJ} site(s) could not be judged — ${fmt(scan.cnj)}. This is NOT a clean bill. ${breakdown}`;
+        return {
+            id,
+            anchor: `${scan.cnj[0].rel}:${scan.cnj[0].n}`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (nC > 0) {
+        return {
+            id,
+            anchor: `${scan.conform[0].rel}:${scan.conform[0].n}`,
+            state: "present",
+            verdict: `${ruleId}: ${nC} applicable site(s) conform (${check}); 0 violations. ${breakdown} Conform: ${fmt(scan.conform)}.`,
+        };
+    }
+    // zero applicable sites — abstain with a machine-readable reason, never a pass.
+    return {
+        id,
+        anchor: "source:no-applicable-site",
+        state: "could-not-judge",
+        verdict: emptyReason,
+        reason: emptyReason,
+    };
+}
+// ---------------------------------------------------------------------------
+// R-21 — an inbound webhook verifies its signature, is idempotent on its
+// delivery id, and fails closed. (standard §15 line 121 / §16 line 257)
+//
+// SOURCE READ: convex/gumroadWebhook.ts — `verifyGumroadSignature` builds
+// `createHmac("sha256", secret)` (line 503), the handler returns `status: 401`
+// on a missing/invalid signature (lines 590, 603) BEFORE any mutation, and keys
+// idempotency on `gumroadOrderId` from `sale_id`/`order_id` (lines ~539-546).
+// PATTERN derived from that file: a webhook path must (a) verify a signature
+// (createHmac / verify*Signature / timingSafeEqual / hmac), (b) fail closed with
+// 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;
+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) {
+    return /webhook/i.test(base(f.rel));
+}
+export function scanR21(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isWebhookFile(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;
+        }
+        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" });
+        }
+        else if (!failClosed) {
+            scan.violate.push({ rel: f.rel, n: sigLine, note: "signature verified but no fail-closed 401/403 reject before acting" });
+        }
+        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" });
+        }
+        else {
+            scan.conform.push({ rel: f.rel, n: sigLine, note: "signature verified (createHmac) + fail-closed 401 + delivery-id idempotency" });
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-22 — a secret is read from the environment, never committed, returned, or
+// logged. (standard §15 line 123)
+//
+// SOURCE READ: convex/auth.config.ts references `process.env.CLERK_JWT_ISSUER_
+// DOMAIN` (line 4) — a conform env-read, no literal. PATTERN: a line holding a
+// secret-SHAPED literal (a provider key/token/PEM assigned as a string) is the
+// violation; a `process.env.<SECRET>` read is the conform evidence. A grep of
+// convex/ + mcp-server/src returns ZERO literals today, so the env-reads are the
+// reachable conform sites and the violation half is exercised by a crafted line.
+// ---------------------------------------------------------------------------
+const SECRET_LITERAL = /["'`](sk-[A-Za-z0-9]{16,}|sk_(live|test)_[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/;
+const ENV_SECRET_READ = /process\.env\.[A-Z0-9_]+/;
+function isConvexOrMcp(f) {
+    return /(^|\/)convex\//.test(f.rel) || /(^|\/)mcp-server\/src\//.test(f.rel);
+}
+export function scanR22(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConvexOrMcp(f))
+            continue;
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            if (SECRET_LITERAL.test(l.raw)) {
+                scan.violate.push({ rel: f.rel, n: l.n, note: "hardcoded secret-shaped literal committed to source" });
+            }
+            else if (ENV_SECRET_READ.test(l.raw)) {
+                scan.conform.push({ rel: f.rel, n: l.n, note: "secret read from process.env, not a literal" });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-33 — an outbound fetch to a caller-influenced address is SSRF-guarded.
+// (standard §15 line 149 / §9a inventory lines 184-196)
+//
+// SOURCE READ: convex/okfBundleNode.ts — `assertBundleUrlSafe` (line 555) is the
+// scheme+range validator; the first fetch at line 702 uses its result
+// (`fetch(safeUrl.toString())`) and the SECOND fetch at line 916 is now
+// `const url = assertBundleUrlSafe(args.bundleUrl); const res = await fetch(url)`
+// (guard at 915). §9a's prose still labels 916 "raw, unguarded" — STALE. The
+// detector derives its predicate from the source: a caller-influenced fetch is
+// conform iff a `assertBundleUrlSafe` guard feeds it within the preceding window;
+// unguarded is the violation. Both okf sites are conform today (§9a gap
+// remediated); the violation branch is exercised by a crafted unguarded fetch.
+// ---------------------------------------------------------------------------
+const GUARD_TOKEN = /assertBundleUrlSafe|assertUrlSafe|ssrf|validateUrl|isUrlSafe/i;
+const FETCH_CALL = /\bfetch\s*\(/;
+const GUARD_WINDOW = 5;
+/** the §9a caller-influenced fetch surface: the bundle/kb import files. */
+function isBundleFetchFile(f) {
+    const b = base(f.rel);
+    return /okfbundle/.test(b) || /^kb/.test(b);
+}
+export function scanR33(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isBundleFetchFile(f))
+            continue;
+        for (let i = 0; i < f.lines.length; i++) {
+            const l = f.lines[i];
+            if (!code(l) || !FETCH_CALL.test(l.raw))
+                continue;
+            // a fetch of a fixed string-literal host is the backend's OWN choice, not
+            // caller-influenced — out of R-33's surface.
+            if (/fetch\s*\(\s*["'`]https?:\/\//.test(l.raw))
+                continue;
+            let guarded = false;
+            let guardLine = 0;
+            for (let j = Math.max(0, i - GUARD_WINDOW); j <= i; j++) {
+                if (code(f.lines[j]) && GUARD_TOKEN.test(f.lines[j].raw)) {
+                    guarded = true;
+                    guardLine = f.lines[j].n;
+                    break;
+                }
+            }
+            if (guarded) {
+                scan.conform.push({ rel: f.rel, n: l.n, note: `caller-influenced fetch guarded by assertBundleUrlSafe at line ${guardLine}` });
+            }
+            else {
+                scan.violate.push({ rel: f.rel, n: l.n, note: "caller-influenced outbound fetch with no SSRF guard (assertBundleUrlSafe) before dereference" });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-34 — an outbound call carries the backend's own credential (never the
+// caller's), and an inbound token's audience is validated. (standard §15 line 159)
+//
+// SOURCE READ: convex/credentials.ts — inbound Clerk JWT verification asserts the
+// audience against `process.env.VP_CLERK_EXPECTED_AUD` (line 188), matching
+// `claims.aud` (lines 194-197) and refusing with "JWT aud claim mismatch" (line
+// 200). PATTERN, two halves: (a) a file that verifies an inbound JWT (reads
+// `claims.aud` / an issuer check) MUST assert audience — else violation; (b) an
+// outbound `Authorization`/`Bearer` header whose value is a caller-supplied token
+// (forwarded from an inbound header) is a passthrough violation. credentials.ts
+// is the conform site; no passthrough exists today.
+// ---------------------------------------------------------------------------
+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;
+export function scanR34(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConvexOrMcp(f))
+            continue;
+        let inboundLine = 0;
+        let audAssert = 0;
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            if (!inboundLine && INBOUND_JWT.test(l.raw))
+                inboundLine = l.n;
+            if (!audAssert && AUD_ASSERT.test(l.raw))
+                audAssert = l.n;
+            if (OUTBOUND_PASSTHROUGH.test(l.raw)) {
+                scan.violate.push({ rel: f.rel, n: l.n, note: "outbound Authorization header forwards a caller-supplied token verbatim (token passthrough)" });
+            }
+        }
+        if (inboundLine) {
+            if (audAssert) {
+                scan.conform.push({ rel: f.rel, n: audAssert, note: "inbound JWT audience asserted (VP_CLERK_EXPECTED_AUD / aud claim mismatch)" });
+            }
+            else {
+                scan.violate.push({ rel: f.rel, n: inboundLine, note: "inbound JWT verified with no audience assertion — accepts a token minted for another party" });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-35 — content the backend returns toward a model is untrusted DATA, never
+// instructions. (standard §15 line 162)
+//
+// SOURCE READ: a sweep of convex/ + mcp-server/src for a fetched/stored value
+// interpolated into an instruction-position string (a var named system / prompt /
+// instruction built with a template literal that splices content) with NO
+// provenance marker. No such splice site exists in the scanned paths today, so
+// the detector reports honestly (absent → abstain naming the empty scan, never a
+// silent pass) and the violation branch is exercised by a crafted splice line.
+// ---------------------------------------------------------------------------
+const INSTRUCTION_LHS = /(const|let|var)\s+\w*(system|prompt|instruction)\w*\s*[:=]/i;
+const CONTENT_SPLICE = /\$\{[^}]*(chunk|doc|content|corpus|row\.|result|body|fetched|message\.text|payload)/i;
+const PROVENANCE_MARKER = /provenance|untrusted|source\s*:|data\s*:|role\s*:\s*["'`]user/i;
+export function scanR35(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConvexOrMcp(f))
+            continue;
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            if (INSTRUCTION_LHS.test(l.raw) && CONTENT_SPLICE.test(l.raw)) {
+                if (PROVENANCE_MARKER.test(l.raw)) {
+                    scan.conform.push({ rel: f.rel, n: l.n, note: "content splice into instruction position carries a provenance marker" });
+                }
+                else {
+                    scan.violate.push({ rel: f.rel, n: l.n, note: "third-party/stored content spliced into a system/instruction position with no provenance marker (LLM01)" });
+                }
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-36 — the backend's dependencies are pinned and the artifact carries
+// provenance. (standard §15 line 165)
+//
+// CO-ARTIFACT READ at `tree.root`: the lockfile (bun.lock — pins every dep by
+// construction) and .github/workflows/npm-publish.yml, whose publish step runs
+// `npm publish --provenance --access public` (line 163). PATTERN: a lockfile MUST
+// be present (the pin) AND a publish path MUST carry `--provenance`. A missing
+// lockfile, or a publish with no `--provenance`, is the violation; no publish
+// workflow at all is could-not-judge.
+// ---------------------------------------------------------------------------
+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;
+export function evalR36(root) {
+    const scan = emptyScan();
+    const lock = LOCKFILES.find((n) => existsSync(join(root, n)));
+    if (!lock) {
+        scan.violate.push({ rel: "(root)", n: 0, note: "no lockfile present — dependencies are not pinned" });
+    }
+    else {
+        scan.conform.push({ rel: lock, n: 1, note: "lockfile present — every dependency pinned by the lockfile" });
+    }
+    const wfDir = join(root, WORKFLOW_DIR);
+    let publishFile = "";
+    let provenance = false;
+    let sawPublish = false;
+    if (existsSync(wfDir)) {
+        // read the conventional publish workflow directly; a broad dir walk is not
+        // needed — the standard names npm-publish as the publish path.
+        for (const name of ["npm-publish.yml", "npm-publish.yaml", "publish.yml", "release.yml"]) {
+            const p = join(wfDir, name);
+            if (!existsSync(p))
+                continue;
+            publishFile = `${WORKFLOW_DIR}/${name}`;
+            const body = readFileSync(p, "utf8");
+            if (PUBLISH_HINT.test(body))
+                sawPublish = true;
+            if (/--provenance/.test(body)) {
+                provenance = true;
+                const n = body.split("\n").findIndex((line) => line.includes("--provenance")) + 1;
+                scan.conform.push({ rel: publishFile, n, note: "publish step carries --provenance attestation" });
+            }
+            break;
+        }
+    }
+    if (!publishFile) {
+        scan.cnj.push({ rel: WORKFLOW_DIR, n: 0, note: "no publish workflow found at .github/workflows — provenance not statically confirmable here" });
+    }
+    else if (sawPublish && !provenance) {
+        scan.violate.push({ rel: publishFile, n: 1, note: "publish workflow has no --provenance flag — artifact ships unattested" });
+    }
+    return scan;
+}
+// ---- detector wrappers ----------------------------------------------------
+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 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.");
+export const R35 = srcDetector("R-35", "R-35 model-facing content is untrusted data", "no third-party/stored content spliced into an instruction position without a provenance marker", scanR35, "R-35: no instruction-position content splice found on the scanned convex/mcp paths — absent (no such site), reported honestly, not a certified pass.");
+export const R36 = {
+    id: "R-36 dependencies pinned + provenance attested",
+    run: (tree) => decide("R-36", "R-36 dependencies pinned + provenance attested", "a lockfile pins every dependency and the publish path carries --provenance", evalR36(tree.root), "R-36: could not read the target root for a lockfile or publish workflow. NOT a clean bill."),
+};
+/** The six, in a form the orchestrator spreads into REGISTRY. */
+export const SOURCE_SECURITY_DETECTORS = [
+    { detector: R21, ruleId: "R-21", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R22, ruleId: "R-22", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R33, ruleId: "R-33", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R34, ruleId: "R-34", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R35, ruleId: "R-35", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R36, ruleId: "R-36", standardPin: SOURCE_STANDARD_PIN },
+];

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

@@ -0,0 +1,14 @@
+import type { Detector } from "../../engine-types.js";
+import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare function scanR17(files: SrcFile[]): Scan;
+export declare function scanR18(files: SrcFile[]): Scan;
+export declare function scanR29(files: SrcFile[]): Scan;
+export declare function scanR30(files: SrcFile[]): Scan;
+export declare function scanR31(files: SrcFile[]): Scan;
+export declare const R17: Detector;
+export declare const R18: Detector;
+export declare const R29: Detector;
+export declare const R30: Detector;
+export declare const R31: Detector;
+/** The five, in a form the orchestrator spreads into REGISTRY. */
+export declare const SOURCE_WRITESAFETY_DETECTORS: SourceDetectorEntry[];