@lumenflow/surfaces 5.1.0

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

@@ -0,0 +1,177 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * WU-2731 (INIT-060 phase 3, ADR-013 §5): HTTP tool-api enforces the
+ * authoritative `from` rule for phone-scoped tokens.
+ *
+ * Acceptance criteria covered here:
+ *   - Inbound POST /tools/:name populates the `from` field on the execution
+ *     context from the authenticated token subject.
+ *   - Request-body `from` is IGNORED (body-supplied attribution cannot
+ *     override the authoritative value).
+ */
+
+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 { issueControlPlaneIdentity } from '../../../control-plane-sdk/src/authenticate.js';
+import { createToolApiRouter } from '../tool-api.js';
+
+const HTTP_METHOD_POST = 'POST';
+const HTTP_STATUS_OK = 200;
+const CONTENT_TYPE_JSON = 'application/json; charset=utf-8';
+const TOOL_NAME = 'orchestrate:initiative';
+const WORKSPACE_ID = 'ws-wu-2731';
+const DEVICE_ID = 'dev-wu-2731-iphone';
+const PHONE_SUBJECT = `${WORKSPACE_ID}:phone:${DEVICE_ID}`;
+const SPOOFED_SUBJECT = 'ws-other-tenant:phone:attacker';
+const METADATA_KEY_FROM = 'from';
+const METADATA_KEY_FROM_SOURCE = 'from_source';
+
+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: { body: unknown; authorization?: string }): 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': CONTENT_TYPE_JSON };
+  if (options.authorization) {
+    request.headers.authorization = options.authorization;
+  }
+  (request as unknown as PassThrough).end(JSON.stringify(options.body));
+  return request;
+}
+
+function createExecutionContext() {
+  return {
+    run_id: 'run-wu-2731',
+    task_id: 'WU-2731',
+    session_id: 'session-wu-2731',
+    allowed_scopes: [{ type: 'path' as const, pattern: '**', access: 'read' as const }],
+  };
+}
+
+function issuePhoneToken(): string {
+  const identity = issueControlPlaneIdentity(
+    {
+      workspace_id: WORKSPACE_ID,
+      org_id: 'org-wu-2731',
+      agent_id: 'agent-wu-2731',
+    },
+    {
+      profile: 'phone',
+      profiles: {
+        phone: {
+          ttl_seconds: 60 * 60 * 24,
+          scopes: ['tool:*'],
+        },
+      },
+      subject: PHONE_SUBJECT,
+    },
+  );
+  return identity.token;
+}
+
+describe('WU-2731: tool-api populates authoritative from from phone token subject', () => {
+  it('writes metadata.from = token subject on the execution context', async () => {
+    const captured: Array<{ input: unknown; ctx: unknown }> = [];
+    const runtime = {
+      executeTool: vi.fn(async (_name: string, input: unknown, ctx: unknown) => {
+        captured.push({ input, ctx });
+        return { success: true, data: {} };
+      }),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME],
+    });
+
+    const request = createRequest({
+      body: { input: { topic: 'test' }, context: createExecutionContext() },
+      authorization: `Bearer ${issuePhoneToken()}`,
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS_OK);
+    expect(captured).toHaveLength(1);
+    const ctx = captured[0].ctx as { metadata?: Record<string, unknown> };
+    expect(ctx.metadata?.[METADATA_KEY_FROM]).toBe(PHONE_SUBJECT);
+    expect(ctx.metadata?.[METADATA_KEY_FROM_SOURCE]).toBe('token');
+  });
+});
+
+describe('WU-2731: tool-api ignores body-supplied from field (spoof rejection)', () => {
+  it('strips context.from and context.metadata.from; authoritative from always wins', async () => {
+    const captured: Array<{ input: unknown; ctx: unknown }> = [];
+    const runtime = {
+      executeTool: vi.fn(async (_name: string, input: unknown, ctx: unknown) => {
+        captured.push({ input, ctx });
+        return { success: true, data: {} };
+      }),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME],
+    });
+
+    // Attacker supplies both top-level context.from and metadata.from.
+    const maliciousContext = {
+      ...createExecutionContext(),
+      from: SPOOFED_SUBJECT,
+      metadata: { from: SPOOFED_SUBJECT, trace_id: 'keep-me' },
+    };
+    const request = createRequest({
+      body: { input: {}, context: maliciousContext },
+      authorization: `Bearer ${issuePhoneToken()}`,
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS_OK);
+    const ctx = captured[0].ctx as {
+      from?: unknown;
+      metadata?: Record<string, unknown>;
+    };
+    // Body-supplied from is stripped at top level.
+    expect(ctx.from).toBeUndefined();
+    // Authoritative value from the token subject replaces spoofed metadata.from.
+    expect(ctx.metadata?.[METADATA_KEY_FROM]).toBe(PHONE_SUBJECT);
+    expect(ctx.metadata?.[METADATA_KEY_FROM]).not.toBe(SPOOFED_SUBJECT);
+    // Unrelated metadata fields survive.
+    expect(ctx.metadata?.trace_id).toBe('keep-me');
+  });
+});

package/http/__tests__/remote-exposure.test.ts

@@ -0,0 +1,212 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+//
+// WU-2729 (INIT-060 Phase 2): HTTP tool-api enforcement for the 10
+// remote-callable software-delivery tools.
+//
+// Tools covered (per ADR-013 §3 + WU-2729 spec):
+//   gates, gates:docs, lane:suggest, lane:health, plan:create,
+//   plan:promote, initiative:create, initiative:add-wu,
+//   initiative:status, flow:report
+//
+// Each tool must:
+//   - Round-trip via POST /tools/:name (200 on success).
+//   - Reject callers whose bearer token lacks the tool:<name> scope (403).
+//   - Accept callers with a privileged profile (tool:*).
+//
+// The scope check is delegated to authorizeToolRequest; this test pins
+// the integration so we catch regressions where the allowlist diverges
+// from the scope grammar.
+
+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';
+import { issueWorkspaceProfileIdentity } from '../auth.js';
+
+const HTTP_METHOD = { POST: 'POST' } as const;
+const HTTP_STATUS = { OK: 200, FORBIDDEN: 403 } as const;
+const CONTENT_TYPE_JSON = 'application/json; charset=utf-8';
+
+const REMOTE_CALLABLE_TOOL_NAMES = [
+  'gates',
+  'gates:docs',
+  'lane:suggest',
+  'lane:health',
+  'plan:create',
+  'plan:promote',
+  'initiative:create',
+  'initiative:add-wu',
+  'initiative:status',
+  'flow:report',
+] as const;
+
+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;
+  }
+}
+
+interface CreateRequestOptions {
+  method: string;
+  body?: unknown;
+  authorization?: string;
+}
+
+function createRequest(options: CreateRequestOptions): 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': CONTENT_TYPE_JSON };
+  if (options.authorization) {
+    request.headers.authorization = options.authorization;
+  }
+  const payload = options.body === undefined ? '' : JSON.stringify(options.body);
+  (request as unknown as PassThrough).end(payload);
+  return request;
+}
+
+function createContext() {
+  return {
+    run_id: 'run-wu-2729',
+    task_id: 'WU-2729',
+    session_id: 'session-wu-2729',
+    allowed_scopes: [{ type: 'path' as const, pattern: '**', access: 'read' as const }],
+  };
+}
+
+function parseJsonBody(body: string): unknown {
+  return JSON.parse(body);
+}
+
+describe('WU-2729: POST /tools/:name round-trips 10 software-delivery tools', () => {
+  it.each(REMOTE_CALLABLE_TOOL_NAMES)(
+    'POST /tools/%s dispatches through runtime and returns 200 when allowlisted with a legacy opaque bearer token',
+    async (toolName) => {
+      // WU-2779 (P0 security): POST /tools/:name no longer dispatches when
+      // the Authorization header is missing. This round-trip test uses a
+      // legacy opaque bearer token, which is still permitted by default
+      // (allow_legacy_unscoped_tokens = true) and exercises the same runtime
+      // path as the original "no auth header" case.
+      const runtime = {
+        executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+      };
+      const router = createToolApiRouter(runtime as never, {
+        allowlistedTools: [...REMOTE_CALLABLE_TOOL_NAMES],
+      });
+      const request = createRequest({
+        method: HTTP_METHOD.POST,
+        body: { input: {}, context: createContext() },
+        authorization: 'Bearer legacy-opaque-token',
+      });
+      const response = new MockResponse();
+
+      await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+        toolName,
+      ]);
+
+      expect(runtime.executeTool).toHaveBeenCalledWith(toolName, {}, createContext());
+      expect(response.statusCode).toBe(HTTP_STATUS.OK);
+    },
+  );
+});
+
+describe('WU-2729: POST /tools/:name enforces scope grammar per WU-2640', () => {
+  it.each(REMOTE_CALLABLE_TOOL_NAMES)(
+    'POST /tools/%s with a mobile-profile token (no matching tool scope) returns 403 missing_scopes',
+    async (toolName) => {
+      const identity = issueWorkspaceProfileIdentity(
+        {
+          workspace_id: 'ws-wu-2729',
+          org_id: 'org-wu-2729',
+          agent_id: 'agent-wu-2729',
+        },
+        {
+          profile: 'mobile',
+          workspaceRoot: process.cwd(),
+        },
+      );
+      const runtime = {
+        executeTool: vi.fn(async () => ({ success: true, data: {} })),
+      };
+      const router = createToolApiRouter(runtime as never, {
+        allowlistedTools: [...REMOTE_CALLABLE_TOOL_NAMES],
+      });
+      const request = createRequest({
+        method: HTTP_METHOD.POST,
+        body: { input: {}, context: createContext() },
+        authorization: `Bearer ${identity.token}`,
+      });
+      const response = new MockResponse();
+
+      await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+        toolName,
+      ]);
+
+      expect(runtime.executeTool).not.toHaveBeenCalled();
+      expect(response.statusCode).toBe(HTTP_STATUS.FORBIDDEN);
+      const body = parseJsonBody(response.body) as { error: string; requested: string };
+      expect(body.error).toBe('missing_scopes');
+      expect(body.requested).toBe(`tool:${toolName}`);
+    },
+  );
+
+  it.each(REMOTE_CALLABLE_TOOL_NAMES)(
+    'POST /tools/%s with a privileged-profile token (tool:*) returns 200',
+    async (toolName) => {
+      const identity = issueWorkspaceProfileIdentity(
+        {
+          workspace_id: 'ws-wu-2729',
+          org_id: 'org-wu-2729',
+          agent_id: 'agent-wu-2729',
+        },
+        {
+          profile: 'privileged',
+          workspaceRoot: process.cwd(),
+        },
+      );
+      const runtime = {
+        executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+      };
+      const router = createToolApiRouter(runtime as never, {
+        allowlistedTools: [...REMOTE_CALLABLE_TOOL_NAMES],
+      });
+      const request = createRequest({
+        method: HTTP_METHOD.POST,
+        body: { input: {}, context: createContext() },
+        authorization: `Bearer ${identity.token}`,
+      });
+      const response = new MockResponse();
+
+      await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+        toolName,
+      ]);
+
+      expect(runtime.executeTool).toHaveBeenCalled();
+      expect(response.statusCode).toBe(HTTP_STATUS.OK);
+    },
+  );
+});