@lumenflow/surfaces 5.1.0

package/http/__tests__/tool-api-schema-validation.test.ts

@@ -0,0 +1,213 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+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 { createHttpSurface } from '../index.js';
+import type { KernelRuntime } from '@lumenflow/kernel';
+
+/*
+ * WU-2639 AC3: input_schema for each tool validates a known-good POST /tools/:name
+ * input using ajv or equivalent (unit test).
+ *
+ * This test validates that:
+ *   1. input_schema returned by GET /tools is a structurally valid JSON Schema
+ *      (object with type:"object" and a properties/required declaration).
+ *   2. A known-good input payload conforms to that schema using a minimal
+ *      JSON-Schema-object validator (ajv-equivalent scope sufficient for AC3).
+ *   3. That same payload is accepted by POST /tools/:name with status 200,
+ *      proving the declared input_schema matches the live dispatch surface.
+ */
+
+const SURFACES_VERSION = '4.23.0';
+const WORKSPACE_ID = 'workspace-schema-1';
+const CONTENT_TYPE_JSON = 'application/json; charset=utf-8';
+const HEADER_CONTENT_TYPE = 'content-type';
+const HTTP_STATUS_OK = 200;
+
+class MockResponse extends EventEmitter {
+  statusCode = HTTP_STATUS_OK;
+  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(method: string, url: string, body?: unknown): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: IncomingHttpHeaders;
+  };
+  request.method = method;
+  request.url = url;
+  request.headers = {
+    [HEADER_CONTENT_TYPE]: CONTENT_TYPE_JSON,
+    // WU-2779: POST /tools/:name requires Authorization. Attach a legacy
+    // opaque bearer token — this suite tests schema validation, not auth.
+    authorization: 'Bearer legacy-opaque-schema-validation-token',
+  };
+  const payload = body === undefined ? '' : JSON.stringify(body);
+  (request as unknown as PassThrough).end(payload);
+  return request;
+}
+
+// Minimal JSON-Schema-object validator (ajv-equivalent for object schemas
+// with properties + required). Sufficient for AC3 which only requires that
+// input_schema validates a known-good input.
+interface JsonSchemaObject {
+  type: 'object';
+  required?: string[];
+  properties?: Record<string, { type: string }>;
+}
+
+function isJsonSchemaObject(value: unknown): value is JsonSchemaObject {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return record.type === 'object';
+}
+
+function validateAgainstSchema(schema: unknown, value: unknown): string[] {
+  const errors: string[] = [];
+  if (!isJsonSchemaObject(schema)) {
+    errors.push('schema must declare type:"object"');
+    return errors;
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    errors.push('value must be an object');
+    return errors;
+  }
+
+  const record = value as Record<string, unknown>;
+  for (const required of schema.required ?? []) {
+    if (!(required in record)) {
+      errors.push(`missing required property "${required}"`);
+    }
+  }
+
+  for (const [key, propSchema] of Object.entries(schema.properties ?? {})) {
+    if (key in record && typeof record[key] !== propSchema.type) {
+      errors.push(`property "${key}" expected type ${propSchema.type}`);
+    }
+  }
+
+  return errors;
+}
+
+interface CatalogEntry {
+  name: string;
+  pack: string;
+  description: string;
+  input_schema: unknown;
+  output_schema: unknown;
+  requires_approval: boolean;
+}
+
+const TOOL_NAME = 'software-delivery:wu.claim';
+
+function createCatalog(): CatalogEntry[] {
+  return [
+    {
+      name: TOOL_NAME,
+      pack: 'software-delivery',
+      description: 'Claim a WU for implementation.',
+      input_schema: {
+        type: 'object',
+        required: ['wu_id'],
+        properties: { wu_id: { type: 'string' } },
+      },
+      output_schema: {
+        type: 'object',
+        properties: { worktree_path: { type: 'string' } },
+      },
+      requires_approval: false,
+    },
+  ];
+}
+
+describe('tool-api schema validation (AC3)', () => {
+  it('input_schema from GET /tools validates a known-good POST input', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { worktree_path: '/wt' } })),
+    } as unknown as KernelRuntime;
+
+    const surface = createHttpSurface(runtime, {
+      allowlistedTools: [TOOL_NAME],
+      toolCatalog: createCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    // 1. Fetch catalog via GET /tools
+    const getRequest = createRequest('GET', '/tools');
+    const getResponse = new MockResponse();
+    await surface.handleRequest(
+      getRequest,
+      getResponse as unknown as ServerResponse<IncomingMessage>,
+    );
+    const catalog = JSON.parse(getResponse.body) as { tools: CatalogEntry[] };
+    const descriptor = catalog.tools.find((tool) => tool.name === TOOL_NAME);
+    expect(descriptor).toBeDefined();
+
+    // 2. Validate known-good input against declared input_schema
+    const knownGoodInput = { wu_id: 'WU-2639' };
+    const errors = validateAgainstSchema(descriptor?.input_schema, knownGoodInput);
+    expect(errors).toEqual([]);
+
+    // 3. POST that same payload to /tools/:name and observe success
+    const postRequest = createRequest('POST', `/tools/${TOOL_NAME}`, {
+      input: knownGoodInput,
+      context: {
+        run_id: 'run-schema',
+        task_id: 'WU-2639',
+        session_id: 'session-schema',
+        allowed_scopes: [],
+      },
+    });
+    const postResponse = new MockResponse();
+    await surface.handleRequest(
+      postRequest,
+      postResponse as unknown as ServerResponse<IncomingMessage>,
+    );
+    expect(postResponse.statusCode).toBe(HTTP_STATUS_OK);
+  });
+
+  it('input_schema rejects a payload missing a required property', async () => {
+    const surface = createHttpSurface({ executeTool: vi.fn() } as unknown as KernelRuntime, {
+      allowlistedTools: [TOOL_NAME],
+      toolCatalog: createCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const getRequest = createRequest('GET', '/tools');
+    const getResponse = new MockResponse();
+    await surface.handleRequest(
+      getRequest,
+      getResponse as unknown as ServerResponse<IncomingMessage>,
+    );
+    const catalog = JSON.parse(getResponse.body) as { tools: CatalogEntry[] };
+    const descriptor = catalog.tools.find((tool) => tool.name === TOOL_NAME);
+
+    const missingRequired = {};
+    const errors = validateAgainstSchema(descriptor?.input_schema, missingRequired);
+    expect(errors).toContain('missing required property "wu_id"');
+  });
+});

package/http/__tests__/tool-api.test.ts

@@ -0,0 +1,491 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+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 { createToolApiRouter } from '../tool-api.js';
+
+const HTTP_METHOD = {
+  POST: 'POST',
+  GET: 'GET',
+} as const;
+
+const HTTP_STATUS = {
+  OK: 200,
+  BAD_REQUEST: 400,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  INTERNAL_SERVER_ERROR: 500,
+} as const;
+
+const TOOL_NAME = {
+  ALLOWED: 'task:status',
+  DISALLOWED: 'task:delete',
+} as const;
+
+interface RequestOptions {
+  method: string;
+  body?: unknown;
+}
+
+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(options: RequestOptions): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: IncomingHttpHeaders;
+  };
+
+  request.method = options.method;
+  request.url = '/';
+  request.headers = {
+    'content-type': 'application/json; charset=utf-8',
+    // WU-2779: POST /tools/:name now requires an Authorization header. Use a
+    // legacy opaque token here — the tests below cover runtime behavior, not
+    // auth; scope enforcement is covered in scope-enforcement.test.ts.
+    authorization: 'Bearer legacy-opaque-test-token',
+  };
+
+  const payload = options.body === undefined ? '' : JSON.stringify(options.body);
+  (request as unknown as PassThrough).end(payload);
+  return request;
+}
+
+function createContext() {
+  return {
+    run_id: 'run-tool-api',
+    task_id: 'WU-tool-api',
+    session_id: 'session-tool-api',
+    allowed_scopes: [
+      {
+        type: 'path' as const,
+        pattern: 'workspace/**',
+        access: 'read' as const,
+      },
+    ],
+  };
+}
+
+function parseJsonBody(body: string): unknown {
+  return JSON.parse(body);
+}
+
+describe('http tool api router', () => {
+  // --- AC1: HTTP surface exposes POST /tools/:name ---
+
+  it('dispatches allowlisted tool via POST and returns success', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: true,
+        data: { ok: true },
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: { taskId: 'WU-1' },
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(runtime.executeTool).toHaveBeenCalledTimes(1);
+    expect(runtime.executeTool).toHaveBeenCalledWith(
+      TOOL_NAME.ALLOWED,
+      { taskId: 'WU-1' },
+      createContext(),
+    );
+    expect(response.statusCode).toBe(HTTP_STATUS.OK);
+  });
+
+  it('passes empty object as input when input is omitted', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: true,
+        data: {},
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(runtime.executeTool).toHaveBeenCalledWith(TOOL_NAME.ALLOWED, {}, createContext());
+  });
+
+  it('returns 405 for non-POST methods', async () => {
+    const runtime = {
+      executeTool: vi.fn(),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.GET,
+      body: {},
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS.METHOD_NOT_ALLOWED);
+  });
+
+  it('returns 404 for nested route segments', async () => {
+    const runtime = {
+      executeTool: vi.fn(),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+      'extra',
+    ]);
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS.NOT_FOUND);
+  });
+
+  // --- AC2: Endpoint dispatches only allowlisted tools ---
+
+  it('denies tools outside the allowlist with 403', async () => {
+    const runtime = {
+      executeTool: vi.fn(),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.DISALLOWED,
+    ]);
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS.FORBIDDEN);
+
+    const body = parseJsonBody(response.body) as {
+      success: boolean;
+      error: { code: string; message: string };
+    };
+    expect(body.success).toBe(false);
+    expect(body.error.code).toBe('TOOL_NOT_ALLOWLISTED');
+  });
+
+  // --- AC3: Policy/scope/tool-not-found responses are enforced and tested ---
+
+  it('returns 404 when runtime reports TOOL_NOT_FOUND', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: false,
+        error: {
+          code: 'TOOL_NOT_FOUND',
+          message: 'Tool not registered.',
+        },
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.NOT_FOUND);
+  });
+
+  it('returns 403 when runtime reports POLICY_DENIED', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: false,
+        error: {
+          code: 'POLICY_DENIED',
+          message: 'Policy forbids this tool.',
+        },
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.FORBIDDEN);
+  });
+
+  it('returns 403 when runtime reports SCOPE_DENIED', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: false,
+        error: {
+          code: 'SCOPE_DENIED',
+          message: 'Scope intersection denied.',
+        },
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.FORBIDDEN);
+  });
+
+  it('returns 403 when runtime reports APPROVAL_REQUIRED', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: false,
+        error: {
+          code: 'APPROVAL_REQUIRED',
+          message: 'Approval needed.',
+        },
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.FORBIDDEN);
+  });
+
+  it('returns 400 when runtime reports INVALID_INPUT', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({
+        success: false,
+        error: {
+          code: 'INVALID_INPUT',
+          message: 'Bad input schema.',
+        },
+      })),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.BAD_REQUEST);
+  });
+
+  it('returns 400 when context is missing from request body', async () => {
+    const runtime = {
+      executeTool: vi.fn(),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS.BAD_REQUEST);
+  });
+
+  it('returns 400 when request body is invalid JSON', async () => {
+    const runtime = {
+      executeTool: vi.fn(),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    // Create request with raw invalid JSON
+    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',
+      // WU-2779: POST /tools/:name now requires an Authorization header.
+      authorization: 'Bearer legacy-opaque-test-token',
+    };
+    (request as unknown as PassThrough).end('not-valid-json{');
+
+    const response = new MockResponse();
+
+    await router.handleRequest(
+      request as IncomingMessage,
+      response as unknown as ServerResponse<IncomingMessage>,
+      [TOOL_NAME.ALLOWED],
+    );
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS.BAD_REQUEST);
+  });
+
+  it('returns 500 when runtime throws an unexpected error', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => {
+        throw new Error('unexpected runtime crash');
+      }),
+    };
+
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ALLOWED],
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: {},
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ALLOWED,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.INTERNAL_SERVER_ERROR);
+  });
+});