rea-agents 2.0.0 → 2.2.0

package/dist/domain/replayMachineRuntime.js

@@ -0,0 +1,215 @@
+import canonicalize from "canonicalize";
+const parseJson = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+const atPath = (value, path) => {
+    let current = value;
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[segment];
+            continue;
+        }
+        if (typeof current !== "object" ||
+            current === null ||
+            !Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+};
+const actionJsonBody = (transition) => {
+    for (const action of transition.actions)
+        if (action.type === "http_response")
+            return action.body;
+        else if (action.type === "websocket_send")
+            return action.data;
+    return undefined;
+};
+const readValue = (source, event, transition) => {
+    switch (source.source) {
+        case "request_header":
+            return event.headers[source.name.toLowerCase()];
+        case "request_json":
+            return atPath(parseJson(event.body), source.path);
+        case "websocket_json":
+            return atPath(parseJson(event.body), source.path);
+        case "action_json": {
+            const body = actionJsonBody(transition);
+            return body === undefined
+                ? undefined
+                : atPath(parseJson(body), source.path);
+        }
+    }
+};
+const triggerMatches = (transition, event) => {
+    const trigger = transition.trigger;
+    if (trigger.protocol !== event.protocol || trigger.path !== event.path)
+        return false;
+    if ("headers" in trigger &&
+        Object.entries(trigger.headers).some(([name, value]) => event.headers[name.toLowerCase()] !== value))
+        return false;
+    if (trigger.protocol === "http")
+        return (trigger.method === event.method &&
+            (trigger.body === null || trigger.body === event.body));
+    if (trigger.protocol === "websocket_message")
+        return trigger.body === null || trigger.body === event.body;
+    return true;
+};
+const isJsonCompatible = (value) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonCompatible);
+    if (typeof value !== "object")
+        return false;
+    return Object.values(value).every(isJsonCompatible);
+};
+const replayValuesEqual = (left, right) => isJsonCompatible(left) &&
+    isJsonCompatible(right) &&
+    (Object.is(left, right) || canonicalize(left) === canonicalize(right));
+/** Stateful evaluator for one validated replay-machine instance. */
+export class ReplayMachineRuntime {
+    machine;
+    #variables = new Map();
+    #sensitiveValues = new Map();
+    #uses = new Map();
+    #stateVisits = new Map();
+    #timeline = [];
+    #state;
+    #connections = 0;
+    #messages = 0;
+    #bytes = 0;
+    #lastAtMs = 0;
+    constructor(machine) {
+        this.machine = machine;
+        this.#state = machine.initial_state;
+        this.#stateVisits.set(machine.initial_state, 1);
+    }
+    /** Current machine state after all accepted transitions. */
+    get state() {
+        return this.#state;
+    }
+    /** Ordered, secret-free transition records. */
+    get timeline() {
+        return this.#timeline;
+    }
+    /** Replace captured secret values with stable aliases before persistence. */
+    redact(value) {
+        let redacted = value;
+        const secrets = [...this.#sensitiveValues]
+            .flatMap(([variable, values]) => [...values].map((secret) => ({ variable, secret })))
+            .sort((left, right) => right.secret.length - left.secret.length ||
+            left.variable.localeCompare(right.variable));
+        for (const { variable, secret } of secrets)
+            redacted = redacted.replaceAll(secret, `<secret:${variable}>`);
+        return redacted;
+    }
+    /** Evaluate and, when admitted, commit one protocol event. */
+    dispatch(event) {
+        const normalizedEvent = {
+            ...event,
+            headers: Object.fromEntries(Object.entries(event.headers).map(([name, value]) => [
+                name.toLowerCase(),
+                value,
+            ])),
+        };
+        if (!this.#admitEvent(normalizedEvent))
+            return this.#refusal("limit_exhausted");
+        const matching = this.machine.transitions
+            .map((transition, declarationOrder) => ({
+            transition,
+            declarationOrder,
+        }))
+            .filter(({ transition }) => triggerMatches(transition, normalizedEvent));
+        const eligible = matching
+            .filter(({ transition }) => transition.from === this.#state)
+            .sort((left, right) => left.transition.priority - right.transition.priority ||
+            left.declarationOrder - right.declarationOrder);
+        if (eligible.length === 0)
+            return this.#refusal(matching.length === 0
+                ? "unmatched"
+                : normalizedEvent.protocol === "websocket_connect" &&
+                    normalizedEvent.connection === "reconnect"
+                    ? "unexpected_reconnect"
+                    : "invalid_state");
+        const guarded = eligible.filter(({ transition }) => transition.guards.every((guard) => this.#variables.has(guard.variable) &&
+            replayValuesEqual(this.#variables.get(guard.variable), readValue(guard.value, normalizedEvent, transition))));
+        if (guarded.length === 0)
+            return this.#refusal("guard_failed");
+        if (this.#timeline.length >= this.machine.max_transitions)
+            return this.#refusal("transition_exhausted");
+        const usable = guarded.find(({ transition }) => (this.#uses.get(transition.id) ?? 0) < transition.max_uses);
+        if (usable === undefined)
+            return this.#refusal("transition_exhausted");
+        const transition = usable.transition;
+        const used = this.#uses.get(transition.id) ?? 0;
+        const nextState = this.machine.states.find(({ name }) => name === transition.to);
+        const nextVisits = (this.#stateVisits.get(transition.to) ?? 0) + 1;
+        if (nextState === undefined || nextVisits > nextState.max_visits)
+            return this.#refusal("limit_exhausted");
+        const captures = transition.captures.map((capture) => ({
+            ...capture,
+            captured: readValue(capture.value, normalizedEvent, transition),
+        }));
+        if (captures.some(({ captured, sensitive }) => !isJsonCompatible(captured) ||
+            (sensitive && typeof captured !== "string")))
+            return this.#refusal("invalid_capture");
+        for (const capture of captures) {
+            this.#variables.set(capture.variable, capture.captured);
+            if (capture.sensitive && typeof capture.captured === "string") {
+                const values = this.#sensitiveValues.get(capture.variable) ?? new Set();
+                if (capture.captured.length > 0)
+                    values.add(capture.captured);
+                this.#sensitiveValues.set(capture.variable, values);
+            }
+        }
+        const record = {
+            sequence: this.#timeline.length,
+            transition_id: transition.id,
+            state_before: this.#state,
+            state_after: transition.to,
+            sensitive_aliases: captures
+                .filter(({ sensitive }) => sensitive)
+                .map(({ variable }) => variable)
+                .sort(),
+        };
+        this.#uses.set(transition.id, used + 1);
+        this.#stateVisits.set(transition.to, nextVisits);
+        this.#state = transition.to;
+        this.#timeline.push(record);
+        return {
+            outcome: "matched",
+            actions: transition.actions,
+            transition: record,
+        };
+    }
+    #admitEvent(event) {
+        const connections = this.#connections + (event.protocol === "websocket_connect" ? 1 : 0);
+        const messages = this.#messages + (event.protocol === "websocket_message" ? 1 : 0);
+        const bytes = this.#bytes + Buffer.byteLength(event.body);
+        if (!Number.isSafeInteger(event.at_ms) ||
+            event.at_ms < this.#lastAtMs ||
+            event.at_ms > this.machine.limits.duration_ms ||
+            connections > this.machine.limits.connections ||
+            messages > this.machine.limits.messages ||
+            bytes > this.machine.limits.bytes)
+            return false;
+        this.#connections = connections;
+        this.#messages = messages;
+        this.#bytes = bytes;
+        this.#lastAtMs = event.at_ms;
+        return true;
+    }
+    #refusal(outcome) {
+        return { outcome, actions: [], transition: null };
+    }
+}

package/dist/domain/runtimeCharacterization.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const stableIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._:/-]{0,199}$/u);
+const runtimeIdentitySchema = z.strictObject({
+    family: z.string().trim().min(1).max(100),
+    provider_id: stableIdSchema,
+    executable_path: z.string().min(1).max(4_096),
+    executable_sha256: digestSchema,
+    version: z.string().trim().min(1).max(500),
+    profile_sha256: digestSchema,
+});
+const artifactIdentitySchema = z.strictObject({
+    path: z.string().min(1).max(4_096),
+    sha256: digestSchema,
+    byte_length: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+});
+const callableIdentitySchema = z.strictObject({
+    callable_id: stableIdSchema,
+    module_id: stableIdSchema,
+    export_name: z.string().min(1).max(1_000),
+    semantic_evidence_id: z
+        .string()
+        .regex(/^ev_[a-f0-9]{64}$/u)
+        .nullable(),
+    selector_sha256: digestSchema,
+});
+export const runtimeCharacterizationPlanSchema = z.strictObject({
+    schema_version: z.literal(1),
+    plan_sha256: digestSchema,
+    preparation_sha256: digestSchema,
+    artifact: artifactIdentitySchema,
+    runtime: runtimeIdentitySchema,
+    callable: callableIdentitySchema,
+    working_directory: z.string().min(1).max(4_096),
+    isolated_home: z.string().min(1).max(4_096),
+    expected_effect: z.enum(["pure", "bounded-effects", "observation-only"]),
+    allowed_boundaries: z.array(stableIdSchema).max(1_000),
+    limits: z.strictObject({
+        max_calls: z.number().int().min(1).max(10_000),
+        max_processes: z.number().int().min(0).max(1_000),
+        max_files: z.number().int().min(0).max(100_000),
+        max_bytes: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+        max_handles: z.number().int().min(0).max(100_000),
+        timeout_ms: z.number().int().min(1).max(300_000),
+        idle_timeout_ms: z.number().int().min(1).max(300_000),
+    }),
+    determinism: z.strictObject({
+        clock: z.enum(["fixed", "real"]),
+        randomness: z.enum(["seeded", "system"]),
+        identifiers: z.enum(["deterministic", "runtime"]),
+        seed: z.number().int().min(0).max(0xffff_ffff),
+    }),
+    authority: z.strictObject({
+        preparation_approved: z.literal(true),
+        execution_approved: z.literal(false),
+        network: z.enum(["none", "loopback"]),
+        provider_owned_process_only: z.literal(true),
+    }),
+});
+/** Commit a provider-neutral preparation plan; execution requires a later approval. */
+export const createRuntimeCharacterizationPlan = (input) => {
+    const parsed = runtimeCharacterizationPlanSchema
+        .omit({ plan_sha256: true })
+        .parse(input);
+    return runtimeCharacterizationPlanSchema.parse({
+        ...parsed,
+        plan_sha256: digest(parsed),
+    });
+};
+/** Parse a characterization plan and reject altered commitments. */
+export const parseRuntimeCharacterizationPlan = (input) => {
+    const parsed = runtimeCharacterizationPlanSchema.parse(input);
+    const { plan_sha256: planSha256, ...semantic } = parsed;
+    if (planSha256 !== digest(semantic))
+        throw new TypeError("Runtime characterization plan digest is invalid");
+    return parsed;
+};
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Runtime characterization plan is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};

package/dist/domain/runtimeIdentification.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { parseArtifactInventoryEvidence } from "./artifactInventoryEvidence.js";
+import { evidenceSchema } from "./evidence.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const runtimeFamilySchema = z.enum([
+    "android",
+    "apple",
+    "javascript",
+    "jvm",
+    "native",
+    "webassembly",
+]);
+const observationSchema = z.strictObject({
+    path: z.string().min(1).max(4_096),
+    artifact_id: z.string().regex(/^art_[a-f0-9]{64}$/u),
+    sha256: digestSchema,
+    format: z.string().min(1).max(100),
+});
+/** Authenticated artifact inventory pages to classify by runtime family. */
+const runtimeIdentificationInputSchema = z.strictObject({
+    inventory_evidence: z.array(evidenceSchema).min(1).max(100),
+    limits: z
+        .strictObject({
+        max_observations: z.number().int().min(1).max(10_000).default(1_000),
+    })
+        .default({ max_observations: 1_000 }),
+});
+/** Provider-neutral runtime identification with explicit tooling availability. */
+export const runtimeIdentificationResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    identification_id: z.string().regex(/^rid_[a-f0-9]{64}$/u),
+    root_sha256: digestSchema,
+    root_format: z.string().min(1).max(100),
+    source_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    runtimes: z.array(z.strictObject({
+        family: runtimeFamilySchema,
+        inspection: z.enum([
+            "available",
+            "provider-missing",
+            "provider-selection-required",
+        ]),
+        provider_id: z.string().min(1).max(200).nullable(),
+        reason: z.string().min(1).max(1_000).nullable(),
+        observations: z.array(observationSchema),
+        omitted_observations: z.number().int().min(0),
+    })),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inventory", "partial", "truncated"]),
+        inventory_complete: z.boolean(),
+        omitted_observations: z.number().int().min(0),
+    }),
+    limitations: z.array(z.string().min(1).max(4_096)).max(100),
+});
+const PROVIDERS = {
+    android: {
+        inspection: "available",
+        id: "rea-android-application",
+        reason: null,
+    },
+    apple: { inspection: "available", id: "rea-apple-application", reason: null },
+    javascript: {
+        inspection: "available",
+        id: "rea-javascript-application",
+        reason: null,
+    },
+    jvm: {
+        inspection: "provider-missing",
+        id: null,
+        reason: "Install or configure a JVM bytecode-analysis provider.",
+    },
+    native: {
+        inspection: "provider-selection-required",
+        id: null,
+        reason: "Select an available native deep-analysis provider for this target and host.",
+    },
+    webassembly: {
+        inspection: "provider-missing",
+        id: null,
+        reason: "Install or configure a WebAssembly semantic-analysis provider.",
+    },
+};
+/** Identify runtime families without executing or semantically decoding target bytes. */
+export const identifyRuntimes = (input) => {
+    const parsed = runtimeIdentificationInputSchema.parse(input);
+    const { evidence, inventory } = parseArtifactInventoryEvidence(parsed.inventory_evidence);
+    const nodes = new Map(inventory.nodes.map((node) => [node.artifact_id, node]));
+    const grouped = new Map();
+    const add = (family, observation) => {
+        const observations = grouped.get(family) ?? [];
+        observations.push(observation);
+        grouped.set(family, observations);
+    };
+    for (const occurrence of inventory.occurrences) {
+        if (occurrence.artifact_id === null)
+            continue;
+        const node = nodes.get(occurrence.artifact_id);
+        if (node === undefined)
+            throw new TypeError("Runtime observation has no artifact node");
+        const observation = {
+            path: occurrence.logical_path,
+            artifact_id: node.artifact_id,
+            sha256: node.sha256,
+            format: node.format,
+        };
+        for (const family of familiesFor(node.format, occurrence.logical_path))
+            add(family, observation);
+    }
+    const rootObservation = inventory.nodes.find(({ sha256 }) => sha256 === inventory.manifest.root_sha256);
+    if (rootObservation !== undefined)
+        for (const family of familiesFor(inventory.manifest.root_format, "."))
+            add(family, {
+                path: ".",
+                artifact_id: rootObservation.artifact_id,
+                sha256: rootObservation.sha256,
+                format: rootObservation.format,
+            });
+    let remaining = parsed.limits.max_observations;
+    let omitted = 0;
+    const runtimes = [...grouped.entries()]
+        .sort(([left], [right]) => compare(left, right))
+        .map(([family, values]) => {
+        const unique = deduplicate(values);
+        const observations = unique.slice(0, remaining);
+        remaining -= observations.length;
+        const omittedObservations = unique.length - observations.length;
+        omitted += omittedObservations;
+        const provider = providerFor(family, inventory.manifest.root_format);
+        return {
+            family,
+            inspection: provider.inspection,
+            provider_id: provider.id,
+            reason: provider.reason,
+            observations,
+            omitted_observations: omittedObservations,
+        };
+    });
+    const limitations = [
+        ...(!inventory.complete
+            ? [
+                "Source inventory pages are incomplete; absent runtimes remain unknown.",
+            ]
+            : []),
+        ...(omitted > 0
+            ? [`${String(omitted)} runtime observations were omitted by the limit.`]
+            : []),
+        "Runtime families are identified from exact artifact formats and paths; semantic claims require the named provider.",
+    ];
+    const withoutId = {
+        schema_version: 1,
+        root_sha256: inventory.manifest.root_sha256,
+        root_format: inventory.manifest.root_format,
+        source_evidence_ids: evidence
+            .map(({ evidence_id: id }) => id)
+            .sort(compare),
+        runtimes,
+        coverage: {
+            status: omitted > 0
+                ? "truncated"
+                : inventory.complete
+                    ? "complete-within-inventory"
+                    : "partial",
+            inventory_complete: inventory.complete,
+            omitted_observations: omitted,
+        },
+        limitations,
+    };
+    return runtimeIdentificationResultSchema.parse({
+        ...withoutId,
+        identification_id: `rid_${digest(withoutId)}`,
+    });
+};
+const providerFor = (family, rootFormat) => family === "android" && rootFormat !== "apk"
+    ? {
+        inspection: "provider-selection-required",
+        id: null,
+        reason: "Extract or select an APK root before using the Android application provider.",
+    }
+    : PROVIDERS[family];
+const familiesFor = (format, path) => {
+    const families = new Set();
+    if (format === "apk" ||
+        format === "dex" ||
+        /(?:^|\/)[^/]+\.dex$/iu.test(path) ||
+        /(?:^|\/)AndroidManifest\.xml$/u.test(path))
+        families.add("android");
+    if (format === "ipa")
+        families.add("apple");
+    if (format === "javascript-bundle")
+        families.add("javascript");
+    if (format === "jvm-class" || /(?:^|\/)[^/]+\.class$/iu.test(path))
+        families.add("jvm");
+    if (["elf", "mach-o", "mach-o-universal", "pe"].includes(format))
+        families.add("native");
+    if (format === "webassembly" || /(?:^|\/)[^/]+\.wasm$/iu.test(path))
+        families.add("webassembly");
+    return [...families];
+};
+const deduplicate = (values) => [
+    ...new Map(values.map((value) => [`${value.path}\0${value.artifact_id}`, value])).values(),
+].sort((left, right) => compare(left.path, right.path));
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Runtime identification is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};