@vantageos/backend-doctor 0.2.0 → 0.3.0

package/dist/detectors/source/guard-helper-flow.d.ts

@@ -9,6 +9,24 @@ export type HelperVerdict = {
     verdict: "could-not-judge";
     why: string;
 };
+/**
+ * SCOPE REFINERS, by name: a call `await R(ctx, <scope>, …)` whose result is
+ * scope-derived exactly when the scope it is handed (at `argIndex`) is. The
+ * refiner returns that scope unchanged, or rebuilds it from a SERVER-SIDE row
+ * after refusing every transport but the fleet service account — vantage-peers
+ * `convex/lib/personPrincipal.ts::resolveVerifiedPerson` (the `verifiedPerson`
+ * proof is believed from the service account only and the person's scope is
+ * re-read from `oauth_access_tokens`). The other arguments it is handed (a
+ * proof, a door name, an asserted name) never become its return.
+ *
+ * Trusted by NAME, on the same footing as `withOrgScope` in isIdentityRead: the
+ * flow walk cannot model "a scope rebuilt from a stored row" as the identity.
+ * The trust is narrow — the result is pure only when the scope argument itself
+ * is pure; a refiner handed anything else confers nothing.
+ */
+export declare const SCOPE_REFINERS: Readonly<Record<string, {
+    argIndex: number;
+}>>;
 /** A callee name, as seen from the function being judged, resolved to its
  * definition in the tree (and to a resolver for names seen from THAT file). */
 export type CallResolver = (name: string) => {
@@ -96,6 +114,10 @@ export interface HandlerGuards {
         line: number;
     }[];
 }
+/** The block body of the `handler` of `const <handlerName> = <builder>({ … })`
+ * at the top level of `sf` (arrow, function expression or method); undefined
+ * when it cannot be located. */
+export declare function handlerBodyOf(sf: ts.SourceFile, handlerName: string): ts.Block | undefined;
 /** Read the direct statements of handler `name` before `beforeLine`. `null`
  * when the handler's body cannot be located. */
 export declare function readHandlerGuards(fileName: string, source: string, handlerName: string, beforeLine: number): HandlerGuards | null;

package/dist/detectors/source/guard-helper-flow.js

@@ -56,6 +56,37 @@ function isIdentityRead(n) {
         return callee.name.text === "getUserIdentity";
     return ts.isIdentifier(callee) && callee.text === "withOrgScope";
 }
+/**
+ * SCOPE REFINERS, by name: a call `await R(ctx, <scope>, …)` whose result is
+ * scope-derived exactly when the scope it is handed (at `argIndex`) is. The
+ * refiner returns that scope unchanged, or rebuilds it from a SERVER-SIDE row
+ * after refusing every transport but the fleet service account — vantage-peers
+ * `convex/lib/personPrincipal.ts::resolveVerifiedPerson` (the `verifiedPerson`
+ * proof is believed from the service account only and the person's scope is
+ * re-read from `oauth_access_tokens`). The other arguments it is handed (a
+ * proof, a door name, an asserted name) never become its return.
+ *
+ * Trusted by NAME, on the same footing as `withOrgScope` in isIdentityRead: the
+ * flow walk cannot model "a scope rebuilt from a stored row" as the identity.
+ * The trust is narrow — the result is pure only when the scope argument itself
+ * is pure; a refiner handed anything else confers nothing.
+ */
+export const SCOPE_REFINERS = {
+    resolveVerifiedPerson: { argIndex: 1 },
+};
+/** `R(…, <pure>, …)` for a SCOPE_REFINERS name, the scope argument pure. */
+function isRefinedPure(n, pure) {
+    if (!ts.isCallExpression(n) || !ts.isIdentifier(n.expression))
+        return false;
+    const spec = SCOPE_REFINERS[n.expression.text];
+    if (!spec)
+        return false;
+    const a = n.arguments[spec.argIndex];
+    if (!a)
+        return false;
+    const u = unwrap(a);
+    return isIdentityRead(u) || (ts.isIdentifier(u) && pure.has(u.text));
+}
 /** Does `expr` depend on the verified identity (a tainted local, or a read)? */
 function dependsOnIdentity(expr, tainted) {
     let hit = false;
@@ -723,7 +754,9 @@ function pureIdentityLocals(fn, seed = new Set()) {
             if (pure.has(n) || reassigned.has(n))
                 continue;
             const u = unwrap(init);
-            if (isIdentityRead(u) || (ts.isIdentifier(u) && pure.has(u.text))) {
+            if (isIdentityRead(u) ||
+                (ts.isIdentifier(u) && pure.has(u.text)) ||
+                isRefinedPure(u, pure)) {
                 pure.add(n);
                 grew = true;
             }
@@ -769,7 +802,10 @@ export function judgeResolverFunction(fn) {
         const where = `the \`return\` at line ${lineOf(r.node)}`;
         const e = ts.isReturnStatement(r.node) ? r.node.expression : undefined;
         const u = e ? unwrap(e) : undefined;
-        if (!u || !(isIdentityRead(u) || (ts.isIdentifier(u) && pure.has(u.text))))
+        if (!u ||
+            !(isIdentityRead(u) ||
+                (ts.isIdentifier(u) && pure.has(u.text)) ||
+                isRefinedPure(u, pure)))
             return {
                 verdict: "refused",
                 why: `${where} hands back a value that is not itself the verified identity/scope`,
@@ -1055,10 +1091,10 @@ function alwaysThrowsStmt(st) {
     });
     return !ret && ts.isThrowStatement(st.statements[st.statements.length - 1]);
 }
-/** Read the direct statements of handler `name` before `beforeLine`. `null`
- * when the handler's body cannot be located. */
-export function readHandlerGuards(fileName, source, handlerName, beforeLine) {
-    const sf = parse(fileName, source);
+/** The block body of the `handler` of `const <handlerName> = <builder>({ … })`
+ * at the top level of `sf` (arrow, function expression or method); undefined
+ * when it cannot be located. */
+export function handlerBodyOf(sf, handlerName) {
     let body;
     for (const st of sf.statements) {
         if (!ts.isVariableStatement(st))
@@ -1085,6 +1121,13 @@ export function readHandlerGuards(fileName, source, handlerName, beforeLine) {
             }
         }
     }
+    return body;
+}
+/** Read the direct statements of handler `name` before `beforeLine`. `null`
+ * when the handler's body cannot be located. */
+export function readHandlerGuards(fileName, source, handlerName, beforeLine) {
+    const sf = parse(fileName, source);
+    const body = handlerBodyOf(sf, handlerName);
     if (!body)
         return null;
     const out = { consts: new Map(), refusals: [] };

package/dist/detectors/source/identity-by-id.d.ts

@@ -0,0 +1,80 @@
+import * as ts from "typescript";
+import type { Detector } from "../../engine-types.js";
+import { type FnDef, type Parsed, type SrcFile } from "./_ast.js";
+import { type Scan, type SourceDetectorEntry } from "./_scan.js";
+export declare const IDENTITY_PACKAGE = "@vantageos/cloud-identity";
+export declare const R53_ID = "R-53 an actor and a target are identified by ID through @vantageos/cloud-identity; a name never selects or authorises a row";
+/** Name fields: a display label that must never be an admission operand. */
+export declare const NAME_TOKENS: ReadonlySet<string>;
+/** The package's principal resolvers: the ONLY sinks a host credential read
+ * may feed (first argument). The package verifies nothing about the credential
+ * (cloud-identity 0.11.0 `principal-by-id.d.ts:37`, `person-principal.d.ts:28`),
+ * so the host MUST read `ctx.auth` and hand the claims over; the read is a local
+ * identity decision only when its value goes anywhere else. */
+export declare const PACKAGE_RESOLVERS: ReadonlySet<string>;
+/** Name comparisons in a node's OWN body: `a === b` with a name on one side
+ * and no literal on either, or `names.includes(x)` over a name list. */
+export declare function nameComparisons(n: ts.Node): ts.Node[];
+/** The package's own target check (cloud-identity `principal-by-id`):
+ * `assertTargetBelongsTo(principal, { orgId, ownerId? }, opts?)` at a6e5780,
+ * `await assertTargetBelongsTo(principal, target, lookups, opts?)` at PR #21. */
+export declare const TARGET_CHECK = "assertTargetBelongsTo";
+/** A file's bindings of the package: local name -> exported name for a named
+ * import (aliases resolved), and the locals bound to a namespace import. */
+interface PkgImports {
+    named: Map<string, string>;
+    namespaces: Set<string>;
+}
+export declare function importsOf(p: Parsed): {
+    pkg: Set<string>;
+    imports: PkgImports;
+    unresolved: boolean;
+};
+/** The package export a callee names, through the file's own import of it
+ * (`assertTargetBelongsTo`, `x as y`, `identity.assertTargetBelongsTo`). */
+export declare function pkgExportOf(callee: ts.Expression, imp: PkgImports): string | undefined;
+/** `!v.ok`, `v.ok === false`, `v.ok !== true` (either operand order). */
+export declare function refusesOnNotOk(c0: ts.Expression, v: string): boolean;
+export declare class HostReadFlow {
+    private readonly parsed;
+    private readonly fns;
+    private readonly pkgImports;
+    private readonly defOf;
+    private readonly memo;
+    constructor(parsed: Parsed[], fns: Map<string, FnDef[]>, pkgImports: Map<string, PkgImports>);
+    /** Every `getUserIdentity()` call in `n` whose value does NOT end only in a
+     * package resolver. */
+    unsanctioned(n: ts.Node): ts.CallExpression[];
+    sanctioned(read: ts.CallExpression): boolean;
+    /** Does the value of expression `e` reach ONLY package resolvers? */
+    private flows;
+    private bindingFlows;
+    /** One read of a bound value: an absence test forwarded to the package, or
+     * a value that flows on. */
+    private refFlows;
+    /** A function's return reaches only package resolvers, at EVERY call site. */
+    private returnFlows;
+}
+export declare const ORG_KIND_ADAPTER = "orgKindOf";
+export declare const ORG_BY_ID_ADAPTER = "organisationById";
+/** The host adapters that may hold the ID-keyed mapping read. */
+export declare const ORG_ID_ADAPTERS: ReadonlySet<string>;
+export declare const ORG_ID_INDEX = "by_clerk_org_id";
+export declare const ORG_ID_FIELD = "clerkOrgId";
+/**
+ * The `client_org_mapping` reads the org-kind ruling admits (see OrgKindReads),
+ * computed over `parsed` so a caller holding the same AST nodes can test
+ * membership. Exported for CR-2 (local-identity.ts), which must not re-derive
+ * R-53's ruling.
+ */
+export declare function conformantMappingReads(parsed: Parsed[]): Set<ts.CallExpression>;
+export interface R53Detail {
+    scan: Scan;
+    doors: number;
+    gates: number;
+}
+export declare function scanR53(files: SrcFile[]): Scan;
+export declare function scanR53Detailed(files: SrcFile[]): R53Detail;
+export declare const R53: Detector;
+export declare const SOURCE_IDENTITY_BY_ID_DETECTORS: SourceDetectorEntry[];
+export {};