@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/package-principal.js

@@ -0,0 +1,177 @@
+// R-6 — the principal @vantageos/cloud-identity resolved, once the door has
+// refused the unresolved branch, is a VERIFIED-IDENTITY value.
+//
+// `resolveActingPrincipal(credential, lookups, door)` and
+// `resolvePersonPrincipal(…)` return `{ ok: true, principal } | { ok: false,
+// refusal }`: the package resolves the person by ID in the organisation its
+// credential is bound to (standard 2825122 R-53). Their definitions live in the
+// package, never in the scanned tree, so R-6's in-tree resolver judgement
+// (judgeResolverFunction) cannot read them, and a door writing
+// `orgId: who.principal.orgId` read as a laundered caller argument —
+// vantage-peers `startBinding` at sigma/start-binding-by-id ae58c95.
+//
+// What is credited, read with the parser on the handler's DIRECT statements
+// before its first write (a statement that ends at or after the write line is
+// not read):
+//   - `const R = await F(…)` where F is the file's own named (or namespace)
+//     import of `resolveActingPrincipal` / `resolvePersonPrincipal` from
+//     @vantageos/cloud-identity (aliases resolved). `let`/`var`, a call that is
+//     not awaited, a local function, or an import from any other module: not
+//     credited.
+//   - `if (!R.ok) <exit>` (or `R.ok === false`, `R.ok !== true`), no `else`,
+//     whose branch ALWAYS leaves the handler: a `throw`/`return` statement, or
+//     a block whose last statement is one. A branch that logs and continues, an
+//     empty block, or a branch that exits on only one of its paths: not
+//     credited.
+//   - the principal is then `R.principal` and any member read of it, and an
+//     ALIAS bound by `const P = R.principal` or `const { principal[: P] } = R`
+//     (no default value), and any member read of the alias.
+// The principal of an R that is not checked, or of a different R than the one
+// checked, is never credited. Nothing here credits `R` itself, `R.refusal…`, or
+// an expression that mixes the principal with anything else
+// (`R.principal.orgId ?? args.orgId`).
+//
+// Declared limits: a refusal inside a nested block of the handler (a branch, a
+// try, a loop) is not read — the door is then judged as before this change; a
+// nested-scope shadow of R or P before the write is not modelled (the text taint
+// read of R-6 still sees the shadowing assignment and keeps it accused).
+import * as ts from "typescript";
+import { dotted, lineOf, unwrap } from "./_ast.js";
+import { handlerBodyOf } from "./guard-helper-flow.js";
+import { importsOf, PACKAGE_RESOLVERS, pkgExportOf, refusesOnNotOk, } from "./identity-by-id.js";
+const NONE = { principalOf: () => undefined };
+/** Does `e` read the handler's `args`, directly or through a `const` it names?
+ * A local whose declaration is not among `locals` (a parameter, a closure
+ * variable) is not followed; `args` itself is the caller's input. */
+function readsArgs(e, locals, seen) {
+    let hit = false;
+    const visit = (n) => {
+        if (hit)
+            return;
+        if (ts.isIdentifier(n)) {
+            const parent = n.parent;
+            const nameOnly = parent &&
+                ((ts.isPropertyAccessExpression(parent) && parent.name === n) ||
+                    (ts.isPropertyAssignment(parent) && parent.name === n));
+            if (!nameOnly) {
+                if (n.text === "args")
+                    hit = true;
+                else if (!seen.has(n.text) && locals.has(n.text)) {
+                    seen.add(n.text);
+                    if (readsArgs(locals.get(n.text), locals, seen))
+                        hit = true;
+                }
+            }
+        }
+        n.forEachChild(visit);
+    };
+    visit(e);
+    return hit;
+}
+/** A statement that leaves the handler on every path. */
+function alwaysExits(st) {
+    if (ts.isThrowStatement(st) || ts.isReturnStatement(st))
+        return true;
+    if (!ts.isBlock(st) || st.statements.length === 0)
+        return false;
+    const last = st.statements[st.statements.length - 1];
+    return ts.isThrowStatement(last) || ts.isReturnStatement(last);
+}
+const endLineOf = (n) => n.getSourceFile().getLineAndCharacterOfPosition(n.getEnd()).line + 1;
+/** Read handler `handlerName` of `p` before `beforeLine` (the first write). */
+export function packagePrincipals(p, handlerName, beforeLine) {
+    const { imports } = importsOf(p);
+    if (imports.named.size === 0 && imports.namespaces.size === 0)
+        return NONE;
+    const body = handlerBodyOf(p.sf, handlerName);
+    if (!body)
+        return NONE;
+    const results = new Map();
+    const locals = new Map(); // const name -> initializer
+    const aliases = new Map(); // alias -> result local
+    for (const st of body.statements) {
+        if (endLineOf(st) >= beforeLine)
+            break;
+        if (ts.isVariableStatement(st)) {
+            if ((st.declarationList.flags & ts.NodeFlags.Const) === 0)
+                continue;
+            for (const d of st.declarationList.declarations) {
+                if (!d.initializer)
+                    continue;
+                const init = d.initializer;
+                if (ts.isIdentifier(d.name)) {
+                    const awaited = ts.isAwaitExpression(init)
+                        ? unwrap(init.expression)
+                        : undefined;
+                    const exp = awaited && ts.isCallExpression(awaited)
+                        ? pkgExportOf(awaited.expression, imports)
+                        : undefined;
+                    if (exp && PACKAGE_RESOLVERS.has(exp)) {
+                        // The credential is the identity claim: one the caller's
+                        // arguments reach is a forged claim, never a verified one.
+                        const cred = awaited && ts.isCallExpression(awaited) ? awaited.arguments[0] : undefined;
+                        if (!cred || readsArgs(cred, locals, new Set()))
+                            continue;
+                        results.set(d.name.text, { resolver: exp, line: lineOf(st) });
+                        continue;
+                    }
+                    locals.set(d.name.text, init);
+                    const path = dotted(init);
+                    const m = path ? /^([A-Za-z_$][\w$]*)\.principal$/.exec(path) : null;
+                    if (m && results.has(m[1]))
+                        aliases.set(d.name.text, m[1]);
+                    continue;
+                }
+                if (ts.isObjectBindingPattern(d.name)) {
+                    const from = unwrap(init);
+                    if (!ts.isIdentifier(from) || !results.has(from.text))
+                        continue;
+                    for (const e of d.name.elements) {
+                        if (e.dotDotDotToken || e.initializer)
+                            continue;
+                        if (!ts.isIdentifier(e.name))
+                            continue;
+                        const key = e.propertyName ?? e.name;
+                        if (ts.isIdentifier(key) && key.text === "principal")
+                            aliases.set(e.name.text, from.text);
+                    }
+                }
+            }
+            continue;
+        }
+        if (!ts.isIfStatement(st) || st.elseStatement)
+            continue;
+        if (!alwaysExits(st.thenStatement))
+            continue;
+        for (const [local, r] of results)
+            if (r.checkLine === undefined && refusesOnNotOk(st.expression, local))
+                r.checkLine = lineOf(st);
+    }
+    const why = (local) => {
+        const r = results.get(local);
+        if (!r || r.checkLine === undefined)
+            return undefined;
+        return `the principal @vantageos/cloud-identity ${r.resolver}() resolved into "${local}" (line ${r.line}), refused on !${local}.ok at line ${r.checkLine} before the write`;
+    };
+    if (![...results.values()].some((r) => r.checkLine !== undefined))
+        return NONE;
+    return {
+        principalOf(expr) {
+            const e = expr
+                .trim()
+                .replace(/;+\s*$/, "")
+                .replace(/\s+/g, "")
+                .replace(/\?\./g, ".");
+            const m = /^([A-Za-z_$][\w$]*)((?:\.[A-Za-z_$][\w$]*)*)$/.exec(e);
+            if (!m)
+                return undefined;
+            const [, head, rest] = m;
+            const aliased = aliases.get(head);
+            if (aliased !== undefined)
+                return why(aliased);
+            if (rest === ".principal" || rest.startsWith(".principal."))
+                return why(head);
+            return undefined;
+        },
+    };
+}

package/dist/detectors/source/r6-shapes.d.ts

@@ -0,0 +1,20 @@
+import * as ts from "typescript";
+import { type Registration, type SrcFile } from "./_ast.js";
+/** Judge a function as a master-only wrapper (shape 1). */
+export declare function isMasterOnlyWrapper(fn: ts.FunctionLikeDeclaration): boolean;
+/** Shape 1 at a handler: an awaited top-level call, before the first write, to a
+ * FILE-LOCAL master-only wrapper. Returns the credit text or undefined. */
+export declare function masterOnlyWrapperCredit(f: SrcFile, handlerName: string): string | undefined;
+/** Shape 2 at a handler. Returns the credit text or undefined. */
+export declare function possessionGatedCredit(f: SrcFile, handlerName: string): string | undefined;
+export interface PossessionGate {
+    rowVar: string;
+    table: string;
+    field: string;
+    hashLine: number;
+    rowLine: number;
+    writes: number;
+}
+/** The possession gate of a registration, or undefined when the shape is not
+ * held in full. */
+export declare function possessionGate(reg: Registration): PossessionGate | undefined;

package/dist/detectors/source/r6-shapes.js

@@ -0,0 +1,285 @@
+// Two write shapes R-6 used to defer (could-not-judge) although each is readable
+// in full from the handler and the file it sits in. Both are judged here on the
+// AST; neither is credited from a comment marker.
+//
+// 1. MASTER-ONLY FILE-LOCAL WRAPPER. The handler's first statements call a
+//    function defined in the SAME file whose body is exactly:
+//        const scope = await withOrgScope(ctx);          // fail-closed resolver
+//        if (!scope.isMaster) throw …;                   // refuses every non-master
+//        [return scope;]
+//    Every path through it refuses unless the verified caller is the fleet
+//    master, so the write that follows is master-only. A master-only write on a
+//    table with no member boundary has no boundary an argument could steer: R-6
+//    conforms. ANY other statement in the wrapper (an early return, a second
+//    branch, a conjunction in the master test, an `allowNoIdentityMaster: true`
+//    option) leaves the shape unrecognised and the site stays where it was.
+//
+// 2. POSSESSION-GATED WRITE. The handler hashes an ARGUMENT
+//    (`const h = await sha256Hex(args.key)`), selects ONE row through a unique
+//    index on a hash field (`.withIndex(…, q => q.eq("keyHash", h)).unique()`),
+//    and every write it performs is a patch/replace/delete of THAT row's `_id` —
+//    no insert, no scheduled or run effect, no other row. The caller can only
+//    reach a row whose secret it already holds; the write carries no boundary
+//    the caller could choose. A handler that hash-matches and then writes ANY
+//    other row is not this shape. `@credential` / `allow-no-caller-resolution:`
+//    markers above the registration are reported as corroboration only.
+//
+// Origin: VP main 11a7057 — seven requireMasterScope sites (errorMonitor.ts
+// 537/565, githubRepoMapping.ts 303/337, issues.ts 183/210/270) and
+// licenses.ts:140 activate, proven safe by vantage-peers sigma/r6-abstentions
+// @08aa83e convex/__tests__/r6AbstentionsResolved.test.ts (10/10).
+import * as ts from "typescript";
+import { dotted, lineOf, parseFile, registrations, unwrap, walk, } from "./_ast.js";
+const HASH_CALLEE = /sha256|sha512|hash|digest/i;
+/** A resolver whose `isMaster: true` comes only from a verified identity unless
+ * the call opts into `allowNoIdentityMaster` (vantage-peers convex/lib/auth.ts
+ * `withOrgScope`: the no-identity branch returns a non-master scope). */
+const FAIL_CLOSED_SCOPE = new Set(["withOrgScope"]);
+// Keyed on the file OBJECT: one parse per file per run, and two different files
+// that share a path (a fixture rewritten between runs) never share a parse.
+const cache = new WeakMap();
+function parsedOf(f) {
+    let p = cache.get(f);
+    if (!p) {
+        p = parseFile(f);
+        cache.set(f, p);
+    }
+    return p;
+}
+function refusesNonMasterOn(c0, scopeVar) {
+    const c = unwrap(c0);
+    if (ts.isPrefixUnaryExpression(c) &&
+        c.operator === ts.SyntaxKind.ExclamationToken) {
+        const o = unwrap(c.operand);
+        return (ts.isPropertyAccessExpression(o) &&
+            o.name.text === "isMaster" &&
+            dotted(o.expression) === scopeVar);
+    }
+    return false;
+}
+function throwsOnly(s) {
+    if (ts.isThrowStatement(s))
+        return true;
+    return (ts.isBlock(s) &&
+        s.statements.length > 0 &&
+        ts.isThrowStatement(s.statements[s.statements.length - 1]) &&
+        s.statements.every((x) => ts.isThrowStatement(x) || ts.isVariableStatement(x)));
+}
+/** Judge a function as a master-only wrapper (shape 1). */
+export function isMasterOnlyWrapper(fn) {
+    const body = fn.body;
+    if (!body || !ts.isBlock(body))
+        return false;
+    const st = body.statements;
+    if (st.length < 2 || st.length > 3)
+        return false;
+    const s0 = st[0];
+    if (!ts.isVariableStatement(s0))
+        return false;
+    const decls = s0.declarationList.declarations;
+    if (decls.length !== 1 || !ts.isIdentifier(decls[0].name))
+        return false;
+    const scopeVar = decls[0].name.text;
+    const init = decls[0].initializer && unwrap(decls[0].initializer);
+    if (!init || !ts.isCallExpression(init))
+        return false;
+    const callee = unwrap(init.expression);
+    if (!ts.isIdentifier(callee) || !FAIL_CLOSED_SCOPE.has(callee.text))
+        return false;
+    if (init.arguments
+        .slice(1)
+        .some((a) => /allowNoIdentityMaster\s*:\s*(?!false\b)/.test(a.getText())))
+        return false;
+    const s1 = st[1];
+    if (!ts.isIfStatement(s1) ||
+        s1.elseStatement !== undefined ||
+        !refusesNonMasterOn(s1.expression, scopeVar) ||
+        !throwsOnly(s1.thenStatement))
+        return false;
+    if (st.length === 3) {
+        const s2 = st[2];
+        if (!ts.isReturnStatement(s2))
+            return false;
+        if (s2.expression && dotted(s2.expression) !== scopeVar)
+            return false;
+    }
+    return true;
+}
+function registrationNamed(p, name) {
+    return registrations(p).find((r) => r.name === name);
+}
+function localFunctions(p) {
+    const out = new Map();
+    for (const st of p.sf.statements) {
+        if (ts.isFunctionDeclaration(st) && st.name && st.body)
+            out.set(st.name.text, st);
+        else if (ts.isVariableStatement(st))
+            for (const d of st.declarationList.declarations) {
+                const i = d.initializer && unwrap(d.initializer);
+                if (ts.isIdentifier(d.name) &&
+                    i &&
+                    (ts.isArrowFunction(i) || ts.isFunctionExpression(i)))
+                    out.set(d.name.text, i);
+            }
+    }
+    return out;
+}
+const WRITE = /\bdb\.(patch|replace|delete|insert)$/;
+const EFFECT = /\b(scheduler\.(runAfter|runAt)|runMutation|runAction)$/;
+/** Shape 1 at a handler: an awaited top-level call, before the first write, to a
+ * FILE-LOCAL master-only wrapper. Returns the credit text or undefined. */
+export function masterOnlyWrapperCredit(f, handlerName) {
+    const p = parsedOf(f);
+    const reg = registrationNamed(p, handlerName);
+    const body = reg?.handler.body;
+    if (!reg || !body || !ts.isBlock(body))
+        return undefined;
+    const locals = localFunctions(p);
+    for (const st of body.statements) {
+        let firstWrite = false;
+        walk(st, (x) => {
+            if (ts.isCallExpression(x)) {
+                const c = dotted(x.expression) ?? "";
+                if (WRITE.test(c) || EFFECT.test(c))
+                    firstWrite = true;
+            }
+        });
+        if (firstWrite)
+            return undefined;
+        const e = ts.isExpressionStatement(st)
+            ? unwrap(st.expression)
+            : ts.isVariableStatement(st) &&
+                st.declarationList.declarations.length === 1 &&
+                st.declarationList.declarations[0].initializer
+                ? unwrap(st.declarationList.declarations[0].initializer)
+                : undefined;
+        if (!e || !ts.isCallExpression(e))
+            continue;
+        const callee = unwrap(e.expression);
+        if (!ts.isIdentifier(callee))
+            continue;
+        const fn = locals.get(callee.text);
+        if (fn && isMasterOnlyWrapper(fn))
+            return `master-only: ${callee.text}() (file-local, ${f.rel}:${lineOf(fn)}) resolves the caller through a fail-closed withOrgScope and refuses every non-master on every path, called at line ${lineOf(st)} before the first write — a master-only write has no member boundary an argument could steer`;
+    }
+    return undefined;
+}
+/** Shape 2 at a handler. Returns the credit text or undefined. */
+export function possessionGatedCredit(f, handlerName) {
+    const p = parsedOf(f);
+    const reg = registrationNamed(p, handlerName);
+    const body = reg?.handler.body;
+    if (!reg || !body)
+        return undefined;
+    const g = possessionGate(reg);
+    if (!g)
+        return undefined;
+    const markers = [];
+    const start = reg.line;
+    const lines = p.sf.text.split("\n");
+    for (let i = Math.max(0, start - 15); i < start - 1; i++) {
+        if (/@credential\b/.test(lines[i]))
+            markers.push("@credential");
+        if (/allow-no-caller-resolution:/.test(lines[i]))
+            markers.push("allow-no-caller-resolution");
+    }
+    return `possession-gated: the argument is hashed (line ${g.hashLine}) and matched through a unique index on ${g.table}.${g.field} (line ${g.rowLine}); every write (${g.writes}) is that one row's _id — no other row, no insert, no effect${markers.length ? ` (corroborated by marker(s) ${[...new Set(markers)].join(", ")}, never the reason)` : ""}`;
+}
+/** The possession gate of a registration, or undefined when the shape is not
+ * held in full. */
+export function possessionGate(reg) {
+    const body = reg.handler.body;
+    if (!body)
+        return undefined;
+    const hashVars = new Map();
+    const rows = new Map();
+    walk(body, (x) => {
+        if (!ts.isVariableDeclaration(x) ||
+            !ts.isIdentifier(x.name) ||
+            !x.initializer)
+            return;
+        const init = unwrap(x.initializer);
+        if (ts.isCallExpression(init)) {
+            const c = dotted(init.expression) ?? "";
+            if (HASH_CALLEE.test(c.split(".").pop() ?? "") &&
+                init.arguments.some((a) => /\bargs\.\w+/.test(a.getText()))) {
+                hashVars.set(x.name.text, lineOf(x));
+                return;
+            }
+            // ctx.db.query("T").withIndex(_, q => q.eq("f", h)).unique()
+            const outer = unwrap(init.expression);
+            if (ts.isPropertyAccessExpression(outer) &&
+                outer.name.text === "unique" &&
+                init.arguments.length === 0) {
+                let table;
+                let eq;
+                let eqCount = 0;
+                walk(init, (y) => {
+                    if (!ts.isCallExpression(y))
+                        return;
+                    const yc = unwrap(y.expression);
+                    if (!ts.isPropertyAccessExpression(yc))
+                        return;
+                    if (yc.name.text === "query" &&
+                        y.arguments[0] &&
+                        ts.isStringLiteralLike(y.arguments[0]))
+                        table = y.arguments[0].text;
+                    if (yc.name.text === "eq" &&
+                        y.arguments.length === 2 &&
+                        ts.isStringLiteralLike(y.arguments[0])) {
+                        eqCount++;
+                        eq = {
+                            field: y.arguments[0].text,
+                            value: y.arguments[1].getText(),
+                        };
+                    }
+                });
+                if (table && eq && eqCount === 1 && /hash/i.test(eq.field))
+                    rows.set(x.name.text, {
+                        table,
+                        field: `${eq.field}=${eq.value}`,
+                        line: lineOf(x),
+                    });
+            }
+        }
+    });
+    let gate;
+    for (const [rowVar, r] of rows) {
+        const [field, value] = r.field.split("=");
+        const hashLine = hashVars.get(value);
+        if (hashLine === undefined)
+            continue;
+        gate = {
+            rowVar,
+            table: r.table,
+            field,
+            hashLine,
+            rowLine: r.line,
+            writes: 0,
+        };
+    }
+    if (!gate)
+        return undefined;
+    let ok = true;
+    let writes = 0;
+    walk(body, (x) => {
+        if (!ts.isCallExpression(x))
+            return;
+        const c = dotted(x.expression) ?? "";
+        if (EFFECT.test(c))
+            ok = false;
+        const m = WRITE.exec(c);
+        if (!m)
+            return;
+        writes++;
+        if (m[1] === "insert")
+            ok = false;
+        else if (!x.arguments[0] ||
+            dotted(x.arguments[0]) !== `${gate?.rowVar}._id`)
+            ok = false;
+    });
+    if (!ok || writes === 0)
+        return undefined;
+    gate.writes = writes;
+    return gate;
+}

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

@@ -1,5 +1,6 @@
 import type { Detector } from "../../engine-types.js";
 import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare const READ_BOUND_TOKEN: RegExp;
 export declare function scanR31(files: SrcFile[]): Scan;
 export declare const R31: Detector;
 /** In the form the orchestrator spreads into REGISTRY. */