@crewhaus/channel-adapter-whatsapp 0.3.2 → 0.4.2

package/dist/index.d.ts

@@ -7,6 +7,11 @@
  * `messages[].id` (Meta's per-message identifier) as the gateway
  * dedup key so retries don't double-process.
  *
+ * `handshake` answers Meta's unsigned GET callback-URL verification
+ * (`hub.mode=subscribe`) by echoing `hub.challenge` once the presented
+ * `hub.verify_token` matches the configured one — without it Meta never
+ * activates the subscription and no webhook is ever delivered.
+ *
  * `parseInbound` handles text + image + audio + button-reply +
  * list-reply payloads from the v22.0 Cloud API. `sendReply` POSTs to
  * `/v22.0/{phoneNumberId}/messages` with the bot's access token.
@@ -18,7 +23,7 @@
  * keys sessions on the contact's phone number (`messages[].from`).
  */
 import { CrewhausError } from "@crewhaus/errors";
-export { signWhatsAppBody, verifyWhatsAppSignature } from "./verify.js";
+export { signWhatsAppBody, verifyWhatsAppSignature, verifyWhatsAppVerifyToken, } from "./verify.js";
 export declare class WhatsAppAdapterError extends CrewhausError {
     readonly name = "WhatsAppAdapterError";
     constructor(message: string, cause?: unknown);
@@ -38,12 +43,14 @@ export type InboundEvent = {
     readonly subtype: "app_mention" | "message";
 };
 /**
- * Three result shapes:
+ * Two result shapes — `parseInbound` only ever sees a signed POST body:
  *   - `{kind:"event", event}` — a real inbound message to route
- *   - `{kind:"verification", challenge}` — Meta's GET-based verification
- *     handshake (the gateway echoes back `hub.challenge`)
  *   - `{kind:"skip"}` — known-but-uninteresting payload (status update,
  *     non-text non-interactive media, etc.)
+ *
+ * Meta's callback-URL verification is NOT a webhook body — it is an unsigned
+ * `GET ?hub.mode=subscribe&hub.verify_token=…&hub.challenge=…`, handled by
+ * `handshake` below, not here.
  */
 export type ParsedInbound = {
     readonly kind: "event";
@@ -51,10 +58,27 @@ export type ParsedInbound = {
 } | {
     readonly kind: "skip";
 };
+/**
+ * Meta's unsigned GET subscription handshake (see `handshake` below).
+ * Structurally identical to the channel-generic type the emitted gateway
+ * uses — the adapter packages deliberately re-declare the shared shapes
+ * rather than depend on one another.
+ */
+export type HandshakeRequest = {
+    readonly headers: Headers;
+    readonly url: URL;
+};
+export type HandshakeResult = {
+    readonly kind: "challenge";
+    readonly challenge: string;
+} | {
+    readonly kind: "reject";
+};
 export interface ChannelAdapter {
     readonly id: string;
     verify(req: RawRequest): boolean;
     parseInbound(req: RawRequest): ParsedInbound;
+    handshake(req: HandshakeRequest): HandshakeResult;
     sendReply(args: {
         event: InboundEvent;
         text: string;
@@ -80,6 +104,14 @@ export type WhatsAppAdapterConfig = {
     readonly accessToken: string;
     /** Meta app secret, used to verify X-Hub-Signature-256. */
     readonly appSecret: string;
+    /**
+     * The verify token configured on the Meta app's webhook callback. Required
+     * to complete the GET subscription handshake — Meta will not deliver any
+     * webhook to a callback URL that has never passed it. Absent ⇒ `handshake`
+     * rejects every attempt (fail closed), and the daemon can still receive
+     * webhooks on a subscription verified elsewhere.
+     */
+    readonly verifyToken?: string;
 };
 export type WhatsAppAdapterOptions = {
     readonly apiBaseUrl?: string;

package/dist/index.js

@@ -7,6 +7,11 @@
  * `messages[].id` (Meta's per-message identifier) as the gateway
  * dedup key so retries don't double-process.
  *
+ * `handshake` answers Meta's unsigned GET callback-URL verification
+ * (`hub.mode=subscribe`) by echoing `hub.challenge` once the presented
+ * `hub.verify_token` matches the configured one — without it Meta never
+ * activates the subscription and no webhook is ever delivered.
+ *
  * `parseInbound` handles text + image + audio + button-reply +
  * list-reply payloads from the v22.0 Cloud API. `sendReply` POSTs to
  * `/v22.0/{phoneNumberId}/messages` with the bot's access token.
@@ -18,8 +23,8 @@
  * keys sessions on the contact's phone number (`messages[].from`).
  */
 import { CrewhausError } from "@crewhaus/errors";
-import { verifyWhatsAppSignature } from "./verify.js";
-export { signWhatsAppBody, verifyWhatsAppSignature } from "./verify.js";
+import { verifyWhatsAppSignature, verifyWhatsAppVerifyToken } from "./verify.js";
+export { signWhatsAppBody, verifyWhatsAppSignature, verifyWhatsAppVerifyToken, } from "./verify.js";
 export class WhatsAppAdapterError extends CrewhausError {
     name = "WhatsAppAdapterError";
     constructor(message, cause) {
@@ -50,6 +55,30 @@ export function createWhatsAppAdapter(config, opts = {}) {
                 appSecret: config.appSecret,
             }, opts.now !== undefined ? { now: opts.now } : {});
         },
+        /**
+         * Meta's callback-URL verification handshake:
+         *   `GET /whatsapp/events?hub.mode=subscribe
+         *        &hub.verify_token=<shared secret>&hub.challenge=<nonce>`
+         * On a token match the caller must echo `hub.challenge` verbatim with 200;
+         * anything else marks the callback URL unverified and Meta delivers no
+         * webhooks at all. The request is unsigned (no body, no
+         * X-Hub-Signature-256), so the verify token IS the authentication — which
+         * is why a mismatch, a missing parameter, or an unconfigured
+         * `verifyToken` all fail closed.
+         */
+        handshake(req) {
+            const params = req.url.searchParams;
+            if (params.get("hub.mode") !== "subscribe")
+                return { kind: "reject" };
+            const challenge = params.get("hub.challenge");
+            const supplied = params.get("hub.verify_token");
+            if (challenge === null || supplied === null)
+                return { kind: "reject" };
+            if (!verifyWhatsAppVerifyToken({ expected: config.verifyToken ?? "", supplied })) {
+                return { kind: "reject" };
+            }
+            return { kind: "challenge", challenge };
+        },
         parseInbound(req) {
             let payload;
             try {

package/dist/verify.d.ts

@@ -17,6 +17,19 @@ export type WhatsAppVerifyOptions = {
     readonly toleranceMs?: number;
 };
 export declare function verifyWhatsAppSignature(args: WhatsAppVerifyArgs, opts?: WhatsAppVerifyOptions): boolean;
+/**
+ * Constant-time comparison of the `hub.verify_token` Meta presents during the
+ * GET subscription handshake against the token this daemon was configured
+ * with. Both are shared secrets, so the comparison must not leak length or
+ * prefix through timing.
+ *
+ * An empty `expected` (no `verifyToken` configured) NEVER matches: a daemon
+ * that was not told the token must not be verifiable by an arbitrary Meta app.
+ */
+export declare function verifyWhatsAppVerifyToken(args: {
+    readonly expected: string;
+    readonly supplied: string;
+}): boolean;
 /**
  * Sign a body — used by smoke tests and the in-repo integration test to
  * construct fixtures the daemon will accept. Production code should NEVER

package/dist/verify.js

@@ -76,6 +76,27 @@ export function verifyWhatsAppSignature(args, opts = {}) {
         return false;
     return true;
 }
+/**
+ * Constant-time comparison of the `hub.verify_token` Meta presents during the
+ * GET subscription handshake against the token this daemon was configured
+ * with. Both are shared secrets, so the comparison must not leak length or
+ * prefix through timing.
+ *
+ * An empty `expected` (no `verifyToken` configured) NEVER matches: a daemon
+ * that was not told the token must not be verifiable by an arbitrary Meta app.
+ */
+export function verifyWhatsAppVerifyToken(args) {
+    if (args.expected.length === 0)
+        return false;
+    const expectedBuf = Buffer.from(args.expected, "utf8");
+    const suppliedBuf = Buffer.from(args.supplied, "utf8");
+    // timingSafeEqual throws on length mismatch, so compare a fixed-length
+    // digest of each instead of the raw bytes — that keeps the comparison
+    // constant-time without leaking the configured token's length.
+    const expectedMac = createHmac("sha256", expectedBuf).update(expectedBuf).digest();
+    const suppliedMac = createHmac("sha256", expectedBuf).update(suppliedBuf).digest();
+    return timingSafeEqual(expectedMac, suppliedMac);
+}
 /**
  * Sign a body — used by smoke tests and the in-repo integration test to
  * construct fixtures the daemon will accept. Production code should NEVER

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/channel-adapter-whatsapp",
-  "version": "0.3.2",
+  "version": "0.4.2",
   "type": "module",
   "description": "WhatsApp Business Cloud API channel adapter: X-Hub-Signature-256 verification + text/media/interactive parsing + idempotent retry handling (Section 33)",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.3.2"
+    "@crewhaus/errors": "0.4.2"
   },
   "license": "Apache-2.0",
   "author": {