@vantageos/backend-doctor 0.1.14 → 0.3.0

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

@@ -1,8 +1,10 @@
 import type { LiveDetector } from "@vantageos/mcp-doctor";
 import type { Detector, DetectorResult, Tree } from "../../engine-types.js";
+import { type GuardHelperKind, type HelperVerdict } from "./guard-helper-flow.js";
 /** The standard both are pinned against (short hash a9d7877b), §15/§18. */
 export declare const IDENTITY_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A715/\u00A718";
 type SrcFile = Tree["files"][number];
+type SrcLine = SrcFile["lines"][number];
 /** A registrable entry — structurally the RegistryEntry the orchestrator spreads
  * into REGISTRY. We do NOT import registry.ts; we mirror its shape so the
  * orchestrator owns the integration (same discipline as security.ts). */
@@ -21,8 +23,62 @@ interface Scan {
     violate: Site[];
     cnj: Site[];
 }
-export declare function scanR6(files: SrcFile[]): Scan;
-export declare function scanR16(files: SrcFile[]): Scan;
+interface Handler {
+    name: string;
+    startN: number;
+    lines: SrcLine[];
+    /** true for an `internalMutation` registration — no client can call it, so
+     * its arguments are supplied by server code, never by a caller (R-6 scope). */
+    internal: boolean;
+}
+/** Split a convex file into its top-level mutation/internalMutation handler
+ * blocks. A block runs from `export const <name> = mutation(` to the next
+ * top-level `export ` (or EOF). Queries/actions are not R-6 write handlers.
+ * Each block records whether it is an `internalMutation` registration. */
+export declare function splitMutationHandlers(f: SrcFile): Handler[];
+export declare function normalizeArgsAccess(raw: string): string;
+/** The taint result of following a boundary local. `matched` is the count of
+ * assignments/declarations of the local actually FOUND in the handler — a
+ * `matched === 0` local is a THIRD state (could-not-judge), never silently
+ * tainted (Eta REVISE #3 defect 2). `cnj` counts RHSes whose own provenance
+ * could not be resolved (a bare-identifier hop that dead-ends or exhausts the
+ * bound) — again could-not-judge, never a guess. */
+export interface LocalTaint {
+    fromArgs: number;
+    fromScope: number;
+    matched: number;
+    cnj: number;
+    /** Present (and > 0) only when a scope-derived assignment is the return of
+     * a function judged in the tree as an identity resolver. */
+    fromResolver?: number;
+}
+/** Follow ONE hop (plus one bounded bare-identifier hop): classify every
+ * assignment/declaration of `local` in the handler as scope-derived, arg-derived,
+ * or could-not-judge. Reads a PLAIN assignment RHS and a DESTRUCTURING RHS with
+ * the same scope test (defect 1). Exposes `matched` so a local with NO resolvable
+ * assignment is a third state, not silently tainted (defect 2). A bare-identifier
+ * RHS (`const t = orgSlug`) is NOT scope evidence on its own — the identifier's
+ * own provenance is resolved one further, bounded, cycle-guarded hop (defect 3);
+ * exhaustion is `cnj`, never a guess. */
+export declare function analyzeLocalTaint(h: Handler, local: string, isResolver?: ResolverTest, principalOf?: PrincipalTest): LocalTaint;
+/** Is `expr` the principal @vantageos/cloud-identity resolved and the door
+ * refused unless ok (package-principal.ts)? Returns the reason, else undefined. */
+export type PrincipalTest = (expr: string) => string | undefined;
+/** Is `name` an identity resolver? `call` is the whole `await name(…)` text,
+ * joined across the lines it spans, so a resolver anchored on one of its call
+ * arguments can read that argument. */
+export type ResolverTest = (name: string, call: string) => boolean;
+export declare const R6_GUARD_HELPERS: Readonly<Record<string, GuardHelperKind>>;
+interface HelperDef {
+    rel: string;
+    n: number;
+    exported: boolean;
+    judgement: HelperVerdict;
+}
+/** Index every definition of an allowlisted helper in the tree. */
+export declare function indexGuardHelpers(files: SrcFile[]): Map<string, HelperDef[]>;
+export declare function scanR6(files: SrcFile[], rootIsConvex?: boolean): Scan;
+export declare function scanR16(files: SrcFile[], rootIsConvex?: boolean): Scan;
 /** A live-probe outcome for R-6: what a boundary-less write call returned. */
 export type LiveWriteOutcome = {
     kind: "refused";