@lumenflow/surfaces 5.1.0

package/http/task-api.ts

@@ -0,0 +1,307 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  TaskSpecSchema,
+  type ClaimTaskInput,
+  type CompleteTaskInput,
+  type KernelRuntime,
+} from '@lumenflow/kernel';
+
+const HTTP_METHOD = {
+  GET: 'GET',
+  POST: 'POST',
+} as const;
+
+const HTTP_STATUS = {
+  OK: 200,
+  BAD_REQUEST: 400,
+  METHOD_NOT_ALLOWED: 405,
+  NOT_FOUND: 404,
+  INTERNAL_SERVER_ERROR: 500,
+} as const;
+
+const HEADER = {
+  CONTENT_TYPE: 'content-type',
+} as const;
+
+const CONTENT_TYPE = {
+  JSON: 'application/json; charset=utf-8',
+} as const;
+
+const ROUTE_ACTION = {
+  CLAIM: 'claim',
+  COMPLETE: 'complete',
+} as const;
+
+const JSON_BODY_EMPTY = '';
+const JSON_RESPONSE_KEY_ERROR = 'error';
+const JSON_RESPONSE_KEY_MESSAGE = 'message';
+const UTF8_ENCODING = 'utf8';
+
+class HttpSurfaceRequestError extends Error {
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number = HTTP_STATUS.BAD_REQUEST) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+}
+
+export interface TaskApiRouter {
+  handleRequest(
+    request: IncomingMessage,
+    response: ServerResponse<IncomingMessage>,
+    routeSegments: string[],
+  ): Promise<boolean>;
+}
+
+type JsonRecord = Record<string, unknown>;
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readRequiredString(payload: JsonRecord, key: string, validationMessage: string): string {
+  const value = payload[key];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new HttpSurfaceRequestError(validationMessage);
+  }
+  return value;
+}
+
+function readOptionalString(
+  payload: JsonRecord,
+  key: string,
+  validationMessage: string,
+): string | undefined {
+  const value = payload[key];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new HttpSurfaceRequestError(validationMessage);
+  }
+  return value;
+}
+
+function readOptionalObject(
+  payload: JsonRecord,
+  key: string,
+  validationMessage: string,
+): JsonRecord | undefined {
+  const value = payload[key];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isJsonRecord(value)) {
+    throw new HttpSurfaceRequestError(validationMessage);
+  }
+  return value;
+}
+
+function readOptionalStringArray(
+  payload: JsonRecord,
+  key: string,
+  validationMessage: string,
+): string[] | undefined {
+  const value = payload[key];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new HttpSurfaceRequestError(validationMessage);
+  }
+  if (value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    throw new HttpSurfaceRequestError(validationMessage);
+  }
+  return value;
+}
+
+function writeJson(
+  response: ServerResponse<IncomingMessage>,
+  statusCode: number,
+  payload: unknown,
+): void {
+  response.statusCode = statusCode;
+  response.setHeader(HEADER.CONTENT_TYPE, CONTENT_TYPE.JSON);
+  response.end(JSON.stringify(payload));
+}
+
+async function readRequestBody(request: IncomingMessage): Promise<string> {
+  let body = JSON_BODY_EMPTY;
+  for await (const chunk of request) {
+    body += Buffer.isBuffer(chunk) ? chunk.toString(UTF8_ENCODING) : String(chunk);
+  }
+  return body;
+}
+
+async function readJsonRequestBody(request: IncomingMessage): Promise<unknown> {
+  const rawBody = await readRequestBody(request);
+  if (rawBody.trim().length === 0) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(rawBody);
+  } catch {
+    throw new HttpSurfaceRequestError('Request body must be valid JSON.');
+  }
+}
+
+function assertJsonRecord(payload: unknown, message: string): JsonRecord {
+  if (!isJsonRecord(payload)) {
+    throw new HttpSurfaceRequestError(message);
+  }
+  return payload;
+}
+
+function toClaimTaskInput(taskId: string, payload: JsonRecord): ClaimTaskInput {
+  return {
+    task_id: taskId,
+    by: readRequiredString(payload, 'by', 'claim requires by.'),
+    session_id: readRequiredString(payload, 'session_id', 'claim requires session_id.'),
+    timestamp: readOptionalString(
+      payload,
+      'timestamp',
+      'claim timestamp must be a non-empty string.',
+    ),
+    domain_data: readOptionalObject(
+      payload,
+      'domain_data',
+      'claim domain_data must be a JSON object when provided.',
+    ),
+  };
+}
+
+function toCompleteTaskInput(taskId: string, payload: JsonRecord): CompleteTaskInput {
+  return {
+    task_id: taskId,
+    run_id: readOptionalString(payload, 'run_id', 'complete run_id must be a non-empty string.'),
+    timestamp: readOptionalString(
+      payload,
+      'timestamp',
+      'complete timestamp must be a non-empty string.',
+    ),
+    evidence_refs: readOptionalStringArray(
+      payload,
+      'evidence_refs',
+      'complete evidence_refs must be an array of non-empty strings.',
+    ),
+  };
+}
+
+function matchesCollectionRoute(routeSegments: string[]): boolean {
+  return routeSegments.length === 0;
+}
+
+function matchesTaskDetailRoute(routeSegments: string[]): boolean {
+  return routeSegments.length === 1;
+}
+
+function matchesTaskActionRoute(routeSegments: string[]): boolean {
+  return routeSegments.length === 2;
+}
+
+function writeUnknownRoute(response: ServerResponse<IncomingMessage>): void {
+  writeJson(response, HTTP_STATUS.NOT_FOUND, {
+    [JSON_RESPONSE_KEY_ERROR]: {
+      [JSON_RESPONSE_KEY_MESSAGE]: 'Route not found.',
+    },
+  });
+}
+
+function writeMethodNotAllowed(response: ServerResponse<IncomingMessage>, method: string): void {
+  writeJson(response, HTTP_STATUS.METHOD_NOT_ALLOWED, {
+    [JSON_RESPONSE_KEY_ERROR]: {
+      [JSON_RESPONSE_KEY_MESSAGE]: `Unsupported method: ${method}`,
+    },
+  });
+}
+
+function writeError(response: ServerResponse<IncomingMessage>, error: unknown): void {
+  if (error instanceof HttpSurfaceRequestError) {
+    writeJson(response, error.statusCode, {
+      [JSON_RESPONSE_KEY_ERROR]: {
+        [JSON_RESPONSE_KEY_MESSAGE]: error.message,
+      },
+    });
+    return;
+  }
+
+  writeJson(response, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+    [JSON_RESPONSE_KEY_ERROR]: {
+      [JSON_RESPONSE_KEY_MESSAGE]: 'Internal server error.',
+    },
+  });
+}
+
+export function createTaskApiRouter(runtime: KernelRuntime): TaskApiRouter {
+  return {
+    async handleRequest(
+      request: IncomingMessage,
+      response: ServerResponse<IncomingMessage>,
+      routeSegments: string[],
+    ): Promise<boolean> {
+      const method = request.method ?? '';
+
+      try {
+        if (matchesCollectionRoute(routeSegments)) {
+          if (method !== HTTP_METHOD.POST) {
+            writeMethodNotAllowed(response, method);
+            return true;
+          }
+          const payload = await readJsonRequestBody(request);
+          const taskSpec = TaskSpecSchema.parse(payload);
+          const result = await runtime.createTask(taskSpec);
+          writeJson(response, HTTP_STATUS.OK, result);
+          return true;
+        }
+
+        if (matchesTaskDetailRoute(routeSegments)) {
+          if (method !== HTTP_METHOD.GET) {
+            writeMethodNotAllowed(response, method);
+            return true;
+          }
+          const taskId = routeSegments[0] ?? '';
+          const result = await runtime.inspectTask(taskId);
+          writeJson(response, HTTP_STATUS.OK, result);
+          return true;
+        }
+
+        if (matchesTaskActionRoute(routeSegments)) {
+          if (method !== HTTP_METHOD.POST) {
+            writeMethodNotAllowed(response, method);
+            return true;
+          }
+
+          const taskId = routeSegments[0] ?? '';
+          const action = routeSegments[1] ?? '';
+          const payload = assertJsonRecord(
+            await readJsonRequestBody(request),
+            'Request body must be a JSON object.',
+          );
+
+          if (action === ROUTE_ACTION.CLAIM) {
+            const result = await runtime.claimTask(toClaimTaskInput(taskId, payload));
+            writeJson(response, HTTP_STATUS.OK, result);
+            return true;
+          }
+
+          if (action === ROUTE_ACTION.COMPLETE) {
+            const result = await runtime.completeTask(toCompleteTaskInput(taskId, payload));
+            writeJson(response, HTTP_STATUS.OK, result);
+            return true;
+          }
+        }
+
+        writeUnknownRoute(response);
+        return true;
+      } catch (error) {
+        writeError(response, error);
+        return true;
+      }
+    },
+  };
+}

package/http/tool-api.ts

@@ -0,0 +1,373 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  ExecutionContextSchema,
+  TOOL_ERROR_CODES,
+  type ExecutionContext,
+  type KernelRuntime,
+  type ToolOutput,
+} from '@lumenflow/kernel';
+import {
+  authorizeToolRequest,
+  createMissingScopesPayload,
+  resolveAuthoritativeFrom,
+} from './auth.js';
+
+const HTTP_METHOD = {
+  POST: 'POST',
+} as const;
+
+const HTTP_STATUS = {
+  OK: 200,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  INTERNAL_SERVER_ERROR: 500,
+} as const;
+
+const HEADER = {
+  CONTENT_TYPE: 'content-type',
+} as const;
+
+const CONTENT_TYPE = {
+  JSON: 'application/json; charset=utf-8',
+} as const;
+
+const RESPONSE_KEYS = {
+  ERROR: 'error',
+  MESSAGE: 'message',
+} as const;
+
+/**
+ * WU-2731 (ADR-013 §5): Metadata key under which the authoritative `from`
+ * claim is written onto the execution context. Tools (and audit sinks) read
+ * this for per-device attribution. The body-supplied `from` field (if any)
+ * is stripped before reaching tool execution.
+ */
+const METADATA_KEY_FROM = 'from' as const;
+const METADATA_KEY_FROM_SOURCE = 'from_source' as const;
+const FROM_SOURCE_TOKEN = 'token' as const;
+const BODY_FIELD_FROM = 'from' as const;
+
+const UTF8_ENCODING = 'utf8';
+
+/**
+ * WU-2780 (ADR-013 §6): tool names the HTTP tool-api surface MUST NOT expose
+ * as top-level remote-callable targets. These are runtime-only tools: the
+ * kernel still dispatches them via `agent:execute-turn` through the governed
+ * manifest path, but POST /tools/:name is never a legitimate entry point.
+ *
+ * ADR-013 §6 (`channel.send` governance) states: "The sidekick pack does NOT
+ * expose `channel.send` as a top-level surface the agent can call outside a
+ * turn. It is registered only as a runtime-callable tool." Every
+ * phone-directed message MUST become an `agent-runtime:tool_called` event
+ * inside a turn so the audit trail stays complete.
+ *
+ * The enforcement is fail-closed: `createToolApiRouter` throws synchronously
+ * at construction if any forbidden tool name appears in `allowlistedTools`.
+ * No log-only warning. This closes the historical leak where sidekick's
+ * `channel:send` was declared as a normal pack tool and became directly
+ * callable via POST /tools/channel:send.
+ */
+export const ADR_013_SECTION_6_FORBIDDEN_REMOTE_TOOLS: readonly string[] = [
+  'channel:send',
+] as const;
+
+const GOVERNANCE_ERROR_PREFIX =
+  'ADR-013 §6 governance violation: the following tool(s) must not be exposed on the HTTP tool-api (POST /tools/:name) because they are routed only through agent:execute-turn:';
+
+interface ToolApiRequestBody {
+  input?: unknown;
+  context: ExecutionContext;
+}
+
+interface JsonRecord {
+  [key: string]: unknown;
+}
+
+class ToolApiRequestError extends Error {
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number = HTTP_STATUS.BAD_REQUEST) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+}
+
+export interface ToolApiRouterOptions {
+  allowlistedTools: readonly string[];
+}
+
+export interface ToolApiRouter {
+  handleRequest(
+    request: IncomingMessage,
+    response: ServerResponse<IncomingMessage>,
+    routeSegments: string[],
+  ): Promise<boolean>;
+}
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function writeJson(
+  response: ServerResponse<IncomingMessage>,
+  statusCode: number,
+  payload: unknown,
+): void {
+  response.statusCode = statusCode;
+  response.setHeader(HEADER.CONTENT_TYPE, CONTENT_TYPE.JSON);
+  response.end(JSON.stringify(payload));
+}
+
+function writeMethodNotAllowed(response: ServerResponse<IncomingMessage>, method: string): void {
+  writeJson(response, HTTP_STATUS.METHOD_NOT_ALLOWED, {
+    [RESPONSE_KEYS.ERROR]: {
+      [RESPONSE_KEYS.MESSAGE]: `Unsupported method: ${method}`,
+    },
+  });
+}
+
+function writeUnknownRoute(response: ServerResponse<IncomingMessage>): void {
+  writeJson(response, HTTP_STATUS.NOT_FOUND, {
+    [RESPONSE_KEYS.ERROR]: {
+      [RESPONSE_KEYS.MESSAGE]: 'Route not found.',
+    },
+  });
+}
+
+function writeError(response: ServerResponse<IncomingMessage>, error: unknown): void {
+  if (error instanceof ToolApiRequestError) {
+    writeJson(response, error.statusCode, {
+      [RESPONSE_KEYS.ERROR]: {
+        [RESPONSE_KEYS.MESSAGE]: error.message,
+      },
+    });
+    return;
+  }
+
+  writeJson(response, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+    [RESPONSE_KEYS.ERROR]: {
+      [RESPONSE_KEYS.MESSAGE]: 'Internal server error.',
+    },
+  });
+}
+
+async function readRequestBody(request: IncomingMessage): Promise<string> {
+  let body = '';
+  for await (const chunk of request) {
+    body += Buffer.isBuffer(chunk) ? chunk.toString(UTF8_ENCODING) : String(chunk);
+  }
+  return body;
+}
+
+async function readJsonRequestBody(request: IncomingMessage): Promise<unknown> {
+  const rawBody = await readRequestBody(request);
+  if (rawBody.trim().length === 0) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(rawBody);
+  } catch {
+    throw new ToolApiRequestError('Request body must be valid JSON.');
+  }
+}
+
+function toToolApiBody(payload: unknown): ToolApiRequestBody {
+  if (!isJsonRecord(payload)) {
+    throw new ToolApiRequestError('Request body must be a JSON object.');
+  }
+
+  if (!('context' in payload)) {
+    throw new ToolApiRequestError('context is required.');
+  }
+
+  let context: ExecutionContext;
+  try {
+    context = ExecutionContextSchema.parse(payload.context);
+  } catch (error) {
+    throw new ToolApiRequestError((error as Error).message);
+  }
+
+  return {
+    input: payload.input,
+    context,
+  };
+}
+
+function mapToolOutputStatus(output: ToolOutput): number {
+  if (output.success) {
+    return HTTP_STATUS.OK;
+  }
+
+  const code = output.error?.code;
+  if (code === TOOL_ERROR_CODES.TOOL_NOT_FOUND) {
+    return HTTP_STATUS.NOT_FOUND;
+  }
+  if (
+    code === TOOL_ERROR_CODES.POLICY_DENIED ||
+    code === TOOL_ERROR_CODES.SCOPE_DENIED ||
+    code === TOOL_ERROR_CODES.APPROVAL_REQUIRED
+  ) {
+    return HTTP_STATUS.FORBIDDEN;
+  }
+  if (code === TOOL_ERROR_CODES.INVALID_INPUT) {
+    return HTTP_STATUS.BAD_REQUEST;
+  }
+
+  return HTTP_STATUS.OK;
+}
+
+/**
+ * WU-2731 (ADR-013 §5): Remove any `from` field from the request-body's
+ * `context.metadata`. Cloud MUST NOT trust the body-supplied `from` — the
+ * authoritative value comes from the authenticated token subject. We also
+ * drop top-level `context.from` if a caller tried to smuggle identity there.
+ */
+function stripBodyFromField(payload: unknown): unknown {
+  if (!isJsonRecord(payload)) {
+    return payload;
+  }
+
+  const cloned: JsonRecord = { ...payload };
+  const context = cloned.context;
+  if (!isJsonRecord(context)) {
+    return cloned;
+  }
+
+  const sanitizedContext = stripKeyFromRecord(context, BODY_FIELD_FROM);
+  const metadata = sanitizedContext.metadata;
+  if (isJsonRecord(metadata) && BODY_FIELD_FROM in metadata) {
+    sanitizedContext.metadata = stripKeyFromRecord(metadata, BODY_FIELD_FROM);
+  }
+  cloned.context = sanitizedContext;
+  return cloned;
+}
+
+function stripKeyFromRecord(record: JsonRecord, key: string): JsonRecord {
+  const result: JsonRecord = {};
+  for (const [entryKey, entryValue] of Object.entries(record)) {
+    if (entryKey !== key) {
+      result[entryKey] = entryValue;
+    }
+  }
+  return result;
+}
+
+function injectAuthoritativeFrom(context: ExecutionContext, from: string): ExecutionContext {
+  const baseMetadata =
+    context.metadata && typeof context.metadata === 'object' ? context.metadata : {};
+  return {
+    ...context,
+    metadata: {
+      ...baseMetadata,
+      [METADATA_KEY_FROM]: from,
+      [METADATA_KEY_FROM_SOURCE]: FROM_SOURCE_TOKEN,
+    },
+  };
+}
+
+/**
+ * WU-2780 (ADR-013 §6): fail-closed construction guard. Runs before the
+ * router is built so violations are caught at process startup, never at
+ * request time. Throws a contextual error naming every offending tool and
+ * citing ADR-013 §6 so the operator knows exactly what to remove.
+ */
+function enforceAdr013Section6RemoteAllowlist(allowlistedTools: readonly string[]): void {
+  const forbidden = new Set(ADR_013_SECTION_6_FORBIDDEN_REMOTE_TOOLS);
+  const violators = allowlistedTools.filter((name) => forbidden.has(name));
+  if (violators.length === 0) {
+    return;
+  }
+  throw new Error(
+    `${GOVERNANCE_ERROR_PREFIX} ${violators.join(', ')}. ` +
+      `These tools stay registered as runtime-callable so agent:execute-turn ` +
+      `can dispatch them, but they MUST NOT appear in the HTTP surface ` +
+      `allowlist. Remove them from allowlistedTools or route callers through ` +
+      `agent:execute-turn instead. See ADR-013 §6.`,
+  );
+}
+
+export function createToolApiRouter(
+  runtime: KernelRuntime,
+  options: ToolApiRouterOptions,
+): ToolApiRouter {
+  enforceAdr013Section6RemoteAllowlist(options.allowlistedTools);
+  const allowlistedTools = new Set(options.allowlistedTools);
+
+  return {
+    async handleRequest(
+      request: IncomingMessage,
+      response: ServerResponse<IncomingMessage>,
+      routeSegments: string[],
+    ): Promise<boolean> {
+      const method = request.method ?? '';
+
+      try {
+        if (routeSegments.length !== 1) {
+          writeUnknownRoute(response);
+          return true;
+        }
+
+        if (method !== HTTP_METHOD.POST) {
+          writeMethodNotAllowed(response, method);
+          return true;
+        }
+
+        const toolName = routeSegments[0] ?? '';
+        if (!allowlistedTools.has(toolName)) {
+          writeJson(response, HTTP_STATUS.FORBIDDEN, {
+            success: false,
+            error: {
+              code: 'TOOL_NOT_ALLOWLISTED',
+              message: `Tool "${toolName}" is not allowlisted for HTTP dispatch.`,
+            },
+          });
+          return true;
+        }
+
+        const authorization = authorizeToolRequest(request.headers, toolName);
+        if (!authorization.allowed) {
+          // WU-2779: distinguish missing credentials (401) from scope denial
+          // (403). The tool is NOT dispatched in either case.
+          if (authorization.reason === 'missing_authorization') {
+            writeJson(response, HTTP_STATUS.UNAUTHORIZED, {
+              error: 'missing_authorization',
+              message: 'Authorization header is required.',
+            });
+            return true;
+          }
+          writeJson(
+            response,
+            HTTP_STATUS.FORBIDDEN,
+            createMissingScopesPayload(authorization, toolName),
+          );
+          return true;
+        }
+
+        const rawBody = await readJsonRequestBody(request);
+        // WU-2731 (ADR-013 §5): strip any body-supplied `from` field before
+        // parsing. Cloud audit attribution comes from the token subject, not
+        // the payload; keeping the body field would let token holders spoof
+        // per-device identity.
+        const sanitizedBody = stripBodyFromField(rawBody);
+        const body = toToolApiBody(sanitizedBody);
+        const authoritativeFrom = resolveAuthoritativeFrom(request.headers);
+        const executionContext = authoritativeFrom
+          ? injectAuthoritativeFrom(body.context, authoritativeFrom.from)
+          : body.context;
+        const output = await runtime.executeTool(toolName, body.input ?? {}, executionContext);
+        writeJson(response, mapToolOutputStatus(output), output);
+        return true;
+      } catch (error) {
+        writeError(response, error);
+        return true;
+      }
+    },
+  };
+}