@openclaw/voice-call 2026.3.13 → 2026.5.1-beta.1

package/src/webhook-security.ts

@@ -1,4 +1,7 @@
 import crypto from "node:crypto";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { safeEqualSecret } from "openclaw/plugin-sdk/security-runtime";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
 import { getHeader } from "./http-headers.js";
 import type { WebhookContext } from "./types.js";
 
@@ -76,7 +79,7 @@ function markReplay(cache: ReplayCache, replayKey: string): boolean {
  *
  * @see https://www.twilio.com/docs/usage/webhooks/webhooks-security
  */
-export function validateTwilioSignature(
+function validateTwilioSignature(
   authToken: string,
   signature: string | undefined,
   url: string,
@@ -120,22 +123,13 @@ function buildCanonicalTwilioParamString(params: URLSearchParams): string {
  * Timing-safe string comparison to prevent timing attacks.
  */
 function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) {
-    // Still do comparison to maintain constant time
-    const dummy = Buffer.from(a);
-    crypto.timingSafeEqual(dummy, dummy);
-    return false;
-  }
-
-  const bufA = Buffer.from(a);
-  const bufB = Buffer.from(b);
-  return crypto.timingSafeEqual(bufA, bufB);
+  return safeEqualSecret(a, b);
 }
 
 /**
  * Configuration for secure URL reconstruction.
  */
-export interface WebhookUrlOptions {
+interface WebhookUrlOptions {
   /**
    * Whitelist of allowed hostnames. If provided, only these hosts will be
    * accepted from forwarding headers. This prevents host header injection attacks.
@@ -196,8 +190,8 @@ function extractHostname(hostHeader: string): string | null {
     if (endBracket === -1) {
       return null; // Malformed IPv6
     }
-    hostname = hostHeader.substring(1, endBracket);
-    return hostname.toLowerCase();
+    hostname = hostHeader.slice(1, endBracket);
+    return normalizeLowercaseStringOrEmpty(hostname);
   }
 
   // Handle IPv4/domain with optional port
@@ -213,7 +207,7 @@ function extractHostname(hostHeader: string): string | null {
     return null;
   }
 
-  return hostname.toLowerCase();
+  return normalizeLowercaseStringOrEmpty(hostname);
 }
 
 function extractHostnameFromHeader(headerValue: string): string | null {
@@ -417,7 +411,7 @@ function extractPortFromHostHeader(hostHeader?: string): string | undefined {
 /**
  * Result of Twilio webhook verification with detailed info.
  */
-export interface TwilioVerificationResult {
+interface TwilioVerificationResult {
   ok: boolean;
   reason?: string;
   /** The URL that was used for verification (for debugging) */
@@ -430,7 +424,7 @@ export interface TwilioVerificationResult {
   verifiedRequestKey?: string;
 }
 
-export interface TelnyxVerificationResult {
+interface TelnyxVerificationResult {
   ok: boolean;
   reason?: string;
   /** Request is cryptographically valid but was already processed recently. */
@@ -526,7 +520,7 @@ export function verifyTelnyxWebhook(
     return { ok: false, reason: "Missing signature or timestamp header" };
   }
 
-  const eventTimeSec = parseInt(timestamp, 10);
+  const eventTimeSec = Number.parseInt(timestamp, 10);
   if (!Number.isFinite(eventTimeSec)) {
     return { ok: false, reason: "Invalid timestamp header" };
   }
@@ -534,6 +528,8 @@ export function verifyTelnyxWebhook(
   try {
     const signedPayload = `${timestamp}|${ctx.rawBody}`;
     const signatureBuffer = decodeBase64OrBase64Url(signature);
+    // Canonicalize equivalent Base64/Base64URL encodings before replay hashing.
+    const canonicalSignature = signatureBuffer.toString("base64");
     const key = importEd25519PublicKey(publicKey);
 
     const isValid = crypto.verify(null, Buffer.from(signedPayload), key, signatureBuffer);
@@ -548,13 +544,13 @@ export function verifyTelnyxWebhook(
       return { ok: false, reason: "Timestamp too old" };
     }
 
-    const replayKey = `telnyx:${sha256Hex(`${timestamp}\n${signature}\n${ctx.rawBody}`)}`;
+    const replayKey = `telnyx:${sha256Hex(`${timestamp}\n${canonicalSignature}\n${ctx.rawBody}`)}`;
     const isReplay = markReplay(telnyxReplayCache, replayKey);
     return { ok: true, isReplay, verifiedRequestKey: replayKey };
   } catch (err) {
     return {
       ok: false,
-      reason: `Verification error: ${err instanceof Error ? err.message : String(err)}`,
+      reason: `Verification error: ${formatErrorMessage(err)}`,
     };
   }
 }
@@ -702,7 +698,7 @@ export function verifyTwilioWebhook(
 /**
  * Result of Plivo webhook verification with detailed info.
  */
-export interface PlivoVerificationResult {
+interface PlivoVerificationResult {
   ok: boolean;
   reason?: string;
   verificationUrl?: string;
@@ -724,13 +720,26 @@ function getBaseUrlNoQuery(url: string): string {
   return `${u.protocol}//${u.host}${u.pathname}`;
 }
 
+function createPlivoV2ReplayKey(url: string, nonce: string): string {
+  return `plivo:v2:${sha256Hex(`${getBaseUrlNoQuery(url)}\n${nonce}`)}`;
+}
+
+function createPlivoV3ReplayKey(params: {
+  method: "GET" | "POST";
+  url: string;
+  postParams: PlivoParamMap;
+  nonce: string;
+}): string {
+  const baseUrl = constructPlivoV3BaseUrl({
+    method: params.method,
+    url: params.url,
+    postParams: params.postParams,
+  });
+  return `plivo:v3:${sha256Hex(`${baseUrl}\n${params.nonce}`)}`;
+}
+
 function timingSafeEqualString(a: string, b: string): boolean {
-  if (a.length !== b.length) {
-    const dummy = Buffer.from(a);
-    crypto.timingSafeEqual(dummy, dummy);
-    return false;
-  }
-  return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  return safeEqualSecret(a, b);
 }
 
 function validatePlivoV2Signature(params: {
@@ -947,7 +956,12 @@ export function verifyPlivoWebhook(
         reason: "Invalid Plivo V3 signature",
       };
     }
-    const replayKey = `plivo:v3:${sha256Hex(`${verificationUrl}\n${nonceV3}`)}`;
+    const replayKey = createPlivoV3ReplayKey({
+      method,
+      url: verificationUrl,
+      postParams,
+      nonce: nonceV3,
+    });
     const isReplay = markReplay(plivoReplayCache, replayKey);
     return { ok: true, version: "v3", verificationUrl, isReplay, verifiedRequestKey: replayKey };
   }
@@ -967,7 +981,7 @@ export function verifyPlivoWebhook(
         reason: "Invalid Plivo V2 signature",
       };
     }
-    const replayKey = `plivo:v2:${sha256Hex(`${verificationUrl}\n${nonceV2}`)}`;
+    const replayKey = createPlivoV2ReplayKey(verificationUrl, nonceV2);
     const isReplay = markReplay(plivoReplayCache, replayKey);
     return { ok: true, version: "v2", verificationUrl, isReplay, verifiedRequestKey: replayKey };
   }

package/src/webhook.hangup-once.lifecycle.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { VoiceCallConfigSchema, type VoiceCallConfig } from "./config.js";
+import { CallManager } from "./manager.js";
+import { createTestStorePath, FakeProvider } from "./manager.test-harness.js";
+import type { WebhookContext, WebhookParseOptions } from "./types.js";
+import { VoiceCallWebhookServer } from "./webhook.js";
+
+const createConfig = (overrides: Partial<VoiceCallConfig> = {}): VoiceCallConfig => {
+  const base = VoiceCallConfigSchema.parse({
+    enabled: true,
+    provider: "plivo",
+    fromNumber: "+15550000000",
+    inboundPolicy: "disabled",
+  });
+  base.serve.port = 0;
+
+  return {
+    ...base,
+    ...overrides,
+    serve: {
+      ...base.serve,
+      ...overrides.serve,
+    },
+  };
+};
+
+async function postWebhookForm(server: VoiceCallWebhookServer, baseUrl: string, body: string) {
+  const address = (
+    server as unknown as { server?: { address?: () => unknown } }
+  ).server?.address?.();
+  const requestUrl = new URL(baseUrl);
+  if (
+    !address ||
+    typeof address !== "object" ||
+    !("port" in address) ||
+    (typeof address.port !== "number" && typeof address.port !== "string") ||
+    !address.port
+  ) {
+    throw new Error("voice webhook server did not expose a bound port");
+  }
+  requestUrl.port = String(address.port);
+  return await fetch(requestUrl.toString(), {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      "x-plivo-signature-v2": "sig",
+      "x-plivo-signature-v2-nonce": "nonce",
+    },
+    body,
+  });
+}
+
+async function runDuplicateInboundReplayLifecycleTest(provider: FakeProvider) {
+  const config = createConfig();
+  const manager = new CallManager(config, createTestStorePath());
+  await manager.initialize(provider, "https://example.com/voice/webhook");
+  const server = new VoiceCallWebhookServer(config, manager, provider);
+
+  try {
+    const baseUrl = await server.start();
+    const first = await postWebhookForm(server, baseUrl, "CallSid=CA123&From=%2B15552222222");
+    const second = await postWebhookForm(server, baseUrl, "CallSid=CA123&From=%2B15552222222");
+    return { first, second, manager };
+  } finally {
+    await server.stop();
+  }
+}
+
+function expectSingleRejectedReplayHangup(params: {
+  first: Response;
+  second: Response;
+  provider: FakeProvider;
+  manager: CallManager;
+}) {
+  expect(params.first.status).toBe(200);
+  expect(params.second.status).toBe(200);
+  expect(params.provider.hangupCalls).toHaveLength(1);
+  expect(params.provider.hangupCalls[0]).toEqual(
+    expect.objectContaining({
+      providerCallId: "provider-inbound-1",
+      reason: "hangup-bot",
+    }),
+  );
+  expect(params.manager.getCallByProviderCallId("provider-inbound-1")).toBeUndefined();
+}
+
+class RejectInboundReplayProvider extends FakeProvider {
+  override verifyWebhook() {
+    return { ok: true, verifiedRequestKey: "verified:req:reject-once" };
+  }
+
+  override parseWebhookEvent(_ctx: WebhookContext, options?: WebhookParseOptions) {
+    return {
+      statusCode: 200,
+      events: [
+        {
+          id: "evt-reject-once",
+          dedupeKey: options?.verifiedRequestKey,
+          type: "call.initiated" as const,
+          callId: "provider-inbound-1",
+          providerCallId: "provider-inbound-1",
+          timestamp: Date.now(),
+          direction: "inbound" as const,
+          from: "+15552222222",
+          to: "+15550000000",
+        },
+      ],
+    };
+  }
+}
+
+class RejectInboundReplayWithHangupFailureProvider extends RejectInboundReplayProvider {
+  override async hangupCall(input: Parameters<FakeProvider["hangupCall"]>[0]): Promise<void> {
+    this.hangupCalls.push(input);
+    throw new Error("hangup failed");
+  }
+}
+
+describe("Voice-call webhook hangup-once lifecycle", () => {
+  afterEach(() => {
+    // Each test uses an isolated store path, so only server cleanup is needed.
+  });
+
+  it("hangs up a rejected inbound replay only once across duplicate webhook delivery", async () => {
+    const provider = new RejectInboundReplayProvider("plivo");
+    const { first, second, manager } = await runDuplicateInboundReplayLifecycleTest(provider);
+    expectSingleRejectedReplayHangup({ first, second, provider, manager });
+  });
+
+  it("does not attempt a second hangup when replay arrives after the first hangup fails", async () => {
+    const provider = new RejectInboundReplayWithHangupFailureProvider("plivo");
+    const { first, second, manager } = await runDuplicateInboundReplayLifecycleTest(provider);
+    expectSingleRejectedReplayHangup({ first, second, provider, manager });
+  });
+});