rea-agents 1.7.0 → 2.1.0

package/dist/application/JavaScriptModuleRelationships.js

@@ -0,0 +1,262 @@
+import { posix } from "node:path";
+import { addAstContainsEdge, artifactLocalIdentity, } from "./JavaScriptArtifactGraphContext.js";
+import { astObservationEvidence, completeReconstructionCoverage, partialReconstructionCoverage, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+import { resolveArtifactPathByContext } from "./JavaScriptArtifactPathResolution.js";
+/** Create one path-scoped source-module identity for every analyzed source file. */
+export const addJavaScriptSourceModules = (context) => {
+    for (const analyzed of context.analysis.files) {
+        const { file, semantic } = analyzed;
+        const asset = context.assetNodes.get(file.path);
+        const program = semantic?.ir.scopes.find(({ kind }) => kind === "program");
+        if (asset === undefined || semantic === null || program === undefined)
+            continue;
+        const exports = semantic.ir.moduleLinks
+            .flatMap(({ exportedName }) => exportedName === null ? [] : [exportedName])
+            .sort(compareCodePoints);
+        const retainedExports = [...new Set(exports)].slice(0, 128);
+        const source = context.accumulator.addNode({
+            kind: "javascript-module",
+            identity: artifactLocalIdentity(file.sha256, "source-module", `${file.container_sha256}:${file.path}`),
+            observations: [
+                {
+                    label: file.path,
+                    properties: {
+                        semantic_role: "source-module",
+                        path: file.path,
+                        container_sha256: file.container_sha256,
+                        logical_module_key: file.path,
+                        module_format: moduleFormat(file.path, semantic.ir),
+                        import_relationships: semantic.ir.moduleLinks.filter(({ kind }) => kind === "import" || kind === "require").length,
+                        export_relationships: exports.length,
+                        export_names: retainedExports,
+                        omitted_export_names: Math.max(0, exports.length - retainedExports.length),
+                    },
+                    evidence: astObservationEvidence({
+                        sha256: file.sha256,
+                        path: file.path,
+                        range: program.location,
+                        operation: "recover-source-module",
+                        coverage: semanticCoverage(semantic),
+                        limitations: semantic.ir.limitations,
+                    }),
+                },
+            ],
+        });
+        context.sourceModuleNodes.set(file.path, source);
+        addAstContainsEdge(context, {
+            source: asset,
+            target: source,
+            file,
+            range: program.location,
+            coverage: semanticCoverage(semantic),
+            properties: { logical_module_key: file.path },
+        });
+    }
+};
+/** Compose bounded CommonJS and ESM binding relationships across artifact files. */
+export const addJavaScriptModuleRelationships = (context) => {
+    for (const analyzed of context.analysis.files) {
+        const { file, semantic } = analyzed;
+        const source = context.sourceModuleNodes.get(file.path);
+        if (semantic === null || source === undefined)
+            continue;
+        for (const link of semantic.ir.moduleLinks) {
+            const input = { context, file, semantic, source, link };
+            if (isExportLink(link))
+                addExportRelationship(input);
+            else if (link.specifier !== null)
+                addImportRelationship(input, source, {
+                    specifier: link.specifier,
+                    importedPath: link.importedName === null ? [] : [link.importedName],
+                });
+        }
+    }
+};
+const addExportRelationship = (input) => {
+    const { context, file, semantic, source, link } = input;
+    if (link.exportedName === null)
+        return;
+    const exported = context.accumulator.addNode({
+        kind: "javascript-module",
+        identity: artifactLocalIdentity(file.sha256, "module-export", `${file.container_sha256}:${file.path}:${link.exportedName}`),
+        observations: [
+            {
+                label: `${file.path}:${link.exportedName}`,
+                properties: {
+                    semantic_role: "export-binding",
+                    module_path: file.path,
+                    relationship_kind: link.kind,
+                    exported_name: link.exportedName,
+                    local_name: link.localName,
+                    imported_name: link.importedName,
+                    declared_specifier: link.specifier,
+                },
+                evidence: astObservationEvidence({
+                    sha256: file.sha256,
+                    path: file.path,
+                    range: link.location,
+                    operation: "recover-module-export",
+                    coverage: semanticCoverage(semantic),
+                    limitations: semantic.ir.limitations,
+                }),
+            },
+        ],
+    });
+    context.accumulator.addEdge({
+        source_node_id: source.node_id,
+        target_node_id: exported.node_id,
+        relation: "exposes",
+        properties: relationshipProperties(link, null),
+        evidence: relationshipEvidence(input, "expose-module-export", []),
+    });
+    const origin = moduleOriginForExport(semantic.ir, link);
+    if (origin !== null)
+        addImportRelationship(input, exported, origin);
+};
+const addImportRelationship = (input, source, origin) => {
+    const target = resolveModuleTarget(input, origin.specifier);
+    input.context.accumulator.addEdge({
+        source_node_id: source.node_id,
+        target_node_id: target.node.node_id,
+        relation: "imports",
+        properties: relationshipProperties(input.link, target, origin),
+        evidence: relationshipEvidence(input, "resolve-semantic-module-relationship", target.limitations, target.status === "resolved"
+            ? "high"
+            : target.status === "external"
+                ? "medium"
+                : "low"),
+    });
+};
+const resolveModuleTarget = (input, specifier) => {
+    const resolution = resolveArtifactPathByContext({
+        declaredPath: specifier,
+        sourcePath: input.file.path,
+        context: "module-specifier",
+        files: input.context.filesByPath,
+        moduleKind: input.link.kind === "require" || input.link.kind === "commonjs-export"
+            ? "require"
+            : "import",
+    });
+    const path = resolution.resolved_path;
+    const file = path === null ? undefined : input.context.filesByPath.get(path);
+    const node = path === null
+        ? undefined
+        : (input.context.sourceModuleNodes.get(path) ??
+            input.context.fileNodes.get(path));
+    if (path !== null && file !== undefined && node !== undefined)
+        return {
+            node,
+            path,
+            file,
+            status: "resolved",
+            limitations: resolution.limitations,
+        };
+    return {
+        node: unresolvedModuleNode(input, specifier, resolution.resolution_status),
+        path: null,
+        file: null,
+        status: resolution.resolution_status,
+        limitations: resolution.limitations,
+    };
+};
+const unresolvedModuleNode = (input, specifier, status) => input.context.accumulator.addNode({
+    kind: "javascript-module",
+    identity: artifactLocalIdentity(input.file.sha256, "unresolved-semantic-module", `${status}:${specifier}`),
+    observations: [
+        {
+            label: specifier,
+            properties: {
+                semantic_role: "module-reference",
+                declared_specifier: specifier,
+                resolution_status: status,
+            },
+            evidence: staticInferenceEvidence({
+                sha256: input.file.sha256,
+                path: input.file.path,
+                range: input.link.location,
+                operation: "retain-unresolved-semantic-module",
+                coverage: semanticCoverage(input.semantic),
+                confidence: "low",
+                limitations: input.semantic.ir.limitations,
+            }),
+        },
+    ],
+});
+const moduleOriginForExport = (ir, link) => {
+    if (link.specifier !== null)
+        return {
+            specifier: link.specifier,
+            importedPath: link.importedName === null ? [] : [link.importedName],
+        };
+    if (link.localName === null)
+        return null;
+    const program = ir.scopes.find(({ kind }) => kind === "program");
+    const binding = ir.bindings.find(({ name, scopeId }) => name === link.localName && scopeId === program?.scopeId);
+    return binding?.provenance.status === "module" &&
+        binding.provenance.origins.length === 1
+        ? (binding.provenance.origins[0] ?? null)
+        : null;
+};
+const relationshipProperties = (link, target, origin) => ({
+    module_link_kind: link.kind,
+    specifier: origin?.specifier ?? link.specifier,
+    imported_name: origin?.importedPath.at(-1) ?? link.importedName,
+    imported_path: origin?.importedPath ?? [],
+    local_name: link.localName,
+    exported_name: link.exportedName,
+    resolved_path: target?.path ?? null,
+    resolution_status: target?.status ?? null,
+    target_file_kind: target?.file?.kind ?? null,
+    target_json_status: target?.file?.kind === "json" ? jsonStatus(target.file) : null,
+});
+const relationshipEvidence = (input, operation, limitations, confidence = "high") => staticInferenceEvidence({
+    sha256: input.file.sha256,
+    path: input.file.path,
+    range: input.link.location,
+    operation,
+    coverage: semanticCoverage(input.semantic),
+    confidence,
+    limitations: [...input.semantic.ir.limitations, ...limitations],
+});
+const semanticCoverage = (semantic) => {
+    const limits = Object.entries(semantic.limits).map(([name, value]) => ({
+        name: `semantic-${camelToKebab(name)}`,
+        value,
+        unit: "items",
+    }));
+    if (semantic.ir.coverage.status === "complete")
+        return completeReconstructionCoverage(limits);
+    return partialReconstructionCoverage(limits, semantic.ir.coverage.omittedCount, semantic.ir.coverage.status === "truncated");
+};
+const moduleFormat = (path, ir) => {
+    const extension = posix.extname(path).toLowerCase();
+    if (extension === ".mjs")
+        return "esm";
+    if (extension === ".cjs")
+        return "commonjs";
+    const esm = ir.moduleLinks.some(({ kind }) => ["import", "export", "re-export"].includes(kind));
+    const commonJs = ir.moduleLinks.some(({ kind }) => ["require", "commonjs-export"].includes(kind));
+    return esm && commonJs
+        ? "mixed"
+        : esm
+            ? "esm"
+            : commonJs
+                ? "commonjs"
+                : "unknown";
+};
+const jsonStatus = (file) => {
+    if (!file.text.included)
+        return "unavailable";
+    try {
+        JSON.parse(file.text.value);
+        return "included";
+    }
+    catch {
+        return "invalid";
+    }
+};
+const isExportLink = (link) => link.kind === "export" ||
+    link.kind === "re-export" ||
+    link.kind === "commonjs-export";
+const camelToKebab = (value) => value.replaceAll(/([a-z])([A-Z])/gu, "$1-$2").toLowerCase();
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/application/JavaScriptReplayPermission.js

@@ -0,0 +1,16 @@
+/** Build the exact permission request for one controlled replay operation. */
+export const replayPermissionRequest = (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: `run_controlled_replay:${input.plan_digest ?? "plan"}`,
+});

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");
+};