rea-agents 1.7.0 → 2.1.0

package/dist/dotnet/ManagedArtifactInspector.js

@@ -0,0 +1,339 @@
+import { managedArtifactInspectionSchema, } from "../domain/managedArtifact.js";
+import { readManagedPeLayout, } from "./ManagedPeReader.js";
+import { managedTableRowCounts, readManagedMetadataInventory, } from "./ManagedMetadataInventory.js";
+import { readManagedMetadataLayout, } from "./ManagedMetadataLayout.js";
+import { ManagedReaderFailure } from "./ManagedReaderFailure.js";
+const emptyPage = (offset, limit) => ({
+    items: [],
+    offset,
+    limit,
+    total: 0,
+    returned: 0,
+    dropped: 0,
+    complete: offset === 0,
+});
+const flagNames = (flags) => {
+    const names = [];
+    for (const [mask, name] of [
+        [0x0000_0001, "il-only"],
+        [0x0000_0002, "32-bit-required"],
+        [0x0000_0004, "il-library"],
+        [0x0000_0008, "strong-name-signed"],
+        [0x0000_0010, "native-entry-point"],
+        [0x0001_0000, "track-debug-data"],
+        [0x0002_0000, "32-bit-preferred"],
+    ])
+        if ((flags & mask) !== 0)
+            names.push(name);
+    return names;
+};
+const cliProjection = (cli) => ({
+    header_offset: cli.headerOffset,
+    header_size: cli.headerSize,
+    runtime_version: `${String(cli.runtimeMajor)}.${String(cli.runtimeMinor)}`,
+    flags: cli.flags,
+    flag_names: flagNames(cli.flags),
+    entry_point: cli.entryPoint === 0
+        ? { kind: "none", value: null }
+        : (cli.flags & 0x10) !== 0
+            ? {
+                kind: "native-rva",
+                value: `0x${cli.entryPoint.toString(16)}`,
+            }
+            : {
+                kind: "metadata-token",
+                value: `0x${cli.entryPoint.toString(16).padStart(8, "0")}`,
+            },
+    metadata_rva: cli.metadata.rva,
+    metadata_size: cli.metadata.size,
+    resources_rva: cli.resources.rva,
+    resources_size: cli.resources.size,
+    strong_name_rva: cli.strongName.rva,
+    strong_name_size: cli.strongName.size,
+    managed_native_header_rva: cli.managedNativeHeader.rva,
+    managed_native_header_size: cli.managedNativeHeader.size,
+    ready_to_run_signature: cli.readyToRunSignature,
+});
+const peProjection = (layout) => ({
+    machine: layout.machine,
+    machine_hex: `0x${layout.machine.toString(16).padStart(4, "0")}`,
+    architecture: layout.architecture,
+    optional_header: layout.optionalHeader,
+    section_count: layout.sectionCount,
+    characteristics: layout.characteristics,
+    cli: layout.cli === null ? null : cliProjection(layout.cli),
+});
+const base = (target, bytes, layout) => ({
+    schema_version: 1,
+    artifact: {
+        path: target.path,
+        sha256: target.sha256,
+        byte_length: bytes.length,
+        format: "pe",
+    },
+    pe: peProjection(layout),
+});
+const unavailableResult = (target, bytes, layout, limits) => {
+    const malformed = layout.cliDirectoryPresent;
+    const issues = layout.cliIssue === null ? [] : [layout.cliIssue];
+    const limitations = malformed
+        ? [
+            "The PE declares a CLI directory, but its CLI header could not be admitted.",
+        ]
+        : [
+            "The PE has no CLI data directory; managed metadata and CIL are unavailable.",
+        ];
+    return managedArtifactInspectionSchema.parse({
+        ...base(target, bytes, layout),
+        classification: {
+            status: malformed ? "malformed" : "not-managed",
+            container: "pe",
+            runtime_family: "unknown",
+            implementation: malformed ? "unknown" : "not-managed",
+            managed_architecture: "unknown",
+            evidence: [
+                {
+                    code: malformed ? "cli-directory-malformed" : "cli-directory-absent",
+                    detail: limitations[0],
+                    file_offset: layout.cliIssue?.offset ?? null,
+                },
+            ],
+        },
+        metadata: {
+            status: malformed ? "malformed" : "absent",
+            version: null,
+            stream_names: [],
+            table_row_counts: {},
+        },
+        module: null,
+        assembly: null,
+        target_frameworks: [],
+        references: emptyPage(limits.referenceOffset, limits.referenceLimit),
+        resources: emptyPage(limits.resourceOffset, limits.resourceLimit),
+        attributes: emptyPage(limits.attributeOffset, limits.attributeLimit),
+        coverage: {
+            state: malformed ? "partial" : "unavailable",
+            issues,
+        },
+        limitations,
+    });
+};
+const runtimeFamilyFor = (cli, inventory, metadata, layout) => {
+    const evidence = [
+        {
+            code: "cli-header-observed",
+            detail: "A file-backed PE CLI header and metadata root were admitted.",
+            file_offset: cli.headerOffset,
+        },
+    ];
+    const frameworks = inventory.targetFrameworks;
+    const hasUnity = inventory.referenceNames.some((name) => name === "UnityEngine" || name.startsWith("UnityEngine."));
+    let runtimeFamily = "unknown";
+    if ((cli.flags & 1) === 0) {
+        runtimeFamily = "mixed-clr-native";
+        evidence.push({
+            code: "cli-il-only-clear",
+            detail: "COMIMAGE_FLAGS_ILONLY is clear, so managed and native analysis must remain composed.",
+            file_offset: cli.headerOffset + 16,
+        });
+    }
+    else if (hasUnity) {
+        runtimeFamily = "unity-mono";
+        evidence.push({
+            code: "unity-reference-observed",
+            detail: "The admitted AssemblyRef table contains a UnityEngine reference.",
+            file_offset: metadata.table(35)?.offset ?? null,
+        });
+    }
+    else if (frameworks.some((value) => value.startsWith(".NETFramework,"))) {
+        runtimeFamily = "dotnet-framework";
+        evidence.push({
+            code: "target-framework-observed",
+            detail: "An assembly-level TargetFrameworkAttribute names .NET Framework.",
+            file_offset: metadata.table(12)?.offset ?? null,
+        });
+    }
+    else if (frameworks.some((value) => value.startsWith(".NETCoreApp,") || value.startsWith(".NETStandard,")) ||
+        cli.readyToRunSignature) {
+        runtimeFamily = "modern-dotnet";
+        evidence.push({
+            code: cli.readyToRunSignature
+                ? "ready-to-run-signature-observed"
+                : "target-framework-observed",
+            detail: cli.readyToRunSignature
+                ? "The managed native header has the ReadyToRun signature."
+                : "An assembly-level TargetFrameworkAttribute names modern .NET.",
+            file_offset: cli.readyToRunSignature
+                ? layout.rvaToOffset(cli.managedNativeHeader.rva, 4, "cli.managed-native-header")
+                : (metadata.table(12)?.offset ?? null),
+        });
+    }
+    return { runtime_family: runtimeFamily, evidence };
+};
+const implementationFor = (cli, metadata) => {
+    if ((cli.flags & 1) === 0)
+        return "cpp-cli-mixed";
+    if (cli.readyToRunSignature)
+        return "cil-and-ready-to-run";
+    return (metadata.rowCounts[6] ?? 0) === 0 ? "metadata-only" : "cil";
+};
+const managedArchitectureFor = (layout, cli) => {
+    if (layout.architecture !== "x86" || (cli.flags & 1) === 0)
+        return layout.architecture;
+    if ((cli.flags & 0x0000_0002) !== 0)
+        return "x86";
+    if ((cli.flags & 0x0002_0000) !== 0)
+        return "anycpu-prefer-32";
+    return "anycpu";
+};
+const runtimeClassification = ({ layout, metadata, inventory, }) => {
+    const cli = layout.cli;
+    if (cli === null)
+        throw new TypeError("Managed classification requires CLI");
+    const { runtime_family: runtimeFamily, evidence } = runtimeFamilyFor(cli, inventory, metadata, layout);
+    const implementation = implementationFor(cli, metadata);
+    const managedArchitecture = managedArchitectureFor(layout, cli);
+    evidence.push({
+        code: "managed-architecture-derived",
+        detail: `Managed architecture ${managedArchitecture} is derived from PE machine and CLI flags.`,
+        file_offset: cli.headerOffset + 16,
+    });
+    return {
+        runtime_family: runtimeFamily,
+        implementation,
+        managed_architecture: managedArchitecture,
+        evidence,
+    };
+};
+const partialMetadataResult = ({ target, bytes, layout, limits, issue, }) => ({
+    ...base(target, bytes, layout),
+    classification: {
+        status: "malformed",
+        container: "pe",
+        runtime_family: (layout.cli?.flags ?? 1) & 1 ? "unknown" : "mixed-clr-native",
+        implementation: "unknown",
+        managed_architecture: "unknown",
+        evidence: [
+            {
+                code: "metadata-not-admitted",
+                detail: issue.detail,
+                file_offset: issue.offset,
+            },
+        ],
+    },
+    metadata: {
+        status: issue.code === "limit-exceeded" ? "partial" : "malformed",
+        version: null,
+        stream_names: [],
+        table_row_counts: {},
+    },
+    module: null,
+    assembly: null,
+    target_frameworks: [],
+    references: emptyPage(limits.referenceOffset, limits.referenceLimit),
+    resources: emptyPage(limits.resourceOffset, limits.resourceLimit),
+    attributes: emptyPage(limits.attributeOffset, limits.attributeLimit),
+    coverage: { state: "partial", issues: [issue] },
+    limitations: [
+        "CLI metadata triage stopped at the reported bounded format or resource limit.",
+    ],
+});
+const mapResources = (bytes, layout, issues) => {
+    const resources = layout.cli?.resources;
+    if (resources === undefined || (resources.rva === 0 && resources.size === 0))
+        return null;
+    try {
+        return {
+            offset: layout.rvaToOffset(resources.rva, resources.size, "cli.resources"),
+            size: resources.size,
+        };
+    }
+    catch (cause) {
+        if (!(cause instanceof ManagedReaderFailure))
+            throw cause;
+        issues.push(cause.issue);
+        return null;
+    }
+};
+const inventoryPagesComplete = (inventory) => inventory.references.complete &&
+    inventory.resources.complete &&
+    inventory.attributes.complete;
+/** Inspect PE/CLI identity directly from bounded bytes without CLR loading. */
+export const inspectManagedArtifactBytes = (bytes, target, limits) => {
+    const layout = readManagedPeLayout(bytes);
+    if (layout.cli === null)
+        return unavailableResult(target, bytes, layout, limits);
+    const cli = layout.cli;
+    if (cli.metadata.size > limits.maxMetadataBytes)
+        return managedArtifactInspectionSchema.parse(partialMetadataResult({
+            target,
+            bytes,
+            layout,
+            limits,
+            issue: {
+                code: "limit-exceeded",
+                scope: "cli.metadata",
+                offset: cli.headerOffset + 8,
+                detail: `CLI metadata size exceeds max_metadata_bytes ${String(limits.maxMetadataBytes)}`,
+            },
+        }));
+    let metadata;
+    try {
+        const metadataOffset = layout.rvaToOffset(cli.metadata.rva, cli.metadata.size, "cli.metadata");
+        metadata = readManagedMetadataLayout(bytes, metadataOffset, cli.metadata.size, limits.maxTableRows);
+    }
+    catch (cause) {
+        if (!(cause instanceof ManagedReaderFailure))
+            throw cause;
+        return managedArtifactInspectionSchema.parse(partialMetadataResult({
+            target,
+            bytes,
+            layout,
+            limits,
+            issue: cause.issue,
+        }));
+    }
+    const resourceIssues = [];
+    const resourceDirectory = mapResources(bytes, layout, resourceIssues);
+    const inventory = readManagedMetadataInventory(bytes, metadata, limits, resourceDirectory);
+    const issues = [...resourceIssues, ...inventory.issues];
+    const pagesComplete = inventoryPagesComplete(inventory);
+    const limitations = [
+        ...(pagesComplete
+            ? []
+            : [
+                "At least one caller-selected metadata page omits rows; use its offset and total to continue.",
+            ]),
+        ...(issues.length === 0
+            ? []
+            : [
+                "At least one bounded metadata or resource item was unavailable; coverage is partial.",
+            ]),
+        "Static inspection did not load the assembly, resolve dependencies through a CLR, decompile C#, or execute target code.",
+    ];
+    return managedArtifactInspectionSchema.parse({
+        ...base(target, bytes, layout),
+        classification: {
+            status: "managed",
+            container: "pe",
+            ...runtimeClassification({ layout, metadata, inventory }),
+        },
+        metadata: {
+            status: issues.length === 0 ? "complete" : "partial",
+            version: metadata.version,
+            stream_names: metadata.streamNames,
+            table_row_counts: managedTableRowCounts(metadata),
+        },
+        module: inventory.module,
+        assembly: inventory.assembly,
+        target_frameworks: inventory.targetFrameworks,
+        references: inventory.references,
+        resources: inventory.resources,
+        attributes: inventory.attributes,
+        coverage: {
+            state: pagesComplete && issues.length === 0 ? "complete" : "partial",
+            issues,
+        },
+        limitations,
+    });
+};

package/dist/dotnet/ManagedMemberInspector.js

@@ -0,0 +1,153 @@
+import { managedMemberInspectionSchema, } from "../domain/managedArtifact.js";
+import { readManagedPeLayout, } from "./ManagedPeReader.js";
+import { managedTableRowCounts, readManagedMetadataInventory, } from "./ManagedMetadataInventory.js";
+import { readManagedMetadataLayout } from "./ManagedMetadataLayout.js";
+import { ManagedReaderFailure, managedFailure, } from "./ManagedReaderFailure.js";
+import { emptyPage, page, parseTypes, typeRanges, } from "./ManagedMemberInspectorCore.js";
+import { edges, parseFields, parseMemberRefs, parseMethods, } from "./ManagedMemberRows.js";
+const unavailable = (target, bytes, limits, issue) => managedMemberInspectionSchema.parse({
+    schema_version: 1,
+    artifact: {
+        path: target.path,
+        sha256: target.sha256,
+        byte_length: bytes.length,
+        format: "pe",
+    },
+    module: null,
+    metadata: {
+        status: issue === null ? "absent" : "malformed",
+        version: null,
+        table_row_counts: {},
+    },
+    identity_scope: {
+        token_identity: "build-local",
+        requires_artifact_sha256: target.sha256,
+        requires_mvid: null,
+    },
+    types: emptyPage(limits.typeOffset, limits.typeLimit),
+    fields: emptyPage(limits.fieldOffset, limits.fieldLimit),
+    methods: emptyPage(limits.methodOffset, limits.methodLimit),
+    member_refs: emptyPage(limits.memberRefOffset, limits.memberRefLimit),
+    call_edges: emptyPage(limits.edgeOffset, limits.edgeLimit),
+    field_accesses: emptyPage(limits.edgeOffset, limits.edgeLimit),
+    coverage: {
+        state: "unavailable",
+        issues: issue === null ? [] : [issue],
+    },
+    limitations: [
+        issue === null
+            ? "The PE has no admitted CLI metadata; managed member inspection is unavailable."
+            : "The CLI metadata could not be admitted; managed member inspection is unavailable.",
+    ],
+});
+const resourceDirectory = (pe) => {
+    if (pe.cli === null ||
+        pe.cli.resources.rva === 0 ||
+        pe.cli.resources.size === 0)
+        return null;
+    return {
+        offset: pe.rvaToOffset(pe.cli.resources.rva, pe.cli.resources.size, "cli.resources"),
+        size: pe.cli.resources.size,
+    };
+};
+const collectMethodBodyIssues = (methods, limits) => methods.methods.flatMap((method) => method.body.status === "partial"
+    ? [
+        {
+            code: "limit-exceeded",
+            scope: `method.${method.token}.body.instructions`,
+            offset: method.body.file_offset,
+            detail: method.body.issue ??
+                `Instruction decode reached max_method_instructions ${String(limits.maxMethodInstructions)}`,
+        },
+    ]
+    : []);
+const readMemberInventory = (bytes, pe, limits) => {
+    const cli = pe.cli;
+    if (cli === null)
+        throw new TypeError("Managed inventory requires CLI metadata");
+    const rootOffset = pe.rvaToOffset(cli.metadata.rva, cli.metadata.size, "cli.metadata");
+    if (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, 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,
+    }, resourceDirectory(pe));
+    return { layout, inventory };
+};
+/** Inspect metadata members and method bodies without loading target code. */
+export const inspectManagedMembersBytes = (bytes, target, limits) => {
+    const pe = readManagedPeLayout(bytes);
+    if (pe.cli === null)
+        return unavailable(target, bytes, limits, pe.cliIssue);
+    const issues = [];
+    try {
+        const { layout, inventory } = readMemberInventory(bytes, pe, limits);
+        issues.push(...inventory.issues);
+        const ranges = typeRanges(bytes, layout, limits.maxHeapItemBytes);
+        const types = parseTypes(bytes, layout, ranges, limits.maxHeapItemBytes);
+        const fields = parseFields(bytes, layout, ranges, limits.maxHeapItemBytes);
+        const memberRefs = parseMemberRefs(bytes, layout, limits.maxHeapItemBytes);
+        const methods = parseMethods({
+            bytes,
+            layout,
+            pe,
+            ranges,
+            maxBytes: limits.maxHeapItemBytes,
+            limits,
+        });
+        const methodBodyIssues = collectMethodBodyIssues(methods, limits);
+        const coverageIssues = [...issues, ...methodBodyIssues];
+        const related = edges(methods.methods, methods.core, fields.core, memberRefs.core);
+        return managedMemberInspectionSchema.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,
+            },
+            types: page(types, limits.typeOffset, limits.typeLimit),
+            fields: page(fields.fields, limits.fieldOffset, limits.fieldLimit),
+            methods: page(methods.methods, limits.methodOffset, limits.methodLimit),
+            member_refs: page(memberRefs.refs, limits.memberRefOffset, limits.memberRefLimit),
+            call_edges: page(related.callEdges, limits.edgeOffset, limits.edgeLimit),
+            field_accesses: page(related.fieldAccesses, limits.edgeOffset, limits.edgeLimit),
+            coverage: {
+                state: coverageIssues.length === 0 ? "complete" : "partial",
+                issues: coverageIssues,
+            },
+            limitations: [
+                "Metadata tokens are build-local coordinates and are only meaningful with the reported artifact SHA-256 and MVID.",
+                "CIL instruction anchors are decoded from file-backed method bodies only; no target assembly is loaded or executed.",
+                "Signatures are decoded for common ECMA-335 primitive, class, valuetype, pointer, byref, array, and generic variable forms; unsupported forms retain raw signature hashes.",
+                ...(methodBodyIssues.length > 0
+                    ? [
+                        "At least one CIL method body reached max_method_instructions; its decoded prefix is partial and has no normalized CIL identity.",
+                    ]
+                    : []),
+            ],
+        });
+    }
+    catch (cause) {
+        if (cause instanceof ManagedReaderFailure)
+            return unavailable(target, bytes, limits, cause.issue);
+        throw cause;
+    }
+};