@vantageos/backend-doctor 0.3.0 → 0.4.0

package/dist/detectors/source/narrow-then-bound.js

@@ -0,0 +1,571 @@
+// R-55 — a read narrows by every predicate that decides which rows belong to the
+// result BEFORE it bounds the result, and an aggregate is computed over the
+// narrowed set.
+//
+// Standard bacc54a §4 R-55 and its Detector spec, read literally. A read that
+// returns a window (`.take(n)`, `.paginate(...)`, a `.slice(0, n)` of the rows it
+// read) must apply every caller-dependent predicate inside the index range or the
+// query builder that feeds the bound. A predicate applied to the window AFTER it is
+// cut makes the window hold rows the caller may not see and drop rows it may: a
+// short page while more exist, a cursor that skips, a figure over someone else's
+// slice.
+//
+// HOW IT READS. For every PUBLIC door in `convex/` (query, mutation, action) and
+// every in-tree helper its handler reaches, in source order (an internal function
+// and a migration return no result to a caller, so there is no page to starve):
+//   bound      a variable assigned from an expression that holds a DB read
+//              (`.query(` / `.withIndex(` / `.withSearchIndex(`) bounded by
+//              `.take(` or `.paginate(` — through a callback handed to a helper
+//              too; or re-bounded by `V.slice(0, n)`. A variable derived from a
+//              bounded one (an alias, `capped.rows`, a map of it) carries its bound.
+//   narrowing  on a bounded variable V (or `V.page` of a paginate result):
+//                `V.filter(cb)` whose callback reads a CALLER-DEPENDENT value: the
+//                  door's arguments, the resolved caller scope, or a local derived
+//                  from either (a cursor, a status, a roster). A filter on the row
+//                  alone, or against a module-level literal, is not caller-dependent
+//                  and is not read as a narrowing;
+//                `filterBy…(V, …)`, a scope-filter helper;
+//                a call to an in-tree function whose own body narrows that
+//                  parameter the same way;
+//                a `for…of` over V that `continue`s on a caller-dependent test.
+//   exempt     the narrowing sits in a FILL LOOP (a loop that holds both the bound
+//              and the narrowing, so it keeps reading until enough kept rows), or
+//              a REFUSAL ON A FULL WINDOW stands between the (latest) bound and the
+//              narrowing: a throw whose condition or message names the cap, the
+//              overflow or the truncation. Each exemption is listed in the
+//              site's note; none is a silent pass.
+//
+// OUT OF SCOPE, stated. An unbounded `.collect()` has no window of its own: a
+// post-filter over it is R-11 (where the tenant predicate runs) and R-47 (the read
+// cap), not this rule. A narrowing hidden behind a value the scan cannot trace
+// (a map that computes a flag the filter reads) is not seen: the detector errs
+// toward silence there and the standard says so (no verdict is invented).
+import * as ts from "typescript";
+import { calledNames, closeOverCalls, indexFunctions, lineOf, parseFile, registrations, unwrap, walk, } from "./_ast.js";
+import { decide, emptyScan, isJudgeable, } from "./_scan.js";
+export const R55_ID = "R-55 a read narrows by every predicate before it bounds the result; an aggregate is computed over the narrowed set";
+const R55_CHECK = "every caller-dependent predicate (tenant, roster, channel, status, time cursor) sits in the index range or the query builder before .take/.paginate, or the narrowing sits in a fill loop, or a refusal on a full window stands between the bound and the narrowing";
+export const R55_STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ bacc54a53d5f6f9f20e5254908e2b46807902faa §4 R-55";
+/** A throw whose condition or message says the window was full. */
+const FULL_WINDOW = /overflow|truncat|exceed|SCAN_CAP|_CAP\b|\bcap\b|incomplete|isFull|hitCap/i;
+const PUBLIC_BUILDERS = new Set([
+    "query",
+    "mutation",
+    "action",
+]);
+const isConvexFile = (f) => /(^|\/)convex\//.test(f.rel);
+// ---- caller-dependent values ------------------------------------------------
+function declaredNames(fn) {
+    const out = new Set();
+    const addBinding = (b) => {
+        if (ts.isIdentifier(b))
+            out.add(b.text);
+        else
+            for (const e of b.elements)
+                if (!ts.isOmittedExpression(e))
+                    addBinding(e.name);
+    };
+    walk(fn, (x) => {
+        if (ts.isParameter(x))
+            addBinding(x.name);
+        else if (ts.isVariableDeclaration(x))
+            addBinding(x.name);
+    });
+    return out;
+}
+/** Does `node` read a caller-dependent value (an identifier in `tainted`) from
+ * outside itself? Declarations inside `node` shadow the outer names. */
+function readsTainted(node, tainted) {
+    const declared = declaredNames(node);
+    let hit = false;
+    walk(node, (x) => {
+        if (hit || !ts.isIdentifier(x))
+            return;
+        const p = x.parent;
+        if (p && ts.isPropertyAccessExpression(p) && p.name === x)
+            return;
+        if (p && ts.isPropertyAssignment(p) && p.name === x)
+            return;
+        if (p && ts.isTypeReferenceNode(p))
+            return;
+        if (declared.has(x.text))
+            return;
+        if (tainted.has(x.text))
+            hit = true;
+    });
+    return hit;
+}
+/** The caller-dependent names of a function: its `args` (or, in a helper, every
+ * parameter), the result of a scope-resolver call, and any local derived from
+ * either, to a fixpoint. */
+function taintedNames(fn, isHandler, resolvers) {
+    const tainted = new Set();
+    const params = fn.parameters ?? [];
+    params.forEach((prm, i) => {
+        if (!ts.isIdentifier(prm.name))
+            return;
+        // a handler is (ctx, args): ctx carries the database, not the caller
+        if (!isHandler || i >= 1)
+            tainted.add(prm.name.text);
+    });
+    const mentions = (e) => {
+        let hit = false;
+        walk(e, (x) => {
+            if (hit)
+                return;
+            if (ts.isIdentifier(x) && tainted.has(x.text)) {
+                const p = x.parent;
+                if (!(p && ts.isPropertyAccessExpression(p) && p.name === x))
+                    hit = true;
+            }
+            if (ts.isCallExpression(x)) {
+                const c = unwrap(x.expression);
+                if (ts.isIdentifier(c) && resolvers.has(c.text))
+                    hit = true;
+            }
+        });
+        return hit;
+    };
+    for (let pass = 0; pass < 5; pass++) {
+        let grew = false;
+        walk(fn, (x) => {
+            if (!ts.isVariableDeclaration(x) || !x.initializer)
+                return;
+            if (!mentions(x.initializer))
+                return;
+            const names = [];
+            const add = (b) => {
+                if (ts.isIdentifier(b))
+                    names.push(b.text);
+                else
+                    for (const e of b.elements)
+                        if (!ts.isOmittedExpression(e))
+                            add(e.name);
+            };
+            add(x.name);
+            for (const n of names)
+                if (!tainted.has(n)) {
+                    tainted.add(n);
+                    grew = true;
+                }
+        });
+        if (!grew)
+            break;
+    }
+    return tainted;
+}
+function rootIdent(e) {
+    let x = unwrap(e);
+    for (;;) {
+        if (ts.isIdentifier(x))
+            return x.text;
+        if (ts.isPropertyAccessExpression(x) || ts.isElementAccessExpression(x)) {
+            x = unwrap(x.expression);
+            continue;
+        }
+        if (ts.isCallExpression(x)) {
+            x = unwrap(x.expression);
+            continue;
+        }
+        return undefined;
+    }
+}
+function holdsBoundedRead(e, queryVars = new Set()) {
+    let kind;
+    let reads = false;
+    walk(e, (x) => {
+        if (!ts.isCallExpression(x))
+            return;
+        const c = unwrap(x.expression);
+        if (!ts.isPropertyAccessExpression(c))
+            return;
+        const m = c.name.text;
+        if (m === "take" || m === "paginate") {
+            kind = kind ?? m;
+            // `baseQuery.paginate(opts)` — the query was built in pieces
+            const r = rootIdent(c.expression);
+            if (r !== undefined && queryVars.has(r))
+                reads = true;
+        }
+        if (m === "query" || m === "withIndex" || m === "withSearchIndex")
+            reads = true;
+    });
+    return kind !== undefined && reads ? { kind } : undefined;
+}
+/** Does `e` build a DB query (without bounding it yet)? */
+function buildsQuery(e) {
+    let hit = false;
+    walk(e, (x) => {
+        if (hit || !ts.isCallExpression(x))
+            return;
+        const c = unwrap(x.expression);
+        if (ts.isPropertyAccessExpression(c) && c.name.text === "query")
+            hit = true;
+    });
+    return hit;
+}
+/** `X.slice(0, …)` where X's root is a bounded variable. */
+function isRebound(e, bounded) {
+    const x = unwrap(e);
+    if (!ts.isCallExpression(x))
+        return false;
+    const c = unwrap(x.expression);
+    if (!ts.isPropertyAccessExpression(c) || c.name.text !== "slice")
+        return false;
+    const a0 = x.arguments[0];
+    if (!a0 || !ts.isNumericLiteral(a0) || a0.text !== "0")
+        return false;
+    const r = rootIdent(c.expression);
+    return r !== undefined && bounded.has(r);
+}
+function mentionedBounded(e, bounded) {
+    let found;
+    walk(e, (x) => {
+        if (found || !ts.isIdentifier(x))
+            return;
+        const p = x.parent;
+        if (p && ts.isPropertyAccessExpression(p) && p.name === x)
+            return;
+        const b = bounded.get(x.text);
+        if (b)
+            found = b;
+    });
+    return found;
+}
+function enclosingLoops(n, stop) {
+    const out = [];
+    for (let x = n.parent; x && x !== stop; x = x.parent)
+        if (ts.isWhileStatement(x) ||
+            ts.isDoStatement(x) ||
+            ts.isForStatement(x) ||
+            ts.isForOfStatement(x) ||
+            ts.isForInStatement(x))
+            out.push(x);
+    return out;
+}
+function contains(outer, inner) {
+    return (inner.getStart() >= outer.getStart() && inner.getEnd() <= outer.getEnd());
+}
+function refusalBetween(fn, from, to) {
+    let found = false;
+    walk(fn, (x) => {
+        if (found || !ts.isThrowStatement(x))
+            return;
+        const at = x.getStart();
+        if (at <= from || at >= to)
+            return;
+        if (FULL_WINDOW.test(x.getText())) {
+            found = true;
+            return;
+        }
+        for (let up = x.parent; up && up !== fn; up = up.parent)
+            if (ts.isIfStatement(up) && FULL_WINDOW.test(up.expression.getText())) {
+                found = true;
+                return;
+            }
+    });
+    return found;
+}
+function readFunction(fn, isHandler, narrowParams, resolvers) {
+    const out = { bounds: [], events: [], exempt: [] };
+    const bounded = new Map();
+    const queryVars = new Set();
+    const seen = new Set();
+    const tainted = taintedNames(fn, isHandler, resolvers);
+    const callerDependent = (cb) => readsTainted(cb, tainted);
+    const record = (node, what, b) => {
+        const ev = { node, line: lineOf(node), what, bound: b };
+        const loops = enclosingLoops(node, fn);
+        if (loops.some((l) => contains(l, b.node))) {
+            out.exempt.push({ event: ev, why: "fill loop" });
+            return;
+        }
+        if (refusalBetween(fn, b.pos, node.getStart())) {
+            out.exempt.push({ event: ev, why: "refuses on a full window" });
+            return;
+        }
+        out.events.push(ev);
+    };
+    const scanNarrowing = (e) => {
+        walk(e, (x) => {
+            if (seen.has(x))
+                return;
+            if (ts.isCallExpression(x)) {
+                const c = unwrap(x.expression);
+                if (ts.isPropertyAccessExpression(c) && c.name.text === "filter") {
+                    const r = rootIdent(c.expression);
+                    let b = r === undefined ? undefined : bounded.get(r);
+                    const inline = b === undefined
+                        ? holdsBoundedRead(c.expression, queryVars)
+                        : undefined;
+                    if (b === undefined && inline !== undefined) {
+                        // `(await ctx.db.query(…).take(n)).filter(cb)` — the bound is in the receiver.
+                        b = {
+                            pos: c.expression.getStart(),
+                            node: c.expression,
+                            kind: inline.kind,
+                            line: lineOf(c.expression),
+                        };
+                        out.bounds.push(b);
+                    }
+                    const cb = x.arguments[0];
+                    if (b &&
+                        cb &&
+                        (ts.isArrowFunction(unwrap(cb)) ||
+                            ts.isFunctionExpression(unwrap(cb))) &&
+                        callerDependent(unwrap(cb))) {
+                        seen.add(x);
+                        record(x, x.getText().replace(/\s+/g, " ").slice(0, 90), b);
+                    }
+                    return;
+                }
+                if (ts.isIdentifier(c)) {
+                    const first = x.arguments[0];
+                    const r = first ? rootIdent(first) : undefined;
+                    const b = r === undefined ? undefined : bounded.get(r);
+                    if (b && /^filter[A-Z]/.test(c.text)) {
+                        seen.add(x);
+                        record(x, x.getText().replace(/\s+/g, " ").slice(0, 90), b);
+                        return;
+                    }
+                    const np = narrowParams.get(c.text);
+                    if (np) {
+                        x.arguments.forEach((a, i) => {
+                            const ra = rootIdent(a);
+                            const ba = ra === undefined ? undefined : bounded.get(ra);
+                            if (ba && np.has(i) && !seen.has(x)) {
+                                seen.add(x);
+                                record(x, `${c.text}(…) narrows its parameter ${i + 1}`, ba);
+                            }
+                        });
+                    }
+                }
+            }
+        });
+    };
+    const assign = (name, init, at) => {
+        scanNarrowing(init);
+        const read = holdsBoundedRead(init, queryVars);
+        if (read) {
+            const b = {
+                pos: at.getStart(),
+                node: at,
+                kind: read.kind,
+                line: lineOf(at),
+            };
+            bounded.set(name, b);
+            out.bounds.push(b);
+            return;
+        }
+        if (buildsQuery(init))
+            queryVars.add(name);
+        if (isRebound(init, bounded)) {
+            const b = {
+                pos: at.getStart(),
+                node: at,
+                kind: "slice",
+                line: lineOf(at),
+            };
+            bounded.set(name, b);
+            return;
+        }
+        const inherited = mentionedBounded(init, bounded);
+        if (inherited)
+            bounded.set(name, inherited);
+        else
+            bounded.delete(name);
+    };
+    const visit = (n) => {
+        if (ts.isVariableDeclaration(n) && n.initializer) {
+            if (ts.isIdentifier(n.name))
+                assign(n.name.text, n.initializer, n);
+            else if (ts.isObjectBindingPattern(n.name))
+                for (const el of n.name.elements)
+                    if (ts.isIdentifier(el.name))
+                        assign(el.name.text, n.initializer, n);
+            // children already scanned by assign(); still descend for nested functions
+            ts.forEachChild(n.initializer, visit);
+            return;
+        }
+        if (ts.isBinaryExpression(n) &&
+            n.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isIdentifier(n.left)) {
+            assign(n.left.text, n.right, n);
+            ts.forEachChild(n.right, visit);
+            return;
+        }
+        if (ts.isForOfStatement(n)) {
+            const r = rootIdent(n.expression);
+            const b = r === undefined ? undefined : bounded.get(r);
+            if (b) {
+                const loopVars = new Set();
+                if (ts.isVariableDeclarationList(n.initializer))
+                    for (const d of n.initializer.declarations)
+                        for (const nm of declaredNames(d))
+                            loopVars.add(nm);
+                walk(n.statement, (x) => {
+                    if (!ts.isIfStatement(x))
+                        return;
+                    const skips = ts.isContinueStatement(x.thenStatement) ||
+                        (ts.isBlock(x.thenStatement) &&
+                            x.thenStatement.statements.some((s) => ts.isContinueStatement(s)));
+                    if (!skips)
+                        return;
+                    if (!readsTainted(x.expression, tainted))
+                        return;
+                    record(x, `a loop that skips rows on ${x.expression.getText().replace(/\s+/g, " ").slice(0, 70)}`, b);
+                });
+            }
+        }
+        if (ts.isReturnStatement(n) && n.expression && !seen.has(n)) {
+            // `return await ctx.db.query(…).take(n)` — a bounded read nobody names.
+            const rd = holdsBoundedRead(n.expression, queryVars);
+            if (rd && !out.bounds.some((b) => contains(n, b.node)))
+                out.bounds.push({
+                    pos: n.getStart(),
+                    node: n,
+                    kind: rd.kind,
+                    line: lineOf(n),
+                });
+        }
+        if (ts.isCallExpression(n) ||
+            ts.isReturnStatement(n) ||
+            ts.isExpressionStatement(n)) {
+            if (!seen.has(n))
+                scanNarrowing(n);
+        }
+        ts.forEachChild(n, visit);
+    };
+    const body = fn.body;
+    if (body)
+        visit(body);
+    return out;
+}
+/** top-level functions whose own body narrows parameter i by a caller-dependent filter. */
+function narrowingParams(idx, resolvers) {
+    const out = new Map();
+    for (const [name, defs] of idx)
+        for (const d of defs) {
+            const params = d.fn.parameters.map((p) => ts.isIdentifier(p.name) ? p.name.text : undefined);
+            if (!d.fn.body)
+                continue;
+            const tainted = taintedNames(d.fn, false, resolvers);
+            walk(d.fn.body, (x) => {
+                if (!ts.isCallExpression(x))
+                    return;
+                const c = unwrap(x.expression);
+                if (!ts.isPropertyAccessExpression(c) || c.name.text !== "filter")
+                    return;
+                const r = rootIdent(c.expression);
+                const i = r === undefined ? -1 : params.indexOf(r);
+                if (i < 0)
+                    return;
+                const cb = x.arguments[0] && unwrap(x.arguments[0]);
+                if (!cb || !(ts.isArrowFunction(cb) || ts.isFunctionExpression(cb)))
+                    return;
+                if (!readsTainted(cb, tainted))
+                    return;
+                const s = out.get(name) ?? new Set();
+                s.add(i);
+                out.set(name, s);
+            });
+        }
+    return out;
+}
+export function scanR55(files) {
+    const scan = emptyScan();
+    scan.bounded = 0;
+    const ps = files
+        .filter((f) => isJudgeable(f) && isConvexFile(f))
+        .map(parseFile);
+    const idx = indexFunctions(ps);
+    // the functions that resolve the caller's scope: withOrgScope and whatever calls it
+    const resolvers = new Set(["withOrgScope"]);
+    for (const n of closeOverCalls(idx, (d) => calledNames(d.fn).has("withOrgScope")))
+        resolvers.add(n);
+    const np = narrowingParams(idx, resolvers);
+    const units = [];
+    const taken = new Set();
+    const queue = [];
+    for (const p of ps)
+        for (const r of registrations(p)) {
+            if (!PUBLIC_BUILDERS.has(r.builder))
+                continue;
+            units.push({
+                rel: r.rel,
+                line: r.line,
+                name: r.name,
+                fn: r.handler,
+                isHandler: true,
+            });
+            taken.add(r.handler);
+            queue.push(r.handler);
+        }
+    // the helpers a public door reaches, once each
+    const reached = new Set();
+    while (queue.length) {
+        const n = queue.pop();
+        for (const c of calledNames(n)) {
+            if (reached.has(c))
+                continue;
+            reached.add(c);
+            for (const d of idx.get(c) ?? []) {
+                if (taken.has(d.fn))
+                    continue;
+                taken.add(d.fn);
+                units.push({
+                    rel: d.rel,
+                    line: d.line,
+                    name: c,
+                    fn: d.fn,
+                    isHandler: false,
+                });
+                queue.push(d.fn);
+            }
+        }
+    }
+    for (const u of units) {
+        const read = readFunction(u.fn, u.isHandler, np, resolvers);
+        if (read.bounds.length === 0)
+            continue;
+        scan.bounded++;
+        const b0 = read.bounds[0];
+        const where = `bounded read (${b0.kind}) at line ${b0.line}`;
+        if (read.events.length > 0) {
+            const named = read.events
+                .slice(0, 3)
+                .map((e) => `line ${e.line}: ${e.what}`)
+                .join("; ");
+            const more = read.events.length > 3 ? ` (+${read.events.length - 3} more)` : "";
+            scan.violate.push({
+                rel: u.rel,
+                n: u.line,
+                note: `${u.name}: ${where}, then a caller-dependent narrowing after the bound — ${named}${more}; the window holds rows the caller may not see and drops rows it may`,
+            });
+            continue;
+        }
+        const parts = read.exempt.length === 0
+            ? "every caller-dependent predicate sits before the bound"
+            : read.exempt
+                .map((x) => `narrowing at line ${x.event.line} is covered (${x.why})`)
+                .join("; ");
+        scan.conform.push({
+            rel: u.rel,
+            n: u.line,
+            note: `${u.name}: ${where}; ${parts}`,
+        });
+    }
+    return scan;
+}
+export const R55 = {
+    id: R55_ID,
+    run: (tree) => {
+        const s = scanR55(tree.files);
+        const n = tree.files.filter((f) => isJudgeable(f) && isConvexFile(f)).length;
+        const empty = `R-55: no applicable site — ${n} convex file(s) read, none holds a bounded read (.take/.paginate over a DB query) in a function body. NOT a clean bill.`;
+        return decide("R-55", R55_ID, R55_CHECK, s, empty);
+    },
+};
+export const SOURCE_NARROW_THEN_BOUND_DETECTORS = [
+    { detector: R55, ruleId: "R-55", standardPin: R55_STANDARD_PIN },
+];

package/dist/detectors/source/service-account-claim.d.ts

@@ -0,0 +1,15 @@
+import type { Detector } from "../../engine-types.js";
+import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare const R54_ID = "R-54 a door the service account can reach acts inside a transport-verified organisation; a claimless call is refused, never served as master";
+export declare const R54_STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ bacc54a53d5f6f9f20e5254908e2b46807902faa \u00A74 R-54";
+/** `fleet-wide: <reason>` — the reason must be a real sentence, not a token. */
+export declare const FLEET_WIDE_MARKER: RegExp;
+export interface R54Scan extends Scan {
+    /** doors that resolve no caller (CR-1 / R-6 govern them), by `rel:name`. */
+    notApplicable: string[];
+    /** public doors read. */
+    doors: number;
+}
+export declare function scanR54(files: SrcFile[]): R54Scan;
+export declare const R54: Detector;
+export declare const SOURCE_SERVICE_ACCOUNT_CLAIM_DETECTORS: SourceDetectorEntry[];