reverseport 0.0.0-stage → 1.2.0

package/dist/domain/webBundleAnalysis.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { emptyArraySchema } from "./emptyArraySchema.js";
+import { inspectWebPageWithSourceInputSchema } from "./browserObservation.js";
+import { webTextArtifactSchema } from "./webContentArtifact.js";
+/** Capture-and-analyze input with optional source-map fetching. */
+export const analyzeWebBundleInputSchema = inspectWebPageWithSourceInputSchema.safeExtend({
+    fetch_source_maps: z.boolean().default(false),
+});
+const sourceLocationSchema = z.object({
+    script_key: z.string(),
+    line: z.number().int().min(1).nullable(),
+    column: z.number().int().min(0).nullable(),
+});
+const basisSchema = z.object({
+    script_key: z.string(),
+    artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    line: z.number().int().min(1).nullable(),
+    column: z.number().int().min(0).nullable(),
+    detector: z.string(),
+});
+const findingSchema = z.object({
+    value: z.string(),
+    mechanism: z.string(),
+    location: sourceLocationSchema,
+});
+const originalSourceSchema = z.object({
+    source_index: z.number().int().min(0).optional(),
+    declaration_index: z.number().int().min(0).optional(),
+    source: z.string().nullable(),
+    artifact: webTextArtifactSchema.nullable(),
+});
+const originalModuleEdgeSchema = z.object({
+    from_source: z.string(),
+    kind: z.enum(["static_import", "dynamic_import", "require"]),
+    specifier: z.string(),
+    resolved_source: z.string().nullable(),
+});
+const sourceMapMappingSchema = z.object({
+    source_index: z.number().int().min(0).optional(),
+    declaration_index: z.number().int().min(0).optional(),
+    generated_line: z.number().int().min(1),
+    generated_column: z.number().int().min(0),
+    source: z.string().nullable(),
+    original_line: z.number().int().min(1),
+    original_column: z.number().int().min(0),
+    name: z.string().nullable(),
+});
+const sourceMapContextShape = {
+    script_key: z.string(),
+    declared_url: z.string(),
+    // Older saved observations omit this field; current fetches emit string/null.
+    effective_url: z.string().nullable().optional(),
+};
+const parsedSourceMapShape = {
+    artifact: webTextArtifactSchema,
+    original_sources: z.array(originalSourceSchema),
+    original_module_edges: z.array(originalModuleEdgeSchema),
+    mappings: z.array(sourceMapMappingSchema),
+};
+const sourceMapSchema = z.union([
+    z.object({
+        ...sourceMapContextShape,
+        ...parsedSourceMapShape,
+        status: z.literal("included"),
+        limitation: z.null(),
+    }),
+    z.object({
+        ...sourceMapContextShape,
+        ...parsedSourceMapShape,
+        status: z.literal("partial"),
+        limitation: z.string(),
+    }),
+    z.object({
+        ...sourceMapContextShape,
+        ...parsedSourceMapShape,
+        status: z.enum(["fetch_failed", "invalid", "policy_filtered"]),
+        artifact: z.null(),
+        original_sources: emptyArraySchema,
+        original_module_edges: emptyArraySchema,
+        mappings: emptyArraySchema,
+        limitation: z.string(),
+    }),
+]);
+const webTextArtifactSummarySchema = z.object({
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    bytes: z.number().int().min(0),
+    media_type: z.string().min(1),
+    charset: z.literal("utf-8"),
+    text_available: z.literal(true),
+});
+export const webSourceMapsSchema = z
+    .object({
+    status: z.enum(["not_requested", "included", "partial", "unavailable"]),
+    requested: z.number().int().min(0),
+    processed: z.number().int().min(0),
+    items: z.array(sourceMapSchema),
+    limitation: z.string().min(1).optional(),
+})
+    .superRefine((sourceMaps, context) => {
+    if (sourceMaps.processed > sourceMaps.requested ||
+        sourceMaps.processed !== sourceMaps.items.length)
+        context.addIssue({
+            code: "custom",
+            message: "Source-map coverage counts are inconsistent",
+        });
+    if (sourceMaps.processed < sourceMaps.requested &&
+        sourceMaps.limitation === undefined)
+        context.addIssue({
+            code: "custom",
+            message: "Unprocessed source maps require an explicit coverage limitation",
+            path: ["limitation"],
+        });
+    const statuses = sourceMaps.items.map(({ status }) => status);
+    const retained = statuses.filter((status) => status === "included" || status === "partial").length;
+    const allowedStatuses = sourceMaps.processed < sourceMaps.requested
+        ? retained === 0
+            ? ["unavailable"]
+            : ["partial"]
+        : sourceMaps.items.length === 0
+            ? ["not_requested", "unavailable"]
+            : retained === 0
+                ? ["unavailable"]
+                : retained === sourceMaps.items.length &&
+                    !statuses.includes("partial")
+                    ? ["included"]
+                    : ["partial"];
+    if (!allowedStatuses.includes(sourceMaps.status))
+        context.addIssue({
+            code: "custom",
+            message: "Source-map status contradicts retained coverage",
+            path: ["status"],
+        });
+});
+/** Provider-neutral result of JavaScript bundle reverse engineering. */
+export const webBundleAnalysisSchema = z.object({
+    capture: z.object({
+        target_url: z.string(),
+        scripts_observed: z.number().int().min(0),
+        scripts_analyzed: z.number().int().min(0),
+        source_artifacts: z.array(webTextArtifactSummarySchema),
+    }),
+    observations: z.object({
+        chunks: z.object({
+            nodes: z.array(z.object({
+                script_key: z.string(),
+                url: z.string(),
+                artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+                bytes: z.number().int().min(0),
+            })),
+            edges: z.array(z.object({
+                from_script_key: z.string(),
+                kind: z.enum([
+                    "static_import",
+                    "dynamic_import",
+                    "require",
+                    "worker_import",
+                ]),
+                specifier: z.string(),
+                resolved_url: z.string().nullable(),
+                location: sourceLocationSchema,
+            })),
+        }),
+        routes: z.array(findingSchema),
+        endpoints: z.array(findingSchema),
+        webmcp_declarations: z.array(z.object({
+            name: z.string().nullable(),
+            description: z.string().nullable(),
+            schema_property_names: z.array(z.string()),
+            trust: z.literal("page-declared-untrusted"),
+            location: sourceLocationSchema,
+        })),
+        source_maps: webSourceMapsSchema,
+    }),
+    inferences: z.array(z.object({
+        kind: z.enum(["vendor_fingerprint", "route_framework", "bundle_runtime"]),
+        value: z.string(),
+        confidence: z.enum(["low", "medium", "high"]),
+        basis: z.array(basisSchema).min(1),
+    })),
+    unknowns: z.array(z.object({
+        dimension: z.string(),
+        reason: z.string(),
+        affected_script_keys: z.array(z.string()),
+    })),
+    completeness: z.object({
+        status: z.enum(["complete", "partial"]),
+        parsed_scripts: z.number().int().min(0),
+        parse_failures: z.number().int().min(0),
+        visited_ast_nodes: z.number().int().min(0),
+    }),
+    limitations: z.array(z.string()),
+});

package/dist/domain/webBundleAnalyzer.js

@@ -0,0 +1,15 @@
+import { analyzeScript, emptyAccumulator, isIncludedScript, } from "./webBundleAnalyzerInspection.js";
+import { buildWebBundleAnalysis } from "./webBundleAnalyzerResult.js";
+/** Analyze selected captured JavaScript source without execution. */
+export const analyzeCapturedWebBundle = (inspection, sourceMaps = {
+    status: "not_requested",
+    requested: 0,
+    processed: 0,
+    items: [],
+}) => {
+    const accumulator = emptyAccumulator();
+    const sourceScripts = inspection.scripts.items.filter(isIncludedScript);
+    for (const script of sourceScripts)
+        analyzeScript(script, accumulator);
+    return buildWebBundleAnalysis(inspection, sourceScripts, sourceMaps, accumulator);
+};

package/dist/domain/webBundleAnalyzerAst.js

@@ -0,0 +1,49 @@
+import * as t from "@babel/types";
+import { sanitizeBrowserUrl } from "./browserObservation.js";
+import { semanticStaticPropertyName } from "./javascript/javascriptAstValues.js";
+/** Pick the endpoint argument for common network-call patterns. */
+export const objectValue = (object, name) => {
+    let value;
+    for (const property of object.properties) {
+        if (t.isSpreadElement(property)) {
+            value = undefined;
+            continue;
+        }
+        const key = semanticStaticPropertyName(property.key, property.computed);
+        if (key === "" && !t.isStringLiteral(property.key))
+            value = undefined;
+        else if (key === name)
+            value = t.isObjectProperty(property) ? property.value : undefined;
+    }
+    return value;
+};
+export const objectString = (object, name) => {
+    const value = objectValue(object, name);
+    return t.isStringLiteral(value) ? value.value : undefined;
+};
+/** Whether module syntax supplies a URL location without a package/import-map resolver. */
+export const isUrlLikeModuleSpecifier = (specifier) => specifier.startsWith("/") ||
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    /^[A-Za-z][A-Za-z0-9+.-]*:/u.test(specifier);
+export const resolveSpecifier = (specifier, base) => {
+    try {
+        const resolved = new URL(specifier, base);
+        if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
+            return null;
+        return sanitizeBrowserUrl(resolved.href).url;
+    }
+    catch (cause) {
+        // Unresolvable specifiers are represented by the null return.
+        void cause;
+        return null;
+    }
+};
+export const location = (scriptKey, node) => ({
+    script_key: scriptKey,
+    ...locationFields(node),
+});
+export const locationFields = (node) => ({
+    line: node.loc?.start.line ?? null,
+    column: node.loc?.start.column ?? null,
+});

package/dist/domain/webBundleAnalyzerInspection.js

@@ -0,0 +1,315 @@
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+import { sanitizeEndpointCandidate } from "./browserObservation.js";
+import { compositeKey } from "./unicodeCodePointOrder.js";
+import { completeSemanticSteps, traverseJavaScriptAst, } from "./javascript/javascriptSemanticTraversal.js";
+import { classifyParsedJavaScriptOpenReceivers, classifyParsedJavaScriptRpcClientRootsSteps, } from "./javascript/javascriptSemanticAnalysis.js";
+import { semanticStaticPropertyName } from "./javascript/javascriptAstValues.js";
+import { calleeName, endpointArgument, stringValue, } from "./javascript/javascriptStaticAnalysisHelpers.js";
+import { location, locationFields, objectString, objectValue, resolveSpecifier, isUrlLikeModuleSpecifier, } from "./webBundleAnalyzerAst.js";
+import { createJavaScriptRpcScan } from "./javascript/javascriptRpcEndpoints.js";
+export const analyzeScript = (script, accumulator) => {
+    let file;
+    try {
+        file = parse(script.source.artifact.text, {
+            sourceType: "unambiguous",
+            errorRecovery: true,
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch (cause) {
+        // Unparseable scripts are counted; the failure needs no extra detail.
+        void cause;
+        accumulator.parseFailures += 1;
+        return;
+    }
+    accumulator.parsedScripts += 1;
+    detectVendorFingerprints(script, accumulator);
+    const openReceiverFacts = classifyParsedJavaScriptOpenReceivers(file);
+    const rpc = createJavaScriptRpcScan(script.source.artifact.text, completeSemanticSteps(classifyParsedJavaScriptRpcClientRootsSteps(file)));
+    traverseJavaScriptAst(file, {
+        enter: (node) => {
+            accumulator.visitedNodes += 1;
+            inspectNode(script, node, accumulator, openReceiverFacts);
+            const endpoint = rpc.inspect(node);
+            if (endpoint !== undefined)
+                addFinding({
+                    collection: accumulator.endpoints,
+                    script,
+                    rawValue: endpoint.value,
+                    mechanism: endpoint.mechanism,
+                    node,
+                    accumulator,
+                });
+        },
+    });
+};
+const inspectNode = (script, node, accumulator, openReceiverFacts) => {
+    if ((t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) &&
+        node.source !== undefined)
+        addEdge({
+            script,
+            specifier: node.source.value,
+            kind: "static_import",
+            node,
+            accumulator,
+        });
+    else if (t.isExportNamedDeclaration(node) && node.source != null)
+        addEdge({
+            script,
+            specifier: node.source.value,
+            kind: "static_import",
+            node,
+            accumulator,
+        });
+    else if (t.isImportExpression(node) && t.isStringLiteral(node.source))
+        addEdge({
+            script,
+            specifier: node.source.value,
+            kind: "dynamic_import",
+            node,
+            accumulator,
+        });
+    if (t.isObjectProperty(node))
+        inspectRouteProperty(script, node, accumulator);
+    if (t.isCallExpression(node) ||
+        t.isOptionalCallExpression(node) ||
+        t.isNewExpression(node))
+        inspectCall(script, node, accumulator, openReceiverFacts);
+};
+const inspectCall = (script, node, accumulator, openReceiverFacts) => {
+    const name = calleeName(node.callee);
+    const first = stringValue(node.arguments[0]);
+    if ((name === "require" || name.endsWith(".require")) && first !== undefined)
+        addEdge({
+            script,
+            specifier: first,
+            kind: "require",
+            node,
+            accumulator,
+        });
+    if (name === "importScripts" || name.endsWith(".importScripts"))
+        for (const argument of node.arguments) {
+            const specifier = stringValue(argument);
+            if (specifier === undefined)
+                continue;
+            addEdge({ script, specifier, kind: "worker_import", node, accumulator });
+        }
+    if (routeCallNames.some((candidate) => name === candidate || name.endsWith(`.${candidate}`))) {
+        if (first !== undefined)
+            addFinding({
+                collection: accumulator.routes,
+                script,
+                rawValue: first,
+                mechanism: `call:${name}`,
+                node,
+                accumulator,
+            });
+        addRouteFrameworkInference({
+            script,
+            name,
+            node,
+            accumulator,
+        });
+    }
+    const endpoint = endpointArgument(name, node.arguments, node.callee, openReceiverFacts.get(node.start ?? -1));
+    if (endpoint !== undefined)
+        addFinding({
+            collection: accumulator.endpoints,
+            script,
+            rawValue: endpoint,
+            mechanism: `call:${name}`,
+            node,
+            accumulator,
+        });
+    if ((t.isCallExpression(node) || t.isNewExpression(node)) &&
+        (name.endsWith("modelContext.registerTool") ||
+            name === "modelContext.registerTool"))
+        addWebMcpDeclaration(script, node, accumulator);
+};
+const inspectRouteProperty = (script, node, accumulator) => {
+    const key = semanticStaticPropertyName(node.key, node.computed);
+    if ((key === "path" || key === "route") && t.isStringLiteral(node.value))
+        addFinding({
+            collection: accumulator.routes,
+            script,
+            rawValue: node.value.value,
+            mechanism: `property:${key}`,
+            node,
+            accumulator,
+        });
+};
+const addEdge = (context) => {
+    const key = `edge\0${context.script.script_key}\0${context.kind}\0${context.specifier}`;
+    addUnique(context.accumulator, key, () => context.accumulator.edges.push({
+        from_script_key: context.script.script_key,
+        kind: context.kind,
+        specifier: context.specifier,
+        resolved_url: context.kind === "worker_import" ||
+            isUrlLikeModuleSpecifier(context.specifier)
+            ? resolveSpecifier(context.specifier, context.script.url)
+            : null,
+        location: location(context.script.script_key, context.node),
+    }));
+};
+const addFinding = (context) => {
+    const value = sanitizeEndpointCandidate(context.rawValue);
+    const key = `finding\0${context.mechanism}\0${context.script.script_key}\0${value}`;
+    addUnique(context.accumulator, key, () => context.collection.push({
+        value,
+        mechanism: context.mechanism,
+        location: location(context.script.script_key, context.node),
+    }));
+};
+const addWebMcpDeclaration = (script, node, accumulator) => {
+    const declaration = node.arguments[0];
+    if (!t.isObjectExpression(declaration))
+        return;
+    const name = objectString(declaration, "name");
+    const description = objectString(declaration, "description");
+    const schema = objectValue(declaration, "inputSchema") ??
+        objectValue(declaration, "input_schema");
+    const declaredProperties = t.isObjectExpression(schema)
+        ? objectValue(schema, "properties")
+        : undefined;
+    const propertyObject = t.isObjectExpression(declaredProperties)
+        ? declaredProperties
+        : schema;
+    const schemaPropertyNames = t.isObjectExpression(propertyObject)
+        ? propertyObject.properties.flatMap((property) => t.isObjectProperty(property)
+            ? [
+                semanticStaticPropertyName(property.key, property.computed),
+            ].filter(Boolean)
+            : [])
+        : [];
+    // Property names are a variable-length source-derived list: NUL-joins
+    // would collapse ["a\0b"] with ["a", "b"] and drop a declaration.
+    const key = compositeKey([
+        "webmcp",
+        script.script_key,
+        name ?? "",
+        schemaPropertyNames,
+    ]);
+    addUnique(accumulator, key, () => accumulator.webMcp.push({
+        name: name ?? null,
+        description: description ?? null,
+        schema_property_names: [...new Set(schemaPropertyNames)].sort(),
+        trust: "page-declared-untrusted",
+        location: location(script.script_key, node),
+    }));
+};
+const detectVendorFingerprints = (script, accumulator) => {
+    const text = script.source.artifact.text;
+    for (const detector of vendorDetectors) {
+        if (!detector.patterns.some((pattern) => text.includes(pattern)))
+            continue;
+        const key = `vendor\0${script.script_key}\0${detector.value}`;
+        addUnique(accumulator, key, () => accumulator.inferences.push({
+            kind: detector.kind,
+            value: detector.value,
+            confidence: detector.confidence,
+            basis: [basis(script, detector.detector)],
+        }));
+    }
+};
+const addRouteFrameworkInference = (context) => {
+    const value = context.name.endsWith("useRoutes") ||
+        context.name.endsWith("createBrowserRouter")
+        ? "React Router-compatible route API"
+        : "Generic route registration API";
+    const key = `route-framework\0${context.script.script_key}\0${value}`;
+    addUnique(context.accumulator, key, () => context.accumulator.inferences.push({
+        kind: "route_framework",
+        value,
+        confidence: "medium",
+        basis: [
+            {
+                ...basis(context.script, `call:${context.name}`),
+                ...locationFields(context.node),
+            },
+        ],
+    }));
+};
+const addUnique = (accumulator, key, add) => {
+    if (accumulator.seen.has(key))
+        return;
+    accumulator.seen.add(key);
+    add();
+};
+const basis = (script, detector) => ({
+    script_key: script.script_key,
+    artifact_sha256: script.source.artifact.sha256,
+    line: null,
+    column: null,
+    detector,
+});
+export const emptyAccumulator = () => ({
+    edges: [],
+    routes: [],
+    endpoints: [],
+    webMcp: [],
+    inferences: [],
+    seen: new Set(),
+    visitedNodes: 0,
+    parsedScripts: 0,
+    parseFailures: 0,
+});
+export const isIncludedScript = (script) => script.source.included;
+const routeCallNames = [
+    "route",
+    "addRoute",
+    "useRoutes",
+    "createBrowserRouter",
+    "createHashRouter",
+];
+const vendorDetectors = [
+    {
+        value: "webpack",
+        detector: "webpack-runtime",
+        patterns: ["__webpack_require__"],
+        confidence: "high",
+        kind: "bundle_runtime",
+    },
+    {
+        value: "Vite",
+        detector: "vite-runtime",
+        patterns: ["__vite__", "import.meta.hot"],
+        confidence: "medium",
+        kind: "bundle_runtime",
+    },
+    {
+        value: "React",
+        detector: "react-runtime",
+        patterns: ["__REACT_DEVTOOLS_GLOBAL_HOOK__", "React.createElement"],
+        confidence: "medium",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Vue",
+        detector: "vue-runtime",
+        patterns: ["__VUE__", "createApp("],
+        confidence: "medium",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Next.js",
+        detector: "next-runtime",
+        patterns: ["__NEXT_DATA__", "/_next/"],
+        confidence: "high",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Angular",
+        detector: "angular-runtime",
+        patterns: ["ɵɵdefineComponent"],
+        confidence: "high",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Svelte",
+        detector: "svelte-runtime",
+        patterns: ["svelte/internal"],
+        confidence: "medium",
+        kind: "vendor_fingerprint",
+    },
+];