rea-agents 1.7.0 → 2.0.0

package/dist/application/JavaScriptReplayPlanning.js

@@ -0,0 +1,201 @@
+import canonicalize from "canonicalize";
+import { createHash } from "node:crypto";
+const REPLAY_POLICY_VERSION = "linux-bwrap-systemd-v1";
+const REPLAY_POLICY_DOCUMENT = Object.freeze({
+    version: REPLAY_POLICY_VERSION,
+    namespaces: ["user", "pid", "network", "ipc", "uts", "cgroup"],
+    capabilities: "drop-all",
+    network: "none",
+    filesystem: "minimal-read-only-runtime-plus-private-tmpfs",
+    seccomp: "rea-linux-x86_64-v1",
+    resource_manager: "systemd-user-cgroup-v2",
+    nested_user_namespaces: false,
+});
+/** Read, normalize, and content-address every input to one replay experiment. */
+export const prepareReplayPlan = async (input, policy, host) => {
+    const cases = replayCases(input).map((item) => ({
+        ...item,
+        sha256: digestJson(item.arguments),
+    }));
+    if (new TextEncoder().encode(JSON.stringify(cases.map(({ arguments: args }) => args))).byteLength > input.limits.input_bytes)
+        throw new RangeError("Replay case inputs exceed the aggregate byte limit");
+    await host.probe(policy);
+    const [runtime, bubblewrap, systemdRun, systemctl, shell, worker, runtimeFiles, left, right,] = await Promise.all([
+        host.identifyExecutable(policy.nodePath, ["--version"]),
+        host.identifyExecutable(policy.bubblewrapPath, ["--version"]),
+        host.identifyExecutable(policy.systemdRunPath, ["--version"]),
+        host.identifyExecutable(policy.systemctlPath, ["--version"]),
+        host.identifyExecutable(policy.shellPath, ["--version"]),
+        host.identifyWorker(),
+        host.identifyRuntimeClosure(policy.nodePath),
+        prepareSide(input.left, input.limits.module_bytes, host),
+        input.right === undefined
+            ? Promise.resolve(undefined)
+            : prepareSide(input.right, input.limits.module_bytes, host),
+    ]);
+    const withoutDigest = {
+        schema_version: 1,
+        policy_version: REPLAY_POLICY_VERSION,
+        policy_sha256: digestJson(REPLAY_POLICY_DOCUMENT),
+        network: "none",
+        filesystem: {
+            host_writes: false,
+            private_tmpfs_bytes: input.limits.tmpfs_bytes,
+        },
+        runtime: {
+            executable: runtime,
+            worker,
+            read_only_files: runtimeFiles.map((item) => ({
+                source_path: item.sourcePath,
+                destination_path: item.destinationPath,
+                sha256: item.sha256,
+            })),
+        },
+        sandbox: {
+            bubblewrap,
+            systemd_run: systemdRun,
+            systemctl,
+            shell,
+            seccomp_sha256: host.seccompDigest(),
+        },
+        left: left.commitment,
+        ...(right === undefined ? {} : { right: right.commitment }),
+        cases,
+        determinism: input.determinism,
+        limits: input.limits,
+        effects: [
+            "Execute selected extracted modules in a disposable Linux OS sandbox",
+            "Create and remove one private cgroup and mount namespace",
+            "Retain bounded return, exception, termination, and diagnostic evidence",
+            "Perform no host filesystem writes and expose no host or external network",
+            ...(input.reproducer_export === undefined
+                ? []
+                : ["Write one separately approved reproducer after sandbox cleanup"]),
+        ],
+        reproducer_export: input.reproducer_export === undefined
+            ? null
+            : {
+                path: input.reproducer_export.path,
+                include_sources: input.reproducer_export.include_sources,
+                authority: "evidence_write",
+            },
+    };
+    const publicPlan = {
+        ...withoutDigest,
+        plan_digest: digestJson(withoutDigest),
+    };
+    return {
+        publicPlan,
+        leftSources: left.sources,
+        ...(right === undefined ? {} : { rightSources: right.sources }),
+    };
+};
+const prepareSide = async (side, maximumBytes, host) => {
+    const aliases = new Set(side.modules.map(({ alias }) => alias));
+    if (aliases.size !== side.modules.length || !aliases.has(side.entry_alias))
+        throw new TypeError("Replay manifest aliases or entry alias are invalid");
+    for (const module of side.modules)
+        for (const dependency of Object.values(module.dependencies))
+            if (!aliases.has(dependency))
+                throw new TypeError(`Undeclared replay dependency alias: ${dependency}`);
+    const loaded = [];
+    let totalBytes = 0;
+    for (const module of side.modules) {
+        const remaining = maximumBytes - totalBytes;
+        if (remaining <= 0)
+            throw new RangeError("Replay module bytes exceed the aggregate limit");
+        const source = await host.readSource(module.path, remaining);
+        totalBytes += source.bytes.byteLength;
+        loaded.push({ module, source });
+    }
+    return {
+        commitment: {
+            modules: loaded.map(({ module, source }) => ({
+                alias: module.alias,
+                canonical_path: source.canonicalPath,
+                format: module.format,
+                role: module.role,
+                byte_count: source.bytes.byteLength,
+                sha256: digestBytes(source.bytes),
+                dependencies: module.dependencies,
+            })),
+            entry_alias: side.entry_alias,
+            entry_export: side.entry_export,
+        },
+        sources: Object.fromEntries(loaded.map(({ module, source }) => [
+            module.alias,
+            new TextDecoder("utf-8", { fatal: true }).decode(source.bytes),
+        ])),
+    };
+};
+const replayCases = (input) => {
+    const explicit = input.cases.map((item) => ({
+        case_id: item.case_id,
+        arguments: item.arguments,
+    }));
+    if (input.generator === undefined)
+        return uniqueCases(explicit);
+    let state = input.generator.seed || 0x9e37_79b9;
+    const next = () => {
+        state ^= state << 13;
+        state ^= state >>> 17;
+        state ^= state << 5;
+        return state >>> 0;
+    };
+    const corpus = boundaryCorpus(input.generator.preset);
+    const generated = Array.from({ length: input.generator.count }, (_, index) => ({
+        case_id: `generated-${input.generator?.preset ?? "boundary"}-${String(index)}`,
+        arguments: [corpus[next() % corpus.length] ?? ""],
+    }));
+    return uniqueCases([...explicit, ...generated]);
+};
+const uniqueCases = (cases) => {
+    const ids = new Set();
+    for (const item of cases) {
+        if (ids.has(item.case_id))
+            throw new TypeError(`Duplicate replay case ID: ${item.case_id}`);
+        ids.add(item.case_id);
+    }
+    return cases;
+};
+const boundaryCorpus = (preset) => {
+    if (preset === "sanitizer-boundaries")
+        return [
+            "",
+            "<script>alert(1)</script>",
+            "<img src=x onerror=alert(1)>",
+            "javascript:alert(1)",
+            "<b>ok</b>",
+            "\u0000",
+        ];
+    if (preset === "clipboard-boundaries")
+        return [
+            "",
+            "plain",
+            "a\r\nb",
+            "a\nb",
+            "\t",
+            "😀",
+            "text/html",
+            "text/plain",
+        ];
+    return [
+        "",
+        " ",
+        "\n",
+        "# heading",
+        "**bold**",
+        "[x](javascript:y)",
+        "`code`",
+        "😀",
+        "\u0000",
+        "a".repeat(1024),
+    ];
+};
+export const digestBytes = (value) => createHash("sha256").update(value).digest("hex");
+export const digestJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Replay commitment is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};

package/dist/application/JavaScriptReplayService.js

@@ -0,0 +1,266 @@
+import { z } from "zod";
+import writeFileAtomic from "write-file-atomic";
+import { controlledReplayInputSchema, replayExecutionResultSchema, controlledReplayOutputSchema, replayEvidenceSchema, } from "../domain/javascriptReplay.js";
+import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisProtocolError, PermissionRequiredError, ReplayPlanStaleError, } from "../domain/errors.js";
+import { createEvidence } from "../domain/evidence.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { digestBytes, prepareReplayPlan, } from "./JavaScriptReplayPlanning.js";
+const OPERATION = "run_controlled_replay";
+const isAborted = (signal) => signal?.aborted === true;
+/** Plan or execute one content-bound extracted-module replay experiment. */
+export const runControlledReplay = async (dependencies, rawInput, options = {}) => {
+    const parsed = controlledReplayInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+    return runControlledReplayValidated(dependencies, parsed.data, options);
+};
+/** Plan or execute replay input already parsed by a trusted adapter. */
+export const runControlledReplayValidated = async (dependencies, input, options = {}) => {
+    if (!dependencies.policy.enabled)
+        return err(new AnalysisCapabilityUnavailableError("rea-javascript-replay", OPERATION, "controlled replay is disabled; configure exact roots and executables before enabling it"));
+    if (dependencies.authority === undefined)
+        return err(new AnalysisCapabilityUnavailableError("rea-javascript-replay", OPERATION, "JavaScript replay permission policy is not configured"));
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(OPERATION));
+    const request = permissionRequest(input, dependencies.policy);
+    const authorized = input.mode === "plan"
+        ? await dependencies.authority.explain(request, "read")
+        : await dependencies.authority.authorize(request, "read");
+    if (!authorized.ok)
+        return err(authorized.error instanceof PermissionRequiredError
+            ? authorized.error
+            : new AnalysisProtocolError(authorized.error.message, {
+                cause: authorized.error,
+            }));
+    let prepared;
+    try {
+        prepared = await prepareReplayPlan(input, dependencies.policy, dependencies.host);
+    }
+    catch (cause) {
+        return err(new AnalysisCapabilityUnavailableError("rea-javascript-replay", OPERATION, cause instanceof Error ? cause.message : "replay planning failed"));
+    }
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(OPERATION));
+    if (input.mode === "plan")
+        return ok(asJson({
+            phase: "plan",
+            plan: prepared.publicPlan,
+            source_evidence: [],
+            evidence: null,
+        }));
+    if (input.plan_digest !== prepared.publicPlan.plan_digest)
+        return err(new ReplayPlanStaleError(input.plan_digest ?? "", prepared.publicPlan.plan_digest));
+    let canonicalExportPath;
+    if (input.reproducer_export !== undefined) {
+        if (input.reproducer_export.approved !== true)
+            return err(new AnalysisInputError(`${OPERATION}:reproducer_export`));
+        const exportAuthorized = await dependencies.authority.authorize({
+            capability: "evidence_write",
+            roots: [input.reproducer_export.path],
+            executables: [],
+            environment_names: [],
+            network: "none",
+            mount: false,
+            operation_identity: `${OPERATION}:reproducer:${prepared.publicPlan.plan_digest}`,
+        }, "write");
+        if (!exportAuthorized.ok)
+            return err(exportAuthorized.error instanceof PermissionRequiredError
+                ? exportAuthorized.error
+                : new AnalysisProtocolError(exportAuthorized.error.message, {
+                    cause: exportAuthorized.error,
+                }));
+        canonicalExportPath = exportAuthorized.value.request.roots[0];
+        if (canonicalExportPath !== input.reproducer_export.path)
+            return err(new AnalysisInputError(`${OPERATION}:reproducer_export:path`, {
+                cause: new TypeError(`Use the canonical reproducer path: ${canonicalExportPath ?? "unavailable"}`),
+            }));
+    }
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(OPERATION));
+    await options.progress?.report({
+        phase: OPERATION,
+        completed: 0,
+        total: 1,
+        message: "Admitting approved modules into the isolated replay worker",
+    });
+    if (isAborted(options.signal))
+        return err(new AnalysisCancelledError(OPERATION));
+    try {
+        let executed = replayExecutionResultSchema.parse(await dependencies.runner.execute(prepared, dependencies.policy, options.signal));
+        await options.progress?.report({
+            phase: OPERATION,
+            completed: 1,
+            total: 1,
+            message: "Controlled replay stopped and sandbox cleanup was observed",
+            terminal: true,
+        });
+        if (executed.termination === "cancelled")
+            return err(new AnalysisCancelledError(OPERATION));
+        if (input.reproducer_export !== undefined &&
+            canonicalExportPath !== undefined &&
+            executed.cleanup.state === "complete") {
+            const manifest = {
+                schema_version: 1,
+                plan: prepared.publicPlan,
+                result: executed,
+                sources: input.reproducer_export.include_sources
+                    ? {
+                        left: prepared.leftSources,
+                        ...(prepared.rightSources === undefined
+                            ? {}
+                            : { right: prepared.rightSources }),
+                    }
+                    : null,
+            };
+            const encoded = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+            try {
+                await writeFileAtomic(canonicalExportPath, encoded, {
+                    mode: 0o600,
+                });
+                executed = replayExecutionResultSchema.parse({
+                    ...executed,
+                    reproducer: {
+                        state: "written",
+                        path: canonicalExportPath,
+                        sha256: digestBytes(encoded),
+                    },
+                });
+            }
+            catch (cause) {
+                executed = replayExecutionResultSchema.parse({
+                    ...executed,
+                    limitations: [
+                        ...executed.limitations,
+                        "Replay completed, but the separately approved reproducer export failed.",
+                    ],
+                    reproducer: {
+                        state: "failed",
+                        path: canonicalExportPath,
+                        error: cause instanceof Error
+                            ? cause.message
+                            : "unknown reproducer export failure",
+                    },
+                });
+            }
+        }
+        const leftCount = prepared.publicPlan.cases.length;
+        const sourceEvidence = [
+            createReplayEvidence(prepared, executed, "left", executed.outcomes.slice(0, leftCount)),
+            ...(prepared.publicPlan.right === undefined
+                ? []
+                : [
+                    createReplayEvidence(prepared, executed, "right", executed.outcomes.slice(leftCount)),
+                ]),
+        ];
+        const subject = prepared.publicPlan.left.modules[0];
+        const evidence = createEvidence(subject === undefined
+            ? undefined
+            : {
+                path: subject.canonical_path,
+                sha256: subject.sha256,
+                format: "javascript",
+            }, {
+            id: "rea-javascript-replay",
+            name: "REA isolated JavaScript replay",
+            version: "1",
+        }, {
+            predicateType: "javascript-controlled-replay",
+            operation: OPERATION,
+            parameters: {
+                replay_plan: jsonValueSchema.parse(JSON.parse(JSON.stringify(prepared.publicPlan))),
+            },
+            result: jsonValueSchema.parse(JSON.parse(JSON.stringify(executed))),
+            rawResult: jsonValueSchema.parse(JSON.parse(JSON.stringify({
+                cases: prepared.publicPlan.cases,
+                outcomes: executed.outcomes,
+                stderr: executed.stderr,
+            }))),
+            confidence: executed.comparison === undefined ? "observed" : "derived",
+            authority: "controlled-replay",
+            environment: {
+                id: prepared.publicPlan.plan_digest,
+                platform: process.platform,
+                architecture: process.arch,
+                isolation: "container",
+            },
+            limitations: executed.limitations,
+            locations: prepared.publicPlan.left.modules.map((module) => ({
+                kind: "artifact-path",
+                path: module.canonical_path,
+            })),
+            evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id),
+        });
+        return ok(asJson({
+            phase: "execute",
+            plan: null,
+            source_evidence: sourceEvidence.map((item) => replayEvidenceSchema.parse(item)),
+            evidence: replayEvidenceSchema.parse(evidence),
+        }));
+    }
+    catch (cause) {
+        return err(new AnalysisProtocolError(cause instanceof z.ZodError
+            ? "Controlled replay produced an invalid bounded result"
+            : "Controlled replay could not establish or clean up its sandbox", { cause }));
+    }
+};
+const createReplayEvidence = (prepared, executed, side, outcomes) => {
+    const manifest = side === "left" ? prepared.publicPlan.left : prepared.publicPlan.right;
+    const subject = manifest?.modules[0];
+    const result = replayExecutionResultSchema.parse({
+        ...executed,
+        outcomes,
+        comparison: undefined,
+        reproducer: null,
+    });
+    return createEvidence(subject === undefined
+        ? undefined
+        : {
+            path: subject.canonical_path,
+            sha256: subject.sha256,
+            format: "javascript",
+        }, {
+        id: "rea-javascript-replay",
+        name: "REA isolated JavaScript replay",
+        version: "1",
+    }, {
+        predicateType: "javascript-controlled-replay-observation",
+        operation: OPERATION,
+        parameters: {
+            replay_plan: jsonValueSchema.parse(JSON.parse(JSON.stringify(prepared.publicPlan))),
+            side,
+        },
+        result: jsonValueSchema.parse(JSON.parse(JSON.stringify(result))),
+        rawResult: jsonValueSchema.parse(JSON.parse(JSON.stringify({ cases: prepared.publicPlan.cases, outcomes }))),
+        confidence: "observed",
+        authority: "controlled-replay",
+        environment: {
+            id: prepared.publicPlan.plan_digest,
+            platform: process.platform,
+            architecture: process.arch,
+            isolation: "container",
+        },
+        limitations: executed.limitations,
+        locations: (manifest?.modules ?? []).map((module) => ({
+            kind: "artifact-path",
+            path: module.canonical_path,
+        })),
+    });
+};
+const asJson = (value) => jsonValueSchema.parse(JSON.parse(JSON.stringify(controlledReplayOutputSchema.parse(value))));
+const permissionRequest = (input, policy) => ({
+    capability: "javascript_replay",
+    roots: [...input.left.modules, ...(input.right?.modules ?? [])].map(({ path }) => path),
+    executables: [
+        policy.nodePath,
+        policy.bubblewrapPath,
+        policy.systemdRunPath,
+        policy.systemctlPath,
+        policy.shellPath,
+    ],
+    environment_names: [],
+    network: "none",
+    mount: true,
+    operation_identity: `${OPERATION}:${input.plan_digest ?? "plan"}`,
+});

package/dist/application/JavaScriptRuntimeReconciliationEvidence.js

@@ -0,0 +1,25 @@
+import { createEvidence, } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER } from "./InvestigationProviders.js";
+/** Create derived Evidence v2 for one exact set of static/runtime inputs. */
+export const createJavaScriptRuntimeReconciliationEvidence = (input, result) => createEvidence(undefined, JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER, {
+    predicateType: "rea.javascript-runtime-reconciliation/v1",
+    operation: "reconcile_javascript_runtime",
+    parameters: parameters(input),
+    result: jsonValueSchema.parse(result),
+    rawResult: null,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    environment: null,
+    limitations: result.limitations,
+    evidenceLinks: result.evidence_links,
+});
+const parameters = (input) => ({
+    static_layers: input.static_layers.map((layer) => ({
+        role: layer.role,
+        evidence_id: layer.analysis.evidence_id,
+        runtime_mappings: layer.runtime_mappings,
+    })),
+    runtime_evidence_ids: input.runtime_observations.map(({ evidence_id: id }) => id),
+    limits: input.limits,
+});

package/dist/application/JavaScriptRuntimeReconciliationService.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { reconcileJavaScriptRuntime } from "../domain/javascriptRuntimeReconciliation.js";
+import { reconcileJavaScriptRuntimeInputSchema } from "../domain/javascriptRuntimeReconciliationSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { createJavaScriptRuntimeReconciliationEvidence } from "./JavaScriptRuntimeReconciliationEvidence.js";
+const OPERATION = "reconcile_javascript_runtime";
+/** Derive a combined JAG from verified static and passive-runtime Evidence. */
+export const reconcileJavaScriptRuntimeEvidence = (rawInput) => {
+    const parsed = reconcileJavaScriptRuntimeInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(parsed.error.issues, rawInput)));
+    return reconcileJavaScriptRuntimeEvidenceValidated(parsed.data);
+};
+/** Reconcile input already parsed by a trusted adapter boundary. */
+export const reconcileJavaScriptRuntimeEvidenceValidated = (input) => {
+    try {
+        const result = reconcileJavaScriptRuntime(input);
+        return ok(createJavaScriptRuntimeReconciliationEvidence(input, result));
+    }
+    catch (cause) {
+        return err(cause instanceof z.ZodError || cause instanceof TypeError
+            ? new AnalysisInputError(OPERATION)
+            : new AnalysisProtocolError("JavaScript runtime reconciliation produced an invalid result", { cause }));
+    }
+};

package/dist/application/ManagedApplicationGraphService.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { managedApplicationGraphResultSchema, projectManagedApplicationGraph, projectManagedApplicationGraphInputSchema, } from "../domain/managedApplicationGraph.js";
+import { err, ok } from "../domain/result.js";
+import { MANAGED_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
+const OPERATION = "project_managed_application_graph";
+/** Project authenticated managed Evidence into a provider-neutral graph. */
+export const projectManagedApplicationGraphEvidence = (rawInput) => {
+    const parsed = projectManagedApplicationGraphInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+    try {
+        const result = projectManagedApplicationGraph(parsed.data);
+        return ok(createManagedApplicationGraphEvidence(parsed.data, result));
+    }
+    catch (cause) {
+        return err(cause instanceof TypeError || cause instanceof z.ZodError
+            ? new AnalysisInputError(OPERATION, { cause })
+            : new AnalysisProtocolError("Managed application graph projection produced an invalid result", { cause }));
+    }
+};
+const createManagedApplicationGraphEvidence = (input, result) => createEvidence(subjectTarget(input), MANAGED_WORKFLOW_PROVIDER, {
+    predicateType: "rea.managed-application-graph/v1",
+    operation: OPERATION,
+    parameters: {
+        managed_artifact_evidence_id: input.managed_artifact?.evidence_id ?? null,
+        managed_members_evidence_id: input.managed_members?.evidence_id ?? null,
+        managed_native_boundaries_evidence_id: input.managed_native_boundaries?.evidence_id ?? null,
+        limits: jsonValueSchema.parse(input.limits),
+    },
+    result: jsonValueSchema.parse(managedApplicationGraphResultSchema.parse(result)),
+    rawResult: null,
+    confidence: "inferred",
+    authority: "analyst-inference",
+    environment: null,
+    limitations: result.limitations,
+    evidenceLinks: result.evidence_links,
+});
+const subjectTarget = (input) => {
+    const subject = input.managed_artifact?.subject ??
+        input.managed_members?.subject ??
+        input.managed_native_boundaries?.subject;
+    if (subject === undefined || subject === null || subject.format !== "pe")
+        return undefined;
+    return {
+        path: subject.local_path,
+        sha256: subject.digest.sha256,
+        format: "pe",
+        ...(subject.architecture === null
+            ? {}
+            : { architecture: subject.architecture }),
+    };
+};