@stacksjs/email 0.70.88 → 0.70.91

package/dist/webhook-handlers.js

@@ -0,0 +1,264 @@
+import { Buffer } from "node:buffer";
+import { suppress } from "./suppression";
+import { recordWebhookEventOrSkip } from "./webhook-dedup";
+import {
+  emitEmailBounceHard,
+  emitEmailBounceSoft,
+  emitEmailComplaint,
+  emitEmailUnsubscribe,
+  suppressionTypeFor
+} from "./webhook-events";
+import {
+  verifyMailgunSignature,
+  verifyPostmarkAuth,
+  verifySendgridSignature,
+  verifySesSnsSignature
+} from "./webhook-signatures";
+const OK_DUPLICATE = { status: 200, body: { ok: !0, processed: !1, reason: "duplicate" } };
+function unauthorized(reason) {
+  return { status: 401, body: { ok: !1, reason } };
+}
+function badRequest(reason) {
+  return { status: 400, body: { ok: !1, reason } };
+}
+async function dispatchClassifiedEvent(classification, payload) {
+  const suppressionType = suppressionTypeFor(classification);
+  if (suppressionType)
+    await suppress(payload.email, suppressionType, payload.reason);
+  switch (classification) {
+    case "bounce-hard":
+      await emitEmailBounceHard(payload);
+      break;
+    case "bounce-soft":
+      await emitEmailBounceSoft(payload);
+      break;
+    case "complaint":
+      await emitEmailComplaint(payload);
+      break;
+    case "unsubscribe":
+      await emitEmailUnsubscribe(payload);
+      break;
+    case "delivered":
+      break;
+  }
+}
+export async function handleMailgunWebhook(rawBody, config) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return badRequest("invalid-json");
+  }
+  const sig = parsed.signature, event = parsed["event-data"];
+  if (!sig || !event)
+    return badRequest("missing-fields");
+  const v = verifyMailgunSignature({
+    timestamp: sig.timestamp,
+    token: sig.token,
+    signature: sig.signature,
+    signingKey: config.signingKey,
+    toleranceSeconds: config.toleranceSeconds
+  });
+  if (!v.ok)
+    return unauthorized(v.reason);
+  if (!await recordWebhookEventOrSkip("mailgun", event.id))
+    return OK_DUPLICATE;
+  const classification = classifyMailgunEvent(event.event, event.severity);
+  if (!classification)
+    return { status: 200, body: { ok: !0, processed: !1, reason: "unhandled-event" } };
+  await dispatchClassifiedEvent(classification, {
+    email: event.recipient,
+    provider: "mailgun",
+    reason: event.reason,
+    raw: event
+  });
+  return { status: 200, body: { ok: !0, processed: !0, classification } };
+}
+function classifyMailgunEvent(event, severity) {
+  switch (event) {
+    case "failed":
+      return severity === "temporary" ? "bounce-soft" : "bounce-hard";
+    case "complained":
+      return "complaint";
+    case "unsubscribed":
+      return "unsubscribe";
+    case "delivered":
+      return "delivered";
+    default:
+      return null;
+  }
+}
+export async function handlePostmarkWebhook(rawBody, authorizationHeader, sourceIp, config) {
+  const v = verifyPostmarkAuth({
+    authorizationHeader,
+    expectedUsername: config.username,
+    expectedPassword: config.password,
+    sourceIp,
+    ipAllowlist: config.ipAllowlist
+  });
+  if (!v.ok)
+    return unauthorized(v.reason);
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return badRequest("invalid-json");
+  }
+  const eventId = String(parsed.ID ?? parsed.MessageID ?? ""), email = String(parsed.Email ?? parsed.Recipient ?? "");
+  if (!email)
+    return badRequest("missing-recipient");
+  if (!await recordWebhookEventOrSkip("postmark", eventId))
+    return OK_DUPLICATE;
+  const classification = classifyPostmarkEvent(parsed);
+  if (!classification)
+    return { status: 200, body: { ok: !0, processed: !1, reason: "unhandled-event" } };
+  await dispatchClassifiedEvent(classification, {
+    email,
+    provider: "postmark",
+    reason: parsed.Description,
+    raw: parsed
+  });
+  return { status: 200, body: { ok: !0, processed: !0, classification } };
+}
+function classifyPostmarkEvent(msg) {
+  switch (msg.RecordType) {
+    case "Bounce":
+      return msg.TypeCode === 1 ? "bounce-hard" : "bounce-soft";
+    case "SpamComplaint":
+      return "complaint";
+    case "SubscriptionChange":
+      return msg.SuppressSending ? "unsubscribe" : null;
+    case "Delivery":
+      return "delivered";
+    default:
+      return null;
+  }
+}
+export async function handleSesWebhook(rawBody, config = {}) {
+  let snsMessage;
+  try {
+    snsMessage = JSON.parse(rawBody);
+  } catch {
+    return badRequest("invalid-json");
+  }
+  const v = await verifySesSnsSignature({
+    message: snsMessage,
+    certUrlHostAllowlist: config.certUrlHostAllowlist,
+    fetchCert: config.fetchCert
+  });
+  if (!v.ok)
+    return unauthorized(v.reason);
+  if (snsMessage.Type === "SubscriptionConfirmation") {
+    if (config.autoConfirmSubscriptions !== !1 && snsMessage.SubscribeURL)
+      try {
+        await fetch(snsMessage.SubscribeURL);
+      } catch {}
+    return { status: 200, body: { ok: !0, processed: !0, reason: "subscription-confirmed" } };
+  }
+  if (snsMessage.Type === "UnsubscribeConfirmation")
+    return { status: 200, body: { ok: !0, processed: !0, reason: "subscription-removed" } };
+  let innerMessage;
+  try {
+    innerMessage = JSON.parse(snsMessage.Message);
+  } catch {
+    return badRequest("invalid-inner-json");
+  }
+  if (!await recordWebhookEventOrSkip("ses", snsMessage.MessageId))
+    return OK_DUPLICATE;
+  const dispatched = [];
+  if (innerMessage.notificationType === "Bounce" && innerMessage.bounce) {
+    const classification = innerMessage.bounce.bounceType === "Permanent" ? "bounce-hard" : "bounce-soft";
+    for (const r of innerMessage.bounce.bouncedRecipients) {
+      await dispatchClassifiedEvent(classification, {
+        email: r.emailAddress,
+        provider: "ses",
+        reason: r.diagnosticCode,
+        raw: innerMessage
+      });
+      dispatched.push(classification);
+    }
+  } else if (innerMessage.notificationType === "Complaint" && innerMessage.complaint)
+    for (const r of innerMessage.complaint.complainedRecipients) {
+      await dispatchClassifiedEvent("complaint", {
+        email: r.emailAddress,
+        provider: "ses",
+        reason: innerMessage.complaint.complaintFeedbackType,
+        raw: innerMessage
+      });
+      dispatched.push("complaint");
+    }
+  else if (innerMessage.notificationType === "Delivery" && innerMessage.delivery)
+    for (const r of innerMessage.delivery.recipients) {
+      await dispatchClassifiedEvent("delivered", { email: r, provider: "ses", raw: innerMessage });
+      dispatched.push("delivered");
+    }
+  return {
+    status: 200,
+    body: {
+      ok: !0,
+      processed: dispatched.length > 0,
+      classification: dispatched[0]
+    }
+  };
+}
+export async function handleSendgridWebhook(rawBody, signatureHeader, timestampHeader, config) {
+  const v = verifySendgridSignature({
+    body: rawBody,
+    signature: signatureHeader,
+    timestamp: timestampHeader,
+    publicKeyPem: config.publicKeyPem,
+    toleranceSeconds: config.toleranceSeconds
+  });
+  if (!v.ok)
+    return unauthorized(v.reason);
+  let events;
+  try {
+    events = JSON.parse(rawBody);
+  } catch {
+    return badRequest("invalid-json");
+  }
+  if (!Array.isArray(events))
+    return badRequest("expected-array");
+  let processed = 0;
+  const classifications = [];
+  for (const ev of events) {
+    if (!ev.email)
+      continue;
+    const id = ev.sg_event_id ?? `${ev.event}:${ev.email}:${Date.now()}`;
+    if (!await recordWebhookEventOrSkip("sendgrid", id))
+      continue;
+    const classification = classifySendgridEvent(ev.event, ev.type);
+    if (!classification)
+      continue;
+    await dispatchClassifiedEvent(classification, {
+      email: ev.email,
+      provider: "sendgrid",
+      reason: ev.reason,
+      raw: ev
+    });
+    processed++;
+    classifications.push(classification);
+  }
+  return {
+    status: 200,
+    body: { ok: !0, processed: processed > 0, classification: classifications[0] }
+  };
+}
+function classifySendgridEvent(event, type) {
+  switch (event) {
+    case "bounce":
+      return type === "blocked" ? "bounce-soft" : "bounce-hard";
+    case "dropped":
+      return "bounce-hard";
+    case "spamreport":
+      return "complaint";
+    case "unsubscribe":
+      return "unsubscribe";
+    case "group_unsubscribe":
+      return "unsubscribe";
+    case "delivered":
+      return "delivered";
+    default:
+      return null;
+  }
+}

package/dist/webhook-signatures.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Verify a Mailgun webhook signature. Mailgun signs
+ * `${timestamp}${token}` with HMAC-SHA256; the hex digest is
+ * compared in constant time against the `signature` field.
+ *
+ * The timestamp is checked against wall clock with a configurable
+ * tolerance (default 5 minutes) to reject replays. Constant-time
+ * compare prevents signature-timing oracles.
+ */
+export declare function verifyMailgunSignature(input: MailgunSignatureInput): SignatureVerification;
+/**
+ * Verify a Postmark webhook. Postmark uses HTTP Basic Auth (the app
+ * configures the username + password when registering the webhook in
+ * the Postmark dashboard); they don't sign the body. The auth check
+ * is constant-time. Optional IP-allowlist check rejects requests
+ * from outside Postmark's published source IPs.
+ */
+export declare function verifyPostmarkAuth(input: PostmarkAuthInput): SignatureVerification;
+/**
+ * Verify an SNS message signature (SES uses SNS for delivery). The
+ * cert URL host MUST match `sns.<region>.amazonaws.com` — any other
+ * host is treated as untrusted (defense against SSRF via crafted
+ * SigningCertURL).
+ *
+ * Note: this function intentionally only does the structural +
+ * cert-URL check + signature verify. SubscriptionConfirmation
+ * handling (responding to `SubscribeURL` to complete the topic
+ * binding) is the route handler's job since it's a one-time setup
+ * action distinct from per-event verification.
+ */
+export declare function verifySesSnsSignature(input: SesSnsSignatureInput): Promise<SignatureVerification>;
+/**
+ * Verify a SendGrid Event Webhook signature. SendGrid signs
+ * `${timestamp}${body}` with ECDSA-SHA256 using the public key from
+ * their signed-webhook setup page. Signature is base64 in the
+ * `X-Twilio-Email-Event-Webhook-Signature` header.
+ */
+export declare function verifySendgridSignature(input: SendgridSignatureInput): SignatureVerification;
+// =============================================================================
+// Mailgun
+// =============================================================================
+export declare interface MailgunSignatureInput {
+  timestamp: string
+  token: string
+  signature: string
+  signingKey: string
+  toleranceSeconds?: number
+}
+// =============================================================================
+// Postmark
+// =============================================================================
+export declare interface PostmarkAuthInput {
+  authorizationHeader: string | null | undefined
+  expectedUsername: string
+  expectedPassword: string
+  sourceIp?: string
+  ipAllowlist?: ReadonlyArray<string>
+}
+// =============================================================================
+// SES (via SNS)
+// =============================================================================
+export declare interface SesSnsSignatureInput {
+  message: {
+    Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation'
+    MessageId: string
+    TopicArn: string
+    Subject?: string
+    Message: string
+    Timestamp: string
+    SignatureVersion: string
+    Signature: string
+    SigningCertURL: string
+    Token?: string
+    SubscribeURL?: string
+    [key: string]: unknown
+  }
+  fetchCert?: (url: string) => Promise<string>
+  certUrlHostAllowlist?: RegExp
+}
+// =============================================================================
+// SendGrid
+// =============================================================================
+export declare interface SendgridSignatureInput {
+  body: string
+  signature: string | null | undefined
+  timestamp: string | null | undefined
+  publicKeyPem: string
+  toleranceSeconds?: number
+}
+export type SignatureVerification = | { ok: true }
+  | { ok: false, reason: 'missing-config' | 'missing-signature' | 'bad-signature' | 'expired' | 'untrusted-cert-url' | 'cert-fetch-failed' }

package/dist/webhook-signatures.js

@@ -0,0 +1,148 @@
+import { createHmac, createVerify, timingSafeEqual } from "node:crypto";
+import { Buffer } from "node:buffer";
+export function verifyMailgunSignature(input) {
+  if (!input.signingKey)
+    return { ok: !1, reason: "missing-config" };
+  if (!input.timestamp || !input.token || !input.signature)
+    return { ok: !1, reason: "missing-signature" };
+  const tolerance = input.toleranceSeconds ?? 300, ts = Number(input.timestamp);
+  if (!Number.isFinite(ts))
+    return { ok: !1, reason: "bad-signature" };
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - ts) > tolerance)
+    return { ok: !1, reason: "expired" };
+  const expected = createHmac("sha256", input.signingKey).update(`${input.timestamp}${input.token}`).digest("hex");
+  let provided;
+  try {
+    provided = Buffer.from(input.signature, "hex");
+  } catch {
+    return { ok: !1, reason: "bad-signature" };
+  }
+  const expectedBuf = Buffer.from(expected, "hex");
+  if (provided.length !== expectedBuf.length)
+    return { ok: !1, reason: "bad-signature" };
+  if (!timingSafeEqual(provided, expectedBuf))
+    return { ok: !1, reason: "bad-signature" };
+  return { ok: !0 };
+}
+export function verifyPostmarkAuth(input) {
+  if (!input.expectedUsername || !input.expectedPassword)
+    return { ok: !1, reason: "missing-config" };
+  if (!input.authorizationHeader || !input.authorizationHeader.startsWith("Basic "))
+    return { ok: !1, reason: "missing-signature" };
+  let decoded;
+  try {
+    decoded = Buffer.from(input.authorizationHeader.slice(6), "base64").toString("utf8");
+  } catch {
+    return { ok: !1, reason: "bad-signature" };
+  }
+  const [user, pass] = decoded.split(":");
+  if (!user || pass === void 0)
+    return { ok: !1, reason: "bad-signature" };
+  const userMatch = safeStringEquals(user, input.expectedUsername), passMatch = safeStringEquals(pass, input.expectedPassword);
+  if (!userMatch || !passMatch)
+    return { ok: !1, reason: "bad-signature" };
+  if (input.ipAllowlist && input.ipAllowlist.length > 0) {
+    if (!input.sourceIp || !input.ipAllowlist.includes(input.sourceIp))
+      return { ok: !1, reason: "bad-signature" };
+  }
+  return { ok: !0 };
+}
+function safeStringEquals(a, b) {
+  const aBuf = Buffer.from(a, "utf8"), bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) {
+    const dummy = Buffer.alloc(Math.max(aBuf.length, bBuf.length));
+    timingSafeEqual(dummy, dummy);
+    return !1;
+  }
+  return timingSafeEqual(aBuf, bBuf);
+}
+const DEFAULT_SNS_HOST_ALLOWLIST = /^sns\.[a-z0-9-]+\.amazonaws\.com$/;
+async function defaultCertFetcher(url) {
+  const res = await fetch(url, { redirect: "error" });
+  if (!res.ok)
+    throw Error(`SNS cert fetch returned ${res.status}`);
+  return await res.text();
+}
+export async function verifySesSnsSignature(input) {
+  const msg = input.message;
+  if (!msg || !msg.Signature || !msg.SigningCertURL)
+    return { ok: !1, reason: "missing-signature" };
+  const allowlist = input.certUrlHostAllowlist ?? DEFAULT_SNS_HOST_ALLOWLIST;
+  let certUrl;
+  try {
+    certUrl = new URL(msg.SigningCertURL);
+  } catch {
+    return { ok: !1, reason: "untrusted-cert-url" };
+  }
+  if (certUrl.protocol !== "https:")
+    return { ok: !1, reason: "untrusted-cert-url" };
+  if (!allowlist.test(certUrl.host))
+    return { ok: !1, reason: "untrusted-cert-url" };
+  let certPem;
+  try {
+    certPem = await (input.fetchCert ?? defaultCertFetcher)(msg.SigningCertURL);
+  } catch {
+    return { ok: !1, reason: "cert-fetch-failed" };
+  }
+  const canonical = canonicalSnsString(msg);
+  if (!canonical)
+    return { ok: !1, reason: "bad-signature" };
+  let sigBuf;
+  try {
+    sigBuf = Buffer.from(msg.Signature, "base64");
+  } catch {
+    return { ok: !1, reason: "bad-signature" };
+  }
+  const algo = msg.SignatureVersion === "2" ? "SHA256" : "SHA1", verifier = createVerify(`RSA-${algo}`);
+  verifier.update(canonical, "utf8");
+  return verifier.verify(certPem, sigBuf) ? { ok: !0 } : { ok: !1, reason: "bad-signature" };
+}
+function canonicalSnsString(msg) {
+  const fields = [];
+  if (msg.Type === "Notification") {
+    fields.push("Message", msg.Message);
+    fields.push("MessageId", msg.MessageId);
+    if (msg.Subject !== void 0)
+      fields.push("Subject", msg.Subject);
+    fields.push("Timestamp", msg.Timestamp);
+    fields.push("TopicArn", msg.TopicArn);
+    fields.push("Type", msg.Type);
+  } else if (msg.Type === "SubscriptionConfirmation" || msg.Type === "UnsubscribeConfirmation") {
+    fields.push("Message", msg.Message);
+    fields.push("MessageId", msg.MessageId);
+    if (!msg.SubscribeURL || !msg.Token)
+      return null;
+    fields.push("SubscribeURL", msg.SubscribeURL);
+    fields.push("Timestamp", msg.Timestamp);
+    fields.push("Token", msg.Token);
+    fields.push("TopicArn", msg.TopicArn);
+    fields.push("Type", msg.Type);
+  } else
+    return null;
+  let out = "";
+  for (const f of fields)
+    out += `${f}
+`;
+  return out;
+}
+export function verifySendgridSignature(input) {
+  if (!input.publicKeyPem)
+    return { ok: !1, reason: "missing-config" };
+  if (!input.signature || !input.timestamp)
+    return { ok: !1, reason: "missing-signature" };
+  const tolerance = input.toleranceSeconds ?? 300, ts = Number(input.timestamp);
+  if (!Number.isFinite(ts))
+    return { ok: !1, reason: "bad-signature" };
+  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > tolerance)
+    return { ok: !1, reason: "expired" };
+  let sigBuf;
+  try {
+    sigBuf = Buffer.from(input.signature, "base64");
+  } catch {
+    return { ok: !1, reason: "bad-signature" };
+  }
+  const verifier = createVerify("SHA256");
+  verifier.update(`${input.timestamp}${input.body}`, "utf8");
+  return verifier.verify(input.publicKeyPem, sigBuf) ? { ok: !0 } : { ok: !1, reason: "bad-signature" };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/email",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "The Stacks Email integration. Painlessly create & manage your inboxes, templates, and send emails.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,10 +58,10 @@
     "@stacksjs/ts-cloud": "^0.7.17"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.88",
-    "@stacksjs/config": "0.70.88",
+    "@stacksjs/cli": "0.70.91",
+    "@stacksjs/config": "0.70.91",
     "better-dx": "^0.2.16",
-    "@stacksjs/error-handling": "0.70.88",
-    "@stacksjs/types": "0.70.88"
+    "@stacksjs/error-handling": "0.70.91",
+    "@stacksjs/types": "0.70.91"
   }
 }