@lumenflow/surfaces 5.1.0

package/http/__tests__/auth-boundary.test.ts

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const HTTP_SURFACE_ROOT = path.resolve(import.meta.dirname, '..');
+const TYPESCRIPT_SOURCE_GLOB = '**/*.ts';
+const CORE_BOUNDARY_PATTERNS = ['@lumenflow/core', '../../core/'] as const;
+
+function collectTypeScriptFiles(root: string): string[] {
+  const results: string[] = [];
+
+  function visit(currentPath: string): void {
+    for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+      const entryPath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        visit(entryPath);
+        continue;
+      }
+
+      if (entry.isFile() && entry.name.endsWith('.ts')) {
+        results.push(entryPath);
+      }
+    }
+  }
+
+  visit(root);
+  return results.sort();
+}
+
+describe('http auth boundary', () => {
+  it(`keeps ${TYPESCRIPT_SOURCE_GLOB} free of core-boundary imports`, () => {
+    const matches = collectTypeScriptFiles(HTTP_SURFACE_ROOT)
+      .map((filePath) => ({
+        filePath,
+        content: readFileSync(filePath, 'utf8'),
+      }))
+      .filter(({ content }) =>
+        CORE_BOUNDARY_PATTERNS.some((pattern) => {
+          const importPattern = new RegExp(
+            String.raw`(?:from\s+['"]${escapeForRegExp(pattern)}['"]|require\(\s*['"]${escapeForRegExp(pattern)}['"]\s*\)|new URL\(\s*['"]${escapeForRegExp(pattern)})`,
+            'u',
+          );
+          return importPattern.test(content);
+        }),
+      )
+      .map(({ filePath }) => path.relative(HTTP_SURFACE_ROOT, filePath));
+
+    expect(matches).toEqual([]);
+  });
+});
+
+function escapeForRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}

package/http/__tests__/channel-send-governance.test.ts

@@ -0,0 +1,158 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * WU-2780 (P0 governance): ADR-013 §6 states `channel.send` MUST NOT be a
+ * top-level remote surface; it is `registered only as a runtime-callable
+ * tool` and the governed dispatch path is `agent:execute-turn`. This suite
+ * enforces that contract fail-closed at the HTTP tool-api boundary.
+ *
+ * Three assertions:
+ *   1. `createToolApiRouter` refuses to construct a router whose allowlist
+ *      contains a forbidden remote-callable tool name (throws with an
+ *      ADR-013 §6 citation).
+ *   2. When a router is built with a non-violating allowlist, POST
+ *      /tools/channel:send returns 403 because the tool is NOT allowlisted
+ *      (no implicit remote exposure).
+ *   3. The runtime `executeTool` path itself is NOT short-circuited by the
+ *      governance check — `agent:execute-turn` (or any other caller that
+ *      dispatches through `runtime.executeTool`) remains free to invoke
+ *      `channel:send`. The governance applies to the HTTP surface only.
+ */
+
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { ADR_013_SECTION_6_FORBIDDEN_REMOTE_TOOLS, createToolApiRouter } from '../tool-api.js';
+
+const HTTP_METHOD_POST = 'POST';
+const HTTP_STATUS_FORBIDDEN = 403;
+const HTTP_STATUS_OK = 200;
+
+const CHANNEL_SEND_TOOL = 'channel:send';
+const SAFE_ALLOWLISTED_TOOL = 'task:status';
+
+const ADR_013_CITATION_FRAGMENT = 'ADR-013';
+
+class MockResponse extends EventEmitter {
+  statusCode = HTTP_STATUS_OK;
+  body = '';
+  private readonly headers = new Map<string, string>();
+
+  setHeader(name: string, value: string | number | readonly string[]): this {
+    this.headers.set(name.toLowerCase(), String(value));
+    return this;
+  }
+
+  write(chunk: string | Buffer): boolean {
+    this.body += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk;
+    return true;
+  }
+
+  end(chunk?: string | Buffer): this {
+    if (chunk !== undefined) {
+      this.write(chunk);
+    }
+    this.emit('finish');
+    return this;
+  }
+}
+
+function createRequest(body: unknown): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: IncomingHttpHeaders;
+  };
+  request.method = HTTP_METHOD_POST;
+  request.url = '/';
+  request.headers = {
+    'content-type': 'application/json; charset=utf-8',
+    authorization: 'Bearer legacy-opaque-test-token',
+  };
+  const payload = body === undefined ? '' : JSON.stringify(body);
+  (request as unknown as PassThrough).end(payload);
+  return request;
+}
+
+function createContext() {
+  return {
+    run_id: 'run-governance',
+    task_id: 'WU-2780',
+    session_id: 'session-governance',
+    allowed_scopes: [
+      {
+        type: 'path' as const,
+        pattern: 'workspace/**',
+        access: 'read' as const,
+      },
+    ],
+  };
+}
+
+describe('WU-2780 ADR-013 §6 channel.send governance (HTTP surface fail-closed)', () => {
+  it('exports the forbidden-remote-tools list with channel:send included', () => {
+    expect(ADR_013_SECTION_6_FORBIDDEN_REMOTE_TOOLS).toContain(CHANNEL_SEND_TOOL);
+  });
+
+  it('createToolApiRouter throws when channel:send is in allowlistedTools', () => {
+    expect(() =>
+      createToolApiRouter({ executeTool: vi.fn() } as never, {
+        allowlistedTools: [SAFE_ALLOWLISTED_TOOL, CHANNEL_SEND_TOOL],
+      }),
+    ).toThrowError(new RegExp(`${CHANNEL_SEND_TOOL}.*${ADR_013_CITATION_FRAGMENT}`, 's'));
+  });
+
+  it('the governance error names ADR-013 §6 and the forbidden tool explicitly', () => {
+    let caught: unknown;
+    try {
+      createToolApiRouter({ executeTool: vi.fn() } as never, {
+        allowlistedTools: [CHANNEL_SEND_TOOL],
+      });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    const message = (caught as Error).message;
+    expect(message).toContain(CHANNEL_SEND_TOOL);
+    expect(message).toContain(ADR_013_CITATION_FRAGMENT);
+    expect(message).toContain('agent:execute-turn');
+  });
+
+  it('POST /tools/channel:send returns 403 when the router is built without channel:send (not allowlisted)', async () => {
+    const runtime = { executeTool: vi.fn() };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [SAFE_ALLOWLISTED_TOOL],
+    });
+    const request = createRequest({ input: { content: 'hi' }, context: createContext() });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      CHANNEL_SEND_TOOL,
+    ]);
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS_FORBIDDEN);
+  });
+
+  it('runtime.executeTool path for channel:send is NOT blocked by the HTTP governance (agent:execute-turn preserved)', async () => {
+    // Governance applies to the HTTP allowlist construction, NOT to the
+    // runtime dispatch path. `agent:execute-turn` calls runtime.executeTool
+    // directly to invoke `channel:send` through the manifest-driven
+    // dispatch (ADR-013 §6). This test proves the in-process path is free
+    // to dispatch channel:send without tripping the HTTP-surface guard.
+    const executeTool = vi.fn(async () => ({ success: true, data: { accepted: true } }));
+    const runtime = { executeTool };
+    const dispatchedContext = createContext();
+
+    await runtime.executeTool(CHANNEL_SEND_TOOL, { content: 'governed-path' }, dispatchedContext);
+
+    expect(executeTool).toHaveBeenCalledTimes(1);
+    expect(executeTool).toHaveBeenCalledWith(
+      CHANNEL_SEND_TOOL,
+      { content: 'governed-path' },
+      dispatchedContext,
+    );
+  });
+});

package/http/__tests__/event-stream.test.ts

@@ -0,0 +1,340 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import type { Disposable, KernelEvent, ReplayFilter, ToolTraceEntry } from '@lumenflow/kernel';
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import {
+  createEventStreamRouter,
+  type EventSubscriber,
+  type TraceSubscriber,
+  type StreamEvent,
+} from '../event-stream.js';
+
+// --- Constants ---
+
+const TASK_ID = 'task-sse-1918';
+const SSE_DATA_PREFIX = 'data: ';
+const SSE_DOUBLE_NEWLINE = '\n\n';
+const SSE_HEARTBEAT_COMMENT = ':heartbeat\n\n';
+const HEARTBEAT_INTERVAL_MS = 15_000;
+
+// --- Test helpers ---
+
+class MockResponse extends EventEmitter {
+  statusCode = 200;
+  body = '';
+  readonly headers = new Map<string, string>();
+
+  setHeader(name: string, value: string | number | readonly string[]): this {
+    this.headers.set(name.toLowerCase(), String(value));
+    return this;
+  }
+
+  write(chunk: string | Buffer): boolean {
+    this.body += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk;
+    return true;
+  }
+
+  end(chunk?: string | Buffer): this {
+    if (chunk !== undefined) {
+      this.write(chunk);
+    }
+    this.emit('finish');
+    return this;
+  }
+}
+
+function createRequest(url: string): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+  };
+  request.method = 'GET';
+  request.url = url;
+  request.headers = {};
+  return request;
+}
+
+function createSampleKernelEvent(): KernelEvent {
+  return {
+    schema_version: 1,
+    kind: 'task_claimed',
+    task_id: TASK_ID,
+    timestamp: '2026-02-20T00:00:01.000Z',
+    by: 'tom',
+    session_id: 'session-1',
+  } as unknown as KernelEvent;
+}
+
+function createSampleTrace(): ToolTraceEntry {
+  return {
+    schema_version: 1,
+    kind: 'tool_call_started',
+    receipt_id: 'receipt-001',
+    run_id: 'run-1',
+    task_id: TASK_ID,
+    session_id: 'session-1',
+    timestamp: '2026-02-20T00:00:02.000Z',
+    tool_name: 'file_read',
+    execution_mode: 'in_process',
+    scope_requested: [],
+    scope_allowed: [],
+    scope_enforced: [],
+    input_hash: 'a'.repeat(64),
+    input_ref: '/tmp/inputs/a',
+    tool_version: '1.0.0',
+    workspace_config_hash: 'b'.repeat(64),
+    runtime_version: '1.0.0',
+  } as ToolTraceEntry;
+}
+
+// --- Tests ---
+
+describe('event-stream SSE framing (AC-1)', () => {
+  it('writes kernel events with data: prefix and double newline', async () => {
+    const dispose = vi.fn();
+    let capturedCallback: ((event: KernelEvent) => void | Promise<void>) | null = null;
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, callback) => {
+        capturedCallback = callback;
+        return { dispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber);
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+    const searchParams = new URLSearchParams();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      searchParams,
+    );
+
+    const event = createSampleKernelEvent();
+    expect(capturedCallback).not.toBeNull();
+    await capturedCallback!(event);
+
+    const expectedPayload = `${SSE_DATA_PREFIX}${JSON.stringify({ source: 'kernel', event })}${SSE_DOUBLE_NEWLINE}`;
+    expect(response.body).toContain(expectedPayload);
+  });
+
+  it('does NOT write bare NDJSON (no data: prefix)', async () => {
+    const dispose = vi.fn();
+    let capturedCallback: ((event: KernelEvent) => void | Promise<void>) | null = null;
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, callback) => {
+        capturedCallback = callback;
+        return { dispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber);
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      new URLSearchParams(),
+    );
+
+    const event = createSampleKernelEvent();
+    await capturedCallback!(event);
+
+    // The old NDJSON format was: JSON.stringify(event) + '\n'
+    // This must NOT appear (without the data: prefix)
+    const bareNdjson = `${JSON.stringify(event)}\n`;
+    // The body should NOT start with this bare format
+    expect(response.body.startsWith(bareNdjson)).toBe(false);
+    // Every data line must start with 'data: '
+    const lines = response.body.split('\n').filter((line: string) => line.length > 0);
+    for (const line of lines) {
+      expect(line.startsWith('data: ') || line.startsWith(':')).toBe(true);
+    }
+  });
+});
+
+describe('event-stream StreamEvent envelope (AC-2)', () => {
+  it('wraps KernelEvent in StreamEvent with source: kernel', async () => {
+    const dispose = vi.fn();
+    let capturedCallback: ((event: KernelEvent) => void | Promise<void>) | null = null;
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, callback) => {
+        capturedCallback = callback;
+        return { dispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber);
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      new URLSearchParams(),
+    );
+
+    const event = createSampleKernelEvent();
+    await capturedCallback!(event);
+
+    // Parse the data line
+    const dataLine = response.body.split('\n').find((line: string) => line.startsWith('data: '));
+    expect(dataLine).toBeDefined();
+    const parsed = JSON.parse(dataLine!.slice('data: '.length)) as StreamEvent;
+    expect(parsed.source).toBe('kernel');
+    expect(parsed.event).toEqual(event);
+  });
+
+  it('wraps ToolTraceEntry in StreamEvent with source: evidence', async () => {
+    const dispose = vi.fn();
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, _callback) => {
+        return { dispose } satisfies Disposable;
+      }),
+    };
+    let capturedTraceCallback: ((trace: ToolTraceEntry) => void) | null = null;
+    const traceSubscriber: TraceSubscriber = {
+      subscribe: vi.fn((_taskId, callback) => {
+        capturedTraceCallback = callback;
+        return { dispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber, { traceSubscriber });
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      new URLSearchParams(),
+    );
+
+    const trace = createSampleTrace();
+    expect(capturedTraceCallback).not.toBeNull();
+    capturedTraceCallback!(trace);
+
+    const dataLine = response.body.split('\n').find((line: string) => line.startsWith('data: '));
+    expect(dataLine).toBeDefined();
+    const parsed = JSON.parse(dataLine!.slice('data: '.length)) as StreamEvent;
+    expect(parsed.source).toBe('evidence');
+    expect(parsed.trace).toEqual(trace);
+  });
+});
+
+describe('event-stream heartbeat (AC-4)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('sends heartbeat comment every 15 seconds', async () => {
+    const dispose = vi.fn();
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, _callback) => {
+        return { dispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber);
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      new URLSearchParams(),
+    );
+
+    // Initially no heartbeat
+    expect(response.body).toBe('');
+
+    // Advance 15 seconds
+    vi.advanceTimersByTime(HEARTBEAT_INTERVAL_MS);
+    expect(response.body).toContain(SSE_HEARTBEAT_COMMENT);
+
+    // Advance another 15 seconds
+    const bodyAfterFirst = response.body;
+    vi.advanceTimersByTime(HEARTBEAT_INTERVAL_MS);
+    // Should have two heartbeats now
+    const heartbeatCount = response.body.split(SSE_HEARTBEAT_COMMENT).length - 1;
+    expect(heartbeatCount).toBe(2);
+  });
+
+  it('stops heartbeat when connection closes', async () => {
+    const dispose = vi.fn();
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, _callback) => {
+        return { dispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber);
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      new URLSearchParams(),
+    );
+
+    // Close the connection
+    request.emit('close');
+
+    // Advance past heartbeat interval
+    vi.advanceTimersByTime(HEARTBEAT_INTERVAL_MS * 2);
+
+    // No heartbeats should have been sent
+    expect(response.body).toBe('');
+  });
+});
+
+describe('event-stream disposes subscriptions on close', () => {
+  it('disposes both event and trace subscriptions on request close', async () => {
+    const eventDispose = vi.fn();
+    const traceDispose = vi.fn();
+    const eventSubscriber: EventSubscriber = {
+      subscribe: vi.fn((_filter, _callback) => {
+        return { dispose: eventDispose } satisfies Disposable;
+      }),
+    };
+    const traceSubscriber: TraceSubscriber = {
+      subscribe: vi.fn((_taskId, _callback) => {
+        return { dispose: traceDispose } satisfies Disposable;
+      }),
+    };
+
+    const router = createEventStreamRouter(eventSubscriber, { traceSubscriber });
+    const request = createRequest(`/events/${TASK_ID}`);
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TASK_ID],
+      new URLSearchParams(),
+    );
+
+    request.emit('close');
+
+    expect(eventDispose).toHaveBeenCalledTimes(1);
+    expect(traceDispose).toHaveBeenCalledTimes(1);
+  });
+});