rea-agents 1.7.0 → 2.1.0

package/dist/domain/javascriptRuntimeReconciliationRuntime.js

@@ -0,0 +1,316 @@
+import { createJavaScriptApplicationEdge, createJavaScriptApplicationNode, } from "./javascriptApplicationGraph.js";
+/** Project authorized passive capture metadata into capture-scoped JAG nodes. */
+export const projectRuntimeCaptures = (captures, maximumEntities) => {
+    if (maximumEntities < captures.length)
+        throw new TypeError("Runtime entity limit must admit one target for every capture");
+    const all = captures.flatMap(projectCapture);
+    const targets = all.filter(({ kind }) => kind === "target");
+    const nonTargets = all.filter(({ kind }) => kind !== "target");
+    const retained = [...targets, ...nonTargets].slice(0, maximumEntities);
+    const retainedIds = new Set(retained.map(({ node }) => node.node_id));
+    const nodes = retained.map(({ node }) => node);
+    const edges = captures
+        .flatMap((capture) => runtimeEdges(capture, all))
+        .filter(({ source_node_id: source, target_node_id: target }) => retainedIds.has(source) && retainedIds.has(target));
+    const targetNodeByEvidenceId = new Map(retained
+        .filter(({ kind }) => kind === "target")
+        .map(({ capture, node }) => [capture.evidence.evidence_id, node]));
+    return {
+        entities: retained,
+        nodes,
+        edges,
+        targetNodeByEvidenceId,
+        omittedEntities: all.length - retained.length,
+    };
+};
+const projectCapture = (capture) => {
+    const target = targetEntity(capture);
+    return [
+        target,
+        ...frameEntities(capture),
+        ...scriptEntities(capture),
+        ...workerEntities(capture),
+    ];
+};
+const targetEntity = (capture) => {
+    const target = capture.inspection.target;
+    const location = "url" in target
+        ? { kind: "url", value: target.url }
+        : { kind: "file", value: target.file_path };
+    return runtimeEntity(capture, {
+        kind: "target",
+        nodeKind: "target",
+        runtimeKey: target.target_id,
+        targetKey: target.target_id,
+        frameKey: null,
+        scriptKey: null,
+        location,
+        staticKind: "renderer",
+        sourceSha256: null,
+        label: target.title,
+        properties: {
+            runtime_type: target.type,
+            location: location.value.slice(0, 4_096),
+            attached: target.attached,
+        },
+        section: "target",
+    });
+};
+const frameEntities = (capture) => capture.inspection.frames.map((frame) => {
+    const location = "url" in frame
+        ? { kind: "url", value: frame.url }
+        : { kind: "file", value: frame.file_path };
+    return runtimeEntity(capture, {
+        kind: "frame",
+        nodeKind: "frame",
+        runtimeKey: frame.frame_id,
+        targetKey: capture.inspection.target.target_id,
+        frameKey: frame.frame_id,
+        scriptKey: null,
+        location,
+        staticKind: "renderer",
+        sourceSha256: null,
+        label: location.value,
+        properties: {
+            parent_frame_id: frame.parent_frame_id,
+            location: location.value.slice(0, 4_096),
+        },
+        section: "frames",
+    });
+});
+const scriptEntities = (capture) => capture.inspection.scripts.items.map((script) => {
+    const location = "url" in script
+        ? { kind: "url", value: script.url }
+        : { kind: "file", value: script.file_path };
+    return runtimeEntity(capture, {
+        kind: "script",
+        nodeKind: "runtime-script-instance",
+        runtimeKey: script.script_key,
+        targetKey: capture.inspection.target.target_id,
+        frameKey: script.frame_id,
+        scriptKey: script.script_key,
+        location,
+        staticKind: "javascript",
+        sourceSha256: script.source.included
+            ? script.source.artifact.sha256
+            : null,
+        label: location.value,
+        properties: {
+            location: location.value.slice(0, 4_096),
+            cdp_hash: script.cdp_hash,
+            length: script.length,
+            is_module: script.is_module,
+            language: script.language,
+            source_sha256: script.source.included
+                ? script.source.artifact.sha256
+                : null,
+            ...("source_map_url" in script
+                ? { source_map_url: script.source_map_url }
+                : {}),
+        },
+        section: "scripts",
+        ...(script.source.included
+            ? { artifactSha256: script.source.artifact.sha256 }
+            : {}),
+    });
+});
+const workerEntities = (capture) => capture.inspection.workers.map((worker) => {
+    const location = "url" in worker
+        ? { kind: "url", value: worker.url }
+        : { kind: "file", value: worker.file_path };
+    const serviceWorker = worker.type.includes("service");
+    return runtimeEntity(capture, {
+        kind: "worker",
+        nodeKind: serviceWorker ? "service-worker" : "worker",
+        runtimeKey: worker.target_id,
+        targetKey: worker.target_id,
+        frameKey: worker.parent_frame_id,
+        scriptKey: null,
+        location,
+        staticKind: serviceWorker ? "service-worker" : "worker",
+        sourceSha256: null,
+        label: location.value,
+        properties: {
+            runtime_type: worker.type,
+            location: location.value.slice(0, 4_096),
+            attached: worker.attached,
+            opener_target_id: worker.opener_target_id,
+            parent_frame_id: worker.parent_frame_id,
+        },
+        section: "workers",
+    });
+});
+const runtimeEntity = (capture, input) => ({
+    kind: input.kind,
+    section: input.section,
+    capture,
+    runtimeKey: input.runtimeKey,
+    location: input.location,
+    frameKey: input.frameKey,
+    sourceSha256: input.sourceSha256,
+    staticKind: input.staticKind,
+    node: createJavaScriptApplicationNode({
+        kind: input.nodeKind,
+        identity: {
+            strategy: "runtime-instance",
+            stability: "capture-only",
+            capture_sha256: capture.captureSha256,
+            runtime_key: input.runtimeKey,
+        },
+        observations: [
+            {
+                label: input.label.slice(0, 1_024) || null,
+                properties: input.properties,
+                evidence: runtimeEvidence(capture, input),
+            },
+        ],
+    }),
+});
+const runtimeEvidence = (capture, input) => ({
+    authority: "passive-cdp-runtime",
+    state: "observed",
+    confidence: "exact",
+    artifact: input.artifactSha256 === undefined
+        ? {
+            available: false,
+            reason: input.section === "scripts" ? "not-observed" : "not-applicable",
+            detail: input.section === "scripts"
+                ? "Script source bytes were not included in this passive capture."
+                : "This runtime entity has no standalone artifact bytes.",
+        }
+        : {
+            available: true,
+            artifact_id: `art_${input.artifactSha256}`,
+            sha256: input.artifactSha256,
+        },
+    location: {
+        available: true,
+        value: {
+            kind: "runtime",
+            capture_sha256: capture.captureSha256,
+            target_key: input.targetKey,
+            frame_key: input.frameKey,
+            script_key: input.scriptKey,
+        },
+    },
+    extractor: {
+        name: capture.evidence.provider.id,
+        version: capture.evidence.provider.version ??
+            (capture.kind === "browser" ? "2" : "1"),
+        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        executable_sha256: null,
+    },
+    coverage: runtimeSectionCoverage(capture, input.section),
+    limitations: [
+        "The entity was observed only within one bounded passive CDP capture.",
+        ...(runtimeSectionComplete(capture, input.section)
+            ? []
+            : [
+                `The runtime ${input.section} inventory was incomplete within this capture.`,
+            ]),
+    ],
+    evidence_ids: [capture.evidence.evidence_id],
+});
+const runtimeEdges = (capture, entities) => {
+    const local = entities.filter(({ capture: candidate }) => candidate.evidence.evidence_id === capture.evidence.evidence_id);
+    const target = local.find(({ kind }) => kind === "target");
+    if (target === undefined)
+        return [];
+    const frames = new Map(local
+        .filter(({ kind }) => kind === "frame")
+        .map((entity) => [entity.runtimeKey, entity]));
+    return local.flatMap((entity) => {
+        if (entity === target)
+            return [];
+        const parent = (entity.kind === "script" || entity.kind === "worker") &&
+            entity.frameKey !== null
+            ? (frames.get(entity.frameKey) ?? target)
+            : target;
+        return [
+            createJavaScriptApplicationEdge({
+                source_node_id: parent.node.node_id,
+                target_node_id: entity.node.node_id,
+                relation: entity.kind === "script" ? "loads" : "contains",
+                properties: { basis: "passive-cdp-observation" },
+                evidence: runtimeRelationshipEvidence(capture, entity),
+            }),
+        ];
+    });
+};
+const runtimeRelationshipEvidence = (capture, entity) => ({
+    authority: "passive-cdp-runtime",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: false,
+        reason: "not-applicable",
+        detail: "The relationship is runtime metadata, not standalone bytes.",
+    },
+    location: {
+        available: true,
+        value: {
+            kind: "runtime",
+            capture_sha256: capture.captureSha256,
+            target_key: capture.inspection.target.target_id,
+            frame_key: entity.frameKey,
+            script_key: entity.kind === "script" ? entity.runtimeKey : null,
+        },
+    },
+    extractor: {
+        name: capture.evidence.provider.id,
+        version: capture.evidence.provider.version ??
+            (capture.kind === "browser" ? "2" : "1"),
+        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        executable_sha256: null,
+    },
+    coverage: runtimeSectionCoverage(capture, entity.section),
+    limitations: [
+        "The relationship was observed only within one bounded passive CDP capture.",
+    ],
+    evidence_ids: [capture.evidence.evidence_id],
+});
+const runtimeSectionComplete = (capture, section) => {
+    if (section === "target")
+        return true;
+    if (section === "scripts")
+        return capture.scriptsCompleteWithinScope;
+    return (!capture.inspection.completeness.truncated_sections.includes(section) &&
+        !capture.inspection.completeness.unavailable_sections.includes(section));
+};
+const runtimeSectionCoverage = (capture, section) => {
+    if (runtimeSectionComplete(capture, section))
+        return {
+            status: "complete",
+            truncated: false,
+            omitted_count: 0,
+            limits: [],
+        };
+    const truncated = section !== "target" &&
+        capture.inspection.completeness.truncated_sections.includes(section);
+    return {
+        status: "partial",
+        truncated,
+        omitted_count: null,
+        limits: truncated
+            ? [
+                {
+                    name: `passive-cdp-${section}-limit`,
+                    value: runtimeSectionCount(capture, section),
+                    unit: "items",
+                },
+            ]
+            : [],
+    };
+};
+const runtimeSectionCount = (capture, section) => {
+    switch (section) {
+        case "target":
+            return 1;
+        case "frames":
+            return capture.inspection.frames.length;
+        case "scripts":
+            return capture.inspection.scripts.items.length;
+        case "workers":
+            return capture.inspection.workers.length;
+    }
+};

package/dist/domain/javascriptRuntimeReconciliationSchemas.js

@@ -0,0 +1,245 @@
+import { isAbsolute, resolve } from "node:path";
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+import { compareCodePoints, javascriptApplicationGraphSchema, } from "./javascriptApplicationGraph.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const nodeIdSchema = z.string().regex(/^jag_node_[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+const safePrefixSchema = z
+    .string()
+    .max(4_096)
+    .refine((value) => value === "" ||
+    (!value.startsWith("/") &&
+        !value.includes("\\") &&
+        value.split("/").every((part) => !["", ".", ".."].includes(part))), "Artifact prefix must be empty or a safe relative POSIX path");
+const runtimeFileMappingSchema = z.strictObject({
+    kind: z.literal("file-root"),
+    root: z
+        .string()
+        .min(1)
+        .max(16_384)
+        .refine(isAbsolute, "Runtime file mapping root must be absolute")
+        .overwrite((value) => resolve(value)),
+    artifact_prefix: safePrefixSchema.default(""),
+});
+const runtimeUrlMappingSchema = z.strictObject({
+    kind: z.literal("url-prefix"),
+    prefix: z
+        .string()
+        .min(1)
+        .max(16_384)
+        .refine((value) => normalizeRuntimeUrlPrefix(value) !== null, "Runtime URL prefix must be HTTP(S) without credentials, query, or fragment")
+        .overwrite((value) => normalizeRuntimeUrlPrefix(value) ?? value),
+    artifact_prefix: safePrefixSchema.default(""),
+});
+const normalizeRuntimeUrlPrefix = (value) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (!["http:", "https:"].includes(url.protocol) ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "")
+        return null;
+    if (!url.pathname.endsWith("/"))
+        url.pathname += "/";
+    return url.href;
+};
+/** Caller-declared translation from an authorized runtime location to a layer. */
+const runtimeLocationMappingSchema = z.discriminatedUnion("kind", [
+    runtimeFileMappingSchema,
+    runtimeUrlMappingSchema,
+]);
+const staticLayerSchema = z.strictObject({
+    role: z.enum(["application", "cache", "assets"]),
+    analysis: evidenceSchema,
+    runtime_mappings: z
+        .array(runtimeLocationMappingSchema)
+        .max(32)
+        .overwrite(normalizeRuntimeMappings)
+        .default([]),
+});
+function normalizeRuntimeMappings(mappings) {
+    return [
+        ...new Map(mappings.map((mapping) => [runtimeMappingKey(mapping), mapping])).values(),
+    ].sort((left, right) => compareCodePoints(runtimeMappingKey(left), runtimeMappingKey(right)));
+}
+function runtimeMappingKey(mapping) {
+    return mapping.kind === "file-root"
+        ? `file-root\0${mapping.root}\0${mapping.artifact_prefix}`
+        : `url-prefix\0${mapping.prefix}\0${mapping.artifact_prefix}`;
+}
+const reconciliationLimitsSchema = z.strictObject({
+    max_runtime_entities: z.number().int().min(1).max(50_000).default(10_000),
+    max_reconciliation_items: z.number().int().min(1).max(50_000).default(20_000),
+    max_static_load_states: z.number().int().min(1).max(50_000).default(20_000),
+});
+/** Evidence-backed static layers and passive captures to reconcile. */
+export const reconcileJavaScriptRuntimeInputSchema = z
+    .strictObject({
+    static_layers: z.array(staticLayerSchema).min(1).max(8),
+    runtime_observations: z.array(evidenceSchema).min(1).max(32),
+    limits: reconciliationLimitsSchema.default({
+        max_runtime_entities: 10_000,
+        max_reconciliation_items: 20_000,
+        max_static_load_states: 20_000,
+    }),
+})
+    .superRefine((input, context) => {
+    if (input.static_layers.filter(({ role }) => role === "application")
+        .length !== 1)
+        context.addIssue({
+            code: "custom",
+            path: ["static_layers"],
+            message: "Exactly one application static layer is required",
+        });
+    const staticIds = input.static_layers.map(({ analysis }) => analysis.evidence_id);
+    if (new Set(staticIds).size !== staticIds.length)
+        context.addIssue({
+            code: "custom",
+            path: ["static_layers"],
+            message: "Static layer Evidence must be unique",
+        });
+    const runtimeIds = input.runtime_observations.map(({ evidence_id: id }) => id);
+    if (new Set(runtimeIds).size !== runtimeIds.length)
+        context.addIssue({
+            code: "custom",
+            path: ["runtime_observations"],
+            message: "Runtime observation Evidence must be unique",
+        });
+    if (input.limits.max_runtime_entities < input.runtime_observations.length)
+        context.addIssue({
+            code: "custom",
+            path: ["limits", "max_runtime_entities"],
+            message: "Runtime entity limit must retain one target per observation",
+        });
+});
+const layerSummarySchema = z.strictObject({
+    layer_id: z.string().regex(/^jrl_[a-f0-9]{64}$/u),
+    role: z.enum(["application", "cache", "assets"]),
+    evidence_id: evidenceIdSchema,
+    graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+    root_artifact_sha256: digestSchema,
+    input_path: z.string().min(1).max(16_384),
+    format: z.enum(["asar", "directory"]),
+    runtime_mappings: z.array(runtimeLocationMappingSchema).max(32),
+});
+const captureSummarySchema = z.strictObject({
+    evidence_id: evidenceIdSchema,
+    capture_sha256: digestSchema,
+    kind: z.enum(["browser", "electron"]),
+    target_node_id: nodeIdSchema,
+    target_key: boundedTextSchema,
+    target_location: boundedTextSchema,
+    frames: z.number().int().min(0),
+    scripts: z.number().int().min(0),
+    workers: z.number().int().min(0),
+    scripts_complete_within_scope: z.boolean(),
+});
+const reconciliationReasonSchema = z.enum([
+    "content-and-location-match",
+    "unique-content-match",
+    "unique-location-match",
+    "ambiguous-static-candidates",
+    "captured-content-disagrees-with-static-location",
+    "no-static-content-match",
+    "no-authorized-location-mapping",
+    "runtime-frame-unattributed",
+    "static-or-runtime-coverage-incomplete",
+    "reconciliation-limit-reached",
+]);
+const reconciliationItemSchema = z.strictObject({
+    reconciliation_id: z.string().regex(/^jrr_item_[a-f0-9]{64}$/u),
+    entity_kind: z.enum(["target", "frame", "script", "worker"]),
+    runtime_evidence_id: evidenceIdSchema,
+    runtime_node_id: nodeIdSchema,
+    static_layer_id: z
+        .string()
+        .regex(/^jrl_[a-f0-9]{64}$/u)
+        .nullable(),
+    static_node_id: nodeIdSchema.nullable(),
+    status: z.enum(["matched", "ambiguous", "unmatched", "unknown"]),
+    basis: z.enum([
+        "content-and-location",
+        "content-sha256",
+        "module-source-sha256",
+        "artifact-path",
+        "operator-file-mapping",
+        "operator-url-mapping",
+        "none",
+    ]),
+    confidence: z.enum(["exact", "high", "medium", "low", "unknown"]),
+    reason: reconciliationReasonSchema,
+    candidate_static_count: z.number().int().min(0).max(800_000),
+    candidate_static_nodes: z
+        .array(z.strictObject({
+        static_layer_id: z.string().regex(/^jrl_[a-f0-9]{64}$/u),
+        static_node_id: nodeIdSchema,
+    }))
+        .max(1_000),
+});
+const staticLoadStateSchema = z.strictObject({
+    static_layer_id: z.string().regex(/^jrl_[a-f0-9]{64}$/u),
+    static_node_id: nodeIdSchema,
+    kind: z.enum(["javascript-asset", "javascript-chunk", "javascript-module"]),
+    status: z.enum([
+        "loaded",
+        "resident-in-loaded-asset",
+        "not-observed-in-capture",
+        "unknown",
+    ]),
+    runtime_node_ids: z.array(nodeIdSchema).max(10_000),
+    reason: z.enum([
+        "runtime-script-correspondence",
+        "containing-asset-was-loaded",
+        "not-observed-in-bounded-capture",
+        "layer-outside-runtime-scope",
+        "static-or-runtime-coverage-incomplete",
+    ]),
+});
+/** Deterministic static/passive-runtime reconciliation with a combined JAG. */
+export const javascriptRuntimeReconciliationResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    reconciliation_id: z.string().regex(/^jrr_[a-f0-9]{64}$/u),
+    static_layers: z.array(layerSummarySchema).min(1).max(8),
+    runtime_captures: z.array(captureSummarySchema).min(1).max(32),
+    graph: javascriptApplicationGraphSchema,
+    summary: z.strictObject({
+        runtime_targets: z.number().int().min(0),
+        runtime_frames: z.number().int().min(0),
+        runtime_scripts: z.number().int().min(0),
+        runtime_workers: z.number().int().min(0),
+        matched: z.number().int().min(0),
+        ambiguous: z.number().int().min(0),
+        unmatched: z.number().int().min(0),
+        unknown: z.number().int().min(0),
+        static_loaded: z.number().int().min(0),
+        static_resident: z.number().int().min(0),
+        static_not_observed: z.number().int().min(0),
+        static_unknown: z.number().int().min(0),
+    }),
+    reconciliations: z.array(reconciliationItemSchema).max(50_000),
+    static_load_states: z.array(staticLoadStateSchema).max(50_000),
+    source_map_authority: z.strictObject({
+        used_for_primary_matching: z.literal(false),
+        static_layers_with_read_approval: z.number().int().min(0),
+        runtime_script_declarations: z.number().int().min(0),
+        limitation: boundedTextSchema,
+    }),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inputs", "partial", "truncated"]),
+        truncated: z.boolean(),
+        omitted_runtime_entities: z.number().int().min(0),
+        omitted_reconciliation_items: z.number().int().min(0),
+        omitted_static_load_states: z.number().int().min(0),
+        omitted_graph_items: z.number().int().min(0),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(2).max(40),
+    limitations: z.array(boundedTextSchema).max(1_000),
+});