rea-agents 3.0.0 → 3.2.0

package/dist/config/parseConfig.js

@@ -1,10 +1,14 @@
-import { isAbsolute } from "node:path";
 import { ConfigurationError } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
+import { ok } from "../domain/result.js";
 import { parseEnvironment } from "./environment.js";
-import { parseStringArray, parseBrowserArray, parseElectronFileRoots, parseLoaderArgs, } from "./parsers.js";
-import { filePolicy, permissionScope, administratorGrants, browserNetworkScope, } from "./permissions.js";
-import { browserEndpointSchema, browserOriginSchema, } from "../domain/browserObservation.js";
+import { parseStringArray, parseAbsoluteRoots, parseLoaderArgs, } from "./parsers.js";
+import { permissionScope, administratorGrants } from "./permissions.js";
+import { appendElectronAutomationCeiling, parseElectronAutomationPolicy, } from "./electronAutomation.js";
+import { appendBrowserScenarioCeiling, parseBrowserScenarioPolicy, } from "./browserScenario.js";
+import { appendManagedRuntimeCeiling, parseManagedRuntimePolicy, } from "./managedRuntime.js";
+import { appendJavaScriptReplayCeiling, parseJavaScriptReplayPolicy, } from "./javascriptReplay.js";
+import { appendProcessCaptureCeiling, parseProcessExecutionPolicy, } from "./processCapture.js";
+import { appendPassiveObservationCeilings, parsePassiveObservationPolicies, } from "./passiveObservation.js";
 const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const defaultHopperLauncherPath = () => process.platform === "linux"
     ? "/opt/hopper/bin/Hopper"
@@ -13,206 +17,36 @@ const parseAllArrays = (env) => {
     const loaderArgs = parseLoaderArgs(env.HOPPER_LOADER_ARGS_JSON);
     if (!loaderArgs.ok)
         return loaderArgs;
-    const executableRoots = parseStringArray(env.REA_PROCESS_EXECUTABLE_ROOTS_JSON, "REA_PROCESS_EXECUTABLE_ROOTS_JSON");
-    if (!executableRoots.ok)
-        return executableRoots;
-    const workingRoots = parseStringArray(env.REA_PROCESS_WORKING_ROOTS_JSON, "REA_PROCESS_WORKING_ROOTS_JSON");
-    if (!workingRoots.ok)
-        return workingRoots;
-    const allowedEnvironment = parseStringArray(env.REA_PROCESS_ALLOWED_ENV_JSON, "REA_PROCESS_ALLOWED_ENV_JSON");
-    if (!allowedEnvironment.ok)
-        return allowedEnvironment;
-    const evidenceRoots = parseStringArray(env.REA_EVIDENCE_ROOTS_JSON, "REA_EVIDENCE_ROOTS_JSON");
-    if (!evidenceRoots.ok)
-        return evidenceRoots;
-    const investigationInputRoots = parseStringArray(env.REA_INVESTIGATION_INPUT_ROOTS_JSON, "REA_INVESTIGATION_INPUT_ROOTS_JSON");
-    if (!investigationInputRoots.ok)
-        return investigationInputRoots;
-    const analysisSnapshotRoots = parseStringArray(env.REA_ANALYSIS_SNAPSHOT_ROOTS_JSON, "REA_ANALYSIS_SNAPSHOT_ROOTS_JSON");
-    if (!analysisSnapshotRoots.ok)
-        return analysisSnapshotRoots;
-    const referenceRoots = parseStringArray(env.REA_REFERENCE_ROOTS_JSON, "REA_REFERENCE_ROOTS_JSON");
-    if (!referenceRoots.ok)
-        return referenceRoots;
     const secretPatterns = parseStringArray(env.REA_REFERENCE_SECRET_PATTERNS_JSON, "REA_REFERENCE_SECRET_PATTERNS_JSON");
     if (!secretPatterns.ok)
         return secretPatterns;
-    const observations = parseObservationArrays(env);
-    if (!observations.ok)
-        return observations;
-    const javascriptReplayRoots = parseAbsoluteRoots(env.REA_JAVASCRIPT_REPLAY_ROOTS_JSON, "REA_JAVASCRIPT_REPLAY_ROOTS_JSON");
-    if (!javascriptReplayRoots.ok)
-        return javascriptReplayRoots;
     const managedRuntimeRoots = parseAbsoluteRoots(env.REA_MANAGED_RUNTIME_ROOTS_JSON, "REA_MANAGED_RUNTIME_ROOTS_JSON");
     if (!managedRuntimeRoots.ok)
         return managedRuntimeRoots;
     return ok({
         loaderArgs: loaderArgs.value,
-        executableRoots: executableRoots.value,
-        workingRoots: workingRoots.value,
-        allowedEnvironment: allowedEnvironment.value,
-        evidenceRoots: evidenceRoots.value,
-        investigationInputRoots: investigationInputRoots.value,
-        analysisSnapshotRoots: analysisSnapshotRoots.value,
-        referenceRoots: referenceRoots.value,
         secretPatterns: secretPatterns.value,
-        ...observations.value,
-        javascriptReplayRoots: javascriptReplayRoots.value,
         managedRuntimeRoots: managedRuntimeRoots.value,
     });
 };
-const parseObservationArrays = (env) => {
-    const browserEndpoints = parseBrowserArray(env.REA_BROWSER_CDP_ENDPOINTS_JSON, "REA_BROWSER_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
-    if (!browserEndpoints.ok)
-        return browserEndpoints;
-    const browserOrigins = parseBrowserArray(env.REA_BROWSER_ALLOWED_ORIGINS_JSON, "REA_BROWSER_ALLOWED_ORIGINS_JSON", browserOriginSchema, 32);
-    if (!browserOrigins.ok)
-        return browserOrigins;
-    const browserScenarioExecutableRoots = parseAbsoluteRoots(env.REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON, "REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON");
-    if (!browserScenarioExecutableRoots.ok)
-        return browserScenarioExecutableRoots;
-    const browserScenarioEndpoints = parseBrowserArray(env.REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON, "REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
-    if (!browserScenarioEndpoints.ok)
-        return browserScenarioEndpoints;
-    const browserScenarioOrigins = parseBrowserArray(env.REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON, "REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON", browserOriginSchema, 32);
-    if (!browserScenarioOrigins.ok)
-        return browserScenarioOrigins;
-    const browserScenarioEnvironment = parseStringArray(env.REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON, "REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON");
-    if (!browserScenarioEnvironment.ok)
-        return browserScenarioEnvironment;
-    const electronEndpoints = parseBrowserArray(env.REA_ELECTRON_CDP_ENDPOINTS_JSON, "REA_ELECTRON_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
-    if (!electronEndpoints.ok)
-        return electronEndpoints;
-    const electronFileRoots = parseElectronFileRoots(env.REA_ELECTRON_FILE_ROOTS_JSON);
-    if (!electronFileRoots.ok)
-        return electronFileRoots;
-    const v8InspectorEndpoints = parseBrowserArray(env.REA_V8_INSPECTOR_ENDPOINTS_JSON, "REA_V8_INSPECTOR_ENDPOINTS_JSON", browserEndpointSchema, 16);
-    if (!v8InspectorEndpoints.ok)
-        return v8InspectorEndpoints;
-    const v8InspectorFileRoots = parseAbsoluteRoots(env.REA_V8_INSPECTOR_FILE_ROOTS_JSON, "REA_V8_INSPECTOR_FILE_ROOTS_JSON");
-    if (!v8InspectorFileRoots.ok)
-        return v8InspectorFileRoots;
-    const v8InspectorOrigins = parseBrowserArray(env.REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON, "REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON", browserOriginSchema, 32);
-    if (!v8InspectorOrigins.ok)
-        return v8InspectorOrigins;
-    return ok({
-        browserEndpoints: browserEndpoints.value,
-        browserOrigins: browserOrigins.value,
-        browserScenarioExecutableRoots: browserScenarioExecutableRoots.value,
-        browserScenarioEndpoints: browserScenarioEndpoints.value,
-        browserScenarioOrigins: browserScenarioOrigins.value,
-        browserScenarioEnvironment: browserScenarioEnvironment.value,
-        electronEndpoints: electronEndpoints.value,
-        electronFileRoots: electronFileRoots.value,
-        v8InspectorEndpoints: v8InspectorEndpoints.value,
-        v8InspectorFileRoots: v8InspectorFileRoots.value,
-        v8InspectorOrigins: v8InspectorOrigins.value,
-    });
-};
-const parseAbsoluteRoots = (value, name) => {
-    const parsed = parseStringArray(value, name);
-    if (!parsed.ok)
-        return parsed;
-    return parsed.value.some((root) => !isAbsolute(root))
-        ? err(new ConfigurationError(`${name} must encode absolute roots`))
-        : parsed;
-};
-const appendProcessCaptureCeiling = (ceilings, env, arrays) => {
-    if (env.REA_PROCESS_CAPTURE_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("process_capture", arrays.workingRoots, {
-        executables: arrays.executableRoots,
-        environment_names: arrays.allowedEnvironment,
-        network: env.REA_PROCESS_ALLOW_EXTERNAL_NETWORK === "true" ? "external" : "none",
-    }));
-};
-const appendBrowserObservationCeiling = (ceilings, env, arrays) => {
-    if (env.REA_BROWSER_OBSERVE_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("browser_observe", [], {
-        origins: [...arrays.browserEndpoints, ...arrays.browserOrigins],
-        network: browserNetworkScope(arrays.browserOrigins),
-    }));
-};
-const appendBrowserScenarioCeiling = (ceilings, env, arrays) => {
-    if (env.REA_BROWSER_SCENARIO_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("browser_automate", [], {
-        executables: arrays.browserScenarioExecutableRoots,
-        environment_names: arrays.browserScenarioEnvironment,
-        origins: [
-            ...arrays.browserScenarioEndpoints,
-            ...arrays.browserScenarioOrigins,
-        ],
-        network: browserNetworkScope(arrays.browserScenarioOrigins),
-    }));
-};
-const appendElectronObservationCeiling = (ceilings, env, arrays) => {
-    if (env.REA_ELECTRON_OBSERVE_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("electron_observe", arrays.electronFileRoots, {
-        origins: arrays.electronEndpoints,
-        network: "loopback",
-    }));
-};
-const appendV8InspectorObservationCeiling = (ceilings, env, arrays) => {
-    if (env.REA_V8_INSPECTOR_OBSERVE_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("v8_inspector_observe", arrays.v8InspectorFileRoots, {
-        origins: [...arrays.v8InspectorEndpoints, ...arrays.v8InspectorOrigins],
-        network: "loopback",
-    }));
-};
 const appendNativeMountCeiling = (ceilings, env) => {
     if (env.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true")
         ceilings.push(permissionScope("native_mount", [], { mount: true }));
 };
-const appendJavaScriptReplayCeiling = (ceilings, env, arrays) => {
-    if (env.REA_JAVASCRIPT_REPLAY_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("javascript_replay", arrays.javascriptReplayRoots, {
-        executables: [
-            env.REA_JAVASCRIPT_REPLAY_NODE_PATH,
-            env.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
-            env.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
-            env.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
-            env.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
-        ],
-        network: "none",
-        mount: true,
-    }));
-};
-const appendManagedRuntimeCeiling = (ceilings, env, arrays) => {
-    if (env.REA_MANAGED_RUNTIME_ENABLED !== "true")
-        return;
-    ceilings.push(permissionScope("managed_runtime", arrays.managedRuntimeRoots, {
-        executables: [env.REA_MANAGED_RUNTIME_EXECUTABLE_PATH],
-        network: "none",
-    }));
-};
-const buildPermissionCeilings = (env, arrays) => {
+const buildPermissionCeilings = (env, arrays, policies) => {
     const ceilings = [
-        permissionScope("evidence_read", arrays.evidenceRoots),
-        permissionScope("evidence_write", arrays.evidenceRoots),
-        permissionScope("investigation_input", arrays.investigationInputRoots),
-        permissionScope("investigation_workspace_read", arrays.evidenceRoots),
-        permissionScope("investigation_workspace_write", arrays.evidenceRoots),
-        permissionScope("snapshot_read", arrays.analysisSnapshotRoots),
-        permissionScope("snapshot_write", arrays.analysisSnapshotRoots),
         permissionScope("artifact_extract", ["/"]),
-        permissionScope("reference_read", arrays.referenceRoots),
     ];
-    appendProcessCaptureCeiling(ceilings, env, arrays);
-    appendBrowserObservationCeiling(ceilings, env, arrays);
-    appendBrowserScenarioCeiling(ceilings, env, arrays);
-    appendElectronObservationCeiling(ceilings, env, arrays);
-    appendV8InspectorObservationCeiling(ceilings, env, arrays);
+    appendProcessCaptureCeiling(ceilings, policies.processCapture);
+    appendPassiveObservationCeilings(ceilings, policies.passiveObservation);
+    appendBrowserScenarioCeiling(ceilings, policies.browserScenario);
+    appendElectronAutomationCeiling(ceilings, policies.electronAutomation);
     appendNativeMountCeiling(ceilings, env);
-    appendJavaScriptReplayCeiling(ceilings, env, arrays);
-    appendManagedRuntimeCeiling(ceilings, env, arrays);
+    appendJavaScriptReplayCeiling(ceilings, policies.javascriptReplay);
+    appendManagedRuntimeCeiling(ceilings, policies.managedRuntime);
     return ceilings;
 };
-const buildAppConfig = (env, arrays, permissionCeilings) => ({
+const buildAppConfig = (env, arrays, permissionCeilings, policies) => ({
     analysisProvider: env.REA_ANALYSIS_PROVIDER,
     ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
     ghidraJavaHome: env.JAVA_HOME,
@@ -222,62 +56,26 @@ const buildAppConfig = (env, arrays, permissionCeilings) => ({
     hopperTargetKind: env.HOPPER_TARGET_KIND,
     hopperLoaderArgs: arrays.loaderArgs,
     logLevel: env.REA_LOG_LEVEL,
-    processExecutionPolicy: {
-        enabled: env.REA_PROCESS_CAPTURE_ENABLED === "true",
-        executableRoots: arrays.executableRoots,
-        workingRoots: arrays.workingRoots,
-        allowedEnvironment: arrays.allowedEnvironment,
-        allowExternalNetwork: env.REA_PROCESS_ALLOW_EXTERNAL_NETWORK === "true",
-    },
+    processExecutionPolicy: policies.processCapture,
     artifactNativeMountEnabled: env.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true",
     artifactIntegrityContinueEnabled: env.REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED === "true",
-    evidenceFilePolicy: filePolicy(arrays.evidenceRoots),
-    investigationInputRoots: arrays.investigationInputRoots,
-    analysisSnapshotFilePolicy: filePolicy(arrays.analysisSnapshotRoots),
     referenceSourcePolicy: {
-        roots: arrays.referenceRoots,
         secretPatterns: arrays.secretPatterns,
-        maxBytes: 16 * 1024 * 1024,
-        maxEntries: 10_000,
-        maxDepth: 32,
-        maxPathBytes: 4_096,
-    },
-    browserObservationEnabled: env.REA_BROWSER_OBSERVE_ENABLED === "true",
-    browserCdpEndpoints: arrays.browserEndpoints,
-    browserAllowedOrigins: arrays.browserOrigins,
-    browserScenarioPolicy: {
-        enabled: env.REA_BROWSER_SCENARIO_ENABLED === "true",
-        executableRoots: arrays.browserScenarioExecutableRoots,
-        cdpEndpoints: arrays.browserScenarioEndpoints,
-        allowedOrigins: arrays.browserScenarioOrigins,
-        allowedEnvironment: arrays.browserScenarioEnvironment,
-    },
-    electronObservationEnabled: env.REA_ELECTRON_OBSERVE_ENABLED === "true",
-    electronCdpEndpoints: arrays.electronEndpoints,
-    electronFileRoots: arrays.electronFileRoots,
-    v8InspectorObservationEnabled: env.REA_V8_INSPECTOR_OBSERVE_ENABLED === "true",
-    v8InspectorEndpoints: arrays.v8InspectorEndpoints,
-    v8InspectorFileRoots: arrays.v8InspectorFileRoots,
-    v8InspectorAllowedOrigins: arrays.v8InspectorOrigins,
-    javascriptReplayPolicy: {
-        enabled: env.REA_JAVASCRIPT_REPLAY_ENABLED === "true",
-        roots: arrays.javascriptReplayRoots,
-        nodePath: env.REA_JAVASCRIPT_REPLAY_NODE_PATH,
-        bubblewrapPath: env.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
-        systemdRunPath: env.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
-        systemctlPath: env.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
-        shellPath: env.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
-    },
-    managedRuntimePolicy: {
-        enabled: env.REA_MANAGED_RUNTIME_ENABLED === "true",
-        roots: arrays.managedRuntimeRoots,
-        executablePath: env.REA_MANAGED_RUNTIME_EXECUTABLE_PATH,
     },
+    browserObservationPolicy: policies.passiveObservation.browser,
+    browserScenarioPolicy: policies.browserScenario,
+    electronObservationPolicy: policies.passiveObservation.electron,
+    electronAutomationPolicy: policies.electronAutomation,
+    v8InspectorObservationPolicy: policies.passiveObservation.v8Inspector,
+    javascriptReplayPolicy: policies.javascriptReplay,
+    managedRuntimePolicy: policies.managedRuntime,
     permissionCeilings,
     administratorPermissionGrants: administratorGrants(permissionCeilings.filter(({ capability }) => (capability !== "process_capture" ||
         env.REA_PROCESS_CAPTURE_AUTO_GRANT === "true") &&
         (capability !== "browser_automate" ||
-            env.REA_BROWSER_SCENARIO_AUTO_GRANT === "true"))),
+            env.REA_BROWSER_SCENARIO_AUTO_GRANT === "true") &&
+        (capability !== "electron_automate" ||
+            env.REA_ELECTRON_AUTOMATE_AUTO_GRANT === "true"))),
     permissionProjectRoot: env.REA_PERMISSION_PROJECT_ROOT,
     permissionProjectStore: env.REA_PERMISSION_PROJECT_STORE,
 });
@@ -294,6 +92,32 @@ export const parseConfig = (environment) => {
     const arraysResult = parseAllArrays(envResult.value);
     if (!arraysResult.ok)
         return arraysResult;
-    const permissionCeilings = buildPermissionCeilings(envResult.value, arraysResult.value);
-    return ok(buildAppConfig(envResult.value, arraysResult.value, permissionCeilings));
+    const passiveObservationPolicies = parsePassiveObservationPolicies(envResult.value);
+    if (!passiveObservationPolicies.ok)
+        return passiveObservationPolicies;
+    const processCapturePolicy = parseProcessExecutionPolicy(envResult.value);
+    if (!processCapturePolicy.ok)
+        return processCapturePolicy;
+    const browserScenarioPolicy = parseBrowserScenarioPolicy(envResult.value);
+    if (!browserScenarioPolicy.ok)
+        return browserScenarioPolicy;
+    const electronAutomationPolicy = parseElectronAutomationPolicy(envResult.value);
+    if (!electronAutomationPolicy.ok)
+        return electronAutomationPolicy;
+    const javascriptReplayPolicy = parseJavaScriptReplayPolicy(envResult.value);
+    if (!javascriptReplayPolicy.ok)
+        return javascriptReplayPolicy;
+    const managedRuntimePolicy = parseManagedRuntimePolicy(envResult.value, arraysResult.value.managedRuntimeRoots);
+    if (!managedRuntimePolicy.ok)
+        return managedRuntimePolicy;
+    const policies = {
+        passiveObservation: passiveObservationPolicies.value,
+        processCapture: processCapturePolicy.value,
+        browserScenario: browserScenarioPolicy.value,
+        electronAutomation: electronAutomationPolicy.value,
+        javascriptReplay: javascriptReplayPolicy.value,
+        managedRuntime: managedRuntimePolicy.value,
+    };
+    const permissionCeilings = buildPermissionCeilings(envResult.value, arraysResult.value, policies);
+    return ok(buildAppConfig(envResult.value, arraysResult.value, permissionCeilings, policies));
 };

package/dist/config/parsers.js

@@ -1,30 +1,32 @@
 import { z } from "zod";
+import { isAbsolute } from "node:path";
 import { ConfigurationError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
-import {} from "../domain/browserObservation.js";
-import { electronFileRootsSchema } from "../domain/electronObservation.js";
 export const parseStringArray = (encoded, name) => {
     try {
-        const parsed = z
-            .array(z.string().min(1))
-            .max(128)
-            .safeParse(JSON.parse(encoded));
+        const parsed = z.array(z.string().min(1)).safeParse(JSON.parse(encoded));
         return parsed.success
             ? ok(parsed.data)
-            : err(new ConfigurationError(parsed.error.issues.some(({ code }) => code === "too_big")
-                ? `${name} must encode at most 128 strings`
-                : `${name} must encode an array of strings`, { cause: parsed.error }));
+            : err(new ConfigurationError(`${name} must encode an array of strings`, {
+                cause: parsed.error,
+            }));
     }
     catch (cause) {
         return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
     }
 };
-export const parseBrowserArray = (encoded, name, itemSchema, maximum) => {
+/** Parse a JSON string array whose members must all be absolute paths. */
+export const parseAbsoluteRoots = (encoded, name) => {
+    const parsed = parseStringArray(encoded, name);
+    if (!parsed.ok)
+        return parsed;
+    return parsed.value.some((root) => !isAbsolute(root))
+        ? err(new ConfigurationError(`${name} must encode absolute roots`))
+        : parsed;
+};
+export const parseBrowserArray = (encoded, name, itemSchema) => {
     try {
-        const parsed = z
-            .array(itemSchema)
-            .max(maximum)
-            .safeParse(JSON.parse(encoded));
+        const parsed = z.array(itemSchema).safeParse(JSON.parse(encoded));
         return parsed.success
             ? ok([...new Set(parsed.data)].sort())
             : err(new ConfigurationError(`${name} must encode valid browser scopes`, {
@@ -35,20 +37,6 @@ export const parseBrowserArray = (encoded, name, itemSchema, maximum) => {
         return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
     }
 };
-export const parseElectronFileRoots = (encoded) => {
-    try {
-        const decoded = JSON.parse(encoded);
-        if (Array.isArray(decoded) && decoded.length === 0)
-            return ok([]);
-        const parsed = electronFileRootsSchema.safeParse(decoded);
-        return parsed.success
-            ? ok(parsed.data)
-            : err(new ConfigurationError("REA_ELECTRON_FILE_ROOTS_JSON must encode absolute roots", { cause: parsed.error }));
-    }
-    catch (cause) {
-        return err(new ConfigurationError("REA_ELECTRON_FILE_ROOTS_JSON must be valid JSON", { cause }));
-    }
-};
 export const parseLoaderArgs = (encoded) => {
     if (encoded === undefined)
         return ok([]);

package/dist/config/passiveObservation.js

@@ -0,0 +1,87 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { browserEndpointSchema, browserOriginSchema, } from "../domain/browserObservation.js";
+import { parseBrowserArray } from "./parsers.js";
+import { browserNetworkScope, permissionScope } from "./permissions.js";
+/** Parse every passive observation capability into closed policy variants. */
+export const parsePassiveObservationPolicies = (env) => {
+    const browser = parseBrowserObservationPolicy(env);
+    if (!browser.ok)
+        return browser;
+    const electron = parseElectronObservationPolicy(env);
+    if (!electron.ok)
+        return electron;
+    const v8Inspector = parseV8InspectorObservationPolicy(env);
+    if (!v8Inspector.ok)
+        return v8Inspector;
+    return ok({
+        browser: browser.value,
+        electron: electron.value,
+        v8Inspector: v8Inspector.value,
+    });
+};
+/** Add permission ceilings for each enabled passive observation policy. */
+export const appendPassiveObservationCeilings = (ceilings, policies) => {
+    appendBrowserCeiling(ceilings, policies.browser);
+    appendElectronCeiling(ceilings, policies.electron);
+    appendV8InspectorCeiling(ceilings, policies.v8Inspector);
+};
+const parseBrowserObservationPolicy = (env) => {
+    const endpoints = parseBrowserArray(env.REA_BROWSER_CDP_ENDPOINTS_JSON, "REA_BROWSER_CDP_ENDPOINTS_JSON", browserEndpointSchema);
+    if (!endpoints.ok)
+        return endpoints;
+    const origins = parseBrowserArray(env.REA_BROWSER_ALLOWED_ORIGINS_JSON, "REA_BROWSER_ALLOWED_ORIGINS_JSON", browserOriginSchema);
+    if (!origins.ok)
+        return origins;
+    if (env.REA_BROWSER_OBSERVE_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    const parsedEndpoints = requireFirst(endpoints.value, "REA_BROWSER_CDP_ENDPOINTS_JSON must encode at least one loopback endpoint when browser observation is enabled");
+    if (!parsedEndpoints.ok)
+        return parsedEndpoints;
+    const parsedOrigins = requireFirst(origins.value, "REA_BROWSER_ALLOWED_ORIGINS_JSON must encode at least one exact origin when browser observation is enabled");
+    if (!parsedOrigins.ok)
+        return parsedOrigins;
+    return ok({
+        status: "enabled",
+        cdpEndpoints: parsedEndpoints.value,
+        allowedOrigins: parsedOrigins.value,
+    });
+};
+const parseElectronObservationPolicy = (env) => {
+    if (env.REA_ELECTRON_OBSERVE_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    return ok({ status: "enabled" });
+};
+const parseV8InspectorObservationPolicy = (env) => {
+    if (env.REA_V8_INSPECTOR_OBSERVE_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    return ok({ status: "enabled" });
+};
+const requireFirst = (values, message) => {
+    const [first, ...remaining] = values;
+    return first === undefined
+        ? err(new ConfigurationError(message))
+        : ok([first, ...remaining]);
+};
+const appendBrowserCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("browser_observe", [], {
+        origins: [...policy.cdpEndpoints, ...policy.allowedOrigins],
+        network: browserNetworkScope(policy.allowedOrigins),
+    }));
+};
+const appendElectronCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("electron_observe", [], {
+        network: "loopback",
+    }));
+};
+const appendV8InspectorCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("v8_inspector_observe", [], {
+        network: "loopback",
+    }));
+};

package/dist/config/permissions.js

@@ -1,11 +1,4 @@
 import { isLiteralLoopbackHostname } from "../domain/browserObservation.js";
-export const filePolicy = (roots) => ({
-    roots,
-    maxBytes: 64 * 1024 * 1024,
-    maxDepth: 64,
-    maxStringLength: 1024 * 1024,
-    maxNodes: 1_000_000,
-});
 export const permissionScope = (capability, roots, options = {}) => ({
     capability,
     roots,

package/dist/config/processCapture.js

@@ -0,0 +1,47 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { parseAbsoluteRoots, parseStringArray } from "./parsers.js";
+import { permissionScope } from "./permissions.js";
+/** Parse process capture into disabled or fully authorized state. */
+export const parseProcessExecutionPolicy = (env) => {
+    const executableRoots = parseAbsoluteRoots(env.REA_PROCESS_EXECUTABLE_ROOTS_JSON, "REA_PROCESS_EXECUTABLE_ROOTS_JSON");
+    if (!executableRoots.ok)
+        return executableRoots;
+    const workingRoots = parseAbsoluteRoots(env.REA_PROCESS_WORKING_ROOTS_JSON, "REA_PROCESS_WORKING_ROOTS_JSON");
+    if (!workingRoots.ok)
+        return workingRoots;
+    const allowedEnvironment = parseStringArray(env.REA_PROCESS_ALLOWED_ENV_JSON, "REA_PROCESS_ALLOWED_ENV_JSON");
+    if (!allowedEnvironment.ok)
+        return allowedEnvironment;
+    if (env.REA_PROCESS_CAPTURE_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    const parsedExecutables = requireRoots(executableRoots.value, "REA_PROCESS_EXECUTABLE_ROOTS_JSON must encode at least one absolute root when process capture is enabled");
+    if (!parsedExecutables.ok)
+        return parsedExecutables;
+    const parsedWorking = requireRoots(workingRoots.value, "REA_PROCESS_WORKING_ROOTS_JSON must encode at least one absolute root when process capture is enabled");
+    if (!parsedWorking.ok)
+        return parsedWorking;
+    return ok({
+        status: "enabled",
+        executableRoots: parsedExecutables.value,
+        workingRoots: parsedWorking.value,
+        allowedEnvironment: allowedEnvironment.value,
+        networkAccess: env.REA_PROCESS_ALLOW_EXTERNAL_NETWORK === "true" ? "external" : "none",
+    });
+};
+/** Add the exact process-capture ceiling when capture is enabled. */
+export const appendProcessCaptureCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("process_capture", policy.workingRoots, {
+        executables: policy.executableRoots,
+        environment_names: policy.allowedEnvironment,
+        network: policy.networkAccess,
+    }));
+};
+const requireRoots = (roots, message) => {
+    const [first, ...remaining] = roots;
+    return first === undefined
+        ? err(new ConfigurationError(message))
+        : ok([first, ...remaining]);
+};

package/dist/contracts/analysisSearchContract.js

@@ -1,14 +1,11 @@
 import { z } from "zod";
-/** Shared bounded provider search input fields. */
+/** Shared provider search input fields. */
 export const analysisSearchInput = {
     pattern: z
         .string()
         .min(1)
-        .max(256)
-        .describe("The literal text or bounded regex pattern to search for"),
+        .describe("The literal text or regex pattern to search for"),
     mode: z.enum(["literal", "regex"]).default("literal"),
     case_sensitive: z.boolean().default(false).describe("Whether to match case"),
-    offset: z.number().int().min(0).default(0),
-    limit: z.number().int().min(1).max(100).default(100),
     document: z.string().optional().describe("The document name"),
 };