Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / javascript-and-desktop-reconstruction

JavaScript and desktop reconstruction

REA builds a bounded model of a JavaScript or Electron application from shipped files and selected runtime observations. It joins static structure with Electron boundary facts and runtime links. The retained result supports tracing and reconstruction without treating a possible relation as proof of execution.

System scope

This area answers two linked questions: what the application contains and how observed runtime entities may relate to that content. Static analysis reads an ASAR file or directory without running its code. Runtime services add bounded Electron observations. Later workflows use the retained results for queries and comparison.

ConcernSystem aimMain result
Static reconstructionModel files, modules, packages, routes, workers, and desktop boundariesJavaScript Application Graph and semantic graph
Worker executionKeep source parsing isolated and boundedStatic facts, semantic facts, or explicit partial coverage
Electron protocol analysisRelate renderer, preload, main, utility, and native boundariesIPC, bridge, protocol, dynamic-code, and call-path findings
Electron observationList targets or inspect one selected page through a providerValidated Electron Evidence or partial observation
Runtime reconciliationCompare captured targets, frames, scripts, and workers with static layersMatched, ambiguous, unmatched, or unknown relations
Semantic queriesFollow selected graph relations from an authenticated seedA bounded trace with coverage and unknowns
Retained application factsPreserve source identity and support for later workImmutable Evidence with links to its sources

The wider artifact route is described in artifact and application analysis. Application reconstruction covers the broader reconstruction and coverage model. Desktop application environments describes the wider desktop runtime context. Binary diagnostics and comparison covers native binary questions.

This diagram shows how shipped files and bounded runtime observations meet in the same evidence model.

flowchart LR
    A[ASAR or application directory] --> B[Static reconstruction]
    B --> C[Application graph]
    B --> D[Semantic graph]
    E[Electron target or page observation] --> F[Electron Evidence]
    C --> G[Runtime reconciliation]
    F --> G
    G --> H[Reconciled application graph]
    D --> I[Semantic query]
    I --> J[Linked result]
    C --> K[Retained application Evidence]
    D --> K
    H --> K

References: src/…/JavaScriptArtifactGraphBuilder.ts• L64-85 src/…/JavaScriptSemanticGraphBuilder.ts• L190-197

Static reconstruction

Static reconstruction resolves one local directory or .asar file and builds two related views. The application graph describes packaged entities and broad relationships. The semantic graph describes source-level values, calls, ownership, influence, and unresolved frontiers. The analysis reads shipped text as inert input.

Artifact graph

The artifact graph starts from stable inventory facts and keeps path ownership separate from equal file content. It can describe modules, chunks, workers, package roles, routes, source-map links, and Electron boundary findings. A selected source can be unavailable, skipped, or partly parsed. Those states remain visible so missing facts do not become claims of absence.

Graph assembly merges observations for the same retained node and removes repeated observation identities. It keeps distinct node identities distinct even when their content is equal. Loader conditions can qualify matching static evidence when the condition belongs to the same source artifact.

Reconstruction admits raw file observations before it expands them into package, module, relationship, and boundary nodes. A projection failure can leave the source fact visible while preventing unsupported relationships. Coverage also records unread files, invalid data, partial parsing, resource limits, and omitted inline scripts.

Analysis offers application JavaScript before dependency JavaScript when no explicit source paths are selected. Declared JavaScript preload paths receive a separate discovery pass. The pass resolves declared preload identities and uses the preload's CommonJS loader scope when required. It does not infer a preload from renderer API text. Discovery gaps remain in the final limitations.

Module and runtime path resolution follows the declared loader context. It keeps import, CommonJS, package entry points, HTML, URL, and runtime-path meanings separate. Incomplete inventory can change a missing result from not-found to unavailable. Unsafe path syntax remains distinct from an unresolved path.

The reconstruction result carries:

  • The root artifact digest and inventory identity.
  • The application graph and its coverage limits.
  • The semantic graph and its unresolved facts.
  • Route inventory and an Electron boundary summary when available.
  • Parse, source-selection, resource, and projection limitations.

References: src/…/JavaScriptArtifactAnalysis.ts• L72-133 src/…/JavaScriptArtifactAnalysis.ts• L316-385 src/…/JavaScriptArtifactGraphAccumulator.ts• L20-133 src/…/JavaScriptArtifactGraphBuilder.ts• L205-277 src/…/JavaScriptArtifactGraphStructure.ts• L141-363

Worker execution

JavaScript source analysis runs in an owned worker so parsing, Electron call-path work, and semantic projection stay isolated from the main service. The parent sends source identity and bounded source text to the worker. The same boundary serves preload discovery and normal analysis.

The worker can report static facts before it offers semantic results. The parent can retain the static checkpoint when semantic work exceeds capacity or the worker stops. Separate total and per-file limits cover memory, time, checkpoints, results, semantic nodes, unknowns, and transferred records. A limit therefore produces partial facts and a stated reason instead of a silently shortened graph.

Semantic projection gives Electron boundary paths priority when capacity is tight. Each source file receives the smaller of its per-file capacity and the remaining application capacity. Relations are emitted only when their endpoint nodes remain in the graph. Unknown omissions retain counts by relation family and reason. Cancellation stops active call-path work at safe checkpoints, and a retry starts with fresh analysis state so a partial attempt does not duplicate unknown counts. Later queries can therefore distinguish an examined graph from a complete graph.

References: src/…/JavaScriptArtifactAnalysis.ts• L101-263 src/…/JavaScriptSemanticGraphBuilder.ts• L239-283 src/…/JavaScriptSemanticGraphBuilder.ts• L401-560 src/…/JavaScriptWrappedCallPathCancellation.test.ts• L13-164

Electron boundary model

Electron protocol analysis models the boundary between renderer code, preload exposure, the main process, utility processes, and native add-ons. It records windows, web preferences, context-bridge members, IPC operations, sender checks, protocol registrations, utility entry points, native binding requests, wrapped call paths, and cached-data compilation sites. These findings let a query relate a renderer-facing API to a host-side boundary.

The boundary summary distinguishes recovered, empty, and partial states. Recovered means boundary facts were found. Empty means the analyzed source referenced Electron but no boundary fact was recovered. Partial means some Electron-loading source was not fully examined. Candidate loader identities do not count as proven Electron coverage. A rejected projection can still leave the summary partial or empty because coverage comes from the retained analysis, not only from expanded graph nodes.

IPC pairing is conservative. A renderer transmission pairs with a main handler only when the channel, owner, and mode support one exact candidate. A static pair describes a candidate relationship. It does not prove registration, dispatch, reachability, sender acceptance, or native loading. Dynamic channels, competing owners, cached-data references, and native binding requests remain unknown or requested boundaries rather than proof of execution or export support.

References: src/…/JavaScriptArtifactGraphBuilder.ts• L114-169 src/…/JavaScriptArtifactGraphBuilder.ts• L231-245 src/…/JavaScriptArtifactGraphBuilder.ts• L380-471 src/…/JavaScriptArtifactGraphElectronCoverage.test.ts• L133-224 src/…/JavaScriptArtifactGraphElectronCoverage.test.ts• L339-425

Runtime reconciliation

Runtime reconciliation joins one application static layer with optional cache or asset layers and passive runtime captures. It projects captures into target, frame, script, and worker entities. It then tests whether each runtime entity has an authorized static counterpart.

The flow below shows the main evidence path.

flowchart LR
    A[Authenticated static layers] --> C[Static candidates]
    B[Passive runtime captures] --> D[Runtime entities]
    C --> E[Location and content matching]
    D --> E
    E --> F[Load-state classification]
    E --> G[Observed-as edges]
    F --> H[Reconciled application graph]
    G --> H
    H --> I[Reconciliation Evidence]

Evidence inputs and mappings

Every input is authenticated before reconciliation. Exactly one layer must have the application role. A layer can also describe cache or asset content. A runtime mapping translates an authorized file root or URL prefix into an artifact prefix. It helps locate a static candidate but does not grant new filesystem or runtime access.

Runtime captures retain target location, frame scope, script source when captured, worker identity, and capture completeness. Unresolved locations and incomplete script inventories remain part of the input. Equal runtime payloads from distinct selected endpoints remain distinct capture instances. The graph does not merge observations only because their content is equal.

The reconciliation service normalizes relative file-root mappings against the current working directory while preserving portable absolute paths. It then validates the selected static layers and runtime observations before producing linked Evidence.

References: src/…/JavaScriptRuntimeReconciliationService.ts• L24-67 src/…/JavaScriptRuntimeReconciliationService.ts• L70-96 src/…/javascriptRuntimeReconciliationSchemas.ts• L25-77

Matching and load states

Matching prefers a content-and-location match when both are known. A unique content digest can match without a location. A unique location can match when source bytes are not present. Several candidates produce ambiguous. No authorized mapping produces unknown. A mapped location with no content match can produce unmatched.

The result classifies static modules and assets as loaded, resident in a loaded asset, not observed in the capture, or unknown. Not observed means outside the bounded capture window. It does not mean globally unloaded or unreachable. The combined graph adds observed_as edges only for matched entities and retains coverage beside each inference.

References: src/…/javascriptRuntimeReconciliationMatching.ts• L21-42 src/…/javascriptRuntimeReconciliationMatching.ts• L68-162 src/…/javascriptRuntimeReconciliationGraph.ts• L38-75

Electron observation

Electron observation uses an explicitly selected provider endpoint. Target listing returns the local file pages exposed by that endpoint. Page inspection observes one selected target for the caller's observation window. The service validates the provider output before it creates Evidence.

The retained record keeps normalized facts and the provider's source data when extra fields are present. A changed target or capture window is an output error rather than a valid observation of the caller's request. If cleanup fails after useful facts arrive, the service retains partial observation data and states the cleanup limit.

References: src/…/ElectronObservationService.ts• L27-65 src/…/ElectronObservationService.ts• L68-156 src/…/ElectronObservationService.ts• L158-183

Semantic queries

Semantic queries answer a focused question over one authenticated semantic graph. A seed identifies a semantic node, application node, literal, function fingerprint, property, endpoint, event, or Electron boundary field. The query walks only the requested direction and relation set. This makes the semantic graph a bounded route through retained source facts rather than a general execution model.

Query seeds and traversal

The query supports four directions:

  • backward-provenance follows facts toward their sources.
  • forward-influence follows possible effects toward their consumers.
  • callers follows call relations toward calling functions.
  • ownership follows ownership relations in either direction.

Callers can restrict relation kinds and can choose whether to include candidate dynamic edges. The result keeps reached nodes and relations with the evidence contexts that explain them. Static object reads, writes, spreads, and destructuring use exact property paths when the retained receiver and slot support that link. Otherwise the graph keeps a candidate relation and an unknown frontier instead of selecting a static leaf.

References: src/…/javascriptSemanticQuerySchemas.ts• L21-82 src/…/javascriptSemanticQuery.ts• L36-99 src/…/javascriptSemanticQuery.ts• L115-181 src/…/JavaScriptSemanticGraphObjectProjection.ts• L24-57 src/…/JavaScriptSemanticGraphObjectProjection.ts• L75-195

Query coverage

The query reports found, no-match, ambiguous, partial, or unsupported. It includes relevant unknown frontiers and candidate relation counts. A no-match result on a partial graph means only that no retained match was found. It does not prove that the application has no such relation.

Semantic graph facts retain compact evidence contexts. A node is anchored to its exact artifact digest, module path, source range, and role. After projection, matching application-graph locations add application node links. This lets a result point back to the exact static observation without copying all provenance into every row. Unknown omissions preserve the fact that a bounded budget prevented complete retention.

References: src/…/JavaScriptSemanticGraphBuilder.ts• L284-390 src/…/JavaScriptSemanticGraphBuilder.ts• L622-740 src/…/JavaScriptSemanticGraphBuilder.test.ts• L232-273 src/…/JavaScriptSemanticGraphBuilder.test.ts• L943-997

Retained application facts

The analysis services publish immutable Evidence only after they validate the graph, its cross-graph bindings, its source identity, and its limitations. A retained record supports later queries and derived workflows without rerunning source analysis. Derived records link the exact source records that produced them.

Application Evidence

Static application Evidence is tied to the input path, format, root artifact digest, and shipped-artifact authority. Runtime reconciliation Evidence has inferred authority and links its static layers and runtime captures. Electron observation Evidence has observed confidence from the named provider endpoint.

Semantic Evidence separates exact syntax from relationships inferred from syntax. Built-in operations remain low-confidence candidates when loader or mutation facts are not known. Dynamic syntax receives explicit unknown Evidence. These labels keep a possible static link distinct from an observed source fact or proof of runtime behavior.

Application analysis seals the complete result, validates its JSON form, hashes it, and remembers the graph Evidence for later use. If cancellation or cleanup interrupts a completed portion, the service can retain a validated partial application Evidence record rather than discard facts already owned by the analysis.

This separation keeps shipped facts distinct from analyst inference and runtime observation. A summary view does not replace the complete retained source.

References: src/…/JavaScriptArtifactGraphAccumulator.ts• L31-53 src/…/JavaScriptArtifactGraphStructure.ts• L59-97 src/…/JavaScriptArtifactGraphStructure.ts• L367-509 src/…/JavaScriptSemanticGraphBuilder.ts• L284-390

Derived workflows

Later workflows reuse retained application facts to trace a feature, compare application versions, compare export shapes, compare a source tree with a bundle, reconcile static and runtime views, or run a semantic query. Each workflow authenticates its inputs first and returns a new result with links to the sources it used.

The same rule applies to partial results. An unresolved match, incomplete graph, or missing runtime link stays in the result and can guide a later probe. The workflow does not upgrade static structure into proof of execution.

References: src/…/JavaScriptApplicationWorkflowService.ts• L81-152 src/…/JavaScriptSemanticTraceService.ts• L22-77 src/…/StaticObservedEndpointComparisonService.ts• L203-243

Analysis boundaries

The central boundary is between a fact observed from supplied bytes or a capture and a relation inferred from those facts. Static analysis does not run the application. Electron observation inspects only the selected provider target and window. Digest equality proves equal bytes. It does not prove execution, reachability, initialization, or feature use.

Runtime mappings help compare authorized inputs but do not enlarge their authority. Candidate loader identity, IPC pairing, native member requests, and cached-data references add useful paths without becoming runtime proof.

Use binary diagnostics and comparison for native layout and binary comparison. Use firmware and embedded analysis for embedded targets. Use application reconstruction when the question concerns reconstruction obligations across several application layers.

References: src/…/JavaScriptArtifactGraphBuilder.ts• L374-471 src/…/JavaScriptArtifactGraphFindings.ts• L207-353 src/…/JavaScriptSemanticGraphObjectProjection.ts• L49-57

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep static layer roles, runtime mapping normalization, capture identity, and reconciliation Evidence links aligned.
  • Keep content matching, location matching, ambiguity rules, capture-instance identity, and load-state labels aligned so a missing mapping does not become an absence claim.
  • Keep Electron observation target identity, observation-window identity, provider identity, raw source retention, and cleanup limitations aligned.
  • Keep Electron applicability, semantics state, IPC mode compatibility, application ownership, source coverage, candidate status, and dynamic-code unknowns aligned across the summary and graphs.
  • Keep worker source identity, static checkpoint admission, semantic result admission, semantic unknown budgets, cancellation checkpoints, and partial-fact recovery aligned.
  • Keep semantic node artifact identity, source locations, application-node bindings, relation evidence, candidate built-in labels, object-path resolution, and unknown omissions aligned.
  • Keep analysis admission order, explicit source selection, preload discovery, preload resolution, and loader choice aligned.
  • Keep graph and semantic graph root artifact identity bound to the same application Evidence.
  • Keep derived workflow source links and authority states aligned when a workflow consumes reconciled, observed, or partial facts.

Important failure modes

TriggerConsequenceGuard
A runtime entity has no authorized file or URL mappingThe system cannot claim a static absenceReport unknown and retain the unresolved location or mapping gap
Several static candidates match one runtime entityA runtime script or worker may be assigned to the wrong fileReturn ambiguous with all candidate identities
Captured source bytes disagree with a mapped static candidateThe result could join different artifact versionsReport disagreement instead of creating an observed_as edge
A passive capture is truncated or has incomplete script coverageUnseen runtime entities may be mistaken for absent entitiesMark reconciliation coverage partial or truncated
A nearer package manifest is unavailable or unobservedA source may use the wrong module scopeKeep the package type unknown and do not use a farther manifest
Preload discovery cannot read all relevant sourcesA declared preload may keep the wrong loader scope or remain undiscoveredRetain the discovery limitation and avoid treating the preload set as complete
The Electron provider changes the selected target or observation windowEvidence could describe a different desktop pageReturn an output error and retain the mismatched report as partial data
Electron cleanup fails after useful facts arriveValid observations could be lost or transport state could be overstatedRetain partial Evidence and state cleanup limits explicitly
An Electron IPC channel is dynamic, owned by an unknown application, or has competing handlersA renderer call may be paired with the wrong handlerKeep the operation ambiguous or unpaired
Candidate Electron loading or a rejected source projection is treated as proven coverageEmpty or partial boundaries can be misread as completeKeep candidate states out of proven counts and derive coverage from retained source analysis
The JavaScript worker reaches a resource or result limitSome semantic facts are unavailable while static facts may remainRetain the completed checkpoint and publish explicit partial limits
Semantic unknown capacity is exhaustedUnresolved frontiers are omitted from the graphRetain omission counts and mark semantic coverage partial
A semantic query starts from a missing seed or partial graphA no-match result can be overread as proof of absenceReturn query status, coverage, and relevant unknown frontiers together
A property receiver or destructuring source is not a retained containerA query may point to the wrong static slotKeep the relation as a candidate and retain an object-flow unknown
Wrapped Electron call-path work is cancelled during indexingA partial handler path could be mistaken for a complete pathStop at the checkpoint and retry with fresh state
A derived workflow receives altered or mismatched EvidenceThe result could cite a graph that was not analyzedAuthenticate source identity and reject mismatched graph bindings

Key files

FileWhy to read it
src/…/JavaScriptArtifactAnalysis.tsSource admission, package scope, worker checkpoints, and partial-fact retention.
src/…/JavaScriptArtifactGraphBuilder.tsApplication graph coverage, Electron summary states, ownership gaps, and limitations.
src/…/JavaScriptArtifactGraphAccumulator.tsCanonical node and edge assembly, observation deduplication, and loader-qualified evidence.
src/…/JavaScriptArtifactGraphFindings.tsStatic imports, workers, roles, endpoints, storage, source maps, and application ownership.
src/…/JavaScriptArtifactGraphStructure.tsArtifact, package, file, ASAR, and unavailable-content structure.
src/…/JavaScriptSemanticGraphBuilder.tsSemantic graph projection, resource ceilings, unknown retention, and graph coverage.
src/…/JavaScriptSemanticGraphObjectProjection.tsConservative property reads, writes, spreads, and destructuring links.
src/…/JavaScriptWrappedCallPathCancellation.test.tsCancellation checkpoints and stable retry behavior for Electron call paths.
src/…/JavaScriptArtifactGraphElectronCoverage.test.tsElectron coverage states and limits on static boundary claims.
src/…/JavaScriptSemanticGraphBuilder.test.tsSemantic flow, query coverage, and resource-bound behavior.
src/…/JavaScriptSemanticGraphDestructuring.test.tsSoundness rules for object and array destructuring under mutation and iterator uncertainty.
src/…/JavaScriptApplicationWorkflowService.tsAuthenticated workflows over retained application facts.