carlyemail 0.2.0 → 0.4.0

package/webhooks.d.ts

@@ -0,0 +1,35 @@
+export interface CarlyEmailEvent {
+  type: "event";
+  event_type: string;
+  event_id: string;
+  message?: Record<string, unknown>;
+  thread?: Record<string, unknown>;
+  send?: Record<string, unknown>;
+  delivery?: Record<string, unknown>;
+  bounce?: Record<string, unknown>;
+  complaint?: Record<string, unknown>;
+  reject?: Record<string, unknown>;
+  domain?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface VerifyWebhookOptions {
+  toleranceSeconds?: number;
+  /** Unix timestamp in seconds; intended for deterministic tests. */
+  now?: number;
+}
+
+export declare class WebhookVerificationError extends Error {}
+
+export declare function verifyWebhook(
+  secret: string,
+  body: string | Uint8Array | ArrayBuffer,
+  headers: Headers | Record<string, string>,
+  options?: VerifyWebhookOptions,
+): Promise<CarlyEmailEvent>;
+
+export declare function createEmailHandler(options: {
+  secret: string;
+  onEmail: (event: CarlyEmailEvent, request: Request) => unknown | Promise<unknown>;
+  toleranceSeconds?: number;
+}): (request: Request) => Promise<Response>;

package/webhooks.js

@@ -0,0 +1,110 @@
+// Webhook verification and an email-channel handler for Workers, Node, and edge
+// runtimes. Web Crypto only; no Node-specific imports and no dependencies.
+
+export class WebhookVerificationError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WebhookVerificationError";
+  }
+}
+
+function header(headers, name) {
+  if (typeof headers?.get === "function") return headers.get(name);
+  const wanted = name.toLowerCase();
+  const found = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === wanted);
+  return found?.[1];
+}
+
+function bytes(value) {
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new TypeError("webhook body must be a string, Uint8Array, or ArrayBuffer");
+}
+
+function decodeBase64(value, label) {
+  try {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  } catch (error) {
+    throw new WebhookVerificationError(`${label} is not valid base64`, { cause: error });
+  }
+}
+
+/**
+ * Verify a CarlyEmail/Svix webhook and return its parsed event body.
+ *
+ * The unmodified raw body is required. A framework-parsed JSON object cannot be
+ * reconstructed byte-for-byte and will fail the signature by design.
+ */
+export async function verifyWebhook(secret, body, headers, options = {}) {
+  const messageId = header(headers, "webhook-id") ?? header(headers, "svix-id");
+  const timestamp = header(headers, "webhook-timestamp") ?? header(headers, "svix-timestamp");
+  const signatures =
+    header(headers, "webhook-signature") ?? header(headers, "svix-signature");
+  if (!messageId || !timestamp || !signatures) {
+    throw new WebhookVerificationError("missing webhook signature headers");
+  }
+
+  const sentAt = Number(timestamp);
+  if (!Number.isSafeInteger(sentAt)) {
+    throw new WebhookVerificationError("webhook timestamp is not an integer");
+  }
+  const now = options.now ?? Math.floor(Date.now() / 1000);
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  if (Math.abs(now - sentAt) > toleranceSeconds) {
+    throw new WebhookVerificationError("webhook timestamp is outside the allowed window");
+  }
+
+  const rawBody = bytes(body);
+  const prefix = new TextEncoder().encode(`${messageId}.${timestamp}.`);
+  const signed = new Uint8Array(prefix.length + rawBody.length);
+  signed.set(prefix);
+  signed.set(rawBody, prefix.length);
+  const keyBytes = decodeBase64(secret.replace(/^whsec_/, ""), "webhook secret");
+  const key = await crypto.subtle.importKey(
+    "raw",
+    keyBytes,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  for (const candidate of signatures.split(/\s+/)) {
+    const [version, encoded] = candidate.split(",", 2);
+    if (version !== "v1" || !encoded) continue;
+    const signature = decodeBase64(encoded, "webhook signature");
+    if (await crypto.subtle.verify("HMAC", key, signature, signed)) {
+      return JSON.parse(new TextDecoder().decode(rawBody));
+    }
+  }
+  throw new WebhookVerificationError("webhook signature does not match");
+}
+
+/**
+ * Build a fetch-compatible handler with a Cloudflare-style `onEmail(event)`
+ * callback. Handler errors are allowed through so the delivery gets a 5xx and
+ * retries; only verification errors are turned into terminal 400 responses.
+ */
+export function createEmailHandler({ secret, onEmail, toleranceSeconds = 300 }) {
+  if (!secret) throw new Error("createEmailHandler requires a webhook secret");
+  if (typeof onEmail !== "function") throw new TypeError("createEmailHandler requires onEmail");
+
+  return async function handle(request) {
+    const body = new Uint8Array(await request.arrayBuffer());
+    let event;
+    try {
+      event = await verifyWebhook(secret, body, request.headers, { toleranceSeconds });
+    } catch (error) {
+      if (error instanceof WebhookVerificationError) {
+        return new Response(error.message, { status: 400 });
+      }
+      throw error;
+    }
+
+    if (event.event_type?.startsWith("message.received")) {
+      await onEmail(event, request);
+    }
+    return new Response(null, { status: 204 });
+  };
+}