niahere 0.3.0 → 0.3.1

package/src/channels/twilio/media-cache.ts

@@ -0,0 +1,107 @@
+/**
+ * Disk-backed cache for outbound Twilio media.
+ *
+ * Twilio fetches outbound MMS/WhatsApp media by URL, so we write the
+ * payload to ~/.niahere/tmp/outbound/<sha>.<ext>, expose it under
+ * GET /twilio/media/<sha>.<ext>, and Twilio retrieves it. Disk (not
+ * memory) so the URL survives daemon restarts and Twilio's webhook
+ * retries within the eviction window.
+ *
+ * Eviction is opportunistic: capped at 100 files, 10MB total, 24h max
+ * age. Oldest-first; expired-first. Runs after every write; cheap
+ * enough at this scale (single user, low traffic).
+ */
+import { mkdir, readdir, readFile, stat, unlink, writeFile } from "fs/promises";
+import { createHash } from "crypto";
+import { join } from "path";
+import { getNiaHome } from "../../utils/paths";
+import { log } from "../../utils/log";
+
+const MAX_FILES = 100;
+const MAX_BYTES = 10 * 1024 * 1024;
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+const MIME_TO_EXT: Record<string, string> = {
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "audio/mpeg": "mp3",
+  "audio/mp4": "m4a",
+  "audio/ogg": "ogg",
+  "audio/wav": "wav",
+  "video/mp4": "mp4",
+  "application/pdf": "pdf",
+};
+
+const FILENAME_RE = /^[a-f0-9]{16,64}\.[a-z0-9]{1,8}$/i;
+
+export function getMediaDir(): string {
+  return join(getNiaHome(), "tmp", "outbound");
+}
+
+export interface CachedMedia {
+  filename: string;
+  path: string;
+}
+
+export async function cacheMedia(buffer: Uint8Array, mime: string, ext?: string): Promise<CachedMedia> {
+  const dir = getMediaDir();
+  await mkdir(dir, { recursive: true });
+  const resolvedExt = (ext ?? MIME_TO_EXT[mime] ?? "bin").replace(/[^a-z0-9]/gi, "").slice(0, 8) || "bin";
+  const hash = createHash("sha256").update(buffer).digest("hex").slice(0, 32);
+  const filename = `${hash}.${resolvedExt}`;
+  const path = join(dir, filename);
+  await writeFile(path, buffer);
+  await evict().catch((err) => log.warn({ err }, "media-cache: eviction failed"));
+  return { filename, path };
+}
+
+export async function readCachedMedia(filename: string): Promise<{ buffer: Buffer; mime: string } | null> {
+  if (!FILENAME_RE.test(filename)) return null;
+  const path = join(getMediaDir(), filename);
+  try {
+    const buffer = await readFile(path);
+    const ext = filename.split(".").pop()!.toLowerCase();
+    const mime = Object.entries(MIME_TO_EXT).find(([, e]) => e === ext)?.[0] ?? "application/octet-stream";
+    return { buffer, mime };
+  } catch {
+    return null;
+  }
+}
+
+async function evict(): Promise<void> {
+  const dir = getMediaDir();
+  const entries = await readdir(dir);
+  const stats = await Promise.all(
+    entries.map(async (name) => {
+      const path = join(dir, name);
+      const s = await stat(path);
+      return { name, path, mtime: s.mtimeMs, size: s.size };
+    }),
+  );
+
+  const now = Date.now();
+  let alive: typeof stats = [];
+  for (const s of stats) {
+    if (now - s.mtime > MAX_AGE_MS) {
+      await unlink(s.path).catch(() => {});
+    } else {
+      alive.push(s);
+    }
+  }
+
+  alive.sort((a, b) => a.mtime - b.mtime);
+
+  while (alive.length > MAX_FILES) {
+    const victim = alive.shift()!;
+    await unlink(victim.path).catch(() => {});
+  }
+
+  let totalBytes = alive.reduce((sum, f) => sum + f.size, 0);
+  while (totalBytes > MAX_BYTES && alive.length > 0) {
+    const victim = alive.shift()!;
+    totalBytes -= victim.size;
+    await unlink(victim.path).catch(() => {});
+  }
+}

package/src/channels/twilio/media.ts

@@ -0,0 +1,79 @@
+/**
+ * Download inbound media attached to a Twilio webhook.
+ *
+ * Twilio's MediaUrlN values are HTTPS URLs that 302-redirect to S3.
+ * They sit behind Basic auth (same Twilio creds), so a vanilla fetch
+ * without an Authorization header gets 401. Bun's fetch follows the
+ * redirect transparently.
+ *
+ * Concurrency is bounded (4 in flight, 10s per item) so a sender that
+ * attaches many large files cannot stall the webhook handler.
+ */
+import { log } from "../../utils/log";
+import type { TwilioCreds } from "./rest";
+
+const MAX_CONCURRENT = 4;
+const TIMEOUT_MS = 10_000;
+
+export interface InboundMedia {
+  index: number;
+  url: string;
+  mime: string;
+  data: Buffer;
+}
+
+export interface MediaDescriptor {
+  index: number;
+  url: string;
+  mime: string;
+}
+
+/**
+ * Pull out the NumMedia / MediaUrlN / MediaContentTypeN fields from a
+ * Twilio webhook form body.
+ */
+export function extractMedia(params: Record<string, string>): MediaDescriptor[] {
+  const num = parseInt(params.NumMedia || "0", 10);
+  if (!Number.isFinite(num) || num <= 0) return [];
+  const items: MediaDescriptor[] = [];
+  for (let i = 0; i < num; i++) {
+    const url = params[`MediaUrl${i}`];
+    const mime = params[`MediaContentType${i}`];
+    if (url && mime) items.push({ index: i, url, mime });
+  }
+  return items;
+}
+
+export async function downloadInboundMedia(
+  descriptors: MediaDescriptor[],
+  creds: TwilioCreds,
+): Promise<InboundMedia[]> {
+  const out: InboundMedia[] = [];
+  for (let i = 0; i < descriptors.length; i += MAX_CONCURRENT) {
+    const slice = descriptors.slice(i, i + MAX_CONCURRENT);
+    const results = await Promise.allSettled(slice.map((d) => downloadOne(d, creds)));
+    for (let j = 0; j < results.length; j++) {
+      const r = results[j];
+      if (r.status === "fulfilled") {
+        out.push(r.value);
+      } else {
+        log.warn({ err: r.reason, descriptor: slice[j] }, "twilio: media download failed");
+      }
+    }
+  }
+  return out;
+}
+
+async function downloadOne(d: MediaDescriptor, creds: TwilioCreds): Promise<InboundMedia> {
+  const auth = `Basic ${Buffer.from(`${creds.authSid}:${creds.authSecret}`).toString("base64")}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const resp = await fetch(d.url, { headers: { Authorization: auth }, signal: controller.signal });
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    const buffer = Buffer.from(await resp.arrayBuffer());
+    return { index: d.index, url: d.url, mime: d.mime, data: buffer };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/channels/twilio/rate-limit.ts

@@ -0,0 +1,33 @@
+/**
+ * Sliding-window rate limiter keyed by an arbitrary string (e.g. caller
+ * E.164). Protects against runaway costs when the WhatsApp Sandbox's
+ * shared number gets random opt-ins and someone spams.
+ */
+export class RateLimiter {
+  private readonly hits = new Map<string, number[]>();
+
+  constructor(
+    private readonly maxPerWindow: number = 30,
+    private readonly windowMs: number = 60_000,
+  ) {}
+
+  /** Returns true if this hit was allowed (and recorded); false if over limit. */
+  allow(key: string): boolean {
+    const now = Date.now();
+    const cutoff = now - this.windowMs;
+    const arr = this.hits.get(key) ?? [];
+    const recent = arr.filter((t) => t > cutoff);
+    if (recent.length >= this.maxPerWindow) {
+      this.hits.set(key, recent);
+      return false;
+    }
+    recent.push(now);
+    this.hits.set(key, recent);
+    return true;
+  }
+
+  /** Drop tracking for a key (e.g. owner number — never rate-limit yourself). */
+  exempt(key: string): void {
+    this.hits.delete(key);
+  }
+}

package/src/channels/twilio/rest.ts

@@ -0,0 +1,133 @@
+/**
+ * Minimal Twilio REST API helpers shared by all Twilio-based channels
+ * (voice, SMS, WhatsApp). No SDK — keeps dependency surface small and
+ * the helpers easy to read.
+ *
+ * Auth: Basic with `${authSid}:${authSecret}`. authSid can be either an
+ * Account SID (AC…) or an API Key SID (SK…); Twilio resolves both. The
+ * URL path always uses the Account SID — when using an API Key, pass
+ * `accountSid` separately.
+ */
+
+const TWILIO_BASE = "https://api.twilio.com/2010-04-01";
+
+export interface TwilioCreds {
+  /** Account SID (AC…) — required for the URL path. */
+  accountSid: string;
+  /** SID used for Basic-auth username. Can be the same Account SID or an API Key SID (SK…). */
+  authSid: string;
+  /** Basic-auth password (Account Auth Token, or API Key Secret if authSid is SK…). */
+  authSecret: string;
+}
+
+function basicAuth({ authSid, authSecret }: TwilioCreds): string {
+  return `Basic ${Buffer.from(`${authSid}:${authSecret}`).toString("base64")}`;
+}
+
+function accountUrl({ accountSid }: TwilioCreds, suffix: string): string {
+  return `${TWILIO_BASE}/Accounts/${encodeURIComponent(accountSid)}${suffix}`;
+}
+
+async function twilioPost<T = unknown>(creds: TwilioCreds, suffix: string, body: URLSearchParams): Promise<T> {
+  const resp = await fetch(accountUrl(creds, suffix), {
+    method: "POST",
+    headers: { Authorization: basicAuth(creds), "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`Twilio ${suffix} failed: ${resp.status} ${text}`);
+  }
+  return (await resp.json()) as T;
+}
+
+// --- Voice ---
+
+export interface PlaceCallOpts extends TwilioCreds {
+  to: string;
+  from: string;
+  twimlUrl: string;
+  statusCallbackUrl?: string;
+  maxDurationSec?: number;
+}
+
+export interface PlaceCallResult {
+  callSid: string;
+  status: string;
+}
+
+export async function placeCall(opts: PlaceCallOpts): Promise<PlaceCallResult> {
+  const body = new URLSearchParams({ To: opts.to, From: opts.from, Url: opts.twimlUrl, Method: "POST" });
+  if (opts.statusCallbackUrl) {
+    body.set("StatusCallback", opts.statusCallbackUrl);
+    body.set("StatusCallbackMethod", "POST");
+    body.append("StatusCallbackEvent", "initiated");
+    body.append("StatusCallbackEvent", "answered");
+    body.append("StatusCallbackEvent", "completed");
+  }
+  if (opts.maxDurationSec && opts.maxDurationSec > 0) {
+    body.set("TimeLimit", String(opts.maxDurationSec));
+  }
+  const data = await twilioPost<{ sid: string; status: string }>(opts, "/Calls.json", body);
+  return { callSid: data.sid, status: data.status };
+}
+
+export async function updateCallUrl(opts: TwilioCreds & { callSid: string; url: string }): Promise<void> {
+  const body = new URLSearchParams({ Url: opts.url, Method: "POST" });
+  await twilioPost(opts, `/Calls/${encodeURIComponent(opts.callSid)}.json`, body);
+}
+
+export async function hangupCall(opts: TwilioCreds & { callSid: string }): Promise<void> {
+  const body = new URLSearchParams({ Status: "completed" });
+  await twilioPost(opts, `/Calls/${encodeURIComponent(opts.callSid)}.json`, body);
+}
+
+// --- Messages (SMS / WhatsApp) ---
+
+export interface SendMessageOpts extends TwilioCreds {
+  /** E.164 for SMS, "whatsapp:+E164" for WhatsApp. */
+  to: string;
+  from: string;
+  body: string;
+  statusCallbackUrl?: string;
+  /** Optional MMS media URLs. */
+  mediaUrl?: string[];
+}
+
+export interface SendMessageResult {
+  messageSid: string;
+  status: string;
+}
+
+export async function sendMessage(opts: SendMessageOpts): Promise<SendMessageResult> {
+  const body = new URLSearchParams({ To: opts.to, From: opts.from, Body: opts.body });
+  if (opts.statusCallbackUrl) body.set("StatusCallback", opts.statusCallbackUrl);
+  if (opts.mediaUrl) {
+    for (const u of opts.mediaUrl) body.append("MediaUrl", u);
+  }
+  const data = await twilioPost<{ sid: string; status: string }>(opts, "/Messages.json", body);
+  return { messageSid: data.sid, status: data.status };
+}
+
+// --- Phone number config (update inbound webhook on a number) ---
+
+export async function updateIncomingPhoneNumber(
+  opts: TwilioCreds & {
+    phoneNumberSid: string;
+    voiceUrl?: string;
+    voiceMethod?: "GET" | "POST";
+    smsUrl?: string;
+    smsMethod?: "GET" | "POST";
+    statusCallback?: string;
+    statusCallbackMethod?: "GET" | "POST";
+  },
+): Promise<void> {
+  const body = new URLSearchParams();
+  if (opts.voiceUrl !== undefined) body.set("VoiceUrl", opts.voiceUrl);
+  if (opts.voiceMethod) body.set("VoiceMethod", opts.voiceMethod);
+  if (opts.smsUrl !== undefined) body.set("SmsUrl", opts.smsUrl);
+  if (opts.smsMethod) body.set("SmsMethod", opts.smsMethod);
+  if (opts.statusCallback !== undefined) body.set("StatusCallback", opts.statusCallback);
+  if (opts.statusCallbackMethod) body.set("StatusCallbackMethod", opts.statusCallbackMethod);
+  await twilioPost(opts, `/IncomingPhoneNumbers/${encodeURIComponent(opts.phoneNumberSid)}.json`, body);
+}

package/src/channels/twilio/server.ts

@@ -0,0 +1,255 @@
+/**
+ * Shared Bun HTTP + WebSocket server for all Twilio-based channels
+ * (voice, SMS, WhatsApp). Channels register routes during their start();
+ * the server lazily binds the port on first start() and stays bound until
+ * stop() is called. Idempotent in both directions.
+ *
+ * Cross-cutting features applied per route:
+ *   - X-Twilio-Signature HMAC-SHA1 validation (default on for /twilio/*).
+ *   - Dedup based on a configurable form field (e.g. MessageSid, CallSid).
+ *   - Per-key rate limit (e.g. From), to bound cost when a stranger
+ *     guesses the shared WhatsApp Sandbox join code.
+ *
+ * Channels keep their domain logic; the server keeps the wiring.
+ */
+import type { Server, ServerWebSocket } from "bun";
+import { log } from "../../utils/log";
+import { validateTwilioSignature } from "./signature";
+import { Dedup } from "./dedup";
+import { RateLimiter } from "./rate-limit";
+import { cacheMedia, readCachedMedia } from "./media-cache";
+
+export interface TwilioRequestContext {
+  /** Form-decoded body. */
+  params: Record<string, string>;
+}
+
+export type HttpHandler = (req: Request, ctx: TwilioRequestContext) => Promise<Response> | Response;
+
+export interface HttpRouteOpts {
+  /** Validate X-Twilio-Signature. Defaults to true. Set false for /healthz etc. */
+  verifySignature?: boolean;
+  /** If set, dedup based on this form field. Repeated values within the dedup window 204 silently. */
+  dedupOn?: string;
+  /** If set, rate-limit based on this form field. Over-limit 429s. */
+  rateLimitOn?: string;
+}
+
+export interface WsConnectionData {
+  path: string;
+  channel: Record<string, unknown>;
+}
+
+export interface WsRoute {
+  /** Called when a frame arrives. */
+  onMessage(ws: ServerWebSocket<WsConnectionData>, data: string): void;
+  /** Called when the connection closes. Optional. */
+  onClose?(ws: ServerWebSocket<WsConnectionData>): void;
+}
+
+export interface ServerConfig {
+  port: number;
+  /** Public base URL the server is reachable at (e.g. https://nia.example.com). No trailing slash. */
+  publicBaseUrl: string | null;
+  /** Account Auth Token used to verify X-Twilio-Signature. */
+  signingToken: string | null;
+}
+
+export interface TwilioServer {
+  configure(cfg: ServerConfig): void;
+  registerHttp(path: string, handler: HttpHandler, opts?: HttpRouteOpts): void;
+  registerWs(path: string, route: WsRoute): void;
+  /** Mark a key as exempt from rate-limiting (e.g. the owner's number). */
+  exemptFromRateLimit(key: string): void;
+  start(): Promise<void>;
+  stop(): void;
+  /** Build the WSS URL for a registered path, using publicBaseUrl. */
+  buildWssUrl(path: string): string;
+  /** Build the HTTPS URL for a registered path, using publicBaseUrl. */
+  buildHttpUrl(path: string): string;
+  /**
+   * Write a media payload to the on-disk outbound cache and return its
+   * publicly-reachable URL. Twilio fetches the URL when delivering MMS /
+   * WhatsApp media. Requires publicBaseUrl to be configured.
+   */
+  serveMedia(buffer: Uint8Array, mime: string, ext?: string): Promise<string>;
+}
+
+class TwilioServerImpl implements TwilioServer {
+  private cfg: ServerConfig | null = null;
+  private bunServer: Server<WsConnectionData> | null = null;
+  private readonly httpRoutes = new Map<string, { handler: HttpHandler; opts: HttpRouteOpts }>();
+  private readonly wsRoutes = new Map<string, WsRoute>();
+  private readonly dedup = new Dedup();
+  private readonly rateLimit = new RateLimiter();
+  private readonly rateLimitExempt = new Set<string>();
+
+  configure(cfg: ServerConfig): void {
+    this.cfg = cfg;
+  }
+
+  registerHttp(path: string, handler: HttpHandler, opts: HttpRouteOpts = {}): void {
+    if (this.httpRoutes.has(path)) {
+      log.warn({ path }, "twilio-server: overwriting existing HTTP route");
+    }
+    this.httpRoutes.set(path, { handler, opts });
+  }
+
+  registerWs(path: string, route: WsRoute): void {
+    if (this.wsRoutes.has(path)) {
+      log.warn({ path }, "twilio-server: overwriting existing WS route");
+    }
+    this.wsRoutes.set(path, route);
+  }
+
+  exemptFromRateLimit(key: string): void {
+    this.rateLimitExempt.add(key);
+    this.rateLimit.exempt(key);
+  }
+
+  async start(): Promise<void> {
+    if (this.bunServer) return;
+    if (!this.cfg) throw new Error("twilio-server: configure() must be called before start()");
+    const cfg = this.cfg;
+    const self = this;
+
+    this.bunServer = Bun.serve<WsConnectionData, never>({
+      port: cfg.port,
+      async fetch(req, server) {
+        const path = new URL(req.url).pathname;
+
+        if (path === "/healthz") return new Response("ok", { status: 200 });
+        if (path === "/twilio/health") return new Response("ok", { status: 200 });
+
+        if (req.method === "GET" && path.startsWith("/twilio/media/")) {
+          return await self.handleMedia(path.slice("/twilio/media/".length));
+        }
+
+        const wsRoute = self.wsRoutes.get(path);
+        if (wsRoute) {
+          const ok = server.upgrade(req, { data: { path, channel: {} } });
+          return ok ? undefined : new Response("expected websocket", { status: 400 });
+        }
+
+        const httpRoute = self.httpRoutes.get(path);
+        if (!httpRoute) return new Response("not found", { status: 404 });
+
+        return await self.handleHttp(req, httpRoute);
+      },
+      websocket: {
+        message(ws, message) {
+          const route = self.wsRoutes.get(ws.data.path);
+          if (!route) {
+            try {
+              ws.close();
+            } catch {}
+            return;
+          }
+          const data = typeof message === "string" ? message : new TextDecoder().decode(message);
+          route.onMessage(ws, data);
+        },
+        close(ws) {
+          const route = self.wsRoutes.get(ws.data.path);
+          route?.onClose?.(ws);
+        },
+      },
+    });
+
+    log.info({ port: cfg.port, publicBaseUrl: cfg.publicBaseUrl }, "twilio-server: started");
+  }
+
+  stop(): void {
+    if (!this.bunServer) return;
+    this.bunServer.stop(true);
+    this.bunServer = null;
+    log.info("twilio-server: stopped");
+  }
+
+  buildWssUrl(path: string): string {
+    if (!this.cfg?.publicBaseUrl) throw new Error("twilio-server: publicBaseUrl not configured");
+    return this.cfg.publicBaseUrl.replace(/^http/, "ws") + path;
+  }
+
+  buildHttpUrl(path: string): string {
+    if (!this.cfg?.publicBaseUrl) throw new Error("twilio-server: publicBaseUrl not configured");
+    return this.cfg.publicBaseUrl + path;
+  }
+
+  async serveMedia(buffer: Uint8Array, mime: string, ext?: string): Promise<string> {
+    if (!this.cfg?.publicBaseUrl) {
+      throw new Error("twilio-server: serveMedia requires channels.twilio.public_base_url to be configured");
+    }
+    const { filename } = await cacheMedia(buffer, mime, ext);
+    return `${this.cfg.publicBaseUrl}/twilio/media/${filename}`;
+  }
+
+  private async handleMedia(filename: string): Promise<Response> {
+    const hit = await readCachedMedia(filename);
+    if (!hit) return new Response("not found", { status: 404 });
+    return new Response(new Uint8Array(hit.buffer), {
+      status: 200,
+      headers: {
+        "Content-Type": hit.mime,
+        "Cache-Control": "private, max-age=300",
+      },
+    });
+  }
+
+  private async handleHttp(req: Request, route: { handler: HttpHandler; opts: HttpRouteOpts }): Promise<Response> {
+    if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+
+    const params = await this.readForm(req);
+
+    if (route.opts.verifySignature !== false) {
+      if (!this.verifySignature(req, params)) {
+        log.warn({ path: new URL(req.url).pathname }, "twilio-server: signature check failed");
+        return new Response("invalid signature", { status: 403 });
+      }
+    }
+
+    if (route.opts.rateLimitOn) {
+      const key = params[route.opts.rateLimitOn];
+      if (key && !this.rateLimitExempt.has(key) && !this.rateLimit.allow(key)) {
+        log.warn({ key, field: route.opts.rateLimitOn }, "twilio-server: rate limit exceeded");
+        return new Response("too many requests", { status: 429 });
+      }
+    }
+
+    if (route.opts.dedupOn) {
+      const id = params[route.opts.dedupOn];
+      if (id && this.dedup.check(id)) {
+        log.debug({ id, field: route.opts.dedupOn }, "twilio-server: duplicate webhook dropped");
+        return new Response("", { status: 204 });
+      }
+    }
+
+    return await route.handler(req, { params });
+  }
+
+  private async readForm(req: Request): Promise<Record<string, string>> {
+    const body = await req.text();
+    const params: Record<string, string> = {};
+    for (const [k, v] of new URLSearchParams(body)) params[k] = v;
+    return params;
+  }
+
+  private verifySignature(req: Request, params: Record<string, string>): boolean {
+    const token = this.cfg?.signingToken;
+    if (!token) return false;
+    const signature = req.headers.get("X-Twilio-Signature") || "";
+    const fullUrl = this.cfg?.publicBaseUrl ? `${this.cfg.publicBaseUrl}${new URL(req.url).pathname}` : req.url;
+    return validateTwilioSignature({ authToken: token, fullUrl, params, signature });
+  }
+}
+
+let _instance: TwilioServer | null = null;
+
+export function getTwilioServer(): TwilioServer {
+  if (!_instance) _instance = new TwilioServerImpl();
+  return _instance;
+}
+
+/** Test-only: drop the singleton so tests get a fresh server. */
+export function resetTwilioServer(): void {
+  _instance = null;
+}

package/src/channels/twilio/signature.ts

@@ -0,0 +1,36 @@
+/**
+ * Validate Twilio's X-Twilio-Signature header.
+ *
+ * Algorithm (per Twilio webhook security docs):
+ *   1. Take the full URL Twilio sent the request to (including ?query).
+ *   2. For application/x-www-form-urlencoded bodies, sort POST keys and
+ *      append each "key" + "value" to the URL string.
+ *   3. HMAC-SHA1 with the account AuthToken, base64-encode.
+ *   4. Timing-safe compare with the X-Twilio-Signature header.
+ *
+ * Signed with the account-level Auth Token, NOT the API Key Secret.
+ * When an API Key is used for REST auth, set TWILIO_AUTH_TOKEN separately.
+ */
+import { createHmac, timingSafeEqual } from "crypto";
+
+export function validateTwilioSignature(opts: {
+  authToken: string;
+  fullUrl: string;
+  params: Record<string, string>;
+  signature: string;
+}): boolean {
+  const { authToken, fullUrl, params, signature } = opts;
+  if (!signature) return false;
+
+  const sortedKeys = Object.keys(params).sort();
+  let data = fullUrl;
+  for (const key of sortedKeys) {
+    data += key + params[key];
+  }
+
+  const computed = createHmac("sha1", authToken).update(data, "utf8").digest("base64");
+  const a = Buffer.from(computed);
+  const b = Buffer.from(signature);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}