rea-agents 6.3.0 → 6.5.0

package/dist/go/GoBinaryContainer.js

@@ -0,0 +1,140 @@
+/** Distinguish corrupt recognized binaries from containers outside parser coverage. */
+export class GoBinaryFormatFailure extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "GoBinaryFormatFailure";
+    }
+}
+/** Resource boundary exceeded while decoding metadata or native container structure. */
+export class GoBinaryResourceFailure extends Error {
+    boundary;
+    maximum_bytes;
+    constructor(boundary, maximum_bytes, message) {
+        super(message);
+        this.boundary = boundary;
+        this.maximum_bytes = maximum_bytes;
+        this.name = "GoBinaryResourceFailure";
+    }
+}
+/** Reader that checks every structural range before decoding numeric fields. */
+export class GoBinaryReader {
+    bytes;
+    little;
+    constructor(bytes, little) {
+        this.bytes = bytes;
+        this.little = little;
+    }
+    range(offset, size, label) {
+        if (!Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(size) ||
+            offset < 0 ||
+            size < 0 ||
+            offset > this.bytes.length ||
+            size > this.bytes.length - offset)
+            throw new GoBinaryFormatFailure("malformed", `${label} range is truncated or outside the file`);
+        return this.bytes.subarray(offset, offset + size);
+    }
+    u16(offset) {
+        const value = this.range(offset, 2, "16-bit field");
+        return this.little ? value.readUInt16LE() : value.readUInt16BE();
+    }
+    u32(offset) {
+        const value = this.range(offset, 4, "32-bit field");
+        return this.little ? value.readUInt32LE() : value.readUInt32BE();
+    }
+    word(offset, bits) {
+        if (bits === 32)
+            return BigInt(this.u32(offset));
+        const value = this.range(offset, 8, "64-bit field");
+        return this.little ? value.readBigUInt64LE() : value.readBigUInt64BE();
+    }
+    fileRange(offset, size, label) {
+        if (offset > BigInt(this.bytes.length) ||
+            size > BigInt(this.bytes.length) - offset)
+            throw new GoBinaryFormatFailure("malformed", `${label} range is outside the file`);
+        const result = { address: 0n, offset: Number(offset), size: Number(size) };
+        this.range(result.offset, result.size, label);
+        return result;
+    }
+    table(offset, count, width, label) {
+        const size = BigInt(count) * BigInt(width);
+        if (size > 16n * 1024n * 1024n)
+            throw new GoBinaryResourceFailure("structure", 16 * 1024 * 1024, `${label} exceeds the 16 MiB structural decoding budget`);
+        return this.fileRange(offset, size, label).offset;
+    }
+}
+/** Admit a declared file span, or mark it unbacked when it leaves the file. */
+export const declaredFileRange = (fileBytes, offset, size) => {
+    if (offset < 0n ||
+        size < 0n ||
+        offset > BigInt(Number.MAX_SAFE_INTEGER) ||
+        size > BigInt(Number.MAX_SAFE_INTEGER) ||
+        offset > BigInt(fileBytes) ||
+        size > BigInt(fileBytes) - offset)
+        return { offset: 0, size: 0, file_backed: false };
+    return {
+        offset: Number(offset),
+        size: Number(size),
+        file_backed: size > 0n,
+    };
+};
+/** Map a virtual span without losing precision or selecting an ambiguous alias. */
+export const mappedFileOffset = (mappings, address, size, zeroFills = []) => {
+    let found;
+    for (const mapping of mappings) {
+        const delta = address - mapping.address;
+        if (delta < 0n ||
+            delta > BigInt(mapping.size) ||
+            BigInt(size) > BigInt(mapping.size) - delta)
+            continue;
+        const offset = mapping.offset + Number(delta);
+        if (found !== undefined && found !== offset)
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file mappings");
+        found = offset;
+    }
+    if (found === undefined)
+        throw new GoBinaryFormatFailure("malformed", "Virtual address or string range is not file mapped");
+    for (const zeroFill of zeroFills) {
+        if (spansOverlap(address, BigInt(size), zeroFill.address, zeroFill.size))
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file and zero-fill mappings");
+    }
+    const end = address + BigInt(size);
+    for (const mapping of mappings) {
+        const start = address > mapping.address ? address : mapping.address;
+        const mappingEnd = mapping.address + BigInt(mapping.size);
+        const overlapEnd = end < mappingEnd ? end : mappingEnd;
+        if (start >= overlapEnd)
+            continue;
+        if (BigInt(found) + start - address !==
+            BigInt(mapping.offset) + start - mapping.address)
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file mappings");
+    }
+    return found;
+};
+/** Recognize a wholly zero-filled span while refusing even partial file aliases. */
+export const isZeroFilledSpan = (mappings, zeroFills, address, size) => {
+    const bytes = BigInt(size);
+    if (!zeroFills.some((mapping) => address >= mapping.address &&
+        address + bytes <= mapping.address + mapping.size))
+        return false;
+    for (const mapping of mappings) {
+        if (spansOverlap(address, bytes, mapping.address, BigInt(mapping.size)))
+            throw new GoBinaryFormatFailure("malformed", "Virtual address has ambiguous file and zero-fill mappings");
+    }
+    return true;
+};
+const spansOverlap = (address, size, otherAddress, otherSize) => size > 0n &&
+    otherSize > 0n &&
+    address < otherAddress + otherSize &&
+    otherAddress < address + size;
+/** Decode metadata text without replacing invalid bytes or stripping an initial BOM. */
+export const goUtf8 = (bytes, label) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new GoBinaryFormatFailure("malformed", `${label} contains malformed UTF-8: ${String(cause)}`);
+    }
+};

package/dist/go/GoBinaryImage.js

@@ -0,0 +1,210 @@
+import { GoBinaryFormatFailure, GoBinaryResourceFailure, GoBinaryReader, goUtf8, mappedFileOffset, isZeroFilledSpan, } from "./GoBinaryContainer.js";
+import { classifyFatContainerIdentity, readFatContainerHeader, } from "../domain/apple/machoContainer.js";
+import { readGoElfImage } from "./GoElfImage.js";
+import { readGoMachoImage } from "./GoMachoImage.js";
+import { readGoPeImage } from "./GoPeImage.js";
+export { GoBinaryFormatFailure, GoBinaryResourceFailure, } from "./GoBinaryContainer.js";
+const MAGIC = Buffer.from("ff20476f206275696c64696e663a", "hex");
+const MODULE_START = Buffer.from("3077af0c9274080241e1c107e6d618e6", "hex");
+const MODULE_END = Buffer.from("f932433186182072008242104116d8f2", "hex");
+const MAX_BUILD_INFO_BYTES = 1024 * 1024;
+const MAX_HEADER_SEARCH_BYTES = 256 * 1024 * 1024;
+/** Inspect bounded executable bytes using native mappings, without loading or executing code. */
+export const readGoBinaryImage = (bytes) => {
+    const container = readGoBinaryContainer(bytes);
+    const { format, architecture, bits, byte_order } = container;
+    let selected = null;
+    const searched = new Set();
+    let remainingSearchBytes = MAX_HEADER_SEARCH_BYTES;
+    for (const search of container.search) {
+        // Identical file spans and alignment inspect the same candidate bytes.
+        // Partially overlapping spans still consume a cumulative work budget.
+        const identity = `${search.offset}:${search.size}:${search.address % 16n}`;
+        if (searched.has(identity))
+            continue;
+        searched.add(identity);
+        if (search.size > remainingSearchBytes)
+            throw new GoBinaryResourceFailure("search", MAX_HEADER_SEARCH_BYTES, "Go build-info discovery exceeds the cumulative 256 MiB header-search budget");
+        remainingSearchBytes -= search.size;
+        const header = findHeader(bytes, search);
+        if (header !== null) {
+            selected = { search, header };
+            break;
+        }
+    }
+    if (selected === null)
+        return { format, architecture, bits, byte_order, build_info: null };
+    const { search, header } = selected;
+    const verifyMapping = (size) => {
+        const address = search.address + BigInt(header - search.offset);
+        if (mappedFileOffset(container.mappings, address, size, container.zero_fills) !== header)
+            throw new GoBinaryFormatFailure("malformed", "Go build-info bytes disagree with their virtual mapping");
+    };
+    verifyMapping(32);
+    const reader = new GoBinaryReader(bytes, byte_order === "little");
+    const ptrSize = bytes[header + 14];
+    const flags = bytes[header + 15] ?? 0;
+    if ((flags & ~3) !== 0)
+        throw new GoBinaryFormatFailure("unsupported", "Go build-info flags contain an unsupported format bit");
+    if ((flags & 2) === 0 && (flags & 1) !== (byte_order === "big" ? 1 : 0))
+        throw new GoBinaryFormatFailure("malformed", "Go build-info byte order disagrees with the image");
+    const encoding = (flags & 2) !== 0 ? "inline" : "pointer";
+    const readInline = (offset, remaining) => readInlineString(reader, offset, remaining);
+    const sourceEnd = search.offset + search.size;
+    let version;
+    let module;
+    if (encoding === "inline") {
+        version = readInline(header + 32, sourceEnd - header - 32);
+        const next = version.location.offset + version.location.bytes;
+        module = readInline(next, sourceEnd - next);
+        verifyMapping(module.location.offset + module.location.bytes - header);
+    }
+    else {
+        if (ptrSize !== 4 && ptrSize !== 8)
+            throw new GoBinaryFormatFailure("malformed", "Go build-info pointer width must be 4 or 8");
+        if (ptrSize * 8 !== bits)
+            throw new GoBinaryFormatFailure("malformed", "Go build-info pointer width disagrees with the image");
+        const pointerBits = ptrSize === 8 ? 64 : 32;
+        version = readPointerString(reader, container, reader.word(header + 16, pointerBits));
+        const moduleField = header + 16 + ptrSize;
+        module = readOptionalModuleString(reader, container, reader.word(moduleField, pointerBits), moduleField);
+    }
+    if (version.location.bytes + module.location.bytes > MAX_BUILD_INFO_BYTES)
+        throw new GoBinaryResourceFailure("build-info", MAX_BUILD_INFO_BYTES, "Go build-info strings exceed the aggregate 1 MiB limit");
+    if (version.bytes.length === 0)
+        throw new GoBinaryFormatFailure("malformed", "Go build-info compiler version is empty");
+    const goVersion = observedText(version.bytes);
+    let moduleText = "";
+    if (module.bytes.length !== 0) {
+        if (module.bytes.length < 33 ||
+            !module.bytes.subarray(0, 16).equals(MODULE_START) ||
+            !module.bytes.subarray(-16).equals(MODULE_END) ||
+            module.bytes[module.bytes.length - 17] !== 10)
+            throw new GoBinaryFormatFailure("malformed", "Go module string framing is invalid");
+        moduleText = observedText(module.bytes.subarray(16, -16));
+    }
+    return {
+        format,
+        architecture,
+        bits,
+        byte_order,
+        build_info: {
+            header_offset: header,
+            encoding,
+            go_version: goVersion,
+            go_version_bytes_base64: version.bytes.toString("base64"),
+            module_text: moduleText,
+            module_bytes_base64: module.bytes.toString("base64"),
+            version_location: version.location,
+            module_location: module.location,
+        },
+    };
+};
+const observedText = (bytes) => {
+    try {
+        return goUtf8(bytes, "Go build string");
+    }
+    catch (cause) {
+        if (cause instanceof GoBinaryFormatFailure)
+            return null;
+        throw cause;
+    }
+};
+/** Identify an ELF, PE, or thin Mach-O image and its named file sections. */
+export const readGoBinaryContainer = (bytes) => {
+    if (bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
+        return readGoElfImage(bytes);
+    if (bytes.subarray(0, 2).equals(Buffer.from("MZ")))
+        return readGoPeImage(bytes);
+    if (bytes.length >= 4) {
+        const magic = bytes.readUInt32BE();
+        if ([0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca].includes(magic)) {
+            const fatHeader = readFatContainerHeader(bytes, bytes.length);
+            if (fatHeader.state === "malformed")
+                throw new GoBinaryFormatFailure("malformed", fatHeader.reason);
+            const identity = fatHeader.state === "parsed"
+                ? classifyFatContainerIdentity(fatHeader, (offset) => {
+                    if (offset >= bytes.length)
+                        return undefined;
+                    if (offset + 4 > bytes.length)
+                        return null;
+                    return bytes.readUInt32BE(offset);
+                })
+                : undefined;
+            // An invalid FAT-shaped table is not proof of a Mach-O container: JVM
+            // constant-pool bytes can share both the magic and a known CPU value.
+            const confirmedFatMachO = identity?.state === "mach-o";
+            if (confirmedFatMachO)
+                throw new GoBinaryFormatFailure("unsupported", "Universal/fat Mach-O containers require selecting a thin slice");
+        }
+        if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
+            return readGoMachoImage(bytes);
+    }
+    throw new GoBinaryFormatFailure("unsupported", "Only ELF, PE, and thin Mach-O native images are supported");
+};
+const findHeader = (bytes, search) => {
+    if (search.size === 0)
+        return null;
+    const end = search.offset + search.size;
+    const selected = bytes.subarray(search.offset, end);
+    let offset = Number((16n - (search.address % 16n)) % 16n);
+    while (offset < selected.length) {
+        const match = selected.indexOf(MAGIC, offset);
+        if (match < 0)
+            return null;
+        const candidate = search.offset + match;
+        const address = search.address + BigInt(candidate - search.offset);
+        if (address % 16n === 0n) {
+            if (end - candidate < 32)
+                throw new GoBinaryFormatFailure("malformed", "Go build-info header is truncated");
+            return candidate;
+        }
+        offset = match + 1;
+    }
+    return null;
+};
+const readInlineString = (reader, offset, remaining) => {
+    let length = 0n;
+    for (let index = 0; index < 10; index++) {
+        if (index >= remaining)
+            throw new GoBinaryFormatFailure("malformed", "Go build-info varint is truncated");
+        const byte = reader.bytes[offset + index] ?? 0;
+        if (index === 9 && byte > 1)
+            throw new GoBinaryFormatFailure("malformed", "Go build-info varint overflows 64 bits");
+        length |= BigInt(byte & 127) << BigInt(index * 7);
+        if ((byte & 128) === 0) {
+            if (length > BigInt(MAX_BUILD_INFO_BYTES))
+                throw new GoBinaryResourceFailure("build-info", MAX_BUILD_INFO_BYTES, "Go build-info string length exceeds the 1 MiB limit");
+            const size = Number(length);
+            if (size > remaining - index - 1)
+                throw new GoBinaryFormatFailure("malformed", "Go build-info string range is truncated");
+            const start = offset + index + 1;
+            return {
+                bytes: reader.range(start, size, "Go build-info string"),
+                location: { offset: start, bytes: size },
+            };
+        }
+    }
+    throw new GoBinaryFormatFailure("malformed", "Go build-info varint is unterminated");
+};
+const readPointerString = (reader, container, address) => {
+    const { mappings, zero_fills: zeroFills, bits } = container;
+    const width = bits / 8;
+    const header = mappedFileOffset(mappings, address, width * 2, zeroFills);
+    const valueAddress = reader.word(header, bits);
+    const length = reader.word(header + width, bits);
+    if (length > BigInt(MAX_BUILD_INFO_BYTES))
+        throw new GoBinaryResourceFailure("build-info", MAX_BUILD_INFO_BYTES, "Go build-info pointer string length exceeds the 1 MiB limit");
+    const size = Number(length);
+    // Zero-length Go strings may carry a zero data pointer.
+    const offset = size === 0 && valueAddress === 0n
+        ? header
+        : mappedFileOffset(mappings, valueAddress, size, zeroFills);
+    return {
+        bytes: reader.range(offset, size, "Go build-info pointer string"),
+        location: { offset, bytes: size },
+    };
+};
+const readOptionalModuleString = (reader, container, address, pointerField) => isZeroFilledSpan(container.mappings, container.zero_fills, address, (container.bits / 8) * 2)
+    ? { bytes: Buffer.alloc(0), location: { offset: pointerField, bytes: 0 } }
+    : readPointerString(reader, container, address);

package/dist/go/GoBinaryProvider.js

@@ -0,0 +1,151 @@
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { goBinarySchema, } from "../domain/go/goBinary.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { readGoBinaryImage, GoBinaryFormatFailure, GoBinaryResourceFailure, } from "./GoBinaryImage.js";
+import { parseGoModuleBytes, parseGoModuleText } from "./GoModuleText.js";
+/** Bundled format reader identity; embedded compiler versions are separate observed facts. */
+export const GO_BINARY_PROVIDER_IDENTITY = {
+    id: "go-build-info",
+    name: "REA Go build-information reader",
+    version: "1",
+};
+const OPERATION = "inspect_go_binary";
+const INPUT_BYTES = 256 * 1024 * 1024;
+const OUTPUT_BYTES = 8 * 1024 * 1024;
+const failureForPrimary = (cause, path, signal) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")
+        return new AnalysisArtifactChangedError(OPERATION, path, cause.message, {
+            cause,
+        });
+    if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
+        return new AnalysisCancelledError(OPERATION, { cause });
+    if (signal?.aborted)
+        return new AnalysisCancelledError(OPERATION, { cause });
+    if (cause instanceof GoBinaryResourceFailure)
+        return new AnalysisResourceConstraintError(OPERATION, cause.boundary === "search" ? "cpu" : "memory", `Selected artifact ${path}: ${cause.message}`, { boundary: cause.boundary, maximum_bytes: cause.maximum_bytes }, { cause });
+    if (cause instanceof GoBinaryFormatFailure)
+        return cause.kind === "unsupported"
+            ? new AnalysisUnsupportedTargetError(OPERATION, path, cause.message, {
+                cause,
+            })
+            : new AnalysisInputError(OPERATION, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_format",
+                    message: `Selected artifact ${path}: ${cause.message}`,
+                },
+            ]);
+    if (cause instanceof ArtifactReaderFailure) {
+        if (cause.reason === "limit")
+            return new AnalysisResourceConstraintError(OPERATION, "file-size", cause.message, { maximum_input_bytes: INPUT_BYTES }, { cause });
+        if (cause.reason === "path")
+            return new AnalysisInputError(OPERATION, { cause }, [
+                { path: ["path"], reason: "invalid_format", message: cause.message },
+            ]);
+    }
+    if (cause instanceof Error && "code" in cause) {
+        if (cause.code === "EACCES" || cause.code === "EPERM")
+            return new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
+                cause,
+            });
+        if (["ENOENT", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(String(cause.code)))
+            return new AnalysisInputError(OPERATION, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_value",
+                    message: `Selected artifact could not be read (${String(cause.code)}): ${path}.`,
+                },
+            ]);
+    }
+    return new ProviderAdapterError(GO_BINARY_PROVIDER_IDENTITY.id, OPERATION, {
+        cause,
+        diagnostics: {
+            path,
+            reason: cause instanceof Error ? cause.message : String(cause),
+        },
+    });
+};
+const failureFor = (cause, path, signal) => {
+    const primary = failureForPrimary(cause, path, signal);
+    if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)
+        return primary;
+    const cleanup = new ProviderCleanupError(GO_BINARY_PROVIDER_IDENTITY.id, cause.cleanup.resources, { reason: cause.cleanup.reason }, { operation: OPERATION, cause });
+    return analysisErrorWithCleanupFailure(primary, cleanup, OPERATION);
+};
+const outputLimit = (path) => new AnalysisResourceConstraintError(OPERATION, "transport", `Complete Go metadata for ${path} exceeds the inline output budget; no partial success is returned.`, { maximum_output_bytes: OUTPUT_BYTES });
+/** Stable in-process metadata inspection without subprocesses, temporary files or Go installation. */
+export class GoBinaryProvider {
+    identity = GO_BINARY_PROVIDER_IDENTITY;
+    #resources = new ArtifactResourceScope();
+    close() {
+        return this.#resources.close();
+    }
+    /** Read complete compiler/module metadata while preserving original byte identity and source ranges. */
+    async inspect(input, options) {
+        try {
+            const snapshot = await this.#resources.run(() => readStableArtifact(input.path, INPUT_BYTES, options?.signal, undefined, this.#resources));
+            options?.signal?.throwIfAborted();
+            const image = readGoBinaryImage(snapshot.bytes);
+            const info = image.build_info;
+            if (info !== null &&
+                ((info.module_text !== null &&
+                    Buffer.byteLength(info.module_text) > OUTPUT_BYTES) ||
+                    Buffer.byteLength(info.module_bytes_base64) > OUTPUT_BYTES))
+                throw outputLimit(input.path);
+            const module = info === null
+                ? null
+                : info.module_text === null
+                    ? parseGoModuleBytes(Buffer.from(info.module_bytes_base64, "base64").subarray(16, -16))
+                    : parseGoModuleText(info.module_text);
+            const report = {
+                ...image,
+                artifact: {
+                    path: input.path,
+                    sha256: snapshot.sha256,
+                    bytes: snapshot.bytes.length,
+                },
+                build_info: info === null ? null : { ...info, module },
+                limitations: [
+                    "Embedded build metadata is observed file content, not proof of compiler identity, dependency authenticity or runtime behavior.",
+                    "Only Go build information is inspected; function names, source mappings, type metadata and decompiled code are not recovered.",
+                    "Resource guards bound stable artifact reads and cumulative header searches to 256 MiB each, aggregate embedded strings to 1 MiB, structural table decoding to 16 MiB and complete metadata payloads to 8 MiB; these are not operating-system memory or CPU limits.",
+                    ...(info !== null &&
+                        (info.go_version === null || info.module_text === null)
+                        ? [
+                            "Some embedded Go strings contain non-UTF8 bytes; undecodable text is null and exact source bytes are preserved as base64.",
+                        ]
+                        : []),
+                    ...(info === null
+                        ? [
+                            "No recognized Go build-info record was found in the inspected image; absent metadata does not establish that the binary is not Go.",
+                        ]
+                        : []),
+                    ...(module?.complete === false
+                        ? [
+                            "Some embedded module-text records could not be parsed completely; their original lines are preserved and additional metadata remains unknown.",
+                        ]
+                        : []),
+                ],
+            };
+            if (Buffer.byteLength(JSON.stringify(report), "utf8") > OUTPUT_BYTES)
+                throw outputLimit(input.path);
+            const parsed = goBinarySchema.safeParse(report);
+            if (!parsed.success)
+                throw new AnalysisOutputError(OPERATION, "Go reader produced invalid source ranges or report values.", { cause: parsed.error });
+            options?.signal?.throwIfAborted();
+            return ok(parsed.data);
+        }
+        catch (cause) {
+            return err(failureFor(cause, input.path, options?.signal));
+        }
+    }
+}