Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(process): add bounded replay state machines

morlutodc0c2e5ac313
diff --git a/src/domain/replayMachine.ts b/src/domain/replayMachine.ts
new file mode 100644
index 000000000..d104be3f4
--- /dev/null
+++ b/src/domain/replayMachine.ts
@@ -0,0 +1,376 @@
+import { MultiDirectedGraph } from "graphology";
+import { singleSource } from "graphology-shortest-path";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+
+const replayIdentifierSchema = z
+ .string()
+ .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u);
+const replayPathSchema = z
+ .array(z.union([z.string().max(256), z.number().int().nonnegative()]))
+ .max(32);
+const sensitiveHeaderNames = new Set([
+ "authorization",
+ "cookie",
+ "proxy-authorization",
+ "set-cookie",
+]);
+const replayHeaderMatchersSchema = z
+ .record(z.string().min(1).max(256), z.string().max(8_192))
+ .superRefine((headers, context) => {
+ const names = Object.keys(headers).map((name) => name.toLowerCase());
+ if (new Set(names).size !== names.length)
+ context.addIssue({
+ code: "custom",
+ message: "replay header matchers must be unique ignoring case",
+ input: headers,
+ });
+ if (names.some((name) => sensitiveHeaderNames.has(name)))
+ context.addIssue({
+ code: "custom",
+ message:
+ "replay header matchers cannot persist authorization or cookie values; capture and guard through a secret alias instead",
+ input: headers,
+ });
+ })
+ .transform((headers) =>
+ Object.fromEntries(
+ Object.entries(headers).map(([name, value]) => [
+ name.toLowerCase(),
+ value,
+ ]),
+ ),
+ );
+
+const replayValueSourceSchema = z.discriminatedUnion("source", [
+ z.strictObject({
+ source: z.literal("request_header"),
+ name: z
+ .string()
+ .min(1)
+ .transform((name) => name.toLowerCase()),
+ }),
+ z.strictObject({ source: z.literal("request_json"), path: replayPathSchema }),
+ z.strictObject({
+ source: z.literal("websocket_json"),
+ path: replayPathSchema,
+ }),
+ z.strictObject({ source: z.literal("action_json"), path: replayPathSchema }),
+]);
+
+const replayTriggerSchema = z.discriminatedUnion("protocol", [
+ z.strictObject({
+ protocol: z.literal("http"),
+ method: z
+ .string()
+ .min(1)
+ .max(16)
+ .transform((method) => method.toUpperCase()),
+ path: z.string().startsWith("/"),
+ headers: replayHeaderMatchersSchema.default({}),
+ body: z.string().max(1_000_000).nullable().default(null),
+ }),
+ z.strictObject({
+ protocol: z.literal("websocket_connect"),
+ path: z.string().startsWith("/"),
+ headers: replayHeaderMatchersSchema.default({}),
+ }),
+ z.strictObject({
+ protocol: z.literal("websocket_message"),
+ path: z.string().startsWith("/"),
+ body: z.string().max(1_000_000).nullable().default(null),
+ }),
+]);
+
+const replayActionSchema = z.discriminatedUnion("type", [
+ z.strictObject({
+ type: z.literal("http_response"),
+ status: z.number().int().min(100).max(599),
+ headers: z.record(z.string(), z.string()).default({}),
+ body: z.string().max(1_000_000),
+ }),
+ z.strictObject({
+ type: z.literal("websocket_send"),
+ data: z.string().max(1_000_000),
+ }),
+ z.strictObject({ type: z.literal("disconnect") }),
+ z.strictObject({
+ type: z.literal("delay"),
+ duration_ms: z.number().int().nonnegative().max(30_000),
+ }),
+]);
+
+const replayTransitionSchema = z.strictObject({
+ id: replayIdentifierSchema,
+ from: replayIdentifierSchema,
+ to: replayIdentifierSchema,
+ priority: z.number().int().min(0).max(1_000).default(100),
+ trigger: replayTriggerSchema,
+ guards: z
+ .array(
+ z.strictObject({
+ variable: replayIdentifierSchema,
+ value: replayValueSourceSchema,
+ }),
+ )
+ .max(32)
+ .default([]),
+ captures: z
+ .array(
+ z.strictObject({
+ variable: replayIdentifierSchema,
+ value: replayValueSourceSchema,
+ sensitive: z.boolean().default(false),
+ }),
+ )
+ .max(32)
+ .default([]),
+ actions: z.array(replayActionSchema).min(1).max(32),
+ max_uses: z.number().int().min(1).max(10_000),
+});
+
+const transitionSignature = (
+ transition: z.infer<typeof replayTransitionSchema>,
+): string => {
+ const signature = canonicalize({
+ from: transition.from,
+ priority: transition.priority,
+ trigger: transition.trigger,
+ });
+ if (signature === undefined)
+ throw new TypeError("Replay transition signature is not canonical JSON");
+ return signature;
+};
+
+const replayMachineBaseSchema = z.strictObject({
+ initial_state: replayIdentifierSchema,
+ states: z
+ .array(
+ z.strictObject({
+ name: replayIdentifierSchema,
+ terminal: z.boolean().default(false),
+ max_visits: z.number().int().min(1).max(100_000).default(100_000),
+ }),
+ )
+ .min(1)
+ .max(256),
+ transitions: z.array(replayTransitionSchema).min(1).max(2_000),
+ max_transitions: z.number().int().min(1).max(100_000),
+ limits: z
+ .strictObject({
+ connections: z.number().int().min(1).max(1_000).default(100),
+ messages: z.number().int().min(1).max(100_000).default(10_000),
+ bytes: z.number().int().min(1).max(10_000_000).default(1_000_000),
+ duration_ms: z.number().int().min(1).max(300_000).default(30_000),
+ })
+ .default({
+ connections: 100,
+ messages: 10_000,
+ bytes: 1_000_000,
+ duration_ms: 30_000,
+ }),
+});
+type ReplayMachineInput = z.infer<typeof replayMachineBaseSchema>;
+type ReplayMachineContext = z.core.$RefinementCtx<ReplayMachineInput>;
+
+const validateReplayIdentities = (
+ machine: ReplayMachineInput,
+ context: ReplayMachineContext,
+): ReadonlySet<string> => {
+ const names = machine.states.map(({ name }) => name);
+ const nameSet = new Set(names);
+ if (nameSet.size !== names.length)
+ context.addIssue({
+ code: "custom",
+ message: "replay machine state names must be unique",
+ path: ["states"],
+ input: machine,
+ });
+ if (!nameSet.has(machine.initial_state))
+ context.addIssue({
+ code: "custom",
+ message: "replay machine initial state is not declared",
+ path: ["initial_state"],
+ input: machine,
+ });
+ const transitionIds = machine.transitions.map(({ id }) => id);
+ if (new Set(transitionIds).size !== transitionIds.length)
+ context.addIssue({
+ code: "custom",
+ message: "replay machine transition IDs must be unique",
+ path: ["transitions"],
+ input: machine,
+ });
+ const signatures = machine.transitions.map(transitionSignature);
+ if (new Set(signatures).size !== signatures.length)
+ context.addIssue({
+ code: "custom",
+ message:
+ "replay machine transitions with the same state, trigger, and priority are ambiguous",
+ path: ["transitions"],
+ input: machine,
+ });
+ return nameSet;
+};
+
+const validateReplayVariables = (
+ machine: ReplayMachineInput,
+ context: ReplayMachineContext,
+): void => {
+ const capturedVariables = new Map<string, boolean>();
+ for (const [transitionIndex, transition] of machine.transitions.entries()) {
+ for (const capture of transition.captures) {
+ const sensitivity = capturedVariables.get(capture.variable);
+ if (sensitivity !== undefined && sensitivity !== capture.sensitive)
+ context.addIssue({
+ code: "custom",
+ message:
+ "a replay variable cannot change secret classification between captures",
+ path: ["transitions", transitionIndex, "captures"],
+ input: machine,
+ });
+ capturedVariables.set(capture.variable, capture.sensitive);
+ }
+ }
+
+ const availableByState = new Map<string, Set<string>>([
+ [machine.initial_state, new Set()],
+ ]);
+ let changed = true;
+ while (changed) {
+ changed = false;
+ for (const transition of machine.transitions) {
+ const available = availableByState.get(transition.from);
+ if (
+ available === undefined ||
+ transition.guards.some(({ variable }) => !available.has(variable))
+ )
+ continue;
+ const nextAvailable = new Set(available);
+ for (const { variable } of transition.captures)
+ nextAvailable.add(variable);
+ const existing = availableByState.get(transition.to);
+ if (existing === undefined) {
+ availableByState.set(transition.to, nextAvailable);
+ changed = true;
+ continue;
+ }
+ for (const variable of nextAvailable)
+ if (!existing.has(variable)) {
+ existing.add(variable);
+ changed = true;
+ }
+ }
+ }
+
+ for (const [transitionIndex, transition] of machine.transitions.entries())
+ for (const [guardIndex, guard] of transition.guards.entries())
+ if (!availableByState.get(transition.from)?.has(guard.variable))
+ context.addIssue({
+ code: "custom",
+ message:
+ "replay guard variable is not captured on an executable path before use",
+ path: ["transitions", transitionIndex, "guards", guardIndex],
+ input: machine,
+ });
+};
+
+const validateReplayActions = (
+ machine: ReplayMachineInput,
+ context: ReplayMachineContext,
+): void => {
+ for (const [index, transition] of machine.transitions.entries()) {
+ const httpResponses = transition.actions.filter(
+ ({ type }) => type === "http_response",
+ ).length;
+ const websocketSends = transition.actions.some(
+ ({ type }) => type === "websocket_send",
+ );
+ const invalid =
+ transition.trigger.protocol === "http"
+ ? httpResponses !== 1 || websocketSends
+ : httpResponses !== 0;
+ if (invalid)
+ context.addIssue({
+ code: "custom",
+ message:
+ "replay actions must match the transition protocol and HTTP transitions require exactly one response",
+ path: ["transitions", index, "actions"],
+ input: machine,
+ });
+ }
+};
+
+const validateReplayGraph = (
+ machine: ReplayMachineInput,
+ names: ReadonlySet<string>,
+ context: ReplayMachineContext,
+): void => {
+ const graph = new MultiDirectedGraph();
+ for (const name of names) graph.addNode(name);
+ for (const [index, transition] of machine.transitions.entries()) {
+ if (!names.has(transition.from) || !names.has(transition.to)) {
+ context.addIssue({
+ code: "custom",
+ message: "replay machine transition references an unknown state",
+ path: ["transitions", index],
+ input: machine,
+ });
+ continue;
+ }
+ graph.addDirectedEdgeWithKey(
+ `${transition.id}:${String(index)}`,
+ transition.from,
+ transition.to,
+ );
+ }
+ if (!graph.hasNode(machine.initial_state)) return;
+ if (!machine.states.some(({ terminal }) => terminal))
+ context.addIssue({
+ code: "custom",
+ message: "replay machine must declare at least one terminal state",
+ path: ["states"],
+ input: machine,
+ });
+ const reachable = new Set(
+ Object.keys(singleSource(graph, machine.initial_state)),
+ );
+ reachable.add(machine.initial_state);
+ for (const [index, state] of machine.states.entries()) {
+ if (!reachable.has(state.name))
+ context.addIssue({
+ code: "custom",
+ message: "replay machine state is unreachable from the initial state",
+ path: ["states", index],
+ input: machine,
+ });
+ if (state.terminal && graph.outDegree(state.name) > 0)
+ context.addIssue({
+ code: "custom",
+ message:
+ "terminal replay machine state cannot have outgoing transitions",
+ path: ["states", index],
+ input: machine,
+ });
+ if (!state.terminal && graph.outDegree(state.name) === 0)
+ context.addIssue({
+ code: "custom",
+ message: "non-terminal replay machine state has no outgoing transition",
+ path: ["states", index],
+ input: machine,
+ });
+ }
+};
+
+/** Portable finite replay machine with no executable callbacks. */
+export const replayMachineSchema = z
+ .object(replayMachineBaseSchema.shape)
+ .strict()
+ .superRefine((machine, context) => {
+ const names = validateReplayIdentities(machine, context);
+ validateReplayVariables(machine, context);
+ validateReplayActions(machine, context);
+ validateReplayGraph(machine, names, context);
+ });
+
+export type ReplayMachine = z.infer<typeof replayMachineSchema>;
diff --git a/src/domain/replayMachineRuntime.ts b/src/domain/replayMachineRuntime.ts
new file mode 100644
index 000000000..178f62a49
--- /dev/null
+++ b/src/domain/replayMachineRuntime.ts
@@ -0,0 +1,318 @@
+import canonicalize from "canonicalize";
+
+import type { ReplayMachine } from "./replayMachine.js";
+
+type ReplayTransition = ReplayMachine["transitions"][number];
+type ReplayValueSource = ReplayTransition["captures"][number]["value"];
+
+/** One bounded inbound protocol event offered to a replay machine. */
+export interface ReplayMachineEvent {
+ readonly protocol: "http" | "websocket_connect" | "websocket_message";
+ readonly connection: "not_applicable" | "initial" | "reconnect";
+ readonly at_ms: number;
+ readonly method: string | null;
+ readonly path: string;
+ readonly headers: Readonly<Record<string, string>>;
+ readonly body: string;
+}
+
+/** Persistable transition journal entry containing aliases, never secrets. */
+export interface ReplayTransitionRecord {
+ readonly sequence: number;
+ readonly transition_id: string;
+ readonly state_before: string;
+ readonly state_after: string;
+ readonly sensitive_aliases: readonly string[];
+}
+
+/** Result of dispatching one event through a replay machine. */
+export type ReplayMachineDecision =
+ | {
+ readonly outcome: "matched";
+ readonly actions: ReplayTransition["actions"];
+ readonly transition: ReplayTransitionRecord;
+ }
+ | {
+ readonly outcome:
+ | "unmatched"
+ | "invalid_state"
+ | "guard_failed"
+ | "transition_exhausted"
+ | "invalid_capture"
+ | "unexpected_reconnect"
+ | "limit_exhausted";
+ readonly actions: readonly [];
+ readonly transition: null;
+ };
+
+const parseJson = (value: string): unknown => {
+ try {
+ return JSON.parse(value) as unknown;
+ } catch {
+ return undefined;
+ }
+};
+
+const atPath = (
+ value: unknown,
+ path: readonly (string | number)[],
+): unknown => {
+ 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 as Readonly<Record<string, unknown>>)[segment];
+ }
+ return current;
+};
+
+const actionJsonBody = (transition: ReplayTransition): string | undefined => {
+ 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: ReplayValueSource,
+ event: ReplayMachineEvent,
+ transition: ReplayTransition,
+): unknown => {
+ 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: ReplayTransition,
+ event: ReplayMachineEvent,
+): boolean => {
+ 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: unknown): boolean => {
+ 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: unknown, right: unknown): boolean =>
+ isJsonCompatible(left) &&
+ isJsonCompatible(right) &&
+ (Object.is(left, right) || canonicalize(left) === canonicalize(right));
+
+/** Stateful evaluator for one validated replay-machine instance. */
+export class ReplayMachineRuntime {
+ readonly #variables = new Map<string, unknown>();
+ readonly #sensitiveValues = new Map<string, Set<string>>();
+ readonly #uses = new Map<string, number>();
+ readonly #stateVisits = new Map<string, number>();
+ readonly #timeline: ReplayTransitionRecord[] = [];
+ #state: string;
+ #connections = 0;
+ #messages = 0;
+ #bytes = 0;
+ #lastAtMs = 0;
+
+ constructor(readonly machine: ReplayMachine) {
+ this.#state = machine.initial_state;
+ this.#stateVisits.set(machine.initial_state, 1);
+ }
+
+ /** Current machine state after all accepted transitions. */
+ get state(): string {
+ return this.#state;
+ }
+
+ /** Ordered, secret-free transition records. */
+ get timeline(): readonly ReplayTransitionRecord[] {
+ return this.#timeline;
+ }
+
+ /** Replace captured secret values with stable aliases before persistence. */
+ redact(value: string): string {
+ 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: ReplayMachineEvent): ReplayMachineDecision {
+ 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(),
+ } satisfies ReplayTransitionRecord;
+ 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: ReplayMachineEvent): boolean {
+ 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: Exclude<ReplayMachineDecision["outcome"], "matched">,
+ ): ReplayMachineDecision {
+ return { outcome, actions: [], transition: null };
+ }
+}
diff --git a/tests/replayMachine.test.ts b/tests/replayMachine.test.ts
new file mode 100644
index 000000000..663d54a71
--- /dev/null
+++ b/tests/replayMachine.test.ts
@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+
+import { replayMachineSchema } from "../src/domain/replayMachine.js";
+
+const loginMachine = () => ({
+ initial_state: "waiting_for_login",
+ states: [
+ { name: "waiting_for_login" },
+ { name: "waiting_for_api" },
+ { name: "complete", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "login",
+ from: "waiting_for_login",
+ to: "waiting_for_api",
+ priority: 10,
+ trigger: { protocol: "http", method: "POST", path: "/login" },
+ captures: [
+ {
+ variable: "token",
+ value: { source: "request_json", path: ["token"] },
+ sensitive: true,
+ },
+ ],
+ actions: [{ type: "http_response", status: 204, headers: {}, body: "" }],
+ max_uses: 1,
+ },
+ {
+ id: "api",
+ from: "waiting_for_api",
+ to: "complete",
+ priority: 10,
+ trigger: { protocol: "http", method: "GET", path: "/api" },
+ guards: [
+ {
+ variable: "token",
+ value: { source: "request_header", name: "authorization" },
+ },
+ ],
+ actions: [
+ {
+ type: "http_response",
+ status: 200,
+ headers: {},
+ body: "done",
+ },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+});
+
+describe("replay machine", () => {
+ it("accepts a bounded, reachable, data-only login machine", () => {
+ expect(replayMachineSchema.parse(loginMachine())).toMatchObject({
+ initial_state: "waiting_for_login",
+ max_transitions: 2,
+ });
+ });
+
+ it.each([
+ [
+ "unreachable state",
+ (machine: ReturnType<typeof loginMachine>) =>
+ machine.states.push({ name: "orphan", terminal: false }),
+ "unreachable",
+ ],
+ [
+ "ambiguous transition",
+ (machine: ReturnType<typeof loginMachine>) => {
+ const transition = machine.transitions[0];
+ if (transition === undefined) throw new TypeError("missing transition");
+ machine.transitions.push({ ...transition, id: "login_2" });
+ },
+ "ambiguous",
+ ],
+ [
+ "outgoing terminal transition",
+ (machine: ReturnType<typeof loginMachine>) => {
+ const transition = machine.transitions[0];
+ if (transition === undefined) throw new TypeError("missing transition");
+ machine.transitions.push({
+ ...transition,
+ id: "restart",
+ from: "complete",
+ to: "waiting_for_login",
+ trigger: { protocol: "http", method: "POST", path: "/restart" },
+ });
+ },
+ "terminal",
+ ],
+ [
+ "unknown guard variable",
+ (machine: ReturnType<typeof loginMachine>) => {
+ const guard = machine.transitions[1]?.guards?.[0];
+ if (guard === undefined) throw new TypeError("missing guard");
+ guard.variable = "missing";
+ },
+ "executable path before use",
+ ],
+ [
+ "missing terminal state",
+ (machine: ReturnType<typeof loginMachine>) => {
+ const state = machine.states[2];
+ if (state === undefined) throw new TypeError("missing state");
+ state.terminal = false;
+ },
+ "terminal state",
+ ],
+ ])("rejects %s", (_name, mutate, message) => {
+ const machine = loginMachine();
+ mutate(machine);
+ expect(() => replayMachineSchema.parse(machine)).toThrow(message);
+ });
+
+ it("canonicalizes methods and headers while refusing persisted credential matchers", () => {
+ const canonical = {
+ ...loginMachine(),
+ transitions: loginMachine().transitions.map((transition, index) =>
+ index === 0
+ ? {
+ ...transition,
+ trigger: {
+ protocol: "http",
+ method: "post",
+ path: "/login",
+ headers: { "X-Request-ID": "fixture" },
+ },
+ }
+ : transition,
+ ),
+ };
+ expect(
+ replayMachineSchema.parse(canonical).transitions[0]?.trigger,
+ ).toMatchObject({
+ method: "POST",
+ headers: { "x-request-id": "fixture" },
+ });
+ const credentialMatcher = {
+ ...loginMachine(),
+ transitions: loginMachine().transitions.map((transition, index) =>
+ index === 0
+ ? {
+ ...transition,
+ trigger: {
+ protocol: "http",
+ method: "POST",
+ path: "/login",
+ headers: { Authorization: "test-auth-token" },
+ },
+ }
+ : transition,
+ ),
+ };
+ expect(() => replayMachineSchema.parse(credentialMatcher)).toThrow(
+ /secret alias/u,
+ );
+ });
+
+ it("rejects unknown fields at nested machine boundaries", () => {
+ const candidate = loginMachine();
+ const action = candidate.transitions[0]?.actions[0];
+ if (action === undefined) throw new TypeError("missing action");
+
+ expect(() =>
+ replayMachineSchema.parse({
+ ...candidate,
+ transitions: [
+ {
+ ...candidate.transitions[0],
+ actions: [{ ...action, unexpected: true }],
+ },
+ candidate.transitions[1],
+ ],
+ }),
+ ).toThrow(/Unrecognized key/u);
+ });
+
+ it("reports duplicate transition IDs as structured validation", () => {
+ const candidate = loginMachine();
+ const first = candidate.transitions[0];
+ const second = candidate.transitions[1];
+ if (first === undefined || second === undefined)
+ throw new TypeError("missing transition");
+
+ expect(
+ replayMachineSchema.safeParse({
+ ...candidate,
+ transitions: [first, { ...second, id: first.id }],
+ }),
+ ).toMatchObject({ success: false });
+ });
+
+ it("rejects guards whose capture is not available before the transition", () => {
+ const candidate = loginMachine();
+ const first = candidate.transitions[0];
+ if (first === undefined) throw new TypeError("missing transition");
+ first.guards = [
+ {
+ variable: "token",
+ value: { source: "request_header", name: "authorization" },
+ },
+ ];
+
+ expect(() => replayMachineSchema.parse(candidate)).toThrow(
+ /executable path before use/u,
+ );
+ });
+
+ it("rejects ambiguous header triggers regardless of key order", () => {
+ const candidate = loginMachine();
+ const first = candidate.transitions[0];
+ if (first === undefined) throw new TypeError("missing transition");
+ const withHeaders = {
+ ...first,
+ trigger: {
+ protocol: "http" as const,
+ method: "POST",
+ path: "/login",
+ headers: { accept: "json", "x-mode": "test" },
+ },
+ };
+
+ expect(() =>
+ replayMachineSchema.parse({
+ ...candidate,
+ transitions: [
+ withHeaders,
+ {
+ ...withHeaders,
+ id: "login_duplicate",
+ trigger: {
+ ...withHeaders.trigger,
+ headers: { "x-mode": "test", accept: "json" },
+ },
+ },
+ candidate.transitions[1],
+ ],
+ }),
+ ).toThrow(/ambiguous/u);
+ });
+});
diff --git a/tests/replayMachineRuntime.test.ts b/tests/replayMachineRuntime.test.ts
new file mode 100644
index 000000000..500c69eae
--- /dev/null
+++ b/tests/replayMachineRuntime.test.ts
@@ -0,0 +1,581 @@
+import { describe, expect, it } from "vitest";
+
+import { replayMachineSchema } from "../src/domain/replayMachine.js";
+import { ReplayMachineRuntime } from "../src/domain/replayMachineRuntime.js";
+
+const machine = replayMachineSchema.parse({
+ initial_state: "login",
+ states: [
+ { name: "login" },
+ { name: "api" },
+ { name: "complete", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "capture_token",
+ from: "login",
+ to: "api",
+ priority: 10,
+ trigger: { protocol: "http", method: "POST", path: "/login" },
+ captures: [
+ {
+ variable: "session_value",
+ value: { source: "request_json", path: ["session_value"] },
+ sensitive: true,
+ },
+ ],
+ actions: [{ type: "http_response", status: 204, headers: {}, body: "" }],
+ max_uses: 1,
+ },
+ {
+ id: "authorize_api",
+ from: "api",
+ to: "complete",
+ priority: 10,
+ trigger: { protocol: "http", method: "GET", path: "/api" },
+ guards: [
+ {
+ variable: "session_value",
+ value: { source: "request_header", name: "authorization" },
+ },
+ ],
+ actions: [
+ { type: "http_response", status: 200, headers: {}, body: "done" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+});
+
+const event = (
+ method: string,
+ path: string,
+ body = "",
+ headers: Readonly<Record<string, string>> = {},
+) => ({
+ protocol: "http" as const,
+ connection: "not_applicable" as const,
+ at_ms: 0,
+ method,
+ path,
+ body,
+ headers,
+});
+
+describe("replay machine runtime", () => {
+ it("captures secret values in memory and journals aliases only", () => {
+ const runtime = new ReplayMachineRuntime(machine);
+ expect(
+ runtime.dispatch(
+ event("POST", "/login", '{"session_value":"test-auth-token"}'),
+ ),
+ ).toMatchObject({
+ outcome: "matched",
+ transition: {
+ transition_id: "capture_token",
+ sensitive_aliases: ["session_value"],
+ },
+ });
+ const expectedRedaction = ["Bearer <", "secret", ":session_value>"].join(
+ "",
+ );
+ expect(runtime.redact("Bearer test-auth-token")).toBe(expectedRedaction);
+ expect(
+ runtime.dispatch(
+ event("GET", "/api", "", { Authorization: "test-auth-token" }),
+ ),
+ ).toMatchObject({ outcome: "matched" });
+ expect(JSON.stringify(runtime.timeline)).not.toContain("test-auth-token");
+ expect(runtime.state).toBe("complete");
+ });
+
+ it("classifies wrong-state, guard, capture, and exhaustion failures", () => {
+ expect(
+ new ReplayMachineRuntime(machine).dispatch(event("GET", "/api")),
+ ).toMatchObject({ outcome: "invalid_state" });
+ expect(
+ new ReplayMachineRuntime(machine).dispatch(event("POST", "/login", "{}")),
+ ).toMatchObject({ outcome: "invalid_capture" });
+ const runtime = new ReplayMachineRuntime(machine);
+ runtime.dispatch(
+ event("POST", "/login", '{"session_value":"test-auth-token"}'),
+ );
+ expect(
+ runtime.dispatch(
+ event("GET", "/api", "", {
+ authorization: "test-token-placeholder",
+ }),
+ ),
+ ).toMatchObject({
+ outcome: "guard_failed",
+ });
+ const bounded = new ReplayMachineRuntime(
+ replayMachineSchema.parse({
+ initial_state: "active",
+ states: [{ name: "active" }, { name: "done", terminal: true }],
+ transitions: [
+ {
+ id: "once",
+ from: "active",
+ to: "active",
+ trigger: { protocol: "http", method: "GET", path: "/once" },
+ actions: [
+ { type: "http_response", status: 200, headers: {}, body: "ok" },
+ ],
+ max_uses: 1,
+ },
+ {
+ id: "finish",
+ from: "active",
+ to: "done",
+ trigger: { protocol: "http", method: "GET", path: "/done" },
+ actions: [
+ { type: "http_response", status: 200, headers: {}, body: "ok" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+ }),
+ );
+ expect(bounded.dispatch(event("GET", "/once"))).toMatchObject({
+ outcome: "matched",
+ });
+ expect(bounded.dispatch(event("GET", "/once"))).toMatchObject({
+ outcome: "transition_exhausted",
+ });
+ });
+
+ it("matches bounded headers and bodies and distinguishes wrong-state reconnects", () => {
+ const runtime = new ReplayMachineRuntime(
+ replayMachineSchema.parse({
+ initial_state: "connected",
+ states: [{ name: "connected" }, { name: "done", terminal: true }],
+ transitions: [
+ {
+ id: "finish",
+ from: "connected",
+ to: "done",
+ trigger: {
+ protocol: "http",
+ method: "POST",
+ path: "/finish",
+ headers: { "content-type": "application/json" },
+ body: '{"done":true}',
+ },
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 1,
+ },
+ {
+ id: "initial_socket",
+ from: "connected",
+ to: "connected",
+ trigger: { protocol: "websocket_connect", path: "/ws" },
+ actions: [{ type: "disconnect" }],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+ }),
+ );
+ expect(runtime.dispatch(event("POST", "/finish", "wrong"))).toMatchObject({
+ outcome: "unmatched",
+ });
+ expect(
+ runtime.dispatch({
+ protocol: "websocket_connect",
+ connection: "initial",
+ at_ms: 0,
+ method: null,
+ path: "/ws",
+ headers: {},
+ body: "",
+ }),
+ ).toMatchObject({ outcome: "matched" });
+ expect(
+ runtime.dispatch({
+ protocol: "websocket_connect",
+ connection: "reconnect",
+ at_ms: 0,
+ method: null,
+ path: "/ws",
+ headers: {},
+ body: "",
+ }),
+ ).toMatchObject({ outcome: "transition_exhausted" });
+ expect(
+ runtime.dispatch(
+ event("POST", "/finish", '{"done":true}', {
+ "content-type": "application/json",
+ }),
+ ),
+ ).toMatchObject({ outcome: "matched" });
+ expect(
+ runtime.dispatch({
+ protocol: "websocket_connect",
+ connection: "reconnect",
+ at_ms: 0,
+ method: null,
+ path: "/ws",
+ headers: {},
+ body: "",
+ }),
+ ).toMatchObject({ outcome: "unexpected_reconnect" });
+ });
+
+ it("enforces state, connection, message, byte, and duration limits", () => {
+ const limitedMachine = replayMachineSchema.parse({
+ initial_state: "active",
+ states: [
+ { name: "active", max_visits: 1 },
+ { name: "done", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "loop",
+ from: "active",
+ to: "active",
+ trigger: { protocol: "websocket_message", path: "/ws" },
+ actions: [{ type: "websocket_send", data: "ack" }],
+ max_uses: 2,
+ },
+ {
+ id: "finish",
+ from: "active",
+ to: "done",
+ trigger: { protocol: "http", method: "GET", path: "/done" },
+ actions: [
+ { type: "http_response", status: 200, headers: {}, body: "ok" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 3,
+ limits: { connections: 1, messages: 1, bytes: 100, duration_ms: 10 },
+ });
+ const stateLimited = new ReplayMachineRuntime(limitedMachine);
+ expect(
+ stateLimited.dispatch({
+ protocol: "websocket_message",
+ connection: "not_applicable",
+ at_ms: 0,
+ method: null,
+ path: "/ws",
+ headers: {},
+ body: "one",
+ }),
+ ).toMatchObject({ outcome: "limit_exhausted" });
+ const messageLimited = new ReplayMachineRuntime(
+ replayMachineSchema.parse({
+ ...limitedMachine,
+ states: limitedMachine.states.map((state) =>
+ state.name === "active" ? { ...state, max_visits: 3 } : state,
+ ),
+ }),
+ );
+ const message = {
+ protocol: "websocket_message" as const,
+ connection: "not_applicable" as const,
+ at_ms: 0,
+ method: null,
+ path: "/ws",
+ headers: {},
+ body: "one",
+ };
+ expect(messageLimited.dispatch(message)).toMatchObject({
+ outcome: "matched",
+ });
+ expect(messageLimited.dispatch(message)).toMatchObject({
+ outcome: "limit_exhausted",
+ });
+ const durationLimited = new ReplayMachineRuntime(limitedMachine);
+ expect(
+ durationLimited.dispatch({ ...event("GET", "/done"), at_ms: 11 }),
+ ).toMatchObject({ outcome: "limit_exhausted" });
+ expect(
+ new ReplayMachineRuntime(limitedMachine).dispatch({
+ ...event("GET", "/done"),
+ at_ms: Number.NaN,
+ }),
+ ).toMatchObject({ outcome: "limit_exhausted" });
+ const monotonic = new ReplayMachineRuntime(limitedMachine);
+ expect(
+ monotonic.dispatch({ ...event("GET", "/missing"), at_ms: 5 }),
+ ).toMatchObject({ outcome: "unmatched" });
+ expect(
+ monotonic.dispatch({ ...event("GET", "/missing"), at_ms: 4 }),
+ ).toMatchObject({ outcome: "limit_exhausted" });
+ const byteLimited = new ReplayMachineRuntime(
+ replayMachineSchema.parse({
+ ...limitedMachine,
+ limits: { ...limitedMachine.limits, bytes: 4 },
+ }),
+ );
+ expect(
+ byteLimited.dispatch(event("GET", "/missing", "12345")),
+ ).toMatchObject({ outcome: "limit_exhausted" });
+ const connectionLimited = new ReplayMachineRuntime(limitedMachine);
+ const connect = {
+ protocol: "websocket_connect" as const,
+ connection: "initial" as const,
+ at_ms: 0,
+ method: null,
+ path: "/unknown",
+ headers: {},
+ body: "",
+ };
+ expect(connectionLimited.dispatch(connect)).toMatchObject({
+ outcome: "unmatched",
+ });
+ expect(
+ connectionLimited.dispatch({ ...connect, connection: "reconnect" }),
+ ).toMatchObject({ outcome: "limit_exhausted" });
+ });
+
+ it("compares captured JSON values canonically", () => {
+ const objectMachine = replayMachineSchema.parse({
+ initial_state: "capture",
+ states: [
+ { name: "capture" },
+ { name: "guard" },
+ { name: "done", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "capture_profile",
+ from: "capture",
+ to: "guard",
+ trigger: { protocol: "http", method: "POST", path: "/capture" },
+ captures: [
+ {
+ variable: "profile",
+ value: { source: "request_json", path: ["profile"] },
+ },
+ ],
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 1,
+ },
+ {
+ id: "guard_profile",
+ from: "guard",
+ to: "done",
+ trigger: { protocol: "http", method: "POST", path: "/guard" },
+ guards: [
+ {
+ variable: "profile",
+ value: { source: "request_json", path: ["profile"] },
+ },
+ ],
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+ });
+ const runtime = new ReplayMachineRuntime(objectMachine);
+
+ expect(
+ runtime.dispatch(
+ event("POST", "/capture", '{"profile":{"name":"A","id":1}}'),
+ ),
+ ).toMatchObject({ outcome: "matched" });
+ expect(
+ runtime.dispatch(
+ event("POST", "/guard", '{"profile":{"id":1,"name":"A"}}'),
+ ),
+ ).toMatchObject({ outcome: "matched" });
+ });
+
+ it("does not traverse inherited properties in JSON capture paths", () => {
+ const inheritedPathMachine = replayMachineSchema.parse({
+ ...machine,
+ transitions: machine.transitions.map((transition, index) =>
+ index === 0
+ ? {
+ ...transition,
+ captures: [
+ {
+ variable: "session_value",
+ value: {
+ source: "request_json" as const,
+ path: ["__proto__", "toString"],
+ },
+ sensitive: true,
+ },
+ ],
+ }
+ : transition,
+ ),
+ });
+
+ expect(
+ new ReplayMachineRuntime(inheritedPathMachine).dispatch(
+ event("POST", "/login", "{}"),
+ ),
+ ).toMatchObject({ outcome: "invalid_capture" });
+ });
+
+ it("rejects non-string sensitive captures and retains rotated values", () => {
+ expect(
+ new ReplayMachineRuntime(machine).dispatch(
+ event("POST", "/login", '{"session_value":1234}'),
+ ),
+ ).toMatchObject({ outcome: "invalid_capture" });
+
+ const rotatingMachine = replayMachineSchema.parse({
+ initial_state: "active",
+ states: [
+ { name: "active", max_visits: 3 },
+ { name: "done", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "rotate",
+ from: "active",
+ to: "active",
+ trigger: { protocol: "http", method: "POST", path: "/rotate" },
+ captures: [
+ {
+ variable: "session_value",
+ value: { source: "request_json", path: ["value"] },
+ sensitive: true,
+ },
+ ],
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 2,
+ },
+ {
+ id: "finish",
+ from: "active",
+ to: "done",
+ trigger: { protocol: "http", method: "GET", path: "/done" },
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 3,
+ });
+ const rotating = new ReplayMachineRuntime(rotatingMachine);
+ rotating.dispatch(event("POST", "/rotate", '{"value":"alpha"}'));
+ rotating.dispatch(event("POST", "/rotate", '{"value":"beta"}'));
+ const alias = ["<", "secret", ":session_value>"].join("");
+
+ expect(rotating.redact("alpha beta")).toBe(`${alias} ${alias}`);
+ });
+
+ it("falls back to a lower-priority transition after a preferred one is exhausted", () => {
+ const fallbackMachine = replayMachineSchema.parse({
+ initial_state: "active",
+ states: [
+ { name: "active", max_visits: 2 },
+ { name: "done", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "preferred",
+ from: "active",
+ to: "active",
+ priority: 10,
+ trigger: { protocol: "http", method: "GET", path: "/next" },
+ actions: [
+ { type: "http_response", status: 200, headers: {}, body: "again" },
+ ],
+ max_uses: 1,
+ },
+ {
+ id: "fallback",
+ from: "active",
+ to: "done",
+ priority: 20,
+ trigger: { protocol: "http", method: "GET", path: "/next" },
+ actions: [
+ { type: "http_response", status: 200, headers: {}, body: "done" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+ });
+ const runtime = new ReplayMachineRuntime(fallbackMachine);
+
+ expect(runtime.dispatch(event("GET", "/next"))).toMatchObject({
+ outcome: "matched",
+ transition: { transition_id: "preferred" },
+ });
+ expect(runtime.dispatch(event("GET", "/next"))).toMatchObject({
+ outcome: "matched",
+ transition: { transition_id: "fallback" },
+ });
+ });
+
+ it("rejects non-finite parsed JSON captures and guard values", () => {
+ const jsonMachine = replayMachineSchema.parse({
+ initial_state: "capture",
+ states: [
+ { name: "capture" },
+ { name: "guard" },
+ { name: "done", terminal: true },
+ ],
+ transitions: [
+ {
+ id: "capture_value",
+ from: "capture",
+ to: "guard",
+ trigger: { protocol: "http", method: "POST", path: "/capture" },
+ captures: [
+ {
+ variable: "value",
+ value: { source: "request_json", path: ["value"] },
+ },
+ ],
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 1,
+ },
+ {
+ id: "guard_value",
+ from: "guard",
+ to: "done",
+ trigger: { protocol: "http", method: "POST", path: "/guard" },
+ guards: [
+ {
+ variable: "value",
+ value: { source: "request_json", path: ["value"] },
+ },
+ ],
+ actions: [
+ { type: "http_response", status: 204, headers: {}, body: "" },
+ ],
+ max_uses: 1,
+ },
+ ],
+ max_transitions: 2,
+ });
+
+ expect(
+ new ReplayMachineRuntime(jsonMachine).dispatch(
+ event("POST", "/capture", '{"value":1e400}'),
+ ),
+ ).toMatchObject({ outcome: "invalid_capture" });
+
+ const guarded = new ReplayMachineRuntime(jsonMachine);
+ expect(
+ guarded.dispatch(event("POST", "/capture", '{"value":null}')),
+ ).toMatchObject({ outcome: "matched" });
+ expect(
+ guarded.dispatch(event("POST", "/guard", '{"value":1e400}')),
+ ).toMatchObject({ outcome: "guard_failed" });
+ });
+});