rea-agents 2.5.0 → 3.1.0

package/dist/domain/conformanceTrustGate.js

@@ -0,0 +1,328 @@
+import { z } from "zod";
+/** Result of comparing a single dimension. */
+export const dimensionResultSchema = z.strictObject({
+    name: z.string().min(1),
+    status: z.enum(["match", "mismatch", "unknown", "truncated"]),
+    message: z.string().default(""),
+    evidence_ids: z.array(z.string()).default([]),
+});
+/** Result of evaluating a trust gate for one scenario. */
+export const trustGateResultSchema = z.strictObject({
+    scenario_id: z.string().min(1),
+    verdict: z.enum(["pass", "fail", "unknown"]),
+    dimension_results: z.array(dimensionResultSchema),
+    first_divergence: z
+        .strictObject({
+        dimension: z.string().min(1),
+        evidence_id: z.string().min(1),
+        message: z.string(),
+    })
+        .nullable(),
+});
+/** Dimension that is volatile due to timing or normalization. */
+const VOLATILE_DIMENSIONS = new Set([
+    "timing",
+    "timestamp",
+    "pid",
+    "ppid",
+    "duration_ms",
+    "created_at",
+    "updated_at",
+]);
+/** Dimension that carries semantic content. */
+const SEMANTIC_DIMENSIONS = new Set([
+    "exit_code",
+    "stdout",
+    "stderr",
+    "filesystem",
+    "process",
+    "process_tree",
+    "shim_events",
+    "protocol_events",
+    "event_journal",
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const uniqueStrings = (values) => [
+    ...new Set(values.filter((value) => value.length > 0)),
+];
+const stringValues = (value) => {
+    if (typeof value === "string")
+        return value.length > 0 ? [value] : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.length > 0);
+};
+const evidenceIds = (record) => uniqueStrings([
+    ...stringValues(record["evidence_id"]),
+    ...stringValues(record["evidence_ids"]),
+    ...stringValues(record["evidence_links"]),
+]);
+const incompleteStatus = (value) => {
+    if (!isRecord(value))
+        return null;
+    const record = value;
+    if (record["truncated"] === true)
+        return "truncated";
+    const status = record["status"];
+    if (status === "truncated")
+        return "truncated";
+    if (status === "unknown" ||
+        status === "unavailable" ||
+        status === "partial" ||
+        status === "incomplete" ||
+        status === "unverifiable" ||
+        status === "failed" ||
+        status === "not_approved")
+        return "unknown";
+    for (const key of ["coverage", "completeness"]) {
+        const nested = record[key];
+        if (!isRecord(nested))
+            continue;
+        const nestedStatus = incompleteStatus(nested);
+        if (nestedStatus !== null)
+            return nestedStatus;
+    }
+    return null;
+};
+const hasResidualUnknowns = (value) => isRecord(value) &&
+    Array.isArray(value["residual_unknowns"]) &&
+    value["residual_unknowns"].length > 0;
+const unknownScopes = (record) => {
+    const residualUnknowns = record["residual_unknowns"];
+    if (!Array.isArray(residualUnknowns))
+        return [];
+    return residualUnknowns.flatMap((item) => {
+        if (!isRecord(item) || typeof item["scope"] !== "string")
+            return [];
+        return [item["scope"]];
+    });
+};
+const evidenceView = (input) => {
+    if (!isRecord(input))
+        return {
+            values: {},
+            evidence_ids: [],
+            status: null,
+            unknown_scopes: [],
+        };
+    const normalized = input["normalized_result"];
+    const values = isRecord(normalized) ? normalized : input;
+    const normalizedStatus = isRecord(normalized)
+        ? incompleteStatus(normalized)
+        : null;
+    return {
+        values,
+        evidence_ids: evidenceIds(input),
+        status: incompleteStatus(input) ?? normalizedStatus,
+        unknown_scopes: uniqueStrings([
+            ...unknownScopes(input),
+            ...(isRecord(normalized) ? unknownScopes(normalized) : []),
+        ]),
+    };
+};
+const dimensionScope = (dimensionName) => {
+    if (dimensionName === "exit_code" || dimensionName === "exit")
+        return "exit";
+    if (dimensionName === "process" ||
+        dimensionName === "process_tree" ||
+        dimensionName === "event_journal")
+        return "process";
+    if (dimensionName === "stdout" || dimensionName === "stderr")
+        return "terminal";
+    if (dimensionName === "filesystem")
+        return "filesystem";
+    if (dimensionName === "shim_events")
+        return "shim";
+    if (dimensionName === "protocol_events")
+        return "protocol";
+    return null;
+};
+const statusForDimension = (view, dimensionName) => {
+    const valueStatus = incompleteStatus(view.values[dimensionName]);
+    if (valueStatus !== null)
+        return valueStatus;
+    if (hasResidualUnknowns(view.values[dimensionName]))
+        return "unknown";
+    const scope = dimensionScope(dimensionName);
+    return scope !== null && view.unknown_scopes.includes(scope)
+        ? "unknown"
+        : view.status;
+};
+const comparisonIncompleteStatus = (expected, actual, options) => {
+    const expectedStatus = options.expected_status ?? incompleteStatus(expected);
+    const actualStatus = options.actual_status ?? incompleteStatus(actual);
+    if (options.truncated)
+        return "truncated";
+    if (expectedStatus === "truncated" || actualStatus === "truncated")
+        return "truncated";
+    if (expectedStatus === "unknown" || actualStatus === "unknown")
+        return "unknown";
+    return null;
+};
+/** Check if a dimension name is volatile (timing/normalization noise). */
+export function isVolatileDimension(name) {
+    return VOLATILE_DIMENSIONS.has(name);
+}
+/** Check if a dimension name carries semantic content. */
+export function isSemanticDimension(name) {
+    return SEMANTIC_DIMENSIONS.has(name);
+}
+/**
+ * Compare two values for a dimension, classifying semantic diffs
+ * from timing/normalization noise.
+ *
+ * Volatile dimensions (timing, timestamps, PIDs) are always treated
+ * as matches because their values are expected to differ across
+ * runs and do not carry semantic meaning.
+ */
+export function compareDimension(dimensionName, expected, actual, options = {}) {
+    // Volatile dimensions: always match regardless of values
+    if (isVolatileDimension(dimensionName)) {
+        return {
+            name: dimensionName,
+            status: "match",
+            message: "volatile dimension ignored",
+            evidence_ids: uniqueStrings(options.evidence_ids ?? []),
+        };
+    }
+    const status = comparisonIncompleteStatus(expected, actual, options);
+    const resultEvidenceIds = uniqueStrings(options.evidence_ids ?? []);
+    if (status !== null) {
+        return {
+            name: dimensionName,
+            status,
+            message: status === "truncated"
+                ? "evidence was truncated"
+                : "evidence completeness is unknown",
+            evidence_ids: resultEvidenceIds,
+        };
+    }
+    if (expected === undefined && actual === undefined) {
+        return {
+            name: dimensionName,
+            status: "unknown",
+            message: "both expected and actual are undefined",
+            evidence_ids: resultEvidenceIds,
+        };
+    }
+    if (expected === undefined || actual === undefined) {
+        return {
+            name: dimensionName,
+            status: "unknown",
+            message: "one side has no observed value",
+            evidence_ids: resultEvidenceIds,
+        };
+    }
+    // Semantic comparison for structured objects
+    if (typeof expected === "object" && typeof actual === "object") {
+        const expectedJson = JSON.stringify(sortKeys(expected));
+        const actualJson = JSON.stringify(sortKeys(actual));
+        if (expectedJson === actualJson) {
+            return {
+                name: dimensionName,
+                status: "match",
+                message: "",
+                evidence_ids: resultEvidenceIds,
+            };
+        }
+        return {
+            name: dimensionName,
+            status: "mismatch",
+            message: "semantic content differs",
+            evidence_ids: resultEvidenceIds,
+        };
+    }
+    // Primitive comparison
+    if (expected === actual) {
+        return {
+            name: dimensionName,
+            status: "match",
+            message: "",
+            evidence_ids: resultEvidenceIds,
+        };
+    }
+    return {
+        name: dimensionName,
+        status: "mismatch",
+        message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
+        evidence_ids: resultEvidenceIds,
+    };
+}
+/** Recursively sort object keys for deterministic comparison. */
+function sortKeys(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!isRecord(value))
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+}
+/**
+ * Evaluate a trust gate for one scenario by comparing expected
+ * evidence against the actual captured run.
+ */
+export function evaluateTrustGate(contract, expectedEvidence, actualEvidence, options = {}) {
+    const dimensionResults = [];
+    let firstDivergence = null;
+    const expectedView = evidenceView(expectedEvidence);
+    const actualView = evidenceView(actualEvidence);
+    for (const dim of contract.dimensions) {
+        if (!dim.required)
+            continue;
+        const expectedValue = expectedView.values[dim.name];
+        const actualValue = actualView.values[dim.name];
+        const result = compareDimension(dim.name, expectedValue, actualValue, {
+            ...options,
+            expected_status: statusForDimension(expectedView, dim.name),
+            actual_status: statusForDimension(actualView, dim.name),
+            evidence_ids: uniqueStrings([
+                ...actualView.evidence_ids,
+                ...expectedView.evidence_ids,
+            ]),
+        });
+        dimensionResults.push(result);
+        if (result.status === "mismatch" && firstDivergence === null) {
+            firstDivergence = {
+                dimension: dim.name,
+                evidence_id: result.evidence_ids[0] ?? "unknown",
+                message: result.message,
+            };
+        }
+    }
+    const hasFail = dimensionResults.some((r) => r.status === "mismatch" || r.status === "truncated");
+    const hasUnknown = dimensionResults.some((r) => r.status === "unknown");
+    const verdict = hasFail
+        ? "fail"
+        : hasUnknown
+            ? "unknown"
+            : "pass";
+    return {
+        scenario_id: contract.scenario_id,
+        verdict,
+        dimension_results: dimensionResults,
+        first_divergence: firstDivergence,
+    };
+}
+/**
+ * Evaluate trust gates for all scenarios in a conformance package.
+ * Rejects runs that differ in required dimensions. Unknown/truncated
+ * evidence is never treated as equivalence.
+ */
+export function evaluatePackageTrustGates(pkg, actualEvidence, options = {}) {
+    const results = [];
+    for (const contract of pkg.verifier_contracts) {
+        const expected = pkg.expected_evidence.find((e) => e.scenario_id === contract.scenario_id);
+        if (!expected)
+            continue;
+        const expectedEvidence = expected.envelopes[0] ?? {};
+        const actual = actualEvidence[contract.scenario_id] ?? {};
+        const result = evaluateTrustGate(contract, expectedEvidence, actual, options);
+        results.push(result);
+    }
+    return results;
+}

package/dist/domain/customProtocolCapture.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
+/** Supported transport types for custom protocol capture. */
+export const transportTypeSchema = z.enum([
+    "tcp",
+    "udp",
+    "ipc",
+    "unix-socket",
+    "named-pipe",
+    "xpc",
+]);
+/** Direction of a protocol frame. */
+export const frameDirectionSchema = z.enum(["sent", "received", "intercepted"]);
+/** A captured protocol frame. */
+export const protocolFrameSchema = z.strictObject({
+    /** Monotonic sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Transport type. */
+    transport: transportTypeSchema,
+    /** Direction of the frame. */
+    direction: frameDirectionSchema,
+    /** Source process identity. */
+    source_pid: z.number().int().nullable(),
+    /** Destination process identity. */
+    dest_pid: z.number().int().nullable(),
+    /** Endpoint address (IP:port, socket path, pipe name). */
+    source_endpoint: z.string().nullable(),
+    /** Destination endpoint. */
+    dest_endpoint: z.string().nullable(),
+    /** Raw frame data as base64. */
+    raw_data: z.string().nullable(),
+    /** Decoded/parsed frame content if known. */
+    decoded_content: jsonValueSchema.nullable(),
+    /** Frame size in bytes. */
+    size: z.number().int().nonnegative(),
+    /** Whether the frame was truncated. */
+    truncated: z.boolean().default(false),
+});
+/** Authentication flow stage. */
+export const authStageSchema = z.enum([
+    "init",
+    "challenge",
+    "response",
+    "token_exchange",
+    "renewal",
+    "revocation",
+    "failure",
+    "success",
+]);
+/** Token lifecycle event. */
+export const tokenLifecycleEventSchema = z.enum([
+    "issued",
+    "refreshed",
+    "expired",
+    "revoked",
+    "renewed",
+]);
+/** A captured authentication flow event. */
+export const authFlowEventSchema = z.strictObject({
+    /** Monotonic sequence number. */
+    sequence: z.number().int().nonnegative(),
+    /** Timestamp in milliseconds. */
+    at_ms: z.number().int().nonnegative(),
+    /** Authentication stage. */
+    stage: authStageSchema,
+    /** Protocol used. */
+    protocol: z.string().min(1),
+    /** Token type if applicable. */
+    token_type: z.string().nullable(),
+    /** Token lifecycle event. */
+    token_lifecycle: tokenLifecycleEventSchema.nullable(),
+    /** Correlation ID linking challenge-response pairs. */
+    correlation_id: z.string().nullable(),
+    /** Whether credentials were detected and redacted. */
+    credentials_redacted: z.boolean().default(false),
+    /** Whether the authentication succeeded. */
+    succeeded: z.boolean().default(false),
+    /** Error message if authentication failed. */
+    error: z.string().nullable(),
+});
+/** A captured protocol session. */
+export const customProtocolCaptureSchema = z.strictObject({
+    /** Transport type for this session. */
+    transport: transportTypeSchema,
+    /** Captured frames in order. */
+    frames: z.array(protocolFrameSchema).min(0).max(100_000),
+    /** Authentication flow events. */
+    auth_events: z.array(authFlowEventSchema).default([]),
+    /** Whether any frame was truncated. */
+    has_truncated: z.boolean().default(false),
+    /** Whether credentials were detected. */
+    credentials_detected: z.boolean().default(false),
+});
+/** Correlate a frame with process identity. */
+export function correlateProcessIdentity(frame, pid) {
+    return frame.source_pid === pid || frame.dest_pid === pid;
+}
+/** Check if a frame contains credential-like content. */
+export function looksLikeCredentialFrame(frame) {
+    const patterns = [
+        "password",
+        "token",
+        "secret",
+        "api_key",
+        "apikey",
+        "authorization",
+        "credential",
+    ];
+    const content = JSON.stringify(frame.decoded_content ?? "").toLowerCase();
+    return patterns.some((p) => content.includes(p));
+}
+/** Filter frames by transport type. */
+export function framesByTransport(frames, transport) {
+    return frames.filter((f) => f.transport === transport);
+}
+/** Get all authentication flow events for a specific protocol. */
+export function authEventsByProtocol(events, protocol) {
+    return events.filter((e) => e.protocol === protocol);
+}
+/** Get successful authentication events. */
+export function successfulAuthEvents(events) {
+    return events.filter((e) => e.succeeded);
+}
+/** Get failed authentication events. */
+export function failedAuthEvents(events) {
+    return events.filter((e) => !e.succeeded);
+}
+/** Compute the duration of an authentication flow in milliseconds. */
+export function authFlowDuration(events) {
+    const first = events.at(0);
+    const last = events.at(-1);
+    if (first === undefined || last === undefined)
+        return null;
+    return last.at_ms - first.at_ms;
+}