@crewhaus/channel-adapter-whatsapp 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/channel-adapter-whatsapp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "WhatsApp Business Cloud API channel adapter: X-Hub-Signature-256 verification + text/media/interactive parsing + idempotent retry handling (Section 33)",
   "main": "src/index.ts",
@@ -12,13 +12,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.1"
+    "@crewhaus/errors": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -30,12 +30,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -22,6 +22,11 @@ const APP_SECRET = "wa-app-secret";
 const PHONE_NUMBER_ID = "999000999000";
 const ACCESS_TOKEN = "EAAxxxxxxxxx";
 
+// The static fixtures carry a fixed (old) messages[].timestamp; pin the
+// replay-window clock near it so the signature tests exercise auth, not age.
+const FIXTURE_TS = 1700000123;
+const FIXTURE_NOW = () => FIXTURE_TS * 1000;
+
 function signedHeaders(body: string): Headers {
   const sig = signWhatsAppBody({ body, appSecret: APP_SECRET });
   const h = new Headers();
@@ -34,6 +39,7 @@ function adapter(overrides: { fetch?: typeof fetch } = {}): ChannelAdapter {
     { phoneNumberId: PHONE_NUMBER_ID, accessToken: ACCESS_TOKEN, appSecret: APP_SECRET },
     {
       apiBaseUrl: "https://test.graph.local",
+      now: FIXTURE_NOW,
       ...(overrides.fetch ? { fetch: overrides.fetch } : {}),
     },
   );
@@ -42,14 +48,43 @@ function adapter(overrides: { fetch?: typeof fetch } = {}): ChannelAdapter {
 describe("verifyWhatsAppSignature (T8)", () => {
   test("matches a valid signature", () => {
     const body = fixture("text_message");
-    const r = verifyWhatsAppSignature({
-      headers: signedHeaders(body),
-      body,
-      appSecret: APP_SECRET,
-    });
+    const r = verifyWhatsAppSignature(
+      {
+        headers: signedHeaders(body),
+        body,
+        appSecret: APP_SECRET,
+      },
+      { now: FIXTURE_NOW },
+    );
     expect(r).toBe(true);
   });
 
+  // SECURITY: WhatsApp signs only the body (no signed timestamp), so a captured
+  // signed POST verified forever. Bound it with messages[].timestamp.
+  test("rejects a stale captured message under the real clock (replay window)", () => {
+    const body = fixture("text_message"); // fixture ts is years old vs Date.now()
+    expect(
+      verifyWhatsAppSignature({ headers: signedHeaders(body), body, appSecret: APP_SECRET }),
+    ).toBe(false);
+  });
+
+  test("rejects a message whose timestamp is in the future beyond tolerance", () => {
+    const body = fixture("text_message");
+    expect(
+      verifyWhatsAppSignature(
+        { headers: signedHeaders(body), body, appSecret: APP_SECRET },
+        { now: () => (FIXTURE_TS - 3600) * 1000 },
+      ),
+    ).toBe(false);
+  });
+
+  test("accepts a status-only webhook with no message timestamp (no freshness gate)", () => {
+    const body = fixture("status_only");
+    expect(
+      verifyWhatsAppSignature({ headers: signedHeaders(body), body, appSecret: APP_SECRET }),
+    ).toBe(true);
+  });
+
   test("rejects tampered body", () => {
     const body = fixture("text_message");
     const headers = signedHeaders(body);
@@ -273,4 +308,313 @@ describe("WhatsAppAdapterError", () => {
     expect(e.code).toBe("channel");
     expect(e.name).toBe("WhatsAppAdapterError");
   });
+
+  test("preserves the cause chain via toJSON()", () => {
+    const root = new Error("socket hang up");
+    const e = new WhatsAppAdapterError("send failed", root);
+    expect(e.cause).toBe(root);
+    expect(e.toJSON()).toEqual({
+      name: "WhatsAppAdapterError",
+      code: "channel",
+      message: "send failed",
+      cause: { name: "Error", message: "socket hang up" },
+    });
+  });
+});
+
+describe("signWhatsAppBody (T8)", () => {
+  test('produces a "sha256=<64-hex>" header that verify accepts', () => {
+    const body = fixture("text_message");
+    const sig = signWhatsAppBody({ body, appSecret: APP_SECRET });
+    expect(sig).toMatch(/^sha256=[0-9a-f]{64}$/);
+    const h = new Headers({ "X-Hub-Signature-256": sig });
+    expect(
+      verifyWhatsAppSignature({ headers: h, body, appSecret: APP_SECRET }, { now: FIXTURE_NOW }),
+    ).toBe(true);
+  });
+
+  test("is deterministic for a given (body, secret)", () => {
+    const a = signWhatsAppBody({ body: "{}", appSecret: APP_SECRET });
+    const b = signWhatsAppBody({ body: "{}", appSecret: APP_SECRET });
+    expect(a).toBe(b);
+  });
+
+  test("differs when the secret differs", () => {
+    const a = signWhatsAppBody({ body: "{}", appSecret: APP_SECRET });
+    const b = signWhatsAppBody({ body: "{}", appSecret: "other-secret" });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("parseInbound — branch coverage (T2)", () => {
+  // Build a well-formed text payload and let callers perturb a single field.
+  function payloadWith(msg: Record<string, unknown>, value: Record<string, unknown> = {}): string {
+    return JSON.stringify({
+      object: "whatsapp_business_account",
+      entry: [
+        {
+          id: "100100100100",
+          changes: [
+            {
+              field: "messages",
+              value: {
+                messaging_product: "whatsapp",
+                metadata: { phone_number_id: PHONE_NUMBER_ID },
+                messages: [{ id: "wamid.gen-1", from: "15554443333", ...msg }],
+                ...value,
+              },
+            },
+          ],
+        },
+      ],
+    });
+  }
+
+  test("non-object JSON (e.g. a bare number) → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound({ headers: new Headers(), body: "42" }).kind).toBe("skip");
+  });
+
+  test("JSON null literal → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound({ headers: new Headers(), body: "null" }).kind).toBe("skip");
+  });
+
+  test("change.field other than 'messages' → skip", () => {
+    const a = adapter();
+    const body = JSON.stringify({
+      object: "whatsapp_business_account",
+      entry: [{ changes: [{ field: "message_template_status_update", value: {} }] }],
+    });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("messages field present but value missing → skip", () => {
+    const a = adapter();
+    const body = JSON.stringify({
+      object: "whatsapp_business_account",
+      entry: [{ changes: [{ field: "messages" }] }],
+    });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("message missing id (non-string) → skip", () => {
+    const a = adapter();
+    const body = payloadWith({ id: undefined, type: "text", text: { body: "hi" } });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("message missing from (non-string) → skip", () => {
+    const a = adapter();
+    const body = payloadWith({ from: undefined, type: "text", text: { body: "hi" } });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("metadata present but phone_number_id empty → skip", () => {
+    const a = adapter();
+    const body = payloadWith(
+      { type: "text", text: { body: "hi" } },
+      { metadata: { display_phone_number: "15551112222" } },
+    );
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("text message with empty body → event with text ''", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "text", text: { body: "" } });
+    const r = a.parseInbound({ headers: new Headers(), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.kind).toBe("event");
+    expect(r.event.text).toBe("");
+  });
+
+  test("text message with no text field → event with text ''", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "text" });
+    const r = a.parseInbound({ headers: new Headers(), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("");
+  });
+
+  test("missing timestamp → event ts defaults to ''", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "text", text: { body: "hi" } });
+    const r = a.parseInbound({ headers: new Headers(), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.ts).toBe("");
+  });
+
+  test("button_reply with missing id → text '[button:]'", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "interactive", interactive: { type: "button_reply" } });
+    const r = a.parseInbound({ headers: new Headers(), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("[button:]");
+  });
+
+  test("list_reply with missing id → text '[list:]'", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "interactive", interactive: { type: "list_reply" } });
+    const r = a.parseInbound({ headers: new Headers(), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("[list:]");
+  });
+
+  test("interactive with unknown sub-type → skip", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "interactive", interactive: { type: "flow_reply" } });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("interactive with no interactive object → skip", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "interactive" });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("video type (unsupported) → skip via default branch", () => {
+    const a = adapter();
+    const body = payloadWith({ type: "video" });
+    expect(a.parseInbound({ headers: new Headers(), body }).kind).toBe("skip");
+  });
+
+  test("ignores prototype-polluting keys in the payload", () => {
+    const a = adapter();
+    const body = `{"object":"whatsapp_business_account","__proto__":{"polluted":true},"entry":[{"changes":[{"field":"messages","value":{"metadata":{"phone_number_id":"${PHONE_NUMBER_ID}"},"messages":[{"id":"wamid.p","from":"15554443333","type":"text","text":{"body":"hi"}}]}}]}]}`;
+    const r = a.parseInbound({ headers: new Headers(), body });
+    expect(r.kind).toBe("event");
+    // No global prototype mutation occurred.
+    expect(({} as Record<string, unknown>)["polluted"]).toBeUndefined();
+  });
+});
+
+describe("createWhatsAppAdapter — config / options", () => {
+  const event: InboundEvent = {
+    idempotencyKey: "wamid.xx",
+    workspaceId: PHONE_NUMBER_ID,
+    channelId: "15554443333",
+    userId: "15554443333",
+    ts: "1700000123",
+    text: "hello",
+    subtype: "message",
+  };
+
+  test("id is 'whatsapp'", () => {
+    expect(adapter().id).toBe("whatsapp");
+  });
+
+  test("defaults to graph.facebook.com / v22.0 when no base url given", async () => {
+    const calls: string[] = [];
+    const f = (async (input: string | Request | URL) => {
+      calls.push(String(input));
+      return new Response("", { status: 200 });
+    }) as unknown as typeof fetch;
+    // No apiBaseUrl override and no env var → default host.
+    const prev = process.env["WHATSAPP_API_BASE_URL"];
+    Reflect.deleteProperty(process.env, "WHATSAPP_API_BASE_URL");
+    try {
+      const a = createWhatsAppAdapter(
+        { phoneNumberId: PHONE_NUMBER_ID, accessToken: ACCESS_TOKEN, appSecret: APP_SECRET },
+        { fetch: f },
+      );
+      await a.sendReply({ event, text: "x" });
+    } finally {
+      if (prev === undefined) Reflect.deleteProperty(process.env, "WHATSAPP_API_BASE_URL");
+      else process.env["WHATSAPP_API_BASE_URL"] = prev;
+    }
+    expect(calls[0]).toBe(`https://graph.facebook.com/v22.0/${PHONE_NUMBER_ID}/messages`);
+  });
+
+  test("honours WHATSAPP_API_BASE_URL env override", async () => {
+    const calls: string[] = [];
+    const f = (async (input: string | Request | URL) => {
+      calls.push(String(input));
+      return new Response("", { status: 200 });
+    }) as unknown as typeof fetch;
+    const prev = process.env["WHATSAPP_API_BASE_URL"];
+    process.env["WHATSAPP_API_BASE_URL"] = "https://env.graph.local";
+    try {
+      const a = createWhatsAppAdapter(
+        { phoneNumberId: PHONE_NUMBER_ID, accessToken: ACCESS_TOKEN, appSecret: APP_SECRET },
+        { fetch: f },
+      );
+      await a.sendReply({ event, text: "x" });
+    } finally {
+      if (prev === undefined) Reflect.deleteProperty(process.env, "WHATSAPP_API_BASE_URL");
+      else process.env["WHATSAPP_API_BASE_URL"] = prev;
+    }
+    expect(calls[0]).toBe(`https://env.graph.local/v22.0/${PHONE_NUMBER_ID}/messages`);
+  });
+
+  test("honours apiVersion option", async () => {
+    const calls: string[] = [];
+    const f = (async (input: string | Request | URL) => {
+      calls.push(String(input));
+      return new Response("", { status: 200 });
+    }) as unknown as typeof fetch;
+    const a = createWhatsAppAdapter(
+      { phoneNumberId: PHONE_NUMBER_ID, accessToken: ACCESS_TOKEN, appSecret: APP_SECRET },
+      { apiBaseUrl: "https://test.graph.local", apiVersion: "v21.0", fetch: f },
+    );
+    await a.sendReply({ event, text: "x" });
+    expect(calls[0]).toBe(`https://test.graph.local/v21.0/${PHONE_NUMBER_ID}/messages`);
+  });
+});
+
+describe("sendReply — response handling (T3)", () => {
+  const event: InboundEvent = {
+    idempotencyKey: "wamid.xx",
+    workspaceId: PHONE_NUMBER_ID,
+    channelId: "15554443333",
+    userId: "15554443333",
+    ts: "1700000123",
+    text: "hello",
+    subtype: "message",
+  };
+
+  test("resolves on a 200 with non-JSON content-type (body not parsed)", async () => {
+    const f = (async () =>
+      new Response("OK", {
+        status: 200,
+        headers: { "content-type": "text/plain" },
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).resolves.toBeUndefined();
+  });
+
+  test("resolves on a 200 with no content-type header", async () => {
+    const f = (async () => new Response("", { status: 200 })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).resolves.toBeUndefined();
+  });
+
+  test("resolves on a 200 JSON success envelope without an error field", async () => {
+    const f = (async () =>
+      new Response(JSON.stringify({ messages: [{ id: "wamid.ok" }] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).resolves.toBeUndefined();
+  });
+
+  test("error envelope with no message falls back to 'unknown'", async () => {
+    const f = (async () =>
+      new Response(JSON.stringify({ error: {} }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).rejects.toThrow(/messages POST error: unknown/);
+  });
 });

package/src/index.ts

@@ -77,6 +77,8 @@ export type WhatsAppAdapterOptions = {
   readonly apiBaseUrl?: string;
   readonly fetch?: typeof fetch;
   readonly apiVersion?: string;
+  /** Clock injection for the signature replay-window check (tests). */
+  readonly now?: () => number;
 };
 
 const DEFAULT_API_BASE_URL = "https://graph.facebook.com";
@@ -96,11 +98,14 @@ export function createWhatsAppAdapter(
     id: "whatsapp",
 
     verify(req: RawRequest): boolean {
-      return verifyWhatsAppSignature({
-        headers: req.headers,
-        body: req.body,
-        appSecret: config.appSecret,
-      });
+      return verifyWhatsAppSignature(
+        {
+          headers: req.headers,
+          body: req.body,
+          appSecret: config.appSecret,
+        },
+        opts.now !== undefined ? { now: opts.now } : {},
+      );
     },
 
     parseInbound(req: RawRequest): ParsedInbound {

package/src/verify.ts

@@ -15,7 +15,66 @@ export type WhatsAppVerifyArgs = {
   readonly appSecret: string;
 };
 
-export function verifyWhatsAppSignature(args: WhatsAppVerifyArgs): boolean {
+export type WhatsAppVerifyOptions = {
+  readonly now?: () => number;
+  readonly toleranceMs?: number;
+};
+
+// WhatsApp signs only the body — there is no signed timestamp header — so the
+// replay-window check reads `messages[].timestamp` from the AUTHENTICATED body
+// after the HMAC passes. Unlike the Slack/Discord real-time interaction
+// windows, WhatsApp redelivers failed webhooks on its own (multi-minute) retry
+// schedule, so this default is deliberately more generous: it bounds INDEFINITE
+// replay of a captured message rather than enforcing sub-minute freshness.
+// Operators can widen/tighten it via `toleranceMs`; the gateway's durable
+// cross-process dedup is the complementary, stronger control.
+const DEFAULT_TOLERANCE_MS = 10 * 60 * 1000;
+
+function asRecord(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null ? (v as Record<string, unknown>) : undefined;
+}
+
+/**
+ * Newest `messages[].timestamp` (unix seconds) in a WhatsApp webhook body, or
+ * undefined when there is none (e.g. status-only webhooks, which are skipped
+ * downstream). An attacker cannot strip the timestamp from a signed message
+ * body without invalidating the HMAC, so "no timestamp ⇒ accept" is safe.
+ */
+function newestMessageTimestamp(body: string): number | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+  const entries = asRecord(parsed)?.["entry"];
+  if (!Array.isArray(entries)) return undefined;
+  let newest: number | undefined;
+  const consider = (raw: unknown): void => {
+    const n =
+      typeof raw === "number"
+        ? raw
+        : typeof raw === "string"
+          ? Number.parseInt(raw, 10)
+          : Number.NaN;
+    if (Number.isFinite(n)) newest = newest === undefined ? n : Math.max(newest, n);
+  };
+  for (const entryRaw of entries) {
+    const changes = asRecord(entryRaw)?.["changes"];
+    if (!Array.isArray(changes)) continue;
+    for (const changeRaw of changes) {
+      const messages = asRecord(asRecord(changeRaw)?.["value"])?.["messages"];
+      if (!Array.isArray(messages)) continue;
+      for (const msgRaw of messages) consider(asRecord(msgRaw)?.["timestamp"]);
+    }
+  }
+  return newest;
+}
+
+export function verifyWhatsAppSignature(
+  args: WhatsAppVerifyArgs,
+  opts: WhatsAppVerifyOptions = {},
+): boolean {
   const supplied = args.headers.get("x-hub-signature-256");
   if (!supplied) return false;
   if (!supplied.startsWith("sha256=")) return false;
@@ -26,7 +85,14 @@ export function verifyWhatsAppSignature(args: WhatsAppVerifyArgs): boolean {
   const expectedBuf = Buffer.from(expected, "utf8");
   const actualBuf = Buffer.from(sigHex.toLowerCase(), "utf8");
   if (expectedBuf.length !== actualBuf.length) return false;
-  return timingSafeEqual(expectedBuf, actualBuf);
+  if (!timingSafeEqual(expectedBuf, actualBuf)) return false;
+
+  // HMAC valid — now bound replay on the authenticated body.
+  const now = opts.now ?? (() => Date.now());
+  const tolerance = opts.toleranceMs ?? DEFAULT_TOLERANCE_MS;
+  const ts = newestMessageTimestamp(args.body);
+  if (ts !== undefined && Math.abs(now() - ts * 1000) > tolerance) return false;
+  return true;
 }
 
 /**