@vellumai/assistant 0.3.0

package/src/tools/network/__tests__/web-search.test.ts

@@ -0,0 +1,427 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+
+// Mutable mock state — set per test
+let mockWebSearchProvider: string | undefined = 'perplexity';
+let mockBraveConfigKey: string | undefined;
+let mockPerplexityConfigKey: string | undefined;
+let mockBraveSecureKey: string | undefined;
+let mockPerplexitySecureKey: string | undefined;
+
+// Capture the registered tool
+let capturedTool: any = null;
+
+mock.module('../../registry.js', () => ({
+  registerTool: (tool: any) => { capturedTool = tool; },
+}));
+
+mock.module('../../../config/loader.js', () => ({
+  getConfig: () => ({
+    webSearchProvider: mockWebSearchProvider,
+    apiKeys: { brave: mockBraveConfigKey, perplexity: mockPerplexityConfigKey },
+  }),
+}));
+
+mock.module('../../../security/secure-keys.js', () => ({
+  getSecureKey: (provider: string) => {
+    if (provider === 'brave') return mockBraveSecureKey;
+    if (provider === 'perplexity') return mockPerplexitySecureKey;
+    return undefined;
+  },
+}));
+
+mock.module('../../../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../../../permissions/types.js', () => ({
+  RiskLevel: { Low: 'low', Medium: 'medium', High: 'high' },
+}));
+
+// Force the module to load (triggers registerTool)
+await import('../web-search.js');
+
+describe('web_search tool', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let savedBraveKey: string | undefined;
+  let savedPerplexityKey: string | undefined;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    mockWebSearchProvider = 'perplexity';
+    mockBraveConfigKey = undefined;
+    mockPerplexityConfigKey = undefined;
+    mockBraveSecureKey = undefined;
+    mockPerplexitySecureKey = undefined;
+
+    // Isolate from host env so getApiKey() doesn't short-circuit on real keys
+    savedBraveKey = process.env.BRAVE_API_KEY;
+    savedPerplexityKey = process.env.PERPLEXITY_API_KEY;
+    delete process.env.BRAVE_API_KEY;
+    delete process.env.PERPLEXITY_API_KEY;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+
+    if (savedBraveKey !== undefined) process.env.BRAVE_API_KEY = savedBraveKey;
+    else delete process.env.BRAVE_API_KEY;
+
+    if (savedPerplexityKey !== undefined) process.env.PERPLEXITY_API_KEY = savedPerplexityKey;
+    else delete process.env.PERPLEXITY_API_KEY;
+  });
+
+  function execute(input: Record<string, unknown>) {
+    return capturedTool.execute(input, {} as any);
+  }
+
+  // ---- Input validation ---------------------------------------------------
+
+  test('rejects missing query', async () => {
+    const result = await execute({});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('query is required');
+  });
+
+  test('rejects non-string query', async () => {
+    const result = await execute({ query: 42 });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('query is required');
+  });
+
+  // ---- No API key configured ----------------------------------------------
+
+  test('returns error when no API key is available', async () => {
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('No web search API key configured');
+  });
+
+  // ---- Perplexity provider ------------------------------------------------
+
+  test('executes Perplexity search successfully', async () => {
+    mockPerplexityConfigKey = 'pplx-test-key';
+    globalThis.fetch = (async (_url: string, _init?: RequestInit) => {
+      return new Response(JSON.stringify({
+        choices: [{ message: { content: 'Perplexity answer about TypeScript' } }],
+        citations: ['https://typescriptlang.org', 'https://example.com/ts'],
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as any;
+
+    const result = await execute({ query: 'what is TypeScript' });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('Perplexity answer about TypeScript');
+    expect(result.content).toContain('Sources:');
+    expect(result.content).toContain('typescriptlang.org');
+  });
+
+  test('Perplexity sends correct request format', async () => {
+    mockPerplexityConfigKey = 'pplx-test-key';
+    let capturedUrl = '';
+    let capturedBody: any = null;
+    let capturedHeaders: any = null;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      capturedUrl = url;
+      capturedBody = JSON.parse(init?.body as string);
+      capturedHeaders = new Headers(init?.headers);
+      return new Response(JSON.stringify({
+        choices: [{ message: { content: 'answer' } }],
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as any;
+
+    await execute({ query: 'test query' });
+    expect(capturedUrl).toContain('perplexity.ai');
+    expect(capturedBody.model).toBe('sonar');
+    expect(capturedBody.messages[0].content).toBe('test query');
+    expect(capturedHeaders.get('authorization')).toBe('Bearer pplx-test-key');
+  });
+
+  test('Perplexity returns no results message when response is empty', async () => {
+    mockPerplexityConfigKey = 'pplx-test-key';
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({ choices: [] }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    const result = await execute({ query: 'obscure query' });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('No results found');
+  });
+
+  test('Perplexity handles 401/403 auth errors', async () => {
+    mockPerplexityConfigKey = 'bad-key';
+    globalThis.fetch = (async () => {
+      return new Response('Unauthorized', { status: 401 });
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid or expired Perplexity API key');
+  });
+
+  test('Perplexity handles 429 rate limit after max retries', async () => {
+    mockPerplexityConfigKey = 'pplx-key';
+    let callCount = 0;
+    globalThis.fetch = (async () => {
+      callCount++;
+      return new Response('Too Many Requests', {
+        status: 429,
+        headers: { 'retry-after': '0' },
+      });
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('rate limit exceeded');
+    // 1 initial + 3 retries = 4 calls
+    expect(callCount).toBe(4);
+  });
+
+  test('Perplexity handles generic server error', async () => {
+    mockPerplexityConfigKey = 'pplx-key';
+    globalThis.fetch = (async () => {
+      return new Response('Internal Server Error', { status: 500 });
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('status 500');
+  });
+
+  // ---- Brave provider -----------------------------------------------------
+
+  test('executes Brave search successfully', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'brave-test-key';
+    globalThis.fetch = (async (_url: string) => {
+      return new Response(JSON.stringify({
+        web: {
+          results: [
+            { title: 'Result 1', url: 'https://example.com/1', description: 'First result', age: '2 days ago' },
+            { title: 'Result 2', url: 'https://example.com/2', description: 'Second result', extra_snippets: ['Extra info'] },
+          ],
+        },
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as any;
+
+    const result = await execute({ query: 'test search' });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('Result 1');
+    expect(result.content).toContain('https://example.com/1');
+    expect(result.content).toContain('2 days ago');
+    expect(result.content).toContain('Result 2');
+    expect(result.content).toContain('Extra info');
+  });
+
+  test('Brave sends correct query parameters', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'brave-key';
+    let capturedUrl = '';
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    await execute({ query: 'test query', count: 5, offset: 2, freshness: 'pw' });
+    const parsed = new URL(capturedUrl);
+    expect(parsed.searchParams.get('q')).toBe('test query');
+    expect(parsed.searchParams.get('count')).toBe('5');
+    expect(parsed.searchParams.get('offset')).toBe('2');
+    expect(parsed.searchParams.get('freshness')).toBe('pw');
+  });
+
+  test('Brave clamps count and offset', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'brave-key';
+    let capturedUrl = '';
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    await execute({ query: 'test', count: 100, offset: 50 });
+    const parsed = new URL(capturedUrl);
+    expect(parsed.searchParams.get('count')).toBe('20');
+    expect(parsed.searchParams.get('offset')).toBe('9');
+  });
+
+  test('Brave skips invalid freshness values', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'brave-key';
+    let capturedUrl = '';
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    await execute({ query: 'test', freshness: 'invalid' });
+    const parsed = new URL(capturedUrl);
+    expect(parsed.searchParams.has('freshness')).toBe(false);
+  });
+
+  test('Brave handles empty results', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'brave-key';
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    const result = await execute({ query: 'no results for this' });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('No results found');
+  });
+
+  test('Brave handles 401 auth error', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'bad-key';
+    globalThis.fetch = (async () => {
+      return new Response('Forbidden', { status: 403 });
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid or expired Brave Search API key');
+  });
+
+  test('Brave handles 429 rate limit with Retry-After header', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'brave-key';
+    let callCount = 0;
+    globalThis.fetch = (async () => {
+      callCount++;
+      if (callCount <= 3) {
+        return new Response('Rate Limited', {
+          status: 429,
+          headers: { 'retry-after': '0' },
+        });
+      }
+      return new Response(JSON.stringify({ web: { results: [{ title: 'Success', url: 'https://example.com', description: 'Got it' }] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('Success');
+    expect(callCount).toBe(4);
+  });
+
+  // ---- Provider fallback --------------------------------------------------
+
+  test('falls back from perplexity to brave when perplexity has no key', async () => {
+    mockWebSearchProvider = 'perplexity';
+    mockBraveConfigKey = 'brave-fallback-key';
+    let capturedUrl = '';
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    const result = await execute({ query: 'fallback test' });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toContain('brave');
+  });
+
+  test('falls back from brave to perplexity when brave has no key', async () => {
+    mockWebSearchProvider = 'brave';
+    mockPerplexityConfigKey = 'pplx-fallback-key';
+    let capturedUrl = '';
+    globalThis.fetch = (async (url: string, _init?: RequestInit) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({
+        choices: [{ message: { content: 'fallback result' } }],
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as any;
+
+    const result = await execute({ query: 'fallback test' });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toContain('perplexity');
+  });
+
+  test('maps anthropic-native to perplexity', async () => {
+    mockWebSearchProvider = 'anthropic-native';
+    mockPerplexityConfigKey = 'pplx-key';
+    let capturedUrl = '';
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({
+        choices: [{ message: { content: 'result' } }],
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toContain('perplexity');
+  });
+
+  // ---- Env var keys -------------------------------------------------------
+
+  test('uses PERPLEXITY_API_KEY env var when available', async () => {
+    const origEnv = process.env.PERPLEXITY_API_KEY;
+    process.env.PERPLEXITY_API_KEY = 'env-pplx-key';
+    try {
+      globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+        const headers = new Headers(init?.headers);
+        expect(headers.get('authorization')).toBe('Bearer env-pplx-key');
+        return new Response(JSON.stringify({
+          choices: [{ message: { content: 'env key works' } }],
+        }), { status: 200, headers: { 'content-type': 'application/json' } });
+      }) as any;
+
+      const result = await execute({ query: 'test' });
+      expect(result.isError).toBe(false);
+    } finally {
+      if (origEnv === undefined) {
+        delete process.env.PERPLEXITY_API_KEY;
+      } else {
+        process.env.PERPLEXITY_API_KEY = origEnv;
+      }
+    }
+  });
+
+  // ---- Network errors -----------------------------------------------------
+
+  test('handles fetch exceptions', async () => {
+    mockPerplexityConfigKey = 'pplx-key';
+    globalThis.fetch = (async () => {
+      throw new Error('Network error: connection refused');
+    }) as any;
+
+    const result = await execute({ query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Web search failed');
+    expect(result.content).toContain('connection refused');
+  });
+
+  // ---- Secure key precedence ----------------------------------------------
+
+  test('prefers secure key over config key for brave', async () => {
+    mockWebSearchProvider = 'brave';
+    mockBraveConfigKey = 'config-key';
+    mockBraveSecureKey = 'secure-key';
+    let capturedHeaders: Headers | null = null;
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      capturedHeaders = new Headers(init?.headers);
+      return new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200, headers: { 'content-type': 'application/json' },
+      });
+    }) as any;
+
+    await execute({ query: 'test' });
+    // Brave uses X-Subscription-Token header with the secure key
+    expect(capturedHeaders!.get('x-subscription-token')).toBe('secure-key');
+  });
+});

package/src/tools/network/domain-normalize.ts

@@ -0,0 +1,85 @@
+/**
+ * Registrable domain normalization utility.
+ *
+ * Wraps `tldts` to provide deterministic domain parsing used by
+ * credential domain policy enforcement.
+ */
+
+import { parse } from 'tldts';
+
+export interface DomainInfo {
+  /** Original hostname, lowercased and stripped of trailing dot. */
+  hostname: string;
+  /** Registrable domain (eTLD+1), e.g. "example.co.uk" for "foo.bar.example.co.uk". */
+  registrableDomain: string | null;
+}
+
+/**
+ * Parse and normalize a hostname or URL into its domain components.
+ *
+ * Handles:
+ * - Full URLs (extracts hostname)
+ * - Bare hostnames
+ * - Trailing dots
+ * - Mixed case
+ * - Punycode/IDN domains
+ *
+ * Returns `null` for inputs that cannot be parsed into a valid hostname
+ * (e.g. IP addresses, localhost, empty strings).
+ */
+export function normalizeDomain(input: string): DomainInfo | null {
+  if (!input || typeof input !== 'string') return null;
+
+  let hostname: string;
+
+  // If input looks like a URL, extract the hostname
+  try {
+    if (input.includes('://')) {
+      const url = new URL(input);
+      hostname = url.hostname;
+    } else {
+      hostname = input;
+    }
+  } catch {
+    hostname = input;
+  }
+
+  // Strip trailing port from bare hostnames (no scheme).
+  // Without this, "example.com:8080" is misidentified as IPv6 by isIPAddress.
+  if (!input.includes('://')) {
+    hostname = hostname.replace(/:\d+$/, '');
+  }
+
+  // Normalize: lowercase, strip trailing dot
+  hostname = hostname.toLowerCase().replace(/\.$/, '');
+
+  if (!hostname) return null;
+
+  // Reject IP addresses and localhost — they don't have registrable domains
+  if (isIPAddress(hostname) || hostname === 'localhost') {
+    return null;
+  }
+
+  // Reject malformed hostnames. Each DNS label must start and end with an
+  // alphanumeric and contain only alphanumerics/hyphens — no consecutive dots,
+  // no labels starting or ending with hyphens.
+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/.test(hostname)) {
+    return null;
+  }
+
+  const result = parse(hostname);
+  const registrableDomain = result.domain || null;
+
+  return {
+    hostname,
+    registrableDomain,
+  };
+}
+
+function isIPAddress(hostname: string): boolean {
+  // IPv4
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname)) return true;
+  // IPv6 (bracketed or bare)
+  if (hostname.startsWith('[') || hostname.includes(':')) return true;
+  return false;
+}