vellum 0.2.7 → 0.2.9

package/src/__tests__/ingress-url-consistency.test.ts

@@ -0,0 +1,214 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+import { createHmac } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Mocks — silence logger output during tests
+// ---------------------------------------------------------------------------
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of ['info', 'warn', 'error', 'debug', 'trace', 'fatal', 'silent', 'child']) {
+    stub[m] = m === 'child' ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+import {
+  getPublicBaseUrl,
+  getTwilioVoiceWebhookUrl,
+  getTwilioStatusCallbackUrl,
+  type IngressConfig,
+} from '../inbound/public-ingress-urls.js';
+
+// ---------------------------------------------------------------------------
+// Helpers — simulate Twilio signature validation the same way the gateway does
+// ---------------------------------------------------------------------------
+
+/**
+ * Reproduce the gateway's canonical URL reconstruction logic from
+ * gateway/src/twilio/validate-webhook.ts (lines 72-76).
+ */
+function reconstructGatewayCanonicalUrl(
+  ingressPublicBaseUrl: string | undefined,
+  requestUrl: string,
+): string {
+  const parsedUrl = new URL(requestUrl);
+  if (ingressPublicBaseUrl) {
+    return ingressPublicBaseUrl.replace(/\/$/, '') + parsedUrl.pathname + parsedUrl.search;
+  }
+  return requestUrl;
+}
+
+/**
+ * Reproduce Twilio's HMAC-SHA1 signature algorithm (same as
+ * gateway/src/twilio/verify.ts).
+ */
+function computeTwilioSignature(
+  url: string,
+  params: Record<string, string>,
+  authToken: string,
+): string {
+  const sortedKeys = Object.keys(params).sort();
+  let data = url;
+  for (const key of sortedKeys) {
+    data += key + params[key];
+  }
+  return createHmac('sha1', authToken).update(data).digest('base64');
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Ingress URL consistency between assistant and gateway', () => {
+  let savedIngressEnv: string | undefined;
+
+  beforeEach(() => {
+    savedIngressEnv = process.env.INGRESS_PUBLIC_BASE_URL;
+    delete process.env.INGRESS_PUBLIC_BASE_URL;
+  });
+
+  afterEach(() => {
+    if (savedIngressEnv !== undefined) {
+      process.env.INGRESS_PUBLIC_BASE_URL = savedIngressEnv;
+    } else {
+      delete process.env.INGRESS_PUBLIC_BASE_URL;
+    }
+  });
+
+  test('assistant callback URL and gateway signature reconstruction use same base when config is set', () => {
+    const config: IngressConfig = {
+      ingress: { publicBaseUrl: 'https://my-tunnel.ngrok.io' },
+    };
+
+    // What the assistant would generate as the Twilio voice webhook callback
+    const assistantCallbackUrl = getTwilioVoiceWebhookUrl(config, 'session-abc');
+
+    // Simulate: when hatch.ts spawns the gateway, it reads config.ingress.publicBaseUrl
+    // and passes it as INGRESS_PUBLIC_BASE_URL. The gateway stores this as
+    // config.ingressPublicBaseUrl.
+    const gatewayIngressPublicBaseUrl = getPublicBaseUrl(config);
+
+    // When Twilio calls the gateway, the gateway reconstructs the canonical URL
+    // from the inbound request URL (which is localhost) + the configured base.
+    const inboundRequestUrl = 'http://127.0.0.1:7830/webhooks/twilio/voice?callSessionId=session-abc';
+    const gatewayCanonicalUrl = reconstructGatewayCanonicalUrl(
+      gatewayIngressPublicBaseUrl,
+      inboundRequestUrl,
+    );
+
+    // Both must resolve to the same URL for Twilio signatures to validate
+    expect(gatewayCanonicalUrl).toBe(assistantCallbackUrl);
+  });
+
+  test('Twilio signature computed against assistant URL validates at gateway', () => {
+    const publicBase = 'https://my-tunnel.ngrok.io';
+    const authToken = 'test-twilio-auth-token-12345';
+    const config: IngressConfig = {
+      ingress: { publicBaseUrl: publicBase },
+    };
+
+    // Assistant generates the callback URL and registers it with Twilio
+    const callbackUrl = getTwilioStatusCallbackUrl(config);
+    expect(callbackUrl).toBe('https://my-tunnel.ngrok.io/webhooks/twilio/status');
+
+    // Twilio signs the request using the callback URL
+    const params = { CallSid: 'CA123', CallStatus: 'completed' };
+    const twilioSignature = computeTwilioSignature(callbackUrl, params, authToken);
+
+    // Gateway receives the request on its local address
+    const localRequestUrl = 'http://127.0.0.1:7830/webhooks/twilio/status';
+
+    // Gateway reconstructs the canonical URL using its configured base
+    // (which was passed from the assistant's config via INGRESS_PUBLIC_BASE_URL)
+    const gatewayIngressPublicBaseUrl = getPublicBaseUrl(config);
+    const canonicalUrl = reconstructGatewayCanonicalUrl(
+      gatewayIngressPublicBaseUrl,
+      localRequestUrl,
+    );
+
+    // Verify the signature matches
+    const recomputedSignature = computeTwilioSignature(canonicalUrl, params, authToken);
+    expect(recomputedSignature).toBe(twilioSignature);
+  });
+
+  test('mismatch scenario: gateway without config creates signature validation failure', () => {
+    const authToken = 'test-twilio-auth-token-12345';
+
+    // Assistant uses config-based URL
+    const assistantConfig: IngressConfig = {
+      ingress: { publicBaseUrl: 'https://my-tunnel.ngrok.io' },
+    };
+    const callbackUrl = getTwilioStatusCallbackUrl(assistantConfig);
+
+    // Twilio signs against the callback URL the assistant registered
+    const params = { CallSid: 'CA123', CallStatus: 'completed' };
+    const twilioSignature = computeTwilioSignature(callbackUrl, params, authToken);
+
+    // Gateway does NOT have the ingress URL configured (simulating the bug)
+    const localRequestUrl = 'http://127.0.0.1:7830/webhooks/twilio/status';
+    const canonicalUrlWithout = reconstructGatewayCanonicalUrl(undefined, localRequestUrl);
+
+    // Signature should NOT match — this proves the mismatch bug
+    const recomputedWithout = computeTwilioSignature(canonicalUrlWithout, params, authToken);
+    expect(recomputedWithout).not.toBe(twilioSignature);
+
+    // Now simulate the fix: gateway has the same ingress URL
+    const canonicalUrlWith = reconstructGatewayCanonicalUrl(
+      'https://my-tunnel.ngrok.io',
+      localRequestUrl,
+    );
+    const recomputedWith = computeTwilioSignature(canonicalUrlWith, params, authToken);
+    expect(recomputedWith).toBe(twilioSignature);
+  });
+
+  test('env var fallback produces consistent URLs across assistant and gateway', () => {
+    // When no config.ingress.publicBaseUrl is set, both assistant and gateway
+    // fall back to the INGRESS_PUBLIC_BASE_URL env var.
+    process.env.INGRESS_PUBLIC_BASE_URL = 'https://env-tunnel.example.com';
+
+    const config: IngressConfig = {};
+
+    // Assistant resolves the base URL from env
+    const assistantBase = getPublicBaseUrl(config);
+    expect(assistantBase).toBe('https://env-tunnel.example.com');
+
+    // Gateway would also read the same env var (process.env.INGRESS_PUBLIC_BASE_URL)
+    // and store it as config.ingressPublicBaseUrl.
+    const gatewayIngressPublicBaseUrl = process.env.INGRESS_PUBLIC_BASE_URL;
+
+    // Callback URL generated by assistant
+    const callbackUrl = getTwilioVoiceWebhookUrl(config, 'session-xyz');
+
+    // Gateway canonical URL reconstruction
+    const localUrl = 'http://127.0.0.1:7830/webhooks/twilio/voice?callSessionId=session-xyz';
+    const gatewayCanonical = reconstructGatewayCanonicalUrl(
+      gatewayIngressPublicBaseUrl,
+      localUrl,
+    );
+
+    expect(gatewayCanonical).toBe(callbackUrl);
+  });
+
+  test('trailing slashes are normalized consistently', () => {
+    const config: IngressConfig = {
+      ingress: { publicBaseUrl: 'https://my-tunnel.ngrok.io///' },
+    };
+
+    const assistantBase = getPublicBaseUrl(config);
+    expect(assistantBase).toBe('https://my-tunnel.ngrok.io');
+
+    const callbackUrl = getTwilioVoiceWebhookUrl(config, 'session-1');
+
+    // Gateway would receive the normalized value (hatch.ts trims trailing slashes)
+    const gatewayBase = 'https://my-tunnel.ngrok.io';
+    const localUrl = 'http://127.0.0.1:7830/webhooks/twilio/voice?callSessionId=session-1';
+    const gatewayCanonical = reconstructGatewayCanonicalUrl(gatewayBase, localUrl);
+
+    expect(gatewayCanonical).toBe(callbackUrl);
+  });
+});

package/src/__tests__/ipc-snapshot.test.ts

@@ -339,8 +339,8 @@ const clientMessages: Record<ClientMessageType, ClientMessage> = {
     type: 'slack_webhook_config',
     action: 'get',
   },
-  twilio_webhook_config: {
-    type: 'twilio_webhook_config',
+  ingress_config: {
+    type: 'ingress_config',
     action: 'get',
   },
   vercel_api_config: {
@@ -892,6 +892,11 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
     title: 'Urgent email from Alice',
     body: 'Meeting rescheduled to 3pm today.',
   },
+  agent_heartbeat_alert: {
+    type: 'agent_heartbeat_alert',
+    title: 'Agent heartbeat stalled',
+    body: 'No activity detected in the last 60 minutes.',
+  },
   watch_started: {
     type: 'watch_started',
     sessionId: 'sess-001',
@@ -1129,9 +1134,10 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
     webhookUrl: 'https://hooks.slack.com/services/T00/B00/xxx',
     success: true,
   },
-  twilio_webhook_config_response: {
-    type: 'twilio_webhook_config_response',
-    webhookBaseUrl: 'https://example.com/twilio',
+  ingress_config_response: {
+    type: 'ingress_config_response',
+    publicBaseUrl: 'https://example.com',
+    localGatewayTarget: 'http://127.0.0.1:7830',
     success: true,
   },
   vercel_api_config_response: {
@@ -1408,6 +1414,12 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
   open_tasks_window: {
     type: 'open_tasks_window',
   },
+  task_run_thread_created: {
+    type: 'task_run_thread_created',
+    conversationId: 'conv-task-run-001',
+    workItemId: 'wi-001',
+    title: 'Process report',
+  },
   subagent_spawned: {
     type: 'subagent_spawned',
     subagentId: 'sub-001',

package/src/__tests__/oauth-callback-registry.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect, afterEach } from 'bun:test';
+import {
+  registerPendingCallback,
+  consumeCallback,
+  consumeCallbackError,
+  clearAllCallbacks,
+} from '../security/oauth-callback-registry.js';
+
+afterEach(() => {
+  clearAllCallbacks();
+});
+
+describe('OAuth callback registry', () => {
+  test('registerPendingCallback + consumeCallback resolves with code', async () => {
+    const promise = new Promise<string>((resolve, reject) => {
+      registerPendingCallback('state-1', resolve, reject);
+    });
+
+    const consumed = consumeCallback('state-1', 'auth-code-123');
+    expect(consumed).toBe(true);
+
+    const code = await promise;
+    expect(code).toBe('auth-code-123');
+  });
+
+  test('consumeCallback with unknown state returns false', () => {
+    const consumed = consumeCallback('nonexistent', 'code');
+    expect(consumed).toBe(false);
+  });
+
+  test('consumeCallbackError rejects the pending callback', async () => {
+    const promise = new Promise<string>((resolve, reject) => {
+      registerPendingCallback('state-err', resolve, reject);
+    });
+
+    const consumed = consumeCallbackError('state-err', 'access_denied');
+    expect(consumed).toBe(true);
+
+    await expect(promise).rejects.toThrow('access_denied');
+  });
+
+  test('consumeCallbackError with unknown state returns false', () => {
+    const consumed = consumeCallbackError('nonexistent', 'some error');
+    expect(consumed).toBe(false);
+  });
+
+  test('duplicate consumeCallback returns false on second call', async () => {
+    const promise = new Promise<string>((resolve, reject) => {
+      registerPendingCallback('state-dup', resolve, reject);
+    });
+
+    const first = consumeCallback('state-dup', 'code-1');
+    expect(first).toBe(true);
+
+    const second = consumeCallback('state-dup', 'code-2');
+    expect(second).toBe(false);
+
+    const code = await promise;
+    expect(code).toBe('code-1');
+  });
+
+  test('TTL expiry rejects callback with timeout error', async () => {
+    const promise = new Promise<string>((resolve, reject) => {
+      registerPendingCallback('state-ttl', resolve, reject, 50);
+    });
+
+    // Wait for the TTL to expire
+    await new Promise((r) => setTimeout(r, 100));
+
+    await expect(promise).rejects.toThrow('OAuth callback timed out');
+
+    // After expiry, consume should return false
+    const consumed = consumeCallback('state-ttl', 'late-code');
+    expect(consumed).toBe(false);
+  });
+
+  test('clearAllCallbacks cleans up all pending entries', () => {
+    registerPendingCallback('s1', () => {}, () => {});
+    registerPendingCallback('s2', () => {}, () => {});
+    clearAllCallbacks();
+
+    expect(consumeCallback('s1', 'code')).toBe(false);
+    expect(consumeCallback('s2', 'code')).toBe(false);
+  });
+});

package/src/__tests__/oauth2-gateway-transport.test.ts

@@ -0,0 +1,304 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Mocks — must be set up before importing the module under test
+// ---------------------------------------------------------------------------
+
+let mockPublicBaseUrl = '';
+
+mock.module('../config/loader.js', () => ({
+  loadConfig: () => ({
+    ingress: { publicBaseUrl: mockPublicBaseUrl },
+  }),
+  getConfig: () => ({
+    ingress: { publicBaseUrl: mockPublicBaseUrl },
+  }),
+  loadRawConfig: () => ({}),
+  saveConfig: () => {},
+  invalidateConfigCache: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+    trace: () => {},
+    fatal: () => {},
+    child: () => ({
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }),
+  }),
+}));
+
+// Track registerPendingCallback calls
+let pendingCallbacks: Map<string, { resolve: (code: string) => void; reject: (error: Error) => void }> = new Map();
+
+mock.module('../security/oauth-callback-registry.js', () => ({
+  registerPendingCallback: (state: string, resolve: (code: string) => void, reject: (error: Error) => void) => {
+    pendingCallbacks.set(state, { resolve, reject });
+  },
+  consumeCallback: () => true,
+  consumeCallbackError: () => true,
+  clearAllCallbacks: () => { pendingCallbacks.clear(); },
+}));
+
+let mockOAuthCallbackUrl = '';
+
+mock.module('../inbound/public-ingress-urls.js', () => ({
+  getOAuthCallbackUrl: () => mockOAuthCallbackUrl,
+  getPublicBaseUrl: (config?: { ingress?: { publicBaseUrl?: string } }) => {
+    const url = config?.ingress?.publicBaseUrl ?? mockPublicBaseUrl;
+    if (!url) {
+      throw new Error('No public base URL configured.');
+    }
+    return url;
+  },
+}));
+
+// Mock fetch for token exchange
+let mockTokenResponse: { ok: boolean; status: number; body: Record<string, unknown> } = {
+  ok: true,
+  status: 200,
+  body: {
+    access_token: 'test-access-token',
+    refresh_token: 'test-refresh-token',
+    expires_in: 3600,
+    scope: 'read write',
+    token_type: 'Bearer',
+  },
+};
+
+const originalFetch = globalThis.fetch;
+globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+  const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+  if (url.includes('token')) {
+    if (!mockTokenResponse.ok) {
+      return new Response(JSON.stringify({ error: 'invalid_grant' }), {
+        status: mockTokenResponse.status,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response(JSON.stringify(mockTokenResponse.body), {
+      status: mockTokenResponse.status,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+  return originalFetch(input, init);
+}) as typeof fetch;
+
+// ---------------------------------------------------------------------------
+// Import module under test AFTER mocks are in place
+// ---------------------------------------------------------------------------
+
+import { startOAuth2Flow, type OAuth2Config } from '../security/oauth2.js';
+
+const BASE_OAUTH_CONFIG: OAuth2Config = {
+  authUrl: 'https://provider.example.com/authorize',
+  tokenUrl: 'https://provider.example.com/token',
+  scopes: ['read', 'write'],
+  clientId: 'test-client-id',
+};
+
+beforeEach(() => {
+  mockPublicBaseUrl = '';
+  mockOAuthCallbackUrl = 'https://gw.example.com/webhooks/oauth/callback';
+  pendingCallbacks.clear();
+  mockTokenResponse = {
+    ok: true,
+    status: 200,
+    body: {
+      access_token: 'test-access-token',
+      refresh_token: 'test-refresh-token',
+      expires_in: 3600,
+      scope: 'read write',
+      token_type: 'Bearer',
+    },
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('OAuth2 gateway transport', () => {
+  describe('auto-detection', () => {
+    test('selects gateway transport when ingress.publicBaseUrl is configured', async () => {
+      mockPublicBaseUrl = 'https://gw.example.com';
+
+      let capturedAuthUrl = '';
+      const flowPromise = startOAuth2Flow(BASE_OAUTH_CONFIG, {
+        openUrl: (url) => { capturedAuthUrl = url; },
+      });
+
+      // Give the flow a tick to register the callback and open the browser
+      await new Promise((r) => setTimeout(r, 10));
+
+      // The auth URL should contain the gateway redirect_uri, not a loopback one
+      expect(capturedAuthUrl).toContain('redirect_uri=');
+      expect(capturedAuthUrl).not.toContain('127.0.0.1');
+      expect(capturedAuthUrl).toContain(encodeURIComponent('https://gw.example.com'));
+
+      // Resolve the pending callback to complete the flow
+      const entries = Array.from(pendingCallbacks.entries());
+      expect(entries.length).toBe(1);
+      const [, { resolve }] = entries[0];
+      resolve('auth-code-from-gateway');
+
+      const result = await flowPromise;
+      expect(result.tokens.accessToken).toBe('test-access-token');
+    });
+
+    test('selects loopback transport when ingress.publicBaseUrl is empty', async () => {
+      mockPublicBaseUrl = '';
+
+      let capturedAuthUrl = '';
+      const flowPromise = startOAuth2Flow(BASE_OAUTH_CONFIG, {
+        openUrl: (url) => { capturedAuthUrl = url; },
+      });
+
+      // Give the flow a tick
+      await new Promise((r) => setTimeout(r, 10));
+
+      // The auth URL should contain a loopback redirect_uri
+      expect(capturedAuthUrl).toContain('redirect_uri=');
+      expect(capturedAuthUrl).toContain('127.0.0.1');
+
+      // Extract the redirect_uri to send the callback
+      const authUrlParsed = new URL(capturedAuthUrl);
+      const redirectUri = authUrlParsed.searchParams.get('redirect_uri')!;
+      const stateParam = authUrlParsed.searchParams.get('state')!;
+
+      // Simulate the OAuth provider callback to the loopback server
+      const callbackUrl = `${redirectUri}?code=loopback-code&state=${stateParam}`;
+      await fetch(callbackUrl);
+
+      const result = await flowPromise;
+      expect(result.tokens.accessToken).toBe('test-access-token');
+    });
+  });
+
+  describe('explicit transport', () => {
+    test('uses gateway transport when explicitly specified', async () => {
+      // Even with no publicBaseUrl, explicit gateway should work
+      mockPublicBaseUrl = 'https://gw.example.com';
+
+      let capturedAuthUrl = '';
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: (url) => { capturedAuthUrl = url; } },
+        { callbackTransport: 'gateway' },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(capturedAuthUrl).toContain(encodeURIComponent('https://gw.example.com'));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      expect(entries.length).toBe(1);
+      entries[0][1].resolve('explicit-gateway-code');
+
+      const result = await flowPromise;
+      expect(result.tokens.accessToken).toBe('test-access-token');
+    });
+
+    test('uses loopback transport when explicitly specified', async () => {
+      // Even with publicBaseUrl configured, explicit loopback should work
+      mockPublicBaseUrl = 'https://gw.example.com';
+
+      let capturedAuthUrl = '';
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: (url) => { capturedAuthUrl = url; } },
+        { callbackTransport: 'loopback' },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(capturedAuthUrl).toContain('127.0.0.1');
+
+      const authUrlParsed = new URL(capturedAuthUrl);
+      const redirectUri = authUrlParsed.searchParams.get('redirect_uri')!;
+      const stateParam = authUrlParsed.searchParams.get('state')!;
+
+      await fetch(`${redirectUri}?code=loopback-code&state=${stateParam}`);
+
+      const result = await flowPromise;
+      expect(result.tokens.accessToken).toBe('test-access-token');
+    });
+  });
+
+  describe('gateway transport flow', () => {
+    test('success: register callback, consume with code, exchange for tokens', async () => {
+      mockPublicBaseUrl = 'https://gw.example.com';
+
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: () => {} },
+        { callbackTransport: 'gateway' },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      // A callback should be registered
+      const entries = Array.from(pendingCallbacks.entries());
+      expect(entries.length).toBe(1);
+
+      // Simulate gateway delivering the authorization code
+      const [state, { resolve }] = entries[0];
+      expect(typeof state).toBe('string');
+      expect(state.length).toBeGreaterThan(0);
+
+      resolve('gateway-auth-code');
+
+      const result = await flowPromise;
+      expect(result.tokens.accessToken).toBe('test-access-token');
+      expect(result.tokens.refreshToken).toBe('test-refresh-token');
+      expect(result.tokens.expiresIn).toBe(3600);
+      expect(result.grantedScopes).toEqual(['read', 'write']);
+    });
+
+    test('error: register callback, consume with error, rejects', async () => {
+      mockPublicBaseUrl = 'https://gw.example.com';
+
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: () => {} },
+        { callbackTransport: 'gateway' },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      expect(entries.length).toBe(1);
+
+      // Simulate the gateway delivering an error (e.g. user denied access)
+      const [, { reject }] = entries[0];
+      reject(new Error('OAuth2 authorization denied: access_denied'));
+
+      await expect(flowPromise).rejects.toThrow('OAuth2 authorization denied: access_denied');
+    });
+
+    test('token exchange failure propagates error', async () => {
+      mockPublicBaseUrl = 'https://gw.example.com';
+      mockTokenResponse = { ok: false, status: 400, body: { error: 'invalid_grant' } };
+
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: () => {} },
+        { callbackTransport: 'gateway' },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve('code-that-fails-exchange');
+
+      await expect(flowPromise).rejects.toThrow('OAuth2 token exchange failed');
+    });
+  });
+});