rea-agents 1.7.0 → 2.1.0

package/dist/dotnet/ManagedPeReader.js

@@ -0,0 +1,188 @@
+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 = (mapping) => {
+    const { bytes, sections, rva, size, scope } = mapping;
+    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,
+        rva: directory.rva,
+        size: 72,
+        scope: "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,
+            rva: managedNativeHeader.rva,
+            size: 4,
+            scope: "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,
+    };
+};
+const readCoffHeader = (bytes) => {
+    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);
+    return { coff, machine, sectionCount, optionalSize, characteristics };
+};
+const readOptionalHeader = (bytes, coff) => {
+    const optionalOffset = coff.coff + 20;
+    requireRange(bytes, optionalOffset, coff.optionalSize, "pe.optional-header");
+    if (coff.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);
+    return {
+        optionalOffset,
+        optionalHeader,
+        directoryCountOffset: optionalOffset + (optionalHeader === "pe32" ? 92 : 108),
+        directoryOffset: optionalOffset + (optionalHeader === "pe32" ? 96 : 112),
+    };
+};
+const readSections = (bytes, coff, optional) => {
+    const sectionOffset = add(optional.optionalOffset, coff.optionalSize, "pe.sections");
+    requireRange(bytes, sectionOffset, coff.sectionCount * 40, "pe.sections");
+    const sections = [];
+    for (let index = 0; index < coff.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);
+    }
+    return sections;
+};
+const readCliDirectory = (bytes, coff, optional) => {
+    requireRange(bytes, optional.directoryCountOffset, 4, "pe.data-directories");
+    const directoryCount = bytes.readUInt32LE(optional.directoryCountOffset);
+    if (directoryCount <= 14 ||
+        coff.optionalSize < optional.directoryOffset - optional.optionalOffset + 120)
+        return { rva: 0, size: 0 };
+    return readDirectory(bytes, optional.directoryOffset + 14 * 8);
+};
+/** 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 coff = readCoffHeader(bytes);
+    const optional = readOptionalHeader(bytes, coff);
+    const sections = readSections(bytes, coff, optional);
+    const cliDirectory = readCliDirectory(bytes, coff, optional);
+    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: coff.machine,
+        architecture: architectureFor(coff.machine),
+        optionalHeader: optional.optionalHeader,
+        sectionCount: coff.sectionCount,
+        characteristics: coff.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 });

package/dist/dotnet/ManagedStaticProvider.js

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
+import { MANAGED_TOOL_CONTRACTS, managedArtifactInputSchema, managedMemberInputSchema, managedNativeBoundaryInputSchema, } from "../contracts/managedToolContracts.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, EvidenceIntegrityError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { inspectManagedArtifactBytes } from "./ManagedArtifactInspector.js";
+import { inspectManagedMembersBytes } from "./ManagedMemberInspector.js";
+import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInspector.js";
+const IDENTITY = Object.freeze(MANAGED_STATIC_PROVIDER);
+/** Execution-free managed PE/CLI auxiliary provider. */
+export class ManagedStaticProvider {
+    #capabilities = Object.freeze(MANAGED_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: false,
+            mayShowUi: false,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: false,
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limits: Object.freeze({
+            maxResults: 500,
+            maxPayloadBytes: 4 * 1024 * 1024,
+            timeoutMs: null,
+        }),
+        limitations: limitationsFor(contract.name),
+    })));
+    identity() {
+        return IDENTITY;
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    createClient(target) {
+        return new ManagedStaticClient(target);
+    }
+}
+class ManagedStaticClient {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    async execute(operation, parameters, options) {
+        if (operation === "health")
+            return ok(createAnalysisExecution(null, IDENTITY));
+        if (!isManagedOperation(operation))
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by the managed static provider."));
+        if (this.target.format !== "pe")
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Managed static triage requires a PE target; observed ${this.target.format}.`));
+        try {
+            if (options?.signal?.aborted === true)
+                return err(new AnalysisCancelledError(operation));
+            const maxFileBytes = maxRequestedFileBytes(operation, parameters);
+            const metadata = await stat(this.target.path);
+            if (metadata.size > maxFileBytes)
+                return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Artifact size ${String(metadata.size)} exceeds max_file_bytes ${String(maxFileBytes)}.`));
+            const bytes = await readFile(this.target.path, options?.signal === undefined ? undefined : { signal: options.signal });
+            if (bytes.length > maxFileBytes)
+                return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Artifact grew beyond max_file_bytes ${String(maxFileBytes)} while it was read.`));
+            const observedDigest = createHash("sha256").update(bytes).digest("hex");
+            if (observedDigest !== this.target.sha256)
+                return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${this.target.sha256}, observed ${observedDigest} at ${this.target.path}`));
+            const result = inspectManagedOperation(operation, parameters, bytes, this.target);
+            return ok(createAnalysisExecution(result, IDENTITY, {
+                rawResult: null,
+                limitations: result.limitations,
+                subject: this.target,
+                locations: managedLocations(result),
+            }));
+        }
+        catch (cause) {
+            if (options?.signal?.aborted === true)
+                return err(new AnalysisCancelledError(operation));
+            return err(new ProviderAdapterError(IDENTITY.id, operation, { cause }));
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+}
+const isManagedOperation = (operation) => MANAGED_TOOL_CONTRACTS.some(({ name }) => name === operation);
+const limitationsFor = (operation) => Object.freeze(operation === "inspect_managed_artifact"
+    ? [
+        "This capability inventories PE/CLI identity only; inspect_managed_members admits bounded metadata members, signatures, and CIL anchors.",
+        "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+    ]
+    : operation === "inspect_managed_native_boundaries"
+        ? [
+            "This capability inventories managed declarations for native boundaries only; native exports, thunks, and addresses require separate native-provider evidence.",
+            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+        ]
+        : [
+            "This capability decodes bounded PE/CLI metadata members, signatures, and file-backed method bodies; decompiled C# and cross-build matching are separate future contracts.",
+            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+        ]);
+const maxRequestedFileBytes = (operation, parameters) => {
+    if (operation === "inspect_managed_artifact")
+        return managedArtifactInputSchema.parse(parameters).max_file_bytes;
+    if (operation === "inspect_managed_native_boundaries")
+        return managedNativeBoundaryInputSchema.parse(parameters).max_file_bytes;
+    return managedMemberInputSchema.parse(parameters).max_file_bytes;
+};
+const inspectManagedOperation = (operation, parameters, bytes, target) => {
+    if (operation === "inspect_managed_artifact") {
+        const input = managedArtifactInputSchema.parse(parameters);
+        return inspectManagedArtifactBytes(bytes, target, {
+            referenceOffset: input.reference_offset,
+            referenceLimit: input.reference_limit,
+            resourceOffset: input.resource_offset,
+            resourceLimit: input.resource_limit,
+            attributeOffset: input.attribute_offset,
+            attributeLimit: input.attribute_limit,
+            maxMetadataBytes: input.max_metadata_bytes,
+            maxTableRows: input.max_table_rows,
+            maxHeapItemBytes: input.max_heap_item_bytes,
+        });
+    }
+    if (operation === "inspect_managed_native_boundaries") {
+        const input = managedNativeBoundaryInputSchema.parse(parameters);
+        return inspectManagedNativeBoundariesBytes(bytes, target, {
+            moduleRefOffset: input.module_ref_offset,
+            moduleRefLimit: input.module_ref_limit,
+            importOffset: input.import_offset,
+            importLimit: input.import_limit,
+            implementationOffset: input.implementation_offset,
+            implementationLimit: input.implementation_limit,
+            maxMetadataBytes: input.max_metadata_bytes,
+            maxTableRows: input.max_table_rows,
+            maxHeapItemBytes: input.max_heap_item_bytes,
+        });
+    }
+    const input = managedMemberInputSchema.parse(parameters);
+    return inspectManagedMembersBytes(bytes, target, {
+        typeOffset: input.type_offset,
+        typeLimit: input.type_limit,
+        methodOffset: input.method_offset,
+        methodLimit: input.method_limit,
+        fieldOffset: input.field_offset,
+        fieldLimit: input.field_limit,
+        memberRefOffset: input.member_ref_offset,
+        memberRefLimit: input.member_ref_limit,
+        edgeOffset: input.edge_offset,
+        edgeLimit: input.edge_limit,
+        instructionAnchorLimit: input.instruction_anchor_limit,
+        maxMetadataBytes: input.max_metadata_bytes,
+        maxTableRows: input.max_table_rows,
+        maxHeapItemBytes: input.max_heap_item_bytes,
+        maxMethodBodyBytes: input.max_method_body_bytes,
+        maxMethodInstructions: input.max_method_instructions,
+    });
+};
+const managedLocations = (result) => {
+    if ("pe" in result) {
+        if (result.pe.cli === null)
+            return [{ kind: "file-offset", offset: 0 }];
+        return [
+            {
+                kind: "file-offset-range",
+                start: result.pe.cli.header_offset,
+                end: result.pe.cli.header_offset + result.pe.cli.header_size,
+            },
+            ...[result.module, result.assembly]
+                .filter((value) => value !== null)
+                .map((value) => ({
+                kind: "file-offset",
+                offset: value.row_offset,
+            })),
+        ];
+    }
+    if ("methods" in result)
+        return [
+            ...(result.module === null
+                ? [{ kind: "file-offset", offset: 0 }]
+                : [{ kind: "file-offset", offset: result.module.row_offset }]),
+            ...result.methods.items
+                .filter((method) => method.body.file_offset !== null)
+                .slice(0, 8)
+                .map((method) => ({
+                kind: "file-offset",
+                offset: method.body.file_offset ?? 0,
+            })),
+        ];
+    return [
+        ...(result.module === null
+            ? [{ kind: "file-offset", offset: 0 }]
+            : [{ kind: "file-offset", offset: result.module.row_offset }]),
+        ...result.pinvoke_imports.items.slice(0, 8).map((mapping) => ({
+            kind: "file-offset",
+            offset: mapping.row_offset,
+        })),
+    ];
+};

package/dist/generatedPackageMetadata.js

@@ -1,9 +1,9 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "1.7.0",
+    version: "2.1.0",
     serverSdkVersion: "2.0.0-beta.4",
     clientSdkVersion: "2.0.0-beta.4",
     coreSdkVersion: "2.0.0-beta.4",
-    skillVersion: "14",
+    skillVersion: "22",
 };