rea-agents 1.7.0 → 2.1.0

package/dist/application/ElectronBoundaryAnalysis.js

@@ -0,0 +1,112 @@
+import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
+/** Flatten all per-file IPC facts into deterministic application records. */
+export const collectElectronIpcRecords = (analysis) => analysis.files
+    .flatMap(({ file, javascript }) => (javascript?.electron.ipc ?? []).map((finding) => ({
+    key: ipcRecordKey(file.path, finding),
+    file,
+    finding,
+})))
+    .sort((left, right) => compareCodePoints(left.key, right.key));
+/** Match only exact literal channels and retain ambiguous matches separately. */
+export const classifyElectronIpcPairings = (records) => {
+    const handlers = records.filter(isMainHandler);
+    return records.filter(isPairableRendererTransmission).map((transmission) => {
+        const candidates = transmission.finding.channel === null
+            ? []
+            : handlers.filter((handler) => handler.finding.channel === transmission.finding.channel &&
+                compatibleIpcModes(transmission.finding, handler.finding));
+        return {
+            transmission,
+            candidates,
+            status: candidates.length === 1
+                ? "paired"
+                : candidates.length > 1
+                    ? "ambiguous"
+                    : "unpaired",
+        };
+    });
+};
+/** Return only pairings supported by one unique literal main handler. */
+export const unambiguousElectronIpcPairings = (records) => classifyElectronIpcPairings(records).flatMap((state) => {
+    const handler = state.candidates[0];
+    return state.status === "paired" && handler !== undefined
+        ? [{ transmission: state.transmission, handler }]
+        : [];
+});
+/** Summarize static Electron findings without treating gaps as absence. */
+export const summarizeElectronBoundaries = (analysis) => {
+    const files = new Map(analysis.files.map(({ file }) => [file.path, file]));
+    const javascript = analysis.files.flatMap(({ javascript: value }) => value === null ? [] : [value]);
+    const windows = javascript.flatMap(({ electron }) => electron.browser_windows);
+    const bridges = javascript.flatMap(({ electron }) => electron.context_bridge_apis);
+    const validations = javascript.flatMap(({ electron }) => electron.sender_validations);
+    const utilities = analysis.files.flatMap(({ file, javascript: value }) => (value?.electron.utility_processes ?? []).map((finding) => ({
+        file,
+        finding,
+    })));
+    const nativeBindings = analysis.files.flatMap(({ file, javascript: value }) => (value?.electron.native_addon_bindings ?? []).map((finding) => ({
+        file,
+        finding,
+    })));
+    const ipc = collectElectronIpcRecords(analysis);
+    const pairing = classifyElectronIpcPairings(ipc);
+    const literalChannels = new Set(ipc.flatMap(({ finding }) => finding.channel === null ? [] : [finding.channel]));
+    return {
+        browser_windows: windows.length,
+        explicit_web_preferences: windows.reduce((count, window) => count + window.web_preferences.length, 0),
+        preload_entrypoints: windows.filter(({ preload_path: path }) => path !== null).length,
+        context_bridge_apis: bridges.length,
+        exposed_api_members: bridges.reduce((count, bridge) => count + bridge.members.length, 0),
+        ipc: {
+            operations: ipc.length,
+            literal_channels: literalChannels.size,
+            dynamic_channel_operations: ipc.filter(({ finding }) => finding.channel === null).length,
+            renderer_transmissions: ipc.filter(isRendererTransmission).length,
+            renderer_listeners: ipc.filter(({ finding }) => finding.side === "renderer" && finding.mode === "listen").length,
+            main_handlers: ipc.filter(isMainHandler).length,
+            paired_renderer_transmissions: pairing.filter(({ status }) => status === "paired").length,
+            ambiguous_renderer_transmissions: pairing.filter(({ status }) => status === "ambiguous").length,
+            unpaired_literal_renderer_transmissions: pairing.filter(({ status, transmission }) => status === "unpaired" && transmission.finding.channel !== null).length,
+        },
+        sender_validation_observations: validations.length,
+        utility_processes: utilities.length,
+        resolved_utility_entrypoints: utilities.filter(({ file, finding }) => resolvesToFile({
+            file,
+            specifier: finding.module_path,
+            context: finding.module_resolution_context ?? "module-specifier",
+            files,
+        })).length,
+        native_addon_bindings: nativeBindings.length,
+        resolved_native_addon_bindings: nativeBindings.filter(({ file, finding }) => resolvesToFile({
+            file,
+            specifier: finding.specifier,
+            context: "module-specifier",
+            files,
+            kind: "native-addon",
+        })).length,
+    };
+};
+const compatibleIpcModes = (transmission, handler) => transmission.mode === "invoke"
+    ? handler.mode === "handle"
+    : transmission.operation === "send-to-host"
+        ? false
+        : transmission.mode === "send" && handler.mode === "listen";
+const isRendererTransmission = ({ finding }) => finding.side === "renderer" &&
+    (finding.mode === "send" || finding.mode === "invoke");
+const isPairableRendererTransmission = (record) => isRendererTransmission(record) && record.finding.operation !== "send-to-host";
+const isMainHandler = ({ finding }) => finding.side === "main" &&
+    (finding.mode === "listen" || finding.mode === "handle");
+const resolvesToFile = (input) => {
+    if (input.specifier === null)
+        return false;
+    const resolved = resolveArtifactPathByContext({
+        declaredPath: input.specifier,
+        sourcePath: input.file.path,
+        context: input.context,
+        files: input.files,
+    }).resolved_path;
+    return (resolved !== null &&
+        (input.kind === undefined || input.files.get(resolved)?.kind === input.kind));
+};
+const ipcRecordKey = (path, finding) => `${path}\0${String(finding.location.start.line)}:${String(finding.location.start.column)}\0${finding.side}\0${finding.operation}`;
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/application/ElectronBoundaryGraph.js

@@ -0,0 +1,9 @@
+import { addElectronIpcBoundaries } from "./ElectronBoundaryGraphIpc.js";
+import { addElectronNativeBoundaries } from "./ElectronBoundaryGraphNative.js";
+import { addElectronWindowBoundaries } from "./ElectronBoundaryGraphWindows.js";
+/** Add every static Electron process and security-boundary fact to the JAG. */
+export const addElectronBoundaries = (context) => {
+    addElectronWindowBoundaries(context);
+    addElectronIpcBoundaries(context);
+    addElectronNativeBoundaries(context);
+};

package/dist/application/ElectronBoundaryGraphContext.js

@@ -0,0 +1,62 @@
+import { sha256Text } from "../domain/javascriptStaticAnalysisHelpers.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Resolve the file or recovered bundle module that owns one finding. */
+export const electronFindingSourceNode = (context, file, moduleKey) => moduleKey === null
+    ? (context.assetNodes.get(file.path) ?? context.fileNodes.get(file.path))
+    : context.moduleNodes.get(`${file.path}\0${moduleKey}`);
+/** Observation-scoped identity shared safely across different artifact files. */
+export const electronObservationIdentity = (context, scope, key) => ({
+    strategy: "observation-fingerprint",
+    stability: "observation-only",
+    observation_sha256: sha256Text(`${context.snapshot.manifest.root_sha256}\0${scope}\0${key}`),
+    scope: scope.slice(0, 4_096),
+});
+/** Add a direct AST syntax relationship. */
+export const addElectronAstEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: astObservationEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: input.operation,
+            coverage: input.coverage,
+            ...(input.limitations === undefined
+                ? {}
+                : { limitations: input.limitations }),
+        }),
+    });
+};
+/** Add an Electron relationship that static syntax suggests but cannot prove. */
+export const addElectronInferenceEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: staticInferenceEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: input.operation,
+            coverage: input.coverage,
+            ...(input.confidence === undefined
+                ? {}
+                : { confidence: input.confidence }),
+            ...(input.limitations === undefined
+                ? {}
+                : { limitations: input.limitations }),
+        }),
+    });
+};
+/** Deterministic source-range key for artifact-local graph identities. */
+export const electronRangeKey = (range) => `${String(range.start.line)}:${String(range.start.column)}-${String(range.end.line)}:${String(range.end.column)}`;
+/** Test exact source-range containment without assuming runtime reachability. */
+export const electronRangeContains = (outer, inner) => comparePoint(outer.start, inner.start) <= 0 &&
+    comparePoint(outer.end, inner.end) >= 0;
+const comparePoint = (left, right) => left.line === right.line
+    ? left.column - right.column
+    : left.line - right.line;

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.",
+        ],
+    });
+};