@openclaw/voice-call 2026.2.21 → 2026.2.23

package/src/webhook-security.ts

@@ -1,6 +1,63 @@
 import crypto from "node:crypto";
 import type { WebhookContext } from "./types.js";
 
+const REPLAY_WINDOW_MS = 10 * 60 * 1000;
+const REPLAY_CACHE_MAX_ENTRIES = 10_000;
+const REPLAY_CACHE_PRUNE_INTERVAL = 64;
+
+type ReplayCache = {
+  seenUntil: Map<string, number>;
+  calls: number;
+};
+
+const twilioReplayCache: ReplayCache = {
+  seenUntil: new Map<string, number>(),
+  calls: 0,
+};
+
+const plivoReplayCache: ReplayCache = {
+  seenUntil: new Map<string, number>(),
+  calls: 0,
+};
+
+function sha256Hex(input: string): string {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+function pruneReplayCache(cache: ReplayCache, now: number): void {
+  for (const [key, expiresAt] of cache.seenUntil) {
+    if (expiresAt <= now) {
+      cache.seenUntil.delete(key);
+    }
+  }
+  while (cache.seenUntil.size > REPLAY_CACHE_MAX_ENTRIES) {
+    const oldest = cache.seenUntil.keys().next().value;
+    if (!oldest) {
+      break;
+    }
+    cache.seenUntil.delete(oldest);
+  }
+}
+
+function markReplay(cache: ReplayCache, replayKey: string): boolean {
+  const now = Date.now();
+  cache.calls += 1;
+  if (cache.calls % REPLAY_CACHE_PRUNE_INTERVAL === 0) {
+    pruneReplayCache(cache, now);
+  }
+
+  const existing = cache.seenUntil.get(replayKey);
+  if (existing && existing > now) {
+    return true;
+  }
+
+  cache.seenUntil.set(replayKey, now + REPLAY_WINDOW_MS);
+  if (cache.seenUntil.size > REPLAY_CACHE_MAX_ENTRIES) {
+    pruneReplayCache(cache, now);
+  }
+  return false;
+}
+
 /**
  * Validate Twilio webhook signature using HMAC-SHA1.
  *
@@ -328,6 +385,8 @@ export interface TwilioVerificationResult {
   verificationUrl?: string;
   /** Whether we're running behind ngrok free tier */
   isNgrokFreeTier?: boolean;
+  /** Request is cryptographically valid but was already processed recently. */
+  isReplay?: boolean;
 }
 
 export interface TelnyxVerificationResult {
@@ -335,6 +394,20 @@ export interface TelnyxVerificationResult {
   reason?: string;
 }
 
+function createTwilioReplayKey(params: {
+  ctx: WebhookContext;
+  signature: string;
+  verificationUrl: string;
+}): string {
+  const idempotencyToken = getHeader(params.ctx.headers, "i-twilio-idempotency-token");
+  if (idempotencyToken) {
+    return `twilio:idempotency:${idempotencyToken}`;
+  }
+  return `twilio:fallback:${sha256Hex(
+    `${params.verificationUrl}\n${params.signature}\n${params.ctx.rawBody}`,
+  )}`;
+}
+
 function decodeBase64OrBase64Url(input: string): Buffer {
   // Telnyx docs say Base64; some tooling emits Base64URL. Accept both.
   const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
@@ -505,7 +578,9 @@ export function verifyTwilioWebhook(
   const isValid = validateTwilioSignature(authToken, signature, verificationUrl, params);
 
   if (isValid) {
-    return { ok: true, verificationUrl };
+    const replayKey = createTwilioReplayKey({ ctx, signature, verificationUrl });
+    const isReplay = markReplay(twilioReplayCache, replayKey);
+    return { ok: true, verificationUrl, isReplay };
   }
 
   // Check if this is ngrok free tier - the URL might have different format
@@ -533,6 +608,8 @@ export interface PlivoVerificationResult {
   verificationUrl?: string;
   /** Signature version used for verification */
   version?: "v3" | "v2";
+  /** Request is cryptographically valid but was already processed recently. */
+  isReplay?: boolean;
 }
 
 function normalizeSignatureBase64(input: string): string {
@@ -753,14 +830,17 @@ export function verifyPlivoWebhook(
       url: verificationUrl,
       postParams,
     });
-    return ok
-      ? { ok: true, version: "v3", verificationUrl }
-      : {
-          ok: false,
-          version: "v3",
-          verificationUrl,
-          reason: "Invalid Plivo V3 signature",
-        };
+    if (!ok) {
+      return {
+        ok: false,
+        version: "v3",
+        verificationUrl,
+        reason: "Invalid Plivo V3 signature",
+      };
+    }
+    const replayKey = `plivo:v3:${sha256Hex(`${verificationUrl}\n${nonceV3}`)}`;
+    const isReplay = markReplay(plivoReplayCache, replayKey);
+    return { ok: true, version: "v3", verificationUrl, isReplay };
   }
 
   if (signatureV2 && nonceV2) {
@@ -770,14 +850,17 @@ export function verifyPlivoWebhook(
       nonce: nonceV2,
       url: verificationUrl,
     });
-    return ok
-      ? { ok: true, version: "v2", verificationUrl }
-      : {
-          ok: false,
-          version: "v2",
-          verificationUrl,
-          reason: "Invalid Plivo V2 signature",
-        };
+    if (!ok) {
+      return {
+        ok: false,
+        version: "v2",
+        verificationUrl,
+        reason: "Invalid Plivo V2 signature",
+      };
+    }
+    const replayKey = `plivo:v2:${sha256Hex(`${verificationUrl}\n${nonceV2}`)}`;
+    const isReplay = markReplay(plivoReplayCache, replayKey);
+    return { ok: true, version: "v2", verificationUrl, isReplay };
   }
 
   return {

package/src/webhook.test.ts

@@ -45,12 +45,14 @@ const createCall = (startedAt: number): CallRecord => ({
 
 const createManager = (calls: CallRecord[]) => {
   const endCall = vi.fn(async () => ({ success: true }));
+  const processEvent = vi.fn();
   const manager = {
     getActiveCalls: () => calls,
     endCall,
+    processEvent,
   } as unknown as CallManager;
 
-  return { manager, endCall };
+  return { manager, endCall, processEvent };
 };
 
 describe("VoiceCallWebhookServer stale call reaper", () => {
@@ -116,3 +118,51 @@ describe("VoiceCallWebhookServer stale call reaper", () => {
     }
   });
 });
+
+describe("VoiceCallWebhookServer replay handling", () => {
+  it("acknowledges replayed webhook requests and skips event side effects", async () => {
+    const replayProvider: VoiceCallProvider = {
+      ...provider,
+      verifyWebhook: () => ({ ok: true, isReplay: true }),
+      parseWebhookEvent: () => ({
+        events: [
+          {
+            id: "evt-replay",
+            dedupeKey: "stable-replay",
+            type: "call.speech",
+            callId: "call-1",
+            providerCallId: "provider-call-1",
+            timestamp: Date.now(),
+            transcript: "hello",
+            isFinal: true,
+          },
+        ],
+        statusCode: 200,
+      }),
+    };
+    const { manager, processEvent } = createManager([]);
+    const config = createConfig({ serve: { port: 0, bind: "127.0.0.1", path: "/voice/webhook" } });
+    const server = new VoiceCallWebhookServer(config, manager, replayProvider);
+
+    try {
+      const baseUrl = await server.start();
+      const address = (
+        server as unknown as { server?: { address?: () => unknown } }
+      ).server?.address?.();
+      const requestUrl = new URL(baseUrl);
+      if (address && typeof address === "object" && "port" in address && address.port) {
+        requestUrl.port = String(address.port);
+      }
+      const response = await fetch(requestUrl.toString(), {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: "CallSid=CA123&SpeechResult=hello",
+      });
+
+      expect(response.status).toBe(200);
+      expect(processEvent).not.toHaveBeenCalled();
+    } finally {
+      await server.stop();
+    }
+  });
+});

package/src/webhook.ts

@@ -77,6 +77,10 @@ export class VoiceCallWebhookServer {
 
     const streamConfig: MediaStreamConfig = {
       sttProvider,
+      preStartTimeoutMs: this.config.streaming?.preStartTimeoutMs,
+      maxPendingConnections: this.config.streaming?.maxPendingConnections,
+      maxPendingConnectionsPerIp: this.config.streaming?.maxPendingConnectionsPerIp,
+      maxConnections: this.config.streaming?.maxConnections,
       shouldAcceptStream: ({ callId, token }) => {
         const call = this.manager.getCallByProviderCallId(callId);
         if (!call) {
@@ -192,9 +196,8 @@ export class VoiceCallWebhookServer {
       // Handle WebSocket upgrades for media streams
       if (this.mediaStreamHandler) {
         this.server.on("upgrade", (request, socket, head) => {
-          const url = new URL(request.url || "/", `http://${request.headers.host}`);
-
-          if (url.pathname === streamPath) {
+          const path = this.getUpgradePathname(request);
+          if (path === streamPath) {
             console.log("[voice-call] WebSocket upgrade for media stream");
             this.mediaStreamHandler?.handleUpgrade(request, socket, head);
           } else {
@@ -269,6 +272,15 @@ export class VoiceCallWebhookServer {
     });
   }
 
+  private getUpgradePathname(request: http.IncomingMessage): string | null {
+    try {
+      const host = request.headers.host || "localhost";
+      return new URL(request.url || "/", `http://${host}`).pathname;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Handle incoming HTTP request.
    */
@@ -334,11 +346,15 @@ export class VoiceCallWebhookServer {
     const result = this.provider.parseWebhookEvent(ctx);
 
     // Process each event
-    for (const event of result.events) {
-      try {
-        this.manager.processEvent(event);
-      } catch (err) {
-        console.error(`[voice-call] Error processing event ${event.type}:`, err);
+    if (verification.isReplay) {
+      console.warn("[voice-call] Replay detected; skipping event side effects");
+    } else {
+      for (const event of result.events) {
+        try {
+          this.manager.processEvent(event);
+        } catch (err) {
+          console.error(`[voice-call] Error processing event ${event.type}:`, err);
+        }
       }
     }