@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/taint/project.d.ts

@@ -0,0 +1,172 @@
+/**
+ * THE PROJECT INDEX  (cross-file resolution)
+ * ==========================================
+ *
+ * Up to now the tracer could follow a value anywhere inside one file and no
+ * further. `helper(dirty)` where `helper` lives in `./helpers.js` was the end of
+ * the road, and on real code that is where most of the road is: applications put
+ * their database access in `db.js`, their escaping in `util/html.py`, their
+ * command runners in `Shell.java`.
+ *
+ * This module answers one question: **"file F calls a function named N - which
+ * file, if any, is that?"**
+ *
+ * THE RULE IT PLAYS BY: answer only when the answer is unambiguous.
+ *
+ * If two imported modules both define `sanitize`, we say nothing and record
+ * that we declined. Picking one at random would let the tool print a
+ * step-by-step "proof" through a function that never runs - which is worse than
+ * printing nothing, because it looks like evidence. The count of declined
+ * resolutions is reported in every scan.
+ *
+ * HOW IMPORTS ARE FOUND, per language:
+ *
+ *   JS/TS   `import x from './a'` and `require('./a')`, resolved relative to the
+ *           importing file, trying the usual extensions and `/index`.
+ *   Python  `from .a import x`, `from pkg.a import x`, `import pkg.a` - resolved
+ *           against the files actually present in the scan.
+ *   Java    `import com.x.Bar;` resolves to a file named `Bar.java`, PLUS every
+ *           file in the same directory, because Java classes in the same
+ *           package see each other with no import at all.
+ *   Go      every file in the same directory, because that is one package. Go
+ *           imports name packages rather than files, and resolving those needs
+ *           module metadata we do not read.
+ *
+ * WHAT IT DOES NOT DO, stated here and in the scan report:
+ *   - It does not check that the function is actually EXPORTED. A module-private
+ *     helper with the same name as an exported one could be entered.
+ *   - It does not follow re-exports (`export * from './a'`).
+ *   - It does not resolve node_modules, third-party packages, or aliases from
+ *     tsconfig `paths` / webpack config.
+ *   - Dynamic imports and computed requires are invisible.
+ */
+import type { Node } from 'web-tree-sitter';
+import type { LanguageId } from '../parse/languages.js';
+import { type TreeStore } from '../parse/tree-store.js';
+import { type CrossFileResolver } from './tracer.js';
+/**
+ * A function recorded as COORDINATES rather than as a syntax node.
+ *
+ * This is the change that lets the memory ceiling go away. The index used to
+ * hold a live Node for every function body in the project, and a Node keeps its
+ * whole tree alive - so indexing the project pinned every tree in it, whether
+ * or not anything ever traced into them. Holding two integers and a string
+ * instead lets the trees be freed, at the cost of parsing a file again on the
+ * rare occasion the tracer actually descends into it.
+ *
+ * bodyType is recorded alongside the offsets because a byte range alone is not
+ * always unique: a node can share its exact extent with its parent. The type is
+ * what tells them apart, and a lookup that cannot match both is refused.
+ */
+export interface IndexedFunction {
+    readonly name: string;
+    readonly params: readonly string[];
+    /** The argument range the function accepts - see LocalFunction.minArgs. */
+    readonly minArgs?: number | undefined;
+    readonly maxArgs?: number | undefined;
+    readonly bodyStart: number;
+    readonly bodyEnd: number;
+    readonly bodyType: string;
+}
+/**
+ * What buildProjectIndex needs from each file. Everything here is extracted
+ * while the file's tree is hot during the first pass, so the index itself never
+ * touches a tree and never holds one.
+ */
+export interface IndexedFileInput {
+    readonly path: string;
+    readonly language: LanguageId;
+    readonly functions: ReadonlyMap<string, IndexedFunction>;
+    /** Raw module specifiers, already read out of the tree. */
+    readonly importSpecifiers: readonly string[];
+    /** Java only - see javaTypeFacts(). */
+    readonly javaTypes?: JavaTypeFacts | undefined;
+}
+/**
+ * What a Java file says about the types it declares and names, read from the
+ * top level of its tree in the first pass. staticMethod() below needs these to
+ * answer "which class does `Utils` mean here?" without holding the tree.
+ */
+export interface JavaTypeFacts {
+    /** From `package a.b;` - the empty string for the unnamed package. */
+    readonly packageName: string;
+    /** Top-level type declarations of every kind - class, interface, enum, record, annotation. */
+    readonly types: readonly {
+        readonly name: string;
+        readonly kind: string;
+    }[];
+    /** `import a.b.C;` as `a.b.C`. Not `import a.b.*;`, not `import static`. */
+    readonly singleTypeImports: readonly string[];
+    /** The last name of each `import static a.b.C.m;` - a member that is then in scope by that name. */
+    readonly staticImports: readonly string[];
+    /** Whether any `import static a.b.C.*;` brings in members nobody here can list. */
+    readonly staticOnDemand: boolean;
+    /** Every type declared anywhere in the file, nested ones included. */
+    readonly allTypeNames: readonly string[];
+}
+export declare function javaTypeFacts(root: Node): JavaTypeFacts;
+/** Turn a file's functions into coordinates, using the tracer's own definition. */
+export declare function indexFunctions(root: Node, language: LanguageId): Map<string, IndexedFunction>;
+export interface ProjectIndexStats {
+    readonly filesIndexed: number;
+    readonly functionsIndexed: number;
+    readonly importEdges: number;
+    /**
+     * Import statements we READ but could not point at a file in this scan.
+     *
+     * Counted because it is the difference between "this code imports nothing"
+     * and "this code imports 117 things and you gave me none of them". A beginner
+     * scanned juice-shop's server.ts on its own, got zero findings, and concluded
+     * the tool was broken. It was not: server.ts is a wiring file whose 117
+     * imports all pointed outside the scan, so every trace stopped at the first
+     * module boundary. The same repository's routes/ directory produces seven
+     * findings, two of them flow-verified.
+     *
+     * The report had the evidence - importEdges was 0 - and never said what it
+     * meant. An undeclared blind spot is exactly what this project refuses to
+     * ship, so it is declared now.
+     */
+    readonly importsUnresolved: number;
+    /** Times a cross-file call WAS followed. */
+    readonly resolved: number;
+    /** Times several files defined the name and we refused to choose. */
+    readonly ambiguous: number;
+    /**
+     * Times a function was found in the index but could not be located again in
+     * the re-parsed tree, and the resolution was declined rather than guessed.
+     *
+     * This should be zero forever: the parse is deterministic, so a node recorded
+     * at bytes 400-980 as a `block` is a `block` at bytes 400-980 every time the
+     * same file is parsed with the same grammar. It is counted anyway, because
+     * "should be impossible" is how a tool ends up tracing into the wrong
+     * function and printing a confident proof of it.
+     */
+    readonly relocationsFailed: number;
+}
+export interface ProjectIndex extends CrossFileResolver {
+    readonly stats: () => ProjectIndexStats;
+    /**
+     * The one static method `receiver.method(...)` can run, from a Java file -
+     * or null whenever that is in any doubt. See the note in the body.
+     */
+    readonly staticMethod: (fromPath: string, receiver: string, method: string, 
+    /** Simple names of the types the call sits inside inherit from - see strings.ts. */
+    supertypes?: readonly string[], 
+    /** The caller created the object with `new X(...)`, so an instance method is exact too. */
+    allowInstance?: boolean) => {
+        readonly path: string;
+        readonly method: Node;
+    } | null;
+    /** Is a Java type of this simple name - top-level or nested - declared anywhere in the scan? */
+    readonly javaTypeInScan: (simpleName: string) => boolean;
+}
+/** The raw module specifiers this file mentions, e.g. "./db", "app.helpers". */
+export declare function importSpecifiers(root: Node, language: LanguageId): string[];
+/**
+ * @param files  one record per scanned file, with functions and import
+ *               specifiers ALREADY extracted from its tree.
+ * @param store  where trees come from. Only touched when a resolution actually
+ *               succeeds, which on real projects is a small fraction of files -
+ *               the index itself is built without a single tree in hand.
+ */
+export declare function buildProjectIndex(files: readonly IndexedFileInput[], store: TreeStore): ProjectIndex;