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

package/src/webhook/tailscale.test.ts

@@ -0,0 +1,214 @@
+import { EventEmitter } from "node:events";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { spawnMock } = vi.hoisted(() => ({
+  spawnMock: vi.fn(),
+}));
+
+vi.mock("node:child_process", async () => {
+  const { mockNodeBuiltinModule } = await import("openclaw/plugin-sdk/test-node-mocks");
+  return mockNodeBuiltinModule(
+    () => vi.importActual<typeof import("node:child_process")>("node:child_process"),
+    {
+      spawn: spawnMock,
+    },
+  );
+});
+
+import {
+  cleanupTailscaleExposure,
+  cleanupTailscaleExposureRoute,
+  getTailscaleDnsName,
+  getTailscaleSelfInfo,
+  setupTailscaleExposure,
+  setupTailscaleExposureRoute,
+} from "./tailscale.js";
+
+function createProc(params?: { code?: number; stdout?: string }) {
+  const proc = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter;
+    kill: ReturnType<typeof vi.fn>;
+  };
+  proc.stdout = new EventEmitter();
+  proc.kill = vi.fn();
+  setTimeout(() => {
+    if (params?.stdout) {
+      proc.stdout.emit("data", Buffer.from(params.stdout));
+    }
+    proc.emit("close", params?.code ?? 0);
+  }, 0);
+  return proc;
+}
+
+function createErrorProc() {
+  const proc = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter;
+    kill: ReturnType<typeof vi.fn>;
+  };
+  proc.stdout = new EventEmitter();
+  proc.kill = vi.fn();
+  setTimeout(() => {
+    proc.emit("error", Object.assign(new Error("spawn tailscale ENOENT"), { code: "ENOENT" }));
+  }, 0);
+  return proc;
+}
+
+describe("voice-call tailscale helpers", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("reads dns and node id from tailscale status json", async () => {
+    spawnMock
+      .mockReturnValueOnce(
+        createProc({
+          stdout: JSON.stringify({
+            Self: {
+              DNSName: "bot.example.ts.net.",
+              ID: "node-123",
+            },
+          }),
+        }),
+      )
+      .mockReturnValueOnce(
+        createProc({
+          stdout: JSON.stringify({
+            Self: {
+              DNSName: "bot.example.ts.net.",
+              ID: "node-123",
+            },
+          }),
+        }),
+      );
+
+    await expect(getTailscaleSelfInfo()).resolves.toEqual({
+      dnsName: "bot.example.ts.net",
+      nodeId: "node-123",
+    });
+    await expect(getTailscaleDnsName()).resolves.toBe("bot.example.ts.net");
+  });
+
+  it("returns null for failing or invalid status responses", async () => {
+    spawnMock.mockReturnValueOnce(createProc({ code: 1, stdout: "bad" }));
+    await expect(getTailscaleSelfInfo()).resolves.toBeNull();
+
+    spawnMock.mockReturnValueOnce(createProc({ stdout: "{not-json" }));
+    await expect(getTailscaleSelfInfo()).resolves.toBeNull();
+  });
+
+  it("treats missing tailscale binary as unavailable instead of leaking spawn errors", async () => {
+    spawnMock.mockReturnValueOnce(createErrorProc());
+
+    await expect(getTailscaleSelfInfo()).resolves.toBeNull();
+  });
+
+  it("sets up and cleans up exposure routes with the selected mode", async () => {
+    spawnMock
+      .mockReturnValueOnce(
+        createProc({
+          stdout: JSON.stringify({ Self: { DNSName: "bot.example.ts.net." } }),
+        }),
+      )
+      .mockReturnValueOnce(createProc({ code: 0 }))
+      .mockReturnValueOnce(createProc({ code: 0 }));
+
+    await expect(
+      setupTailscaleExposureRoute({
+        mode: "serve",
+        path: "/voice",
+        localUrl: "http://127.0.0.1:8787/webhook",
+      }),
+    ).resolves.toBe("https://bot.example.ts.net/voice");
+
+    await cleanupTailscaleExposureRoute({ mode: "serve", path: "/voice" });
+
+    expect(spawnMock).toHaveBeenNthCalledWith(
+      1,
+      "tailscale",
+      ["status", "--json"],
+      expect.objectContaining({ stdio: ["ignore", "pipe", "pipe"] }),
+    );
+    expect(spawnMock).toHaveBeenNthCalledWith(
+      2,
+      "tailscale",
+      ["serve", "--bg", "--yes", "--set-path", "/voice", "http://127.0.0.1:8787/webhook"],
+      expect.any(Object),
+    );
+    expect(spawnMock).toHaveBeenNthCalledWith(
+      3,
+      "tailscale",
+      ["serve", "off", "/voice"],
+      expect.any(Object),
+    );
+  });
+
+  it("returns null when setup cannot resolve dns or route activation fails", async () => {
+    spawnMock
+      .mockReturnValueOnce(createProc({ code: 1 }))
+      .mockReturnValueOnce(
+        createProc({
+          stdout: JSON.stringify({ Self: { DNSName: "bot.example.ts.net." } }),
+        }),
+      )
+      .mockReturnValueOnce(createProc({ code: 1 }));
+
+    await expect(
+      setupTailscaleExposureRoute({
+        mode: "funnel",
+        path: "/voice",
+        localUrl: "http://127.0.0.1:8787/webhook",
+      }),
+    ).resolves.toBeNull();
+
+    await expect(
+      setupTailscaleExposureRoute({
+        mode: "funnel",
+        path: "/voice",
+        localUrl: "http://127.0.0.1:8787/webhook",
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it("maps config modes to serve or funnel and skips off", async () => {
+    spawnMock
+      .mockReturnValueOnce(
+        createProc({
+          stdout: JSON.stringify({ Self: { DNSName: "bot.example.ts.net." } }),
+        }),
+      )
+      .mockReturnValueOnce(createProc({ code: 0 }))
+      .mockReturnValueOnce(createProc({ code: 0 }));
+
+    await expect(
+      setupTailscaleExposure({
+        tailscale: { mode: "off", path: "/voice" },
+        serve: { port: 8787, path: "/webhook" },
+      } as never),
+    ).resolves.toBeNull();
+
+    await expect(
+      setupTailscaleExposure({
+        tailscale: { mode: "funnel", path: "/voice" },
+        serve: { port: 8787, path: "/webhook" },
+      } as never),
+    ).resolves.toBe("https://bot.example.ts.net/voice");
+
+    await cleanupTailscaleExposure({
+      tailscale: { mode: "serve", path: "/voice" },
+      serve: { port: 8787, path: "/webhook" },
+    } as never);
+
+    expect(spawnMock).toHaveBeenNthCalledWith(
+      2,
+      "tailscale",
+      ["funnel", "--bg", "--yes", "--set-path", "/voice", "http://127.0.0.1:8787/webhook"],
+      expect.any(Object),
+    );
+    expect(spawnMock).toHaveBeenNthCalledWith(
+      3,
+      "tailscale",
+      ["serve", "off", "/voice"],
+      expect.any(Object),
+    );
+  });
+});

package/src/webhook/tailscale.ts

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import type { VoiceCallConfig } from "../config.js";
 
-export type TailscaleSelfInfo = {
+type TailscaleSelfInfo = {
   dnsName: string | null;
   nodeId: string | null;
 };
@@ -16,18 +16,32 @@ function runTailscaleCommand(
     });
 
     let stdout = "";
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    const finish = (result: { code: number; stdout: string }) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+
     proc.stdout.on("data", (data) => {
       stdout += data;
     });
 
-    const timer = setTimeout(() => {
+    timer = setTimeout(() => {
       proc.kill("SIGKILL");
-      resolve({ code: -1, stdout: "" });
+      finish({ code: -1, stdout: "" });
     }, timeoutMs);
 
+    proc.on("error", () => {
+      finish({ code: -1, stdout: "" });
+    });
+
     proc.on("close", (code) => {
-      clearTimeout(timer);
-      resolve({ code: code ?? -1, stdout });
+      finish({ code: code ?? -1, stdout });
     });
   });
 }

package/src/webhook-exposure.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { isLocalOnlyWebhookHost, isProviderUnreachableWebhookUrl } from "./webhook-exposure.js";
+
+describe("webhook exposure host classification", () => {
+  it.each([
+    "http://[::]:3334/voice/webhook",
+    "http://[::1]:3334/voice/webhook",
+    "http://[fc00::1]/voice/webhook",
+    "http://[fd00::1]/voice/webhook",
+    "http://[::ffff:127.0.0.1]/voice/webhook",
+    "http://[::ffff:10.0.0.1]/voice/webhook",
+    "http://[::ffff:192.168.0.1]/voice/webhook",
+    "http://[::ffff:172.16.0.1]/voice/webhook",
+    "http://[fe80::1]/voice/webhook",
+  ])("treats local/private webhook URL %s as provider-unreachable", (url) => {
+    expect(isProviderUnreachableWebhookUrl(url)).toBe(true);
+  });
+
+  it.each([
+    "http://[::ffff:8.8.8.8]/voice/webhook",
+    "https://voice.example.com/voice/webhook",
+    "https://fcloud.example/voice/webhook",
+  ])("does not reject public webhook URL %s", (url) => {
+    expect(isProviderUnreachableWebhookUrl(url)).toBe(false);
+  });
+
+  it.each(["[::1]", "[fc00::1]", "[fd00::1]", "::ffff:7f00:1", "::ffff:a00:1", "[fe80::1]"])(
+    "normalizes local/private URL hostnames like %s",
+    (host) => {
+      expect(isLocalOnlyWebhookHost(host)).toBe(true);
+    },
+  );
+});

package/src/webhook-exposure.ts

@@ -0,0 +1,84 @@
+import { isBlockedHostnameOrIp } from "../api.js";
+
+type VoiceCallWebhookExposureConfig = {
+  provider?: string;
+  publicUrl?: string;
+  tunnel?: {
+    provider?: string;
+  };
+  tailscale?: {
+    mode?: string;
+  };
+};
+
+type VoiceCallWebhookExposureStatus = {
+  ok: boolean;
+  configured: boolean;
+  message: string;
+};
+
+export function providerRequiresPublicWebhook(providerName: string | undefined): boolean {
+  return providerName === "twilio" || providerName === "telnyx" || providerName === "plivo";
+}
+
+export function isLocalOnlyWebhookHost(hostname: string): boolean {
+  return isBlockedHostnameOrIp(hostname);
+}
+
+export function isProviderUnreachableWebhookUrl(webhookUrl: string): boolean {
+  try {
+    const parsed = new URL(webhookUrl);
+    return isLocalOnlyWebhookHost(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveWebhookExposureStatus(
+  config: VoiceCallWebhookExposureConfig,
+): VoiceCallWebhookExposureStatus {
+  if (config.provider === "mock") {
+    return {
+      ok: true,
+      configured: true,
+      message: "Mock provider does not need a public webhook",
+    };
+  }
+
+  if (config.publicUrl) {
+    if (isProviderUnreachableWebhookUrl(config.publicUrl)) {
+      return {
+        ok: false,
+        configured: true,
+        message: `Public webhook URL is local/private and cannot be reached by ${config.provider ?? "the provider"}: ${config.publicUrl}`,
+      };
+    }
+    return {
+      ok: true,
+      configured: true,
+      message: `Public webhook URL configured: ${config.publicUrl}`,
+    };
+  }
+
+  if (config.tunnel?.provider && config.tunnel.provider !== "none") {
+    return {
+      ok: true,
+      configured: true,
+      message: "Webhook exposure configured through tunnel",
+    };
+  }
+
+  if (config.tailscale?.mode && config.tailscale.mode !== "off") {
+    return {
+      ok: true,
+      configured: true,
+      message: "Webhook exposure configured through Tailscale",
+    };
+  }
+
+  return {
+    ok: false,
+    configured: false,
+    message: "Set publicUrl or configure tunnel/tailscale so the provider can reach webhooks",
+  };
+}

package/src/webhook-security.test.ts

@@ -92,7 +92,9 @@ function expectReplayResultPair(
 ) {
   expect(first.ok).toBe(true);
   expect(first.isReplay).toBeFalsy();
-  expect(first.verifiedRequestKey).toBeTruthy();
+  if (!first.verifiedRequestKey) {
+    throw new Error("verified webhook request did not produce a request key");
+  }
   expect(second.ok).toBe(true);
   expect(second.isReplay).toBe(true);
   expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
@@ -143,6 +145,36 @@ function verifyTwilioSignedRequest(params: {
   );
 }
 
+function createSignedTelnyxWebhookRequest() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const pemPublicKey = publicKey.export({ format: "pem", type: "spki" });
+  const timestamp = String(Math.floor(Date.now() / 1000));
+  const rawBody = JSON.stringify({
+    data: { event_type: "call.initiated", payload: { call_control_id: "call-1" } },
+    nonce: crypto.randomUUID(),
+  });
+  const signedPayload = `${timestamp}|${rawBody}`;
+  const signature = crypto.sign(null, Buffer.from(signedPayload), privateKey).toString("base64");
+
+  return {
+    pemPublicKey,
+    timestamp,
+    rawBody,
+    signature,
+    makeCtx(signatureValue = signature) {
+      return {
+        headers: {
+          "telnyx-signature-ed25519": signatureValue,
+          "telnyx-timestamp": timestamp,
+        },
+        rawBody,
+        url: "https://example.com/voice/webhook",
+        method: "POST" as const,
+      };
+    },
+  };
+}
+
 describe("verifyPlivoWebhook", () => {
   it("accepts valid V2 signature", () => {
     const authToken = "test-auth-token";
@@ -254,6 +286,52 @@ describe("verifyPlivoWebhook", () => {
     expectReplayResultPair(first, second);
   });
 
+  it("treats query-only V2 variants as the same verified request", () => {
+    const authToken = "test-auth-token";
+    const nonce = "nonce-replay-v2";
+    const verificationUrl = "https://example.com/voice/webhook";
+    const signature = plivoV2Signature({
+      authToken,
+      urlNoQuery: verificationUrl,
+      nonce,
+    });
+
+    const baseHeaders = {
+      host: "example.com",
+      "x-forwarded-proto": "https",
+      "x-plivo-signature-v2": signature,
+      "x-plivo-signature-v2-nonce": nonce,
+    };
+    const rawBody = "CallUUID=uuid&CallStatus=in-progress";
+
+    const first = verifyPlivoWebhook(
+      {
+        headers: baseHeaders,
+        rawBody,
+        url: `${verificationUrl}?flow=answer&callId=abc`,
+        method: "POST",
+        query: { flow: "answer", callId: "abc" },
+      },
+      authToken,
+    );
+    const second = verifyPlivoWebhook(
+      {
+        headers: baseHeaders,
+        rawBody,
+        url: `${verificationUrl}?flow=getinput&callId=abc`,
+        method: "POST",
+        query: { flow: "getinput", callId: "abc" },
+      },
+      authToken,
+    );
+
+    expect(first.ok).toBe(true);
+    expect(first.verifiedRequestKey).toBeDefined();
+    expect(second.ok).toBe(true);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+    expect(second.isReplay).toBe(true);
+  });
+
   it("returns a stable request key when verification is skipped", () => {
     const ctx = {
       headers: {},
@@ -269,31 +347,73 @@ describe("verifyPlivoWebhook", () => {
     expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
     expect(second.isReplay).toBe(true);
   });
+
+  it("detects V3 replay when query parameters are reordered", () => {
+    const authToken = "test-auth-token";
+    const nonce = "nonce-v3-reorder";
+    const postBody = "CallUUID=uuid&CallStatus=in-progress";
+
+    const urlA = "https://example.com/voice/webhook?flow=answer&callId=abc";
+    const urlB = "https://example.com/voice/webhook?callId=abc&flow=answer";
+
+    const signatureA = plivoV3Signature({ authToken, urlWithQuery: urlA, postBody, nonce });
+    const signatureB = plivoV3Signature({ authToken, urlWithQuery: urlB, postBody, nonce });
+    expect(signatureA).toBe(signatureB);
+
+    const first = verifyPlivoWebhook(
+      {
+        headers: {
+          host: "example.com",
+          "x-forwarded-proto": "https",
+          "x-plivo-signature-v3": signatureA,
+          "x-plivo-signature-v3-nonce": nonce,
+        },
+        rawBody: postBody,
+        url: urlA,
+        method: "POST",
+        query: { flow: "answer", callId: "abc" },
+      },
+      authToken,
+    );
+
+    const second = verifyPlivoWebhook(
+      {
+        headers: {
+          host: "example.com",
+          "x-forwarded-proto": "https",
+          "x-plivo-signature-v3": signatureB,
+          "x-plivo-signature-v3-nonce": nonce,
+        },
+        rawBody: postBody,
+        url: urlB,
+        method: "POST",
+        query: { callId: "abc", flow: "answer" },
+      },
+      authToken,
+    );
+
+    expectReplayResultPair(first, second);
+  });
 });
 
 describe("verifyTelnyxWebhook", () => {
   it("marks replayed valid requests as replay without failing auth", () => {
-    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
-    const pemPublicKey = publicKey.export({ format: "pem", type: "spki" }).toString();
-    const timestamp = String(Math.floor(Date.now() / 1000));
-    const rawBody = JSON.stringify({
-      data: { event_type: "call.initiated", payload: { call_control_id: "call-1" } },
-      nonce: crypto.randomUUID(),
-    });
-    const signedPayload = `${timestamp}|${rawBody}`;
-    const signature = crypto.sign(null, Buffer.from(signedPayload), privateKey).toString("base64");
-    const ctx = {
-      headers: {
-        "telnyx-signature-ed25519": signature,
-        "telnyx-timestamp": timestamp,
-      },
-      rawBody,
-      url: "https://example.com/voice/webhook",
-      method: "POST" as const,
-    };
+    const request = createSignedTelnyxWebhookRequest();
 
-    const first = verifyTelnyxWebhook(ctx, pemPublicKey);
-    const second = verifyTelnyxWebhook(ctx, pemPublicKey);
+    const first = verifyTelnyxWebhook(request.makeCtx(), request.pemPublicKey);
+    const second = verifyTelnyxWebhook(request.makeCtx(), request.pemPublicKey);
+
+    expectReplayResultPair(first, second);
+  });
+
+  it("treats Base64 and Base64URL signatures as the same replayed request", () => {
+    const request = createSignedTelnyxWebhookRequest();
+    const urlSafeSignature = request.signature
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/g, "");
+    const first = verifyTelnyxWebhook(request.makeCtx(), request.pemPublicKey);
+    const second = verifyTelnyxWebhook(request.makeCtx(urlSafeSignature), request.pemPublicKey);
 
     expectReplayResultPair(first, second);
   });
@@ -498,6 +618,37 @@ describe("verifyTwilioWebhook", () => {
     expect(result.verificationUrl).toBe(webhookUrl);
   });
 
+  it("verifies Twilio signatures for Cloudflare Tunnel publicUrl requests", () => {
+    const authToken = "test-auth-token";
+    const postBody = "CallSid=CA123&CallStatus=ringing&Direction=inbound&From=%2B15550000000";
+    const webhookUrl = "https://oc1.example.com/voice/webhook";
+    const signature = twilioSignature({ authToken, url: webhookUrl, postBody });
+
+    const result = verifyTwilioWebhook(
+      {
+        headers: {
+          host: "localhost:8765",
+          "cf-connecting-ip": "203.0.113.42",
+          "x-forwarded-proto": "https",
+          "x-twilio-signature": signature,
+        },
+        rawBody: postBody,
+        url: "http://localhost:8765/voice/webhook",
+        method: "POST",
+        remoteAddress: "127.0.0.1",
+      },
+      authToken,
+      {
+        publicUrl: webhookUrl,
+        allowedHosts: ["oc1.example.com"],
+        trustForwardingHeaders: true,
+      },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.verificationUrl).toBe(webhookUrl);
+  });
+
   it("rejects X-Forwarded-Host not in allowedHosts whitelist", () => {
     const authToken = "test-auth-token";
     const postBody = "CallSid=CS123&CallStatus=completed&From=%2B15550000000";