@vellumai/assistant 0.3.0

package/src/calls/twilio-provider.ts

@@ -0,0 +1,263 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { getLogger } from '../util/logger.js';
+import { getSecureKey } from '../security/secure-keys.js';
+import { getTwilioCredentials, twilioAuthHeader, twilioBaseUrl } from './twilio-rest.js';
+import type { VoiceProvider, InitiateCallOptions } from './voice-provider.js';
+
+const log = getLogger('twilio-provider');
+
+/**
+ * Twilio ConversationRelay voice provider.
+ *
+ * Uses the Twilio REST API directly via fetch() — no twilio npm package.
+ * Credentials are resolved lazily from the secure key store on each call.
+ */
+export class TwilioConversationRelayProvider implements VoiceProvider {
+  readonly name = 'twilio';
+
+  // ── Credential helpers ──────────────────────────────────────────────
+
+  private getCredentials(): { accountSid: string; authToken: string } {
+    return getTwilioCredentials();
+  }
+
+  private authHeader(accountSid: string, authToken: string): string {
+    return twilioAuthHeader(accountSid, authToken);
+  }
+
+  private baseUrl(accountSid: string): string {
+    return twilioBaseUrl(accountSid);
+  }
+
+  // ── VoiceProvider interface ─────────────────────────────────────────
+
+  async initiateCall(opts: InitiateCallOptions): Promise<{ callSid: string }> {
+    const { accountSid, authToken } = this.getCredentials();
+
+    const body = new URLSearchParams({
+      From: opts.from,
+      To: opts.to,
+      Url: opts.webhookUrl,
+      StatusCallback: opts.statusCallbackUrl,
+    });
+    // Twilio expects repeated StatusCallbackEvent params, not a single
+    // space-delimited string.
+    body.append('StatusCallbackEvent', 'initiated');
+    body.append('StatusCallbackEvent', 'ringing');
+    body.append('StatusCallbackEvent', 'answered');
+    body.append('StatusCallbackEvent', 'completed');
+
+    const reservedKeys = new Set(['From', 'To', 'Url', 'StatusCallback', 'StatusCallbackEvent']);
+    if (opts.customParams) {
+      for (const [key, value] of Object.entries(opts.customParams)) {
+        if (reservedKeys.has(key)) {
+          log.warn({ key }, 'Ignoring reserved Twilio parameter in customParams');
+          continue;
+        }
+        body.set(key, value);
+      }
+    }
+
+    log.info({ from: opts.from, to: opts.to }, 'Initiating Twilio call');
+
+    const res = await fetch(`${this.baseUrl(accountSid)}/Calls.json`, {
+      method: 'POST',
+      headers: {
+        Authorization: this.authHeader(accountSid, authToken),
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      log.error({ status: res.status, body: text }, 'Twilio initiateCall failed');
+      throw new Error(`Twilio API error ${res.status}: ${text}`);
+    }
+
+    const data = (await res.json()) as { sid: string };
+    log.info({ callSid: data.sid }, 'Twilio call initiated');
+    return { callSid: data.sid };
+  }
+
+  async endCall(callSid: string): Promise<void> {
+    const { accountSid, authToken } = this.getCredentials();
+
+    log.info({ callSid }, 'Ending Twilio call');
+
+    const body = new URLSearchParams({ Status: 'completed' });
+
+    const res = await fetch(`${this.baseUrl(accountSid)}/Calls/${callSid}.json`, {
+      method: 'POST',
+      headers: {
+        Authorization: this.authHeader(accountSid, authToken),
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      log.error({ status: res.status, body: text, callSid }, 'Twilio endCall failed');
+      throw new Error(`Twilio API error ${res.status}: ${text}`);
+    }
+
+    log.info({ callSid }, 'Twilio call ended');
+  }
+
+  async getCallStatus(callSid: string): Promise<string> {
+    const { accountSid, authToken } = this.getCredentials();
+
+    const res = await fetch(`${this.baseUrl(accountSid)}/Calls/${callSid}.json`, {
+      method: 'GET',
+      headers: {
+        Authorization: this.authHeader(accountSid, authToken),
+      },
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      log.error({ status: res.status, body: text, callSid }, 'Twilio getCallStatus failed');
+      throw new Error(`Twilio API error ${res.status}: ${text}`);
+    }
+
+    const data = (await res.json()) as { status: string };
+    return data.status;
+  }
+
+  // ── Caller ID eligibility ───────────────────────────────────────────
+
+  /**
+   * Check whether a phone number can be used as an outbound caller ID
+   * by the current Twilio account. A number is eligible if it appears as
+   * either an Incoming Phone Number (owned) or an Outgoing Caller ID
+   * (verified) on the account.
+   */
+  async checkCallerIdEligibility(
+    phoneNumber: string,
+  ): Promise<{ eligible: boolean; reason?: string }> {
+    const { accountSid, authToken } = this.getCredentials();
+    const encodedNumber = encodeURIComponent(phoneNumber);
+
+    let incomingOk = false;
+    let outgoingOk = false;
+
+    // Check incoming phone numbers (owned by this account)
+    const incomingRes = await fetch(
+      `${this.baseUrl(accountSid)}/IncomingPhoneNumbers.json?PhoneNumber=${encodedNumber}`,
+      {
+        method: 'GET',
+        headers: {
+          Authorization: this.authHeader(accountSid, authToken),
+        },
+      },
+    );
+
+    if (incomingRes.ok) {
+      incomingOk = true;
+      const incomingData = (await incomingRes.json()) as {
+        incoming_phone_numbers: unknown[];
+      };
+      if (incomingData.incoming_phone_numbers.length > 0) {
+        log.info({ phoneNumber }, 'Number found in IncomingPhoneNumbers — eligible as caller ID');
+        return { eligible: true };
+      }
+    } else {
+      log.warn(
+        { status: incomingRes.status, phoneNumber },
+        'Failed to query IncomingPhoneNumbers — falling through to OutgoingCallerIds',
+      );
+    }
+
+    // Check outgoing caller IDs (verified with this account)
+    const outgoingRes = await fetch(
+      `${this.baseUrl(accountSid)}/OutgoingCallerIds.json?PhoneNumber=${encodedNumber}`,
+      {
+        method: 'GET',
+        headers: {
+          Authorization: this.authHeader(accountSid, authToken),
+        },
+      },
+    );
+
+    if (outgoingRes.ok) {
+      outgoingOk = true;
+      const outgoingData = (await outgoingRes.json()) as {
+        outgoing_caller_ids: unknown[];
+      };
+      if (outgoingData.outgoing_caller_ids.length > 0) {
+        log.info({ phoneNumber }, 'Number found in OutgoingCallerIds — eligible as caller ID');
+        return { eligible: true };
+      }
+    } else {
+      log.warn(
+        { status: outgoingRes.status, phoneNumber },
+        'Failed to query OutgoingCallerIds',
+      );
+    }
+
+    // If any API call failed, the eligibility check is inconclusive —
+    // propagate as an error rather than returning a false negative.
+    if (!incomingOk || !outgoingOk) {
+      const failedEndpoints = [
+        ...(!incomingOk ? [`IncomingPhoneNumbers: ${incomingRes.status}`] : []),
+        ...(!outgoingOk ? [`OutgoingCallerIds: ${outgoingRes.status}`] : []),
+      ].join(', ');
+      throw new Error(
+        `Unable to verify caller ID eligibility for ${phoneNumber}: Twilio API error (${failedEndpoints}). The number may be eligible but could not be confirmed. Please check your Twilio credentials and try again.`,
+      );
+    }
+
+    log.info({ phoneNumber }, 'Number not found in either IncomingPhoneNumbers or OutgoingCallerIds');
+    return {
+      eligible: false,
+      reason:
+        'Number is not owned by or verified with your Twilio account. To use this number as caller ID, either: (1) add it as an Incoming Phone Number, or (2) verify it as an Outgoing Caller ID in the Twilio Console.',
+    };
+  }
+
+  // ── Webhook signature verification ──────────────────────────────────
+
+  /**
+   * Returns the Twilio auth token from the secure key store, or null if
+   * not configured. Exposed as a static method so callers (e.g. the
+   * HTTP server webhook middleware) can check availability independently.
+   */
+  static getAuthToken(): string | null {
+    return getSecureKey('credential:twilio:auth_token') ?? null;
+  }
+
+  /**
+   * Validates an X-Twilio-Signature header using HMAC-SHA1.
+   *
+   * Algorithm (from Twilio docs):
+   * 1. Take the full URL of the request.
+   * 2. Sort the POST parameters alphabetically by key.
+   * 3. Concatenate the URL with each key-value pair (key + value, no delimiters).
+   * 4. HMAC-SHA1 the result using the auth token as the key.
+   * 5. Base64-encode the hash.
+   * 6. Compare to the X-Twilio-Signature header value.
+   */
+  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 = createHmac('sha1', authToken)
+      .update(data)
+      .digest('base64');
+
+    // Constant-time comparison to prevent timing attacks
+    const a = Buffer.from(computed);
+    const b = Buffer.from(signature);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  }
+}

package/src/calls/twilio-rest.ts

@@ -0,0 +1,156 @@
+/**
+ * Reusable Twilio REST API helpers.
+ *
+ * Provides low-level building blocks (auth header, base URL, credential
+ * resolution) shared across the voice provider, SMS channel, and IPC
+ * config handler. Uses fetch() directly — no twilio npm package.
+ */
+
+import { getSecureKey } from '../security/secure-keys.js';
+
+export interface TwilioCredentials {
+  accountSid: string;
+  authToken: string;
+}
+
+/** Resolve Twilio credentials from the secure key store. Throws if not configured. */
+export function getTwilioCredentials(): TwilioCredentials {
+  const accountSid = getSecureKey('credential:twilio:account_sid');
+  const authToken = getSecureKey('credential:twilio:auth_token');
+  if (!accountSid || !authToken) {
+    throw new Error(
+      'Twilio credentials not configured. Set credential:twilio:account_sid and credential:twilio:auth_token via the credential_store tool.',
+    );
+  }
+  return { accountSid, authToken };
+}
+
+/** Check whether Twilio credentials are present (non-throwing). */
+export function hasTwilioCredentials(): boolean {
+  return !!getSecureKey('credential:twilio:account_sid') && !!getSecureKey('credential:twilio:auth_token');
+}
+
+/** Build the HTTP Basic auth header for Twilio API requests. */
+export function twilioAuthHeader(accountSid: string, authToken: string): string {
+  return 'Basic ' + Buffer.from(`${accountSid}:${authToken}`).toString('base64');
+}
+
+/** Build the Twilio REST API base URL for a given account. */
+export function twilioBaseUrl(accountSid: string): string {
+  return `https://api.twilio.com/2010-04-01/Accounts/${accountSid}`;
+}
+
+export interface TwilioPhoneNumber {
+  phoneNumber: string;
+  friendlyName: string;
+  capabilities: { voice: boolean; sms: boolean };
+}
+
+/** List incoming phone numbers owned by the account. */
+export async function listIncomingPhoneNumbers(
+  accountSid: string,
+  authToken: string,
+): Promise<TwilioPhoneNumber[]> {
+  const res = await fetch(`${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers.json`, {
+    method: 'GET',
+    headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio API error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as {
+    incoming_phone_numbers: Array<{
+      phone_number: string;
+      friendly_name: string;
+      capabilities: { voice: boolean; sms: boolean };
+    }>;
+  };
+
+  return data.incoming_phone_numbers.map((n) => ({
+    phoneNumber: n.phone_number,
+    friendlyName: n.friendly_name,
+    capabilities: { voice: n.capabilities.voice, sms: n.capabilities.sms },
+  }));
+}
+
+export interface AvailablePhoneNumber {
+  phoneNumber: string;
+  friendlyName: string;
+  capabilities: { voice: boolean; sms: boolean };
+}
+
+/** Search for available phone numbers to purchase. */
+export async function searchAvailableNumbers(
+  accountSid: string,
+  authToken: string,
+  country: string,
+  areaCode?: string,
+): Promise<AvailablePhoneNumber[]> {
+  const params = new URLSearchParams({ SmsEnabled: 'true', VoiceEnabled: 'true' });
+  if (areaCode) params.set('AreaCode', areaCode);
+
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/AvailablePhoneNumbers/${encodeURIComponent(country)}/Local.json?${params.toString()}`,
+    {
+      method: 'GET',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio API error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as {
+    available_phone_numbers: Array<{
+      phone_number: string;
+      friendly_name: string;
+      capabilities: { voice: boolean; sms: boolean };
+    }>;
+  };
+
+  return data.available_phone_numbers.map((n) => ({
+    phoneNumber: n.phone_number,
+    friendlyName: n.friendly_name,
+    capabilities: { voice: n.capabilities.voice, sms: n.capabilities.sms },
+  }));
+}
+
+/** Provision (buy) a phone number. Returns the purchased number details. */
+export async function provisionPhoneNumber(
+  accountSid: string,
+  authToken: string,
+  phoneNumber: string,
+): Promise<TwilioPhoneNumber> {
+  const body = new URLSearchParams({ PhoneNumber: phoneNumber });
+
+  const res = await fetch(`${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers.json`, {
+    method: 'POST',
+    headers: {
+      Authorization: twilioAuthHeader(accountSid, authToken),
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio API error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as {
+    phone_number: string;
+    friendly_name: string;
+    capabilities: { voice: boolean; sms: boolean };
+  };
+
+  return {
+    phoneNumber: data.phone_number,
+    friendlyName: data.friendly_name,
+    capabilities: { voice: data.capabilities.voice, sms: data.capabilities.sms },
+  };
+}