@vantageos/backend-doctor 0.4.0 → 0.4.3

package/dist/detectors/source/local-identity.js

@@ -71,7 +71,7 @@
 // per-module split, and gives a non-zero exit.
 import * as ts from "typescript";
 import { siteCount, withCount } from "../../violation-count.js";
-import { calleeName, dotted, lineOf, parseFile, propRead, propReadResolved, sourceOf, unwrap, walk, } from "./_ast.js";
+import { calleeName, dotted, indexFunctions, lineOf, parseFile, propRead, propReadResolved, sourceOf, unwrap, walk, } from "./_ast.js";
 import { isConvexOrMcp, isJudgeable, } from "./_scan.js";
 import { conformantMappingReads, IDENTITY_PACKAGE, scanR53Detailed, } from "./identity-by-id.js";
 export 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";
@@ -301,8 +301,435 @@ const isNormaliserCall = (e) => {
     const u = unwrap(e);
     return ts.isCallExpression(u) && NAME_NORMALISER.test(calleeName(u) ?? "");
 };
+// ---- forwarding a verified claim ------------------------------------------
+//
+// A function that copies a verified-claim field (`oauthCtx.fromAllowList`) into
+// the arguments of a backend call decides nothing from it: the door it calls
+// does the deciding. That is the CONFORMING shape — the claim travels to the
+// one place allowed to judge it. vantage-peers 9e224b2 `rosterClaimArgs`
+// (mcp-server/src/tools.ts:1849) needed an `allow-local-identity:` marker only
+// because the read was taken for a filter.
+//
+// Credited ONLY when, mechanically:
+//  - the call it reaches is a BACKEND DOOR (`doorCheckIn`:
+//    `convex|client|<x>Client .query/.mutation/.action`, `<ctx>.runQuery/
+//    runMutation/runAction`, on a receiver whose BINDING is a parameter, a
+//    package import, a constructed client or a judged client wrapper — never
+//    its name alone, Eta probe V5). A claim handed to a function defined in the tree,
+//    to an unknown helper, or to a storage write is NOT forwarded: that callee
+//    is where the decision would move (`etaAdmits(rosterClaimArgs(ctx), who)`),
+//    and nothing judges it here (Eta on #68, probe V2);
+//  - the read's value reaches a call ARGUMENT (or an object literal that is a
+//    call argument) through nothing but parentheses, casts, non-null, and a
+//    `?? <literal | [] | {}>` / `|| <…>` fallback — any other use (a `.filter`,
+//    `.includes`, a comparison, a local binding) is not a forward;
+//  - or that object literal is RETURNED by a named function (a declaration, or
+//    a `const` bound to an arrow / function expression) and EVERY reference to
+//    that name in the tree is a call whose result is itself handed to a
+//    backend door's argument — directly, spread into the arguments, or spread into an object
+//    literal that is a call argument. A function nobody calls, a callback, a
+//    property-assigned arrow, or one caller that keeps the result (to compare
+//    it, to bind it, to return it) credits nothing: a tool does not clear a
+//    site whose consumer nobody judged;
+//  - the receiver is not the caller's own `args` (a client-supplied list is not
+//    a verified claim);
+//  - the function holding it makes NO identity decision: no equality between
+//    two non-literal values, no equality reading a name or slug field, no
+//    membership test (`includes`/`has`/`indexOf`/`some`/`every`) on a
+//    non-literal, and no refusing `if` (then-arm returns or throws) whose
+//    condition reads a field of the object the claim is read off. Any one of
+//    these keeps the read red.
+const FALLBACK_OPS = new Set([
+    ts.SyntaxKind.QuestionQuestionToken,
+    ts.SyntaxKind.BarBarToken,
+]);
+const isInertFallback = (e) => {
+    const u = unwrap(e);
+    return (isLiteral(u) ||
+        (ts.isArrayLiteralExpression(u) && u.elements.length === 0) ||
+        (ts.isObjectLiteralExpression(u) && u.properties.length === 0));
+};
+const rootIdentifier = (e) => {
+    let x = unwrap(e);
+    for (;;) {
+        const r = propRead(x);
+        if (r)
+            x = unwrap(r.obj);
+        else if (ts.isCallExpression(x))
+            return undefined;
+        else
+            return ts.isIdentifier(x) ? x : undefined;
+    }
+};
+/** The calls allowed to judge a forwarded claim: a Convex door reached
+ * through a client (`convex.query/mutation/action`, `client.…`,
+ * `<x>Client.…`) or from a function context (`<ctx>.runQuery/runMutation/
+ * runAction`). Never a function defined in the tree, never a storage write
+ * (`ctx.db.patch` / `insert`), never an unknown helper: none of those judges
+ * the claim, so handing it to one is not forwarding it.
+ *
+ * The door is recognised by its receiver's BINDING, never by its name alone
+ * (Eta on #68, probe V5: a local `const etaClient = { query: <decides> }`
+ * named like a client). The receiver must be a plain identifier that resolves,
+ * in its own file, to one of:
+ *  - a parameter of an enclosing function (the caller hands the client in);
+ *  - an import from a PACKAGE (a non-relative specifier);
+ *  - a `const` built by a known client constructor (`new ConvexHttpClient(…)`,
+ *    `new ConvexClient(…)`, `new ConvexReactClient(…)`);
+ *  - a `const` built by a CLIENT WRAPPER `W(<receiver>, …)` whose first
+ *    argument itself qualifies, where every definition of `W` in the tree takes
+ *    the client as its first parameter and returns only that parameter or
+ *    `new Proxy(<that parameter>, …)` (vantage-peers `withVerifiedActor`).
+ *    A `W` with no definition in the tree credits nothing.
+ * Anything else is refused: an object literal, an arrow or function, a class,
+ * a `let`, a loop variable, a relative (tree) import, an unresolved name, or a
+ * property-access receiver (`ctx.db.query`, `deps.client.query`).
+ * NOT JUDGED (declared): the handler of a `new Proxy(<client>, handler)`
+ * wrapper; such a handler could decide, and is credited as a pass-through. */
+const CLIENT_DOOR_METHODS = new Set([
+    "query",
+    "mutation",
+    "action",
+]);
+const CTX_DOOR_METHODS = new Set([
+    "runQuery",
+    "runMutation",
+    "runAction",
+]);
+const CLIENT_RECEIVER = /^(convex|client|[A-Za-z_$][\w$]*Client)$/;
+const CLIENT_CONSTRUCTORS = new Set([
+    "ConvexHttpClient",
+    "ConvexClient",
+    "ConvexReactClient",
+]);
+/** Does a binding name (identifier or destructuring pattern) bind `name`? */
+function bindsName(b, name) {
+    if (ts.isIdentifier(b))
+        return b.text === name;
+    const els = b.elements;
+    return els.some((e) => !ts.isOmittedExpression(e) && bindsName(e.name, name));
+}
+/** The declaration `id` resolves to, by lexical scope, in its own file. */
+function bindingOf(id) {
+    const name = id.text;
+    for (let n = id.parent; n; n = n.parent) {
+        if (ts.isFunctionLike(n)) {
+            if (n.parameters.some((prm) => bindsName(prm.name, name)))
+                return { kind: "param" };
+            if (ts.isFunctionExpression(n) && n.name?.text === name)
+                return { kind: "other" };
+        }
+        if ((ts.isForStatement(n) || ts.isForOfStatement(n) || ts.isForInStatement(n)) &&
+            n.initializer &&
+            ts.isVariableDeclarationList(n.initializer) &&
+            n.initializer.declarations.some((d) => bindsName(d.name, name)))
+            return { kind: "other" };
+        if (ts.isCatchClause(n) &&
+            n.variableDeclaration &&
+            bindsName(n.variableDeclaration.name, name))
+            return { kind: "other" };
+        const stmts = ts.isBlock(n) ||
+            ts.isSourceFile(n) ||
+            ts.isModuleBlock(n) ||
+            ts.isCaseClause(n) ||
+            ts.isDefaultClause(n)
+            ? n.statements
+            : undefined;
+        if (!stmts)
+            continue;
+        for (const st of stmts) {
+            if (ts.isVariableStatement(st)) {
+                const isConst = (st.declarationList.flags & ts.NodeFlags.Const) !== 0;
+                for (const d of st.declarationList.declarations) {
+                    if (!bindsName(d.name, name))
+                        continue;
+                    return isConst && ts.isIdentifier(d.name)
+                        ? { kind: "const", init: d.initializer }
+                        : { kind: "other" };
+                }
+            }
+            if ((ts.isFunctionDeclaration(st) ||
+                ts.isClassDeclaration(st) ||
+                ts.isEnumDeclaration(st) ||
+                ts.isModuleDeclaration(st)) &&
+                st.name &&
+                ts.isIdentifier(st.name) &&
+                st.name.text === name)
+                return { kind: "other" };
+            if (ts.isImportDeclaration(st) &&
+                ts.isStringLiteral(st.moduleSpecifier)) {
+                const c = st.importClause;
+                const b = c?.namedBindings;
+                const hit = c?.name?.text === name ||
+                    (b !== undefined &&
+                        (ts.isNamespaceImport(b)
+                            ? b.name.text === name
+                            : b.elements.some((e) => e.name.text === name)));
+                if (hit)
+                    return { kind: "import", spec: st.moduleSpecifier.text };
+            }
+        }
+    }
+    return undefined;
+}
+/** Own return expressions of `fn` (nested functions excluded); a concise
+ * arrow body counts as its one return. */
+function ownReturns(fn) {
+    if (!fn.body)
+        return [];
+    if (!ts.isBlock(fn.body))
+        return [fn.body];
+    const out = [];
+    const visit = (x) => {
+        if (ts.isFunctionLike(x) || ts.isClassLike(x))
+            return;
+        if (ts.isReturnStatement(x))
+            out.push(x.expression);
+        ts.forEachChild(x, visit);
+    };
+    ts.forEachChild(fn.body, visit);
+    return out;
+}
+/** `fn` takes the client first and hands back only that client, bare or behind
+ * `new Proxy(<client>, …)`. */
+function isClientWrapper(fn) {
+    const p0 = fn.parameters[0]?.name;
+    if (!p0 || !ts.isIdentifier(p0))
+        return false;
+    const isP0 = (e) => {
+        if (!e)
+            return false;
+        const u = unwrap(e);
+        return ts.isIdentifier(u) && u.text === p0.text;
+    };
+    const rets = ownReturns(fn);
+    return (rets.length > 0 &&
+        rets.every((r) => {
+            if (isP0(r))
+                return true;
+            const u = r && unwrap(r);
+            return (!!u &&
+                ts.isNewExpression(u) &&
+                ts.isIdentifier(u.expression) &&
+                u.expression.text === "Proxy" &&
+                isP0(u.arguments?.[0]));
+        }));
+}
+/** The door check over a parsed tree (client wrappers resolve by name). */
+function doorCheckIn(parsed) {
+    const idx = indexFunctions(parsed);
+    const wrapperMemo = new Map();
+    const wrapperOk = (name) => {
+        let v = wrapperMemo.get(name);
+        if (v === undefined) {
+            const defs = idx.get(name) ?? [];
+            v = defs.length > 0 && defs.every((d) => isClientWrapper(d.fn));
+            wrapperMemo.set(name, v);
+        }
+        return v;
+    };
+    const clientBinding = (id, depth) => {
+        if (depth > 4)
+            return false;
+        const b = bindingOf(id);
+        if (!b)
+            return false;
+        if (b.kind === "param")
+            return true;
+        if (b.kind === "import")
+            return !b.spec.startsWith(".") && !b.spec.startsWith("/");
+        if (b.kind !== "const" || !b.init)
+            return false;
+        const init = unwrap(b.init);
+        if (ts.isNewExpression(init) &&
+            ts.isIdentifier(init.expression) &&
+            CLIENT_CONSTRUCTORS.has(init.expression.text))
+            return true;
+        if (ts.isCallExpression(init) && ts.isIdentifier(init.expression)) {
+            const a0 = init.arguments[0] && unwrap(init.arguments[0]);
+            return (!!a0 &&
+                ts.isIdentifier(a0) &&
+                clientBinding(a0, depth + 1) &&
+                wrapperOk(init.expression.text));
+        }
+        return false;
+    };
+    return (call) => {
+        const c = unwrap(call.expression);
+        if (!ts.isPropertyAccessExpression(c))
+            return false;
+        const m = c.name.text;
+        const recv = unwrap(c.expression);
+        if (!ts.isIdentifier(recv))
+            return false;
+        if (CTX_DOOR_METHODS.has(m))
+            return clientBinding(recv, 0);
+        if (!CLIENT_DOOR_METHODS.has(m))
+            return false;
+        return CLIENT_RECEIVER.test(recv.text) && clientBinding(recv, 0);
+    };
+}
+/** Climb from `n` through wrappers and object-literal nesting; true when it
+ * lands in a BACKEND DOOR call's arguments (`isBackendDoor`). `inObject` reports whether an object literal was
+ * climbed (the caller of a returned literal needs one). */
+function climbToArgument(n, isBackendDoor, onReturn) {
+    let cur = n;
+    let inObject = false;
+    for (let p = cur.parent; p; cur = p, p = p.parent) {
+        if (ts.isParenthesizedExpression(p) ||
+            ts.isNonNullExpression(p) ||
+            ts.isAsExpression(p) ||
+            ts.isSatisfiesExpression(p) ||
+            ts.isAwaitExpression(p))
+            continue;
+        if (ts.isBinaryExpression(p) &&
+            FALLBACK_OPS.has(p.operatorToken.kind) &&
+            p.left === cur &&
+            isInertFallback(p.right))
+            continue;
+        if ((ts.isPropertyAssignment(p) && p.initializer === cur) ||
+            (ts.isSpreadAssignment(p) && p.expression === cur)) {
+            p = p.parent; // the object literal
+            inObject = true;
+            continue;
+        }
+        if (ts.isSpreadElement(p) && p.expression === cur) {
+            if (p.parent && ts.isCallExpression(p.parent))
+                return (isBackendDoor(p.parent) && p.parent.arguments.some((a) => a === p));
+            return false;
+        }
+        if (ts.isCallExpression(p))
+            return isBackendDoor(p) && p.arguments.some((a) => a === cur);
+        if (!onReturn)
+            return false;
+        if (ts.isReturnStatement(p) && p.expression === cur) {
+            let fn = p.parent;
+            while (fn && !ts.isFunctionLike(fn))
+                fn = fn.parent;
+            return !!fn && onReturn(fn, inObject);
+        }
+        if (ts.isArrowFunction(p) && p.body === cur)
+            return onReturn(p, inObject);
+        return false;
+    }
+    return false;
+}
+/** The name a function is called by: a declaration's, or the `const` an arrow /
+ * function expression initialises. */
+function calledName(fn) {
+    if (ts.isFunctionDeclaration(fn))
+        return fn.name?.text;
+    if ((ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) &&
+        fn.parent &&
+        ts.isVariableDeclaration(fn.parent) &&
+        fn.parent.initializer === fn &&
+        ts.isIdentifier(fn.parent.name))
+        return fn.parent.name.text;
+    return undefined;
+}
+function callersForwardIn(parsed, isBackendDoor) {
+    const memo = new Map();
+    return (name) => {
+        const hit = memo.get(name);
+        if (hit !== undefined)
+            return hit;
+        let calls = 0;
+        let ok = true;
+        for (const p of parsed) {
+            if (!ok)
+                break;
+            if (!p.sf.text.includes(name))
+                continue;
+            walk(p.sf, (x) => {
+                if (!ok || !ts.isIdentifier(x) || x.text !== name)
+                    return;
+                const par = x.parent;
+                if ((ts.isFunctionDeclaration(par) && par.name === x) ||
+                    (ts.isVariableDeclaration(par) && par.name === x) ||
+                    ts.isImportSpecifier(par) ||
+                    ts.isExportSpecifier(par) ||
+                    ts.isImportClause(par) ||
+                    (ts.isPropertyAccessExpression(par) && par.name === x) ||
+                    (ts.isPropertyAssignment(par) && par.name === x))
+                    return;
+                if (ts.isCallExpression(par) &&
+                    par.expression === x &&
+                    climbToArgument(par, isBackendDoor)) {
+                    calls++;
+                    return;
+                }
+                ok = false;
+            });
+        }
+        const v = ok && calls > 0;
+        memo.set(name, v);
+        return v;
+    };
+}
+/** Does the read `n` (receiver `obj`) only travel into a call's arguments? */
+function forwardsOnly(n, obj, callersForward, isBackendDoor) {
+    if (rootIdentifier(obj)?.text === "args")
+        return false;
+    return climbToArgument(n, isBackendDoor, (fn, inObject) => {
+        if (!inObject)
+            return false;
+        const name = calledName(fn);
+        return name !== undefined && callersForward(name);
+    });
+}
+const NAME_OR_SLUG = new Set([
+    ...NAME_FIELDS,
+    "slug",
+    "orgSlug",
+    "clerkOrgSlug",
+]);
+/** The first node of `owner` that decides on identity, or undefined. */
+function decidesOnIdentity(owner, 
+/** the root identifier the forwarded claim is read off (`mapping`) */
+root) {
+    let hit;
+    walk(owner, (x) => {
+        if (hit)
+            return;
+        // a refusing gate that judges a field of the very object the claim is
+        // forwarded from (`if (!mapping || !mapping.isActive) return …`): the
+        // function admits on that object, it does not merely forward it
+        if (root !== undefined && ts.isIfStatement(x) && exits(x.thenStatement)) {
+            let reads = false;
+            walk(x.expression, (y) => {
+                const r = propRead(y);
+                if (r && rootIdentifier(r.obj)?.text === root)
+                    reads = true;
+            });
+            if (reads) {
+                hit = x.expression;
+                return;
+            }
+        }
+        if (ts.isBinaryExpression(x) && EQ.has(x.operatorToken.kind)) {
+            const named = [x.left, x.right].some((s) => {
+                const r = propReadResolved(s);
+                return ((r !== undefined && NAME_OR_SLUG.has(r.name)) ||
+                    (ts.isIdentifier(unwrap(s)) &&
+                        NAME_OR_SLUG.has(unwrap(s).text)));
+            });
+            if (named || (!isLiteral(x.left) && !isLiteral(x.right)))
+                hit = x;
+            return;
+        }
+        if (ts.isCallExpression(x)) {
+            const c = unwrap(x.expression);
+            if (ts.isPropertyAccessExpression(c) &&
+                MEMBER_TEST.has(c.name.text) &&
+                x.arguments[0] &&
+                !isLiteral(x.arguments[0]))
+                hit = x;
+        }
+    });
+    return hit;
+}
 /** The primitives this module adds beside R-53's, one hit per deciding node. */
-function ownHits(p, okReads) {
+function ownHits(p, okReads, callersForward, isBackendDoor) {
     const out = [];
     const jwt = jwtBindings(p);
     walk(p.sf, (x) => {
@@ -389,10 +816,23 @@ function ownHits(p, okReads) {
                     });
             }
         }
-        // scope: a read of an allow-list field
+        // scope: a read of an allow-list field — unless it only FORWARDS the
+        // verified claim into call arguments from a function that decides nothing
         const rd = propRead(x);
-        if (rd && SCOPE_PROPS.has(rd.name))
-            out.push({ node: x, kind: "scope", why: `reads \`${snippet(x)}\`` });
+        if (rd && SCOPE_PROPS.has(rd.name)) {
+            const fwd = forwardsOnly(x, rd.obj, callersForward, isBackendDoor);
+            const decision = fwd
+                ? decidesOnIdentity(ownerOf(x, p.rel).node, rootIdentifier(rd.obj)?.text)
+                : undefined;
+            if (!fwd)
+                out.push({ node: x, kind: "scope", why: `reads \`${snippet(x)}\`` });
+            else if (decision)
+                out.push({
+                    node: x,
+                    kind: "scope",
+                    why: `reads \`${snippet(x)}\` (forwarded, but the same function also decides: \`${snippet(decision)}\`)`,
+                });
+        }
         // membership: a gate on a role / master field
         if (ts.isIfStatement(x) && exits(x.thenStatement)) {
             const r = readsProp(x.expression, ROLE_PROPS);
@@ -545,8 +985,10 @@ export function scanLocalIdentity(files) {
         const o = r.atOwner ? ownerAtDecl(node, p.rel, r.n) : ownerOf(node, p.rel);
         note(o, r.kind, r.why);
     }
+    const isBackendDoor = doorCheckIn(parsed);
+    const callersForward = callersForwardIn(parsed, isBackendDoor);
     for (const p of parsed)
-        for (const h of ownHits(p, okReads))
+        for (const h of ownHits(p, okReads, callersForward, isBackendDoor))
             note(ownerOf(h.node, p.rel), h.kind, `${h.why}, line ${lineOf(h.node)}`);
     for (const { owner, why } of [...sites.values()].sort((a, b) => a.owner.rel.localeCompare(b.owner.rel) || a.owner.n - b.owner.n)) {
         const site = { rel: owner.rel, n: owner.n };

package/dist/trigger.js

@@ -1,6 +1,6 @@
 // D6 — THE PATH-TRIGGER. Decides, given a list of changed paths, whether
 // backend-doctor MUST run. The backend-path shapes are DERIVED from what a
-// Convex backend actually IS (grounded against the real /root/coding/vantage-memory
+// Convex backend actually IS (grounded against the real vantage-peers repository
 // layout, read-only):
 //
 //   SHAPE (a) SCHEMA      — convex/schema.ts (the defineSchema file).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/backend-doctor",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "A conformance instrument that measures the VantagePeers backend against the pinned backend standard. The THIRD doctor built ON the @vantageos/mcp-doctor engine — never a third engine. It consumes runDoctor/renderTable and adds only detectors.",
   "type": "module",
   "main": "./dist/cli.js",