rea-agents 6.4.0 → 6.7.0

package/dist/domain/captures/packetFields.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { packetCaptureSchema } from "./packetCapture.js";
+export const inspectPacketFieldsInputSchema = z.strictObject({
+    kind: z
+        .enum(["protocols", "fields"])
+        .default("protocols")
+        .describe("Return protocol registrations or field definitions; defaults to protocols"),
+    protocol: z
+        .string()
+        .min(1)
+        .max(8192)
+        .nullable()
+        .default(null)
+        .describe("Exact protocol abbreviation; selects that protocol or its registered fields"),
+    query: z
+        .string()
+        .max(8192)
+        .default("")
+        .describe("Case-insensitive literal substring in name, abbreviation or field description"),
+    offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(0)
+        .describe("Number of matching records to skip; defaults to 0"),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(Number.MAX_SAFE_INTEGER)
+        .nullable()
+        .default(50)
+        .describe("Maximum matches returned; null requests all remaining within the record budget"),
+});
+export const packetFieldRecordSchema = z.strictObject({
+    source_line: z.number().int().positive(),
+    kind: z.enum(["protocol", "field"]),
+    name: z.string(),
+    abbreviation: z.string(),
+    field_type: z.string().nullable(),
+    parent_protocol: z.string().nullable(),
+    display_base: z.string().nullable(),
+    bitmask: z.string().nullable(),
+    description: z.string().nullable(),
+});
+export const packetFieldsCatalogSchema = z
+    .strictObject({
+    selection: inspectPacketFieldsInputSchema,
+    records: z.array(packetFieldRecordSchema),
+    output_window: z.strictObject({
+        examined: z.number().int().nonnegative(),
+        matching: z.number().int().nonnegative(),
+        returned: z.number().int().nonnegative(),
+        has_more: z.boolean(),
+    }),
+    diagnostics: z.string(),
+    tool: packetCaptureSchema.shape.tool,
+    resource_limiter: packetCaptureSchema.shape.resource_limiter,
+    limits: packetCaptureSchema.shape.limits.extend({
+        record_budget_bytes: z.literal(8388608),
+    }),
+    configuration: z.literal("private-empty-personal-profile"),
+    hardware_acquisition: z.literal("not-performed"),
+})
+    .superRefine((report, context) => {
+    const w = report.output_window;
+    const remaining = Math.max(0, w.matching - report.selection.offset);
+    const expected = Math.min(remaining, report.selection.limit ?? remaining);
+    if (w.matching > w.examined ||
+        w.returned !== expected ||
+        report.records.length !== expected ||
+        w.has_more !== remaining > expected ||
+        report.records.some((row) => row.kind !==
+            (report.selection.kind === "protocols" ? "protocol" : "field")))
+        context.addIssue({
+            code: "custom",
+            path: ["output_window"],
+            message: "Field discovery coverage must match the selected page and record kind",
+        });
+});

package/dist/domain/changedBehavior.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { uniqueSorted } from "./canonicalOrdering.js";
 import { compositeKey, compareUnicodeCodePoints, } from "./unicodeCodePointOrder.js";
-import { comparisonSourceEvidenceIds } from "./comparisonSourceEvidence.js";
+import { assertComparisonFindingLinks, comparisonSourceEvidenceIds, } from "./comparisonSourceEvidence.js";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
 import { functionComparisonResultSchema } from "./functionComparisonSchemas.js";
 import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./process/processEvidenceProvider.js";
@@ -85,18 +85,24 @@ const EXPECTED_PROVIDERS = {
     },
 };
 const acceptsPredicate = (expected, actual) => expected.some((predicate) => predicate === actual);
-/** Find observed runtime changes and separately report static change candidates. */
-export const findChangedBehavior = (comparisonsInput) => {
-    const parsedInput = changedBehaviorInputSchema.parse({
-        comparisons: comparisonsInput,
-    });
-    const comparisons = parsedInput.comparisons;
+export const findChangedBehavior = (input) => {
+    // The public input schema remains available to clients; this internal
+    // admission only checks the list shape because parseEvidence below owns
+    // validation and authentication of each retained Evidence item.
+    const { comparisons } = z
+        .strictObject({ comparisons: z.array(z.unknown()).min(1) })
+        .parse(input);
     const evidence = comparisons.map(parseComparisonEvidence);
-    assertUnique(evidence.map(({ evidence_id: id }) => id), "comparison Evidence");
+    assertUnique(evidence.map(({ evidence: { evidence_id: id } }) => id), "comparison Evidence");
     const findings = evidence.flatMap(findingsFor).sort(compareFindings);
-    const runtimeStatuses = evidence.flatMap(runtimeStatus);
-    const links = uniqueSorted(evidence.flatMap((item) => [item.evidence_id, ...item.evidence_links]));
-    return changedBehaviorResultSchema.parse({
+    const runtimeStatuses = evidence.flatMap((comparison) => comparison.operation === "compare_process_captures"
+        ? [comparison.result.status]
+        : []);
+    const links = uniqueSorted(evidence.flatMap(({ evidence: item }) => [
+        item.evidence_id,
+        ...item.evidence_links,
+    ]));
+    const result = changedBehaviorResultSchema.parse({
         behavior_status: behaviorStatus(runtimeStatuses),
         summary: {
             observed_changes: count(findings, "observed_change"),
@@ -109,7 +115,7 @@ export const findChangedBehavior = (comparisonsInput) => {
         },
         evidence_links: links,
         limitations: uniqueSorted([
-            ...evidence.flatMap(({ limitations }) => limitations),
+            ...evidence.flatMap(({ evidence: item }) => item.limitations),
             ...(evidence.some(({ operation }) => operation !== "compare_process_captures")
                 ? [
                     "Static differences are behavior candidates, not runtime observations.",
@@ -120,6 +126,10 @@ export const findChangedBehavior = (comparisonsInput) => {
                 : []),
         ]),
     });
+    return {
+        result,
+        comparisonEvidenceIds: evidence.map(({ evidence: { evidence_id } }) => evidence_id),
+    };
 };
 const parseComparisonEvidence = (input) => {
     const evidence = parseEvidence(input);
@@ -145,39 +155,34 @@ const parseComparisonEvidence = (input) => {
         throw new TypeError("Comparison Evidence operation, predicate, and provider disagree");
     if (!comparisonSourceEvidenceIds(evidence).every((id) => evidence.evidence_links.includes(id)))
         throw new TypeError("Comparison Evidence must cite both selected source observations");
-    parseResult(evidence);
-    return evidence;
+    return parseResult(evidence, operation);
 };
-const parseResult = (evidence) => {
-    if (evidence.operation === "compare_process_captures") {
+const parseResult = (evidence, operation) => {
+    if (operation === "compare_process_captures") {
         const result = processCaptureComparisonSchema.parse(evidence.normalized_result);
         const expected = deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => result[dimension]));
         if (result.status !== expected)
             throw new TypeError("Process comparison status contradicts its dimensions");
-        return;
+        return { operation, evidence, result };
     }
-    if (evidence.operation === "compare_functions") {
+    if (operation === "compare_functions") {
         const result = functionComparisonResultSchema.parse(evidence.normalized_result);
-        assertNestedLinks(evidence, result.dimensions.flatMap(({ evidence_links: links }) => links));
-        return;
+        assertComparisonFindingLinks(evidence, result.dimensions.flatMap(({ evidence_links: links }) => links));
+        return { operation, evidence, result };
     }
     const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
-    assertNestedLinks(evidence, result.changes.flatMap(({ evidence_links: links }) => links));
-};
-const assertNestedLinks = (evidence, nestedLinks) => {
-    const topLevel = new Set(evidence.evidence_links);
-    if (nestedLinks.some((evidenceId) => !topLevel.has(evidenceId)))
-        throw new TypeError("Comparison finding cites Evidence outside its top-level closure");
+    assertComparisonFindingLinks(evidence, result.changes.flatMap(({ evidence_links: links }) => links));
+    return { operation, evidence, result };
 };
-const findingsFor = (evidence) => {
-    if (evidence.operation === "compare_process_captures")
-        return processFindings(evidence);
-    if (evidence.operation === "compare_functions")
-        return functionFindings(evidence);
-    return artifactFindings(evidence);
+const findingsFor = (comparison) => {
+    if (comparison.operation === "compare_process_captures")
+        return processFindings(comparison);
+    if (comparison.operation === "compare_functions")
+        return functionFindings(comparison);
+    return artifactFindings(comparison);
 };
-const processFindings = (evidence) => {
-    const result = processCaptureComparisonSchema.parse(evidence.normalized_result);
+const processFindings = (comparison) => {
+    const { evidence, result } = comparison;
     const dimensions = [
         ["terminal", result.terminal, "runtime"],
         ["interaction", result.interaction, "runtime"],
@@ -200,8 +205,8 @@ const processFindings = (evidence) => {
             }),
         ]);
 };
-const functionFindings = (evidence) => {
-    const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+const functionFindings = (comparison) => {
+    const { evidence, result } = comparison;
     return result.dimensions.flatMap((dimension) => dimension.status === "unchanged"
         ? []
         : [
@@ -218,8 +223,8 @@ const functionFindings = (evidence) => {
             }),
         ]);
 };
-const artifactFindings = (evidence) => {
-    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+const artifactFindings = (comparison) => {
+    const { evidence, result } = comparison;
     const changes = result.changes.map((change) => makeFinding({
         evidence,
         dimension: `artifact:${change.logical_path}`,
@@ -260,9 +265,6 @@ const makeFinding = (input) => findingSchema.parse({
     ]),
     limitations: uniqueSorted(input.limitations),
 });
-const runtimeStatus = (evidence) => evidence.operation === "compare_process_captures"
-    ? [processCaptureComparisonSchema.parse(evidence.normalized_result).status]
-    : [];
 const behaviorStatus = (statuses) => {
     if (statuses.length === 0)
         return "unknown";

package/dist/domain/comparisonSourceEvidence.js

@@ -38,3 +38,9 @@ export const comparisonSourceEvidenceIds = (evidence) => {
     const sides = comparisonSourceEvidenceSides(evidence);
     return uniqueSorted([...sides.left, ...sides.right]);
 };
+/** Preserve the source closure when consuming nested comparison findings. */
+export const assertComparisonFindingLinks = (evidence, nestedLinks) => {
+    const closure = new Set(evidence.evidence_links);
+    if (nestedLinks.some((id) => !closure.has(id)))
+        throw new TypeError("Comparison finding cites Evidence outside its top-level closure");
+};

package/dist/domain/dosCom.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { err, ok } from "./result.js";
-/** Headerless DOS COM interpretation explicitly selected by the caller. */
-export const executableFormatHintSchema = z.literal("dos-com");
+/** Headerless executable interpretation explicitly selected by the caller. */
+export const executableFormatHintSchema = z.enum(["dos-com", "raw-binary"]);
 /** Validate the single 64 KiB COM segment, excluding its 256-byte PSP prefix. */
 export const validateDosComLength = (length) => Number.isSafeInteger(length) && length >= 1 && length <= 0xff00
     ? ok(null)

package/dist/domain/dosMz.js

@@ -1,44 +1,89 @@
 import { err, ok } from "./result.js";
+/** The unsigned 16-bit page count bounds the initialized image, not overlays. */
+export const dosMzImageByteLength = (bytes) => {
+    if (bytes.length < 28 || bytes.toString("latin1", 0, 2) !== "MZ")
+        return err("invalid or truncated DOS MZ header");
+    const lastPageBytes = bytes.readUInt16LE(2);
+    const pages = bytes.readUInt16LE(4);
+    if (pages === 0 || lastPageBytes > 511)
+        return err("invalid DOS MZ page count or final-page size");
+    return ok((pages - 1) * 512 + (lastPageBytes === 0 ? 512 : lastPageBytes));
+};
 /**
- * Locate a Windows new-header declaration without interpreting a short DOS
- * header's load-module or relocation-table bytes at 0x3c as e_lfanew. A
- * new-header pointer must lie in a sufficiently large header and outside
- * actual relocation records. Zero-sized legacy stubs remain eligible for
- * PE signature validation.
+ * Observe the Windows new-header pointer without mistaking short DOS module
+ * bytes for e_lfanew. Complete DOS headers declare their pointer; for shorter
+ * headers, only a PE/NE/LE/LX signature at that pointer confirms the candidate.
+ * A bounded prefix that does not reach the candidate requests one bounded read
+ * from its owner instead of treating unexamined bytes as absent.
  */
-export const mzWindowsHeaderOffset = (bytes) => {
+export const observeMzWindowsHeader = (bytes, fileSize = bytes.length, signatureAtOffset) => {
     if (bytes.length < 64)
-        return null;
+        return fileSize >= 64 ? { state: "header-needed" } : { state: "absent" };
     const headerBytes = bytes.readUInt16LE(8) * 16;
-    if (headerBytes !== 0 && headerBytes < 64)
-        return null;
     const relocationCount = bytes.readUInt16LE(6);
     const tableStart = bytes.readUInt16LE(24);
     if (headerBytes !== 0 &&
         relocationCount > 0 &&
         tableStart < 64 &&
         tableStart + relocationCount * 4 > 60)
-        return null;
+        return { state: "absent" };
     const offset = bytes.readUInt32LE(60);
-    return offset === 0 ? null : offset;
+    if (offset === 0)
+        return { state: "absent" };
+    const inlineSignature = offset < bytes.length
+        ? bytes.subarray(offset, Math.min(offset + 4, bytes.length))
+        : undefined;
+    const available = signatureAtOffset ?? inlineSignature;
+    const signature = windowsHeaderSignature(available);
+    if (headerBytes === 0 || headerBytes >= 64)
+        return { state: "declared", offset, signature };
+    if (signature !== "other" && signature !== "unobserved")
+        return { state: "declared", offset, signature };
+    if (signature === "other")
+        return { state: "absent" };
+    const observedPePrefix = available !== undefined &&
+        available.length >= 2 &&
+        available.toString("latin1", 0, 2) === "PE";
+    if (fileSize - offset < (observedPePrefix ? 4 : 2))
+        return { state: "absent" };
+    return { state: "signature-needed", offset };
+};
+const windowsHeaderSignature = (bytes) => {
+    if (bytes === undefined || bytes.length < 2)
+        return "unobserved";
+    const first = bytes[0];
+    const second = bytes[1];
+    if (first === 0x4e && second === 0x45)
+        return "NE";
+    if (first === 0x4c && second === 0x45)
+        return "LE";
+    if (first === 0x4c && second === 0x58)
+        return "LX";
+    if (first !== 0x50 || second !== 0x45)
+        return "other";
+    if (bytes.length < 4)
+        return "unobserved";
+    return bytes[2] === 0 && bytes[3] === 0 ? "PE" : "other";
 };
 /**
  * Validate a DOS MZ load module using a bounded header/table and the actual
  * file length. Appended overlay bytes are retained separately; they are not
  * silently included in the initialized load module.
  */
-export const parseDosMzHeader = (bytes, fileSize = bytes.length) => {
-    if (bytes.length < 28 || bytes.toString("ascii", 0, 2) !== "MZ")
+export const parseDosMzHeader = (bytes, fileSize = bytes.length, signatureAtOffset) => {
+    if (bytes.length < 28 || bytes.toString("latin1", 0, 2) !== "MZ")
         return err("invalid or truncated DOS MZ header");
     if (!Number.isSafeInteger(fileSize) || fileSize < bytes.length)
         return err("invalid DOS MZ file length");
-    if (mzWindowsHeaderOffset(bytes) !== null)
+    const windowsHeader = observeMzWindowsHeader(bytes, fileSize, signatureAtOffset);
+    if (windowsHeader.state === "declared")
         return err("MZ declares a Windows new header; it is not a DOS-only image");
-    const lastPageBytes = bytes.readUInt16LE(2);
-    const pages = bytes.readUInt16LE(4);
-    if (pages === 0 || lastPageBytes > 511)
-        return err("invalid DOS MZ page count or final-page size");
-    const imageBytes = (pages - 1) * 512 + (lastPageBytes === 0 ? 512 : lastPageBytes);
+    if (windowsHeader.state === "signature-needed")
+        return err("MZ Windows new-header signature is outside the bounded prefix");
+    const extent = dosMzImageByteLength(bytes);
+    if (!extent.ok)
+        return extent;
+    const imageBytes = extent.value;
     const headerBytes = bytes.readUInt16LE(8) * 16;
     if (headerBytes < 28 || headerBytes >= imageBytes)
         return err("invalid DOS MZ header size or empty load module");
@@ -52,6 +97,8 @@ export const parseDosMzHeader = (bytes, fileSize = bytes.length) => {
         return err("DOS MZ relocation table lies outside its header");
     if (relocationCount > 0 && tableEnd > bytes.length)
         return err("truncated DOS MZ relocation table");
+    if (windowsHeader.state === "header-needed")
+        return err("MZ Windows new-header pointer is outside the bounded prefix");
     const moduleBytes = imageBytes - headerBytes;
     const relocations = validateRelocations(bytes, relocationTableOffset, relocationCount, moduleBytes);
     if (!relocations.ok)

package/dist/domain/electron/electronFuseEvidence.js

@@ -0,0 +1,42 @@
+import { BINARY_ARCHITECTURES } from "../binaryTargetTypes.js";
+import { createEvidence } from "../evidence.js";
+/** Preserve the same validated fuse facts on success and incomplete finalization. */
+export const createElectronFuseEvidence = (input, value, provider) => {
+    const architecture = subjectArchitecture(value);
+    return createEvidence({
+        path: value.artifact.resolved_path,
+        sha256: value.artifact.sha256,
+        format: value.artifact.format,
+        ...(architecture === undefined ? {} : { architecture }),
+    }, provider, {
+        operation: "inspect_electron_fuses",
+        parameters: input,
+        result: value,
+        confidence: "observed",
+        limitations: value.limitations,
+        locations: locationsFor(value),
+    });
+};
+const subjectArchitecture = (report) => {
+    if (report.artifact.format === "mach-o-universal")
+        return undefined;
+    if (report.slices.length !== 1)
+        return undefined;
+    const name = report.slices[0]?.architecture;
+    return BINARY_ARCHITECTURES.find((supported) => supported === name);
+};
+const locationsFor = (report) => [
+    { kind: "artifact-path", path: report.artifact.selected_path },
+    ...(report.artifact.resolved_path === report.artifact.selected_path
+        ? []
+        : [
+            {
+                kind: "artifact-path",
+                path: report.artifact.resolved_path,
+            },
+        ]),
+    ...report.slices.flatMap((slice) => slice.sentinels.map((sentinel) => ({
+        kind: "file-offset",
+        offset: sentinel.sentinel_offset,
+    }))),
+];