@mulmobridge/webhook-runtime 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -12,3 +12,17 @@ export declare const SAFE_CHALLENGE_RE: RegExp;
  *  `null`. Non-string query forms (`?hub.challenge[]=…`) return `null`
  *  rather than coercing to "", so callers can't compare a coerced empty. */
 export declare function narrowChallenge(raw: unknown): string | null;
+export interface MetaVerificationResult {
+    status: 200 | 403;
+    body: string;
+    verified: boolean;
+}
+export declare function metaVerificationResult(query: Record<string, unknown>, verifyToken: string): MetaVerificationResult;
+export interface MetaWebhookVerificationOptions {
+    rateLimit: RateLimitRequestHandler;
+    verifyToken: string;
+    /** Log prefix, e.g. "messenger" / "whatsapp". */
+    label: string;
+}
+export declare function registerMetaWebhookVerification(app: Express, opts: MetaWebhookVerificationOptions): void;
+export declare function verifyMetaHmacSignature(rawBody: string, signature: string, appSecret: string): boolean;

package/dist/index.js

@@ -101,3 +101,31 @@ export function narrowChallenge(raw) {
         return null;
     return raw;
 }
+// Pure decision for Meta's GET handshake: echo `hub.challenge` only when
+// `hub.mode=subscribe`, `hub.verify_token` matches, and the challenge clears
+// `narrowChallenge`. Split out from the Express handler so it can be tested
+// without a request object. Messenger and WhatsApp share this byte-for-byte.
+export function metaVerificationResult(query, verifyToken) {
+    const challenge = narrowChallenge(query["hub.challenge"]);
+    if (query["hub.mode"] === "subscribe" && query["hub.verify_token"] === verifyToken && challenge !== null) {
+        return { status: 200, body: challenge, verified: true };
+    }
+    return { status: 403, body: "Forbidden", verified: false };
+}
+// Register the shared Meta webhook-verification GET handler (Messenger,
+// WhatsApp). Always `text/plain` — the CodeQL `js/reflected-xss` defence for
+// the echoed challenge (see narrowChallenge + SAFE_CHALLENGE_RE above).
+export function registerMetaWebhookVerification(app, opts) {
+    app.get("/webhook", opts.rateLimit, (req, res) => {
+        const result = metaVerificationResult(req.query, opts.verifyToken);
+        if (result.verified)
+            console.log(`[${opts.label}] webhook verified`);
+        res.status(result.status).type("text/plain").send(result.body);
+    });
+}
+// Meta prefixes the x-hub-signature-256 hex digest with `sha256=`; strip it
+// before the timing-safe compare. Wraps the generic hex/SHA-256 HMAC check so
+// the Messenger and WhatsApp bridges stop carrying identical copies.
+export function verifyMetaHmacSignature(rawBody, signature, appSecret) {
+    return verifyHmacSignature(rawBody, signature.replace("sha256=", ""), appSecret, "sha256", "hex");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/webhook-runtime",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Shared HTTP-webhook plumbing (Express app, trust-proxy, rate limit, HMAC verify) for the MulmoClaude messaging bridges",
   "type": "module",
   "main": "./dist/index.js",