@mulmobridge/webhook-runtime 1.0.3 → 1.2.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

@@ -1,4 +1,5 @@
 import crypto from "crypto";
+import type { Server } from "node:http";
 import { type Express } from "express";
 import { type RateLimitRequestHandler } from "express-rate-limit";
 export declare function configureTrustProxy(app: Express, env?: string | undefined): void;
@@ -26,3 +27,27 @@ 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;
+export interface ListenWebhookOptions {
+    /** The env var that overrides the port. Every message names it — each bridge
+     *  has a different one, and "which knob do I turn" is the question an
+     *  operator has at exactly the moment this fails. */
+    envVar: string;
+    /** Port used when the env var is unset or blank. */
+    fallback: number;
+    /** Test seam. Production prints the message and exits non-zero. */
+    onFatal?: (message: string) => void;
+}
+export declare function listenWebhook(app: Express, opts: ListenWebhookOptions, onReady: (port: number) => void): Server | undefined;

package/dist/index.js

@@ -10,6 +10,8 @@
 import crypto from "crypto";
 import express from "express";
 import rateLimit, { ipKeyGenerator } from "express-rate-limit";
+import { hasNumberProp } from "@mulmoclaude/common";
+import { describeListenError, resolveWebhookPort } from "./port.js";
 // Honour an explicit `trust proxy` setting so `req.ip` (the rate-limit
 // key) reflects the real client IP rather than the load balancer's.
 // Default `false` for safety; operators behind a known LB choose from:
@@ -129,3 +131,66 @@ 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);
+    });
+}
+// Bind a bridge's webhook port, and say something useful when that fails.
+//
+// Before #3084 each bridge did `Number(process.env.X) || N` and a bare
+// `app.listen(PORT, cb)`: a typo ran on the default without a word, `X=0` was
+// impossible, and `EADDRINUSE` surfaced as an unhandled error with no mention
+// of which env var to change. The server's port band (3002-3021) overlaps the
+// bridge band (3002-3013), so that collision is routine, not theoretical
+// (#3079).
+export function listenWebhook(app, opts, onReady) {
+    const fatal = opts.onFatal ?? exitWithMessage;
+    const resolved = resolveWebhookPort(process.env[opts.envVar], opts.fallback, opts.envVar);
+    if (!resolved.ok) {
+        fatal(resolved.message);
+        return undefined;
+    }
+    const server = app.listen(resolved.port, () => {
+        // `server.address()` is the authority on whether the bind happened, and on
+        // which port it got (it differs from the requested one for `=0`). Express 5
+        // runs this callback even when the bind FAILED — verified against
+        // express@5.1: `address()` is null, `listening` is false, and the 'error'
+        // event arrives on the next tick. Without this guard a bridge prints its
+        // "listening on <port>" banner for a server that never bound, which is the
+        // same silence #3084 is about, one step later.
+        const address = server.address();
+        if (!hasNumberProp(address, "port"))
+            return;
+        onReady(address.port);
+    });
+    server.on("error", (err) => fatal(describeListenError(err, resolved.port, opts.envVar)));
+    return server;
+}
+function exitWithMessage(message) {
+    console.error(message);
+    process.exit(1);
+}

package/dist/port.d.ts

@@ -0,0 +1,14 @@
+export type PortResolution = {
+    readonly ok: true;
+    readonly port: number;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Resolve a bridge's listen port from its env var, or say why it cannot be used.
+ *  `raw` is passed in rather than read here so this stays pure. */
+export declare function resolveWebhookPort(raw: string | undefined, fallback: number, envVar: string): PortResolution;
+/** What to tell the operator when `listen` fails. Names the env var, because
+ *  every bridge uses a different one and "which knob do I turn" is the whole
+ *  question at that moment. */
+export declare function describeListenError(err: unknown, port: number, envVar: string): string;

package/dist/port.js

@@ -0,0 +1,40 @@
+// Port resolution and bind diagnostics for the webhook bridges (#3084).
+//
+// Pure on purpose — no `process`, no sockets — so both decisions can be tested
+// directly: WHICH port a bridge binds, and WHAT a human is told when the bind
+// fails. `listenWebhook` in `index.ts` is the only part that touches the world.
+import { asInt, errorMessage, isErrorWithCode, PORT_RANGE } from "@mulmoclaude/common";
+// A fallback that `asInt` can never produce from a real value, since
+// `PORT_RANGE.min` is 0. Comparing against it turns `asInt`'s "fell back"
+// into "the operator typed something unusable", without changing `asInt`'s
+// contract (it returns the fallback for bad input by design).
+const UNUSABLE = -1;
+/** Resolve a bridge's listen port from its env var, or say why it cannot be used.
+ *  `raw` is passed in rather than read here so this stays pure. */
+export function resolveWebhookPort(raw, fallback, envVar) {
+    // A blank value means "not configured", which is what `Number(x) || N` did
+    // for the nine bridges before this — `asInt` alone would read it as 0 and
+    // ask the OS for an ephemeral port.
+    if (raw === undefined || raw.trim() === "")
+        return { ok: true, port: fallback };
+    const port = asInt(raw, UNUSABLE, PORT_RANGE);
+    if (port === UNUSABLE) {
+        return {
+            ok: false,
+            message: `${envVar}="${raw}" is not a usable port. Set it to an integer from ${PORT_RANGE.min} to ${PORT_RANGE.max} (${envVar}=0 asks the OS for a free port), or unset it to use ${fallback}.`,
+        };
+    }
+    return { ok: true, port };
+}
+/** What to tell the operator when `listen` fails. Names the env var, because
+ *  every bridge uses a different one and "which knob do I turn" is the whole
+ *  question at that moment. */
+export function describeListenError(err, port, envVar) {
+    if (isErrorWithCode(err) && err.code === "EADDRINUSE") {
+        return `Port ${port} is already in use. Set ${envVar} to a free port, or ${envVar}=0 to let the OS pick one.`;
+    }
+    if (isErrorWithCode(err) && err.code === "EACCES") {
+        return `Port ${port} needs elevated privileges. Set ${envVar} to a port above 1023.`;
+    }
+    return `Failed to listen on port ${port} (set ${envVar} to change it): ${errorMessage(err)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/webhook-runtime",
-  "version": "1.0.3",
+  "version": "1.2.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",
@@ -27,12 +27,14 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
+    "@mulmoclaude/common": "^1.3.0",
     "express": "^5.1.0",
-    "express-rate-limit": "^8.6.1"
+    "express-rate-limit": "^8.7.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "tsx": "^4.23.1",
+    "@types/node": "^26.4.1",
+    "tsx": "^4.23.13",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/webhook-runtime#readme",