rea-agents 1.6.0 → 2.0.0

package/dist/domain/managedApplicationGraph.js

@@ -0,0 +1,556 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { createJavaScriptApplicationEdge, createJavaScriptApplicationGraph, createJavaScriptApplicationNode, javascriptApplicationGraphSchema, } from "./javascriptApplicationGraph.js";
+import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } 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 boundedTextSchema = z.string().min(1).max(4_096);
+const managedApplicationGraphLimitsSchema = z.strictObject({
+    max_types: z.number().int().min(0).max(100_000).default(5_000),
+    max_methods: z.number().int().min(0).max(100_000).default(10_000),
+    max_fields: z.number().int().min(0).max(100_000).default(5_000),
+    max_pinvoke_imports: z.number().int().min(0).max(100_000).default(5_000),
+    max_native_implementations: z
+        .number()
+        .int()
+        .min(0)
+        .max(100_000)
+        .default(5_000),
+});
+/** Authenticated managed Evidence records projected into the application graph. */
+export const projectManagedApplicationGraphInputSchema = z
+    .strictObject({
+    managed_artifact: evidenceSchema.optional(),
+    managed_members: evidenceSchema.optional(),
+    managed_native_boundaries: evidenceSchema.optional(),
+    limits: managedApplicationGraphLimitsSchema.default({
+        max_types: 5_000,
+        max_methods: 10_000,
+        max_fields: 5_000,
+        max_pinvoke_imports: 5_000,
+        max_native_implementations: 5_000,
+    }),
+})
+    .superRefine((input, context) => {
+    if (input.managed_artifact === undefined &&
+        input.managed_members === undefined &&
+        input.managed_native_boundaries === undefined)
+        context.addIssue({
+            code: "custom",
+            message: "At least one managed artifact, member, or native-boundary Evidence record is required",
+        });
+});
+/** Managed-code projection result containing a validated application graph. */
+export const managedApplicationGraphResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    projection_id: z.string().regex(/^magp_[a-f0-9]{64}$/u),
+    root_artifact_sha256: digestSchema,
+    source_evidence: z.strictObject({
+        managed_artifact_evidence_id: evidenceIdSchema.nullable(),
+        managed_members_evidence_id: evidenceIdSchema.nullable(),
+        managed_native_boundaries_evidence_id: evidenceIdSchema.nullable(),
+    }),
+    summary: z.strictObject({
+        graph_nodes: z.number().int().min(0),
+        graph_edges: z.number().int().min(0),
+        assemblies: z.number().int().min(0),
+        modules: z.number().int().min(0),
+        types: z.number().int().min(0),
+        methods: z.number().int().min(0),
+        fields: z.number().int().min(0),
+        pinvoke_imports: z.number().int().min(0),
+        native_implementations: z.number().int().min(0),
+    }),
+    graph: javascriptApplicationGraphSchema,
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inputs", "partial", "truncated"]),
+        omitted_types: z.number().int().min(0),
+        omitted_methods: z.number().int().min(0),
+        omitted_fields: z.number().int().min(0),
+        omitted_pinvoke_imports: z.number().int().min(0),
+        omitted_native_implementations: z.number().int().min(0),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(3),
+    limitations: z.array(boundedTextSchema).max(1_000),
+});
+const sha256 = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Managed application graph canonicalization failed");
+    return createHash("sha256").update(serialized).digest("hex");
+};
+/** Project authenticated managed Evidence records into the application graph. */
+export const projectManagedApplicationGraph = (input) => {
+    const parsed = parseManagedInputs(input);
+    const artifactIdentity = chooseArtifact(parsed);
+    assertSameArtifact(parsed, artifactIdentity.sha256);
+    const evidenceLinks = [
+        parsed.artifact?.evidence.evidence_id,
+        parsed.members?.evidence.evidence_id,
+        parsed.boundaries?.evidence.evidence_id,
+    ].filter((id) => id !== undefined);
+    const state = {
+        nodes: [],
+        edges: [],
+        artifactSha256: artifactIdentity.sha256,
+        artifactPath: artifactIdentity.path,
+        evidenceLinks,
+        typeNodes: new Map(),
+        methodNodes: new Map(),
+        fieldNodes: new Map(),
+    };
+    const artifactNode = addArtifactNode(state);
+    addArtifactIdentityNodes(state, artifactNode, parsed);
+    const memberCounts = addMemberNodes(state, artifactNode, parsed, input.limits);
+    const boundaryCounts = addBoundaryNodes(state, artifactNode, parsed, input.limits);
+    const omissions = omittedCounts(parsed, input.limits);
+    const limitations = projectionLimitations(parsed, omissions);
+    const graph = createJavaScriptApplicationGraph({
+        schema: "JavaScriptApplicationGraph",
+        schema_version: 1,
+        root_node_ids: [artifactNode.node_id],
+        nodes: state.nodes,
+        edges: state.edges,
+        coverage: graphCoverage(omissions),
+        limitations,
+    });
+    const withoutId = {
+        schema_version: 1,
+        root_artifact_sha256: state.artifactSha256,
+        source_evidence: {
+            managed_artifact_evidence_id: parsed.artifact?.evidence.evidence_id ?? null,
+            managed_members_evidence_id: parsed.members?.evidence.evidence_id ?? null,
+            managed_native_boundaries_evidence_id: parsed.boundaries?.evidence.evidence_id ?? null,
+        },
+        summary: {
+            graph_nodes: graph.nodes.length,
+            graph_edges: graph.edges.length,
+            assemblies: parsed.artifact?.result.assembly === null ? 0 : 1,
+            modules: parsed.artifact?.result.module === null ? 0 : 1,
+            ...memberCounts,
+            ...boundaryCounts,
+        },
+        graph,
+        coverage: resultCoverage(omissions),
+        evidence_links: evidenceLinks,
+        limitations,
+    };
+    return managedApplicationGraphResultSchema.parse({
+        ...withoutId,
+        projection_id: `magp_${sha256(withoutId)}`,
+    });
+};
+const parseManagedInputs = (input) => ({
+    artifact: input.managed_artifact === undefined
+        ? null
+        : parseManagedEvidence(input.managed_artifact, "inspect_managed_artifact", managedArtifactInspectionSchema),
+    members: input.managed_members === undefined
+        ? null
+        : parseManagedEvidence(input.managed_members, "inspect_managed_members", managedMemberInspectionSchema),
+    boundaries: input.managed_native_boundaries === undefined
+        ? null
+        : parseManagedEvidence(input.managed_native_boundaries, "inspect_managed_native_boundaries", managedNativeBoundaryInspectionSchema),
+});
+const parseManagedEvidence = (rawEvidence, operation, schema) => {
+    const evidence = parseEvidence(rawEvidence);
+    if (evidence.operation !== operation)
+        throw new TypeError(`Evidence operation is not ${operation}`);
+    return { evidence, result: schema.parse(evidence.normalized_result) };
+};
+const chooseArtifact = (parsed) => {
+    const result = parsed.artifact?.result ??
+        parsed.members?.result ??
+        parsed.boundaries?.result;
+    if (result === undefined)
+        throw new TypeError("Managed graph projection requires managed Evidence");
+    return { sha256: result.artifact.sha256, path: result.artifact.path };
+};
+const assertSameArtifact = (parsed, sha256Value) => {
+    for (const result of [
+        parsed.artifact?.result,
+        parsed.members?.result,
+        parsed.boundaries?.result,
+    ])
+        if (result !== undefined && result.artifact.sha256 !== sha256Value)
+            throw new TypeError("Managed graph projection inputs must describe the same artifact SHA-256");
+};
+const addArtifactNode = (state) => {
+    const node = createJavaScriptApplicationNode({
+        kind: "artifact",
+        identity: {
+            strategy: "content-digest",
+            stability: "global-exact",
+            sha256: state.artifactSha256,
+        },
+        observations: [
+            {
+                label: basename(state.artifactPath),
+                properties: {
+                    format: "pe",
+                    source: "managed-application-graph",
+                },
+                evidence: managedEvidence(state, "project-managed-artifact"),
+            },
+        ],
+    });
+    state.nodes.push(node);
+    return node;
+};
+const addArtifactIdentityNodes = (state, artifactNode, parsed) => {
+    const artifact = parsed.artifact?.result;
+    if (artifact?.assembly !== undefined && artifact.assembly !== null) {
+        const assembly = createJavaScriptApplicationNode({
+            kind: "managed-assembly",
+            identity: artifactLocalIdentity(state.artifactSha256, "managed-assembly", artifact.assembly.token),
+            observations: [
+                {
+                    label: artifact.assembly.name,
+                    properties: {
+                        name: artifact.assembly.name,
+                        version: artifact.assembly.version,
+                        culture: artifact.assembly.culture,
+                        public_key_kind: artifact.assembly.public_key.kind,
+                    },
+                    evidence: managedEvidence(state, "inspect_managed_artifact"),
+                },
+            ],
+        });
+        state.nodes.push(assembly);
+        addContainsEdge(state, artifactNode, assembly, "declares-managed-assembly");
+    }
+    const module = artifact?.module ??
+        parsed.members?.result.module ??
+        parsed.boundaries?.result.module;
+    if (module !== undefined && module !== null) {
+        const moduleNode = createJavaScriptApplicationNode({
+            kind: "managed-module",
+            identity: artifactLocalIdentity(state.artifactSha256, "managed-module", module.mvid ?? module.token),
+            observations: [
+                {
+                    label: module.name,
+                    properties: {
+                        name: module.name,
+                        mvid: module.mvid,
+                        generation: module.generation,
+                        token: module.token,
+                    },
+                    evidence: managedEvidence(state, "inspect_managed_artifact"),
+                },
+            ],
+        });
+        state.nodes.push(moduleNode);
+        addContainsEdge(state, artifactNode, moduleNode, "declares-managed-module");
+    }
+};
+const addMemberNodes = (state, artifactNode, parsed, limits) => {
+    const members = parsed.members?.result;
+    if (members === undefined)
+        return { types: 0, methods: 0, fields: 0 };
+    const types = members.types.items.slice(0, limits.max_types);
+    const methods = members.methods.items.slice(0, limits.max_methods);
+    const fields = members.fields.items.slice(0, limits.max_fields);
+    for (const type of types) {
+        const node = typeNode(state, type);
+        state.nodes.push(node);
+        state.typeNodes.set(type.token, node);
+        addContainsEdge(state, artifactNode, node, "declares-managed-type");
+    }
+    for (const method of methods) {
+        const node = methodNode(state, method);
+        state.nodes.push(node);
+        state.methodNodes.set(method.token, node);
+        const owner = method.declaring_type_token === null
+            ? artifactNode
+            : (state.typeNodes.get(method.declaring_type_token) ?? artifactNode);
+        addContainsEdge(state, owner, node, "declares-managed-method");
+    }
+    for (const field of fields) {
+        const node = fieldNode(state, field);
+        state.nodes.push(node);
+        state.fieldNodes.set(field.token, node);
+        const owner = field.declaring_type_token === null
+            ? artifactNode
+            : (state.typeNodes.get(field.declaring_type_token) ?? artifactNode);
+        addContainsEdge(state, owner, node, "declares-managed-field");
+    }
+    return {
+        types: types.length,
+        methods: methods.length,
+        fields: fields.length,
+    };
+};
+const typeNode = (state, type) => createJavaScriptApplicationNode({
+    kind: "managed-type",
+    identity: artifactLocalIdentity(state.artifactSha256, "managed-type-token", type.token),
+    observations: [
+        {
+            label: type.full_name,
+            properties: {
+                token: type.token,
+                namespace: type.namespace,
+                name: type.name,
+                full_name: type.full_name,
+                flags: type.flags,
+                extends_token: type.extends_token,
+            },
+            evidence: managedEvidence(state, "inspect_managed_members"),
+        },
+    ],
+});
+const methodNode = (state, method) => createJavaScriptApplicationNode({
+    kind: "managed-method",
+    identity: artifactLocalIdentity(state.artifactSha256, "managed-method-token", method.token),
+    observations: [
+        {
+            label: method.declaring_type === null
+                ? method.name
+                : `${method.declaring_type}.${method.name}`,
+            properties: {
+                token: method.token,
+                declaring_type_token: method.declaring_type_token,
+                declaring_type: method.declaring_type,
+                name: method.name,
+                rva: method.rva,
+                signature_sha256: method.signature.raw_sha256,
+                signature_status: method.signature.parse_status,
+                body_status: method.body.status,
+                normalized_il_sha256: method.body.normalized_il_sha256,
+                il_size: method.body.il_size,
+            },
+            evidence: managedEvidence(state, "inspect_managed_members"),
+        },
+    ],
+});
+const fieldNode = (state, field) => createJavaScriptApplicationNode({
+    kind: "managed-field",
+    identity: artifactLocalIdentity(state.artifactSha256, "managed-field-token", field.token),
+    observations: [
+        {
+            label: field.declaring_type === null
+                ? field.name
+                : `${field.declaring_type}.${field.name}`,
+            properties: {
+                token: field.token,
+                declaring_type_token: field.declaring_type_token,
+                declaring_type: field.declaring_type,
+                name: field.name,
+                flags: field.flags,
+                signature_sha256: field.signature.raw_sha256,
+                signature_status: field.signature.parse_status,
+            },
+            evidence: managedEvidence(state, "inspect_managed_members"),
+        },
+    ],
+});
+const addBoundaryNodes = (state, artifactNode, parsed, limits) => {
+    const boundaries = parsed.boundaries?.result;
+    if (boundaries === undefined)
+        return { pinvoke_imports: 0, native_implementations: 0 };
+    const pinvokes = boundaries.pinvoke_imports.items.slice(0, limits.max_pinvoke_imports);
+    const implementations = boundaries.native_implementations.items.slice(0, limits.max_native_implementations);
+    for (const pinvoke of pinvokes) {
+        const node = pinvokeNode(state, pinvoke);
+        state.nodes.push(node);
+        const owner = pinvoke.member_token === null
+            ? artifactNode
+            : (state.methodNodes.get(pinvoke.member_token) ?? artifactNode);
+        state.edges.push(createJavaScriptApplicationEdge({
+            source_node_id: owner.node_id,
+            target_node_id: node.node_id,
+            relation: "imports",
+            properties: {
+                kind: "managed-pinvoke",
+                import_name: pinvoke.import_name,
+                import_scope_name: pinvoke.import_scope_name,
+            },
+            evidence: managedEvidence(state, "inspect_managed_native_boundaries"),
+        }));
+    }
+    for (const implementation of implementations) {
+        const node = nativeImplementationNode(state, implementation);
+        state.nodes.push(node);
+        const owner = state.methodNodes.get(implementation.token) ?? artifactNode;
+        addContainsEdge(state, owner, node, "declares-managed-native-implementation");
+    }
+    return {
+        pinvoke_imports: pinvokes.length,
+        native_implementations: implementations.length,
+    };
+};
+const pinvokeNode = (state, pinvoke) => createJavaScriptApplicationNode({
+    kind: "managed-pinvoke-import",
+    identity: artifactLocalIdentity(state.artifactSha256, "managed-pinvoke-token", pinvoke.token),
+    observations: [
+        {
+            label: pinvoke.import_name,
+            properties: {
+                token: pinvoke.token,
+                member_token: pinvoke.member_token,
+                member_name: pinvoke.member_name,
+                import_name: pinvoke.import_name,
+                import_scope_name: pinvoke.import_scope_name,
+                char_set: pinvoke.char_set,
+                call_convention: pinvoke.call_convention,
+                verification: pinvoke.verification,
+            },
+            evidence: managedEvidence(state, "inspect_managed_native_boundaries"),
+        },
+    ],
+});
+const nativeImplementationNode = (state, implementation) => createJavaScriptApplicationNode({
+    kind: "managed-native-implementation",
+    identity: artifactLocalIdentity(state.artifactSha256, "managed-native-implementation-token", implementation.token),
+    observations: [
+        {
+            label: implementation.name,
+            properties: {
+                token: implementation.token,
+                name: implementation.name,
+                rva: implementation.rva,
+                code_type: implementation.code_type,
+                managed_kind: implementation.managed_kind,
+                pinvoke_declared: implementation.pinvoke_declared,
+                boundary_kind: implementation.boundary_kind,
+                body_interpretation: implementation.body_interpretation,
+            },
+            evidence: managedEvidence(state, "inspect_managed_native_boundaries"),
+        },
+    ],
+});
+const addContainsEdge = (state, source, target, kind) => {
+    state.edges.push(createJavaScriptApplicationEdge({
+        source_node_id: source.node_id,
+        target_node_id: target.node_id,
+        relation: "contains",
+        properties: { kind },
+        evidence: managedEvidence(state, "project-managed-contains"),
+    }));
+};
+const artifactLocalIdentity = (artifactSha256, namespace, key) => ({
+    strategy: "artifact-local-key",
+    stability: "artifact-version",
+    artifact_sha256: artifactSha256,
+    namespace,
+    key,
+});
+const managedEvidence = (state, operation) => ({
+    authority: "managed-static-analysis",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: true,
+        artifact_id: `art_${state.artifactSha256}`,
+        sha256: state.artifactSha256,
+    },
+    location: {
+        available: true,
+        value: {
+            kind: "artifact-path",
+            path: graphArtifactPath(state.artifactPath),
+        },
+    },
+    extractor: {
+        name: "rea-dotnet-static",
+        version: "1",
+        operation,
+        executable_sha256: null,
+    },
+    coverage: completeCoverage(),
+    limitations: [],
+    evidence_ids: state.evidenceLinks,
+});
+const graphArtifactPath = (path) => {
+    const name = basename(path).replaceAll(/[^A-Za-z0-9._-]/gu, "_");
+    return `managed/${name.length === 0 ? "artifact.pe" : name}`;
+};
+const completeCoverage = () => ({
+    status: "complete",
+    truncated: false,
+    omitted_count: 0,
+    limits: [],
+});
+const graphCoverage = (omissions) => {
+    const omitted = totalOmitted(omissions);
+    return {
+        status: omitted === 0 ? "complete" : "partial",
+        truncated: omitted > 0,
+        omitted_count: omitted,
+        limits: [
+            { name: "max_types", value: omissions.limits.max_types, unit: "items" },
+            {
+                name: "max_methods",
+                value: omissions.limits.max_methods,
+                unit: "items",
+            },
+            { name: "max_fields", value: omissions.limits.max_fields, unit: "items" },
+            {
+                name: "max_pinvoke_imports",
+                value: omissions.limits.max_pinvoke_imports,
+                unit: "items",
+            },
+            {
+                name: "max_native_implementations",
+                value: omissions.limits.max_native_implementations,
+                unit: "items",
+            },
+        ],
+    };
+};
+const resultCoverage = (omissions) => {
+    const omitted = totalOmitted(omissions);
+    return {
+        status: omitted > 0
+            ? "truncated"
+            : omissions.partialInput
+                ? "partial"
+                : "complete-within-inputs",
+        omitted_types: omissions.types,
+        omitted_methods: omissions.methods,
+        omitted_fields: omissions.fields,
+        omitted_pinvoke_imports: omissions.pinvokeImports,
+        omitted_native_implementations: omissions.nativeImplementations,
+    };
+};
+const omittedCounts = (parsed, limits) => ({
+    limits,
+    partialInput: (parsed.members !== null &&
+        parsed.members.result.coverage.state !== "complete") ||
+        (parsed.boundaries !== null &&
+            parsed.boundaries.result.coverage.state !== "complete") ||
+        (parsed.artifact !== null &&
+            parsed.artifact.result.coverage.state !== "complete"),
+    types: Math.max(0, (parsed.members?.result.types.items.length ?? 0) - limits.max_types),
+    methods: Math.max(0, (parsed.members?.result.methods.items.length ?? 0) - limits.max_methods),
+    fields: Math.max(0, (parsed.members?.result.fields.items.length ?? 0) - limits.max_fields),
+    pinvokeImports: Math.max(0, (parsed.boundaries?.result.pinvoke_imports.items.length ?? 0) -
+        limits.max_pinvoke_imports),
+    nativeImplementations: Math.max(0, (parsed.boundaries?.result.native_implementations.items.length ?? 0) -
+        limits.max_native_implementations),
+});
+const totalOmitted = (omissions) => omissions.types +
+    omissions.methods +
+    omissions.fields +
+    omissions.pinvokeImports +
+    omissions.nativeImplementations;
+const projectionLimitations = (parsed, omissions) => [
+    "Managed graph projection preserves static metadata observations only; it does not execute managed code, load assemblies, or map managed tokens to native addresses.",
+    ...(parsed.members === null
+        ? [
+            "Managed member Evidence was not supplied; type, method, and field nodes are absent.",
+        ]
+        : []),
+    ...(parsed.boundaries === null
+        ? [
+            "Managed native-boundary Evidence was not supplied; P/Invoke and native-implementation nodes are absent.",
+        ]
+        : []),
+    ...(omissions.partialInput
+        ? ["At least one supplied managed Evidence record has partial coverage."]
+        : []),
+    ...(totalOmitted(omissions) > 0
+        ? ["Projection output was truncated by managed application graph limits."]
+        : []),
+];