rea-agents 1.7.0 → 2.0.0

package/dist/dotnet/ManagedNativeBoundaryInspector.js

@@ -0,0 +1,391 @@
+import { managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
+import { metadataRowOffset, readManagedMetadataLayout, } from "./ManagedMetadataLayout.js";
+import { MetadataRowCursor, metadataToken, readMetadataString, } from "./ManagedMetadataHeaps.js";
+import { readManagedMetadataInventory, managedTableRowCounts, } from "./ManagedMetadataInventory.js";
+import { readManagedPeLayout, } from "./ManagedPeReader.js";
+import { ManagedReaderFailure, managedFailure, } from "./ManagedReaderFailure.js";
+const rowCursor = (bytes, layout, table, row) => {
+    const descriptor = layout.table(table);
+    const start = metadataRowOffset(layout, table, row);
+    if (descriptor === undefined)
+        throw managedFailure("invalid-row", `metadata.${String(table)}`, "Metadata table is absent", start);
+    return new MetadataRowCursor(bytes, start, start + descriptor.rowSize, `metadata.${descriptor.name}`);
+};
+const codedToken = (raw, tagBits, tables) => {
+    const tagMask = (1 << tagBits) - 1;
+    const table = tables[raw & tagMask];
+    const row = raw >> tagBits;
+    if (table === undefined || row === 0)
+        return null;
+    return metadataToken(table, row);
+};
+const flagsHex = (value) => `0x${value.toString(16).padStart(4, "0")}`;
+const page = (items, offset, limit) => {
+    const safeOffset = Math.min(offset, items.length);
+    const selected = items.slice(safeOffset, safeOffset + limit);
+    return {
+        items: selected,
+        offset,
+        limit,
+        total: items.length,
+        returned: selected.length,
+        dropped: Math.max(0, items.length - safeOffset - selected.length),
+        complete: safeOffset === 0 && selected.length === items.length,
+    };
+};
+const parseModuleRefs = (bytes, layout, maxBytes) => {
+    const refs = [];
+    const table = layout.table(26);
+    for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
+        const cursor = rowCursor(bytes, layout, 26, row);
+        refs.push({
+            token: metadataToken(26, row),
+            row_offset: cursor.start,
+            name: readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes),
+        });
+    }
+    return refs;
+};
+const parseFields = (bytes, layout, maxBytes) => {
+    const fields = new Map();
+    const table = layout.table(4);
+    for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
+        const cursor = rowCursor(bytes, layout, 4, row);
+        const flags = cursor.readUInt16();
+        const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+        cursor.readIndex(layout.blobIndexSize);
+        const token = metadataToken(4, row);
+        fields.set(token, {
+            token,
+            rowOffset: cursor.start,
+            kind: "field",
+            name,
+            flags,
+            implFlags: null,
+            rva: null,
+        });
+    }
+    return fields;
+};
+const parseMethods = (bytes, layout, maxBytes) => {
+    const methods = new Map();
+    const table = layout.table(6);
+    for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
+        const cursor = rowCursor(bytes, layout, 6, row);
+        const rva = cursor.readUInt32();
+        const implFlags = cursor.readUInt16();
+        const flags = cursor.readUInt16();
+        const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+        cursor.readIndex(layout.blobIndexSize);
+        cursor.readIndex(layout.tableIndexSize(8));
+        const token = metadataToken(6, row);
+        methods.set(token, {
+            token,
+            rowOffset: cursor.start,
+            kind: "method",
+            name,
+            flags,
+            implFlags,
+            rva,
+        });
+    }
+    return methods;
+};
+const parseImplMaps = (bytes, layout, maxBytes, modules, members) => {
+    const moduleNames = new Map(modules.map((module) => [module.token, module]));
+    const imports = [];
+    const table = layout.table(28);
+    for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
+        const cursor = rowCursor(bytes, layout, 28, row);
+        const mappingFlags = cursor.readUInt16();
+        const memberToken = codedToken(cursor.readIndex(layout.codedIndexSize("MemberForwarded")), 1, [4, 6]);
+        const importName = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+        const importScopeRow = cursor.readIndex(layout.tableIndexSize(26));
+        const importScopeToken = importScopeRow === 0 ? null : metadataToken(26, importScopeRow);
+        const member = memberToken === null ? undefined : members.get(memberToken);
+        imports.push({
+            token: metadataToken(28, row),
+            row_offset: cursor.start,
+            mapping_flags: mappingFlags,
+            mapping_flags_hex: flagsHex(mappingFlags),
+            member_token: memberToken,
+            member_kind: member?.kind ?? "unknown",
+            member_name: member?.name ?? null,
+            import_name: importName,
+            import_scope_token: importScopeToken,
+            import_scope_name: importScopeToken === null
+                ? null
+                : (moduleNames.get(importScopeToken)?.name ?? null),
+            no_mangle: (mappingFlags & 0x0001) !== 0,
+            char_set: charSet(mappingFlags),
+            call_convention: callConvention(mappingFlags),
+            supports_last_error: (mappingFlags & 0x0040) !== 0,
+            best_fit: bestFit(mappingFlags),
+            throw_on_unmappable_char: throwOnUnmappable(mappingFlags),
+            verification: "managed-declaration-only",
+        });
+    }
+    return imports;
+};
+const charSet = (flags) => {
+    switch (flags & 0x0006) {
+        case 0x0000:
+            return "not-specified";
+        case 0x0002:
+            return "ansi";
+        case 0x0004:
+            return "unicode";
+        case 0x0006:
+            return "auto";
+        default:
+            return "unknown";
+    }
+};
+const callConvention = (flags) => {
+    switch (flags & 0x0700) {
+        case 0x0000:
+            return "not-specified";
+        case 0x0100:
+            return "winapi";
+        case 0x0200:
+            return "cdecl";
+        case 0x0300:
+            return "stdcall";
+        case 0x0400:
+            return "thiscall";
+        case 0x0500:
+            return "fastcall";
+        default:
+            return "unknown";
+    }
+};
+const bestFit = (flags) => {
+    switch (flags & 0x0030) {
+        case 0x0000:
+            return "assembly-default";
+        case 0x0010:
+            return "enabled";
+        case 0x0020:
+            return "disabled";
+        default:
+            return "unknown";
+    }
+};
+const throwOnUnmappable = (flags) => {
+    switch (flags & 0x3000) {
+        case 0x0000:
+            return "assembly-default";
+        case 0x1000:
+            return "enabled";
+        case 0x2000:
+            return "disabled";
+        default:
+            return "unknown";
+    }
+};
+const nativeImplementations = (methods, pinvokeTokens) => {
+    const implementations = [];
+    for (const method of methods) {
+        const implFlags = method.implFlags ?? 0;
+        const codeType = codeTypeFor(implFlags);
+        const managedKind = managedKindFor(implFlags);
+        const pinvokeDeclared = pinvokeTokens.has(method.token) || (method.flags & 0x2000) !== 0;
+        if (!pinvokeDeclared && codeType === "il" && managedKind === "managed")
+            continue;
+        implementations.push({
+            token: method.token,
+            row_offset: method.rowOffset,
+            name: method.name,
+            rva: method.rva ?? 0,
+            flags: method.flags,
+            impl_flags: implFlags,
+            code_type: codeType,
+            managed_kind: managedKind,
+            pinvoke_declared: pinvokeDeclared,
+            boundary_kind: boundaryKind(pinvokeDeclared, codeType, managedKind),
+            body_interpretation: codeType === "il" && managedKind === "managed" && !pinvokeDeclared
+                ? "managed-cil"
+                : method.rva === 0
+                    ? "not-file-backed"
+                    : "native-or-runtime",
+        });
+    }
+    return implementations;
+};
+const codeTypeFor = (implFlags) => {
+    switch (implFlags & 0x0003) {
+        case 0x0000:
+            return "il";
+        case 0x0001:
+            return "native";
+        case 0x0002:
+            return "optil";
+        case 0x0003:
+            return "runtime";
+        default:
+            return "unknown";
+    }
+};
+const managedKindFor = (implFlags) => {
+    switch (implFlags & 0x0004) {
+        case 0x0000:
+            return "managed";
+        case 0x0004:
+            return "unmanaged";
+        default:
+            return "unknown";
+    }
+};
+const boundaryKind = (pinvokeDeclared, codeType, managedKind) => {
+    if (pinvokeDeclared)
+        return "pinvoke";
+    if (codeType === "native")
+        return "native-body";
+    if (codeType === "runtime")
+        return "runtime-provided";
+    if (managedKind === "unmanaged")
+        return "unmanaged-method";
+    return "mixed-or-unknown";
+};
+const cliNative = (pe) => {
+    if (pe.cli === null)
+        return {
+            il_only: false,
+            requires_32bit: false,
+            strong_name_signed: false,
+            native_entry_point: false,
+            ready_to_run_signature: false,
+            managed_native_header_rva: 0,
+            managed_native_header_size: 0,
+        };
+    return {
+        il_only: (pe.cli.flags & 0x0000_0001) !== 0,
+        requires_32bit: (pe.cli.flags & 0x0000_0002) !== 0,
+        strong_name_signed: (pe.cli.flags & 0x0000_0008) !== 0,
+        native_entry_point: (pe.cli.flags & 0x0000_0010) !== 0,
+        ready_to_run_signature: pe.cli.readyToRunSignature,
+        managed_native_header_rva: pe.cli.managedNativeHeader.rva,
+        managed_native_header_size: pe.cli.managedNativeHeader.size,
+    };
+};
+const unavailable = (target, bytes, limits, issue) => managedNativeBoundaryInspectionSchema.parse({
+    schema_version: 1,
+    artifact: {
+        path: target.path,
+        sha256: target.sha256,
+        byte_length: bytes.length,
+        format: "pe",
+    },
+    module: null,
+    metadata: { status: "absent", version: null, table_row_counts: {} },
+    identity_scope: {
+        token_identity: "build-local",
+        requires_artifact_sha256: target.sha256,
+        requires_mvid: null,
+    },
+    cli_native: {
+        il_only: false,
+        requires_32bit: false,
+        strong_name_signed: false,
+        native_entry_point: false,
+        ready_to_run_signature: false,
+        managed_native_header_rva: 0,
+        managed_native_header_size: 0,
+    },
+    module_refs: page([], limits.moduleRefOffset, limits.moduleRefLimit),
+    pinvoke_imports: page([], limits.importOffset, limits.importLimit),
+    native_implementations: page([], limits.implementationOffset, limits.implementationLimit),
+    summary: {
+        module_ref_count: 0,
+        pinvoke_import_count: 0,
+        native_implementation_count: 0,
+        ready_to_run: false,
+        mixed_mode_or_native_header: false,
+    },
+    coverage: {
+        state: "unavailable",
+        issues: issue === null ? [] : [issue],
+    },
+    limitations: [
+        "The PE has no admitted CLI metadata; managed/native boundary inspection is unavailable.",
+    ],
+});
+/** Inspect PE/CLI managed/native boundary declarations without executing code. */
+export const inspectManagedNativeBoundariesBytes = (bytes, target, limits) => {
+    const pe = readManagedPeLayout(bytes);
+    if (pe.cli === null)
+        return unavailable(target, bytes, limits, pe.cliIssue);
+    const issues = [];
+    try {
+        const rootOffset = pe.rvaToOffset(pe.cli.metadata.rva, pe.cli.metadata.size, "cli.metadata");
+        if (pe.cli.metadata.size > limits.maxMetadataBytes)
+            throw managedFailure("limit-exceeded", "metadata.root", `CLI metadata size exceeds max_metadata_bytes ${String(limits.maxMetadataBytes)}`, rootOffset);
+        const layout = readManagedMetadataLayout(bytes, rootOffset, pe.cli.metadata.size, limits.maxTableRows);
+        const inventory = readManagedMetadataInventory(bytes, layout, {
+            referenceOffset: 0,
+            referenceLimit: 1,
+            resourceOffset: 0,
+            resourceLimit: 1,
+            attributeOffset: 0,
+            attributeLimit: 1,
+            maxHeapItemBytes: limits.maxHeapItemBytes,
+        }, null);
+        issues.push(...inventory.issues);
+        const moduleRefs = parseModuleRefs(bytes, layout, limits.maxHeapItemBytes);
+        const fields = parseFields(bytes, layout, limits.maxHeapItemBytes);
+        const methods = parseMethods(bytes, layout, limits.maxHeapItemBytes);
+        const members = new Map([...fields, ...methods]);
+        const imports = parseImplMaps(bytes, layout, limits.maxHeapItemBytes, moduleRefs, members);
+        const implementations = nativeImplementations(methods.values(), new Set(imports
+            .map(({ member_token: token }) => token)
+            .filter((token) => token !== null)));
+        const native = cliNative(pe);
+        return managedNativeBoundaryInspectionSchema.parse({
+            schema_version: 1,
+            artifact: {
+                path: target.path,
+                sha256: target.sha256,
+                byte_length: bytes.length,
+                format: "pe",
+            },
+            module: inventory.module,
+            metadata: {
+                status: issues.length === 0 ? "complete" : "partial",
+                version: layout.version,
+                table_row_counts: managedTableRowCounts(layout),
+            },
+            identity_scope: {
+                token_identity: "build-local",
+                requires_artifact_sha256: target.sha256,
+                requires_mvid: inventory.module?.mvid ?? null,
+            },
+            cli_native: native,
+            module_refs: page(moduleRefs, limits.moduleRefOffset, limits.moduleRefLimit),
+            pinvoke_imports: page(imports, limits.importOffset, limits.importLimit),
+            native_implementations: page(implementations, limits.implementationOffset, limits.implementationLimit),
+            summary: {
+                module_ref_count: moduleRefs.length,
+                pinvoke_import_count: imports.length,
+                native_implementation_count: implementations.length,
+                ready_to_run: native.ready_to_run_signature,
+                mixed_mode_or_native_header: native.managed_native_header_rva !== 0 ||
+                    native.managed_native_header_size !== 0 ||
+                    native.native_entry_point,
+            },
+            coverage: {
+                state: issues.length === 0 ? "complete" : "partial",
+                issues,
+            },
+            limitations: [
+                "P/Invoke rows prove managed import declarations only; this inspection does not verify that a native library, export, thunk, or provider-qualified function exists.",
+                "Managed metadata tokens are build-local coordinates and are only meaningful with the reported artifact SHA-256 and MVID.",
+                "ReadyToRun, NativeAOT, C++/CLI, and IL2CPP native semantics require separately selected native-provider evidence; this tool does not translate managed tokens into native addresses.",
+            ],
+        });
+    }
+    catch (cause) {
+        if (cause instanceof ManagedReaderFailure)
+            return unavailable(target, bytes, limits, cause.issue);
+        throw cause;
+    }
+};

package/dist/dotnet/ManagedPeReader.js

@@ -0,0 +1,157 @@
+import { managedFailure, ManagedReaderFailure, } from "./ManagedReaderFailure.js";
+const requireRange = (bytes, offset, length, scope) => {
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(length) ||
+        offset < 0 ||
+        length < 0 ||
+        offset > bytes.length - length)
+        throw managedFailure("invalid-directory", scope, `${scope} leaves the artifact byte range`, Number.isSafeInteger(offset) && offset >= 0 ? offset : null);
+};
+const add = (left, right, scope) => {
+    const result = left + right;
+    if (!Number.isSafeInteger(result) || result < left)
+        throw managedFailure("invalid-directory", scope, `${scope} offset arithmetic overflowed`, left);
+    return result;
+};
+const architectureFor = (machine) => {
+    switch (machine) {
+        case 0x014c:
+            return "x86";
+        case 0x8664:
+            return "x86_64";
+        case 0x01c0:
+            return "arm";
+        case 0xaa64:
+            return "arm64";
+        default:
+            throw managedFailure("invalid-directory", "pe.machine", `Unsupported PE machine 0x${machine.toString(16).padStart(4, "0")}`);
+    }
+};
+const mapRva = (bytes, sections, rva, size, scope) => {
+    if (rva === 0 && size === 0)
+        return 0;
+    for (const section of sections) {
+        const mappedSize = Math.max(section.virtualSize, section.rawSize);
+        if (rva < section.virtualAddress)
+            continue;
+        const within = rva - section.virtualAddress;
+        if (within > mappedSize || size > mappedSize - within)
+            continue;
+        if (within > section.rawSize || size > section.rawSize - within)
+            throw managedFailure("invalid-directory", scope, `${scope} occupies virtual bytes without file-backed data`);
+        const offset = add(section.rawOffset, within, scope);
+        requireRange(bytes, offset, size, scope);
+        return offset;
+    }
+    throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by a PE section`);
+};
+const readDirectory = (bytes, offset) => {
+    requireRange(bytes, offset, 8, "pe.data-directory");
+    return {
+        rva: bytes.readUInt32LE(offset),
+        size: bytes.readUInt32LE(offset + 4),
+    };
+};
+const readCliHeader = (bytes, sections, directory) => {
+    if (directory.size < 72)
+        throw managedFailure("invalid-cli-header", "cli.header", "CLI header is shorter than the required 72 bytes");
+    const offset = mapRva(bytes, sections, directory.rva, 72, "cli.header");
+    const headerSize = bytes.readUInt32LE(offset);
+    if (headerSize < 72 || headerSize > directory.size)
+        throw managedFailure("invalid-cli-header", "cli.header", "CLI header size is outside its PE data directory", offset);
+    const metadata = readDirectory(bytes, offset + 8);
+    if (metadata.rva === 0 || metadata.size === 0)
+        throw managedFailure("invalid-cli-header", "cli.metadata", "CLI metadata directory is absent", offset + 8);
+    const flags = bytes.readUInt32LE(offset + 16);
+    const managedNativeHeader = readDirectory(bytes, offset + 64);
+    let readyToRunSignature = false;
+    if (managedNativeHeader.rva !== 0 && managedNativeHeader.size >= 4) {
+        const nativeOffset = mapRva(bytes, sections, managedNativeHeader.rva, 4, "cli.managed-native-header");
+        readyToRunSignature = bytes.readUInt32LE(nativeOffset) === 0x0052_5452;
+    }
+    return {
+        headerOffset: offset,
+        headerSize,
+        runtimeMajor: bytes.readUInt16LE(offset + 4),
+        runtimeMinor: bytes.readUInt16LE(offset + 6),
+        metadata,
+        flags,
+        entryPoint: bytes.readUInt32LE(offset + 20),
+        resources: readDirectory(bytes, offset + 24),
+        strongName: readDirectory(bytes, offset + 32),
+        managedNativeHeader,
+        readyToRunSignature,
+    };
+};
+/** Parse the file-backed PE and CLI layout without loading target code. */
+export const readManagedPeLayout = (bytes) => {
+    requireRange(bytes, 0, 64, "pe.dos-header");
+    if (bytes[0] !== 0x4d || bytes[1] !== 0x5a)
+        throw managedFailure("invalid-directory", "pe.dos-header", "Artifact does not start with an MZ header", 0);
+    const peOffset = bytes.readUInt32LE(0x3c);
+    requireRange(bytes, peOffset, 24, "pe.coff-header");
+    if (bytes.readUInt32LE(peOffset) !== 0x0000_4550)
+        throw managedFailure("invalid-directory", "pe.signature", "PE signature is invalid", peOffset);
+    const coff = peOffset + 4;
+    const machine = bytes.readUInt16LE(coff);
+    const sectionCount = bytes.readUInt16LE(coff + 2);
+    if (sectionCount === 0 || sectionCount > 96)
+        throw managedFailure("invalid-directory", "pe.sections", "PE section count is outside the admitted range", coff + 2);
+    const optionalSize = bytes.readUInt16LE(coff + 16);
+    const characteristics = bytes.readUInt16LE(coff + 18);
+    const optionalOffset = coff + 20;
+    requireRange(bytes, optionalOffset, optionalSize, "pe.optional-header");
+    if (optionalSize < 96)
+        throw managedFailure("invalid-directory", "pe.optional-header", "PE optional header is too short", optionalOffset);
+    const magic = bytes.readUInt16LE(optionalOffset);
+    const optionalHeader = magic === 0x010b ? "pe32" : magic === 0x020b ? "pe32-plus" : undefined;
+    if (optionalHeader === undefined)
+        throw managedFailure("invalid-directory", "pe.optional-header", "PE optional header magic is unsupported", optionalOffset);
+    const directoryCountOffset = optionalOffset + (optionalHeader === "pe32" ? 92 : 108);
+    const directoryOffset = optionalOffset + (optionalHeader === "pe32" ? 96 : 112);
+    requireRange(bytes, directoryCountOffset, 4, "pe.data-directories");
+    const directoryCount = bytes.readUInt32LE(directoryCountOffset);
+    const sectionOffset = add(optionalOffset, optionalSize, "pe.sections");
+    requireRange(bytes, sectionOffset, sectionCount * 40, "pe.sections");
+    const sections = [];
+    for (let index = 0; index < sectionCount; index += 1) {
+        const offset = sectionOffset + index * 40;
+        const section = {
+            virtualSize: bytes.readUInt32LE(offset + 8),
+            virtualAddress: bytes.readUInt32LE(offset + 12),
+            rawSize: bytes.readUInt32LE(offset + 16),
+            rawOffset: bytes.readUInt32LE(offset + 20),
+        };
+        if (section.rawSize > 0)
+            requireRange(bytes, section.rawOffset, section.rawSize, "pe.section-data");
+        sections.push(section);
+    }
+    const cliDirectory = directoryCount <= 14 ||
+        optionalSize < directoryOffset - optionalOffset + 120
+        ? { rva: 0, size: 0 }
+        : readDirectory(bytes, directoryOffset + 14 * 8);
+    const cliDirectoryPresent = cliDirectory.rva !== 0 || cliDirectory.size !== 0;
+    let cli = null;
+    let cliIssue = null;
+    if (cliDirectoryPresent)
+        try {
+            cli = readCliHeader(bytes, sections, cliDirectory);
+        }
+        catch (cause) {
+            if (!(cause instanceof ManagedReaderFailure))
+                throw cause;
+            cliIssue = cause.issue;
+        }
+    return {
+        machine,
+        architecture: architectureFor(machine),
+        optionalHeader,
+        sectionCount,
+        characteristics,
+        sections,
+        cli,
+        cliDirectoryPresent,
+        cliIssue,
+        rvaToOffset: (rva, size, scope) => mapRva(bytes, sections, rva, size, scope),
+    };
+};

package/dist/dotnet/ManagedReaderFailure.js

@@ -0,0 +1,10 @@
+/** Bounded format failure retained as caller-visible managed coverage. */
+export class ManagedReaderFailure extends Error {
+    issue;
+    constructor(issue, options) {
+        super(issue.detail, options);
+        this.issue = issue;
+    }
+}
+/** Construct a typed managed parse failure at an exact byte location. */
+export const managedFailure = (code, scope, detail, offset = null) => new ManagedReaderFailure({ code, scope, offset, detail });