rea-agents 3.2.0 → 4.0.0

package/dist/application/LoopbackReplay.js

@@ -1,389 +0,0 @@
-import { createServer, } from "node:http";
-import { WebSocketServer } from "ws";
-import {} from "../domain/replayMachineRuntime.js";
-import { closeReplayServer, listenOnLoopback, recordMachineEvent, readReplayRequestBody, ReplayRecorder, ReplayDelayScheduler, requestHeaders, } from "./LoopbackReplayRecorder.js";
-const recordHttpResponse = (recorder, request, data, outcome) => recorder.record({
-    at_ms: recorder.atMs(),
-    protocol: "http",
-    direction: "response",
-    method: request.method,
-    path: request.path,
-    data,
-    outcome,
-});
-const handleMachineHttp = async (recorder, request, delays) => {
-    const machine = recorder.machine;
-    if (machine === undefined)
-        return;
-    const decision = recorder.dispatchMachine({
-        protocol: "http",
-        connection: "not_applicable",
-        at_ms: request.rawAtMs,
-        recorded_at_ms: request.recordedAtMs,
-        method: request.method,
-        path: request.path,
-        headers: requestHeaders(request.request),
-        body: request.body,
-    });
-    recordMachineEvent(recorder, {
-        at_ms: request.recordedAtMs,
-        protocol: "http",
-        direction: "request",
-        method: request.method,
-        path: request.path,
-        data: request.body,
-    }, decision);
-    if (decision.outcome !== "matched") {
-        request.response.statusCode = decision.outcome === "unmatched" ? 404 : 409;
-        request.response.end();
-        return;
-    }
-    for (const action of decision.actions) {
-        if (action.type === "delay")
-            await delays.wait(action.duration_ms);
-        else if (action.type === "disconnect") {
-            request.response.destroy();
-            recordHttpResponse(recorder, request, "", "disconnected");
-            return;
-        }
-        else if (action.type === "http_response") {
-            request.response.statusCode = action.status;
-            for (const [name, value] of Object.entries(action.headers))
-                request.response.setHeader(name, value);
-            request.response.end(action.body);
-            recordHttpResponse(recorder, request, machine.redact(action.body), "matched");
-        }
-    }
-};
-const handleStaticHttp = async (recorder, request, calls, delays) => {
-    const index = recorder.scenario.replay.http.findIndex((route) => route.method !== request.method || route.path !== request.path
-        ? false
-        : (route.request_body === undefined ||
-            route.request_body === request.body) &&
-            Object.entries(route.request_headers).every(([name, value]) => request.request.headers[name.toLowerCase()] === value));
-    const route = recorder.scenario.replay.http[index];
-    const used = index < 0 ? 0 : (calls.get(index) ?? 0);
-    const outcome = route === undefined
-        ? "unmatched"
-        : used >= route.max_calls
-            ? "script_exhausted"
-            : "matched";
-    recorder.record({
-        at_ms: recorder.atMs(),
-        protocol: "http",
-        direction: "request",
-        method: request.method,
-        path: request.path,
-        data: request.body.length === 0 ? "" : "<redacted-request-body>",
-        outcome,
-    });
-    if (route === undefined || outcome === "script_exhausted") {
-        request.response.statusCode = route === undefined ? 404 : 409;
-        request.response.end();
-        return;
-    }
-    calls.set(index, used + 1);
-    if (route.delay_ms > 0)
-        await delays.wait(route.delay_ms);
-    if (route.disconnect) {
-        request.response.destroy();
-        recordHttpResponse(recorder, request, "", "disconnected");
-        return;
-    }
-    request.response.statusCode = route.status;
-    for (const [name, value] of Object.entries(route.response_headers))
-        request.response.setHeader(name, value);
-    request.response.end(route.body);
-    recordHttpResponse(recorder, request, route.body, "matched");
-};
-const handleHttpRequest = async (recorder, request, response, calls, delays) => {
-    const body = await readReplayRequestBody(request, recorder.scenario.limits.protocol_body_bytes);
-    const method = request.method ?? "GET";
-    const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
-    if (body === undefined) {
-        recorder.truncated = true;
-        response.statusCode = 413;
-        response.end();
-        recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "http",
-            direction: "request",
-            method,
-            path,
-            data: "<body-over-limit>",
-            outcome: "unmatched",
-        });
-        return;
-    }
-    const replayRequest = {
-        request,
-        response,
-        method,
-        path,
-        body,
-        rawAtMs: recorder.rawAtMs(),
-        recordedAtMs: recorder.atMs(),
-    };
-    await (recorder.machine === undefined
-        ? handleStaticHttp(recorder, replayRequest, calls, delays)
-        : recorder.enqueueMachine(() => handleMachineHttp(recorder, replayRequest, delays)));
-};
-const createHttpHandler = (recorder, delays) => {
-    const calls = new Map();
-    return (request, response) => {
-        void handleHttpRequest(recorder, request, response, calls, delays).catch(() => {
-            recorder.truncated = true;
-            if (response.headersSent)
-                response.destroy();
-            else {
-                response.statusCode = 500;
-                response.end();
-            }
-        });
-    };
-};
-const sendWebSocketScript = async (client, connection, recorder, delays) => {
-    const scripts = recorder.scenario.replay.websocket_connections;
-    const script = scripts[connection - 1];
-    if (scripts.length > 0 && script === undefined) {
-        recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "websocket",
-            direction: "sent",
-            method: null,
-            path: "/ws",
-            data: "",
-            outcome: "script_exhausted",
-        });
-        client.terminate();
-        return;
-    }
-    const messages = script?.messages ??
-        recorder.scenario.replay.websocket_messages.map((data) => ({
-            data,
-            delay_ms: 0,
-        }));
-    for (const message of messages) {
-        if (message.delay_ms > 0)
-            await delays.wait(message.delay_ms);
-        if (client.readyState !== 1)
-            return;
-        client.send(message.data);
-        recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "websocket",
-            direction: "sent",
-            method: null,
-            path: "/ws",
-            data: message.data,
-            outcome: "matched",
-        });
-    }
-    if (script?.disconnect_after === true) {
-        client.close();
-        recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "websocket",
-            direction: "sent",
-            method: null,
-            path: "/ws",
-            data: "",
-            outcome: "disconnected",
-        });
-    }
-};
-const runWebSocketActions = async (client, recorder, decision, path, delays) => {
-    for (const action of decision.actions) {
-        if (action.type === "delay") {
-            await delays.wait(action.duration_ms);
-            continue;
-        }
-        if (action.type === "disconnect") {
-            client.close();
-            recorder.record({
-                at_ms: recorder.atMs(),
-                protocol: "websocket",
-                direction: "sent",
-                method: null,
-                path,
-                data: "",
-                outcome: "disconnected",
-            });
-            return;
-        }
-        if (action.type === "websocket_send" && client.readyState === 1) {
-            client.send(action.data);
-            recorder.record({
-                at_ms: recorder.atMs(),
-                protocol: "websocket",
-                direction: "sent",
-                method: null,
-                path,
-                data: recorder.machine?.redact(action.data) ?? action.data,
-                outcome: "matched",
-            });
-        }
-    }
-};
-const handleStaticWebSocket = (client, recorder, connection, path, delays) => {
-    client.on("message", (value) => recorder.record({
-        at_ms: recorder.atMs(),
-        protocol: "websocket",
-        direction: "received",
-        method: null,
-        path,
-        data: value.toString(),
-        outcome: "matched",
-    }));
-    void sendWebSocketScript(client, connection, recorder, delays);
-};
-const handleMachineWebSocket = (options) => {
-    const { client, request, recorder, connection, path, delays } = options;
-    const machine = recorder.machine;
-    if (machine === undefined)
-        return;
-    void recorder
-        .enqueueMachine(async () => {
-        const connectedAt = recorder.atMs();
-        const connectionDecision = recorder.dispatchMachine({
-            protocol: "websocket_connect",
-            connection: connection === 1 ? "initial" : "reconnect",
-            at_ms: recorder.rawAtMs(),
-            recorded_at_ms: connectedAt,
-            method: null,
-            path,
-            headers: requestHeaders(request),
-            body: "",
-        });
-        recordMachineEvent(recorder, {
-            at_ms: connectedAt,
-            protocol: "websocket",
-            direction: "received",
-            method: null,
-            path,
-            data: "",
-        }, connectionDecision);
-        if (connectionDecision.outcome === "matched")
-            await runWebSocketActions(client, recorder, connectionDecision, path, delays);
-        else
-            client.close();
-    })
-        .catch(() => {
-        recorder.truncated = true;
-        client.terminate();
-    });
-    client.on("message", (value) => {
-        const body = value.toString();
-        const rawAtMs = recorder.rawAtMs();
-        const recordedAtMs = recorder.atMs();
-        void recorder
-            .enqueueMachine(async () => {
-            const decision = recorder.dispatchMachine({
-                protocol: "websocket_message",
-                connection: connection === 1 ? "initial" : "reconnect",
-                at_ms: rawAtMs,
-                recorded_at_ms: recordedAtMs,
-                method: null,
-                path,
-                headers: {},
-                body,
-            });
-            recordMachineEvent(recorder, {
-                at_ms: recordedAtMs,
-                protocol: "websocket",
-                direction: "received",
-                method: null,
-                path,
-                data: body,
-            }, decision);
-            if (decision.outcome === "matched")
-                await runWebSocketActions(client, recorder, decision, path, delays);
-        })
-            .catch(() => {
-            recorder.truncated = true;
-            client.terminate();
-        });
-    });
-};
-const createWebSocketReplay = (server, recorder, delays) => {
-    let connections = 0;
-    const websocket = new WebSocketServer({
-        noServer: true,
-        maxPayload: recorder.scenario.limits.protocol_body_bytes,
-        clientTracking: true,
-    });
-    server.on("upgrade", (request, socket, head) => {
-        if (recorder.machine === undefined &&
-            new URL(request.url ?? "/", "http://127.0.0.1").pathname !== "/ws") {
-            socket.destroy();
-            return;
-        }
-        websocket.handleUpgrade(request, socket, head, (client) => websocket.emit("connection", client, request));
-    });
-    websocket.on("connection", (client, request) => {
-        connections += 1;
-        if (connections > recorder.scenario.limits.connections) {
-            recorder.truncated = true;
-            client.terminate();
-            return;
-        }
-        client.on("error", () => undefined);
-        const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
-        if (recorder.machine === undefined)
-            handleStaticWebSocket(client, recorder, connections, path, delays);
-        else
-            handleMachineWebSocket({
-                client,
-                request,
-                recorder,
-                connection: connections,
-                path,
-                delays,
-            });
-    });
-    return websocket;
-};
-/** Start bounded HTTP and WebSocket replay endpoints on IPv4 loopback only. */
-export const startLoopbackReplay = async (scenario, recordEvent = () => undefined) => {
-    const recorder = new ReplayRecorder(scenario, recordEvent);
-    const delays = new ReplayDelayScheduler();
-    const server = createServer(createHttpHandler(recorder, delays));
-    const websocket = createWebSocketReplay(server, recorder, delays);
-    let closePromise;
-    let port;
-    try {
-        port = await listenOnLoopback(server);
-    }
-    catch (cause) {
-        await closeReplayServer(server).catch(() => undefined);
-        throw cause;
-    }
-    return {
-        httpUrl: `http://127.0.0.1:${String(port)}`,
-        websocketUrl: `ws://127.0.0.1:${String(port)}/ws`,
-        get events() {
-            return recorder.events.map((event) => ({ ...event }));
-        },
-        get transitions() {
-            return recorder.transitions.map((transition) => ({
-                ...transition,
-                sensitive_aliases: [...transition.sensitive_aliases],
-            }));
-        },
-        get truncated() {
-            return recorder.truncated;
-        },
-        async close() {
-            closePromise ??= (async () => {
-                delays.close();
-                recorder.stopMachineAdmission();
-                await recorder.drainMachine();
-                for (const client of websocket.clients)
-                    client.terminate();
-                await new Promise((resolveClose) => websocket.close(() => resolveClose()));
-                await closeReplayServer(server);
-            })();
-            await closePromise;
-        },
-    };
-};

package/dist/application/LoopbackReplayRecorder.js

@@ -1,129 +0,0 @@
-import { ReplayMachineRuntime, } from "../domain/replayMachineRuntime.js";
-import { scheduleProcessDelay } from "./ProcessTimer.js";
-/** Bounded protocol and replay-machine observations for one process run. */
-export class ReplayRecorder {
-    scenario;
-    recordEvent;
-    events = [];
-    started = Date.now();
-    machine;
-    #machineQueue = Promise.resolve();
-    #machineAdmissionOpen = true;
-    truncated = false;
-    constructor(scenario, recordEvent = () => undefined) {
-        this.scenario = scenario;
-        this.recordEvent = recordEvent;
-        this.machine =
-            scenario.replay.machine === null
-                ? undefined
-                : new ReplayMachineRuntime(scenario.replay.machine);
-    }
-    get transitions() {
-        return this.machine?.timeline ?? [];
-    }
-    atMs() {
-        return (Math.floor((Date.now() - this.started) /
-            this.scenario.normalization.time_bucket_ms) * this.scenario.normalization.time_bucket_ms);
-    }
-    rawAtMs() {
-        return Date.now() - this.started;
-    }
-    enqueueMachine(operation) {
-        if (!this.#machineAdmissionOpen)
-            return Promise.reject(new Error("replay machine is closing"));
-        const result = this.#machineQueue.then(operation);
-        this.#machineQueue = result.then(() => undefined, () => undefined);
-        return result;
-    }
-    stopMachineAdmission() {
-        this.#machineAdmissionOpen = false;
-    }
-    async drainMachine() {
-        await this.#machineQueue;
-    }
-    dispatchMachine(event) {
-        if (this.machine === undefined)
-            throw new Error("replay machine is not configured");
-        return this.machine.dispatch(event);
-    }
-    recordTransition(decision) {
-        if (decision.transition !== null)
-            this.recordEvent("replay_transitions", decision.transition.sequence);
-    }
-    record(event) {
-        if (this.events.length >= this.scenario.limits.protocol_events) {
-            this.truncated = true;
-            return;
-        }
-        const sequence = this.events.length;
-        this.events.push({ sequence, ...event });
-        this.recordEvent("protocol_events", sequence);
-    }
-}
-export const requestHeaders = (request) => Object.fromEntries(Object.entries(request.headers).flatMap(([name, value]) => value === undefined
-    ? []
-    : [[name, Array.isArray(value) ? value.join(", ") : value]]));
-export const readReplayRequestBody = async (request, limit) => {
-    const chunks = [];
-    let bytes = 0;
-    for await (const chunk of request) {
-        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += value.byteLength;
-        if (bytes > limit)
-            return undefined;
-        chunks.push(value);
-    }
-    return Buffer.concat(chunks).toString("utf8");
-};
-export const recordMachineEvent = (recorder, event, decision) => {
-    recorder.record({
-        ...event,
-        data: recorder.machine?.redact(event.data) ?? event.data,
-        outcome: decision.outcome,
-    });
-    recorder.recordTransition(decision);
-};
-/** Owns replay delays so endpoint shutdown can release every waiting handler. */
-export class ReplayDelayScheduler {
-    #pending = new Map();
-    #closed = false;
-    wait(durationMs) {
-        if (this.#closed)
-            return Promise.resolve();
-        return new Promise((resolveDelay) => {
-            let timer;
-            const finish = () => {
-                this.#pending.delete(timer);
-                resolveDelay();
-            };
-            timer = scheduleProcessDelay(durationMs, finish);
-            this.#pending.set(timer, finish);
-        });
-    }
-    close() {
-        if (this.#closed)
-            return;
-        this.#closed = true;
-        for (const [timer, finish] of this.#pending) {
-            timer.cancel();
-            finish();
-        }
-        this.#pending.clear();
-    }
-}
-export const listenOnLoopback = async (server) => {
-    await new Promise((resolveListen, rejectListen) => {
-        server.once("error", rejectListen);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", rejectListen);
-            resolveListen();
-        });
-    });
-    const address = server.address();
-    if (address === null || typeof address === "string")
-        throw new Error("loopback replay did not acquire a TCP port");
-    return address.port;
-};
-export const closeReplayServer = (server) => new Promise((resolveClose, rejectClose) => {
-    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
-});

package/dist/application/ManagedRuntimeCorrelationService.js

@@ -1,104 +0,0 @@
-import { projectPermissionFailure } from "./PermissionFailure.js";
-import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
-import { createEvidence, parseEvidence, } from "../domain/evidence.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-import { managedRuntimeCorrelationInputSchema, planManagedRuntimeCorrelation, } from "../domain/managedRuntimeCorrelation.js";
-import { err, ok } from "../domain/result.js";
-import { MANAGED_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
-import { digestJson } from "./JavaScriptReplayPlanning.js";
-const OPERATION = "plan_managed_runtime_correlation";
-/** A managed-runtime policy that grants no runtime-correlation authority. */
-export const MANAGED_RUNTIME_DISABLED = {
-    status: "disabled",
-};
-/** Create a separately authorized, non-executing managed runtime plan Evidence. */
-export const planManagedRuntimeCorrelationEvidence = async (dependencies, rawInput) => {
-    const parsed = managedRuntimeCorrelationInputSchema.safeParse(rawInput);
-    if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
-    return planManagedRuntimeCorrelationEvidenceValidated(dependencies, parsed.data);
-};
-/** Plan runtime correlation from input parsed by a trusted adapter. */
-export const planManagedRuntimeCorrelationEvidenceValidated = async (dependencies, input) => {
-    const policy = dependencies.policy();
-    if (policy.status === "disabled")
-        return err(new AnalysisCapabilityUnavailableError(MANAGED_WORKFLOW_PROVIDER.id, OPERATION, "managed runtime correlation is disabled; configure exact roots and runtime executable before enabling it"));
-    if (dependencies.authority === undefined)
-        return err(new AnalysisCapabilityUnavailableError(MANAGED_WORKFLOW_PROVIDER.id, OPERATION, "managed runtime permission policy is not configured"));
-    let staticEvidence, artifactPath;
-    try {
-        staticEvidence = parseEvidence(input.static_members);
-        artifactPath = artifactPathFor(staticEvidence);
-    }
-    catch (cause) {
-        return err(new AnalysisInputError(OPERATION, { cause }));
-    }
-    const authorized = await dependencies.authority.explain({
-        capability: "managed_runtime",
-        roots: [artifactPath],
-        executables: [policy.executablePath],
-        environment_names: [],
-        network: "none",
-        mount: false,
-        operation_identity: operationIdentity(input, staticEvidence),
-    }, "read", { remediation: "restart" });
-    if (!authorized.ok)
-        return err(projectPermissionFailure(authorized.error));
-    try {
-        const result = planManagedRuntimeCorrelation(input, policy.executablePath, authorized.value.grant_id);
-        return ok(createEvidence({
-            path: result.static_observation.artifact_path,
-            sha256: result.static_observation.artifact_sha256,
-            format: "pe",
-        }, MANAGED_WORKFLOW_PROVIDER, {
-            predicateType: "rea.managed-runtime-correlation-plan",
-            operation: OPERATION,
-            parameters: {
-                static_members_evidence_id: staticEvidence.evidence_id,
-                method: jsonValueSchema.parse(input.method),
-                requested_effect: input.requested_effect,
-                host: jsonValueSchema.parse(input.host),
-                bounds: jsonValueSchema.parse(input.bounds),
-            },
-            result: jsonValueSchema.parse(result),
-            rawResult: null,
-            confidence: "derived",
-            authority: "analyst-inference",
-            environment: null,
-            limitations: result.limitations,
-            locations: [
-                {
-                    kind: "artifact-path",
-                    path: result.static_observation.artifact_path,
-                },
-            ],
-            evidenceLinks: result.evidence_links,
-        }));
-    }
-    catch (cause) {
-        return err(cause instanceof TypeError
-            ? new AnalysisInputError(OPERATION, { cause })
-            : new AnalysisProtocolError("Managed runtime correlation planning produced an invalid result", { cause }));
-    }
-};
-const artifactPathFor = (evidence) => {
-    const result = evidence.normalized_result;
-    if (typeof result === "object" &&
-        result !== null &&
-        "artifact" in result &&
-        typeof result.artifact === "object" &&
-        result.artifact !== null &&
-        "path" in result.artifact &&
-        typeof result.artifact.path === "string")
-        return result.artifact.path;
-    throw new AnalysisInputError(OPERATION, {
-        cause: new TypeError("Managed member Evidence does not expose an artifact path"),
-    });
-};
-const operationIdentity = (input, evidence) => `${OPERATION}:${digestJson({
-    evidence_id: evidence.evidence_id,
-    method: input.method,
-    requested_effect: input.requested_effect,
-    host: input.host,
-    bounds: input.bounds,
-})}`;