rea-agents 2.0.0 → 2.1.0

package/dist/config/environment.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { isAbsolute } from "node:path";
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
+const environmentSchema = z
+    .object({
+    REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
+    GHIDRA_INSTALL_DIR: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "GHIDRA_INSTALL_DIR must be absolute")
+        .optional(),
+    JAVA_HOME: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "JAVA_HOME must be absolute")
+        .optional(),
+    REA_ILSPY_CMD_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_ILSPY_CMD_PATH must be absolute")
+        .optional(),
+    HOPPER_LAUNCHER_PATH: z.string().min(1).optional(),
+    HOPPER_TARGET_PATH: z.string().min(1).optional(),
+    HOPPER_TARGET_KIND: z
+        .enum(["executable", "database"])
+        .default("executable"),
+    HOPPER_LOADER_ARGS_JSON: z.string().optional(),
+    REA_LOG_LEVEL: z
+        .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
+        .default("info"),
+    REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_PROCESS_CAPTURE_AUTO_GRANT: z.enum(["true", "false"]).default("true"),
+    REA_ARTIFACT_NATIVE_MOUNT_ENABLED: z
+        .enum(["true", "false"])
+        .default("false"),
+    REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED: z
+        .enum(["true", "false"])
+        .default("false"),
+    REA_PROCESS_ALLOW_EXTERNAL_NETWORK: z
+        .enum(["true", "false"])
+        .default("false"),
+    REA_PROCESS_EXECUTABLE_ROOTS_JSON: z.string().default("[]"),
+    REA_PROCESS_WORKING_ROOTS_JSON: z.string().default("[]"),
+    REA_PROCESS_ALLOWED_ENV_JSON: z.string().default("[]"),
+    REA_EVIDENCE_ROOTS_JSON: z.string().default("[]"),
+    REA_INVESTIGATION_INPUT_ROOTS_JSON: z.string().default("[]"),
+    REA_ANALYSIS_SNAPSHOT_ROOTS_JSON: z.string().default("[]"),
+    REA_REFERENCE_ROOTS_JSON: z.string().default("[]"),
+    REA_REFERENCE_SECRET_PATTERNS_JSON: z.string().default("[]"),
+    REA_BROWSER_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_BROWSER_CDP_ENDPOINTS_JSON: z.string().default("[]"),
+    REA_BROWSER_ALLOWED_ORIGINS_JSON: z.string().default("[]"),
+    REA_ELECTRON_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_ELECTRON_CDP_ENDPOINTS_JSON: z.string().default("[]"),
+    REA_ELECTRON_FILE_ROOTS_JSON: z.string().default("[]"),
+    REA_JAVASCRIPT_REPLAY_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_JAVASCRIPT_REPLAY_ROOTS_JSON: z.string().default("[]"),
+    REA_JAVASCRIPT_REPLAY_NODE_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_NODE_PATH must be absolute")
+        .default(process.execPath),
+    REA_JAVASCRIPT_REPLAY_BWRAP_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_BWRAP_PATH must be absolute")
+        .default("/usr/bin/bwrap"),
+    REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH must be absolute")
+        .default("/usr/bin/systemd-run"),
+    REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH must be absolute")
+        .default("/usr/bin/systemctl"),
+    REA_JAVASCRIPT_REPLAY_SHELL_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_JAVASCRIPT_REPLAY_SHELL_PATH must be absolute")
+        .default("/usr/bin/bash"),
+    REA_MANAGED_RUNTIME_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_MANAGED_RUNTIME_ROOTS_JSON: z.string().default("[]"),
+    REA_MANAGED_RUNTIME_EXECUTABLE_PATH: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_MANAGED_RUNTIME_EXECUTABLE_PATH must be absolute")
+        .default("/usr/bin/dotnet"),
+    REA_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(),
+    REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(),
+})
+    .refine((value) => (value.REA_PERMISSION_PROJECT_ROOT === undefined) ===
+    (value.REA_PERMISSION_PROJECT_STORE === undefined), {
+    message: "REA_PERMISSION_PROJECT_ROOT and REA_PERMISSION_PROJECT_STORE must be configured together",
+});
+export const parseEnvironment = (environment) => {
+    const parsed = environmentSchema.safeParse(environment);
+    if (!parsed.success) {
+        return err(new ConfigurationError("Invalid REA environment configuration", {
+            cause: parsed.error,
+        }));
+    }
+    return ok(parsed.data);
+};

package/dist/config/parseConfig.js

@@ -0,0 +1,228 @@
+import { isAbsolute } from "node:path";
+import { ConfigurationError } from "../domain/errors.js";
+import { err, 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";
+const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
+const defaultHopperLauncherPath = () => process.platform === "linux"
+    ? "/opt/hopper/bin/Hopper"
+    : DEFAULT_HOPPER_LAUNCHER_PATH;
+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 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 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 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,
+        browserEndpoints: browserEndpoints.value,
+        browserOrigins: browserOrigins.value,
+        electronEndpoints: electronEndpoints.value,
+        electronFileRoots: electronFileRoots.value,
+        javascriptReplayRoots: javascriptReplayRoots.value,
+        managedRuntimeRoots: managedRuntimeRoots.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 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 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 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);
+    appendElectronObservationCeiling(ceilings, env, arrays);
+    appendNativeMountCeiling(ceilings, env);
+    appendJavaScriptReplayCeiling(ceilings, env, arrays);
+    appendManagedRuntimeCeiling(ceilings, env, arrays);
+    return ceilings;
+};
+const buildAppConfig = (env, arrays, permissionCeilings) => ({
+    analysisProvider: env.REA_ANALYSIS_PROVIDER,
+    ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
+    ghidraJavaHome: env.JAVA_HOME,
+    ilspyCmdPath: env.REA_ILSPY_CMD_PATH,
+    hopperLauncherPath: env.HOPPER_LAUNCHER_PATH ?? defaultHopperLauncherPath(),
+    hopperTargetPath: env.HOPPER_TARGET_PATH,
+    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",
+    },
+    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,
+    electronObservationEnabled: env.REA_ELECTRON_OBSERVE_ENABLED === "true",
+    electronCdpEndpoints: arrays.electronEndpoints,
+    electronFileRoots: arrays.electronFileRoots,
+    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,
+    },
+    permissionCeilings,
+    administratorPermissionGrants: administratorGrants(env.REA_PROCESS_CAPTURE_AUTO_GRANT === "true"
+        ? permissionCeilings
+        : permissionCeilings.filter(({ capability }) => capability !== "process_capture")),
+    permissionProjectRoot: env.REA_PERMISSION_PROJECT_ROOT,
+    permissionProjectStore: env.REA_PERMISSION_PROJECT_STORE,
+});
+/**
+ * Parse provider and authority configuration once at the composition root.
+ * Explicit loader arguments override REA's header-derived defaults for a
+ * supported target, allowing callers to refine Hopper's loader behavior without
+ * bypassing REA's path and executable-header checks.
+ */
+export const parseConfig = (environment) => {
+    const envResult = parseEnvironment(environment);
+    if (!envResult.ok)
+        return envResult;
+    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));
+};

package/dist/config/parsers.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+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));
+        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 }));
+    }
+    catch (cause) {
+        return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
+    }
+};
+export const parseBrowserArray = (encoded, name, itemSchema, maximum) => {
+    try {
+        const parsed = z
+            .array(itemSchema)
+            .max(maximum)
+            .safeParse(JSON.parse(encoded));
+        return parsed.success
+            ? ok([...new Set(parsed.data)].sort())
+            : err(new ConfigurationError(`${name} must encode valid browser scopes`, {
+                cause: parsed.error,
+            }));
+    }
+    catch (cause) {
+        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([]);
+    let decoded;
+    try {
+        decoded = JSON.parse(encoded);
+    }
+    catch (cause) {
+        return err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must be valid JSON", {
+            cause,
+        }));
+    }
+    const parsed = z.array(z.string()).safeParse(decoded);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must encode an array of strings", { cause: parsed.error }));
+};

package/dist/config/permissions.js

@@ -0,0 +1,30 @@
+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,
+    executables: options.executables ?? [],
+    environment_names: options.environment_names ?? [],
+    ...(options.origins === undefined ? {} : { origins: options.origins }),
+    network: options.network ?? "none",
+    mount: options.mount ?? false,
+});
+export const administratorGrants = (ceilings) => ceilings.map((ceiling) => ({
+    ...ceiling,
+    grant_id: `administrator:${ceiling.capability}`,
+    lifetime: "administrator",
+    operation_identity: null,
+    expires_at: null,
+}));
+export const browserNetworkScope = (origins) => origins.every((origin) => {
+    const hostname = new URL(origin).hostname;
+    return isLiteralLoopbackHostname(hostname);
+})
+    ? "loopback"
+    : "external";

package/dist/config/types.js

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