experimental-ash 0.13.0 → 0.14.0

package/dist/src/public/channels/twilio/verify.js

@@ -0,0 +1,73 @@
+/**
+ * Twilio inbound-webhook verification.
+ *
+ * Twilio signs webhook requests with `X-Twilio-Signature`. For form
+ * posts, the signed payload is the exact public URL Twilio called plus
+ * every POST parameter sorted by name and appended as `name + value`.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createLogger } from "#internal/logging.js";
+const log = createLogger("twilio.verify");
+/** Resolves a Twilio auth token, falling back to `TWILIO_AUTH_TOKEN`. */
+export async function resolveTwilioAuthToken(authToken) {
+    const source = authToken ?? process.env.TWILIO_AUTH_TOKEN;
+    if (!source)
+        throw new Error("TWILIO_AUTH_TOKEN is required.");
+    return typeof source === "function" ? await source() : source;
+}
+/**
+ * Verifies an inbound Twilio webhook and returns the raw body plus form params.
+ *
+ * Throws when the auth token is missing, the signature header is missing,
+ * or the computed signature does not match `X-Twilio-Signature`.
+ */
+export async function verifyTwilioRequest(request, options) {
+    const body = await request.text();
+    const params = new URLSearchParams(body);
+    const authToken = await resolveTwilioAuthToken(options.authToken);
+    const signature = request.headers.get("x-twilio-signature") ?? "";
+    if (!signature) {
+        throw new Error("twilioChannel: inbound request missing X-Twilio-Signature.");
+    }
+    const url = await resolveWebhookUrl(request, options.webhookUrl);
+    const expected = signTwilioRequest({ authToken, params, url });
+    if (!constantTimeCompare(expected, signature)) {
+        throw new Error("twilioChannel: inbound request signature mismatch.");
+    }
+    return { body, params };
+}
+/** Computes Twilio's HMAC-SHA1 request signature. */
+export function signTwilioRequest(input) {
+    const base = buildTwilioSignatureBase(input.url, input.params);
+    return createHmac("sha1", input.authToken).update(base).digest("base64");
+}
+/** Builds the string Twilio signs for a form POST webhook. */
+export function buildTwilioSignatureBase(url, params) {
+    const entries = Array.from(params.entries()).sort(([aName, aValue], [bName, bValue]) => {
+        const nameOrder = aName < bName ? -1 : aName > bName ? 1 : 0;
+        if (nameOrder !== 0)
+            return nameOrder;
+        return aValue < bValue ? -1 : aValue > bValue ? 1 : 0;
+    });
+    let base = url;
+    for (const [name, value] of entries) {
+        base += `${name}${value}`;
+    }
+    return base;
+}
+async function resolveWebhookUrl(request, webhookUrl) {
+    if (typeof webhookUrl === "function")
+        return webhookUrl(request);
+    return webhookUrl ?? request.url;
+}
+function constantTimeCompare(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    }
+    catch (error) {
+        log.debug("timingSafeEqual threw", { error });
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -136,6 +136,11 @@
       "import": "./dist/src/public/channels/slack/index.js",
       "default": "./dist/src/public/channels/slack/index.js"
     },
+    "./channels/twilio": {
+      "types": "./dist/src/public/channels/twilio/index.d.ts",
+      "import": "./dist/src/public/channels/twilio/index.js",
+      "default": "./dist/src/public/channels/twilio/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {