@kb-labs/gateway-app 0.2.0

package/src/__tests__/subscription-registry.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Unit tests for SubscriptionRegistry (CC5 — Multi-Client Pub/Sub).
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SubscriptionRegistry } from '../clients/subscription-registry.js';
+import type { ExecutionEventMessage } from '@kb-labs/gateway-contracts';
+
+// Minimal WebSocket mock with configurable readyState
+function makeSocket(readyState = 1 /* OPEN */) {
+  return {
+    readyState,
+    OPEN: 1,
+    send: vi.fn(),
+  };
+}
+
+let registry: SubscriptionRegistry;
+
+beforeEach(() => {
+  registry = new SubscriptionRegistry();
+});
+
+// ── subscribe / unsubscribe ────────────────────────────────────────────────────
+
+describe('SubscriptionRegistry — subscribe / unsubscribe', () => {
+  it('subscribe adds to both indexes', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    expect(registry.getSubscribers('exec-1').has('conn-1')).toBe(true);
+    expect(registry.getSubscriptions('conn-1').has('exec-1')).toBe(true);
+  });
+
+  it('multiple connections can subscribe to same execution', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-2', 'exec-1');
+    const subs = registry.getSubscribers('exec-1');
+    expect(subs.has('conn-1')).toBe(true);
+    expect(subs.has('conn-2')).toBe(true);
+    expect(subs.size).toBe(2);
+  });
+
+  it('one connection can subscribe to multiple executions', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-1', 'exec-2');
+    const subs = registry.getSubscriptions('conn-1');
+    expect(subs.has('exec-1')).toBe(true);
+    expect(subs.has('exec-2')).toBe(true);
+    expect(subs.size).toBe(2);
+  });
+
+  it('subscribe is idempotent', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-1', 'exec-1');
+    expect(registry.getSubscribers('exec-1').size).toBe(1);
+    expect(registry.getSubscriptions('conn-1').size).toBe(1);
+  });
+
+  it('unsubscribe removes from both indexes', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.unsubscribe('conn-1', 'exec-1');
+    expect(registry.getSubscribers('exec-1').has('conn-1')).toBe(false);
+    expect(registry.getSubscriptions('conn-1').has('exec-1')).toBe(false);
+  });
+
+  it('unsubscribe GCs empty sets', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.unsubscribe('conn-1', 'exec-1');
+    // getSubscribers returns an empty set (not the internal one), but size should be 0
+    expect(registry.getSubscribers('exec-1').size).toBe(0);
+    expect(registry.getSubscriptions('conn-1').size).toBe(0);
+    // connectionCount and subscriptionCount reflect no data
+    expect(registry.connectionCount).toBe(0);
+    expect(registry.subscriptionCount).toBe(0);
+  });
+
+  it('unsubscribe only removes one connection, other subscribers remain', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-2', 'exec-1');
+    registry.unsubscribe('conn-1', 'exec-1');
+    const subs = registry.getSubscribers('exec-1');
+    expect(subs.has('conn-1')).toBe(false);
+    expect(subs.has('conn-2')).toBe(true);
+  });
+
+  it('unsubscribe on non-existent connection/execution does not throw', () => {
+    expect(() => registry.unsubscribe('ghost', 'exec-1')).not.toThrow();
+    expect(() => registry.unsubscribe('conn-1', 'ghost')).not.toThrow();
+  });
+});
+
+// ── registerSocket / removeSocket ─────────────────────────────────────────────
+
+describe('SubscriptionRegistry — registerSocket / removeSocket', () => {
+  it('registerSocket stores socket for broadcast', () => {
+    const socket = makeSocket();
+    registry.registerSocket('conn-1', socket as never);
+    registry.subscribe('conn-1', 'exec-1');
+
+    const event: ExecutionEventMessage = {
+      type: 'execution:output',
+      requestId: 'req-1',
+      executionId: 'exec-1',
+      stream: 'stdout',
+      data: 'hello',
+      timestamp: Date.now(),
+    };
+    registry.broadcast('exec-1', event);
+    expect(socket.send).toHaveBeenCalledTimes(1);
+  });
+
+  it('removeSocket prevents broadcast after removal', () => {
+    const socket = makeSocket();
+    registry.registerSocket('conn-1', socket as never);
+    registry.subscribe('conn-1', 'exec-1');
+    registry.removeSocket('conn-1');
+
+    const event: ExecutionEventMessage = {
+      type: 'execution:output',
+      requestId: 'req-1',
+      executionId: 'exec-1',
+      stream: 'stdout',
+      data: 'hello',
+      timestamp: Date.now(),
+    };
+    registry.broadcast('exec-1', event);
+    expect(socket.send).not.toHaveBeenCalled();
+  });
+});
+
+// ── broadcast ─────────────────────────────────────────────────────────────────
+
+describe('SubscriptionRegistry — broadcast', () => {
+  const makeEvent = (executionId: string): ExecutionEventMessage => ({
+    type: 'execution:output',
+    requestId: 'req-broadcast',
+    executionId,
+    stream: 'stdout',
+    data: 'output data',
+    timestamp: Date.now(),
+  });
+
+  it('broadcasts to all open subscribers', () => {
+    const s1 = makeSocket();
+    const s2 = makeSocket();
+    registry.registerSocket('conn-1', s1 as never);
+    registry.registerSocket('conn-2', s2 as never);
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-2', 'exec-1');
+
+    registry.broadcast('exec-1', makeEvent('exec-1'));
+    expect(s1.send).toHaveBeenCalledTimes(1);
+    expect(s2.send).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not broadcast to closed sockets', () => {
+    const open = makeSocket(1); // OPEN
+    const closed = makeSocket(3); // CLOSED
+    registry.registerSocket('conn-open', open as never);
+    registry.registerSocket('conn-closed', closed as never);
+    registry.subscribe('conn-open', 'exec-1');
+    registry.subscribe('conn-closed', 'exec-1');
+
+    registry.broadcast('exec-1', makeEvent('exec-1'));
+    expect(open.send).toHaveBeenCalledTimes(1);
+    expect(closed.send).not.toHaveBeenCalled();
+  });
+
+  it('does not broadcast to connections without a registered socket', () => {
+    registry.subscribe('conn-no-socket', 'exec-1');
+    // Should not throw
+    expect(() => registry.broadcast('exec-1', makeEvent('exec-1'))).not.toThrow();
+  });
+
+  it('broadcast sends JSON-serialised event', () => {
+    const socket = makeSocket();
+    registry.registerSocket('conn-1', socket as never);
+    registry.subscribe('conn-1', 'exec-1');
+
+    const event = makeEvent('exec-1');
+    registry.broadcast('exec-1', event);
+
+    const sent = JSON.parse((socket.send as ReturnType<typeof vi.fn>).mock.calls[0]![0] as string) as unknown;
+    expect(sent).toEqual(event);
+  });
+
+  it('broadcast to execution with no subscribers is a no-op', () => {
+    // Should not throw
+    expect(() => registry.broadcast('no-subscribers', makeEvent('no-subscribers'))).not.toThrow();
+  });
+
+  it('broadcast only reaches subscribers of the target execution', () => {
+    const s1 = makeSocket();
+    const s2 = makeSocket();
+    registry.registerSocket('conn-1', s1 as never);
+    registry.registerSocket('conn-2', s2 as never);
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-2', 'exec-2'); // different execution
+
+    registry.broadcast('exec-1', makeEvent('exec-1'));
+    expect(s1.send).toHaveBeenCalledTimes(1);
+    expect(s2.send).not.toHaveBeenCalled(); // unrelated subscriber
+  });
+});
+
+// ── removeConnection ──────────────────────────────────────────────────────────
+
+describe('SubscriptionRegistry — removeConnection', () => {
+  it('returns orphaned executionIds (those with zero subscribers after removal)', () => {
+    registry.subscribe('conn-1', 'exec-orphan');
+    const orphaned = registry.removeConnection('conn-1');
+    expect(orphaned).toContain('exec-orphan');
+  });
+
+  it('does not return executionId still subscribed by another connection', () => {
+    registry.subscribe('conn-1', 'exec-shared');
+    registry.subscribe('conn-2', 'exec-shared');
+    const orphaned = registry.removeConnection('conn-1');
+    expect(orphaned).not.toContain('exec-shared');
+  });
+
+  it('returns empty array if connection had no subscriptions', () => {
+    const orphaned = registry.removeConnection('ghost-conn');
+    expect(orphaned).toEqual([]);
+  });
+
+  it('cleans up all indexes for removed connection', () => {
+    const socket = makeSocket();
+    registry.registerSocket('conn-1', socket as never);
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-1', 'exec-2');
+
+    registry.removeConnection('conn-1');
+
+    expect(registry.connectionCount).toBe(0);
+    expect(registry.getSubscriptions('conn-1').size).toBe(0);
+    expect(registry.getSubscribers('exec-1').size).toBe(0);
+    expect(registry.getSubscribers('exec-2').size).toBe(0);
+  });
+
+  it('removes socket during removeConnection', () => {
+    const socket = makeSocket();
+    registry.registerSocket('conn-1', socket as never);
+    registry.subscribe('conn-1', 'exec-1');
+    registry.removeConnection('conn-1');
+
+    // Broadcast should not reach the removed socket
+    const event: ExecutionEventMessage = {
+      type: 'execution:output',
+      requestId: 'req-late',
+      executionId: 'exec-1',
+      stream: 'stdout',
+      data: 'late',
+      timestamp: Date.now(),
+    };
+    // exec-1 was orphaned and removed, but even if called directly it should not throw
+    registry.broadcast('exec-1', event);
+    expect(socket.send).not.toHaveBeenCalled();
+  });
+
+  it('returns orphaned list with multiple executions', () => {
+    registry.subscribe('conn-1', 'exec-a');
+    registry.subscribe('conn-1', 'exec-b');
+    // conn-2 also subscribes to exec-b → exec-b won't be orphaned
+    registry.subscribe('conn-2', 'exec-b');
+
+    const orphaned = registry.removeConnection('conn-1');
+    expect(orphaned).toContain('exec-a');
+    expect(orphaned).not.toContain('exec-b');
+  });
+});
+
+// ── connectionCount / subscriptionCount ───────────────────────────────────────
+
+describe('SubscriptionRegistry — metrics', () => {
+  it('connectionCount tracks unique connections with subscriptions', () => {
+    expect(registry.connectionCount).toBe(0);
+    registry.subscribe('conn-1', 'exec-1');
+    expect(registry.connectionCount).toBe(1);
+    registry.subscribe('conn-2', 'exec-1');
+    expect(registry.connectionCount).toBe(2);
+  });
+
+  it('subscriptionCount is the sum of all (connection, execution) pairs', () => {
+    expect(registry.subscriptionCount).toBe(0);
+    registry.subscribe('conn-1', 'exec-1');
+    expect(registry.subscriptionCount).toBe(1);
+    registry.subscribe('conn-1', 'exec-2');
+    expect(registry.subscriptionCount).toBe(2);
+    registry.subscribe('conn-2', 'exec-1');
+    expect(registry.subscriptionCount).toBe(3);
+  });
+
+  it('counts decrease after unsubscribe', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-1', 'exec-2');
+    registry.unsubscribe('conn-1', 'exec-1');
+    expect(registry.subscriptionCount).toBe(1);
+    expect(registry.connectionCount).toBe(1);
+  });
+
+  it('counts reset to 0 after all connections removed', () => {
+    registry.subscribe('conn-1', 'exec-1');
+    registry.subscribe('conn-2', 'exec-1');
+    registry.removeConnection('conn-1');
+    registry.removeConnection('conn-2');
+    expect(registry.connectionCount).toBe(0);
+    expect(registry.subscriptionCount).toBe(0);
+  });
+});

package/src/__tests__/telemetry-ingest.test.ts

@@ -0,0 +1,309 @@
+/**
+ * Integration tests for Telemetry Ingestion endpoint.
+ *
+ * Covers:
+ *   POST /telemetry/v1/ingest
+ *     - 401 without auth
+ *     - 400 with invalid body
+ *     - 400 with empty events array
+ *     - 503 when analytics not configured
+ *     - 200 single event ingest
+ *     - 200 batch ingest (multiple events)
+ *     - 200 with default timestamp when omitted
+ *     - 422 when all events fail
+ *     - Partial success (some accepted, some rejected)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import type { ICache, ILogger, IAnalytics } from '@kb-labs/core-platform';
+import type { JwtConfig } from '@kb-labs/gateway-auth';
+import { createAuthMiddleware } from '../auth/middleware.js';
+import { registerTelemetryRoutes } from '../telemetry/routes.js';
+
+// ── Mocks ─────────────────────────────────────────────────────────────────
+
+const mockAnalytics: IAnalytics = {
+  track: vi.fn(),
+  identify: vi.fn(),
+  flush: vi.fn(),
+};
+
+let analyticsEnabled = true;
+
+vi.mock('@kb-labs/core-runtime', () => ({
+  platform: {
+    get analytics() { return analyticsEnabled ? mockAnalytics : undefined; },
+  },
+}));
+
+function makeCache(): ICache {
+  const store = new Map<string, unknown>();
+  return {
+    async get<T>(k: string) { return (store.get(k) as T) ?? null; },
+    async set(k: string, v: unknown) { store.set(k, v); },
+    async delete(k: string) { store.delete(k); },
+    async clear() { store.clear(); },
+  } as unknown as ICache;
+}
+
+const noopLogger: ILogger = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn(),
+  child: vi.fn(() => noopLogger),
+} as unknown as ILogger;
+
+const stubJwtConfig: JwtConfig = { secret: 'test-secret' };
+const TEST_TOKEN = 'test-telemetry-token';
+const TEST_AUTH_HEADER = `Bearer ${TEST_TOKEN}`;
+
+// ── Test app builder ──────────────────────────────────────────────────────
+
+async function buildApp(): Promise<FastifyInstance> {
+  const cache = makeCache();
+  await cache.set(`host:token:${TEST_TOKEN}`, {
+    hostId: 'host-test',
+    namespaceId: 'ns-test',
+  });
+
+  const app = Fastify({ logger: false });
+  await app.register(async function scope(s) {
+    s.addHook('onRequest', createAuthMiddleware(cache, stubJwtConfig));
+    registerTelemetryRoutes(s as any, noopLogger);
+  });
+
+  await app.ready();
+  return app;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function makeIngestPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    events: [
+      {
+        source: 'my-product',
+        type: 'user.signup',
+        payload: { plan: 'pro' },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe('POST /telemetry/v1/ingest', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    analyticsEnabled = true;
+    app = await buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  // ── Auth ──────────────────────────────────────────────────────────────
+
+  it('returns 401 without auth token', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      payload: makeIngestPayload(),
+    });
+    expect(res.statusCode).toBe(401);
+  });
+
+  // ── Validation ────────────────────────────────────────────────────────
+
+  it('returns 400 with empty body', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('returns 400 with empty events array', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: { events: [] },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('returns 400 when event missing required source field', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: { events: [{ type: 'test' }] }, // missing source
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  // ── Analytics unavailable ─────────────────────────────────────────────
+
+  it('returns 503 when analytics adapter not configured', async () => {
+    analyticsEnabled = false;
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: makeIngestPayload(),
+    });
+    expect(res.statusCode).toBe(503);
+  });
+
+  // ── Happy path ────────────────────────────────────────────────────────
+
+  it('ingests single event and calls analytics.track()', async () => {
+    (mockAnalytics.track as any).mockResolvedValue(undefined);
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: makeIngestPayload(),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.accepted).toBe(1);
+    expect(body.rejected).toBe(0);
+
+    expect(mockAnalytics.track).toHaveBeenCalledTimes(1);
+    expect(mockAnalytics.track).toHaveBeenCalledWith(
+      'user.signup',
+      expect.objectContaining({
+        _source: 'my-product',
+        _tenantId: 'ns-test',
+        plan: 'pro',
+      }),
+    );
+  });
+
+  it('ingests batch of multiple events', async () => {
+    (mockAnalytics.track as any).mockResolvedValue(undefined);
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: {
+        events: [
+          { source: 'api', type: 'request', payload: { path: '/a' } },
+          { source: 'api', type: 'request', payload: { path: '/b' } },
+          { source: 'api', type: 'error', payload: { code: 500 } },
+        ],
+      },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.accepted).toBe(3);
+    expect(body.rejected).toBe(0);
+    expect(mockAnalytics.track).toHaveBeenCalledTimes(3);
+  });
+
+  it('uses current timestamp when event.timestamp is omitted', async () => {
+    (mockAnalytics.track as any).mockResolvedValue(undefined);
+
+    await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: makeIngestPayload(),
+    });
+
+    const trackCall = (mockAnalytics.track as any).mock.calls[0];
+    expect(trackCall[1]._ts).toBeDefined();
+    // Should be a valid ISO string
+    expect(new Date(trackCall[1]._ts).getTime()).toBeGreaterThan(0);
+  });
+
+  it('passes tags as flat properties', async () => {
+    (mockAnalytics.track as any).mockResolvedValue(undefined);
+
+    await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: {
+        events: [
+          {
+            source: 'my-app',
+            type: 'deploy',
+            tags: { env: 'prod', region: 'eu' },
+            payload: { version: '1.2.3' },
+          },
+        ],
+      },
+    });
+
+    expect(mockAnalytics.track).toHaveBeenCalledWith(
+      'deploy',
+      expect.objectContaining({
+        env: 'prod',
+        region: 'eu',
+        version: '1.2.3',
+      }),
+    );
+  });
+
+  // ── Error handling ────────────────────────────────────────────────────
+
+  it('returns 422 when all events fail', async () => {
+    (mockAnalytics.track as any).mockRejectedValue(new Error('DB write failed'));
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: makeIngestPayload(),
+    });
+
+    expect(res.statusCode).toBe(422);
+    const body = res.json();
+    expect(body.accepted).toBe(0);
+    expect(body.rejected).toBe(1);
+    expect(body.errors).toHaveLength(1);
+    expect(body.errors[0].message).toContain('DB write failed');
+  });
+
+  it('handles partial failure (some events succeed, some fail)', async () => {
+    let callCount = 0;
+    (mockAnalytics.track as any).mockImplementation(async () => {
+      callCount++;
+      if (callCount === 2) {throw new Error('Failed event 2');}
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/telemetry/v1/ingest',
+      headers: { authorization: TEST_AUTH_HEADER },
+      payload: {
+        events: [
+          { source: 'app', type: 'ok1' },
+          { source: 'app', type: 'fail' },
+          { source: 'app', type: 'ok2' },
+        ],
+      },
+    });
+
+    expect(res.statusCode).toBe(200); // partial success = 200
+    const body = res.json();
+    expect(body.accepted).toBe(2);
+    expect(body.rejected).toBe(1);
+    expect(body.errors).toHaveLength(1);
+    expect(body.errors[0].index).toBe(1);
+  });
+});

package/src/__tests__/tokens.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi } from 'vitest';
+import { resolveToken, extractBearerToken } from '../auth/tokens.js';
+import type { ICache } from '@kb-labs/core-platform';
+import type { JwtConfig } from '@kb-labs/gateway-auth';
+
+function makeCache(entries: Record<string, unknown> = {}): ICache {
+  return {
+    get: vi.fn(async (key: string) => entries[key] ?? null),
+    set: vi.fn(),
+    delete: vi.fn(),
+    clear: vi.fn(),
+  } as unknown as ICache;
+}
+
+describe('extractBearerToken', () => {
+  it('extracts token from Bearer header', () => {
+    expect(extractBearerToken('Bearer abc-123')).toBe('abc-123');
+  });
+
+  it('is case-insensitive', () => {
+    expect(extractBearerToken('bearer abc-123')).toBe('abc-123');
+    expect(extractBearerToken('BEARER abc-123')).toBe('abc-123');
+  });
+
+  it('returns null for missing header', () => {
+    expect(extractBearerToken(undefined)).toBeNull();
+  });
+
+  it('returns null for non-Bearer scheme', () => {
+    expect(extractBearerToken('Basic dXNlcjpwYXNz')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(extractBearerToken('')).toBeNull();
+  });
+
+  it('handles token with special characters', () => {
+    expect(extractBearerToken('Bearer 8d006616-9c5e-466f-a72f-1c6a6dc20a60')).toBe(
+      '8d006616-9c5e-466f-a72f-1c6a6dc20a60',
+    );
+  });
+});
+
+const stubJwtConfig: JwtConfig = { secret: 'test-secret' };
+
+describe('resolveToken', () => {
+  it('resolves machine token from cache', async () => {
+    const token = 'machine-token-uuid';
+    const cache = makeCache({
+      [`host:token:${token}`]: { hostId: 'host-1', namespaceId: 'ns-1' },
+    });
+
+    const ctx = await resolveToken(token, cache, stubJwtConfig);
+    expect(ctx).not.toBeNull();
+    expect(ctx!.type).toBe('machine');
+    expect(ctx!.userId).toBe('host-1');
+    expect(ctx!.namespaceId).toBe('ns-1');
+    expect(ctx!.permissions).toContain('host:connect');
+  });
+
+  it('returns null for unknown token (no CLI fallback)', async () => {
+    const cache = makeCache(); // no entries
+    const ctx = await resolveToken('some-unknown-token', cache, stubJwtConfig);
+    expect(ctx).toBeNull();
+  });
+
+  it('machine token resolves correctly, unknown token returns null', async () => {
+    const token = 'machine-uuid';
+    const cache = makeCache({ [`host:token:${token}`]: { hostId: 'h-1', namespaceId: 'ns-a' } });
+    const ctx = await resolveToken(token, cache, stubJwtConfig);
+    expect(ctx!.type).toBe('machine');
+
+    const unknown = await resolveToken('other-token', cache, stubJwtConfig);
+    expect(unknown).toBeNull();
+  });
+
+  it('checks correct cache key for machine token', async () => {
+    const token = 'test-token';
+    const cache = makeCache();
+    await resolveToken(token, cache, stubJwtConfig);
+    expect(cache.get).toHaveBeenCalledWith(`host:token:${token}`);
+  });
+});