@openclaw/voice-call 2026.2.12 → 2026.2.14

package/src/providers/telnyx.test.ts

@@ -0,0 +1,121 @@
+import crypto from "node:crypto";
+import { describe, expect, it } from "vitest";
+import type { WebhookContext } from "../types.js";
+import { TelnyxProvider } from "./telnyx.js";
+
+function createCtx(params?: Partial<WebhookContext>): WebhookContext {
+  return {
+    headers: {},
+    rawBody: "{}",
+    url: "http://localhost/voice/webhook",
+    method: "POST",
+    query: {},
+    remoteAddress: "127.0.0.1",
+    ...params,
+  };
+}
+
+function decodeBase64Url(input: string): Buffer {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (normalized.length % 4)) % 4;
+  const padded = normalized + "=".repeat(padLen);
+  return Buffer.from(padded, "base64");
+}
+
+describe("TelnyxProvider.verifyWebhook", () => {
+  it("fails closed when public key is missing and skipVerification is false", () => {
+    const provider = new TelnyxProvider(
+      { apiKey: "KEY123", connectionId: "CONN456", publicKey: undefined },
+      { skipVerification: false },
+    );
+
+    const result = provider.verifyWebhook(createCtx());
+    expect(result.ok).toBe(false);
+  });
+
+  it("allows requests when skipVerification is true (development only)", () => {
+    const provider = new TelnyxProvider(
+      { apiKey: "KEY123", connectionId: "CONN456", publicKey: undefined },
+      { skipVerification: true },
+    );
+
+    const result = provider.verifyWebhook(createCtx());
+    expect(result.ok).toBe(true);
+  });
+
+  it("fails when signature headers are missing (with public key configured)", () => {
+    const provider = new TelnyxProvider(
+      { apiKey: "KEY123", connectionId: "CONN456", publicKey: "public-key" },
+      { skipVerification: false },
+    );
+
+    const result = provider.verifyWebhook(createCtx({ headers: {} }));
+    expect(result.ok).toBe(false);
+  });
+
+  it("verifies a valid signature with a raw Ed25519 public key (Base64)", () => {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+
+    const jwk = publicKey.export({ format: "jwk" }) as JsonWebKey;
+    expect(jwk.kty).toBe("OKP");
+    expect(jwk.crv).toBe("Ed25519");
+    expect(typeof jwk.x).toBe("string");
+
+    const rawPublicKey = decodeBase64Url(jwk.x as string);
+    const rawPublicKeyBase64 = rawPublicKey.toString("base64");
+
+    const provider = new TelnyxProvider(
+      { apiKey: "KEY123", connectionId: "CONN456", publicKey: rawPublicKeyBase64 },
+      { skipVerification: false },
+    );
+
+    const rawBody = JSON.stringify({
+      event_type: "call.initiated",
+      payload: { call_control_id: "x" },
+    });
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const signedPayload = `${timestamp}|${rawBody}`;
+    const signature = crypto.sign(null, Buffer.from(signedPayload), privateKey).toString("base64");
+
+    const result = provider.verifyWebhook(
+      createCtx({
+        rawBody,
+        headers: {
+          "telnyx-signature-ed25519": signature,
+          "telnyx-timestamp": timestamp,
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+  });
+
+  it("verifies a valid signature with a DER SPKI public key (Base64)", () => {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+    const spkiDer = publicKey.export({ format: "der", type: "spki" }) as Buffer;
+    const spkiDerBase64 = spkiDer.toString("base64");
+
+    const provider = new TelnyxProvider(
+      { apiKey: "KEY123", connectionId: "CONN456", publicKey: spkiDerBase64 },
+      { skipVerification: false },
+    );
+
+    const rawBody = JSON.stringify({
+      event_type: "call.initiated",
+      payload: { call_control_id: "x" },
+    });
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const signedPayload = `${timestamp}|${rawBody}`;
+    const signature = crypto.sign(null, Buffer.from(signedPayload), privateKey).toString("base64");
+
+    const result = provider.verifyWebhook(
+      createCtx({
+        rawBody,
+        headers: {
+          "telnyx-signature-ed25519": signature,
+          "telnyx-timestamp": timestamp,
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+  });
+});

package/src/providers/telnyx.ts

@@ -14,6 +14,7 @@ import type {
   WebhookVerificationResult,
 } from "../types.js";
 import type { VoiceCallProvider } from "./base.js";
+import { verifyTelnyxWebhook } from "../webhook-security.js";
 
 /**
  * Telnyx Voice API provider implementation.
@@ -22,8 +23,8 @@ import type { VoiceCallProvider } from "./base.js";
  * @see https://developers.telnyx.com/docs/api/v2/call-control
  */
 export interface TelnyxProviderOptions {
-  /** Allow unsigned webhooks when no public key is configured */
-  allowUnsignedWebhooks?: boolean;
+  /** Skip webhook signature verification (development only, NOT for production) */
+  skipVerification?: boolean;
 }
 
 export class TelnyxProvider implements VoiceCallProvider {
@@ -82,65 +83,11 @@ export class TelnyxProvider implements VoiceCallProvider {
    * Verify Telnyx webhook signature using Ed25519.
    */
   verifyWebhook(ctx: WebhookContext): WebhookVerificationResult {
-    if (!this.publicKey) {
-      if (this.options.allowUnsignedWebhooks) {
-        console.warn("[telnyx] Webhook verification skipped (no public key configured)");
-        return { ok: true, reason: "verification skipped (no public key configured)" };
-      }
-      return {
-        ok: false,
-        reason: "Missing telnyx.publicKey (configure to verify webhooks)",
-      };
-    }
-
-    const signature = ctx.headers["telnyx-signature-ed25519"];
-    const timestamp = ctx.headers["telnyx-timestamp"];
-
-    if (!signature || !timestamp) {
-      return { ok: false, reason: "Missing signature or timestamp header" };
-    }
-
-    const signatureStr = Array.isArray(signature) ? signature[0] : signature;
-    const timestampStr = Array.isArray(timestamp) ? timestamp[0] : timestamp;
-
-    if (!signatureStr || !timestampStr) {
-      return { ok: false, reason: "Empty signature or timestamp" };
-    }
-
-    try {
-      const signedPayload = `${timestampStr}|${ctx.rawBody}`;
-      const signatureBuffer = Buffer.from(signatureStr, "base64");
-      const publicKeyBuffer = Buffer.from(this.publicKey, "base64");
-
-      const isValid = crypto.verify(
-        null, // Ed25519 doesn't use a digest
-        Buffer.from(signedPayload),
-        {
-          key: publicKeyBuffer,
-          format: "der",
-          type: "spki",
-        },
-        signatureBuffer,
-      );
-
-      if (!isValid) {
-        return { ok: false, reason: "Invalid signature" };
-      }
-
-      // Check timestamp is within 5 minutes
-      const eventTime = parseInt(timestampStr, 10) * 1000;
-      const now = Date.now();
-      if (Math.abs(now - eventTime) > 5 * 60 * 1000) {
-        return { ok: false, reason: "Timestamp too old" };
-      }
+    const result = verifyTelnyxWebhook(ctx, this.publicKey, {
+      skipVerification: this.options.skipVerification,
+    });
 
-      return { ok: true };
-    } catch (err) {
-      return {
-        ok: false,
-        reason: `Verification error: ${err instanceof Error ? err.message : String(err)}`,
-      };
-    }
+    return { ok: result.ok, reason: result.reason };
   }
 
   /**

package/src/runtime.ts

@@ -55,8 +55,7 @@ function resolveProvider(config: VoiceCallConfig): VoiceCallProvider {
           publicKey: config.telnyx?.publicKey,
         },
         {
-          allowUnsignedWebhooks:
-            config.inboundPolicy === "open" || config.inboundPolicy === "disabled",
+          skipVerification: config.skipSignatureVerification,
         },
       );
     case "twilio":
@@ -113,6 +112,12 @@ export async function createVoiceCallRuntime(params: {
     throw new Error("Voice call disabled. Enable the plugin entry in config.");
   }
 
+  if (config.skipSignatureVerification) {
+    log.warn(
+      "[voice-call] SECURITY WARNING: skipSignatureVerification=true disables webhook signature verification (development only). Do not use in production.",
+    );
+  }
+
   const validation = validateProviderConfig(config);
   if (!validation.valid) {
     throw new Error(`Invalid voice-call config: ${validation.errors.join("; ")}`);

package/src/webhook-security.test.ts

@@ -222,9 +222,16 @@ describe("verifyTwilioWebhook", () => {
     expect(result.reason).toMatch(/Invalid signature/);
   });
 
-  it("allows invalid signatures for ngrok free tier only on loopback", () => {
+  it("accepts valid signatures for ngrok free tier on loopback when compatibility mode is enabled", () => {
     const authToken = "test-auth-token";
     const postBody = "CallSid=CS123&CallStatus=completed&From=%2B15550000000";
+    const webhookUrl = "https://local.ngrok-free.app/voice/webhook";
+
+    const signature = twilioSignature({
+      authToken,
+      url: webhookUrl,
+      postBody,
+    });
 
     const result = verifyTwilioWebhook(
       {
@@ -232,7 +239,7 @@ describe("verifyTwilioWebhook", () => {
           host: "127.0.0.1:3334",
           "x-forwarded-proto": "https",
           "x-forwarded-host": "local.ngrok-free.app",
-          "x-twilio-signature": "invalid",
+          "x-twilio-signature": signature,
         },
         rawBody: postBody,
         url: "http://127.0.0.1:3334/voice/webhook",
@@ -244,8 +251,33 @@ describe("verifyTwilioWebhook", () => {
     );
 
     expect(result.ok).toBe(true);
+    expect(result.verificationUrl).toBe(webhookUrl);
+  });
+
+  it("does not allow invalid signatures for ngrok free tier on loopback", () => {
+    const authToken = "test-auth-token";
+    const postBody = "CallSid=CS123&CallStatus=completed&From=%2B15550000000";
+
+    const result = verifyTwilioWebhook(
+      {
+        headers: {
+          host: "127.0.0.1:3334",
+          "x-forwarded-proto": "https",
+          "x-forwarded-host": "local.ngrok-free.app",
+          "x-twilio-signature": "invalid",
+        },
+        rawBody: postBody,
+        url: "http://127.0.0.1:3334/voice/webhook",
+        method: "POST",
+        remoteAddress: "127.0.0.1",
+      },
+      authToken,
+      { allowNgrokFreeTierLoopbackBypass: true },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toMatch(/Invalid signature/);
     expect(result.isNgrokFreeTier).toBe(true);
-    expect(result.reason).toMatch(/compatibility mode/);
   });
 
   it("ignores attacker X-Forwarded-Host without allowedHosts or trustForwardingHeaders", () => {

package/src/webhook-security.ts

@@ -330,6 +330,111 @@ export interface TwilioVerificationResult {
   isNgrokFreeTier?: boolean;
 }
 
+export interface TelnyxVerificationResult {
+  ok: boolean;
+  reason?: string;
+}
+
+function decodeBase64OrBase64Url(input: string): Buffer {
+  // Telnyx docs say Base64; some tooling emits Base64URL. Accept both.
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (normalized.length % 4)) % 4;
+  const padded = normalized + "=".repeat(padLen);
+  return Buffer.from(padded, "base64");
+}
+
+function base64UrlEncode(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function importEd25519PublicKey(publicKey: string): crypto.KeyObject | string {
+  const trimmed = publicKey.trim();
+
+  // PEM (spki) support.
+  if (trimmed.startsWith("-----BEGIN")) {
+    return trimmed;
+  }
+
+  // Base64-encoded raw Ed25519 key (32 bytes) or Base64-encoded DER SPKI key.
+  const decoded = decodeBase64OrBase64Url(trimmed);
+  if (decoded.length === 32) {
+    // JWK is the easiest portable way to import raw Ed25519 keys in Node crypto.
+    return crypto.createPublicKey({
+      key: { kty: "OKP", crv: "Ed25519", x: base64UrlEncode(decoded) },
+      format: "jwk",
+    });
+  }
+
+  return crypto.createPublicKey({
+    key: decoded,
+    format: "der",
+    type: "spki",
+  });
+}
+
+/**
+ * Verify Telnyx webhook signature using Ed25519.
+ *
+ * Telnyx signs `timestamp|payload` and provides:
+ * - `telnyx-signature-ed25519` (Base64 signature)
+ * - `telnyx-timestamp` (Unix seconds)
+ */
+export function verifyTelnyxWebhook(
+  ctx: WebhookContext,
+  publicKey: string | undefined,
+  options?: {
+    /** Skip verification entirely (only for development) */
+    skipVerification?: boolean;
+    /** Maximum allowed clock skew (ms). Defaults to 5 minutes. */
+    maxSkewMs?: number;
+  },
+): TelnyxVerificationResult {
+  if (options?.skipVerification) {
+    return { ok: true, reason: "verification skipped (dev mode)" };
+  }
+
+  if (!publicKey) {
+    return { ok: false, reason: "Missing telnyx.publicKey (configure to verify webhooks)" };
+  }
+
+  const signature = getHeader(ctx.headers, "telnyx-signature-ed25519");
+  const timestamp = getHeader(ctx.headers, "telnyx-timestamp");
+
+  if (!signature || !timestamp) {
+    return { ok: false, reason: "Missing signature or timestamp header" };
+  }
+
+  const eventTimeSec = parseInt(timestamp, 10);
+  if (!Number.isFinite(eventTimeSec)) {
+    return { ok: false, reason: "Invalid timestamp header" };
+  }
+
+  try {
+    const signedPayload = `${timestamp}|${ctx.rawBody}`;
+    const signatureBuffer = decodeBase64OrBase64Url(signature);
+    const key = importEd25519PublicKey(publicKey);
+
+    const isValid = crypto.verify(null, Buffer.from(signedPayload), key, signatureBuffer);
+    if (!isValid) {
+      return { ok: false, reason: "Invalid signature" };
+    }
+
+    const maxSkewMs = options?.maxSkewMs ?? 5 * 60 * 1000;
+    const eventTimeMs = eventTimeSec * 1000;
+    const now = Date.now();
+    if (Math.abs(now - eventTimeMs) > maxSkewMs) {
+      return { ok: false, reason: "Timestamp too old" };
+    }
+
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `Verification error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 /**
  * Verify Twilio webhook with full context and detailed result.
  */
@@ -339,7 +444,13 @@ export function verifyTwilioWebhook(
   options?: {
     /** Override the public URL (e.g., from config) */
     publicUrl?: string;
-    /** Allow ngrok free tier compatibility mode (loopback only, less secure) */
+    /**
+     * Allow ngrok free tier compatibility mode (loopback only).
+     *
+     * IMPORTANT: This does NOT bypass signature verification.
+     * It only enables trusting forwarded headers on loopback so we can
+     * reconstruct the public ngrok URL that Twilio used for signing.
+     */
     allowNgrokFreeTierLoopbackBypass?: boolean;
     /** Skip verification entirely (only for development) */
     skipVerification?: boolean;
@@ -401,18 +512,6 @@ export function verifyTwilioWebhook(
   const isNgrokFreeTier =
     verificationUrl.includes(".ngrok-free.app") || verificationUrl.includes(".ngrok.io");
 
-  if (isNgrokFreeTier && options?.allowNgrokFreeTierLoopbackBypass && isLoopback) {
-    console.warn(
-      "[voice-call] Twilio signature validation failed (ngrok free tier compatibility, loopback only)",
-    );
-    return {
-      ok: true,
-      reason: "ngrok free tier compatibility mode (loopback only)",
-      verificationUrl,
-      isNgrokFreeTier: true,
-    };
-  }
-
   return {
     ok: false,
     reason: `Invalid signature for URL: ${verificationUrl}`,

package/src/webhook.ts

@@ -1,6 +1,11 @@
 import { spawn } from "node:child_process";
 import http from "node:http";
 import { URL } from "node:url";
+import {
+  isRequestBodyLimitError,
+  readRequestBodyWithLimit,
+  requestBodyErrorToText,
+} from "openclaw/plugin-sdk";
 import type { VoiceCallConfig } from "./config.js";
 import type { CoreConfig } from "./core-bridge.js";
 import type { CallManager } from "./manager.js";
@@ -244,11 +249,16 @@ export class VoiceCallWebhookServer {
     try {
       body = await this.readBody(req, MAX_WEBHOOK_BODY_BYTES);
     } catch (err) {
-      if (err instanceof Error && err.message === "PayloadTooLarge") {
+      if (isRequestBodyLimitError(err, "PAYLOAD_TOO_LARGE")) {
         res.statusCode = 413;
         res.end("Payload Too Large");
         return;
       }
+      if (isRequestBodyLimitError(err, "REQUEST_BODY_TIMEOUT")) {
+        res.statusCode = 408;
+        res.end(requestBodyErrorToText("REQUEST_BODY_TIMEOUT"));
+        return;
+      }
       throw err;
     }
 
@@ -303,42 +313,7 @@ export class VoiceCallWebhookServer {
     maxBytes: number,
     timeoutMs = 30_000,
   ): Promise<string> {
-    return new Promise((resolve, reject) => {
-      let done = false;
-      const finish = (fn: () => void) => {
-        if (done) {
-          return;
-        }
-        done = true;
-        clearTimeout(timer);
-        fn();
-      };
-
-      const timer = setTimeout(() => {
-        finish(() => {
-          const err = new Error("Request body timeout");
-          req.destroy(err);
-          reject(err);
-        });
-      }, timeoutMs);
-
-      const chunks: Buffer[] = [];
-      let totalBytes = 0;
-      req.on("data", (chunk: Buffer) => {
-        totalBytes += chunk.length;
-        if (totalBytes > maxBytes) {
-          finish(() => {
-            req.destroy();
-            reject(new Error("PayloadTooLarge"));
-          });
-          return;
-        }
-        chunks.push(chunk);
-      });
-      req.on("end", () => finish(() => resolve(Buffer.concat(chunks).toString("utf-8"))));
-      req.on("error", (err) => finish(() => reject(err)));
-      req.on("close", () => finish(() => reject(new Error("Connection closed"))));
-    });
+    return readRequestBodyWithLimit(req, { maxBytes, timeoutMs });
   }
 
   /**