@agent-wall/core 0.1.0

package/src/read-buffer-security.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { ReadBuffer, BufferOverflowError } from "./read-buffer.js";
+
+describe("ReadBuffer Security", () => {
+  describe("overflow protection", () => {
+    it("should accept data within the default limit", () => {
+      const buf = new ReadBuffer();
+      const chunk = Buffer.alloc(1000, "a");
+      expect(() => buf.append(chunk)).not.toThrow();
+    });
+
+    it("should throw BufferOverflowError when exceeding limit", () => {
+      const buf = new ReadBuffer(100); // 100 byte limit
+      const chunk = Buffer.alloc(200, "a");
+      expect(() => buf.append(chunk)).toThrow(BufferOverflowError);
+    });
+
+    it("should clear buffer after overflow", () => {
+      const buf = new ReadBuffer(100);
+      try {
+        buf.append(Buffer.alloc(200, "a"));
+      } catch {
+        // expected
+      }
+      expect(buf.hasPendingData).toBe(false);
+      expect(buf.currentSize).toBe(0);
+    });
+
+    it("should throw when accumulated chunks exceed limit", () => {
+      const buf = new ReadBuffer(100);
+      buf.append(Buffer.alloc(60, "a"));
+      expect(() => buf.append(Buffer.alloc(60, "b"))).toThrow(BufferOverflowError);
+    });
+
+    it("should work normally after extracting messages frees space", () => {
+      const buf = new ReadBuffer(200);
+      const msg = JSON.stringify({ jsonrpc: "2.0", method: "test" }) + "\n";
+      buf.append(Buffer.from(msg));
+      const result = buf.readMessage();
+      expect(result).not.toBeNull();
+      expect(buf.currentSize).toBe(0);
+    });
+
+    it("should respect custom buffer size", () => {
+      const buf = new ReadBuffer(50);
+      expect(() => buf.append(Buffer.alloc(51, "x"))).toThrow(BufferOverflowError);
+    });
+
+    it("should include size info in error message", () => {
+      const buf = new ReadBuffer(100);
+      try {
+        buf.append(Buffer.alloc(200, "a"));
+      } catch (err) {
+        expect((err as Error).message).toContain("200");
+        expect((err as Error).message).toContain("100");
+      }
+    });
+  });
+});

package/src/read-buffer.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for ReadBuffer — JSON-RPC message parsing over newline-delimited streams.
+ */
+
+import { describe, it, expect } from "vitest";
+import { ReadBuffer, serializeMessage, deserializeMessage } from "./read-buffer.js";
+import type { JsonRpcMessage } from "./types.js";
+
+describe("ReadBuffer", () => {
+  it("should parse a single complete message", () => {
+    const buf = new ReadBuffer();
+    const msg: JsonRpcMessage = {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/list",
+    };
+    buf.append(Buffer.from(JSON.stringify(msg) + "\n"));
+
+    const result = buf.readMessage();
+    expect(result).toEqual(msg);
+  });
+
+  it("should return null when no complete message available", () => {
+    const buf = new ReadBuffer();
+    buf.append(Buffer.from('{"jsonrpc":"2.0"'));
+
+    const result = buf.readMessage();
+    expect(result).toBeNull();
+  });
+
+  it("should handle messages split across multiple chunks", () => {
+    const buf = new ReadBuffer();
+    const msg: JsonRpcMessage = {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "read_file", arguments: { path: "/test" } },
+    };
+    const full = JSON.stringify(msg) + "\n";
+    const mid = Math.floor(full.length / 2);
+
+    buf.append(Buffer.from(full.slice(0, mid)));
+    expect(buf.readMessage()).toBeNull();
+
+    buf.append(Buffer.from(full.slice(mid)));
+    const result = buf.readMessage();
+    expect(result).toEqual(msg);
+  });
+
+  it("should parse multiple messages in one chunk", () => {
+    const buf = new ReadBuffer();
+    const msg1: JsonRpcMessage = { jsonrpc: "2.0", id: 1, method: "a" };
+    const msg2: JsonRpcMessage = { jsonrpc: "2.0", id: 2, method: "b" };
+
+    buf.append(
+      Buffer.from(JSON.stringify(msg1) + "\n" + JSON.stringify(msg2) + "\n")
+    );
+
+    const results = buf.readAllMessages();
+    expect(results).toHaveLength(2);
+    expect(results[0]).toEqual(msg1);
+    expect(results[1]).toEqual(msg2);
+  });
+
+  it("should handle \\r\\n line endings (Windows)", () => {
+    const buf = new ReadBuffer();
+    const msg: JsonRpcMessage = { jsonrpc: "2.0", id: 1, method: "test" };
+    buf.append(Buffer.from(JSON.stringify(msg) + "\r\n"));
+
+    const result = buf.readMessage();
+    expect(result).toEqual(msg);
+  });
+
+  it("should skip empty lines", () => {
+    const buf = new ReadBuffer();
+    const msg: JsonRpcMessage = { jsonrpc: "2.0", id: 1, method: "test" };
+    buf.append(Buffer.from("\n\n" + JSON.stringify(msg) + "\n"));
+
+    const results = buf.readAllMessages();
+    expect(results).toHaveLength(1);
+    expect(results[0]).toEqual(msg);
+  });
+
+  it("should clear the buffer", () => {
+    const buf = new ReadBuffer();
+    buf.append(Buffer.from("some data"));
+    expect(buf.hasPendingData).toBe(true);
+
+    buf.clear();
+    expect(buf.hasPendingData).toBe(false);
+  });
+
+  it("should throw on invalid JSON", () => {
+    const buf = new ReadBuffer();
+    buf.append(Buffer.from("not-json\n"));
+
+    expect(() => buf.readMessage()).toThrow();
+  });
+});
+
+describe("serializeMessage", () => {
+  it("should serialize with trailing newline", () => {
+    const msg: JsonRpcMessage = { jsonrpc: "2.0", id: 1, method: "test" };
+    const result = serializeMessage(msg);
+    expect(result).toBe('{"jsonrpc":"2.0","id":1,"method":"test"}\n');
+    expect(result.endsWith("\n")).toBe(true);
+  });
+});
+
+describe("deserializeMessage", () => {
+  it("should parse valid JSON-RPC request", () => {
+    const line = '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_file"}}';
+    const result = deserializeMessage(line);
+    expect(result).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "read_file" },
+    });
+  });
+
+  it("should parse valid JSON-RPC response", () => {
+    const line = '{"jsonrpc":"2.0","id":1,"result":{"content":"hello"}}';
+    const result = deserializeMessage(line);
+    expect(result).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      result: { content: "hello" },
+    });
+  });
+
+  it("should reject non-JSON-RPC messages", () => {
+    expect(() => deserializeMessage('{"hello":"world"}')).toThrow();
+  });
+});

package/src/read-buffer.ts

@@ -0,0 +1,126 @@
+/**
+ * Agent Wall Read Buffer
+ *
+ * Accumulates raw bytes from a stream and extracts
+ * newline-delimited JSON-RPC messages one at a time.
+ *
+ * Directly mirrors the MCP SDK's ReadBuffer pattern:
+ *   - Append raw chunks
+ *   - Scan for '\n' delimiter
+ *   - Extract line, strip '\r', JSON.parse, validate
+ *
+ * Security: Enforces maximum buffer size to prevent DOS
+ * via unbounded memory growth from a single large message.
+ */
+
+import { JsonRpcMessage, JsonRpcMessageSchema } from "./types.js";
+
+/** Default max buffer size: 10MB */
+const DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+
+export class ReadBuffer {
+  private buffer: Buffer | null = null;
+  private maxBufferSize: number;
+
+  constructor(maxBufferSize: number = DEFAULT_MAX_BUFFER_SIZE) {
+    this.maxBufferSize = maxBufferSize;
+  }
+
+  /**
+   * Append raw bytes from a stream chunk.
+   * Throws if the buffer exceeds the configured maximum size.
+   */
+  append(chunk: Buffer): void {
+    this.buffer = this.buffer ? Buffer.concat([this.buffer, chunk]) : chunk;
+    if (this.buffer.length > this.maxBufferSize) {
+      const size = this.buffer.length;
+      this.buffer = null;
+      throw new BufferOverflowError(
+        `Buffer size ${size} exceeds maximum ${this.maxBufferSize} bytes — possible DOS attack`
+      );
+    }
+  }
+
+  /**
+   * Try to extract the next complete JSON-RPC message.
+   * Returns null if no complete message is available yet.
+   * Automatically skips empty lines.
+   */
+  readMessage(): JsonRpcMessage | null {
+    while (this.buffer) {
+      const index = this.buffer.indexOf("\n");
+      if (index === -1) return null;
+
+      // Extract the line (strip trailing \r for Windows compatibility)
+      const line = this.buffer.toString("utf8", 0, index).replace(/\r$/, "");
+      this.buffer = this.buffer.subarray(index + 1);
+
+      // Normalize: discard buffer reference if empty
+      if (this.buffer.length === 0) this.buffer = null;
+
+      // Skip empty lines
+      if (line.length === 0) continue;
+
+      return deserializeMessage(line);
+    }
+    return null;
+  }
+
+  /**
+   * Extract ALL available messages from the buffer.
+   */
+  readAllMessages(): JsonRpcMessage[] {
+    const messages: JsonRpcMessage[] = [];
+    let msg: JsonRpcMessage | null;
+    while ((msg = this.readMessage()) !== null) {
+      messages.push(msg);
+    }
+    return messages;
+  }
+
+  /**
+   * Clear the buffer.
+   */
+  clear(): void {
+    this.buffer = null;
+  }
+
+  /**
+   * Check if there's any pending data in the buffer.
+   */
+  get hasPendingData(): boolean {
+    return this.buffer !== null && this.buffer.length > 0;
+  }
+
+  /**
+   * Get current buffer size in bytes.
+   */
+  get currentSize(): number {
+    return this.buffer?.length ?? 0;
+  }
+}
+
+/**
+ * Error thrown when buffer exceeds maximum size.
+ */
+export class BufferOverflowError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BufferOverflowError";
+  }
+}
+
+/**
+ * Parse a single line of text into a validated JSON-RPC message.
+ */
+export function deserializeMessage(line: string): JsonRpcMessage {
+  const parsed = JSON.parse(line);
+  return JsonRpcMessageSchema.parse(parsed);
+}
+
+/**
+ * Serialize a JSON-RPC message to a newline-delimited string.
+ */
+export function serializeMessage(message: JsonRpcMessage): string {
+  return JSON.stringify(message) + "\n";
+}