fix(voice-call): block Twilio webhook replay and stale transitions

Author: steipete

CHANGELOG.md

@@ -10,6 +10,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Security/Voice Call: harden Twilio webhook replay handling by preserving provider event IDs through normalization, adding bounded replay dedupe, and enforcing per-call turn-token matching for call-state transitions. This ships in the next npm release. Thanks @jiseoung for reporting.
 - Security/Commands: enforce sender-only matching for `commands.allowFrom` by blocking conversation-shaped `From` identities (`channel:`, `group:`, `thread:`, `@g.us`) while preserving direct-message fallback when sender fields are missing. Ships in the next npm release. Thanks @jiseoung.
 - Config/Kilo Gateway: Kilo provider flow now surfaces an updated list of models. (#24921) thanks @gumadeiras.
 - Security/Sandbox: enforce `tools.exec.applyPatch.workspaceOnly` and `tools.fs.workspaceOnly` for `apply_patch` in sandbox-mounted paths so writes/deletes cannot escape the workspace boundary via mounts like `/agent` unless explicitly opted out (`tools.exec.applyPatch.workspaceOnly=false`). This ships in the next npm release. Thanks @tdjackey for reporting.

docs/plugins/voice-call.md

@@ -177,6 +177,12 @@ headers are trusted.
 `webhookSecurity.trustedProxyIPs` only trusts forwarded headers when the request
 remote IP matches the list.
 
+Webhook replay protection is enabled for Twilio and Plivo. Replayed valid webhook
+requests are acknowledged but skipped for side effects.
+
+Twilio conversation turns include a per-turn token in `<Gather>` callbacks, so
+stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
+
 Example with a stable public host:
 
 ```json5

extensions/voice-call/README.md

@@ -175,5 +175,7 @@ Actions:
 ## Notes
 
 - Uses webhook signature verification for Twilio/Telnyx/Plivo.
+- Adds replay protection for Twilio and Plivo webhooks (valid duplicate callbacks are ignored safely).
+- Twilio speech turns include a per-turn token so stale/replayed callbacks cannot complete a newer turn.
 - `responseModel` / `responseSystemPrompt` control AI auto-responses.
 - Media streaming requires `ws` and OpenAI Realtime API key.

extensions/voice-call/src/manager.test.ts

@@ -17,12 +17,16 @@ import type {
 } from "./types.js";
 
 class FakeProvider implements VoiceCallProvider {
-  readonly name = "plivo" as const;
+  readonly name: "plivo" | "twilio";
   readonly playTtsCalls: PlayTtsInput[] = [];
   readonly hangupCalls: HangupCallInput[] = [];
   readonly startListeningCalls: StartListeningInput[] = [];
   readonly stopListeningCalls: StopListeningInput[] = [];
 
+  constructor(name: "plivo" | "twilio" = "plivo") {
+    this.name = name;
+  }
+
   verifyWebhook(_ctx: WebhookContext): WebhookVerificationResult {
     return { ok: true };
   }
@@ -319,6 +323,61 @@ describe("CallManager", () => {
     expect(provider.stopListeningCalls).toHaveLength(1);
   });
 
+  it("ignores speech events with mismatched turnToken while waiting for transcript", async () => {
+    const { manager, provider } = createManagerHarness(
+      {
+        transcriptTimeoutMs: 5000,
+      },
+      new FakeProvider("twilio"),
+    );
+
+    const started = await manager.initiateCall("+15550000004");
+    expect(started.success).toBe(true);
+
+    markCallAnswered(manager, started.callId, "evt-turn-token-answered");
+
+    const turnPromise = manager.continueCall(started.callId, "Prompt");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const expectedTurnToken = provider.startListeningCalls[0]?.turnToken;
+    expect(typeof expectedTurnToken).toBe("string");
+
+    manager.processEvent({
+      id: "evt-turn-token-bad",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "stale replay",
+      isFinal: true,
+      turnToken: "wrong-token",
+    });
+
+    const pendingState = await Promise.race([
+      turnPromise.then(() => "resolved"),
+      new Promise<"pending">((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+    expect(pendingState).toBe("pending");
+
+    manager.processEvent({
+      id: "evt-turn-token-good",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "final answer",
+      isFinal: true,
+      turnToken: expectedTurnToken,
+    });
+
+    const turnResult = await turnPromise;
+    expect(turnResult.success).toBe(true);
+    expect(turnResult.transcript).toBe("final answer");
+
+    const call = manager.getCall(started.callId);
+    expect(call?.transcript.map((entry) => entry.text)).toEqual(["Prompt", "final answer"]);
+  });
+
   it("tracks latency metadata across multiple closed-loop turns", async () => {
     const { manager, provider } = createManagerHarness({
       transcriptTimeoutMs: 5000,

extensions/voice-call/src/manager/context.ts

@@ -6,6 +6,7 @@ export type TranscriptWaiter = {
   resolve: (text: string) => void;
   reject: (err: Error) => void;
   timeout: NodeJS.Timeout;
+  turnToken?: string;
 };
 
 export type CallManagerRuntimeState = {

extensions/voice-call/src/manager/events.test.ts

@@ -234,4 +234,49 @@ describe("processEvent (functional)", () => {
     expect(() => processEvent(ctx, event)).not.toThrow();
     expect(ctx.activeCalls.size).toBe(0);
   });
+
+  it("deduplicates by dedupeKey even when event IDs differ", () => {
+    const now = Date.now();
+    const ctx = createContext();
+    ctx.activeCalls.set("call-dedupe", {
+      callId: "call-dedupe",
+      providerCallId: "provider-dedupe",
+      provider: "plivo",
+      direction: "outbound",
+      state: "answered",
+      from: "+15550000000",
+      to: "+15550000001",
+      startedAt: now,
+      transcript: [],
+      processedEventIds: [],
+      metadata: {},
+    });
+    ctx.providerCallIdMap.set("provider-dedupe", "call-dedupe");
+
+    processEvent(ctx, {
+      id: "evt-1",
+      dedupeKey: "stable-key-1",
+      type: "call.speech",
+      callId: "call-dedupe",
+      providerCallId: "provider-dedupe",
+      timestamp: now + 1,
+      transcript: "hello",
+      isFinal: true,
+    });
+
+    processEvent(ctx, {
+      id: "evt-2",
+      dedupeKey: "stable-key-1",
+      type: "call.speech",
+      callId: "call-dedupe",
+      providerCallId: "provider-dedupe",
+      timestamp: now + 2,
+      transcript: "hello",
+      isFinal: true,
+    });
+
+    const call = ctx.activeCalls.get("call-dedupe");
+    expect(call?.transcript).toHaveLength(1);
+    expect(Array.from(ctx.processedEventIds)).toEqual(["stable-key-1"]);
+  });
 });

extensions/voice-call/src/manager/events.ts

@@ -92,10 +92,11 @@ function createInboundCall(params: {
 }
 
 export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
-  if (ctx.processedEventIds.has(event.id)) {
+  const dedupeKey = event.dedupeKey || event.id;
+  if (ctx.processedEventIds.has(dedupeKey)) {
     return;
   }
-  ctx.processedEventIds.add(event.id);
+  ctx.processedEventIds.add(dedupeKey);
 
   let call = findCall({
     activeCalls: ctx.activeCalls,
@@ -158,7 +159,7 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
     }
   }
 
-  call.processedEventIds.push(event.id);
+  call.processedEventIds.push(dedupeKey);
 
   switch (event.type) {
     case "call.initiated":
@@ -192,8 +193,20 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
 
     case "call.speech":
       if (event.isFinal) {
+        const hadWaiter = ctx.transcriptWaiters.has(call.callId);
+        const resolved = resolveTranscriptWaiter(
+          ctx,
+          call.callId,
+          event.transcript,
+          event.turnToken,
+        );
+        if (hadWaiter && !resolved) {
+          console.warn(
+            `[voice-call] Ignoring speech event with mismatched turn token for ${call.callId}`,
+          );
+          break;
+        }
         addTranscriptEntry(call, "user", event.transcript);
-        resolveTranscriptWaiter(ctx, call.callId, event.transcript);
       }
       transitionState(call, "listening");
       break;

extensions/voice-call/src/manager/outbound.ts

@@ -291,6 +291,7 @@ export async function continueCall(
   ctx.activeTurnCalls.add(callId);
 
   const turnStartedAt = Date.now();
+  const turnToken = provider.name === "twilio" ? crypto.randomUUID() : undefined;
 
   try {
     await speak(ctx, callId, prompt);
@@ -299,9 +300,9 @@ export async function continueCall(
     persistCallRecord(ctx.storePath, call);
 
     const listenStartedAt = Date.now();
-    await provider.startListening({ callId, providerCallId });
+    await provider.startListening({ callId, providerCallId, turnToken });
 
-    const transcript = await waitForFinalTranscript(ctx, callId);
+    const transcript = await waitForFinalTranscript(ctx, callId, turnToken);
     const transcriptReceivedAt = Date.now();
 
     // Best-effort: stop listening after final transcript.

extensions/voice-call/src/manager/timers.ts

@@ -77,16 +77,25 @@ export function resolveTranscriptWaiter(
   ctx: TranscriptWaiterContext,
   callId: CallId,
   transcript: string,
-): void {
+  turnToken?: string,
+): boolean {
   const waiter = ctx.transcriptWaiters.get(callId);
   if (!waiter) {
-    return;
+    return false;
+  }
+  if (waiter.turnToken && waiter.turnToken !== turnToken) {
+    return false;
   }
   clearTranscriptWaiter(ctx, callId);
   waiter.resolve(transcript);
+  return true;
 }
 
-export function waitForFinalTranscript(ctx: TimerContext, callId: CallId): Promise<string> {
+export function waitForFinalTranscript(
+  ctx: TimerContext,
+  callId: CallId,
+  turnToken?: string,
+): Promise<string> {
   if (ctx.transcriptWaiters.has(callId)) {
     return Promise.reject(new Error("Already waiting for transcript"));
   }
@@ -98,6 +107,6 @@ export function waitForFinalTranscript(ctx: TimerContext, callId: CallId): Promi
       reject(new Error(`Timed out waiting for transcript after ${timeoutMs}ms`));
     }, timeoutMs);
 
-    ctx.transcriptWaiters.set(callId, { resolve, reject, timeout });
+    ctx.transcriptWaiters.set(callId, { resolve, reject, timeout, turnToken });
   });
 }

extensions/voice-call/src/providers/plivo.ts

@@ -30,6 +30,29 @@ export interface PlivoProviderOptions {
 type PendingSpeak = { text: string; locale?: string };
 type PendingListen = { language?: string };
 
+function getHeader(
+  headers: Record<string, string | string[] | undefined>,
+  name: string,
+): string | undefined {
+  const value = headers[name.toLowerCase()];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+
+function createPlivoRequestDedupeKey(ctx: WebhookContext): string {
+  const nonceV3 = getHeader(ctx.headers, "x-plivo-signature-v3-nonce");
+  if (nonceV3) {
+    return `plivo:v3:${nonceV3}`;
+  }
+  const nonceV2 = getHeader(ctx.headers, "x-plivo-signature-v2-nonce");
+  if (nonceV2) {
+    return `plivo:v2:${nonceV2}`;
+  }
+  return `plivo:fallback:${crypto.createHash("sha256").update(ctx.rawBody).digest("hex")}`;
+}
+
 export class PlivoProvider implements VoiceCallProvider {
   readonly name = "plivo" as const;
 
@@ -104,7 +127,7 @@ export class PlivoProvider implements VoiceCallProvider {
       console.warn(`[plivo] Webhook verification failed: ${result.reason}`);
     }
 
-    return { ok: result.ok, reason: result.reason };
+    return { ok: result.ok, reason: result.reason, isReplay: result.isReplay };
   }
 
   parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult {
@@ -173,7 +196,8 @@ export class PlivoProvider implements VoiceCallProvider {
 
     // Normal events.
     const callIdFromQuery = this.getCallIdFromQuery(ctx);
-    const event = this.normalizeEvent(parsed, callIdFromQuery);
+    const dedupeKey = createPlivoRequestDedupeKey(ctx);
+    const event = this.normalizeEvent(parsed, callIdFromQuery, dedupeKey);
 
     return {
       events: event ? [event] : [],
@@ -186,7 +210,11 @@ export class PlivoProvider implements VoiceCallProvider {
     };
   }
 
-  private normalizeEvent(params: URLSearchParams, callIdOverride?: string): NormalizedEvent | null {
+  private normalizeEvent(
+    params: URLSearchParams,
+    callIdOverride?: string,
+    dedupeKey?: string,
+  ): NormalizedEvent | null {
     const callUuid = params.get("CallUUID") || "";
     const requestUuid = params.get("RequestUUID") || "";
 
@@ -201,6 +229,7 @@ export class PlivoProvider implements VoiceCallProvider {
 
     const baseEvent = {
       id: crypto.randomUUID(),
+      dedupeKey,
       callId: callIdOverride || callUuid || requestUuid,
       providerCallId: callUuid || requestUuid || undefined,
       timestamp: Date.now(),