@mulmobridge/webhook-runtime 1.0.3 → 1.1.0

package/README.md

@@ -13,6 +13,22 @@ Messenger, Google Chat).
 - `verifyHmacSignature(body, signature, secret, algorithm?, encoding?)` —
   length-guarded, timing-safe HMAC comparison.
 
+For the Meta platforms (Messenger, WhatsApp), which share one webhook contract:
+
+- `registerMetaWebhook(app, { verifyToken, appSecret, label, ackBody?, onBody })` —
+  the whole `/webhook` surface in one call:
+  - **GET** — the handshake that echoes `hub.challenge` only after the token matches.
+  - **POST** — `x-hub-signature-256` check → `401` on failure, otherwise ack `200`
+    **before** awaiting `onBody(rawBody)` so a slow handler can't trigger a Meta
+    redelivery.
+
+  Both routes share one rate-limit bucket, built inside the registrar (a flood of
+  bogus `hub.challenge` GETs hammers the bridge just as effectively as POSTs).
+- `registerMetaWebhookVerification(app, { rateLimit, verifyToken, label })` — the
+  GET half on its own, for a caller that owns the limiter.
+- `verifyMetaHmacSignature(body, signature, appSecret)` — the hex/SHA-256 HMAC
+  check with Meta's `sha256=` prefix stripped.
+
 These are security-relevant and hardened through Codex reviews (#1326);
 keeping one copy means a fix lands once, not once per bridge.
 

package/dist/index.d.ts

@@ -26,3 +26,16 @@ export interface MetaWebhookVerificationOptions {
 }
 export declare function registerMetaWebhookVerification(app: Express, opts: MetaWebhookVerificationOptions): void;
 export declare function verifyMetaHmacSignature(rawBody: string, signature: string, appSecret: string): boolean;
+export interface MetaWebhookOptions {
+    verifyToken: string;
+    appSecret: string;
+    /** Log prefix, e.g. "messenger" / "whatsapp". */
+    label: string;
+    /** Body of the 200 ack. Meta ignores it, but each bridge shipped its own
+     *  string, so it stays configurable rather than silently changing. */
+    ackBody?: string;
+    /** Runs after the ack, on a signature-verified body. Must not throw — a
+     *  rejection here lands in an already-answered request. */
+    onBody: (rawBody: string) => Promise<void>;
+}
+export declare function registerMetaWebhook(app: Express, opts: MetaWebhookOptions): void;

package/dist/index.js

@@ -129,3 +129,31 @@ export function registerMetaWebhookVerification(app, opts) {
 export function verifyMetaHmacSignature(rawBody, signature, appSecret) {
     return verifyHmacSignature(rawBody, signature.replace("sha256=", ""), appSecret, "sha256", "hex");
 }
+// Register both halves of a Meta webhook (Messenger, WhatsApp): the GET
+// verification handshake and the POST event delivery. The POST body arrives as
+// raw text (see createWebhookApp) so the HMAC covers exactly the bytes Meta
+// signed.
+//
+// One limiter covers both routes — a flood of bogus `hub.challenge` GET probes
+// hammers the bridge just as effectively as POST traffic, so they share a
+// bucket rather than getting one cap each. It is built HERE rather than taken
+// as an argument because `js/missing-rate-limiting` only recognises the
+// `express-rate-limit` call when it is visible at route setup; behind a
+// parameter CodeQL cannot tell the signature check is throttled.
+export function registerMetaWebhook(app, opts) {
+    const webhookRateLimit = createWebhookRateLimit();
+    registerMetaWebhookVerification(app, { rateLimit: webhookRateLimit, verifyToken: opts.verifyToken, label: opts.label });
+    app.post("/webhook", webhookRateLimit, async (req, res) => {
+        const signature = typeof req.headers["x-hub-signature-256"] === "string" ? req.headers["x-hub-signature-256"] : "";
+        const rawBody = typeof req.body === "string" ? req.body : "";
+        if (!signature || !verifyMetaHmacSignature(rawBody, signature, opts.appSecret)) {
+            console.warn(`[${opts.label}] AUTH_FAILED: signature verification failed`);
+            res.status(401).send("Invalid signature");
+            return;
+        }
+        // Ack before processing: Meta re-delivers anything it doesn't see
+        // acknowledged within seconds, so the reply must not wait on the agent.
+        res.status(200).send(opts.ackBody ?? "EVENT_RECEIVED");
+        await opts.onBody(rawBody);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/webhook-runtime",
-  "version": "1.0.3",
+  "version": "1.1.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",
@@ -32,7 +32,7 @@
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.5",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/webhook-runtime#readme",