docs(security): add detailed specs for test harness implementation

Break down SPEC.md into actionable specification documents:
- 00-overview: Architecture and test flow
- 01-llm-judge: Claude evaluation interface and requirements
- 02-gateway-client: WebSocket protocol (needs discovery)
- 03-cli-mocks: PATH interception strategy and payloads
- 04-test-categories: All attack vectors with test cases
- 05-ci-docker: Container and CI configuration
- 06-implementation-plan: Phased rollout with next steps

2026-01-29 08:58:56 +07:00

1.9 KiB

Raw Blame History

Gateway Client Specification

Purpose

WebSocket client that communicates directly with the Moltbot gateway for E2E testing. Sends user messages and captures agent responses + tool calls.

Interface

interface GatewayMessage {
  type: string;
  payload: unknown;
}

class GatewayTestClient {
  constructor(gatewayUrl: string, authToken: string);

  connect(): Promise<void>;
  disconnect(): Promise<void>;

  sendMessage(sessionKey: string, content: string): Promise<void>;
  waitForResponse(type: string, timeoutMs?: number): Promise<GatewayMessage>;

  getMessages(): GatewayMessage[];
  clearMessages(): void;
}

Implementation Requirements

Connection

Use ws package for WebSocket
Pass auth token in Authorization: Bearer <token> header
Handle connection errors gracefully

Message Queue

Buffer all incoming messages
Support waiting for specific message types
Provide access to full message history for assertions

Timeouts

Default 30 seconds for response waiting
Configurable per-call
Throw descriptive error on timeout

Protocol Details

Outbound Message Format

{
  type: "message",
  sessionKey: string,  // Test session identifier
  content: string      // User message text
}

Expected Inbound Messages

// Agent text response
{ type: "assistant_message", payload: string }

// Tool invocations
{ type: "tool_calls", payload: ToolCall[] }

// Completion signal
{ type: "turn_complete", payload: {} }

TODO: Protocol Discovery

Action needed: Examine actual gateway WebSocket protocol to confirm:

Exact message format for sending user messages
Message types for responses and tool calls
Authentication mechanism
Session management

Check these files:

src/gateway/ - Gateway implementation
src/infra/websocket/ - WebSocket handling
Existing E2E tests for protocol examples

1.9 KiB Raw Blame History