@lumenflow/surfaces 5.1.0

package/http/__tests__/scope-enforcement.test.ts

@@ -0,0 +1,349 @@
+// 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 { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { issueControlPlaneIdentity } from '../../../control-plane-sdk/src/authenticate.js';
+import { issueWorkspaceProfileIdentity, readWorkspaceSurfaceAuthConfig } from '../auth.js';
+import { createToolApiRouter } from '../tool-api.js';
+
+const HTTP_METHOD = {
+  POST: 'POST',
+} as const;
+
+const HTTP_STATUS = {
+  OK: 200,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+} as const;
+
+const TOOL_NAME = {
+  ORCHESTRATE_INITIATIVE: 'orchestrate:initiative',
+  WU_DELETE: 'wu:delete',
+} as const;
+
+const IDENTITY_INPUT = {
+  workspace_id: 'workspace-test',
+  org_id: 'org-test',
+  agent_id: 'agent-test',
+} 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;
+  }
+}
+
+function createRequest(options: { body: unknown; token?: 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': 'application/json; charset=utf-8',
+    ...(options.token
+      ? {
+          authorization: `Bearer ${options.token}`,
+        }
+      : {}),
+  };
+
+  (request as unknown as PassThrough).end(JSON.stringify(options.body));
+  return request;
+}
+
+function createContext() {
+  return {
+    run_id: 'run-tool-api',
+    task_id: 'WU-tool-api',
+    session_id: 'session-tool-api',
+    allowed_scopes: [],
+  };
+}
+
+function parseBody(body: string): Record<string, unknown> {
+  return JSON.parse(body) as Record<string, unknown>;
+}
+
+describe('http tool scope enforcement', () => {
+  it('rejects POST /tools/:name with no Authorization header (WU-2779 security fix)', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ORCHESTRATE_INITIATIVE, TOOL_NAME.WU_DELETE],
+    });
+
+    const request = createRequest({
+      // deliberately no token
+      body: { input: {}, context: createContext() },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.WU_DELETE,
+    ]);
+
+    // Tool must NOT dispatch when no Authorization header is present.
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    // 401 UNAUTHORIZED — missing credentials, not a scope denial.
+    expect(response.statusCode).toBe(HTTP_STATUS.UNAUTHORIZED);
+    const body = parseBody(response.body);
+    expect(body).toEqual(
+      expect.objectContaining({
+        error: 'missing_authorization',
+      }),
+    );
+  });
+
+  it('returns 403 missing_scopes when a mobile token targets wu:delete', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ORCHESTRATE_INITIATIVE, TOOL_NAME.WU_DELETE],
+    });
+    const mobileIdentity = issueControlPlaneIdentity(IDENTITY_INPUT, {
+      profile: 'mobile',
+      now: '2026-04-17T12:00:00.000Z',
+      profiles: {
+        mobile: {
+          ttl_seconds: 60 * 60 * 24,
+          scopes: ['tool:orchestrate:initiative'],
+        },
+      },
+    });
+
+    const request = createRequest({
+      token: mobileIdentity.token,
+      body: { input: {}, context: createContext() },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.WU_DELETE,
+    ]);
+
+    expect(runtime.executeTool).not.toHaveBeenCalled();
+    expect(response.statusCode).toBe(HTTP_STATUS.FORBIDDEN);
+    const body = parseBody(response.body);
+    expect(body).toEqual(
+      expect.objectContaining({
+        error: 'missing_scopes',
+        required: ['tool:wu:delete'],
+        granted: ['tool:orchestrate:initiative'],
+        requested: 'tool:wu:delete',
+        held: ['tool:orchestrate:initiative'],
+      }),
+    );
+    expect(body.hint).toEqual(expect.stringContaining('tool:wu:delete'));
+  });
+
+  it('allows a privileged token to invoke orchestrate:initiative as well as wu:delete', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ORCHESTRATE_INITIATIVE, TOOL_NAME.WU_DELETE],
+    });
+    const privilegedIdentity = issueControlPlaneIdentity(IDENTITY_INPUT, {
+      scopes: ['tool:*'],
+      now: '2026-04-17T12:00:00.000Z',
+      ttl_seconds: 60,
+    });
+
+    const orchestrateResponse = new MockResponse();
+    await router.handleRequest(
+      createRequest({
+        token: privilegedIdentity.token,
+        body: { input: { initiativeId: 'INIT-057' }, context: createContext() },
+      }),
+      orchestrateResponse as unknown as ServerResponse<IncomingMessage>,
+      [TOOL_NAME.ORCHESTRATE_INITIATIVE],
+    );
+
+    const deleteResponse = new MockResponse();
+    await router.handleRequest(
+      createRequest({
+        token: privilegedIdentity.token,
+        body: { input: {}, context: createContext() },
+      }),
+      deleteResponse as unknown as ServerResponse<IncomingMessage>,
+      [TOOL_NAME.WU_DELETE],
+    );
+
+    expect(orchestrateResponse.statusCode).toBe(HTTP_STATUS.OK);
+    expect(deleteResponse.statusCode).toBe(HTTP_STATUS.OK);
+    expect(runtime.executeTool).toHaveBeenCalledTimes(2);
+    expect(runtime.executeTool).toHaveBeenNthCalledWith(
+      1,
+      TOOL_NAME.ORCHESTRATE_INITIATIVE,
+      { initiativeId: 'INIT-057' },
+      createContext(),
+    );
+    expect(runtime.executeTool).toHaveBeenNthCalledWith(
+      2,
+      TOOL_NAME.WU_DELETE,
+      {},
+      createContext(),
+    );
+  });
+
+  it('allows exact-scope mobile access to orchestrate:initiative', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ORCHESTRATE_INITIATIVE, TOOL_NAME.WU_DELETE],
+    });
+    const mobileIdentity = issueControlPlaneIdentity(IDENTITY_INPUT, {
+      profile: 'mobile',
+      now: '2026-04-17T12:00:00.000Z',
+      profiles: {
+        mobile: {
+          ttl_seconds: 60 * 60 * 24,
+          scopes: ['tool:orchestrate:initiative'],
+        },
+      },
+    });
+
+    const request = createRequest({
+      token: mobileIdentity.token,
+      body: { input: { initiativeId: 'INIT-057' }, context: createContext() },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      TOOL_NAME.ORCHESTRATE_INITIATIVE,
+    ]);
+
+    expect(runtime.executeTool).toHaveBeenCalledWith(
+      TOOL_NAME.ORCHESTRATE_INITIATIVE,
+      { initiativeId: 'INIT-057' },
+      createContext(),
+    );
+    expect(response.statusCode).toBe(HTTP_STATUS.OK);
+  });
+
+  it('allows privileged wildcard and pack wildcard tokens, and keeps legacy opaque tokens working', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+    };
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [TOOL_NAME.ORCHESTRATE_INITIATIVE, TOOL_NAME.WU_DELETE],
+    });
+
+    const privilegedIdentity = issueControlPlaneIdentity(IDENTITY_INPUT, {
+      scopes: ['tool:*'],
+      now: '2026-04-17T12:00:00.000Z',
+      ttl_seconds: 60,
+    });
+    const packWildcardIdentity = issueControlPlaneIdentity(IDENTITY_INPUT, {
+      scopes: ['tool:wu:*'],
+      now: '2026-04-17T12:00:00.000Z',
+      ttl_seconds: 60,
+    });
+
+    const privilegedResponse = new MockResponse();
+    await router.handleRequest(
+      createRequest({
+        token: privilegedIdentity.token,
+        body: { input: {}, context: createContext() },
+      }),
+      privilegedResponse as unknown as ServerResponse<IncomingMessage>,
+      [TOOL_NAME.WU_DELETE],
+    );
+
+    const packWildcardResponse = new MockResponse();
+    await router.handleRequest(
+      createRequest({
+        token: packWildcardIdentity.token,
+        body: { input: {}, context: createContext() },
+      }),
+      packWildcardResponse as unknown as ServerResponse<IncomingMessage>,
+      [TOOL_NAME.WU_DELETE],
+    );
+
+    const legacyResponse = new MockResponse();
+    await router.handleRequest(
+      createRequest({
+        token: 'legacy-opaque-bearer',
+        body: { input: {}, context: createContext() },
+      }),
+      legacyResponse as unknown as ServerResponse<IncomingMessage>,
+      [TOOL_NAME.WU_DELETE],
+    );
+
+    expect(runtime.executeTool).toHaveBeenCalledTimes(3);
+    expect(privilegedResponse.statusCode).toBe(HTTP_STATUS.OK);
+    expect(packWildcardResponse.statusCode).toBe(HTTP_STATUS.OK);
+    expect(legacyResponse.statusCode).toBe(HTTP_STATUS.OK);
+  });
+
+  it('reads profile scopes from workspace.yaml overrides', () => {
+    const workspaceRoot = mkdtempSync(path.join(tmpdir(), 'lumenflow-auth-config-'));
+    writeFileSync(
+      path.join(workspaceRoot, 'workspace.yaml'),
+      [
+        'software_delivery:',
+        '  surfaces:',
+        '    auth:',
+        '      allow_legacy_unscoped_tokens: false',
+        '      profiles:',
+        '        mobile:',
+        '          ttl_seconds: 900',
+        '          scopes:',
+        '            - tool:wu:status',
+        '        privileged:',
+        '          ttl_seconds: 1800',
+        '          scopes:',
+        '            - tool:wu:*',
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+
+    const config = readWorkspaceSurfaceAuthConfig(workspaceRoot);
+    expect(config.allow_legacy_unscoped_tokens).toBe(false);
+    expect(config.profiles.mobile).toEqual({
+      ttl_seconds: 900,
+      scopes: ['tool:wu:status'],
+    });
+
+    const identity = issueWorkspaceProfileIdentity(IDENTITY_INPUT, {
+      profile: 'mobile',
+      now: '2026-04-17T12:00:00.000Z',
+      workspaceRoot,
+    });
+
+    expect(identity.scopes).toEqual(['tool:wu:status']);
+    expect(identity.expires_at).toBe('2026-04-17T12:15:00.000Z');
+  });
+});

package/http/__tests__/sidecar-entry.test.ts

@@ -0,0 +1,158 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * WU-2642 (INIT-057 Phase 4): Sidecar entry for control-plane event sync.
+ *
+ * `startControlPlaneEventSync` must be importable without booting
+ * `createHttpSurface`, and must expose a clean `dispose()` that stops its
+ * interval timer (so `wu:done` / `session-end` can shut the sidecar down
+ * without leaking handles).
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import type { KernelEvent } from '@lumenflow/kernel';
+import {
+  startControlPlaneEventSync,
+  type StartControlPlaneEventSyncOptions,
+} from '../sidecar-entry.js';
+import type { ControlPlaneSyncPortLike } from '../control-plane-event-subscriber.js';
+
+const WORKSPACE_ID = 'workspace-sidecar-test';
+const SYNC_INTERVAL_MS = 10;
+const INTERVAL_STEP_MS = 12;
+
+type PullPoliciesInput = Parameters<ControlPlaneSyncPortLike['pullPolicies']>[0];
+type HeartbeatInput = Parameters<ControlPlaneSyncPortLike['heartbeat']>[0];
+type PushEventsInput = Parameters<ControlPlaneSyncPortLike['pushKernelEvents']>[0];
+
+function createFakeControlPlane(): {
+  port: ControlPlaneSyncPortLike;
+  calls: {
+    pulls: PullPoliciesInput[];
+    heartbeats: HeartbeatInput[];
+    pushes: PushEventsInput[];
+  };
+} {
+  const calls = {
+    pulls: [] as PullPoliciesInput[],
+    heartbeats: [] as HeartbeatInput[],
+    pushes: [] as PushEventsInput[],
+  };
+
+  const port: ControlPlaneSyncPortLike = {
+    async pullPolicies(input) {
+      calls.pulls.push(input);
+      return { default_decision: 'allow', rules: [] };
+    },
+    async heartbeat(input) {
+      calls.heartbeats.push(input);
+      return { status: 'ok', server_time: new Date().toISOString() };
+    },
+    async pushKernelEvents(input) {
+      calls.pushes.push(input);
+      return { accepted: input.events.length };
+    },
+  };
+
+  return { port, calls };
+}
+
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('startControlPlaneEventSync (WU-2642)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('does not require createHttpSurface to run', async () => {
+    // AC2: startControlPlaneEventSync is importable from @lumenflow/surfaces/http
+    // without requiring createHttpSurface. The import at the top of this file
+    // proves importability; this assertion proves it is also callable with a
+    // minimal options object (no KernelRuntime, no HTTP server).
+    const { port } = createFakeControlPlane();
+    const options: StartControlPlaneEventSyncOptions = {
+      controlPlaneSyncPort: port,
+      workspaceId: WORKSPACE_ID,
+      syncIntervalMs: SYNC_INTERVAL_MS,
+    };
+
+    const handle = startControlPlaneEventSync(options);
+    expect(typeof handle.dispose).toBe('function');
+    handle.dispose();
+  });
+
+  it('polls the control plane on the configured cadence and stops on dispose', async () => {
+    // AC1/AC4: the sidecar syncs on a configurable cadence (default 30s, but
+    // overridable via sync_interval). We fake-tick INTERVAL_STEP_MS twice and
+    // expect two heartbeats; then dispose, tick again, and expect no more.
+    const { port, calls } = createFakeControlPlane();
+    const handle = startControlPlaneEventSync({
+      controlPlaneSyncPort: port,
+      workspaceId: WORKSPACE_ID,
+      syncIntervalMs: SYNC_INTERVAL_MS,
+    });
+
+    await vi.advanceTimersByTimeAsync(INTERVAL_STEP_MS);
+    await flushMicrotasks();
+    await vi.advanceTimersByTimeAsync(INTERVAL_STEP_MS);
+    await flushMicrotasks();
+
+    expect(calls.heartbeats.length).toBeGreaterThanOrEqual(2);
+    expect(calls.heartbeats[0].workspace_id).toBe(WORKSPACE_ID);
+
+    const heartbeatsBeforeDispose = calls.heartbeats.length;
+    handle.dispose();
+
+    await vi.advanceTimersByTimeAsync(INTERVAL_STEP_MS * 3);
+    await flushMicrotasks();
+
+    // AC3: wu:done / session-end stops the sidecar cleanly (no more polls).
+    expect(calls.heartbeats.length).toBe(heartbeatsBeforeDispose);
+  });
+
+  it('forwards queued events through pushKernelEvents on the next tick', async () => {
+    // AC5: Integration seam — an event enqueued to the sidecar must reach the
+    // fake control plane on the next sync tick. This is how wu:claim-era
+    // state changes propagate to cloud in sub-minute cadence.
+    const { port, calls } = createFakeControlPlane();
+    const handle = startControlPlaneEventSync({
+      controlPlaneSyncPort: port,
+      workspaceId: WORKSPACE_ID,
+      syncIntervalMs: SYNC_INTERVAL_MS,
+    });
+
+    const event: KernelEvent = {
+      schema_version: 1,
+      kind: 'workspace_warning',
+      timestamp: new Date().toISOString(),
+      message: 'test event from sidecar',
+    } as KernelEvent;
+
+    handle.enqueue(event);
+
+    await vi.advanceTimersByTimeAsync(INTERVAL_STEP_MS);
+    await flushMicrotasks();
+
+    const pushedKinds = calls.pushes.flatMap((call) => call.events.map((e) => e.kind));
+    expect(pushedKinds).toContain('workspace_warning');
+
+    handle.dispose();
+  });
+
+  it('does not import createHttpSurface (ADR-058 sidecar mode)', async () => {
+    // AC2 structural: the sidecar module must not transitively pull in the
+    // full HttpSurface stack (server.ts, run-agent, task-api). This keeps the
+    // sidecar cheap to spawn from wu:claim.
+    const sidecarModule = await import('../sidecar-entry.js');
+    expect(sidecarModule).not.toHaveProperty('createHttpSurface');
+  });
+});