@mulmobridge/webhook-runtime 1.0.0 → 1.0.2

package/README.md

@@ -15,3 +15,11 @@ Messenger, Google Chat).
 
 These are security-relevant and hardened through Codex reviews (#1326);
 keeping one copy means a fix lands once, not once per bridge.
+
+## Related projects
+
+Published from the MulmoClaude monorepo by [Receptron](https://github.com/receptron).
+
+- **[MulmoClaude](https://github.com/receptron/mulmoclaude)** — an open-source AI assistant platform that runs on your own computer. Claude Code as the engine, a personal wiki for long-term memory, schema-driven collections for your data, and chat that summons the right GUI (markdown, charts, forms, spreadsheets, wikis) for each task.
+- **[MulmoTerminal](https://github.com/receptron/mulmoterminal)** — a terminal-first cockpit for running many AI coding agents in parallel. One roster showing every session's summary and PR status, tmux-backed session persistence, git-worktree isolation, one-click PRs, and mobile push with remote reply.
+- **[MulmoTerminal manual](https://receptron.github.io/mulmoterminal/)** — setup, workflows, feature reference, configuration, mobile notifications, and alternative / local model providers. Available in English and Japanese.

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.2",
   "description": "Shared HTTP-webhook plumbing (Express app, trust-proxy, rate limit, HMAC verify) for the MulmoClaude messaging bridges",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,5 +34,21 @@
     "@types/express": "^5.0.0",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/webhook-runtime#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/receptron/mulmoclaude.git",
+    "directory": "packages/webhook-runtime"
+  },
+  "keywords": [
+    "mulmobridge",
+    "webhook",
+    "express",
+    "hmac",
+    "rate-limit"
+  ],
+  "bugs": {
+    "url": "https://github.com/receptron/mulmoclaude/issues"
   }
 }