Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(cutter): attribute status proof failures to command

morluto5c0472c571cd
diff --git a/docs/reverse-engineering-tools.md b/docs/reverse-engineering-tools.md
index 3373526c9..bb5df5ef3 100644
--- a/docs/reverse-engineering-tools.md
+++ b/docs/reverse-engineering-tools.md
@@ -73,7 +73,9 @@ invocation. A signed status response also confirms completion of older bridge
connections after its UI dispatch, preserving recovery proof for a caller whose
receipt another caller has acknowledged. Neither receipt recovery nor a status
probe retries the original command. Failed acknowledgements remain pending and
-block new commands until they can be retried successfully.
+block new commands until they can be retried successfully. Status proof failures
+identify `cutter_command` and retain `status` in
+`details.diagnostics.auxiliary_operation`; malformed proof still blocks dispatch.
## Configuration and coverage
diff --git a/src/cutter/CutterBridgeClient.ts b/src/cutter/CutterBridgeClient.ts
index dc821745d..8ca252510 100644
--- a/src/cutter/CutterBridgeClient.ts
+++ b/src/cutter/CutterBridgeClient.ts
@@ -530,52 +530,34 @@ export class CutterBridgeClient {
);
}
try {
- const raw = await this.#request(
- descriptor,
- serializeRequest(descriptor, {
- kind: "status",
- session_id: sessionId,
- }),
- );
- const parsed = responseSchema.safeParse(raw);
- if (
- !parsed.success ||
- !parsed.data.ok ||
- parsed.data.session_id !== sessionId
- )
- return err(
- new AnalysisOutputError(
- "cutter_command_status",
- "The bridge status response did not contain a valid session identity.",
- { cause: parsed.success ? undefined : parsed.error },
- ),
- );
- const completed = (parsed.data.completed_commands ?? []).some(
+ const status = await this.#readCommandStatus(descriptor);
+ const completed = (status.completed_commands ?? []).some(
(receipt) => receipt.request_id === requestId,
);
if (completed) await this.#acknowledgeCompletion(descriptor, requestId);
return ok(
completed ||
(completionToken !== undefined &&
- parsed.data.completed_connection !== undefined &&
- parsed.data.completed_connection >= completionToken),
+ status.completed_connection !== undefined &&
+ status.completed_connection >= completionToken),
);
} catch (cause) {
+ if (cause instanceof AnalysisError) return err(cause);
return err(
new AnalysisCapabilityUnavailableError(
"cutter",
- "cutter_command_status",
+ "cutter_command",
cause instanceof Error ? cause.message : "Cutter status failed",
- { cause },
+ { cause, diagnostics: { auxiliary_operation: "status" } },
),
);
}
}
- async #recoverCompletedCommands(
+ async #readCommandStatus(
descriptor: z.infer<typeof descriptorSchema>,
signal?: AbortSignal,
- ): Promise<void> {
+ ): Promise<z.infer<typeof responseSchema>> {
const raw = await this.#request(
descriptor,
serializeRequest(descriptor, {
@@ -591,18 +573,30 @@ export class CutterBridgeClient {
status.data.session_id !== descriptor.session_id
)
throw new AnalysisOutputError(
- "cutter_command_status",
+ "cutter_command",
"The bridge status response did not contain a valid session identity.",
- { cause: status.success ? undefined : status.error },
+ {
+ cause: status.success ? undefined : status.error,
+ diagnostics: { auxiliary_operation: "status" },
+ },
);
- if (status.data.completed_connection === undefined)
+ return status.data;
+ }
+
+ async #recoverCompletedCommands(
+ descriptor: z.infer<typeof descriptorSchema>,
+ signal?: AbortSignal,
+ ): Promise<void> {
+ const status = await this.#readCommandStatus(descriptor, signal);
+ if (status.completed_connection === undefined)
throw new AnalysisOutputError(
- "cutter_command_status",
+ "cutter_command",
"The bridge did not provide authenticated proof that earlier connections reached a terminal state.",
+ { diagnostics: { auxiliary_operation: "status" } },
);
const pending =
this.#pendingAcknowledgements.get(descriptor.session_id) ?? new Set();
- for (const receipt of status.data.completed_commands ?? [])
+ for (const receipt of status.completed_commands ?? [])
pending.add(receipt.request_id);
if (pending.size > 0)
this.#pendingAcknowledgements.set(descriptor.session_id, pending);
diff --git a/tests/boundary/cli/cutterStatusAttributionCli.test.ts b/tests/boundary/cli/cutterStatusAttributionCli.test.ts
new file mode 100644
index 000000000..c88685864
--- /dev/null
+++ b/tests/boundary/cli/cutterStatusAttributionCli.test.ts
@@ -0,0 +1,121 @@
+import { expect } from "vitest";
+import { chmod } from "node:fs/promises";
+import { workspaceCliTest } from "../../support/cli/workspaceCliFixture.js";
+import {
+ authenticatedServer,
+ writeDescriptor,
+} from "../../fixtures/cutterBridgeProtocol.js";
+
+const sessionId = "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a";
+workspaceCliTest.for([
+ "missing-watermark",
+ "invalid-identity",
+ "valid",
+] as const)(
+ "retains caller operation and preflight proof through the CLI: %s",
+ async (mode, { cli, workspace }) => {
+ const directory = await workspace.mkdir("bridge");
+ if (process.platform !== "win32") await chmod(directory, 0o700);
+ const token = "synthetic-cutter-status-test-token";
+ const calls: string[] = [];
+ let phase = "discovery";
+ const bridge = authenticatedServer(
+ token,
+ sessionId,
+ (request, respond) => {
+ calls.push(`${phase}:${String(request.kind)}`);
+ if (request.kind === "ack") {
+ respond({ ok: true, acknowledged: true });
+ return;
+ }
+ if (request.kind === "status") {
+ respond({
+ ok: true,
+ session_id:
+ mode === "invalid-identity" && phase === "command"
+ ? "00000000-0000-4000-8000-000000000001"
+ : sessionId,
+ current_file: null,
+ document_generation: 0,
+ cutter_version: "Cutter fixture",
+ identity_status: "partial",
+ completed_commands: [],
+ ...(mode === "missing-watermark"
+ ? {}
+ : { completed_connection: "0000000000000000" }),
+ });
+ return;
+ }
+ expect(request.kind).toBe("command");
+ expect(request.command).toBe("ij");
+ respond({
+ ok: true,
+ session_id: sessionId,
+ output: "fixture output",
+ document_generation: 0,
+ current_file: null,
+ execution_state: "complete",
+ output_truncated: false,
+ });
+ },
+ true,
+ );
+ await new Promise<void>((resolve) =>
+ bridge.listen(0, "127.0.0.1", resolve),
+ );
+ try {
+ const address = bridge.address();
+ if (address === null || typeof address === "string")
+ throw new Error("Missing bridge address");
+ await writeDescriptor(directory, sessionId, address.port, token);
+ const environment = {
+ ...workspace.environment,
+ REA_CUTTER_BRIDGE_DIR: directory,
+ REA_LOG_LEVEL: "silent",
+ };
+ const discovery = await cli.run({
+ arguments: ["list-cutter-sessions", "--json"],
+ environment,
+ });
+ expect(discovery.exitCode).toBe(0);
+ expect(discovery.json).toMatchObject({
+ discovery_status: "sessions_found",
+ sessions: [{ session_id: sessionId }],
+ });
+ phase = "command";
+ const result = await cli.run({
+ arguments: ["cutter-command", sessionId, "0", "ij", "--json"],
+ environment,
+ });
+ expect(result.stderr).toBe("");
+ if (mode === "valid") {
+ expect(result.exitCode).toBe(0);
+ expect(result.json).toMatchObject({
+ operation: "cutter_command",
+ normalized_result: {
+ output: "fixture output",
+ execution_state: "complete",
+ },
+ });
+ expect(calls).toContain("command:command");
+ expect(calls).toContain("command:ack");
+ } else {
+ expect(result.exitCode).toBe(1);
+ expect(result.json).toMatchObject({
+ code: "unreadable_output",
+ details: {
+ operation: "cutter_command",
+ reason:
+ mode === "missing-watermark"
+ ? "The bridge did not provide authenticated proof that earlier connections reached a terminal state."
+ : "The bridge status response did not contain a valid session identity.",
+ diagnostics: { auxiliary_operation: "status" },
+ },
+ });
+ expect(calls).toEqual(["discovery:status", "command:status"]);
+ }
+ } finally {
+ await new Promise<void>((resolve) => bridge.close(() => resolve()));
+ }
+ },
+);
diff --git a/tests/boundary/providers/CutterBridgeClient.test.ts b/tests/boundary/providers/CutterBridgeClient.test.ts
index a4e52087c..4a77cf6fc 100644
--- a/tests/boundary/providers/CutterBridgeClient.test.ts
+++ b/tests/boundary/providers/CutterBridgeClient.test.ts
@@ -1,5 +1,8 @@
+import {
+ authenticatedServer,
+ writeDescriptor,
+} from "../../fixtures/cutterBridgeProtocol.js";
import { createServer } from "node:net";
-import { createHmac } from "node:crypto";
import { readFileSync } from "node:fs";
import {
chmod,
@@ -28,112 +31,6 @@ const listen = async (
return address.port;
};
-const authenticatedServer = (
- token: string,
- sessionId: string,
- onRequest: (
- request: Record<string, unknown>,
- respond: (
- value: unknown,
- options?: { raw?: boolean; fragment?: boolean; chunkBytes?: number },
- ) => void,
- connection: import("node:net").Socket,
- ) => void,
- handleStatusRequests = false,
-): ReturnType<typeof createServer> => {
- let nextConnectionOrdinal = 0;
- return createServer((connection) => {
- const connectionOrdinal = ++nextConnectionOrdinal;
- connection.setEncoding("utf8");
- let input = "";
- let clientNonce = "";
- let serverNonce = "";
- connection.on("data", (chunk: string) => {
- input += chunk;
- for (;;) {
- const end = input.indexOf("\n");
- if (end < 0) return;
- const frame = JSON.parse(input.slice(0, end)) as Record<
- string,
- unknown
- >;
- input = input.slice(end + 1);
- if (frame.kind === "rea-auth-v2") {
- clientNonce = String(frame.nonce);
- serverNonce = `${connectionOrdinal.toString(16).padStart(16, "0")}${"e".repeat(48)}`;
- const proof = createHmac("sha256", token)
- .update(
- `rea-cutter-server-v2:${sessionId}:${clientNonce}:${serverNonce}`,
- )
- .digest("hex");
- connection.write(
- `${JSON.stringify({ session_id: sessionId, nonce: serverNonce, proof })}\n`,
- );
- continue;
- }
- const requestBytes = String(frame.request);
- const expected = createHmac("sha256", token)
- .update(
- `rea-cutter-client-v2:${sessionId}:${clientNonce}:${serverNonce}:${requestBytes}`,
- )
- .digest("hex");
- if (frame.proof !== expected) {
- connection.destroy();
- return;
- }
- const respond = (
- value: unknown,
- options: {
- raw?: boolean;
- fragment?: boolean;
- chunkBytes?: number;
- } = {},
- ): void => {
- const response =
- options.raw === true ? String(value) : JSON.stringify(value);
- const responseProof = createHmac("sha256", token)
- .update(
- `rea-cutter-response-v2:${sessionId}:${clientNonce}:${serverNonce}:${response}`,
- )
- .digest("hex");
- const frame = `${JSON.stringify({ response, proof: responseProof })}\n`;
- const bytes = Buffer.from(frame);
- if (options.chunkBytes !== undefined) {
- const writeChunk = (offset: number): void => {
- if (connection.destroyed) return;
- const end = Math.min(offset + options.chunkBytes!, bytes.length);
- if (offset === bytes.length) {
- connection.end();
- return;
- }
- connection.write(bytes.subarray(offset, end));
- setImmediate(() => writeChunk(end));
- };
- setImmediate(() => writeChunk(0));
- } else if (options.fragment === true) {
- const midpoint = Math.floor(bytes.length / 2);
- connection.write(bytes.subarray(0, midpoint));
- setImmediate(() => connection.end(bytes.subarray(midpoint)));
- } else connection.end(frame);
- };
- const request = JSON.parse(requestBytes) as Record<string, unknown>;
- if (request.kind === "status" && !handleStatusRequests) {
- respond({
- ok: true,
- session_id: sessionId,
- completed_commands: [],
- completed_connection: (connectionOrdinal - 1)
- .toString(16)
- .padStart(16, "0"),
- });
- continue;
- }
- onRequest(request, respond, connection);
- }
- });
- });
-};
-
const statusServer = (
token: string,
currentFile: string | null,
@@ -170,32 +67,6 @@ const createStatusHarness = (
return { server, requestText: () => requestText };
};
-const writeDescriptor = async (
- directory: string,
- sessionId: string,
- port: number,
- token: string,
- options: {
- readonly currentFile?: string | null;
- readonly documentGeneration?: number;
- } = {},
-): Promise<void> =>
- writeFile(
- join(directory, `cutter-${process.pid}-${sessionId}.json`),
- JSON.stringify({
- session_id: sessionId,
- pid: process.pid,
- host: "127.0.0.1",
- port,
- token,
- document_generation: options.documentGeneration ?? 0,
- current_file: options.currentFile ?? null,
- cutter_version: "Cutter fixture version",
- identity_status: "partial",
- }),
- { mode: 0o600 },
- );
-
const expectDiscoveredSession = (
result: unknown,
sessionId: string,
diff --git a/tests/boundary/providers/CutterStatusProof.test.ts b/tests/boundary/providers/CutterStatusProof.test.ts
new file mode 100644
index 000000000..2b4fa97b1
--- /dev/null
+++ b/tests/boundary/providers/CutterStatusProof.test.ts
@@ -0,0 +1,71 @@
+import { it, expect, onTestFinished } from "vitest";
+import {
+ authenticatedServer,
+ writeDescriptor,
+} from "../../fixtures/cutterBridgeProtocol.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { CutterBridgeClient } from "../../../src/cutter/CutterBridgeClient.js";
+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
+
+it.each(["invalid-identity", "exact-receipt", "unrelated-receipt"] as const)(
+ "checks command completion independently of preflight watermark admission: %s",
+ async (mode) => {
+ const directory = await createTestTempDirectory("rea-cutter-status-proof-");
+ const sessionId = "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a";
+ const requestId = "4b18ce4d-bf31-456e-ae31-e8c547b2f9db";
+ const otherId = "ede4bbfd-6348-46aa-963b-0de0e78ccbdc";
+ const token = "synthetic-cutter-status-proof-token";
+ const calls: string[] = [];
+ const server = authenticatedServer(
+ token,
+ sessionId,
+ (request, respond) => {
+ calls.push(String(request.kind));
+ if (request.kind === "ack") {
+ expect(request.request_id).toBe(requestId);
+ respond({ ok: true, acknowledged: true });
+ return;
+ }
+ respond({
+ ok: true,
+ session_id: mode === "invalid-identity" ? otherId : sessionId,
+ completed_commands: [
+ {
+ request_id: mode === "exact-receipt" ? requestId : otherId,
+ execution_state: "complete",
+ },
+ ],
+ });
+ },
+ true,
+ );
+ onTestFinished(
+ async () => new Promise<void>((resolve) => server.close(() => resolve())),
+ );
+ await new Promise<void>((resolve) =>
+ server.listen(0, "127.0.0.1", resolve),
+ );
+ const address = server.address();
+ if (address === null || typeof address === "string")
+ throw new Error("Missing listener");
+ const port = address.port;
+ await writeDescriptor(directory, sessionId, port, token);
+ const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: directory });
+ const result = await client.confirmCommandCompletion(sessionId, requestId);
+ if (mode === "invalid-identity") {
+ if (result.ok) throw new Error("Expected invalid status identity");
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "unreadable_output",
+ details: {
+ operation: "cutter_command",
+ diagnostics: { auxiliary_operation: "status" },
+ },
+ });
+ } else
+ expect(result).toEqual({ ok: true, value: mode === "exact-receipt" });
+ expect(calls).toEqual(
+ mode === "exact-receipt" ? ["status", "ack"] : ["status"],
+ );
+ await client.close();
+ },
+);
diff --git a/tests/fixtures/cutterBridgeProtocol.ts b/tests/fixtures/cutterBridgeProtocol.ts
new file mode 100644
index 000000000..2103a8753
--- /dev/null
+++ b/tests/fixtures/cutterBridgeProtocol.ts
@@ -0,0 +1,137 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createServer } from "node:net";
+import { createHmac } from "node:crypto";
+
+/** Authenticate real v2 frames before dispatching controlled bridge replies. */
+export const authenticatedServer = (
+ token: string,
+ sessionId: string,
+ onRequest: (
+ request: Record<string, unknown>,
+ respond: (
+ value: unknown,
+ options?: { raw?: boolean; fragment?: boolean; chunkBytes?: number },
+ ) => void,
+ connection: import("node:net").Socket,
+ ) => void,
+ handleStatusRequests = false,
+): ReturnType<typeof createServer> => {
+ let nextConnectionOrdinal = 0;
+ return createServer((connection) => {
+ const connectionOrdinal = ++nextConnectionOrdinal;
+ connection.setEncoding("utf8");
+ let input = "";
+ let clientNonce = "";
+ let serverNonce = "";
+ connection.on("data", (chunk: string) => {
+ input += chunk;
+ for (;;) {
+ const end = input.indexOf("\n");
+ if (end < 0) return;
+ const frame = JSON.parse(input.slice(0, end)) as Record<
+ string,
+ unknown
+ >;
+ input = input.slice(end + 1);
+ if (frame.kind === "rea-auth-v2") {
+ clientNonce = String(frame.nonce);
+ serverNonce = `${connectionOrdinal.toString(16).padStart(16, "0")}${"e".repeat(48)}`;
+ const proof = createHmac("sha256", token)
+ .update(
+ `rea-cutter-server-v2:${sessionId}:${clientNonce}:${serverNonce}`,
+ )
+ .digest("hex");
+ connection.write(
+ `${JSON.stringify({ session_id: sessionId, nonce: serverNonce, proof })}\n`,
+ );
+ continue;
+ }
+ const requestBytes = String(frame.request);
+ const expected = createHmac("sha256", token)
+ .update(
+ `rea-cutter-client-v2:${sessionId}:${clientNonce}:${serverNonce}:${requestBytes}`,
+ )
+ .digest("hex");
+ if (frame.proof !== expected) {
+ connection.destroy();
+ return;
+ }
+ const respond = (
+ value: unknown,
+ options: {
+ raw?: boolean;
+ fragment?: boolean;
+ chunkBytes?: number;
+ } = {},
+ ): void => {
+ const response =
+ options.raw === true ? String(value) : JSON.stringify(value);
+ const responseProof = createHmac("sha256", token)
+ .update(
+ `rea-cutter-response-v2:${sessionId}:${clientNonce}:${serverNonce}:${response}`,
+ )
+ .digest("hex");
+ const frame = `${JSON.stringify({ response, proof: responseProof })}\n`;
+ const bytes = Buffer.from(frame);
+ if (options.chunkBytes !== undefined) {
+ const writeChunk = (offset: number): void => {
+ if (connection.destroyed) return;
+ const end = Math.min(offset + options.chunkBytes!, bytes.length);
+ if (offset === bytes.length) {
+ connection.end();
+ return;
+ }
+ connection.write(bytes.subarray(offset, end));
+ setImmediate(() => writeChunk(end));
+ };
+ setImmediate(() => writeChunk(0));
+ } else if (options.fragment === true) {
+ const midpoint = Math.floor(bytes.length / 2);
+ connection.write(bytes.subarray(0, midpoint));
+ setImmediate(() => connection.end(bytes.subarray(midpoint)));
+ } else connection.end(frame);
+ };
+ const request = JSON.parse(requestBytes) as Record<string, unknown>;
+ if (request.kind === "status" && !handleStatusRequests) {
+ respond({
+ ok: true,
+ session_id: sessionId,
+ completed_commands: [],
+ completed_connection: (connectionOrdinal - 1)
+ .toString(16)
+ .padStart(16, "0"),
+ });
+ continue;
+ }
+ onRequest(request, respond, connection);
+ }
+ });
+ });
+};
+
+export const writeDescriptor = async (
+ directory: string,
+ sessionId: string,
+ port: number,
+ token: string,
+ options: {
+ readonly currentFile?: string | null;
+ readonly documentGeneration?: number;
+ } = {},
+): Promise<void> =>
+ writeFile(
+ join(directory, `cutter-${process.pid}-${sessionId}.json`),
+ JSON.stringify({
+ session_id: sessionId,
+ pid: process.pid,
+ host: "127.0.0.1",
+ port,
+ token,
+ document_generation: options.documentGeneration ?? 0,
+ current_file: options.currentFile ?? null,
+ cutter_version: "Cutter fixture version",
+ identity_status: "partial",
+ }),
+ { mode: 0o600 },
+ );