@mulmobridge/webhook-runtime 0.1.0 → 1.0.0

package/dist/index.d.ts

@@ -7,3 +7,8 @@ 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;

package/dist/index.js

@@ -83,3 +83,21 @@ 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;
+}

package/package.json

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