rea-agents 0.3.0 → 0.4.0

package/dist/artifacts/ArtifactProvider.js

@@ -0,0 +1,130 @@
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { inventoryArtifact } from "../application/ArtifactInventory.js";
+import { extractArtifact } from "../application/ArtifactExtraction.js";
+import { ARTIFACT_TOOL_CONTRACTS, artifactInventoryInputSchema, artifactExtractionInputSchema, } from "../contracts/artifactToolContracts.js";
+import { AnalysisCapabilityUnavailableError, ArtifactOperationError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+const IDENTITY = Object.freeze({
+    id: "rea-artifact-graph",
+    name: "REA safe artifact graph provider",
+    version: "1",
+});
+/** Read-only inventory and exclusively owned extraction provider. */
+export class ArtifactProvider {
+    #capabilities = Object.freeze(ARTIFACT_TOOL_CONTRACTS.map((contract) => Object.freeze({
+        provider: IDENTITY,
+        operation: contract.name,
+        inputContractVersion: 1,
+        outputContractVersion: 1,
+        available: true,
+        reason: null,
+        pagination: "offset",
+        exhaustive: false,
+        effects: Object.freeze({
+            mutatesArtifact: false,
+            launchesProcess: true,
+            mayShowUi: false,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: contract.name === "extract_artifact",
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limits: Object.freeze({
+            maxResults: 500,
+            maxPayloadBytes: 4 * 1024 * 1024,
+            timeoutMs: 120_000,
+        }),
+        limitations: Object.freeze([
+            "DMG and PKG child inventory requires a future native read-only adapter.",
+            "Nested containers are recorded but not recursively expanded implicitly.",
+        ]),
+    })));
+    identity() {
+        return IDENTITY;
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    createClient(target) {
+        return new ArtifactClient(target);
+    }
+}
+class ArtifactClient {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    async execute(operation, parameters, options) {
+        if (operation === "health")
+            return ok(createAnalysisExecution(null, IDENTITY));
+        if (!isArtifactOperation(operation))
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by artifact graph provider."));
+        try {
+            if (operation === "extract_artifact") {
+                const parsed = artifactExtractionInputSchema.parse(parameters);
+                const result = await extractArtifact({
+                    inputPath: this.target.sourcePath ?? this.target.path,
+                    inputFormat: this.target.format,
+                    outputRoot: parsed.output_root,
+                    occurrenceIds: parsed.occurrence_ids,
+                    offset: parsed.offset,
+                    limit: parsed.limit,
+                    limits: limitsFrom(parsed),
+                }, options?.signal);
+                return ok(createAnalysisExecution(result, IDENTITY, {
+                    rawResult: null,
+                    limitations: result.limitations,
+                    subject: subjectFor(this.target.sourcePath ?? this.target.path, result.manifest),
+                    locations: result.artifacts.items.map(({ relative_path: path }) => ({
+                        kind: "artifact-path",
+                        path,
+                    })),
+                }));
+            }
+            const parsed = artifactInventoryInputSchema.parse(parameters);
+            const result = await inventoryArtifact(this.target.sourcePath ?? this.target.path, limitsFrom(parsed), {
+                nodeOffset: parsed.node_offset,
+                nodeLimit: parsed.node_limit,
+                occurrenceOffset: parsed.occurrence_offset,
+                occurrenceLimit: parsed.occurrence_limit,
+                edgeOffset: parsed.edge_offset,
+                edgeLimit: parsed.edge_limit,
+            }, options?.signal);
+            return ok(createAnalysisExecution(result, IDENTITY, {
+                rawResult: null,
+                limitations: result.limitations,
+                subject: subjectFor(this.target.sourcePath ?? this.target.path, result.manifest),
+                locations: result.occurrences.items.map(({ logical_path: path }) => ({
+                    kind: "artifact-path",
+                    path,
+                })),
+            }));
+        }
+        catch (cause) {
+            return err(translateFailure(operation, cause));
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+}
+const limitsFrom = (input) => ({
+    maxEntries: input.max_entries,
+    maxTotalBytes: input.max_total_bytes,
+    maxEntryBytes: input.max_entry_bytes,
+    maxCompressionRatio: input.max_compression_ratio,
+    maxDepth: input.max_depth,
+    maxPathBytes: input.max_path_bytes,
+});
+const isArtifactOperation = (operation) => ARTIFACT_TOOL_CONTRACTS.some(({ name }) => name === operation);
+const translateFailure = (operation, cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return new ArtifactOperationError(operation, cause.reason);
+    return new ArtifactOperationError(operation, "io");
+};
+const subjectFor = (path, manifest) => ({
+    path,
+    sha256: manifest.root_sha256,
+    format: manifest.root_format,
+});

package/dist/artifacts/ArtifactReader.js

@@ -0,0 +1,9 @@
+/** Typed adapter failure translated at provider boundary. */
+export class ArtifactReaderFailure extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "ArtifactReaderFailure";
+    }
+}

package/dist/artifacts/AsarArtifactReader.js

@@ -0,0 +1,62 @@
+import { Readable } from "node:stream";
+import { extractFile, listPackage, statFile } from "@electron/asar";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Official Electron ASAR adapter. Individual files remain caller-bounded. */
+export class AsarArtifactReader {
+    path;
+    format = "asar";
+    constructor(path) {
+        this.path = path;
+    }
+    async *entries(signal) {
+        const paths = listPackage(this.path, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
+        for (const listed of paths) {
+            abortIfNeeded(signal);
+            const path = listed.replace(/^\/+|\/+$/gu, "");
+            if (path.length === 0)
+                continue;
+            const metadata = statFile(this.path, path, false);
+            const kind = "files" in metadata
+                ? "directory"
+                : "link" in metadata
+                    ? "symlink"
+                    : "file";
+            yield {
+                path,
+                kind,
+                declaredSize: "size" in metadata ? metadata.size : null,
+                compressedSize: null,
+                executable: "executable" in metadata && metadata.executable,
+                encrypted: false,
+                byteOffset: null,
+                declaredSha256: "integrity" in metadata &&
+                    metadata.integrity.algorithm === "SHA256" &&
+                    /^[a-f0-9]{64}$/u.test(metadata.integrity.hash)
+                    ? metadata.integrity.hash
+                    : null,
+                limitations: kind === "symlink"
+                    ? ["ASAR symlink target was not followed or disclosed."]
+                    : [
+                        "Official ASAR extraction buffers each individually bounded file.",
+                    ],
+                adapterKey: path,
+            };
+        }
+    }
+    open(entry, signal) {
+        abortIfNeeded(signal);
+        if (entry.kind !== "file")
+            return Promise.reject(new ArtifactReaderFailure("format", "ASAR entry is not a regular file"));
+        return Promise.resolve(Readable.from(extractFile(this.path, entry.adapterKey, false)));
+    }
+    close() {
+        return Promise.resolve();
+    }
+    provenance() {
+        return [];
+    }
+}
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+};

package/dist/artifacts/DirectoryArtifactReader.js

@@ -0,0 +1,107 @@
+import { constants } from "node:fs";
+import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Deterministic, non-symlink-following directory reader. */
+export class DirectoryArtifactReader {
+    format = "directory";
+    #rootPromise;
+    constructor(root) {
+        this.#rootPromise = realpath(root);
+    }
+    async *entries(signal) {
+        const root = await this.#rootPromise;
+        const pending = [root];
+        while (pending.length > 0) {
+            abortIfNeeded(signal);
+            const directory = pending.pop();
+            if (directory === undefined)
+                break;
+            await assertContainedDirectory(root, directory);
+            const children = [];
+            const handle = await opendir(directory);
+            try {
+                for await (const child of handle)
+                    children.push(child.name);
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+            await assertContainedDirectory(root, directory);
+            children.sort((left, right) => left.localeCompare(right, "en"));
+            const directories = [];
+            for (const name of children) {
+                abortIfNeeded(signal);
+                const absolute = join(directory, name);
+                const metadata = await lstat(absolute);
+                const path = relative(root, absolute).split(sep).join("/");
+                const kind = metadata.isSymbolicLink()
+                    ? "symlink"
+                    : metadata.isDirectory()
+                        ? "directory"
+                        : metadata.isFile()
+                            ? "file"
+                            : undefined;
+                if (kind === undefined)
+                    continue;
+                if (kind === "directory")
+                    directories.push(absolute);
+                yield {
+                    path,
+                    kind,
+                    declaredSize: kind === "file" ? metadata.size : null,
+                    compressedSize: null,
+                    executable: (metadata.mode & 0o111) !== 0,
+                    encrypted: false,
+                    byteOffset: null,
+                    declaredSha256: null,
+                    limitations: kind === "symlink"
+                        ? ["Symlink target was not followed or disclosed."]
+                        : [],
+                    adapterKey: absolute,
+                    ...(kind === "file"
+                        ? { sourceIdentity: { device: metadata.dev, inode: metadata.ino } }
+                        : {}),
+                };
+            }
+            directories.reverse();
+            pending.push(...directories);
+        }
+    }
+    async open(entry, signal) {
+        abortIfNeeded(signal);
+        if (entry.kind !== "file")
+            throw new ArtifactReaderFailure("format", "Only regular files can be opened");
+        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const observed = await handle.stat();
+        if (!observed.isFile() ||
+            entry.sourceIdentity === undefined ||
+            observed.dev !== entry.sourceIdentity.device ||
+            observed.ino !== entry.sourceIdentity.inode) {
+            await handle.close();
+            throw new ArtifactReaderFailure("integrity", `Directory entry changed before open: ${entry.path}`);
+        }
+        return handle.createReadStream({ autoClose: true });
+    }
+    close() {
+        return Promise.resolve();
+    }
+    provenance() {
+        return [];
+    }
+}
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "Artifact traversal cancelled");
+};
+const assertContainedDirectory = async (root, directory) => {
+    const canonical = await realpath(directory);
+    const fromRoot = relative(root, canonical);
+    const metadata = await lstat(directory);
+    if (metadata.isSymbolicLink() ||
+        !metadata.isDirectory() ||
+        fromRoot === ".." ||
+        fromRoot.startsWith(`..${sep}`) ||
+        isAbsolute(fromRoot))
+        throw new ArtifactReaderFailure("path", "Directory traversal escaped or changed its artifact root");
+};

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -0,0 +1,66 @@
+import { createReadStream } from "node:fs";
+import { XcrunCommandRunner, } from "../native/CommandRunner.js";
+import { parseLipoArchitectures } from "../native/parsers/lipo.js";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Read-only universal Mach-O slice reader backed by native lipo metadata. */
+export class MachOSliceArtifactReader {
+    path;
+    runner;
+    format = "file";
+    #command;
+    constructor(path, runner = new XcrunCommandRunner()) {
+        this.path = path;
+        this.runner = runner;
+    }
+    async *entries(signal) {
+        const captured = await this.runner.run("lipo", ["-detailed_info", this.path], {
+            ...(signal === undefined ? {} : { signal }),
+            timeoutMs: 30_000,
+            maxOutputBytes: 4 * 1024 * 1024,
+        });
+        if (!captured.ok)
+            throw new ArtifactReaderFailure(captured.error.reason === "cancelled" ? "cancelled" : "unavailable", "lipo could not enumerate universal Mach-O slices", { cause: captured.error });
+        this.#command = {
+            tool: captured.value.tool,
+            arguments: ["-detailed_info", "$ARTIFACT"],
+            tool_version: captured.value.toolVersion,
+            executable_sha256: captured.value.executableSha256,
+            exit_code: captured.value.exitCode,
+            effects: ["read"],
+        };
+        for (const architecture of parseLipoArchitectures(captured.value.stdout)) {
+            if (architecture.file_offset === null || architecture.size === null)
+                throw new ArtifactReaderFailure("integrity", "lipo omitted a universal slice byte range");
+            yield {
+                path: `slices/${architecture.name}`,
+                kind: "slice",
+                declaredSize: architecture.size,
+                compressedSize: null,
+                executable: true,
+                encrypted: false,
+                byteOffset: architecture.file_offset,
+                declaredSha256: null,
+                limitations: [],
+                adapterKey: `${String(architecture.file_offset)}:${String(architecture.size)}`,
+            };
+        }
+    }
+    open(entry, signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled"));
+        const [offsetText, sizeText] = entry.adapterKey.split(":");
+        const offset = Number(offsetText);
+        const size = Number(sizeText);
+        if (!Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(size) ||
+            size <= 0)
+            return Promise.reject(new ArtifactReaderFailure("integrity", "Invalid Mach-O slice byte range"));
+        return Promise.resolve(createReadStream(this.path, { start: offset, end: offset + size - 1 }));
+    }
+    provenance() {
+        return this.#command === undefined ? [] : [this.#command];
+    }
+    close() {
+        return Promise.resolve();
+    }
+}

package/dist/artifacts/SafeOutputTree.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { streamChunkToBuffer } from "./StreamBytes.js";
+import { ArtifactPathRegistry, normalizeArtifactPath, } from "./ArtifactPaths.js";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Symlink-resistant materialization in an exclusively owned, initially absent tree. */
+export class SafeOutputTree {
+    #registry = new ArtifactPathRegistry();
+    #limits;
+    #outputRoot;
+    #stagingRoot;
+    #totalBytes = 0;
+    #published = false;
+    #cleanup = {
+        attempted: false,
+        verified: false,
+        residualPaths: [],
+    };
+    constructor(outputRoot, stagingRoot, limits) {
+        this.#outputRoot = outputRoot;
+        this.#stagingRoot = stagingRoot;
+        this.#limits = limits;
+    }
+    /** Exclusively create the absent destination as this operation's owned tree. */
+    static async create(outputRoot, limits) {
+        if (!isAbsolute(outputRoot))
+            throw new ArtifactReaderFailure("path", "Extraction output root must be absolute");
+        const requested = resolve(outputRoot);
+        const name = basename(requested);
+        if (name === "." || name === "..")
+            throw new ArtifactReaderFailure("path", "Invalid extraction output root");
+        const parent = await realpath(dirname(requested)).catch((cause) => {
+            throw new ArtifactReaderFailure("unavailable", "Extraction output parent is unavailable", { cause });
+        });
+        const canonicalOutput = join(parent, name);
+        await mkdir(canonicalOutput, { mode: 0o700 }).catch((cause) => {
+            if (isAlreadyExists(cause))
+                throw new ArtifactReaderFailure("path", "Extraction output root already exists", { cause });
+            throw cause;
+        });
+        try {
+            const stagingHandle = await open(canonicalOutput, constants.O_RDONLY | constants.O_DIRECTORY);
+            try {
+                await stagingHandle.chmod(0o700);
+            }
+            finally {
+                await stagingHandle.close();
+            }
+            return new SafeOutputTree(canonicalOutput, canonicalOutput, limits);
+        }
+        catch (cause) {
+            await rm(canonicalOutput, { recursive: true, force: true });
+            throw cause;
+        }
+    }
+    get outputRoot() {
+        return this.#outputRoot;
+    }
+    get cleanup() {
+        return this.#cleanup;
+    }
+    /** Stream one selected regular file with exact byte and digest verification. */
+    async write(relativePath, source, expectedSha256, signal) {
+        this.#assertWritable();
+        const path = normalizeArtifactPath(relativePath, this.#limits);
+        this.#registry.add(path, "file");
+        const destination = await this.#prepareParent(path);
+        const handle = await open(destination, constants.O_CREAT |
+            constants.O_EXCL |
+            constants.O_WRONLY |
+            constants.O_NOFOLLOW, 0o600).catch((cause) => {
+            throw new ArtifactReaderFailure("path", `Could not exclusively create extraction path: ${path}`, { cause });
+        });
+        const hash = createHash("sha256");
+        let bytes = 0;
+        try {
+            for await (const raw of source) {
+                abortIfNeeded(signal);
+                const chunk = streamChunkToBuffer(raw);
+                bytes += chunk.length;
+                if (bytes > this.#limits.maxEntryBytes)
+                    throw new ArtifactReaderFailure("limit", `Observed entry bytes exceed limit: ${path}`);
+                if (this.#totalBytes + bytes > this.#limits.maxTotalBytes)
+                    throw new ArtifactReaderFailure("limit", "Observed extraction bytes exceed cumulative limit");
+                hash.update(chunk);
+                await writeAll(handle, chunk);
+            }
+            const sha256 = hash.digest("hex");
+            if (sha256 !== expectedSha256)
+                throw new ArtifactReaderFailure("integrity", `Extracted content disagrees with inventory: ${path}`);
+            await handle.sync();
+            await handle.close();
+            const readback = await hashFile(destination, bytes, signal);
+            if (readback.sha256 !== sha256 || readback.bytes !== bytes)
+                throw new ArtifactReaderFailure("integrity", `Durable readback verification failed: ${path}`);
+            this.#totalBytes += bytes;
+            return { relativePath: path, sha256, bytesWritten: bytes };
+        }
+        catch (cause) {
+            await handle.close().catch(() => undefined);
+            throw cause;
+        }
+    }
+    /** Sync the owned output tree and prevent further writes through this instance. */
+    async commit() {
+        this.#assertWritable();
+        const parent = await open(dirname(this.#outputRoot), constants.O_RDONLY | constants.O_DIRECTORY);
+        const staging = await open(this.#stagingRoot, constants.O_RDONLY | constants.O_DIRECTORY);
+        try {
+            await staging.sync();
+            await parent.sync();
+            this.#published = true;
+        }
+        catch (cause) {
+            throw new ArtifactReaderFailure("path", "Could not durably sync extraction output", { cause });
+        }
+        finally {
+            await Promise.allSettled([parent.close(), staging.close()]);
+        }
+    }
+    /** Remove only this operation's unsealed tree and verify absence. */
+    async rollback() {
+        if (this.#published)
+            return this.#cleanup;
+        await rm(this.#stagingRoot, { recursive: true, force: true });
+        const absent = await isAbsent(this.#stagingRoot);
+        this.#cleanup = {
+            attempted: true,
+            verified: absent,
+            residualPaths: absent ? [] : [basename(this.#stagingRoot)],
+        };
+        if (!absent)
+            throw new ArtifactReaderFailure("integrity", "Extraction output cleanup could not be verified");
+        return this.#cleanup;
+    }
+    async #prepareParent(relativePath) {
+        const parts = relativePath.split("/");
+        const fileName = parts.pop();
+        if (fileName === undefined)
+            throw new ArtifactReaderFailure("path", "Invalid extraction path");
+        let current = this.#stagingRoot;
+        for (const part of parts) {
+            current = join(current, part);
+            await mkdir(current, { mode: 0o700 }).catch((cause) => {
+                if (!isAlreadyExists(cause))
+                    throw cause;
+            });
+            const metadata = await lstat(current);
+            if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                throw new ArtifactReaderFailure("path", `Unsafe extraction parent: ${relativePath}`);
+        }
+        return join(current, fileName);
+    }
+    #assertWritable() {
+        if (this.#published)
+            throw new ArtifactReaderFailure("integrity", "Extraction tree is already committed");
+    }
+}
+const hashFile = async (path, maximum, signal) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const hash = createHash("sha256");
+    let bytes = 0;
+    try {
+        for await (const raw of handle.createReadStream({ autoClose: false })) {
+            abortIfNeeded(signal);
+            const chunk = streamChunkToBuffer(raw);
+            bytes += chunk.length;
+            if (bytes > maximum)
+                throw new ArtifactReaderFailure("integrity", "Readback exceeded the bytes written");
+            hash.update(chunk);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return { sha256: hash.digest("hex"), bytes };
+};
+const writeAll = async (handle, chunk) => {
+    let offset = 0;
+    while (offset < chunk.length) {
+        const { bytesWritten } = await handle.write(chunk, offset, chunk.length - offset);
+        if (bytesWritten === 0)
+            throw new ArtifactReaderFailure("unavailable", "Extraction output stopped accepting bytes");
+        offset += bytesWritten;
+    }
+};
+const isAbsent = async (path) => lstat(path).then(() => false, (cause) => {
+    if (isNotFound(cause))
+        return true;
+    throw cause;
+});
+const isNotFound = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const isAlreadyExists = (cause) => cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled");
+};

package/dist/artifacts/StreamBytes.js

@@ -0,0 +1,10 @@
+/** Parse a Node readable chunk without unchecked coercion. */
+export const streamChunkToBuffer = (value) => {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (value instanceof Uint8Array)
+        return Buffer.from(value);
+    if (typeof value === "string")
+        return Buffer.from(value);
+    throw new TypeError("Readable stream emitted a non-byte chunk");
+};