rea-agents 1.6.0 → 2.0.0

package/dist/application/ElectronBoundaryGraphIpc.js

@@ -0,0 +1,242 @@
+import { artifactLocalIdentity, javascriptAnalysisCoverage, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
+import { collectElectronIpcRecords, unambiguousElectronIpcPairings, } from "./ElectronBoundaryAnalysis.js";
+import { addElectronAstEdge, addElectronInferenceEdge, electronFindingSourceNode, electronObservationIdentity, electronRangeContains, electronRangeKey, } from "./ElectronBoundaryGraphContext.js";
+/** Project IPC syntax, handler locations, validations, and exact pairings. */
+export const addElectronIpcBoundaries = (context) => {
+    const state = {
+        context,
+        records: collectElectronIpcRecords(context.analysis),
+        channels: new Map(),
+        handlers: new Map(),
+        sources: new Map(),
+    };
+    for (const record of state.records)
+        addIpcRecord(state, record);
+    addValidationObservations(state);
+    addLiteralPairings(state);
+};
+const addIpcRecord = (state, record) => {
+    const { context } = state;
+    const coverage = coverageFor(context, record.file);
+    if (coverage === undefined)
+        return;
+    const source = electronFindingSourceNode(context, record.file, record.finding.module_key);
+    if (source === undefined)
+        return;
+    state.sources.set(record.key, source);
+    const channel = addChannelNode(context, record, coverage);
+    state.channels.set(record.key, channel);
+    if (record.finding.mode === "listen" || record.finding.mode === "handle") {
+        const handler = addHandlerNode({
+            context,
+            record,
+            source,
+            channel,
+            coverage,
+        });
+        state.handlers.set(record.key, handler);
+        return;
+    }
+    addElectronInferenceEdge(context, {
+        source,
+        target: channel,
+        file: record.file,
+        range: record.finding.location,
+        coverage,
+        relation: record.finding.mode === "invoke" ? "invokes" : "sends",
+        operation: "map-ipc-transmission",
+        properties: {
+            side: record.finding.side,
+            operation: record.finding.operation,
+            channel: record.finding.channel,
+            channel_expression: record.finding.channel_expression,
+            resolution: record.finding.channel === null ? "dynamic" : "literal",
+        },
+    });
+};
+const addChannelNode = (context, record, coverage) => {
+    const { finding, file } = record;
+    const identityKey = finding.channel === null
+        ? `dynamic:${record.key}`
+        : `literal:${finding.channel}`;
+    return context.accumulator.addNode({
+        kind: "ipc-channel",
+        identity: electronObservationIdentity(context, "electron-ipc-channel", identityKey),
+        observations: [
+            {
+                label: finding.channel ?? finding.channel_expression,
+                properties: {
+                    side: finding.side,
+                    operation: finding.operation,
+                    mode: finding.mode,
+                    channel: finding.channel,
+                    channel_expression: finding.channel_expression,
+                    resolution: finding.channel === null ? "dynamic" : "literal",
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: finding.location,
+                    operation: "observe-ipc-channel-expression",
+                    coverage,
+                    limitations: finding.channel === null
+                        ? [
+                            "The channel expression is dynamic; its runtime value and pairings remain unknown.",
+                        ]
+                        : [],
+                }),
+            },
+        ],
+    });
+};
+const addHandlerNode = (input) => {
+    const { context, record, source, channel, coverage } = input;
+    const { finding, file } = record;
+    const handlerRange = finding.handler_location ?? finding.location;
+    const handler = context.accumulator.addNode({
+        kind: "ipc-handler",
+        identity: artifactLocalIdentity(file.sha256, "electron-ipc-handler", `${finding.side}:${finding.operation}:${finding.channel ?? finding.channel_expression ?? "[missing]"}:${electronRangeKey(handlerRange)}`),
+        observations: [
+            {
+                label: finding.channel,
+                properties: {
+                    side: finding.side,
+                    operation: finding.operation,
+                    mode: finding.mode,
+                    channel: finding.channel,
+                    channel_expression: finding.channel_expression,
+                    handler_kind: finding.handler_kind,
+                    handler_location: finding.handler_location,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: handlerRange,
+                    operation: "observe-ipc-handler",
+                    coverage,
+                }),
+            },
+        ],
+    });
+    addElectronAstEdge(context, {
+        source,
+        target: handler,
+        file,
+        range: handlerRange,
+        coverage,
+        relation: "contains",
+        operation: "locate-ipc-handler",
+        properties: { side: finding.side, operation: finding.operation },
+    });
+    addElectronInferenceEdge(context, {
+        source: handler,
+        target: channel,
+        file,
+        range: finding.location,
+        coverage,
+        relation: "handles",
+        operation: "map-ipc-handler-registration",
+        properties: {
+            channel: finding.channel,
+            channel_expression: finding.channel_expression,
+            resolution: finding.channel === null ? "dynamic" : "literal",
+        },
+    });
+    return handler;
+};
+const addLiteralPairings = (state) => {
+    for (const pairing of unambiguousElectronIpcPairings(state.records)) {
+        const source = state.sources.get(pairing.transmission.key);
+        const handler = state.handlers.get(pairing.handler.key);
+        const coverage = coverageFor(state.context, pairing.transmission.file);
+        if (source === undefined || handler === undefined || coverage === undefined)
+            continue;
+        addElectronInferenceEdge(state.context, {
+            source,
+            target: handler,
+            file: pairing.transmission.file,
+            range: pairing.transmission.finding.location,
+            coverage,
+            relation: pairing.transmission.finding.mode === "invoke" ? "invokes" : "sends",
+            operation: "pair-ipc-literal-channel",
+            properties: {
+                channel: pairing.transmission.finding.channel,
+                pairing_basis: "unique-exact-literal-channel",
+                handler_path: pairing.handler.file.path,
+                handler_operation: pairing.handler.finding.operation,
+            },
+            limitations: [
+                "Literal channel equality does not prove that the handler is registered or reachable at runtime.",
+            ],
+        });
+    }
+};
+const addValidationObservations = (state) => {
+    for (const analyzed of state.context.analysis.files) {
+        const { file, javascript } = analyzed;
+        if (javascript === null)
+            continue;
+        const coverage = javascriptAnalysisCoverage(javascript, state.context.input);
+        for (const validation of javascript.electron.sender_validations) {
+            const handlerRecord = containingHandler(state.records, file, validation);
+            const target = handlerRecord === undefined
+                ? electronFindingSourceNode(state.context, file, validation.module_key)
+                : state.handlers.get(handlerRecord.key);
+            if (target !== undefined)
+                addValidationObservation({
+                    context: state.context,
+                    file,
+                    validation,
+                    target,
+                    coverage,
+                });
+        }
+    }
+};
+const addValidationObservation = (input) => {
+    const { context, file, validation, target, coverage } = input;
+    context.accumulator.addNode({
+        kind: target.kind,
+        identity: target.identity,
+        observations: [
+            {
+                label: `${validation.subject} validation candidate`,
+                properties: {
+                    fact_kind: "sender-validation-candidate",
+                    subject: validation.subject,
+                    mechanism: validation.mechanism,
+                    expected: validation.expected,
+                    enforcement: validation.enforcement,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: validation.location,
+                    operation: "observe-ipc-sender-validation-candidate",
+                    coverage,
+                    limitations: [
+                        "A comparison or string check is visible, but static syntax alone does not prove rejection, ordering, or complete sender validation.",
+                    ],
+                }),
+            },
+        ],
+    });
+};
+const containingHandler = (records, file, validation) => records
+    .filter((record) => record.file.path === file.path &&
+    record.finding.handler_location !== null &&
+    electronRangeContains(record.finding.handler_location, validation.location))
+    .sort((left, right) => rangeMagnitude(left.finding.handler_location) -
+    rangeMagnitude(right.finding.handler_location))[0];
+const rangeMagnitude = (range) => range === null
+    ? Number.MAX_SAFE_INTEGER
+    : (range.end.line - range.start.line) * 1_000_000 +
+        range.end.column -
+        range.start.column;
+const coverageFor = (context, file) => {
+    const javascript = context.analysis.files.find(({ file: candidate }) => candidate.path === file.path)?.javascript;
+    return javascript === null || javascript === undefined
+        ? undefined
+        : javascriptAnalysisCoverage(javascript, context.input);
+};

package/dist/application/ElectronBoundaryGraphNative.js

@@ -0,0 +1,86 @@
+import { javascriptAnalysisCoverage, resolveArtifactPath, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
+import { addElectronInferenceEdge, electronFindingSourceNode, electronObservationIdentity, electronRangeKey, } from "./ElectronBoundaryGraphContext.js";
+/** Project JavaScript-requested native addon binding and re-export surfaces. */
+export const addElectronNativeBoundaries = (context) => {
+    for (const analyzed of context.analysis.files) {
+        const { file, javascript } = analyzed;
+        if (javascript === null)
+            continue;
+        const coverage = javascriptAnalysisCoverage(javascript, context.input);
+        for (const value of javascript.electron.native_addon_bindings)
+            addNativeBinding({ context, file, value, coverage });
+    }
+};
+const addNativeBinding = (input) => {
+    const { context, file, value, coverage } = input;
+    const source = electronFindingSourceNode(context, file, value.module_key);
+    if (source === undefined)
+        return;
+    const resolved = resolveArtifactPath(value.specifier, file.path, context.filesByPath);
+    const addon = resolved === null ? undefined : context.fileNodes.get(resolved);
+    const binding = context.accumulator.addNode({
+        kind: "native-export",
+        identity: electronObservationIdentity(context, "javascript-requested-native-export", `${file.path}:${value.specifier}:${value.binding_kind}:${value.members.join("\0")}:${electronRangeKey(value.location)}`),
+        observations: [
+            {
+                label: value.members.join(", "),
+                properties: {
+                    specifier: value.specifier,
+                    binding_kind: value.binding_kind,
+                    requested_members: value.members,
+                    members_truncated: value.members_truncated,
+                    resolved_path: resolved,
+                    native_export_verification: "not-performed",
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: value.location,
+                    operation: "observe-native-addon-binding",
+                    coverage,
+                    limitations: [
+                        "JavaScript syntax identifies requested member names; it does not prove that the native binary exports or implements them.",
+                    ],
+                }),
+            },
+        ],
+    });
+    addElectronInferenceEdge(context, {
+        source,
+        target: binding,
+        file,
+        range: value.location,
+        coverage,
+        relation: value.binding_kind === "re-export" ? "exposes" : "imports",
+        operation: "map-native-addon-binding",
+        properties: {
+            specifier: value.specifier,
+            binding_kind: value.binding_kind,
+            requested_members: value.members,
+        },
+        limitations: [
+            "Requested JavaScript members are not verified native exports.",
+        ],
+    });
+    if (addon === undefined || resolved === null)
+        return;
+    addElectronInferenceEdge(context, {
+        source: addon,
+        target: binding,
+        file,
+        range: value.location,
+        coverage,
+        relation: "exposes",
+        operation: "associate-native-addon-requested-exports",
+        properties: {
+            resolved_path: resolved,
+            requested_members: value.members,
+            verified: false,
+        },
+        confidence: "medium",
+        limitations: [
+            "The .node artifact path is resolved, but requested JavaScript members have not been verified against native symbols.",
+        ],
+    });
+};

package/dist/application/ElectronBoundaryGraphWindows.js

@@ -0,0 +1,199 @@
+import { artifactLocalIdentity, createElectronRoleNode, javascriptAnalysisCoverage, linkElectronRoleToAsset, resolveArtifactPath, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
+import { addElectronAstEdge, addElectronInferenceEdge, electronFindingSourceNode, electronRangeKey, } from "./ElectronBoundaryGraphContext.js";
+/** Project BrowserWindow, contextBridge, preload, and utility-process facts. */
+export const addElectronWindowBoundaries = (context) => {
+    for (const analyzed of context.analysis.files) {
+        const { file, javascript } = analyzed;
+        if (javascript === null)
+            continue;
+        const coverage = javascriptAnalysisCoverage(javascript, context.input);
+        for (const value of javascript.electron.browser_windows) {
+            const source = electronFindingSourceNode(context, file, value.module_key);
+            if (source !== undefined)
+                addBrowserWindow({ context, file, source, value, coverage });
+        }
+        for (const value of javascript.electron.context_bridge_apis) {
+            const source = electronFindingSourceNode(context, file, value.module_key);
+            if (source !== undefined)
+                addContextBridge({ context, file, source, value, coverage });
+        }
+        for (const value of javascript.electron.utility_processes) {
+            const source = electronFindingSourceNode(context, file, value.module_key);
+            if (source !== undefined)
+                addUtilityProcess({ context, file, source, value, coverage });
+        }
+    }
+};
+const addBrowserWindow = (input) => {
+    const { context, file, value, coverage } = input;
+    const window = context.accumulator.addNode({
+        kind: "browser-window",
+        identity: artifactLocalIdentity(file.sha256, "electron-browser-window", electronRangeKey(value.location)),
+        observations: [
+            {
+                label: `BrowserWindow@${electronRangeKey(value.location)}`,
+                properties: {
+                    source_path: file.path,
+                    options_status: value.options_status,
+                    web_preferences_status: value.web_preferences_status,
+                    web_preferences: value.web_preferences,
+                    omitted_web_preferences: value.omitted_web_preferences,
+                    preload_path: value.preload_path,
+                    absence_means_default: false,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: value.location,
+                    operation: "observe-browser-window-construction",
+                    coverage,
+                    limitations: [
+                        "Only explicitly present webPreferences are reported; omitted properties are not interpreted as Electron defaults.",
+                    ],
+                }),
+            },
+        ],
+    });
+    addElectronAstEdge(context, {
+        source: input.source,
+        target: window,
+        file,
+        range: value.location,
+        coverage,
+        relation: "contains",
+        operation: "locate-browser-window-construction",
+        properties: { source_path: file.path },
+    });
+    addWindowPreload(input, window);
+};
+const addWindowPreload = (input, window) => {
+    const declared = input.value.preload_path;
+    if (declared === null)
+        return;
+    const resolved = resolveArtifactPath(declared, input.file.path, input.context.filesByPath);
+    const role = createElectronRoleNode(input.context, {
+        kind: "electron-preload",
+        anchor: input.file,
+        declaredPath: declared,
+        resolvedPath: resolved,
+        mechanism: "BrowserWindow:webPreferences.preload",
+        range: input.value.location,
+        coverage: input.coverage,
+    });
+    addElectronInferenceEdge(input.context, {
+        source: window,
+        target: role,
+        file: input.file,
+        range: input.value.location,
+        coverage: input.coverage,
+        relation: "loads",
+        operation: "associate-browser-window-preload",
+        properties: { declared_path: declared, resolved_path: resolved },
+    });
+    linkElectronRoleToAsset(input.context, {
+        role,
+        anchor: input.file,
+        path: resolved,
+        range: input.value.location,
+        coverage: input.coverage,
+    });
+};
+const addContextBridge = (input) => {
+    const { context, file, value, coverage } = input;
+    const bridge = context.accumulator.addNode({
+        kind: "context-bridge-api",
+        identity: artifactLocalIdentity(file.sha256, "electron-context-bridge", `${value.world}:${value.api_key ?? value.api_key_expression ?? "[missing]"}:${electronRangeKey(value.location)}`),
+        observations: [
+            {
+                label: value.api_key,
+                properties: {
+                    world: value.world,
+                    world_id: value.world_id,
+                    api_key: value.api_key,
+                    api_key_expression: value.api_key_expression,
+                    api_status: value.api_status,
+                    members: value.members,
+                    unknown_members: value.unknown_members,
+                    omitted_members: value.omitted_members,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: value.location,
+                    operation: "observe-context-bridge-api",
+                    coverage,
+                }),
+            },
+        ],
+    });
+    addElectronInferenceEdge(context, {
+        source: input.source,
+        target: bridge,
+        file,
+        range: value.location,
+        coverage,
+        relation: "exposes",
+        operation: "map-context-bridge-exposure",
+        properties: {
+            world: value.world,
+            api_key: value.api_key,
+            resolution: value.api_key === null ? "dynamic" : "literal",
+        },
+    });
+};
+const addUtilityProcess = (input) => {
+    const { context, file, value, coverage } = input;
+    const utility = context.accumulator.addNode({
+        kind: "electron-utility",
+        identity: artifactLocalIdentity(file.sha256, "electron-utility-process", `${value.module_path ?? value.module_expression ?? "[missing]"}:${electronRangeKey(value.location)}`),
+        observations: [
+            {
+                label: value.service_name ?? value.module_path,
+                properties: {
+                    module_path: value.module_path,
+                    module_expression: value.module_expression,
+                    service_name: value.service_name,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: value.location,
+                    operation: "observe-utility-process-fork",
+                    coverage,
+                }),
+            },
+        ],
+    });
+    addElectronInferenceEdge(context, {
+        source: input.source,
+        target: utility,
+        file,
+        range: value.location,
+        coverage,
+        relation: "loads",
+        operation: "map-utility-process-launch",
+        properties: {
+            declared_path: value.module_path,
+            expression: value.module_expression,
+        },
+    });
+    if (value.module_path === null)
+        return;
+    const resolved = resolveArtifactPath(value.module_path, file.path, context.filesByPath);
+    const target = resolved === null
+        ? undefined
+        : (context.assetNodes.get(resolved) ?? context.fileNodes.get(resolved));
+    if (target === undefined)
+        return;
+    addElectronInferenceEdge(context, {
+        source: utility,
+        target,
+        file,
+        range: value.location,
+        coverage,
+        relation: "maps_to",
+        operation: "resolve-utility-process-entrypoint",
+        properties: { resolved_path: resolved },
+    });
+};

package/dist/application/EnhancedTools.js

@@ -4,72 +4,97 @@ import { addressDistance, parseDocuments, parseFunctionDossier, parseAddressedPa
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, discoverSwiftClasses, } from "../domain/symbolAnalysis.js";
 /**
- * Composes official Hopper operations into bounded reverse-engineering tools.
- * Inputs are parsed again at this application boundary even though MCP normally
- * validates them, allowing direct callers to use the same service safely.
+ * Composes direct provider operations into bounded reverse-engineering tools.
+ * Direct callers use `execute`; adapters that own validation use
+ * `executeValidated` so an MCP input is parsed exactly once.
  */
 export class EnhancedTools {
     analysis;
     constructor(analysis) {
         this.analysis = analysis;
     }
-    /** Parse inputs again at the direct-call boundary, then dispatch exhaustively. */
+    /** Parse an untrusted direct-call input once, then dispatch exhaustively. */
     execute(name, input, signal) {
         switch (name) {
             case "swift_classes": {
                 const parsed = enhancedInputSchemas.swift_classes.safeParse(input);
                 return parsed.success
-                    ? this.#swiftClasses(parsed.data.pattern, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "get_objc_classes": {
                 const parsed = enhancedInputSchemas.get_objc_classes.safeParse(input);
                 return parsed.success
-                    ? this.#objcClasses(parsed.data.pattern, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "get_objc_protocols":
-                return this.#objcProtocols(signal);
+                return this.executeValidated({ name, input: {} }, signal);
             case "batch_decompile": {
                 const parsed = enhancedInputSchemas.batch_decompile.safeParse(input);
                 return parsed.success
-                    ? this.#batchDecompile(parsed.data.addresses, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "get_call_graph": {
                 const parsed = enhancedInputSchemas.get_call_graph.safeParse(input);
                 return parsed.success
-                    ? this.#callGraph(parsed.data, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "analyze_swift_types":
-                return this.#analyzeSwiftTypes(signal);
+                return this.executeValidated({ name, input: {} }, signal);
             case "find_xrefs_to_name": {
                 const parsed = enhancedInputSchemas.find_xrefs_to_name.safeParse(input);
                 return parsed.success
-                    ? this.#findXrefs(parsed.data.name, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "binary_overview": {
                 const parsed = enhancedInputSchemas.binary_overview.safeParse(input);
                 return parsed.success
-                    ? this.#binaryOverview(parsed.data, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "analyze_function": {
                 const parsed = enhancedInputSchemas.analyze_function.safeParse(input);
                 return parsed.success
-                    ? this.#analyzeFunction(parsed.data, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
             case "trace_feature": {
                 const parsed = enhancedInputSchemas.trace_feature.safeParse(input);
                 return parsed.success
-                    ? this.#traceFeature(parsed.data, signal)
+                    ? this.executeValidated({ name, input: parsed.data }, signal)
                     : invalidInput(name, parsed.error);
             }
         }
     }
+    /** Dispatch input already parsed by a trusted adapter boundary. */
+    executeValidated(call, signal) {
+        switch (call.name) {
+            case "swift_classes":
+                return this.#swiftClasses(call.input.pattern, signal);
+            case "get_objc_classes":
+                return this.#objcClasses(call.input.pattern, signal);
+            case "get_objc_protocols":
+                return this.#objcProtocols(signal);
+            case "batch_decompile":
+                return this.#batchDecompile(call.input.addresses, signal);
+            case "get_call_graph":
+                return this.#callGraph(call.input, signal);
+            case "analyze_swift_types":
+                return this.#analyzeSwiftTypes(signal);
+            case "find_xrefs_to_name":
+                return this.#findXrefs(call.input.name, signal);
+            case "binary_overview":
+                return this.#binaryOverview(call.input, signal);
+            case "analyze_function":
+                return this.#analyzeFunction(call.input, signal);
+            case "trace_feature":
+                return this.#traceFeature(call.input, signal);
+        }
+    }
     async #analyzeFunction(input, signal) {
         const result = await this.#call("analyze_function", input, signal);
         return result.ok ? parseFunctionDossier(result.value) : result;