vellum 0.2.7 → 0.2.8

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,298 @@
+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: () => 'https://gw.example.com',
+}));
+
+// 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');
+    });
+  });
+});

package/src/__tests__/provider-commit-message-generator.test.ts

@@ -262,34 +262,51 @@ describe('ProviderCommitMessageGenerator', () => {
     expect(result.reason).toBe('invalid_output');
   });
 
-  // 11. LLM output too long (subject > 72 chars)
-  test('LLM output too long (subject > 72 chars) → returns deterministic, reason "invalid_output"', async () => {
-    const longSubject = 'a'.repeat(73);
+  // 11. LLM subject > 72 chars → truncated to 72, still source "llm"
+  test('LLM subject > 72 chars → truncated to 72, source "llm"', async () => {
+    const longSubject = 'a'.repeat(100);
     mockSendMessage.mockResolvedValueOnce(makeSuccessResponse(longSubject));
     const gen = getCommitMessageGenerator();
     const result = await gen.generateCommitMessage(baseContext, {
       changedFiles: baseContext.changedFiles,
     });
-    expect(result.source).toBe('deterministic');
-    expect(result.reason).toBe('invalid_output');
+    expect(result.source).toBe('llm');
+    expect(result.reason).toBeUndefined();
+    expect(result.message.split('\n')[0].length).toBeLessThanOrEqual(72);
+    expect(result.message).toBe('a'.repeat(72));
   });
 
-  // 12. Keyless provider (Ollama) skips API key preflight
-  test('Ollama without API key → does not return missing_provider_api_key', async () => {
+  // 11b. LLM subject > 72 chars with body → subject truncated, body preserved
+  test('LLM subject > 72 chars with body → subject truncated, body preserved', async () => {
+    const longSubject = 'b'.repeat(80);
+    const body = '\n\n- bullet one\n- bullet two';
+    mockSendMessage.mockResolvedValueOnce(makeSuccessResponse(longSubject + body));
+    const gen = getCommitMessageGenerator();
+    const result = await gen.generateCommitMessage(baseContext, {
+      changedFiles: baseContext.changedFiles,
+    });
+    expect(result.source).toBe('llm');
+    expect(result.reason).toBeUndefined();
+    expect(result.message.split('\n')[0].length).toBeLessThanOrEqual(72);
+    expect(result.message).toBe('b'.repeat(72) + body);
+  });
+
+  // 12. Keyless provider (Ollama) without fast model → missing_fast_model (skips API key check)
+  test('Ollama without API key or fast model → returns deterministic, reason "missing_fast_model"', async () => {
     (currentConfig as Record<string, unknown>).provider = 'ollama';
     currentConfig.apiKeys = {} as Record<string, string>;
-    // Ollama has no default fast model, so it will fall through to provider_error,
-    // but crucially it should NOT be blocked by missing_provider_api_key
     const gen = getCommitMessageGenerator();
     const result = await gen.generateCommitMessage(baseContext, {
       changedFiles: baseContext.changedFiles,
     });
     expect(result.source).toBe('deterministic');
+    expect(result.reason).toBe('missing_fast_model');
     expect(result.reason).not.toBe('missing_provider_api_key');
+    expect(mockSendMessage).not.toHaveBeenCalled();
   });
 
-  // 13. No default fast model for unknown provider
-  test('No default fast model for unknown provider → returns deterministic fallback', async () => {
+  // 13. Unknown provider without fast model default → missing_fast_model, no provider call
+  test('Unknown provider without fast model default → returns deterministic, reason "missing_fast_model"', async () => {
     (currentConfig as Record<string, unknown>).provider = 'exotic-provider';
     currentConfig.apiKeys = { 'exotic-provider': 'sk-exotic' } as Record<string, string>;
     const gen = getCommitMessageGenerator();
@@ -297,7 +314,29 @@ describe('ProviderCommitMessageGenerator', () => {
       changedFiles: baseContext.changedFiles,
     });
     expect(result.source).toBe('deterministic');
-    expect(result.reason).toBe('provider_error');
+    expect(result.reason).toBe('missing_fast_model');
     expect(mockSendMessage).not.toHaveBeenCalled();
   });
+
+  // 14. Fast-model override enables LLM path for provider without built-in default
+  test('fast-model override enables LLM path for provider without built-in default', async () => {
+    (currentConfig as Record<string, unknown>).provider = 'ollama';
+    currentConfig.apiKeys = {} as Record<string, string>; // Ollama is keyless
+    currentConfig.workspaceGit.commitMessageLLM.providerFastModelOverrides = {
+      ollama: 'llama3.2:3b',
+    };
+    const commitMsg = 'fix: local model commit';
+    mockSendMessage.mockResolvedValueOnce(makeSuccessResponse(commitMsg));
+    const gen = getCommitMessageGenerator();
+    const result = await gen.generateCommitMessage(baseContext, {
+      changedFiles: baseContext.changedFiles,
+    });
+    expect(result.source).toBe('llm');
+    expect(result.message).toBe(commitMsg);
+
+    // Verify the override model was passed
+    const callArgs = mockSendMessage.mock.calls[0];
+    const options = callArgs[3] as { config: { model: string } };
+    expect(options.config.model).toBe('llama3.2:3b');
+  });
 });

package/src/__tests__/public-ingress-urls.test.ts

@@ -0,0 +1,206 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// 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,
+  getTwilioConnectActionUrl,
+  getTwilioRelayUrl,
+  getOAuthCallbackUrl,
+} from '../inbound/public-ingress-urls.js';
+
+// ---------------------------------------------------------------------------
+// getPublicBaseUrl — fallback chain
+// ---------------------------------------------------------------------------
+
+describe('getPublicBaseUrl', () => {
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedEnv = process.env.TWILIO_WEBHOOK_BASE_URL;
+    delete process.env.TWILIO_WEBHOOK_BASE_URL;
+  });
+
+  afterEach(() => {
+    if (savedEnv !== undefined) {
+      process.env.TWILIO_WEBHOOK_BASE_URL = savedEnv;
+    } else {
+      delete process.env.TWILIO_WEBHOOK_BASE_URL;
+    }
+  });
+
+  test('prefers ingress.publicBaseUrl when set', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: 'https://ingress.example.com/' },
+      calls: { webhookBaseUrl: 'https://calls.example.com' },
+    });
+    expect(result).toBe('https://ingress.example.com');
+  });
+
+  test('falls back to calls.webhookBaseUrl when ingress.publicBaseUrl is empty', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '' },
+      calls: { webhookBaseUrl: 'https://calls.example.com/' },
+    });
+    expect(result).toBe('https://calls.example.com');
+  });
+
+  test('falls back to calls.webhookBaseUrl when ingress is undefined', () => {
+    const result = getPublicBaseUrl({
+      calls: { webhookBaseUrl: 'https://calls.example.com' },
+    });
+    expect(result).toBe('https://calls.example.com');
+  });
+
+  test('falls back to TWILIO_WEBHOOK_BASE_URL env var when both config fields are empty', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com/';
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '' },
+      calls: { webhookBaseUrl: '' },
+    });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('falls back to env var when config fields are undefined', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getPublicBaseUrl({});
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('throws when no source provides a value', () => {
+    expect(() => getPublicBaseUrl({
+      ingress: { publicBaseUrl: '' },
+      calls: { webhookBaseUrl: '' },
+    })).toThrow(/No public base URL configured/);
+  });
+
+  test('throws when all sources are undefined', () => {
+    expect(() => getPublicBaseUrl({})).toThrow(/No public base URL configured/);
+  });
+
+  test('normalizes trailing slashes from ingress.publicBaseUrl', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: 'https://example.com///' },
+    });
+    expect(result).toBe('https://example.com');
+  });
+
+  test('trims whitespace from ingress.publicBaseUrl', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '  https://example.com  ' },
+    });
+    expect(result).toBe('https://example.com');
+  });
+
+  test('skips whitespace-only ingress.publicBaseUrl and falls through', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '   ' },
+      calls: { webhookBaseUrl: 'https://calls.example.com' },
+    });
+    expect(result).toBe('https://calls.example.com');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioVoiceWebhookUrl
+// ---------------------------------------------------------------------------
+
+describe('getTwilioVoiceWebhookUrl', () => {
+  test('builds correct URL with callSessionId', () => {
+    const url = getTwilioVoiceWebhookUrl(
+      { ingress: { publicBaseUrl: 'https://example.com' } },
+      'session-123',
+    );
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=session-123');
+  });
+
+  test('normalizes base URL before composing', () => {
+    const url = getTwilioVoiceWebhookUrl(
+      { ingress: { publicBaseUrl: 'https://example.com/' } },
+      'abc',
+    );
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=abc');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioStatusCallbackUrl
+// ---------------------------------------------------------------------------
+
+describe('getTwilioStatusCallbackUrl', () => {
+  test('builds correct URL', () => {
+    const url = getTwilioStatusCallbackUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('https://example.com/webhooks/twilio/status');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioConnectActionUrl
+// ---------------------------------------------------------------------------
+
+describe('getTwilioConnectActionUrl', () => {
+  test('builds correct URL', () => {
+    const url = getTwilioConnectActionUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('https://example.com/webhooks/twilio/connect-action');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioRelayUrl — scheme conversion
+// ---------------------------------------------------------------------------
+
+describe('getTwilioRelayUrl', () => {
+  test('converts https to wss', () => {
+    const url = getTwilioRelayUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('wss://example.com/webhooks/twilio/relay');
+  });
+
+  test('converts http to ws', () => {
+    const url = getTwilioRelayUrl({
+      ingress: { publicBaseUrl: 'http://localhost:7821' },
+    });
+    expect(url).toBe('ws://localhost:7821/webhooks/twilio/relay');
+  });
+
+  test('normalizes trailing slash before conversion', () => {
+    const url = getTwilioRelayUrl({
+      ingress: { publicBaseUrl: 'https://example.com/' },
+    });
+    expect(url).toBe('wss://example.com/webhooks/twilio/relay');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getOAuthCallbackUrl
+// ---------------------------------------------------------------------------
+
+describe('getOAuthCallbackUrl', () => {
+  test('builds correct URL', () => {
+    const url = getOAuthCallbackUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('https://example.com/webhooks/oauth/callback');
+  });
+});