rea-agents 1.6.0 → 2.0.0

package/dist/domain/managedRuntimeCorrelation.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { managedMemberInspectionSchema } from "./managedArtifact.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+const managedRuntimeEffectSchema = z.enum([
+    "attach",
+    "load",
+    "debugger",
+    "reflection",
+    "instrumentation",
+]);
+const managedRuntimeHostSchema = z.strictObject({
+    os: z.enum(["linux", "macos", "windows"]),
+    clr_family: z.enum(["dotnet", "dotnet-framework", "mono", "unknown"]),
+    architecture: z.enum(["x86", "x86_64", "arm", "arm64"]),
+});
+const managedRuntimeBoundsSchema = z.strictObject({
+    timeout_ms: z.number().int().min(1).max(60_000).default(5_000),
+    max_threads: z.number().int().min(1).max(256).default(32),
+    max_output_bytes: z.number().int().min(0).max(1_048_576).default(65_536),
+    allow_network: z.literal(false).default(false),
+    allow_ui: z.literal(false).default(false),
+});
+export const managedRuntimeCorrelationInputSchema = z.strictObject({
+    static_members: evidenceSchema,
+    method: z.strictObject({
+        token: tokenSchema,
+        signature_sha256: digestSchema,
+        normalized_il_sha256: digestSchema.nullable(),
+    }),
+    requested_effect: managedRuntimeEffectSchema,
+    host: managedRuntimeHostSchema,
+    bounds: managedRuntimeBoundsSchema.default({
+        timeout_ms: 5_000,
+        max_threads: 32,
+        max_output_bytes: 65_536,
+        allow_network: false,
+        allow_ui: false,
+    }),
+    unknown_registry_approved: z.literal(true).optional(),
+});
+export const managedRuntimeCorrelationResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    correlation_id: z.string().regex(/^mrc_[a-f0-9]{64}$/u),
+    phase: z.literal("admission-plan"),
+    executed: z.literal(false),
+    authority_model: z.strictObject({
+        capability: z.literal("managed_runtime"),
+        permission_grant_id: z.string().min(1),
+        default_enabled: z.literal(false),
+        per_call_approval_required: z.literal(true),
+    }),
+    static_observation: z.strictObject({
+        evidence_id: evidenceIdSchema,
+        artifact_sha256: digestSchema,
+        artifact_path: z.string().min(1),
+        byte_length: z.number().int().min(0),
+        module_name: z.string().nullable(),
+        mvid: z.string().uuid().nullable(),
+        metadata_status: z.enum(["absent", "complete", "partial", "malformed"]),
+    }),
+    method_lock: z.strictObject({
+        token: tokenSchema,
+        declaring_type: z.string().nullable(),
+        name: z.string(),
+        signature_sha256: digestSchema,
+        normalized_il_sha256: digestSchema.nullable(),
+        body_sha256: digestSchema.nullable(),
+        il_size: z.number().int().min(0),
+        body_status: z.enum(["present", "absent", "malformed", "too-large"]),
+        exact_build_required: z.literal(true),
+    }),
+    requested_runtime: z.strictObject({
+        effect: managedRuntimeEffectSchema,
+        host: managedRuntimeHostSchema,
+        executable_path: z.string().min(1),
+        network: z.literal("none"),
+        filesystem: z.literal("owned-artifacts-only"),
+    }),
+    effect_taxonomy: z.strictObject({
+        attaches_process: z.boolean(),
+        loads_target: z.boolean(),
+        uses_debugger: z.boolean(),
+        uses_reflection: z.boolean(),
+        instruments_code: z.boolean(),
+        invokes_target_code: z.literal(false),
+    }),
+    bounds: managedRuntimeBoundsSchema,
+    unsupported_until_executor_exists: z.literal(true),
+    evidence_links: z.array(evidenceIdSchema).length(1),
+    limitations: z.array(boundedTextSchema).max(1_000),
+});
+const sha256 = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Managed runtime correlation canonicalization failed");
+    return createHash("sha256").update(serialized).digest("hex");
+};
+/** Authenticate static managed Evidence and build a non-executing runtime plan. */
+export const planManagedRuntimeCorrelation = (input, executablePath, permissionGrantId) => {
+    const staticEvidence = parseEvidence(input.static_members);
+    if (staticEvidence.operation !== "inspect_managed_members")
+        throw new TypeError("Evidence operation is not inspect_managed_members");
+    const members = managedMemberInspectionSchema.parse(staticEvidence.normalized_result);
+    const method = members.methods.items.find((item) => item.token === input.method.token &&
+        item.signature.raw_sha256 === input.method.signature_sha256 &&
+        item.body.normalized_il_sha256 === input.method.normalized_il_sha256);
+    if (method === undefined)
+        throw new TypeError("Requested method lock does not match a static managed member observation");
+    const withoutId = {
+        schema_version: 1,
+        phase: "admission-plan",
+        executed: false,
+        authority_model: {
+            capability: "managed_runtime",
+            permission_grant_id: permissionGrantId,
+            default_enabled: false,
+            per_call_approval_required: true,
+        },
+        static_observation: {
+            evidence_id: staticEvidence.evidence_id,
+            artifact_sha256: members.artifact.sha256,
+            artifact_path: members.artifact.path,
+            byte_length: members.artifact.byte_length,
+            module_name: members.module?.name ?? null,
+            mvid: members.module?.mvid ?? null,
+            metadata_status: members.metadata.status,
+        },
+        method_lock: {
+            token: method.token,
+            declaring_type: method.declaring_type,
+            name: method.name,
+            signature_sha256: method.signature.raw_sha256,
+            normalized_il_sha256: method.body.normalized_il_sha256,
+            body_sha256: method.body.il_sha256,
+            il_size: method.body.il_size,
+            body_status: method.body.status,
+            exact_build_required: true,
+        },
+        requested_runtime: {
+            effect: input.requested_effect,
+            host: input.host,
+            executable_path: executablePath,
+            network: "none",
+            filesystem: "owned-artifacts-only",
+        },
+        effect_taxonomy: effectTaxonomy(input.requested_effect),
+        bounds: input.bounds,
+        unsupported_until_executor_exists: true,
+        evidence_links: [staticEvidence.evidence_id],
+        limitations: [
+            "This operation admits and records a runtime-correlation plan only; it did not attach, load, debug, reflect, instrument, invoke, or execute target code.",
+            "Runtime agreement would be a separate runtime observation and would not retroactively turn static inference into a byte observation.",
+            "The exact artifact SHA-256, MVID, method signature, and normalized IL shape must match before any future executor can run.",
+            "Network and UI effects are not admitted by this contract.",
+        ],
+    };
+    return managedRuntimeCorrelationResultSchema.parse({
+        ...withoutId,
+        correlation_id: `mrc_${sha256(withoutId)}`,
+    });
+};
+const effectTaxonomy = (effect) => ({
+    attaches_process: effect === "attach",
+    loads_target: effect === "load" || effect === "reflection",
+    uses_debugger: effect === "debugger",
+    uses_reflection: effect === "reflection",
+    instruments_code: effect === "instrumentation",
+    invokes_target_code: false,
+});

package/dist/domain/reconstructionVerificationSchemas.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { evidenceBundleSchema } from "./evidenceBundle.js";
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 const unknownIdSchema = z.string().regex(/^unk_[a-f0-9]{64}$/u);
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
@@ -69,9 +68,8 @@ export const reconstructionSpecificationSchema = z
         });
 });
 /** Bounded reconstruction-verification input. */
-export const reconstructionVerificationInputSchema = z.object({
+export const reconstructionVerificationInputSchema = z.strictObject({
     specification: reconstructionSpecificationSchema,
-    evidence_bundle: evidenceBundleSchema,
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(100).default(100),
     unknown_registry_approved: z.literal(true).optional(),

package/dist/dotnet/ManagedArtifactInspector.js

@@ -0,0 +1,318 @@
+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 runtimeClassification = (layout, metadata, inventory) => {
+    const cli = layout.cli;
+    if (cli === null)
+        throw new TypeError("Managed classification requires CLI");
+    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),
+        });
+    }
+    const implementation = (cli.flags & 1) === 0
+        ? "cpp-cli-mixed"
+        : cli.readyToRunSignature
+            ? "cil-and-ready-to-run"
+            : (metadata.rowCounts[6] ?? 0) === 0
+                ? "metadata-only"
+                : "cil";
+    const managedArchitecture = layout.architecture === "x86" && (cli.flags & 1) !== 0
+        ? (cli.flags & 0x0000_0002) !== 0
+            ? "x86"
+            : (cli.flags & 0x0002_0000) !== 0
+                ? "anycpu-prefer-32"
+                : "anycpu"
+        : layout.architecture;
+    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;
+    }
+};
+/** 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, {
+            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, cause.issue));
+    }
+    const resourceIssues = [];
+    const resourceDirectory = mapResources(bytes, layout, resourceIssues);
+    const inventory = readManagedMetadataInventory(bytes, metadata, limits, resourceDirectory);
+    const issues = [...resourceIssues, ...inventory.issues];
+    const pagesComplete = inventory.references.complete &&
+        inventory.resources.complete &&
+        inventory.attributes.complete;
+    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,
+    });
+};