rea-agents 6.0.0 → 6.2.0

package/dist/domain/analysisSnapshot.js

@@ -96,7 +96,7 @@ export const analysisSnapshotSchema = z.object({
     target: targetSchema,
     binding: bindingSchema,
     entries: z.array(entrySchema),
-    workflow_entries: z.array(workflowEntrySchema).optional(),
+    workflow_entries: z.array(workflowEntrySchema),
     evidence_bundle: evidenceBundleSchema,
 });
 const canonicalJson = (value) => {
@@ -139,7 +139,7 @@ export const snapshotEvidenceForQuery = (snapshot, query) => {
     const encodedParameters = canonicalJson(parameters);
     const queryId = analysisQueryId(snapshot.target, snapshot.binding, operation, parameters);
     const entry = snapshot.entries.find((candidate) => candidate.query_id === queryId);
-    const workflowEntry = snapshot.workflow_entries?.find((candidate) => candidate.query_id === queryId);
+    const workflowEntry = snapshot.workflow_entries.find((candidate) => candidate.query_id === queryId);
     if (entry === undefined && workflowEntry === undefined)
         return undefined;
     return snapshot.evidence_bundle.records.find((record) => record.subject?.digest.sha256 === target.sha256 &&
@@ -147,7 +147,7 @@ export const snapshotEvidenceForQuery = (snapshot, query) => {
         record.provider.id === provider.id &&
         record.provider.name === provider.name &&
         record.provider.version === provider.version &&
-        "analysis_profile" in record &&
+        record.analysis_profile !== null &&
         analysisProfilesEqual(record.analysis_profile, evidenceProfile) &&
         canonicalJson(record.parameters) === encodedParameters &&
         ((entry !== undefined && evidenceMatchesEntry(record, entry, snapshot)) ||
@@ -233,11 +233,17 @@ export const createAnalysisSnapshotEntry = (input) => {
 export const parseAnalysisSnapshot = (input) => {
     const parsed = analysisSnapshotSchema.parse(input);
     parseEvidenceBundle(parsed.evidence_bundle);
-    if (JSON.stringify(evidenceBundleForTarget(parsed.evidence_bundle, parsed.target.sha256)) !== JSON.stringify(parsed.evidence_bundle))
+    const scopedEvidence = evidenceBundleForTarget(parsed.evidence_bundle, parsed.target.sha256);
+    // The validated canonical bundle is filtered, never extended. Equal counts
+    // establish that no record or unknown was removed without serializing results.
+    if (scopedEvidence.records.length !== parsed.evidence_bundle.records.length ||
+        scopedEvidence.unknowns.length !== parsed.evidence_bundle.unknowns.length)
         throw new TypeError("Analysis snapshot evidence contains records for another target");
+    if (!hasCanonicalQueryOrder(parsed.entries))
+        throw new TypeError("Analysis snapshot entries are not canonical");
+    if (!hasCanonicalQueryOrder(parsed.workflow_entries))
+        throw new TypeError("Analysis snapshot workflow entries are not canonical");
     const ids = new Set();
-    const boundEntries = [];
-    const boundWorkflowEntries = [];
     const index = createEvidenceIndex(parsed);
     const workflowIndex = createWorkflowEvidenceIndex(parsed);
     for (const entry of parsed.entries) {
@@ -254,13 +260,10 @@ export const parseAnalysisSnapshot = (input) => {
         if (!entryHasMatchingEvidence(entry, parsed, index)) {
             if (entryHasCorrespondingEvidence(entry, parsed, index))
                 throw new TypeError(`Analysis snapshot entry ${entry.operation} differs from its Evidence record`);
-            // Older snapshots may contain cache entries without profile-bound Evidence.
-            // Keep their Evidence bundle, but never replay those unbound values.
-            continue;
+            throw new TypeError(`Analysis snapshot entry ${entry.operation} has no profile-bound Evidence record`);
         }
-        boundEntries.push(entry);
     }
-    for (const entry of parsed.workflow_entries ?? []) {
+    for (const entry of parsed.workflow_entries) {
         if (entry.execution.provider.id !==
             entry.execution.analysis_profile.provider.id ||
             entry.execution.provider.name !==
@@ -277,24 +280,19 @@ export const parseAnalysisSnapshot = (input) => {
         if (!workflowEntryHasMatchingEvidence(entry, workflowIndex)) {
             if (workflowEntryHasCorrespondingEvidence(entry, workflowIndex))
                 throw new TypeError(`Analysis snapshot workflow entry ${entry.operation} differs from its Evidence record`);
-            continue;
+            throw new TypeError(`Analysis snapshot workflow entry ${entry.operation} has no profile-bound Evidence record`);
         }
-        boundWorkflowEntries.push(entry);
     }
-    const sorted = [...parsed.entries].sort((left, right) => left.query_id.localeCompare(right.query_id));
-    if (JSON.stringify(parsed.entries) !== JSON.stringify(sorted))
-        throw new TypeError("Analysis snapshot entries are not canonical");
-    const sortedWorkflows = [...(parsed.workflow_entries ?? [])].sort((left, right) => left.query_id.localeCompare(right.query_id));
-    if (parsed.workflow_entries !== undefined &&
-        JSON.stringify(parsed.workflow_entries) !== JSON.stringify(sortedWorkflows))
-        throw new TypeError("Analysis snapshot workflow entries are not canonical");
-    return {
-        ...parsed,
-        entries: boundEntries,
-        ...(parsed.workflow_entries === undefined
-            ? {}
-            : { workflow_entries: boundWorkflowEntries }),
-    };
+    return parsed;
+};
+const hasCanonicalQueryOrder = (entries) => {
+    let previous;
+    for (const { query_id: queryId } of entries) {
+        if (previous !== undefined && previous.localeCompare(queryId) > 0)
+            return false;
+        previous = queryId;
+    }
+    return true;
 };
 const createEvidenceIndex = (snapshot) => {
     const matching = new Set();
@@ -329,13 +327,13 @@ const isCorrespondingEvidence = (evidence, snapshot) => evidence.predicate_type
     evidence.confidence === "observed" &&
     evidence.authority === "shipped-artifact" &&
     evidence.subject?.digest.sha256 === snapshot.target.sha256 &&
-    "analysis_profile" in evidence &&
+    evidence.analysis_profile !== null &&
     analysisProfilesEqual(evidence.analysis_profile, snapshot.binding.analysis_profile);
 const evidenceQueryKey = (evidence) => canonicalJson({
     operation: evidence.operation,
     parameters: evidence.parameters,
     provider: evidence.provider,
-    analysis_profile: "analysis_profile" in evidence ? evidence.analysis_profile : null,
+    analysis_profile: evidence.analysis_profile,
 });
 const entryQueryKey = (entry, binding) => canonicalJson({
     operation: entry.operation,
@@ -383,7 +381,7 @@ const isWorkflowEvidence = (evidence, snapshot, entry) => evidence.predicate_typ
     evidence.confidence === "derived" &&
     evidence.authority === "shipped-artifact" &&
     evidence.subject?.digest.sha256 === snapshot.target.sha256 &&
-    "analysis_profile" in evidence &&
+    evidence.analysis_profile !== null &&
     analysisProfilesEqual(evidence.analysis_profile, entry.execution.analysis_profile) &&
     evidence.provider.id === entry.execution.provider.id &&
     evidence.provider.name === entry.execution.provider.name &&
@@ -396,7 +394,7 @@ const createWorkflowEvidenceIndex = (snapshot) => {
             evidence.confidence !== "derived" ||
             evidence.authority !== "shipped-artifact" ||
             evidence.subject?.digest.sha256 !== snapshot.target.sha256 ||
-            !("analysis_profile" in evidence))
+            evidence.analysis_profile === null)
             continue;
         corresponding.add(evidenceQueryKey(evidence));
         matching.add(canonicalJson(evidenceContentProjection(evidence)));

package/dist/domain/analysisView/analysisView.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisUnsupportedTargetError, } from "../analysisErrorCore.js";
+import { digestCanonicalValue } from "../canonicalDigest.js";
+import { digestSchema, prefixedDigestSchema } from "../digests.js";
+import { evidenceSchema } from "../evidence.js";
+import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js";
+import { err, ok } from "../result.js";
+import { binaryLayoutSchema } from "../native/binaryLayout.js";
+import { parseOwnedJavaScriptApplicationAnalysisSteps, } from "../javascript/javascriptApplicationAnalysis.js";
+import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
+import { projectBinaryLayoutView } from "./binaryLayoutView.js";
+import { projectJavaScriptApplicationView } from "./javascriptApplicationView.js";
+/** Public name of the selected-view workflow. */
+export const INSPECT_ANALYSIS_VIEW_OPERATION = "inspect_analysis_view";
+const summaryViewSchema = z.strictObject({ kind: z.literal("summary") });
+const facetViewSchema = z.strictObject({
+    kind: z.literal("facet"),
+    facet: z.enum(["mitigations", "linkage"]),
+});
+const itemSelectorSchema = z.union([
+    z.strictObject({ index: z.number().int().nonnegative() }),
+    z.strictObject({ name: z.string() }),
+    z.strictObject({
+        path: z
+            .string()
+            .describe("Exact observed module path or original source-map reference from a module page; an empty reference is valid."),
+    }),
+    z.strictObject({ node_id: prefixedDigestSchema("jag_node") }),
+]);
+const itemViewSchema = z
+    .strictObject({
+    kind: z.literal("item"),
+    collection: z.enum(["sections", "symbols", "modules"]),
+    selector: itemSelectorSchema,
+})
+    .superRefine((value, context) => {
+    const selector = value.selector;
+    if (value.collection === "modules") {
+        if (!("path" in selector) && !("node_id" in selector))
+            context.addIssue({
+                code: "custom",
+                path: ["selector"],
+                message: "Module items are selected by exact path or node_id, not index or name.",
+            });
+        return;
+    }
+    if (!("index" in selector) && !("name" in selector))
+        context.addIssue({
+            code: "custom",
+            path: ["selector"],
+            message: "Section and symbol items are selected by index or exact name, not path or node_id.",
+        });
+});
+const pageViewSchema = z.strictObject({
+    kind: z.literal("page"),
+    collection: z.enum(["sections", "symbols", "modules"]),
+    offset: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+});
+/** Caller-selected projection of already completed analysis Evidence. */
+export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
+    summaryViewSchema,
+    facetViewSchema,
+    itemViewSchema,
+    pageViewSchema,
+]);
+/** Inline Evidence or an exact same-session retained reference. */
+export const analysisViewSourceSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("retained-evidence"),
+        evidence_id: prefixedDigestSchema("ev"),
+    }),
+    z.strictObject({
+        kind: z.literal("inline"),
+        evidence: evidenceSchema,
+    }),
+]);
+/** Public inspect_analysis_view input. */
+export const inspectAnalysisViewInputSchema = z.strictObject({
+    source: analysisViewSourceSchema,
+    view: analysisViewRequestSchema,
+});
+const coverageSchema = z.strictObject({
+    status: z.enum(["complete-within-view", "page", "empty"]),
+    examined: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    next_offset: z.number().int().nonnegative().nullable(),
+    exhausted: z.boolean(),
+});
+const artifactSchema = z.strictObject({
+    path: z.string().min(1),
+    sha256: digestSchema,
+});
+const layoutSummarySchema = z.strictObject({
+    bytes: z.number().int().nonnegative(),
+    format: z.literal("elf"),
+    architecture: z.strictObject({
+        machine: z.literal("EM_X86_64"),
+        bits: z.literal(64),
+        byte_order: z.literal("little"),
+    }),
+    image_type: z.enum(["ET_EXEC", "ET_DYN", "ET_REL"]),
+    entry: z.strictObject({
+        reported_value: z.string().min(1),
+        meaning: z.enum(["linked-virtual-address", "not-applicable", "absent"]),
+        execution_status: z.literal("unknown"),
+    }),
+    counts: z.strictObject({
+        sections: z.number().int().nonnegative(),
+        segments: z.number().int().nonnegative(),
+        symbols: z.number().int().nonnegative(),
+        relocations: z.number().int().nonnegative(),
+    }),
+    limitation_count: z.number().int().nonnegative(),
+});
+const javascriptSummarySchema = z.strictObject({
+    input_path: z.string().min(1),
+    format: z.enum(["asar", "directory"]),
+    root_artifact_sha256: digestSchema,
+    statistics: jsonObjectSchema,
+    electron: jsonObjectSchema,
+    coverage: jsonObjectSchema,
+    limitation_count: z.number().int().nonnegative(),
+});
+const viewResultBase = {
+    parent_evidence_id: prefixedDigestSchema("ev"),
+    parent_operation: z.enum([
+        "inspect_binary_layout",
+        "analyze_javascript_application",
+    ]),
+    parent_digest: digestSchema,
+    view_digest: digestSchema,
+    artifact: artifactSchema,
+    coverage: coverageSchema,
+    limitations: z.array(z.string()),
+    unknowns: z.array(z.string()),
+};
+/** Projected facts for one selected view of retained analysis Evidence. */
+export const analysisViewResultSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("summary"),
+        view: summaryViewSchema,
+        summary: z.union([layoutSummarySchema, javascriptSummarySchema]),
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("facet"),
+        view: facetViewSchema,
+        facet: jsonValueSchema,
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("item"),
+        view: itemViewSchema,
+        item: jsonValueSchema,
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("page"),
+        view: pageViewSchema,
+        items: z.array(jsonValueSchema),
+        ...viewResultBase,
+    }),
+]);
+/** Construct a typed input failure for one selected-view constraint. */
+export const analysisViewInputError = (issues) => new AnalysisInputError(INSPECT_ANALYSIS_VIEW_OPERATION, undefined, issues);
+/** SHA-256 of the canonical projected JSON, excluding this digest field. */
+export const analysisViewDigest = (projection) => digestCanonicalValue(projection, "Analysis view");
+/** Attach the content digest that must change when projected bytes change. */
+export const sealAnalysisView = (projection) => analysisViewResultSchema.parse({
+    ...projection,
+    view_digest: analysisViewDigest(projection),
+});
+const parentDigest = (evidenceId) => evidenceId.slice(3);
+const parseJavaScriptParent = (input) => {
+    try {
+        // Only the existing realm-private graph proofs permit reuse. Imported or
+        // merely frozen graphs still receive full canonical validation.
+        const steps = parseOwnedJavaScriptApplicationAnalysisSteps(input);
+        let step = steps.next();
+        while (!step.done)
+            step = steps.next();
+        return ok(step.value);
+    }
+    catch (cause) {
+        if (!(cause instanceof z.ZodError))
+            throw cause;
+        return err(analysisInputErrorFromIssues(INSPECT_ANALYSIS_VIEW_OPERATION, cause.issues.map((issue) => ({
+            ...issue,
+            path: ["source", "normalized_result", ...issue.path],
+        })), { source: { normalized_result: input } }, { cause }));
+    }
+};
+const unsupportedParent = (parent) => new AnalysisUnsupportedTargetError(INSPECT_ANALYSIS_VIEW_OPERATION, parentArtifactPath(parent), `Parent Evidence operation ${JSON.stringify(parent.operation)} is not inspect_binary_layout or analyze_javascript_application.`);
+const parentArtifactPath = (parent) => {
+    if (typeof parent.normalizedResult === "object" &&
+        parent.normalizedResult !== null &&
+        "artifact" in parent.normalizedResult &&
+        typeof parent.normalizedResult.artifact === "object" &&
+        parent.normalizedResult.artifact !== null &&
+        "path" in parent.normalizedResult.artifact &&
+        typeof parent.normalizedResult.artifact.path === "string")
+        return parent.normalizedResult.artifact.path;
+    if (typeof parent.normalizedResult === "object" &&
+        parent.normalizedResult !== null &&
+        "input_path" in parent.normalizedResult &&
+        typeof parent.normalizedResult.input_path === "string")
+        return parent.normalizedResult.input_path;
+    return parent.evidenceId;
+};
+/** Project one selected view from authenticated parent analysis Evidence. */
+export const projectAnalysisView = (parent, view) => {
+    const digest = parentDigest(parent.evidenceId);
+    if (!digestSchema.safeParse(digest).success)
+        return err(analysisViewInputError([
+            {
+                path: ["source"],
+                reason: "invalid_format",
+                message: "Parent Evidence ID is not a digest-backed identifier.",
+            },
+        ]));
+    if (parent.operation === "inspect_binary_layout") {
+        const layout = binaryLayoutSchema.safeParse(parent.normalizedResult);
+        if (!layout.success)
+            return err(analysisViewInputError([
+                {
+                    path: ["source"],
+                    reason: "invalid_value",
+                    message: "Parent Evidence result does not match inspect_binary_layout.",
+                },
+            ]));
+        const projected = projectBinaryLayoutView(parent, layout.data, view);
+        return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+    }
+    if (parent.operation === "analyze_javascript_application") {
+        const analysis = parseJavaScriptParent(parent.normalizedResult);
+        if (!analysis.ok)
+            return analysis;
+        const projected = projectJavaScriptApplicationView(parent, analysis.value, view);
+        return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+    }
+    return err(unsupportedParent(parent));
+};

package/dist/domain/analysisView/analysisViewCoverage.js

@@ -0,0 +1,19 @@
+/** Coverage for a summary, facet, or single selected object. */
+export const completeWithinViewCoverage = (examined, total) => ({
+    status: "complete-within-view",
+    examined,
+    total,
+    next_offset: null,
+    exhausted: true,
+});
+/** Coverage for a stable page, including an offset past the collection. */
+export const pageViewCoverage = (offset, examined, total) => {
+    const exhausted = offset >= total || offset + examined >= total;
+    return {
+        status: examined === 0 ? "empty" : "page",
+        examined,
+        total,
+        next_offset: exhausted ? null : offset + examined,
+        exhausted,
+    };
+};

package/dist/domain/analysisView/binaryLayoutView.js

@@ -0,0 +1,159 @@
+import { AnalysisInputError, } from "../analysisErrorCore.js";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { err, ok } from "../result.js";
+import { completeWithinViewCoverage as completeCoverage, pageViewCoverage as pageCoverage, } from "./analysisViewCoverage.js";
+const OPERATION = "inspect_analysis_view";
+const inputError = (issues) => new AnalysisInputError(OPERATION, undefined, issues);
+const layoutUnknowns = (layout) => {
+    const unknowns = [
+        "runtime_load_base is unknown",
+        "entry_point.execution_status is unknown",
+        "relocation_inventory_completeness is unknown",
+        "linkage.convenience_maps_completeness is unknown",
+        "linkage.runtime_library_paths are unknown",
+    ];
+    if (layout.mitigations.nx_indicator === null)
+        unknowns.push("mitigations.nx_indicator is unknown");
+    if (layout.mitigations.relro === null)
+        unknowns.push("mitigations.relro is unknown");
+    return unknowns;
+};
+const displayName = (name) => name.display;
+const namedMatches = (rows, name) => rows.flatMap((row, index) => row.name.unknown_reason === null && displayName(row.name) === name
+    ? [{ index, row }]
+    : []);
+const selectNamed = (collection, rows, name) => {
+    const matches = namedMatches(rows, name);
+    if (matches.length === 1) {
+        const selected = matches[0];
+        if (selected !== undefined)
+            return ok(selected.row);
+    }
+    if (matches.length === 0)
+        return err(inputError([
+            {
+                path: ["view", "selector", "name"],
+                reason: "invalid_value",
+                message: `No ${collection} named ${JSON.stringify(name)}. Collection has ${String(rows.length)} entries; page it to inspect exact indexes and names.`,
+            },
+        ]));
+    return err(inputError([
+        {
+            path: ["view", "selector", "name"],
+            reason: "invalid_value",
+            message: `Multiple ${collection} named ${JSON.stringify(name)}; select one by index.`,
+            expected: matches.map(({ index }) => ({ index })),
+        },
+    ]));
+};
+const selectIndexed = (collection, rows, index) => {
+    const row = rows[index];
+    if (row !== undefined)
+        return ok(row);
+    return err(inputError([
+        {
+            path: ["view", "selector", "index"],
+            reason: "out_of_range",
+            message: `${collection} index ${String(index)} is outside 0..${String(Math.max(0, rows.length - 1))} (${String(rows.length)} entries).`,
+            minimum: 0,
+            maximum: Math.max(0, rows.length - 1),
+        },
+    ]));
+};
+const pageRows = (rows, offset, limit) => rows.slice(offset, offset + limit);
+const layoutIncompatible = (detail) => inputError([
+    {
+        path: ["view"],
+        reason: "invalid_value",
+        message: detail,
+    },
+]);
+const parentFields = (parent, layout) => ({
+    parent_evidence_id: parent.evidenceId,
+    parent_operation: "inspect_binary_layout",
+    parent_digest: parent.evidenceId.slice(3),
+    artifact: {
+        path: layout.artifact.path,
+        sha256: layout.artifact.sha256,
+    },
+    limitations: uniqueSorted([...parent.limitations, ...layout.limitations]),
+    unknowns: uniqueSorted([...layoutUnknowns(layout)]),
+});
+const layoutSummary = (layout) => ({
+    bytes: layout.artifact.bytes,
+    format: layout.format,
+    architecture: layout.architecture,
+    image_type: layout.image_type,
+    entry: layout.entry_point,
+    counts: {
+        sections: layout.sections.length,
+        segments: layout.segments.length,
+        symbols: layout.symbols.length,
+        relocations: layout.relocations.length,
+    },
+    limitation_count: layout.limitations.length,
+});
+/** Project one layout view without re-running the decoder. */
+export const projectBinaryLayoutView = (parent, layout, view) => {
+    const shared = parentFields(parent, layout);
+    if (view.kind === "summary")
+        return ok({
+            kind: "summary",
+            view,
+            summary: layoutSummary(layout),
+            coverage: completeCoverage(layout.sections.length +
+                layout.segments.length +
+                layout.symbols.length +
+                layout.relocations.length, layout.sections.length +
+                layout.segments.length +
+                layout.symbols.length +
+                layout.relocations.length),
+            ...shared,
+        });
+    if (view.kind === "facet")
+        return ok({
+            kind: "facet",
+            view,
+            facet: view.facet === "mitigations" ? layout.mitigations : layout.linkage,
+            coverage: completeCoverage(1, 1),
+            ...shared,
+        });
+    if (view.kind === "item") {
+        if (view.collection === "modules")
+            return err(layoutIncompatible("modules collection applies to analyze_javascript_application Evidence."));
+        const selected = view.collection === "sections"
+            ? selectLayoutItem(view.collection, layout.sections, view.selector)
+            : selectLayoutItem(view.collection, layout.symbols, view.selector);
+        if (!selected.ok)
+            return selected;
+        return ok({
+            kind: "item",
+            view,
+            item: selected.value,
+            coverage: completeCoverage(1, view.collection === "sections"
+                ? layout.sections.length
+                : layout.symbols.length),
+            ...shared,
+        });
+    }
+    if (view.collection === "modules")
+        return err(layoutIncompatible("modules collection applies to analyze_javascript_application Evidence."));
+    const rows = view.collection === "sections" ? layout.sections : layout.symbols;
+    const items = view.collection === "sections"
+        ? pageRows(layout.sections, view.offset, view.limit)
+        : pageRows(layout.symbols, view.offset, view.limit);
+    return ok({
+        kind: "page",
+        view,
+        items: [...items],
+        coverage: pageCoverage(view.offset, items.length, rows.length),
+        ...shared,
+    });
+};
+const selectLayoutItem = (collection, rows, selector) => {
+    if ("index" in selector)
+        return selectIndexed(collection, rows, selector.index);
+    if ("name" in selector)
+        return selectNamed(collection, rows, selector.name);
+    return err(layoutIncompatible("Section and symbol items are selected by index or exact name."));
+};