vellum 0.2.13 → 0.2.14

package/src/__tests__/twilio-routes.test.ts

@@ -1,15 +1,19 @@
 /**
  * Integration tests for Twilio webhook route handlers.
  *
+ * Tests handler-level behavior by calling route handlers directly (not via HTTP
+ * server). Gateway-only blocking of direct webhook routes is covered in the
+ * dedicated `gateway-only-enforcement.test.ts` suite.
+ *
  * Tests:
- * - Gateway-only blocking of direct webhook routes (signature validation
- *   is now handled at the gateway, not the runtime)
  * - Duplicate callback replay (idempotency)
  * - Unknown status and malformed payload handling
+ * - Status mapping and completion notifications
+ * - resolveRelayUrl unit behavior
+ * - Voice webhook TwiML relay URL generation
  * - Handler-level idempotency concurrency (concurrent duplicates, failure-retry)
  */
 import { describe, test, expect, beforeEach, afterAll, mock, spyOn } from 'bun:test';
-import { createHmac } from 'node:crypto';
 import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -46,57 +50,19 @@ mock.module('../config/loader.js', () => ({
   }),
 }));
 
-// Configurable mock auth token — tests can switch between configured/unconfigured
-let mockAuthToken: string | undefined = 'test-auth-token-for-webhooks';
-
 mock.module('../security/secure-keys.js', () => ({
-  getSecureKey: (account: string) => {
-    if (account === 'credential:twilio:auth_token') return mockAuthToken;
-    return undefined;
-  },
+  getSecureKey: () => undefined,
 }));
 
-// Use the real TwilioConversationRelayProvider (not mocked) for signature validation
-// but mock the instance methods that hit Twilio API
-mock.module('../calls/twilio-provider.js', () => {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { createHmac: createHmacNode } = require('node:crypto');
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { timingSafeEqual: timingSafeEqualNode } = require('node:crypto');
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { getSecureKey } = require('../security/secure-keys.js');
-
-  return {
-    TwilioConversationRelayProvider: class {
-      readonly name = 'twilio';
-
-      static getAuthToken(): string | null {
-        return getSecureKey('credential:twilio:auth_token') ?? null;
-      }
-
-      static verifyWebhookSignature(
-        url: string,
-        params: Record<string, string>,
-        signature: string,
-        authToken: string,
-      ): boolean {
-        const sortedKeys = Object.keys(params).sort();
-        let data = url;
-        for (const key of sortedKeys) {
-          data += key + params[key];
-        }
-        const computed = createHmacNode('sha1', authToken).update(data).digest('base64');
-        const a = Buffer.from(computed);
-        const b = Buffer.from(signature);
-        if (a.length !== b.length) return false;
-        return timingSafeEqualNode(a, b);
-      }
-
-      async initiateCall() { return { callSid: 'CA_mock_test' }; }
-      async endCall() { return; }
-    },
-  };
-});
+mock.module('../calls/twilio-provider.js', () => ({
+  TwilioConversationRelayProvider: class {
+    readonly name = 'twilio';
+    static getAuthToken(): string | null { return null; }
+    static verifyWebhookSignature(): boolean { return true; }
+    async initiateCall() { return { callSid: 'CA_mock_test' }; }
+    async endCall() { return; }
+  },
+}));
 
 // Configurable mock Twilio config — tests can override wssBaseUrl
 let mockWssBaseUrl: string = 'wss://test.example.com';
@@ -114,7 +80,6 @@ mock.module('../calls/twilio-config.js', () => ({
 
 import { initializeDb, getDb, resetDb } from '../memory/db.js';
 import { conversations } from '../memory/schema.js';
-import { RuntimeHttpServer } from '../runtime/http-server.js';
 import * as callStore from '../calls/call-store.js';
 import {
   createCallSession,
@@ -129,9 +94,6 @@ initializeDb();
 
 // ── Helpers ────────────────────────────────────────────────────────────
 
-const TEST_TOKEN = 'test-bearer-token-twilio-routes';
-const AUTH_TOKEN = 'test-auth-token-for-webhooks';
-
 let ensuredConvIds = new Set<string>();
 
 function ensureConversation(id: string): void {
@@ -157,19 +119,6 @@ function resetTables() {
   ensuredConvIds = new Set();
 }
 
-function computeSignature(
-  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');
-}
-
 function createTestSession(convId: string, callSid: string) {
   ensureConversation(convId);
   const session = createCallSession({
@@ -202,15 +151,10 @@ function makeVoiceRequest(sessionId: string, params: Record<string, string>): Re
 // ── Tests ──────────────────────────────────────────────────────────────
 
 describe('twilio webhook routes', () => {
-  let server: RuntimeHttpServer;
-  let port: number;
-
   beforeEach(() => {
     resetTables();
-    mockAuthToken = AUTH_TOKEN;
     mockWssBaseUrl = 'wss://test.example.com';
     mockWebhookBaseUrl = 'https://test.example.com';
-    delete process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED;
   });
 
   afterAll(() => {
@@ -218,195 +162,6 @@ describe('twilio webhook routes', () => {
     try { rmSync(testDir, { recursive: true, force: true }); } catch { /* best effort */ }
   });
 
-  async function startServer(): Promise<void> {
-    server = new RuntimeHttpServer({ port: 0, bearerToken: TEST_TOKEN });
-    await server.start();
-    port = server.actualPort;
-  }
-
-  async function stopServer(): Promise<void> {
-    await server?.stop();
-  }
-
-  function statusUrl(): string {
-    return `http://127.0.0.1:${port}/v1/calls/twilio/status`;
-  }
-
-  function buildFormBody(params: Record<string, string>): string {
-    return new URLSearchParams(params).toString();
-  }
-
-  function signedRequest(
-    url: string,
-    params: Record<string, string>,
-  ): { body: string; headers: Record<string, string> } {
-    const body = buildFormBody(params);
-    const sig = computeSignature(url, params, AUTH_TOKEN);
-    return {
-      body,
-      headers: {
-        'Content-Type': 'application/x-www-form-urlencoded',
-        'X-Twilio-Signature': sig,
-      },
-    };
-  }
-
-  // ── Gateway-only blocking tests ───────────────────────────────────
-  // Direct Twilio webhook routes are blocked in gateway-only mode.
-  // Signature validation is now handled at the gateway level, not the runtime.
-
-  describe('gateway-only blocking of direct webhook routes', () => {
-    test('direct status callback returns 410', async () => {
-      await startServer();
-      const url = statusUrl();
-      const params = { CallSid: 'CA_sig_valid', CallStatus: 'completed' };
-      const { body, headers } = signedRequest(url, params);
-
-      const res = await fetch(url, { method: 'POST', headers, body });
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-
-    test('direct status callback without signature returns 410', async () => {
-      await startServer();
-      const url = statusUrl();
-      const params = { CallSid: 'CA_no_sig', CallStatus: 'completed' };
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-
-    test('direct status callback with invalid signature returns 410', async () => {
-      await startServer();
-      const url = statusUrl();
-      const params = { CallSid: 'CA_bad_sig', CallStatus: 'completed' };
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/x-www-form-urlencoded',
-          'X-Twilio-Signature': 'totally-wrong-signature',
-        },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-
-    test('direct status callback with wrong token signature returns 410', async () => {
-      await startServer();
-      const url = statusUrl();
-      const params = { CallSid: 'CA_wrong_token', CallStatus: 'completed' };
-      computeSignature(url, params, 'wrong-auth-token');
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/x-www-form-urlencoded',
-          'X-Twilio-Signature': computeSignature(url, params, 'wrong-auth-token'),
-        },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-  });
-
-  // ── Fail-closed behavior ──────────────────────────────────────────
-
-  describe('fail-closed when auth token missing', () => {
-    test('direct route returns 410 regardless of auth token config', async () => {
-      mockAuthToken = undefined;
-      await startServer();
-
-      const url = statusUrl();
-      const params = { CallSid: 'CA_no_token', CallStatus: 'completed' };
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-  });
-
-  // ── TWILIO_WEBHOOK_VALIDATION_DISABLED bypass ─────────────────────
-
-  describe('validation disabled env flag', () => {
-    test('direct route returns 410 even when validation disabled', async () => {
-      process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = 'true';
-      mockAuthToken = undefined;
-      await startServer();
-
-      const url = statusUrl();
-      const params = { CallSid: 'CA_bypass', CallStatus: 'completed' };
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-
-    test('direct route returns 410 when env var is non-true value', async () => {
-      process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = '1';
-      mockAuthToken = undefined;
-      await startServer();
-
-      const url = statusUrl();
-      const params = { CallSid: 'CA_no_bypass', CallStatus: 'completed' };
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-
-    test('direct route returns 410 when env var is empty string', async () => {
-      process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = '';
-      mockAuthToken = undefined;
-      await startServer();
-
-      const url = statusUrl();
-      const params = { CallSid: 'CA_empty_env', CallStatus: 'completed' };
-
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: buildFormBody(params),
-      });
-
-      expect(res.status).toBe(410);
-
-      await stopServer();
-    });
-  });
-
   // ── Callback idempotency / replay tests ───────────────────────────
   // These call handleStatusCallback directly (bypassing the HTTP server)
   // since direct routes are blocked by gateway-only mode.

package/src/__tests__/twitter-auth-handler.test.ts

@@ -144,6 +144,7 @@ import type {
   TwitterAuthStatusRequest,
   ServerMessage,
 } from '../daemon/ipc-contract.js';
+import { DebouncerMap } from '../util/debounce.js';
 
 // Mock global fetch for Twitter /2/users/me
 const _originalFetch = globalThis.fetch;
@@ -162,7 +163,7 @@ function createTestContext(): { ctx: HandlerContext; sent: ServerMessage[] } {
     cuObservationParseSequence: new Map(),
     socketSandboxOverride: new Map(),
     sharedRequestTimestamps: [],
-    debounceTimers: new Map(),
+    debounceTimers: new DebouncerMap({ defaultDelayMs: 200 }),
     suppressConfigReload: false,
     setSuppressConfigReload: () => {},
     updateConfigFingerprint: () => {},

package/src/__tests__/twitter-cli-error-shaping.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Tests for CLI error-shaping logic in the `run()` helper of twitter.ts.
+ *
+ * These tests verify that structured router metadata (pathUsed,
+ * suggestAlternative, oauthError) is preserved in CLI output while
+ * maintaining backward-compatible error codes.
+ */
+import { describe, test, expect } from 'bun:test';
+import { SessionExpiredError } from '../twitter/client.js';
+
+// ---------------------------------------------------------------------------
+// We test the error-shaping logic directly by reproducing the branching in
+// the CLI `run()` function. The actual `run()` function writes to stdout and
+// sets process.exitCode, which makes it awkward to test in isolation. Instead
+// we extract the payload-building logic into a pure helper and verify its
+// output here.
+// ---------------------------------------------------------------------------
+
+const SESSION_EXPIRED_MSG =
+  'Your Twitter session has expired. Please sign in to Twitter in Chrome — ' +
+  'run `vellum twitter refresh` to capture your session automatically.';
+
+/**
+ * Replicates the error-to-payload logic from `run()` in twitter.ts.
+ * Returns the JSON payload that would be written to stdout.
+ */
+function buildErrorPayload(err: unknown): Record<string, unknown> | null {
+  const meta = err as Record<string, unknown>;
+
+  if (err instanceof SessionExpiredError) {
+    const payload: Record<string, unknown> = {
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+    };
+    if (meta.pathUsed !== undefined) payload.pathUsed = meta.pathUsed;
+    if (meta.suggestAlternative !== undefined) payload.suggestAlternative = meta.suggestAlternative;
+    if (meta.oauthError !== undefined) payload.oauthError = meta.oauthError;
+    return payload;
+  }
+
+  if (err instanceof Error && (meta.pathUsed !== undefined || meta.suggestAlternative !== undefined || meta.oauthError !== undefined)) {
+    const payload: Record<string, unknown> = {
+      ok: false,
+      error: err.message,
+    };
+    if (meta.pathUsed !== undefined) payload.pathUsed = meta.pathUsed;
+    if (meta.suggestAlternative !== undefined) payload.suggestAlternative = meta.suggestAlternative;
+    if (meta.oauthError !== undefined) payload.oauthError = meta.oauthError;
+    return payload;
+  }
+
+  // Generic fallback
+  return { ok: false, error: err instanceof Error ? err.message : String(err) };
+}
+
+describe('CLI error shaping', () => {
+  test('plain SessionExpiredError preserves backward-compatible error code', () => {
+    const err = new SessionExpiredError('No Twitter session found.');
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+    });
+  });
+
+  test('SessionExpiredError from browser path preserves pathUsed and suggestAlternative', () => {
+    const err = Object.assign(new SessionExpiredError('Session cookies expired'), {
+      pathUsed: 'browser' as const,
+      suggestAlternative: 'oauth' as const,
+    });
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+      pathUsed: 'browser',
+      suggestAlternative: 'oauth',
+    });
+  });
+
+  test('SessionExpiredError from auto path preserves pathUsed and oauthError', () => {
+    const err = Object.assign(new SessionExpiredError('Session cookies expired'), {
+      pathUsed: 'auto' as const,
+      oauthError: 'Token revoked',
+    });
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'session_expired',
+      message: SESSION_EXPIRED_MSG,
+      pathUsed: 'auto',
+      oauthError: 'Token revoked',
+    });
+  });
+
+  test('routed non-session error with suggestAlternative emits structured JSON', () => {
+    const err = Object.assign(
+      new Error('OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy.'),
+      {
+        pathUsed: 'oauth' as const,
+        suggestAlternative: 'browser' as const,
+      },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy.',
+      pathUsed: 'oauth',
+      suggestAlternative: 'browser',
+    });
+  });
+
+  test('routed auto-mode error with oauthError and suggestAlternative', () => {
+    const err = Object.assign(
+      new Error('Both OAuth and browser paths failed'),
+      {
+        pathUsed: 'auto' as const,
+        suggestAlternative: 'browser' as const,
+        oauthError: 'Twitter API error (401)',
+      },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Both OAuth and browser paths failed',
+      pathUsed: 'auto',
+      suggestAlternative: 'browser',
+      oauthError: 'Twitter API error (401)',
+    });
+  });
+
+  test('auto-mode error with pathUsed and oauthError but no suggestAlternative preserves metadata', () => {
+    // This is the scenario flagged by Codex: routedPostTweet in auto mode tries
+    // OAuth (fails), then browser (fails with non-SessionExpiredError). The thrown
+    // error has pathUsed and oauthError but no suggestAlternative.
+    const err = Object.assign(
+      new Error('Browser automation failed: element not found'),
+      {
+        pathUsed: 'auto' as const,
+        oauthError: 'Twitter API error (401)',
+      },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Browser automation failed: element not found',
+      pathUsed: 'auto',
+      oauthError: 'Twitter API error (401)',
+    });
+  });
+
+  test('error with only pathUsed (no oauthError or suggestAlternative) preserves metadata', () => {
+    const err = Object.assign(
+      new Error('Something went wrong'),
+      { pathUsed: 'browser' as const },
+    );
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Something went wrong',
+      pathUsed: 'browser',
+    });
+  });
+
+  test('generic error without router metadata falls back to plain error', () => {
+    const err = new Error('Network connection failed');
+    const payload = buildErrorPayload(err);
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'Network connection failed',
+    });
+  });
+
+  test('non-Error value falls back to stringified error', () => {
+    const payload = buildErrorPayload('some string error');
+
+    expect(payload).toEqual({
+      ok: false,
+      error: 'some string error',
+    });
+  });
+
+  test('backward compatibility: session_expired error code is always preserved', () => {
+    // Even with metadata, the error code stays 'session_expired'
+    const err = Object.assign(new SessionExpiredError('expired'), {
+      pathUsed: 'auto' as const,
+      suggestAlternative: 'oauth' as const,
+      oauthError: 'token expired',
+    });
+    const payload = buildErrorPayload(err);
+
+    expect(payload!.error).toBe('session_expired');
+    expect(payload!.ok).toBe(false);
+    expect(payload!.pathUsed).toBe('auto');
+    expect(payload!.suggestAlternative).toBe('oauth');
+    expect(payload!.oauthError).toBe('token expired');
+  });
+});