rea-agents 1.3.0 → 1.5.0

package/README.md

@@ -10,16 +10,20 @@
 
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
-[![68 MCP tools](https://img.shields.io/badge/MCP_tools-68-5c4ee5?style=flat-square)](#68-tools-for-investigation)
+[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#70-tools-for-investigation)
 [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 
-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [68 tools](#68-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
+[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [70 tools](#70-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <br />
 
 <code>npm install --global rea-agents && rea setup</code>
 
+<br />
+
+<img src="docs/assets/rea-hopper-analysis.png" alt="REA launching its analysis bridge inside Hopper while inspecting a native binary" width="1200" />
+
 </div>
 
 ---
@@ -290,15 +294,16 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 - Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
 - Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.
 
-## 68 tools for investigation
+## 70 tools for investigation
 
-| Tool family               | Count | Examples                                                                                                                |
-| ------------------------- | ----: | ----------------------------------------------------------------------------------------------------------------------- |
-| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                        |
-| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery |
-| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing           |
-| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree      |
-| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle |
+| Tool family               | Count | Examples                                                                                                                           |
+| ------------------------- | ----: | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                   |
+| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery            |
+| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                      |
+| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree                 |
+| Browser observation       |     2 | exact-origin CDP page discovery and passive DOM, accessibility, script, resource, network, console, worker, and storage inspection |
+| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle            |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
 
@@ -307,6 +312,7 @@ The public interface describes what the agent is trying to learn. Providers deci
 REA is already useful for native application investigation on macOS:
 
 - Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.
+- Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint, list only pages on approved exact origins, and capture bounded passive web evidence without navigation or JavaScript evaluation.
 - Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots.
 - Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.
 - Search and trace features across symbols, strings, metadata, references, and call paths.
@@ -327,12 +333,27 @@ REA is already useful for native application investigation on macOS:
 
 Hopper is the first provider, not the boundary of the project. Some current workflows still require Hopper and macOS; every evidence record identifies the provider and limitations behind its result.
 
+### Website observation with CDP
+
+REA can inspect an already-running Chrome-family browser that you own. Browser observation is disabled by default and requires a literal loopback CDP endpoint plus exact approved page origins:
+
+```bash
+export REA_BROWSER_OBSERVE_ENABLED=true
+export REA_BROWSER_CDP_ENDPOINTS_JSON='["http://127.0.0.1:9222"]'
+export REA_BROWSER_ALLOWED_ORIGINS_JSON='["http://127.0.0.1:3000"]'
+
+rea list-browser-targets http://127.0.0.1:9222 --approved --json
+rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --approved --json
+```
+
+`list_browser_targets` and `inspect_web_page` expose the same Evidence v2 contracts over MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. It redacts query values and never retains headers, bodies, cookies, storage values, console argument values, or WebSocket payloads. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model.
+
 ## Roadmap
 
 REA is growing into a toolkit for understanding software across static artifacts and observed behavior. The next capability families are:
 
 1. **Artifact decomposition** — DMG, ASAR, ZIP, packages, universal-binary slices, application resources, embedded frameworks, mobile packages, and artifact graphs.
-2. **Web and Electron investigation** — Playwright/CDP capture of DOM, accessibility trees, screenshots, storage, console, IPC, HTTP, WebSocket, routes, and visual or structural differences.
+2. **Web and Electron investigation** — extend the shipped passive CDP observation with approved interaction, screenshots, Electron IPC, route discovery, controlled replay, and visual or structural differences.
 3. **Deterministic behavior harnesses** — stronger process-tree ownership, protocol fixtures, network policy, filesystem tracing, signals, reconnects, and cross-version comparison.
 4. **JavaScript and source recovery** — bundle indexing, AST/module reconstruction, source-map discovery, historical-source matching, and CodeDB-backed cross-references.
 5. **Runtime observation** — approval-gated LLDB, Frida, system logs, process and filesystem observers, and native API tracing.
@@ -377,8 +398,9 @@ flowchart LR
     Router --> Hopper["Hopper provider"]
     Router --> Native["Native macOS provider"]
     Router --> Artifact["Artifact graph provider"]
+    Router --> Browser["Browser CDP provider"]
     Router --> Process["Process capture provider"]
-    Router -. roadmap .-> More["Browser, dynamic,<br/>and additional static providers"]
+    Router -. roadmap .-> More["Dynamic and additional<br/>static providers"]
     Hopper --> Target["Target software"]
     Process --> Target
     Native --> Target
@@ -420,6 +442,27 @@ rea mcp
 
 REA accepts a Mac `.app` folder directly. If an agent cannot find an app by name, tell it where the app is installed.
 
+### CLI exit status
+
+| Status    | Meaning                                                                                                                                                                                                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0`       | The requested operation completed. Truthful unknowns, warnings, and bounded or truncated evidence remain successful results.                                                                                                                                             |
+| `1`       | Arguments, policy, permission, provider analysis, integrity checking, cancellation, timeout, setup, diagnostics, update, uninstall, output encoding, or output writing prevented completion. Structured output identifies the failure category when REA could encode it. |
+| `128 + N` | The process ended from signal `N`, where the shell or runtime preserves the conventional signal-derived status.                                                                                                                                                          |
+
+`setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human`
+because configuration is not ready; rerun it after approval or remediation.
+`doctor` returns `1` when any check is unhealthy. Output format, full envelopes,
+filters, and token controls never change the operation status.
+
+When REA feeds a shell pipeline, enable `pipefail` so a downstream formatter
+cannot hide its failure:
+
+```bash
+set -o pipefail
+rea inventory-artifact ./app.asar --json | jq . > inventory.json
+```
+
 ## Current Hopper provider
 
 REA starts Hopper when needed; Hopper does not need to be running first. Hopper's launcher internally activates the application, so opening a target may bring Hopper to the foreground. REA asks macOS to start Hopper hidden and in the background when possible, but cannot guarantee that it will remain behind the current application.

package/bridge/hopper_bridge.py

@@ -628,16 +628,23 @@ def _dispatch(method, params):
     global _selected_document
     if method == "health":
         return {"name": "REA Hopper bridge", "version": "1.0.0", "run_id": REA_RUN_ID}
-    if method == "shutdown":
+    if method in ("shutdown", "shutdown_document"):
         document = _session_document()
         if document is None:
             return {"shutdown": True, "analysis_stopped": True, "document_closed": True}
         if document.backgroundProcessActive():
             document.requestBackgroundProcessStop()
+        if method == "shutdown" and REA_OWNS_PROCESS_LIFETIME:
+            return {
+                "shutdown": True,
+                "analysis_stopped": not document.backgroundProcessActive(),
+                "document_closed": False,
+                "cleanup_required": True,
+            }
         if document.backgroundProcessActive():
             document.waitForBackgroundProcessToEnd()
-        analysis_stopped = not document.backgroundProcessActive()
         document.closeDocument()
+        analysis_stopped = not document.backgroundProcessActive()
         document_closed = _session_document() is None
         return {
             "shutdown": True,
@@ -806,7 +813,9 @@ def _serve_connection(connection):
             if not isinstance(request["token"], str) or not hmac.compare_digest(request["token"], REA_TOKEN):
                 raise PermissionError("Invalid bridge capability")
             result = _dispatch(request["method"], request["params"])
-            should_stop = request["method"] == "shutdown"
+            should_stop = request["method"] == "shutdown_document" or (
+                request["method"] == "shutdown" and not result.get("cleanup_required", False)
+            )
             response = {"id": request_id, "result": _json_safe(result)}
         except Exception as error:
             response = {"id": request_id if isinstance(request_id, int) else 0, "error": {"code": -32000, "message": str(error)[:512], "type": _diagnostic_type(error)}}

package/dist/application/AnalysisSnapshotCache.js

@@ -52,12 +52,12 @@ export class AnalysisSnapshotCache {
                 this.#target.format !== snapshot.target.format ||
                 this.#target.architecture !== snapshot.target.architecture))
             this.#entries.clear();
-        this.#target = snapshot.target;
+        this.#target = structuredClone(snapshot.target);
         let imported = 0;
         for (const entry of snapshot.entries) {
             if (!this.#entries.has(entry.query_id))
                 imported += 1;
-            this.#entries.set(entry.query_id, entry);
+            this.#entries.set(entry.query_id, structuredClone(entry));
         }
         return imported;
     }
@@ -69,7 +69,7 @@ export class AnalysisSnapshotCache {
             snapshot_version: 1,
             target: snapshotTarget(target),
             entries: this.entries(),
-            evidence_bundle: evidenceBundle,
+            evidence_bundle: structuredClone(evidenceBundle),
         });
     }
     /** Validate target identity, merge evidence atomically, then stage entries. */
@@ -81,7 +81,9 @@ export class AnalysisSnapshotCache {
     }
     /** Return canonical entries for persistence. */
     entries() {
-        return [...this.#entries.values()].sort((left, right) => left.query_id.localeCompare(right.query_id));
+        return [...this.#entries.values()]
+            .sort((left, right) => left.query_id.localeCompare(right.query_id))
+            .map((entry) => structuredClone(entry));
     }
     /** Replay an exact provider-specific query, marking its cached provenance. */
     lookup(target, operation, parameters, provider) {
@@ -90,7 +92,7 @@ export class AnalysisSnapshotCache {
         if (cached === undefined)
             return undefined;
         const subject = cached.execution.subject;
-        return {
+        return structuredClone({
             result: cached.execution.result,
             rawResult: cached.execution.raw_result,
             provider: cached.execution.provider,
@@ -113,7 +115,7 @@ export class AnalysisSnapshotCache {
                         format: subject.format,
                         architecture: subject.architecture,
                     },
-        };
+        });
     }
     /** Record one successful immutable call unless the cache is full. */
     record(target, operation, parameters, execution) {

package/dist/application/ArtifactGraphConstruction.js

@@ -1,6 +1,14 @@
 import { createHash } from "node:crypto";
 import { extname } from "node:path";
 import canonicalize from "canonicalize";
+/** Index the first occurrence for each canonical logical path. */
+export const indexOccurrencesByPath = (occurrences) => {
+    const byPath = new Map();
+    for (const occurrence of occurrences)
+        if (!byPath.has(occurrence.logical_path))
+            byPath.set(occurrence.logical_path, occurrence);
+    return byPath;
+};
 export const createOccurrence = (entry, path, parent) => ({
     occurrence_id: `occ_${digestCanonical({ path, kind: entry.kind })}`,
     artifact_id: null,
@@ -83,7 +91,7 @@ export const createArtifactNode = (input) => ({
     architecture: null,
     executable: input.executable,
     content_state: input.contentState,
-    limitations: [],
+    limitations: [...(input.limitations ?? [])],
 });
 export const rootOccurrenceFor = (node, declaredSize) => ({
     occurrence_id: `occ_${digestCanonical({ root: node.artifact_id })}`,
@@ -118,13 +126,14 @@ export const rekeyOccurrences = (rootArtifactId, occurrences) => {
 };
 export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
     const byId = new Map(occurrences.map((item) => [item.occurrence_id, item]));
+    const byPath = indexOccurrencesByPath(occurrences);
     const edges = [];
     for (const occurrence of occurrences) {
         if (occurrence.parent_occurrence_id === null ||
             occurrence.artifact_id === null)
             continue;
-        const mappedSource = occurrence.logical_path.endsWith(".map")
-            ? occurrences.find(({ logical_path: path }) => path === occurrence.logical_path.slice(0, -".map".length))
+        const mappedSource = occurrence.logical_path.toLowerCase().endsWith(".map")
+            ? byPath.get(occurrence.logical_path.slice(0, -".map".length))
             : undefined;
         const parentArtifactId = mappedSource?.artifact_id ??
             byId.get(occurrence.parent_occurrence_id)?.artifact_id ??

package/dist/application/ArtifactInventory.js

@@ -10,24 +10,33 @@ import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.
 import { NativeDmgArtifactReader } from "../artifacts/NativeDmgArtifactReader.js";
 import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
 import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
-import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, indexOccurrencesByPath, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
 const NATIVE_MOUNT_DISABLED = {
     nativeMountApproved: false,
     nativeMountEnabled: false,
 };
+const STRICT_INTEGRITY_POLICY = {
+    mode: "fail",
+    approved: false,
+    enabled: false,
+    maxMismatches: 1,
+};
 /** Inventory one local artifact without extracting or mounting it. */
 export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED);
+    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED, options.integrity ?? STRICT_INTEGRITY_POLICY);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
+export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
-    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount);
+    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount, integrity);
 };
 /** Scan one already-canonical artifact path without resolving it again. */
-export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
+export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
+    if (integrity.mode === "record-and-continue" &&
+        (!integrity.approved || !integrity.enabled))
+        throw new ArtifactReaderFailure("unavailable", "Integrity continuation requires explicit approval and operator policy");
     const metadata = await lstat(path);
     const rootFormat = await classifyRoot(path, metadata.isDirectory());
     const rootDigest = metadata.isDirectory()
@@ -35,7 +44,7 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
         : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
     const reader = await createReader(path, rootFormat, nativeMount, signal);
     try {
-        const { nodes, occurrences } = await scanReader(reader, limits, signal);
+        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, limits, signal, integrity);
         materializeDirectoryNodes(occurrences, nodes);
         const rootNode = createRootNode({
             path,
@@ -51,6 +60,37 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
             if (occurrence.parent_occurrence_id === null)
                 occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
         occurrences.unshift(rootOccurrence);
+        const occurrenceById = new Map(occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]));
+        const occurrenceByPath = indexOccurrencesByPath(occurrences);
+        const integrityContradictions = pendingContradictions.map((contradiction) => {
+            const occurrence = occurrenceByPath.get(contradiction.logicalPath);
+            if (occurrence === undefined)
+                throw new ArtifactReaderFailure("integrity", "Integrity contradiction lost its graph occurrence");
+            const parent = occurrence.parent_occurrence_id === null
+                ? undefined
+                : occurrenceById.get(occurrence.parent_occurrence_id);
+            const parentArtifactId = parent?.artifact_id ?? rootNode.artifact_id;
+            return {
+                contradiction_id: `ic_${digestCanonical({
+                    root_artifact_id: rootNode.artifact_id,
+                    logical_path: contradiction.logicalPath,
+                    declared_sha256: contradiction.declaredSha256,
+                    observed_sha256: contradiction.observedSha256,
+                })}`,
+                occurrence_id: occurrence.occurrence_id,
+                parent_artifact_id: parentArtifactId,
+                logical_path: contradiction.logicalPath,
+                declared_sha256: contradiction.declaredSha256,
+                observed_sha256: contradiction.observedSha256,
+                entry_kind: contradiction.entryKind,
+                unpacked: contradiction.unpacked,
+                trust: "observed-untrusted",
+                provenance: "container-integrity-metadata-versus-observed-bytes",
+                limitations: [
+                    "Observed bytes contradict declared integrity metadata and cannot support equivalence.",
+                ],
+            };
+        });
         const edges = createArtifactEdges(rootNode.artifact_id, occurrences, reader?.provenance()[0]);
         const orderedNodes = [...nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
         const orderedOccurrences = occurrences.sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
@@ -65,6 +105,7 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
             nodes: orderedNodes,
             occurrences: orderedOccurrences,
             edges: orderedEdges,
+            integrity_contradictions: integrityContradictions,
         });
         const manifestId = `agm_${digestCanonical({
             schema_version: 1,
@@ -88,7 +129,15 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
             edges: orderedEdges,
             limits: toOutputLimits(limits),
             provenance: reader?.provenance() ?? [],
-            limitations: inventoryLimitations(rootFormat, reader),
+            integrity_contradictions: integrityContradictions,
+            limitations: [
+                ...inventoryLimitations(rootFormat, reader),
+                ...(integrityContradictions.length === 0
+                    ? []
+                    : [
+                        `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
+                    ]),
+            ],
         };
     }
     finally {
@@ -149,11 +198,11 @@ const visitNestedAsar = async (adapterKey, logicalPath, visit) => {
 const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
     logicalPath.toLowerCase().endsWith(".asar") &&
     entry.adapterKey.startsWith("/");
-const emptyScan = () => ({ nodes: new Map(), occurrences: [] });
-const scanReader = async (reader, limits, signal) => {
-    const { nodes, occurrences } = emptyScan();
+const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
+const scanReader = async (reader, limits, signal, integrity = STRICT_INTEGRITY_POLICY) => {
+    const { nodes, occurrences, pendingContradictions } = emptyScan();
     if (reader === undefined)
-        return { nodes, occurrences };
+        return { nodes, occurrences, pendingContradictions };
     const occurrenceByPath = new Map();
     const registry = new ArtifactPathRegistry();
     let totalBytes = 0;
@@ -167,24 +216,44 @@ const scanReader = async (reader, limits, signal) => {
             throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
         const digest = await hashReadable(await currentReader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
         totalBytes += digest.bytes;
-        if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
+        const mismatched = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
+        if (mismatched && integrity.mode === "fail")
             throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
                 logicalPath,
                 declaredSha256: entry.declaredSha256,
                 calculatedSha256: digest.sha256,
                 unpacked: entry.unpacked,
             });
+        if (mismatched && entry.declaredSha256 !== null) {
+            if (pendingContradictions.length >= integrity.maxMismatches)
+                throw new ArtifactReaderFailure("limit", "Artifact integrity mismatch limit exceeded");
+            pendingContradictions.push({
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                observedSha256: digest.sha256,
+                entryKind: entry.kind,
+                unpacked: entry.unpacked,
+            });
+        }
         const classified = entry.kind === "slice"
             ? { kind: "universal-slice", format: "mach-o" }
             : classifyArtifactContent(logicalPath, digest.prefix);
-        return createArtifactNode({
-            sha256: digest.sha256,
-            size: digest.bytes,
-            kind: classified.kind,
-            format: classified.format,
-            executable: entry.executable,
-            contentState: "embedded",
-        });
+        return {
+            node: createArtifactNode({
+                sha256: digest.sha256,
+                size: digest.bytes,
+                kind: classified.kind,
+                format: classified.format,
+                executable: entry.executable,
+                contentState: "embedded",
+                limitations: mismatched
+                    ? [
+                        "Observed content contradicts declared integrity metadata and is untrusted.",
+                    ]
+                    : [],
+            }),
+            mismatched,
+        };
     };
     const visit = async (currentReader, prefix) => {
         for await (const entry of currentReader.entries(signal)) {
@@ -196,20 +265,24 @@ const scanReader = async (reader, limits, signal) => {
             preflightEntry(entry, limits);
             const parent = nearestParent(logicalPath, occurrenceByPath);
             const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
-            const node = await digestEntry(currentReader, entry, logicalPath);
-            if (node !== undefined) {
-                nodes.set(node.artifact_id, node);
-                occurrence.artifact_id = node.artifact_id;
-                occurrence.hash_status = "verified";
+            const digested = await digestEntry(currentReader, entry, logicalPath);
+            if (digested !== undefined) {
+                nodes.set(digested.node.artifact_id, digested.node);
+                occurrence.artifact_id = digested.node.artifact_id;
+                occurrence.hash_status = digested.mismatched
+                    ? "mismatched"
+                    : "verified";
+                if (digested.mismatched)
+                    occurrence.limitations.push("Declared integrity metadata contradicts observed bytes.");
             }
             occurrences.push(occurrence);
             occurrenceByPath.set(logicalPath, occurrence);
-            if (expandableAsar)
+            if (expandableAsar && digested?.mismatched !== true)
                 await visitNestedAsar(entry.adapterKey, logicalPath, visit);
         }
     };
     await visit(reader, "");
-    return { nodes, occurrences };
+    return { nodes, occurrences, pendingContradictions };
 };
 const classifyRoot = async (path, directory) => {
     if (directory)

package/dist/application/AuthorizedArtifactInventory.js

@@ -2,15 +2,16 @@ import { realpath } from "node:fs/promises";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
 import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 /** Resolve, authorize, and scan one artifact without a second path resolution. */
-export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal) => {
+export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal, integrity) => {
     if (roots.length === 0)
         throw new ArtifactReaderFailure("path", "Artifact input roots are disabled");
     const [path, approved] = await Promise.all([
         realpath(inputPath),
-        Promise.all(roots.map(async (root) => realpath(root))),
+        canonicalizeConfiguredRoots(roots),
     ]);
     if (!approved.some((root) => withinRoot(root, path)))
         throw new ArtifactReaderFailure("path", "Artifact path is outside approved input roots");
-    return scanCanonicalArtifactInventory(path, limits, signal);
+    return scanCanonicalArtifactInventory(path, limits, signal, undefined, integrity);
 };