@mulmobridge/webhook-runtime 0.1.0 → 1.0.1

package/dist/index.d.ts

@@ -7,3 +7,22 @@ export declare function createWebhookApp(opts?: {
 }): Express;
 export declare function createWebhookRateLimit(limitPerMinute?: number): RateLimitRequestHandler;
 export declare function verifyHmacSignature(body: string, signature: string, secret: string, algorithm?: string, encoding?: crypto.BinaryToTextEncoding): boolean;
+export declare const SAFE_CHALLENGE_RE: RegExp;
+/** The challenge string when `raw` matches the shape we'll echo, else
+ *  `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

@@ -83,3 +83,49 @@ export function verifyHmacSignature(body, signature, secret, algorithm = "SHA256
         return false;
     return crypto.timingSafeEqual(expected, provided);
 }
+// ── Meta (Messenger / WhatsApp) webhook verification ───────────
+//
+// Meta's GET handshake echoes back `hub.challenge`. Narrowing it to a
+// known shape before it reaches `res.send()` is the CodeQL sanitiser that
+// clears the `js/reflected-xss` alert (Codex review on #1328) and gives
+// defence-in-depth. `[A-Za-z0-9_-]{1,256}` covers every observed base64url
+// nonce (~32 chars); widen it HERE if Meta ever extends the format.
+export const SAFE_CHALLENGE_RE = /^[A-Za-z0-9_-]{1,256}$/;
+/** The challenge string when `raw` matches the shape we'll echo, else
+ *  `null`. Non-string query forms (`?hub.challenge[]=…`) return `null`
+ *  rather than coercing to "", so callers can't compare a coerced empty. */
+export function narrowChallenge(raw) {
+    if (typeof raw !== "string")
+        return null;
+    if (!SAFE_CHALLENGE_RE.test(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": "0.1.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",