@stacksjs/email 0.70.87 → 0.70.90

package/dist/unsubscribe.js

@@ -0,0 +1,65 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import process from "node:process";
+import { Buffer } from "node:buffer";
+const DEFAULT_TTL_SECONDS = 2592000, DEFAULT_ROUTE = "/_stacks/email/unsubscribe";
+function getAppKey() {
+  const k = process.env.APP_KEY;
+  if (!k || k.length < 16) {
+    if (process.env.APP_ENV === "production" || process.env.NODE_ENV === "production")
+      throw Error("[email/unsubscribe] APP_KEY is missing or too short (need \u226516 chars). Cannot sign unsubscribe URL.");
+  }
+  return k || "stacks-default-key-dev-only-do-not-use-prod";
+}
+function b64UrlEncode(buf) {
+  return buf.toString("base64url");
+}
+function b64UrlDecode(s) {
+  return Buffer.from(s, "base64url");
+}
+export function createUnsubscribeToken(email, ttlSeconds = DEFAULT_TTL_SECONDS) {
+  if (!email)
+    throw Error("[email/unsubscribe] email is required");
+  const exp = Math.floor(Date.now() / 1000) + Math.floor(ttlSeconds), claims = {
+    email: String(email).trim().toLowerCase(),
+    exp,
+    iss: "stacks"
+  }, payload = b64UrlEncode(Buffer.from(JSON.stringify(claims))), sig = b64UrlEncode(createHmac("sha256", getAppKey()).update(payload).digest());
+  return `${payload}.${sig}`;
+}
+export function verifyUnsubscribeToken(token) {
+  if (typeof token !== "string")
+    return { valid: !1, reason: "malformed" };
+  const parts = token.split(".");
+  if (parts.length !== 2)
+    return { valid: !1, reason: "malformed" };
+  const [payload, sig] = parts, expectedSig = createHmac("sha256", getAppKey()).update(payload).digest();
+  let provided;
+  try {
+    provided = b64UrlDecode(sig);
+  } catch {
+    return { valid: !1, reason: "malformed" };
+  }
+  if (provided.length !== expectedSig.length || !timingSafeEqual(provided, expectedSig))
+    return { valid: !1, reason: "bad_signature" };
+  let claims;
+  try {
+    claims = JSON.parse(b64UrlDecode(payload).toString("utf8"));
+  } catch {
+    return { valid: !1, reason: "malformed" };
+  }
+  if (typeof claims.exp !== "number" || Math.floor(Date.now() / 1000) >= claims.exp)
+    return { valid: !1, reason: "expired" };
+  if (!claims.email || typeof claims.email !== "string")
+    return { valid: !1, reason: "malformed" };
+  return { valid: !0, email: claims.email };
+}
+export function buildUnsubscribeUrl(email, ttlSeconds, options = {}) {
+  const token = createUnsubscribeToken(email, ttlSeconds), base = (options.baseUrl || process.env.APP_URL || "http://localhost").replace(/\/$/, ""), route = (options.routePrefix || DEFAULT_ROUTE).replace(/\/$/, "");
+  return `${base}${route}/${token}`;
+}
+export function buildListUnsubscribeHeaders(email, ttlSeconds, options) {
+  return {
+    "List-Unsubscribe": `<${buildUnsubscribeUrl(email, ttlSeconds, options)}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  };
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,3 @@
+import { notification } from '@stacksjs/config';
+export declare const email: typeof notification.email;
+export default email;

package/dist/utils/config.js

@@ -0,0 +1,3 @@
+import { notification } from "@stacksjs/config";
+export const email = notification.email;
+export default email;

package/dist/validation.js

@@ -0,0 +1,22 @@
+export const ENVELOPE_ADDRESS = /^[^\s<>"\\\r\n\t]+@[^\s<>"\\\r\n\t]+$/;
+export function assertEnvelopeAddress(addr, role) {
+  if (typeof addr !== "string" || !ENVELOPE_ADDRESS.test(addr))
+    throw Error(`Email ${role} address is malformed or contains forbidden characters: ${JSON.stringify(addr)}`);
+}
+export function assertHeaderSafeSubject(subject) {
+  if (/[\r\n]/.test(subject))
+    throw Error("Email subject contains forbidden line break characters (CR/LF)");
+}
+export function filterStringHeaders(headers) {
+  if (!headers)
+    return;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== "string")
+      continue;
+    if (/[\r\n]/.test(k) || /[\r\n]/.test(v))
+      continue;
+    out[k] = v;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}

package/dist/webhook-dedup.js

@@ -0,0 +1,33 @@
+import { db } from "@stacksjs/database";
+let warnedAboutMissingTable = !1;
+function warnOnceAboutMissingTable() {
+  if (warnedAboutMissingTable)
+    return;
+  warnedAboutMissingTable = !0;
+  console.warn("[email/webhook-dedup] email_webhook_events table missing \u2014 webhook idempotency NOT enforced. " + "Providers may double-deliver retries; run migrations to enable dedup.");
+}
+function isMissingTableError(err) {
+  const msg = err?.message ?? "";
+  return msg.includes("no such table") || msg.includes("doesn't exist");
+}
+export async function recordWebhookEventOrSkip(provider, eventId) {
+  if (!eventId)
+    return !0;
+  try {
+    await db.insertInto("email_webhook_events").values({
+      provider,
+      event_id: eventId,
+      processed_at: new Date().toISOString().slice(0, 19).replace("T", " ")
+    }).execute();
+    return !0;
+  } catch (err) {
+    if (isMissingTableError(err)) {
+      warnOnceAboutMissingTable();
+      return !0;
+    }
+    const msg = err?.message ?? "";
+    if (msg.includes("UNIQUE constraint") || msg.includes("Duplicate entry"))
+      return !1;
+    throw err;
+  }
+}

package/dist/webhook-events.js

@@ -0,0 +1,37 @@
+async function emit(event, payload) {
+  try {
+    const mod = await import("@stacksjs/events").catch(() => null);
+    if (!mod)
+      return;
+    const dispatch = mod.dispatch;
+    if (typeof dispatch !== "function")
+      return;
+    dispatch(event, payload);
+  } catch {}
+}
+export async function emitEmailBounceHard(payload) {
+  await emit("email:bounce-hard", payload);
+  await emit("email:bounce", payload);
+}
+export async function emitEmailBounceSoft(payload) {
+  await emit("email:bounce-soft", payload);
+  await emit("email:bounce", payload);
+}
+export async function emitEmailComplaint(payload) {
+  await emit("email:complaint", payload);
+}
+export async function emitEmailUnsubscribe(payload) {
+  await emit("email:unsubscribe", payload);
+}
+export function suppressionTypeFor(classification) {
+  switch (classification) {
+    case "bounce-hard":
+      return "bounce";
+    case "complaint":
+      return "complaint";
+    case "unsubscribe":
+      return "unsubscribe";
+    default:
+      return null;
+  }
+}

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.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.87",
+  "version": "0.70.90",
   "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.87",
-    "@stacksjs/config": "0.70.87",
+    "@stacksjs/cli": "0.70.90",
+    "@stacksjs/config": "0.70.90",
     "better-dx": "^0.2.16",
-    "@stacksjs/error-handling": "0.70.87",
-    "@stacksjs/types": "0.70.87"
+    "@stacksjs/error-handling": "0.70.90",
+    "@stacksjs/types": "0.70.90"
   }
 }