@vellumai/vellum-gateway 0.6.0 → 0.6.1

package/Dockerfile

@@ -1,5 +1,5 @@
 # Bun binary source (pinned to SHA digest for immutable reference)
-FROM oven/bun:1.2.21@sha256:5a2011bf09364b9af658ac1e66f60d08092f4291aeefbff448d58b027734fdd0 AS bun
+FROM oven/bun:1.3.11@sha256:0733e50325078969732ebe3b15ce4c4be5082f18c4ac1a0f0ca4839c2e4e42a7 AS bun
 
 # Build stage
 FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS builder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/config.test.ts

@@ -23,7 +23,8 @@ describe("config: hardcoded defaults", () => {
     expect(config.unmappedPolicy).toBe("reject");
     expect(config.routingEntries).toEqual([]);
     expect(config.defaultAssistantId).toBeUndefined();
-    expect(config.logFile).toEqual({ dir: undefined, retentionDays: 30 });
+    expect(config.logFile.dir).toMatch(/\.vellum\/logs$/);
+    expect(config.logFile.retentionDays).toBe(30);
   });
 
   test("GATEWAY_PORT defaults to 7830", () => {

package/src/__tests__/remote-feature-flag-sync.test.ts

@@ -428,6 +428,43 @@ describe("RemoteFeatureFlagSync", () => {
     );
   });
 
+  test("ignores remote false for GA flags (defaultEnabled: true in registry)", async () => {
+    // The platform sends false for all flags it knows about (blanket-deny).
+    // GA flags (defaultEnabled: true in the registry) should not be disabled
+    // by remote overrides — only local persisted overrides can do that.
+    fetchMock = mock(async () =>
+      Response.json({
+        flags: {
+          // GA flag (defaultEnabled: true) — remote false should be dropped
+          "conversation-starters": false,
+          // Gated flag (defaultEnabled: false) — remote false is kept
+          "email-channel": false,
+          // GA flag set to true — should be kept (redundant but harmless)
+          browser: true,
+          // Unknown flag — remote false is kept (not in registry)
+          "unknown-flag": false,
+        },
+      }),
+    );
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+    });
+    await sync.start();
+    sync.stop();
+
+    clearRemoteFeatureFlagStoreCache();
+    const cached = readRemoteFeatureFlags();
+    // conversation-starters (GA, remote false) should be absent
+    expect(cached["conversation-starters"]).toBeUndefined();
+    // email-channel (gated, remote false) should be present
+    expect(cached["email-channel"]).toBe(false);
+    // browser (GA, remote true) should be present
+    expect(cached.browser).toBe(true);
+    // unknown-flag (not in registry, remote false) should be present
+    expect(cached["unknown-flag"]).toBe(false);
+  });
+
   test("trims whitespace from credential values", async () => {
     fetchMock = mock(async () => Response.json({ flags: {} }));
 

package/src/channels/inbound-event.ts

@@ -10,7 +10,7 @@ import type { ChannelId } from "./types.js";
 
 export type InboundChannelId = Extract<
   ChannelId,
-  "telegram" | "whatsapp" | "slack"
+  "telegram" | "whatsapp" | "slack" | "email"
 >;
 
 interface InboundEventBase<C extends InboundChannelId> {
@@ -52,8 +52,10 @@ interface InboundEventBase<C extends InboundChannelId> {
 export type TelegramInboundEvent = InboundEventBase<"telegram">;
 export type WhatsAppInboundEvent = InboundEventBase<"whatsapp">;
 export type SlackInboundEvent = InboundEventBase<"slack">;
+export type EmailInboundEvent = InboundEventBase<"email">;
 
 export type GatewayInboundEvent =
   | TelegramInboundEvent
   | WhatsAppInboundEvent
-  | SlackInboundEvent;
+  | SlackInboundEvent
+  | EmailInboundEvent;

package/src/channels/transport-hints.ts

@@ -35,3 +35,21 @@ export function buildWhatsAppTransportMetadata(): {
     uxBrief: WHATSAPP_CHANNEL_TRANSPORT_UX_BRIEF,
   };
 }
+
+export const EMAIL_CHANNEL_TRANSPORT_HINTS = [
+  "email-medium",
+  "defer-dashboard-only-tasks",
+] as const;
+
+export const EMAIL_CHANNEL_TRANSPORT_UX_BRIEF =
+  "Email is an asynchronous medium. Responses can be longer and more detailed than chat. Use proper formatting. The user may not see the response immediately.";
+
+export function buildEmailTransportMetadata(): {
+  hints: string[];
+  uxBrief: string;
+} {
+  return {
+    hints: [...EMAIL_CHANNEL_TRANSPORT_HINTS],
+    uxBrief: EMAIL_CHANNEL_TRANSPORT_UX_BRIEF,
+  };
+}

package/src/config.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { getLogger, type LogFileConfig } from "./logger.js";
@@ -148,7 +149,9 @@ export function loadConfig(): GatewayConfig {
   }
 
   const logFile: LogFileConfig = {
-    dir: undefined,
+    dir:
+      process.env.GATEWAY_LOG_DIR ??
+      join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum", "logs"),
     retentionDays: 30,
   };
 

package/src/download-validation.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ContentMismatchError,
+  validateDownloadedContent,
+} from "./download-validation.js";
+
+/** Create a minimal valid PNG buffer that file-type can detect. */
+function makePngBuffer(): Uint8Array {
+  return new Uint8Array([
+    // PNG signature
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+    // IHDR chunk: length (13)
+    0x00, 0x00, 0x00, 0x0d,
+    // IHDR type
+    0x49, 0x48, 0x44, 0x52,
+    // Width: 1
+    0x00, 0x00, 0x00, 0x01,
+    // Height: 1
+    0x00, 0x00, 0x00, 0x01,
+    // Bit depth, color type, compression, filter, interlace
+    0x08, 0x02, 0x00, 0x00, 0x00,
+    // CRC (placeholder)
+    0x90, 0x77, 0x53, 0xde,
+  ]);
+}
+
+function htmlBuffer(html: string): Uint8Array {
+  return new TextEncoder().encode(html);
+}
+
+describe("validateDownloadedContent", () => {
+  test("throws ContentMismatchError when HTML is received instead of image/png", async () => {
+    const buffer = htmlBuffer(
+      "<!DOCTYPE html><html><body><h1>Access Denied</h1></body></html>",
+    );
+
+    await expect(
+      validateDownloadedContent(buffer, "image/png", "F001"),
+    ).rejects.toThrow(ContentMismatchError);
+
+    await expect(
+      validateDownloadedContent(buffer, "image/png", "F001"),
+    ).rejects.toThrow(
+      "File F001 declared as image/png but content is HTML (likely an auth/error page)",
+    );
+  });
+
+  test("throws ContentMismatchError for HTML with leading whitespace and BOM", async () => {
+    // UTF-8 BOM (EF BB BF) + whitespace + HTML
+    const bom = new Uint8Array([0xef, 0xbb, 0xbf]);
+    const html = new TextEncoder().encode(
+      "  \n  <!DOCTYPE html><html><body>Error</body></html>",
+    );
+    const buffer = new Uint8Array(bom.length + html.length);
+    buffer.set(bom, 0);
+    buffer.set(html, bom.length);
+
+    await expect(
+      validateDownloadedContent(buffer, "image/jpeg", "F002"),
+    ).rejects.toThrow(ContentMismatchError);
+  });
+
+  test("passes for valid PNG buffer with declared image/png", async () => {
+    const buffer = makePngBuffer();
+
+    // Should not throw
+    await validateDownloadedContent(buffer, "image/png", "F003");
+  });
+
+  test("passes for valid PNG buffer with declared image/jpeg (same image family)", async () => {
+    const buffer = makePngBuffer();
+
+    // file-type detects it as image/png, which still starts with "image/"
+    // so it should pass even though declared as image/jpeg
+    await validateDownloadedContent(buffer, "image/jpeg", "F004");
+  });
+
+  test("passes for plain text buffer with declared text/plain (non-binary)", async () => {
+    const buffer = new TextEncoder().encode("hello world");
+
+    // text/plain is not a binary MIME type, so no validation is performed
+    await validateDownloadedContent(
+      new Uint8Array(buffer),
+      "text/plain",
+      "F005",
+    );
+  });
+
+  test("passes for empty buffer with declared image/png", async () => {
+    const buffer = new Uint8Array(0);
+
+    // Empty buffer: looksLikeHtml returns false, fileTypeFromBuffer returns
+    // undefined, so we allow it through and let downstream handle it
+    await validateDownloadedContent(buffer, "image/png", "F006");
+  });
+});

package/src/download-validation.ts

@@ -0,0 +1,92 @@
+import { fileTypeFromBuffer } from "file-type";
+
+export class ContentMismatchError extends Error {
+  override name = "ContentMismatchError";
+}
+
+/**
+ * Check whether a buffer looks like an HTML page by inspecting the first
+ * non-whitespace / non-BOM bytes for common HTML markers.
+ */
+export function looksLikeHtml(buffer: Uint8Array): boolean {
+  // Skip leading whitespace and UTF-8 BOM (0xEF 0xBB 0xBF)
+  let offset = 0;
+  // Skip UTF-8 BOM if present
+  if (
+    buffer.length >= 3 &&
+    buffer[0] === 0xef &&
+    buffer[1] === 0xbb &&
+    buffer[2] === 0xbf
+  ) {
+    offset = 3;
+  }
+  // Skip whitespace characters (space, tab, newline, carriage return)
+  while (offset < buffer.length) {
+    const byte = buffer[offset];
+    if (byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d) {
+      offset++;
+    } else {
+      break;
+    }
+  }
+
+  if (offset >= buffer.length) {
+    return false;
+  }
+
+  const remaining = buffer.subarray(offset);
+  const prefix = new TextDecoder("utf-8", { fatal: false }).decode(
+    remaining.subarray(0, Math.min(remaining.length, 15)),
+  );
+
+  const upper = prefix.toUpperCase();
+  return upper.startsWith("<!DOCTYPE") || upper.startsWith("<HTML");
+}
+
+const BINARY_MIME_PREFIXES = [
+  "image/",
+  "audio/",
+  "video/",
+  "application/pdf",
+] as const;
+
+/**
+ * Validate that downloaded content actually matches its declared MIME type.
+ *
+ * This catches a common failure mode where CDNs (Slack, WhatsApp, Telegram)
+ * return an HTML error or auth page instead of the actual binary file.
+ * Base64-encoding that HTML and sending it to a provider as e.g. `image/png`
+ * causes the provider to reject the request.
+ */
+export async function validateDownloadedContent(
+  buffer: Uint8Array,
+  declaredMime: string,
+  fileId: string,
+): Promise<void> {
+  const isBinary = BINARY_MIME_PREFIXES.some((prefix) =>
+    declaredMime.startsWith(prefix),
+  );
+
+  if (!isBinary) {
+    return;
+  }
+
+  // Guard: if the buffer looks like HTML, it's almost certainly an error page
+  if (looksLikeHtml(buffer)) {
+    throw new ContentMismatchError(
+      `File ${fileId} declared as ${declaredMime} but content is HTML (likely an auth/error page)`,
+    );
+  }
+
+  // For image types, do a deeper check with file-type detection
+  if (declaredMime.startsWith("image/")) {
+    const detected = await fileTypeFromBuffer(buffer);
+    if (detected && !detected.mime.startsWith("image/")) {
+      throw new ContentMismatchError(
+        `File ${fileId} declared as ${declaredMime} but detected as ${detected.mime}`,
+      );
+    }
+    // If detected is undefined and it doesn't look like HTML, allow it
+    // through — some image formats may not be in file-type's database.
+  }
+}

package/src/email/normalize.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "bun:test";
+import { normalizeEmailWebhook } from "./normalize.js";
+
+describe("normalizeEmailWebhook", () => {
+  function makePayload(overrides?: Record<string, unknown>) {
+    return {
+      from: "alice@example.com",
+      to: "bot@vellum.me",
+      messageId: "<msg-1@example.com>",
+      conversationId: "conv-1",
+      subject: "Test Subject",
+      strippedText: "Hello, world!",
+      bodyText: "On Mon, someone wrote:\n> old\n\nHello, world!",
+      timestamp: "2026-04-03T01:00:00.000Z",
+      ...(overrides ?? {}),
+    };
+  }
+
+  it("normalizes a valid email payload", () => {
+    const result = normalizeEmailWebhook(makePayload());
+    expect(result).not.toBeNull();
+    expect(result!.eventId).toBe("<msg-1@example.com>");
+    expect(result!.recipientAddress).toBe("bot@vellum.me");
+    expect(result!.event.sourceChannel).toBe("email");
+    expect(result!.event.message.content).toBe("Hello, world!");
+    expect(result!.event.message.conversationExternalId).toBe("conv-1");
+    expect(result!.event.message.externalMessageId).toBe("<msg-1@example.com>");
+    expect(result!.event.actor.actorExternalId).toBe("alice@example.com");
+    expect(result!.event.actor.displayName).toBe("alice@example.com");
+  });
+
+  it("returns null when required fields are missing", () => {
+    // Missing 'from'
+    expect(
+      normalizeEmailWebhook({
+        to: "bot@vellum.me",
+        messageId: "m",
+        conversationId: "c",
+      }),
+    ).toBeNull();
+    // Missing 'to'
+    expect(
+      normalizeEmailWebhook({
+        from: "a@b.com",
+        messageId: "m",
+        conversationId: "c",
+      }),
+    ).toBeNull();
+    // Missing 'messageId'
+    expect(
+      normalizeEmailWebhook({
+        from: "a@b.com",
+        to: "bot@vellum.me",
+        conversationId: "c",
+      }),
+    ).toBeNull();
+    // Missing 'conversationId'
+    expect(
+      normalizeEmailWebhook({
+        from: "a@b.com",
+        to: "bot@vellum.me",
+        messageId: "m",
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null for empty object", () => {
+    expect(normalizeEmailWebhook({})).toBeNull();
+  });
+
+  it("uses fromName as displayName when provided", () => {
+    const result = normalizeEmailWebhook(
+      makePayload({ fromName: "Alice Smith" }),
+    );
+    expect(result).not.toBeNull();
+    expect(result!.event.actor.actorExternalId).toBe("alice@example.com");
+    expect(result!.event.actor.displayName).toBe("Alice Smith");
+  });
+
+  it("falls back to email as displayName when fromName is absent", () => {
+    const result = normalizeEmailWebhook(makePayload());
+    expect(result!.event.actor.displayName).toBe("alice@example.com");
+  });
+
+  it("prefers strippedText over bodyText", () => {
+    const result = normalizeEmailWebhook(
+      makePayload({
+        strippedText: "Just the new reply",
+        bodyText: "Full email with quoted content",
+      }),
+    );
+    expect(result!.event.message.content).toBe("Just the new reply");
+  });
+
+  it("falls back to bodyText when strippedText is missing", () => {
+    const payload = makePayload();
+    delete (payload as Record<string, unknown>).strippedText;
+    const result = normalizeEmailWebhook(payload);
+    expect(result!.event.message.content).toBe(
+      "On Mon, someone wrote:\n> old\n\nHello, world!",
+    );
+  });
+
+  it("uses empty string when both strippedText and bodyText are missing", () => {
+    const payload = makePayload();
+    delete (payload as Record<string, unknown>).strippedText;
+    delete (payload as Record<string, unknown>).bodyText;
+    const result = normalizeEmailWebhook(payload);
+    expect(result!.event.message.content).toBe("");
+  });
+
+  it("uses messageId as eventId", () => {
+    const result = normalizeEmailWebhook(
+      makePayload({ messageId: "<unique@example.com>" }),
+    );
+    expect(result!.eventId).toBe("<unique@example.com>");
+  });
+
+  it("sets username to sender email", () => {
+    const result = normalizeEmailWebhook(makePayload());
+    expect(result!.event.actor.username).toBe("alice@example.com");
+  });
+
+  it("preserves raw payload in event.raw", () => {
+    const payload = makePayload();
+    const result = normalizeEmailWebhook(payload);
+    expect(result!.event.raw).toEqual(payload);
+  });
+});

package/src/email/normalize.ts

@@ -0,0 +1,94 @@
+import type { GatewayInboundEvent } from "../types.js";
+
+/**
+ * Shape of a normalized inbound email event as sent by the Vellum
+ * platform (or any upstream caller).
+ *
+ * The platform is responsible for provider-specific parsing (e.g.
+ * Mailgun multipart → JSON). By the time the payload reaches the
+ * gateway it should already be in this canonical shape.
+ */
+export interface VellumEmailPayload {
+  /** Sender email address (e.g. "user@vellum.me"). */
+  from: string;
+  /** Sender display name (e.g. "Alice Smith"). Optional. */
+  fromName?: string;
+  /** Recipient email address (the assistant's address). */
+  to: string;
+  /** Email subject line. */
+  subject?: string;
+  /** Plain-text body content (latest reply only, quoted text stripped). */
+  strippedText?: string;
+  /** Full plain-text body (fallback when strippedText is unavailable). */
+  bodyText?: string;
+  /** RFC 5322 Message-ID header value. */
+  messageId: string;
+  /** Message-ID of the parent message (In-Reply-To header). */
+  inReplyTo?: string;
+  /** Space-separated chain of ancestor Message-IDs (References header). */
+  references?: string;
+  /** Stable conversation/thread identifier derived by the platform. */
+  conversationId: string;
+  /** ISO 8601 timestamp of the original email. */
+  timestamp?: string;
+}
+
+export interface NormalizedEmailEvent {
+  event: GatewayInboundEvent;
+  /** Unique event/message ID for dedup. */
+  eventId: string;
+  /** Original recipient address for routing. */
+  recipientAddress: string;
+}
+
+/**
+ * Normalize a Vellum email webhook payload into a GatewayInboundEvent.
+ *
+ * Returns null if required fields are missing.
+ */
+export function normalizeEmailWebhook(
+  payload: Record<string, unknown>,
+): NormalizedEmailEvent | null {
+  const from = payload.from as string | undefined;
+  const to = payload.to as string | undefined;
+  const messageId = payload.messageId as string | undefined;
+  const conversationId = payload.conversationId as string | undefined;
+
+  if (!from || !to || !messageId || !conversationId) {
+    return null;
+  }
+
+  // Prefer strippedText (latest reply only) over full body
+  const content =
+    (payload.strippedText as string | undefined) ??
+    (payload.bodyText as string | undefined) ??
+    "";
+
+  const fromName = payload.fromName as string | undefined;
+
+  const event: GatewayInboundEvent = {
+    version: "v1",
+    sourceChannel: "email",
+    receivedAt: new Date().toISOString(),
+    message: {
+      content,
+      conversationExternalId: conversationId,
+      externalMessageId: messageId,
+    },
+    actor: {
+      actorExternalId: from,
+      displayName: fromName || from,
+      username: from,
+    },
+    source: {
+      updateId: messageId,
+    },
+    raw: payload,
+  };
+
+  return {
+    event,
+    eventId: messageId,
+    recipientAddress: to,
+  };
+}

package/src/email/verify.test.ts

@@ -0,0 +1,96 @@
+import { createHmac } from "node:crypto";
+import { describe, it, expect } from "bun:test";
+import { verifyEmailWebhookSignature } from "./verify.js";
+
+const SECRET = "test-webhook-secret-1234";
+
+function computeSignature(body: string, secret: string): string {
+  return (
+    "sha256=" + createHmac("sha256", secret).update(body, "utf8").digest("hex")
+  );
+}
+
+describe("verifyEmailWebhookSignature", () => {
+  const body = '{"from":"sender@example.com","to":"bot@vellum.me"}';
+
+  it("accepts a valid HMAC signature", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, SECRET),
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(true);
+  });
+
+  it("rejects a wrong secret", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, "wrong-secret"),
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects when header is missing", () => {
+    const headers = new Headers();
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects when secret is empty", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, SECRET),
+    });
+    expect(verifyEmailWebhookSignature(headers, body, "")).toBe(false);
+  });
+
+  it("rejects when header value is empty", () => {
+    const headers = new Headers({
+      "vellum-signature": "",
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects a signature without sha256= prefix", () => {
+    const digest = createHmac("sha256", SECRET)
+      .update(body, "utf8")
+      .digest("hex");
+    const headers = new Headers({
+      "vellum-signature": digest,
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects when body has been tampered with", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, SECRET),
+    });
+    expect(verifyEmailWebhookSignature(headers, "tampered body", SECRET)).toBe(
+      false,
+    );
+  });
+
+  it("produces different signatures for different bodies", () => {
+    const sig1 = computeSignature("body-a", SECRET);
+    const sig2 = computeSignature("body-b", SECRET);
+    expect(sig1).not.toBe(sig2);
+
+    const headers1 = new Headers({ "vellum-signature": sig1 });
+    expect(verifyEmailWebhookSignature(headers1, "body-a", SECRET)).toBe(true);
+    expect(verifyEmailWebhookSignature(headers1, "body-b", SECRET)).toBe(false);
+  });
+
+  it("rejects a truncated hex digest", () => {
+    const headers = new Headers({
+      "vellum-signature": "sha256=abcd1234",
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects non-ASCII hex values without throwing (Buffer byte length divergence)", () => {
+    // 64 non-ASCII characters whose UTF-16 .length === 64 (same as a valid
+    // hex digest) but whose Buffer byte length > 64, which would cause
+    // timingSafeEqual to throw if we only compared string lengths.
+    const nonAsciiHex = "\u00e9".repeat(64); // é is 2 bytes in UTF-8
+    const headers = new Headers({
+      "vellum-signature": `sha256=${nonAsciiHex}`,
+    });
+    // Must return false cleanly — not throw
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+});

package/src/email/verify.ts

@@ -0,0 +1,41 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify the Vellum-Signature header sent by the Vellum platform.
+ *
+ * The platform computes: HMAC-SHA256(webhookSecret, rawBody) and sends it as
+ *   Vellum-Signature: sha256=<hex-digest>
+ *
+ * We must compare with a constant-time comparison to avoid timing attacks.
+ *
+ * This mirrors the WhatsApp webhook signature verification pattern
+ * (`X-Hub-Signature-256` header).
+ */
+
+const HEADER_NAME = "vellum-signature";
+
+export function verifyEmailWebhookSignature(
+  headers: Headers,
+  rawBody: string,
+  webhookSecret: string,
+): boolean {
+  const signatureHeader = headers.get(HEADER_NAME);
+  if (!signatureHeader || !webhookSecret) return false;
+
+  // Header format: "sha256=<hex-digest>"
+  if (!signatureHeader.startsWith("sha256=")) return false;
+  const providedHex = signatureHeader.slice(7);
+
+  const expected = createHmac("sha256", webhookSecret)
+    .update(rawBody, "utf8")
+    .digest("hex");
+
+  // Compare Buffer byte lengths — not string .length — to avoid
+  // timingSafeEqual throwing on non-ASCII input where UTF-16 code unit
+  // count matches but byte length diverges.
+  const providedBuf = Buffer.from(providedHex);
+  const expectedBuf = Buffer.from(expected);
+  if (providedBuf.length !== expectedBuf.length) return false;
+
+  return timingSafeEqual(providedBuf, expectedBuf);
+}