rea-agents 1.4.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

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,
@@ -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,7 +10,7 @@ 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,
@@ -61,8 +61,9 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
                 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 = occurrences.find(({ logical_path: path }) => path === contradiction.logicalPath);
+            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

package/dist/application/AuthorizedArtifactInventory.js

@@ -2,13 +2,14 @@ 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, 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");

package/dist/application/BinarySession.js

@@ -61,7 +61,7 @@ export class BinarySession {
         if (operation !== undefined) {
             const exact = this.#capabilities?.get(operation)?.provider;
             if (exact !== undefined)
-                return exact;
+                return structuredClone(exact);
             if (enhancedToolNameSchema.safeParse(operation).success) {
                 const providers = new Map();
                 for (const descriptor of this.#capabilities?.values() ?? [])
@@ -71,11 +71,11 @@ export class BinarySession {
                 if (providers.size === 1) {
                     const provider = providers.values().next().value;
                     if (provider !== undefined)
-                        return provider;
+                        return structuredClone(provider);
                 }
             }
         }
-        return this.#providerIdentity;
+        return structuredClone(this.#providerIdentity);
     }
     /** Observe runtime provider-health changes that affect discovery metadata. */
     onAvailabilityChanged(listener) {
@@ -130,12 +130,15 @@ export class BinarySession {
     }
     /** Read one session-retained immutable workspace revision. */
     investigationWorkspace(workspaceId, revision) {
-        return this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
+        const workspace = this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
+        return workspace === undefined ? undefined : structuredClone(workspace);
     }
     /** List retained workspace revisions in canonical identity order. */
     investigationWorkspaces() {
-        return [...this.#investigationWorkspaces.values()].sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
-            left.revision - right.revision);
+        return [...this.#investigationWorkspaces.values()]
+            .sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
+            left.revision - right.revision)
+            .map((workspace) => structuredClone(workspace));
     }
     /** Create an approved residual unknown and immutable mutation evidence. */
     recordUnknown(input) {
@@ -310,7 +313,9 @@ export class BinarySession {
     }
     /** Return the immutable artifact identity captured before Hopper launched. */
     activeTarget() {
-        return this.#active?.target;
+        return this.#active === undefined
+            ? undefined
+            : structuredClone(this.#active.target);
     }
     /**
      * Invoke a Hopper tool against the active target.

package/dist/application/BoundedJsonFiles.js

@@ -2,7 +2,9 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { EvidenceFileError } from "../domain/errors.js";
+import { isJsonWithinLimits } from "../domain/jsonLimits.js";
 import { err, ok } from "../domain/result.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 /** Read bounded JSON data from a regular file beneath an approved root. */
 export const readBoundedJson = async (path, policy) => {
     if (policy.roots.length === 0)
@@ -26,8 +28,9 @@ export const readBoundedJson = async (path, policy) => {
         catch (cause) {
             return err(new EvidenceFileError("read", "invalid-json", { cause }));
         }
-        const limits = validateJsonLimits(decoded, policy);
-        return limits.ok ? ok(decoded) : limits;
+        return isJsonWithinLimits(decoded, policy)
+            ? ok(decoded)
+            : err(new EvidenceFileError("read", "too-large"));
     }
     catch (cause) {
         return err(new EvidenceFileError("read", "io", { cause }));
@@ -69,8 +72,7 @@ export const writeBoundedText = async (encoded, path, overwrite, policy) => {
     }
 };
 const isApproved = async (candidate, roots) => {
-    for (const configuredRoot of roots) {
-        const root = await realpath(resolve(configuredRoot));
+    for (const root of await canonicalizeConfiguredRoots(roots.map((configuredRoot) => resolve(configuredRoot)))) {
         const relation = relative(root, candidate);
         if (relation === "" ||
             (!relation.startsWith("..") && !isAbsolute(relation)))
@@ -78,31 +80,6 @@ const isApproved = async (candidate, roots) => {
     }
     return false;
 };
-const validateJsonLimits = (root, policy) => {
-    const pending = [
-        { value: root, depth: 0 },
-    ];
-    let nodes = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        nodes += 1;
-        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
-            return err(new EvidenceFileError("read", "too-large"));
-        if (typeof current.value === "string" &&
-            current.value.length > policy.maxStringLength)
-            return err(new EvidenceFileError("read", "too-large"));
-        if (typeof current.value !== "object" || current.value === null)
-            continue;
-        for (const [key, value] of Object.entries(current.value)) {
-            if (key.length > policy.maxStringLength)
-                return err(new EvidenceFileError("read", "too-large"));
-            pending.push({ value, depth: current.depth + 1 });
-        }
-    }
-    return ok(null);
-};
 const isFileNotFound = (cause) => typeof cause === "object" &&
     cause !== null &&
     "code" in cause &&

package/dist/application/BrowserEvidence.js

@@ -0,0 +1,35 @@
+import { createEvidence, } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+/** Create Evidence v2 for a policy-scoped external browser observation. */
+export const createBrowserEvidence = (operation, input, result, provider) => createEvidence(undefined, provider, {
+    predicateType: operation === "list_browser_targets"
+        ? "rea.browser-target-list/v1"
+        : "rea.web-page-inspection/v1",
+    operation,
+    parameters: browserParameters(input),
+    result: jsonValueSchema.parse(result),
+    confidence: "observed",
+    authority: "external-service",
+    environment: "target" in result
+        ? {
+            id: `${result.browser.product}@${result.browser.revision}`,
+            platform: process.platform,
+            architecture: process.arch,
+            isolation: "none",
+        }
+        : null,
+    limitations: result.limitations,
+});
+const browserParameters = (input) => ({
+    cdp_endpoint: input.cdp_endpoint,
+    allowed_origins: input.allowed_origins,
+    ...("target_id" in input
+        ? {
+            target_id: input.target_id,
+            observation_ms: input.observation_ms,
+            include_script_sources: input.include_script_sources,
+            include_storage_keys: input.include_storage_keys,
+            limits: input.limits,
+        }
+        : { offset: input.offset, limit: input.limit }),
+});

package/dist/application/BrowserObservationPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/BrowserObservationService.js

@@ -0,0 +1,52 @@
+import { AnalysisCapabilityUnavailableError, AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createBrowserEvidence } from "./BrowserEvidence.js";
+/** Authorize and execute one policy-scoped target discovery observation. */
+export const listBrowserTargets = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "list_browser_targets");
+    if (!ready.ok)
+        return ready;
+    const result = await ready.value.listTargets(input, options);
+    return result.ok
+        ? ok(createBrowserEvidence("list_browser_targets", input, result.value, ready.value.identity()))
+        : result;
+};
+/** Authorize and execute one policy-scoped passive page inspection. */
+export const inspectWebPage = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "inspect_web_page");
+    if (!ready.ok)
+        return ready;
+    const result = await ready.value.inspectPage(input, options);
+    return result.ok
+        ? ok(createBrowserEvidence("inspect_web_page", input, result.value, ready.value.identity()))
+        : result;
+};
+const prepare = async (browser, authority, input, operation) => {
+    if (authority === undefined)
+        return err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation permission policy is not configured"));
+    const authorized = await authority.authorize({
+        capability: "browser_observe",
+        roots: [],
+        executables: [],
+        environment_names: [],
+        origins: [input.cdp_endpoint, ...input.allowed_origins],
+        network: browserNetworkScope(input.allowed_origins),
+        mount: false,
+        operation_identity: `${operation}:${input.target_id ?? input.cdp_endpoint}`,
+    }, "read");
+    if (!authorized.ok)
+        return err(authorized.error instanceof PermissionRequiredError
+            ? authorized.error
+            : new AnalysisProtocolError(authorized.error.message, {
+                cause: authorized.error,
+            }));
+    return browser === undefined
+        ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation provider is not configured"))
+        : ok(browser);
+};
+const browserNetworkScope = (allowedOrigins) => allowedOrigins.every((origin) => {
+    const hostname = new URL(origin).hostname;
+    return hostname === "127.0.0.1" || hostname === "[::1]";
+})
+    ? "loopback"
+    : "external";

package/dist/application/CapabilityInventory.js

@@ -64,6 +64,13 @@ const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy
             reason: "policy_disabled",
             remediation: "Configure or grant an evidence_read root.",
         };
+    if (kind === "browser-provider")
+        return policy.browserObservationEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "policy_disabled",
+                remediation: "Enable browser observation and configure exact CDP endpoint and page origins.",
+            };
     if (kind === "session")
         return { reason: "available", remediation: null };
     if (!targetOpen)

package/dist/application/ConfiguredRoots.js

@@ -0,0 +1,19 @@
+import { realpath } from "node:fs/promises";
+/** Canonicalize configured policy roots while ignoring stale missing entries. */
+export const canonicalizeConfiguredRoots = async (roots) => {
+    const canonical = [];
+    for (const root of roots) {
+        try {
+            canonical.push(await realpath(root));
+        }
+        catch (cause) {
+            if (!isMissingPath(cause))
+                throw cause;
+        }
+    }
+    return canonical;
+};
+const isMissingPath = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";

package/dist/application/CrossVersionInvestigation.js

@@ -47,6 +47,7 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         session: execution.session,
         signal: execution.signal,
         progress: execution.progress,
+        authorizeWorkspaceWrite: execution.authorizeWorkspaceWrite,
     });
 };
 const continueInvestigation = async (context) => {
@@ -74,6 +75,11 @@ const continueInvestigation = async (context) => {
             run.run_id === legacyIdentity.runId));
     if (context.initial !== null && existing?.status === "complete")
         return completeOutcome(context.initial, existing, true, context.session);
+    if (context.authorizeWorkspaceWrite !== undefined) {
+        const authorized = await context.authorizeWorkspaceWrite();
+        if (!authorized.ok)
+            return authorized;
+    }
     const pages = createInventoryEvidencePages(context.input, context.snapshots);
     if (!pages.ok)
         return pages;

package/dist/application/DeferredFileAuthorization.js

@@ -0,0 +1,61 @@
+import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { PermissionPathError, } from "./PermissionAuthority.js";
+/** Authorize one root-scoped operation and project policy path failures. */
+export const authorizeRootPermission = async (authority, request) => {
+    const authorized = await authority.authorize({
+        capability: request.capability,
+        roots: request.roots,
+        executables: [],
+        environment_names: [],
+        network: "none",
+        mount: false,
+        operation_identity: `${request.operation}:${request.capability}:${request.roots.join(":")}`,
+    }, request.access);
+    return authorized.ok
+        ? ok(null)
+        : err(authorized.error instanceof PermissionRequiredError
+            ? authorized.error
+            : new AnalysisProtocolError(authorized.error.message, {
+                cause: authorized.error,
+            }));
+};
+/** Authorize an existing file read and defer write authority until requested. */
+export const authorizeFileReadWithDeferredWrite = async (authority, input) => {
+    const read = await authority.authorize({
+        capability: input.readCapability,
+        roots: [input.path],
+        executables: [],
+        environment_names: [],
+        network: "none",
+        mount: false,
+        operation_identity: `${input.operation}:${input.readCapability}:${input.path}`,
+    }, "read");
+    let writeAuthorization;
+    if (!read.ok) {
+        if (!(read.error instanceof PermissionPathError) ||
+            read.error.reason !== "not_found")
+            return err(read.error instanceof PermissionRequiredError
+                ? read.error
+                : new AnalysisProtocolError(read.error.message, {
+                    cause: read.error,
+                }));
+        writeAuthorization = authorizeRootPermission(authority, {
+            capability: input.writeCapability,
+            roots: [input.path],
+            access: "write",
+            operation: input.operation,
+        });
+        const authorized = await writeAuthorization;
+        if (!authorized.ok)
+            return authorized;
+    }
+    return ok({
+        authorizeWrite: () => (writeAuthorization ??= authorizeRootPermission(authority, {
+            capability: input.writeCapability,
+            roots: [input.path],
+            access: "write",
+            operation: input.operation,
+        })),
+    });
+};

package/dist/application/DirectAnalysis.js

@@ -12,6 +12,7 @@ import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/analysisSnapshot.js";
 import { err, ok } from "../domain/result.js";
 import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
+import { authorizeFileReadWithDeferredWrite, } from "./DeferredFileAuthorization.js";
 const WORKFLOW_PROVIDER = {
     id: "rea-workflow",
     name: "REA composed investigation workflow",
@@ -26,6 +27,9 @@ export const runDirectAnalysis = async (path, tool, arguments_, options = {}) =>
     logger: options.logger ?? silentLogger,
     snapshotPath: options.snapshotPath,
     signal,
+    ...(options.permissionAuthority === undefined
+        ? {}
+        : { permissionAuthority: options.permissionAuthority }),
 }));
 /** Execute one provider-native semantic operation with atomic provenance. */
 export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger, signal) => withProcessCancellation(signal, (operationSignal) => runAnalysis(path, tool, arguments_, {
@@ -51,19 +55,8 @@ export const runSessionStatus = async (logger = silentLogger) => {
         await session.close();
     }
 };
-const authorizeAnalysis = async (authority, tool, arguments_, snapshotPath) => {
+const authorizeAnalysis = async (authority, tool, arguments_) => {
     const requests = [];
-    if (snapshotPath !== undefined) {
-        requests.push({
-            capability: "snapshot_read",
-            path: snapshotPath,
-            access: "write",
-        }, {
-            capability: "snapshot_write",
-            path: snapshotPath,
-            access: "write",
-        });
-    }
     if (tool === "extract_artifact" && typeof arguments_.output_root === "string")
         requests.push({
             capability: "artifact_extract",
@@ -107,17 +100,41 @@ const authorizeAnalysis = async (authority, tool, arguments_, snapshotPath) => {
     }
     return ok(null);
 };
+const permissionAuthorityFor = (config, supplied) => supplied === undefined
+    ? loadConfiguredPermissionAuthority(config)
+    : Promise.resolve(ok(supplied));
+const authorizeSnapshotAccess = async (authority, tool, snapshotPath) => snapshotPath === undefined
+    ? ok(undefined)
+    : authorizeFileReadWithDeferredWrite(authority, {
+        path: snapshotPath,
+        readCapability: "snapshot_read",
+        writeCapability: "snapshot_write",
+        operation: tool,
+    });
+const authorizeDeferredWrite = (authorization) => authorization?.authorizeWrite() ?? Promise.resolve(ok(null));
+const authorizeAnalysisRun = async (input) => {
+    const authority = await permissionAuthorityFor(input.config, input.suppliedAuthority);
+    if (!authority.ok)
+        return authority;
+    const operation = await authorizeAnalysis(authority.value, input.tool, input.arguments);
+    if (!operation.ok)
+        return operation;
+    return authorizeSnapshotAccess(authority.value, input.tool, input.snapshotPath);
+};
 const runAnalysis = async (path, tool, arguments_, options) => {
     const { logger, signal, snapshotPath } = options;
     const config = parseConfig(process.env);
     if (!config.ok)
         return cliError(config.error);
-    const permissionAuthority = await loadConfiguredPermissionAuthority(config.value);
-    if (!permissionAuthority.ok)
-        return cliError(permissionAuthority.error);
-    const authorized = await authorizeAnalysis(permissionAuthority.value, tool, arguments_, snapshotPath);
-    if (!authorized.ok)
-        return cliError(authorized.error);
+    const authorization = await authorizeAnalysisRun({
+        config: config.value,
+        suppliedAuthority: options.permissionAuthority,
+        tool,
+        arguments: arguments_,
+        snapshotPath,
+    });
+    if (!authorization.ok)
+        return cliError(authorization.error);
     const unavailable = snapshotUnavailable(snapshotPath, config.value.hopperLoaderArgs);
     if (unavailable !== undefined)
         return cliError(unavailable);
@@ -135,6 +152,9 @@ const runAnalysis = async (path, tool, arguments_, options) => {
             return cliError(prepared.error);
         if (prepared.value.evidence !== undefined)
             return prepared.value.evidence;
+        const writable = await authorizeDeferredWrite(authorization.value);
+        if (!writable.ok)
+            return cliError(writable.error);
         const { snapshot } = prepared.value;
         const opened = await session.open(path, snapshot === undefined ? { signal } : { signal, snapshot });
         if (!opened.ok)