@vantageos/backend-doctor 0.4.0 → 0.4.3

package/dist/detectors/source/isolation-read.js

@@ -0,0 +1,557 @@
+// R-11, unbounded-read arm — the tenant boundary of an UNBOUNDED read is an
+// index-range predicate inside the query, never a post-query handler filter.
+//
+// Standard bacc54a §4 R-11, read literally: "The boundary is an index-range
+// predicate inside the query — `.withIndex("by_org", q => q.eq("orgId",
+// identity.orgId))` — never a post-query handler filter … the query has already
+// read rows the caller may not see, and correctness rests on a filter nothing
+// enforces structurally — a leak and a cost at once." R-55's frontier hands this
+// shape to R-11 by name: "an unbounded read has no window of its own, so a
+// post-filter over it is R-11 and R-47".
+//
+// WHY A SECOND ARM. The line arm (contract.ts `scanR11`) judges a `.filter(` line
+// whose predicate names a scope key. It cannot see the three cause-4 doors the
+// door audit reproduced at vantage-peers 16f0907: the tenant predicate there is a
+// helper call (`isNamespaceAllowedForScope`, `filterByOrgScope`) on a line that
+// does not name a key, or there is no predicate at all (a streamed count).
+//
+// HOW IT READS. For every PUBLIC door in `convex/` (query, mutation, action) and
+// every in-tree helper its handler reaches (call depth <= 4):
+//   read      a `<…>.db.query(T)` chain that is UNBOUNDED: it ends in `.collect()`,
+//             or it is iterated by `for await (… of <chain>)` with no `.take`,
+//             `.paginate`, `.first` or `.unique` in it. A bounded read is R-55's.
+//   table     T is a string literal, a const naming one, or a helper parameter
+//             bound at the call site to either. Anything else is could-not-judge.
+//   applies   T carries a tenant column in `schema.ts` (orgId / tenantId /
+//             workspaceId / orgSlug, required or optional) or a `namespace`.
+//   conform   an `.eq(K, …)` inside the chain's `.withIndex`/`.withSearchIndex`
+//             where K is a tenant column of T, or whose value reads the resolved
+//             caller (a value derived from `withOrgScope`/a resolver/an identity),
+//             or K is an id-reference column (`v.id("P")`): the read is then the
+//             children of ONE parent row, and whether the caller may reach that
+//             row is the door's by-id question (R-53, R-52), not R-11's locus;
+//             or the read is reached only by the fleet master: an earlier
+//             statement refuses every non-master caller (`requireResolvedCaller(…,
+//             { masterOnly: true })`, `if (!scope.isMaster) throw|return`, or an
+//             in-tree helper whose body does either first), or the read sits in
+//             the branch an `isMaster` test reserves for the master.
+//   red       otherwise. The note says which harm: a post-query handler filter
+//             (a scope helper, or a test reading the caller or a tenant field,
+//             applied to the rows after the read) or no tenant predicate at all.
+//   cnj       the table cannot be resolved, or there is no readable `schema.ts`.
+//
+// OUT OF SCOPE, stated. An internal function serves no caller; its reachability
+// from a door through `ctx.runQuery` is not traced. A narrowing hidden behind a
+// value the scan cannot trace is not seen. Where the value of an index `.eq` came
+// from (an argument, a verified claim) is R-5 / R-6's question, not the locus.
+import * as ts from "typescript";
+import { indexFunctions, lineOf, NAMESPACE_COLUMN, parseFile, readSchema, registrations, TENANT_COLUMNS, unwrap, walk, } from "./_ast.js";
+import { emptyScan, isJudgeable } from "./_scan.js";
+const PUBLIC = new Set(["query", "mutation", "action"]);
+const BOUNDING = new Set([
+    "take",
+    "paginate",
+    "first",
+    "unique",
+]);
+const INDEX_CALLS = new Set([
+    "withIndex",
+    "withSearchIndex",
+]);
+const MAX_DEPTH = 4;
+/** A call whose result is the resolved caller (scope, principal, identity). */
+const RESOLVER = /^(withOrgScope|getUserIdentity|resolve[A-Z]\w*|require[A-Z]\w*)$/;
+/** A helper that narrows rows to the caller's scope after the read. */
+const SCOPE_HELPER = /^(filterBy\w*|isRowVisibleToScope|isNamespaceAllowedForScope|\w*(ForScope|OnScope|ToScope|OnRoster|OnOrgRoster)\w*)$/;
+const isConvexFile = (f) => /(^|\/)convex\//.test(f.rel);
+// ---- small readers -----------------------------------------------------------
+function calleeIdent(c) {
+    const e = unwrap(c.expression);
+    if (ts.isIdentifier(e))
+        return e.text;
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text;
+    return undefined;
+}
+function plainCallee(c) {
+    const e = unwrap(c.expression);
+    return ts.isIdentifier(e) ? e.text : undefined;
+}
+/** `<x>.db.query(…)` / `db.query(…)`. */
+function isDbQuery(c) {
+    const e = unwrap(c.expression);
+    if (!ts.isPropertyAccessExpression(e) || e.name.text !== "query")
+        return false;
+    const o = unwrap(e.expression);
+    return ((ts.isPropertyAccessExpression(o) && o.name.text === "db") ||
+        (ts.isIdentifier(o) && o.text === "db"));
+}
+function stringOf(e) {
+    const u = unwrap(e);
+    if (ts.isStringLiteralLike(u))
+        return u.text;
+    if (ts.isIdentifier(u)) {
+        const init = constInitOf(u);
+        if (init) {
+            const i = unwrap(init);
+            if (ts.isStringLiteralLike(i))
+                return i.text;
+        }
+    }
+    return undefined;
+}
+/** nearest `const id = <init>` in an enclosing block or the file. */
+function constInitOf(id) {
+    for (let x = id.parent; x; x = x.parent) {
+        const stmts = ts.isBlock(x) || ts.isSourceFile(x) ? x.statements : undefined;
+        if (!stmts)
+            continue;
+        for (const st of stmts) {
+            if (!ts.isVariableStatement(st))
+                continue;
+            if (!(st.declarationList.flags & ts.NodeFlags.Const))
+                continue;
+            for (const d of st.declarationList.declarations)
+                if (ts.isIdentifier(d.name) && d.name.text === id.text)
+                    return d.initializer;
+        }
+    }
+    return undefined;
+}
+function identsIn(n) {
+    const out = new Set();
+    walk(n, (x) => {
+        if (!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;
+        out.add(x.text);
+    });
+    return out;
+}
+function readsAny(n, names) {
+    for (const i of identsIn(n))
+        if (names.has(i))
+            return true;
+    return false;
+}
+/** Names in `fn` holding the resolved caller: assigned from a resolver call, or
+ * derived from such a name (to a fixed point), or a loop variable over one. */
+function callerNames(fn, seed) {
+    const out = new Set(seed);
+    const decls = [];
+    const bindingNames = (b) => ts.isIdentifier(b)
+        ? [b.text]
+        : b.elements.flatMap((e) => ts.isOmittedExpression(e) ? [] : bindingNames(e.name));
+    walk(fn, (x) => {
+        if (ts.isVariableDeclaration(x) && x.initializer)
+            decls.push({ names: bindingNames(x.name), init: x.initializer });
+        else if ((ts.isForOfStatement(x) || ts.isForInStatement(x)) &&
+            ts.isVariableDeclarationList(x.initializer))
+            for (const d of x.initializer.declarations)
+                decls.push({ names: bindingNames(d.name), init: x.expression });
+    });
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const d of decls) {
+            if (d.names.every((n) => out.has(n)))
+                continue;
+            let hit = readsAny(d.init, out);
+            if (!hit)
+                walk(d.init, (y) => {
+                    if (ts.isCallExpression(y)) {
+                        const c = calleeIdent(y);
+                        if (c && RESOLVER.test(c))
+                            hit = true;
+                    }
+                });
+            if (hit)
+                for (const n of d.names)
+                    if (!out.has(n)) {
+                        out.add(n);
+                        grew = true;
+                    }
+        }
+    }
+    return out;
+}
+// ---- the fleet-master gate ---------------------------------------------------
+/** `!x.isMaster` / `!isMaster`, or an `||` one of whose operands is one. */
+function refusesNonMaster(cond) {
+    const c = unwrap(cond);
+    if (ts.isBinaryExpression(c) &&
+        c.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+        return refusesNonMaster(c.left) || refusesNonMaster(c.right);
+    if (ts.isPrefixUnaryExpression(c) &&
+        c.operator === ts.SyntaxKind.ExclamationToken)
+        return isMasterRead(c.operand);
+    return false;
+}
+function isMasterRead(e) {
+    const u = unwrap(e);
+    return ((ts.isIdentifier(u) && u.text === "isMaster") ||
+        (ts.isPropertyAccessExpression(u) && u.name.text === "isMaster"));
+}
+function exits(s) {
+    if (ts.isThrowStatement(s) || ts.isReturnStatement(s))
+        return true;
+    if (ts.isBlock(s)) {
+        const last = s.statements[s.statements.length - 1];
+        return last !== undefined && exits(last);
+    }
+    return false;
+}
+function hasMasterOnlyFlag(c) {
+    return c.arguments.some((a) => {
+        const u = unwrap(a);
+        return (ts.isObjectLiteralExpression(u) &&
+            u.properties.some((p) => ts.isPropertyAssignment(p) &&
+                ts.isIdentifier(p.name) &&
+                p.name.text === "masterOnly" &&
+                p.initializer.kind === ts.SyntaxKind.TrueKeyword));
+    });
+}
+/** Does this statement refuse every non-master caller before the next one runs? */
+function isMasterGate(s, masterHelpers) {
+    if (ts.isIfStatement(s))
+        return refusesNonMaster(s.expression) && exits(s.thenStatement);
+    let call;
+    if (ts.isExpressionStatement(s))
+        call = s.expression;
+    else if (ts.isVariableStatement(s))
+        call = s.declarationList.declarations.find((d) => d.initializer)?.initializer;
+    if (!call)
+        return false;
+    const u = unwrap(call);
+    if (!ts.isCallExpression(u))
+        return false;
+    const name = plainCallee(u);
+    if (name === "requireResolvedCaller" && hasMasterOnlyFlag(u))
+        return true;
+    return name !== undefined && masterHelpers.has(name);
+}
+function bodyStatements(fn) {
+    return fn.body && ts.isBlock(fn.body) ? fn.body.statements : [];
+}
+/** In-tree functions whose body refuses every non-master caller (closed over calls). */
+function masterOnlyHelpers(idx) {
+    const out = new Set();
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [n, ds] of idx) {
+            if (out.has(n))
+                continue;
+            if (ds.every((d) => bodyStatements(d.fn).some((s) => isMasterGate(s, out)))) {
+                out.add(n);
+                grew = true;
+            }
+        }
+    }
+    return out;
+}
+/** Is `node` (inside `fn`) reached only by the fleet master within this frame? */
+function masterOnlyAt(fn, node, masterHelpers) {
+    // an enclosing `isMaster` branch reserved for the master
+    for (let x = node; x && x !== fn; x = x.parent) {
+        const p = x.parent;
+        if (!p)
+            break;
+        if (ts.isIfStatement(p)) {
+            if (p.thenStatement === x && isMasterRead(p.expression))
+                return true;
+            if (p.elseStatement === x && refusesNonMaster(p.expression))
+                return true;
+        }
+        if (ts.isConditionalExpression(p)) {
+            if (p.whenTrue === x && isMasterRead(p.condition))
+                return true;
+            if (p.whenFalse === x && refusesNonMaster(p.condition))
+                return true;
+        }
+        // an earlier statement of any enclosing block that refuses non-masters
+        if (ts.isBlock(p) || ts.isSourceFile(p)) {
+            for (const s of p.statements) {
+                if (s === x)
+                    break;
+                if (isMasterGate(s, masterHelpers))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function chainOf(q) {
+    const methods = [];
+    let top = q;
+    for (;;) {
+        const p = top.parent;
+        if (!p || !ts.isPropertyAccessExpression(p) || p.expression !== top)
+            break;
+        const call = p.parent;
+        if (!call || !ts.isCallExpression(call) || call.expression !== p)
+            break;
+        methods.push({ name: p.name.text, call });
+        top = call;
+    }
+    return { query: q, methods, top };
+}
+function unbounded(ch) {
+    if (ch.methods.some((m) => BOUNDING.has(m.name)))
+        return undefined;
+    if (ch.methods.some((m) => m.name === "collect"))
+        return "collect";
+    let x = ch.top;
+    while (x.parent &&
+        (ts.isParenthesizedExpression(x.parent) || ts.isAsExpression(x.parent)))
+        x = x.parent;
+    const p = x.parent;
+    if (p && ts.isForOfStatement(p) && p.expression === x && p.awaitModifier)
+        return "for await";
+    return undefined;
+}
+function tenantKeysOf(t) {
+    const out = new Set();
+    for (const f of t.fields)
+        if (TENANT_COLUMNS.has(f))
+            out.add(f);
+    if (t.namespace !== "none")
+        out.add(NAMESPACE_COLUMN);
+    return out;
+}
+/** An index `.eq` carrying a tenant key, a value read from the caller, or an
+ * id-reference column (the children of ONE parent row). */
+function narrowsInQuery(ch, keys, caller, idRef) {
+    for (const m of ch.methods) {
+        if (!INDEX_CALLS.has(m.name))
+            continue;
+        let found;
+        walk(m.call, (x) => {
+            if (found || !ts.isCallExpression(x))
+                return;
+            if (calleeIdent(x) !== "eq" || x.arguments.length < 2)
+                return;
+            const k = stringOf(x.arguments[0]);
+            if (k !== undefined && keys.has(k))
+                found = `.${m.name} .eq("${k}")`;
+            else if (k !== undefined && idRef.has(k))
+                found = `.${m.name} .eq("${k}"), an id reference to ${idRef.get(k)}: the read is the children of one ${idRef.get(k)} row, and whether the caller may reach that row is the door's by-id question (R-53/R-52), not the locus`;
+            else if (readsAny(x.arguments[1], caller))
+                found = `.${m.name} .eq("${k ?? "?"}") on a value read from the resolved caller`;
+        });
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** Is there a narrowing step applied to the rows after the read, in this frame? */
+function postFilterAfter(fn, ch, keys, caller) {
+    const from = ch.top.getEnd();
+    const scope = unbounded(ch) === "for await"
+        ? ch.top.parent
+        : (fn.body ?? fn);
+    let found;
+    walk(scope, (x) => {
+        if (found || x.getStart() < from)
+            return;
+        if (ts.isCallExpression(x)) {
+            const c = plainCallee(x);
+            if (c && SCOPE_HELPER.test(c)) {
+                found = `${c}(…)`;
+                return;
+            }
+            if (calleeIdent(x) === "filter" && x.arguments[0]) {
+                const cb = x.arguments[0];
+                let tenantField = false;
+                walk(cb, (y) => {
+                    if (ts.isPropertyAccessExpression(y) && keys.has(y.name.text))
+                        tenantField = true;
+                });
+                if (tenantField || readsAny(cb, caller))
+                    found = ".filter(…) on the caller's scope";
+            }
+        }
+    });
+    return found;
+}
+function resolveDef(idx, name, rel) {
+    const ds = idx.get(name);
+    if (!ds || ds.length === 0)
+        return undefined;
+    return ds.find((d) => d.rel === rel) ?? (ds.length === 1 ? ds[0] : undefined);
+}
+function tableRef(arg, frame) {
+    const s = stringOf(arg);
+    if (s !== undefined)
+        return { kind: "table", name: s };
+    const u = unwrap(arg);
+    if (ts.isIdentifier(u) && frame.tableOf.has(u.text))
+        return frame.tableOf.get(u.text);
+    return {
+        kind: "unknown",
+        why: `the table is \`${arg.getText()}\`, a value the scan cannot resolve to a table name`,
+    };
+}
+function visitFrame(c, frame, depth) {
+    const caller = callerNames(frame.fn, frame.tainted);
+    walk(frame.fn, (x) => {
+        if (!ts.isCallExpression(x))
+            return;
+        if (isDbQuery(x)) {
+            judgeRead(c, frame, x, caller);
+            return;
+        }
+        if (depth >= MAX_DEPTH)
+            return;
+        const name = plainCallee(x);
+        if (!name)
+            return;
+        const def = resolveDef(c.idx, name, frame.rel);
+        if (!def || def.fn === frame.fn || frame.via.includes(name))
+            return;
+        const tableOf = new Map();
+        const tainted = new Set();
+        def.fn.parameters.forEach((p, i) => {
+            if (!ts.isIdentifier(p.name))
+                return;
+            const a = x.arguments[i];
+            if (!a)
+                return;
+            tableOf.set(p.name.text, tableRef(a, frame));
+            if (readsAny(a, caller))
+                tainted.add(p.name.text);
+        });
+        visitFrame(c, {
+            fn: def.fn,
+            rel: def.rel,
+            name,
+            tableOf,
+            tainted,
+            via: [...frame.via, name],
+            anchor: frame.anchor ?? x,
+            masterOnly: frame.masterOnly || masterOnlyAt(frame.fn, x, c.masterHelpers),
+        }, depth + 1);
+    });
+}
+function judgeRead(c, frame, q, caller) {
+    const ch = chainOf(q);
+    const kind = unbounded(ch);
+    if (!kind || !q.arguments[0])
+        return;
+    const anchor = frame.anchor ?? q;
+    const line = lineOf(anchor);
+    const rel = anchor.getSourceFile().fileName;
+    const via = frame.via.length
+        ? ` via ${frame.via.join(" -> ")} (${frame.rel}:${lineOf(q)})`
+        : "";
+    const ref = tableRef(q.arguments[0], frame);
+    const key = `${c.door}|${line}|${ref.kind === "table" ? ref.name : "?"}`;
+    if (c.seen.has(key))
+        return;
+    c.seen.add(key);
+    const master = frame.masterOnly || masterOnlyAt(frame.fn, q, c.masterHelpers);
+    const at = `${c.door}: unbounded ${kind} read`;
+    if (ref.kind === "unknown") {
+        if (master)
+            return;
+        c.scan.cnj.push({
+            rel,
+            n: line,
+            note: `${at}${via} — ${ref.why}; whether it carries a tenant column is not decided`,
+        });
+        return;
+    }
+    if (!c.schema) {
+        c.scan.cnj.push({
+            rel,
+            n: line,
+            note: `${at} of ${ref.name}${via} — no readable convex/schema.ts, so whether ${ref.name} carries a tenant column is not decided`,
+        });
+        return;
+    }
+    const t = c.schema.get(ref.name);
+    if (!t) {
+        c.scan.cnj.push({
+            rel,
+            n: line,
+            note: `${at} of ${ref.name}${via} — ${ref.name} is not a table of convex/schema.ts`,
+        });
+        return;
+    }
+    const keys = tenantKeysOf(t);
+    if (keys.size === 0)
+        return; // no tenant column: not an isolation site
+    if (master) {
+        c.scan.conform.push({
+            rel,
+            n: line,
+            note: `${at} of ${ref.name}${via} on a fleet-master-only path (every non-master caller is refused before the read)`,
+        });
+        return;
+    }
+    const inQuery = narrowsInQuery(ch, keys, caller, t.idRef);
+    if (inQuery) {
+        c.scan.conform.push({
+            rel,
+            n: line,
+            note: `${at} of ${ref.name}${via} — narrowed by an index range inside the query (${inQuery})`,
+        });
+        return;
+    }
+    const post = postFilterAfter(frame.fn, ch, keys, caller);
+    const tenant = [...keys].join("/");
+    c.scan.violate.push({
+        rel,
+        n: line,
+        note: post
+            ? `${at} of ${ref.name}${via} with no index range on ${tenant}; the tenant predicate is a post-query handler filter (${post}) — every row of ${ref.name} the index admits is read before the caller's scope is applied (R-11 defect)`
+            : `${at} of ${ref.name}${via} with no index range on ${tenant} and no tenant predicate at all, on a door a non-master caller is served — the result is computed over every tenant's rows (R-11 defect)`,
+    });
+}
+export function scanR11UnboundedReads(files) {
+    const scan = emptyScan();
+    const parsed = [];
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConvexFile(f))
+            continue;
+        try {
+            parsed.push(parseFile(f));
+        }
+        catch {
+            // an unparsable file yields no site here; other rules report parse failures
+        }
+    }
+    const schemaFile = parsed.find((p) => /(^|\/)convex\/schema\.ts$/.test(p.rel));
+    const schema = schemaFile ? readSchema(schemaFile) : undefined;
+    const idx = indexFunctions(parsed);
+    const masterHelpers = masterOnlyHelpers(idx);
+    for (const p of parsed) {
+        for (const r of registrations(p)) {
+            if (!PUBLIC.has(r.builder))
+                continue;
+            const door = r.name;
+            visitFrame({
+                schema: schema && schema.size > 0 ? schema : undefined,
+                idx,
+                masterHelpers,
+                scan,
+                door,
+                seen: new Set(),
+            }, {
+                fn: r.handler,
+                rel: p.rel,
+                name: door,
+                tableOf: new Map(),
+                tainted: new Set(),
+                via: [],
+                anchor: undefined,
+                masterOnly: false,
+            }, 0);
+        }
+    }
+    return scan;
+}

package/dist/detectors/source/local-identity.d.ts

@@ -1,3 +1,4 @@
+import * as ts from "typescript";
 import type { Detector, DetectorResult } from "../../engine-types.js";
 import { type Site, type SrcFile } from "./_scan.js";
 export declare const CR2_ID = "CR-2 no application defines its own identity primitive (tenant resolution, membership, scope filtering, credential validation, identification by name); identity lives only in @vantageos/cloud-identity";
@@ -18,6 +19,10 @@ export interface LocalIdentityScan {
     exempt: Site[];
     cnj: Site[];
 }
+export type DoorCheck = (call: ts.CallExpression) => boolean;
+/** Every reference to `name` in the tree (outside its declaration, imports and
+ * exports) is a call whose result goes into a call argument; at least one. */
+export type CallersForward = (name: string) => boolean;
 export declare function scanLocalIdentity(files: SrcFile[]): LocalIdentityScan;
 export declare function localIdentityResult(scan: LocalIdentityScan): DetectorResult;
 /** The rendered section: EVERY violation, exemption and abstention is named. */