@iskra-bun/mailer-kit 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,23 +1,35 @@
 import {
   SmtpEmailAdapter
-} from "./chunk-4Y2FQY2L.js";
+} from "./chunk-VRF3QYGZ.js";
 import {
   SendGridEmailAdapter
-} from "./chunk-4256VN6L.js";
+} from "./chunk-U4ZHXPGW.js";
 import {
   MailgunEmailAdapter
-} from "./chunk-P5HWUNVS.js";
+} from "./chunk-4OJHFX3J.js";
 import {
   SesEmailAdapter
-} from "./chunk-H6SSV4G4.js";
+} from "./chunk-IACNO3YI.js";
+import {
+  checkRecipients,
+  checkReplyTo
+} from "./chunk-URXCRWND.js";
 
 // src/mock.ts
 var MockEmailAdapter = class {
-  async send(_message) {
+  async send(message) {
+    checkRecipients(message.to);
+    checkRecipients(message.cc, "cc recipient");
+    checkRecipients(message.bcc, "bcc recipient");
+    checkReplyTo(message.replyTo);
     return { messageId: `mock-${Date.now()}`, success: true };
   }
   async sendTemplate(name, to, data) {
-    return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });
+    return this.send({
+      to,
+      subject: `Template: ${name}`,
+      html: `Template ${name} with data: ${JSON.stringify(data)}`
+    });
   }
 };
 
@@ -27,19 +39,19 @@ async function createEmailAdapter(config) {
     case "mock":
       return new MockEmailAdapter();
     case "smtp": {
-      const { SmtpEmailAdapter: SmtpEmailAdapter2 } = await import("./smtp-GZ4DZMCQ.js");
+      const { SmtpEmailAdapter: SmtpEmailAdapter2 } = await import("./smtp-J33QQBJ7.js");
       return new SmtpEmailAdapter2(config);
     }
     case "sendgrid": {
-      const { SendGridEmailAdapter: SendGridEmailAdapter2 } = await import("./sendgrid-EYSREU2M.js");
+      const { SendGridEmailAdapter: SendGridEmailAdapter2 } = await import("./sendgrid-T6ZZERVV.js");
       return new SendGridEmailAdapter2(config);
     }
     case "mailgun": {
-      const { MailgunEmailAdapter: MailgunEmailAdapter2 } = await import("./mailgun-CKVSFBJE.js");
+      const { MailgunEmailAdapter: MailgunEmailAdapter2 } = await import("./mailgun-4CTSFUTK.js");
       return new MailgunEmailAdapter2(config);
     }
     case "ses": {
-      const { SesEmailAdapter: SesEmailAdapter2 } = await import("./ses-KGJG5IB5.js");
+      const { SesEmailAdapter: SesEmailAdapter2 } = await import("./ses-WL4MNF4F.js");
       return new SesEmailAdapter2(config);
     }
     default:
@@ -52,6 +64,8 @@ export {
   SendGridEmailAdapter,
   SesEmailAdapter,
   SmtpEmailAdapter,
+  checkRecipients,
+  checkReplyTo,
   createEmailAdapter
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mock.ts","../src/factory.ts"],"sourcesContent":["import type { EmailAdapter, EmailMessage, TemplateData } from \"./types\";\n\n/**\n * In-memory email adapter used for tests and local development.\n * It performs no network I/O and stays silent (no stdout) so it is\n * safe to use inside library code and background workers.\n */\nexport class MockEmailAdapter implements EmailAdapter {\n    async send(_message: EmailMessage) {\n        return { messageId: `mock-${Date.now()}`, success: true };\n    }\n\n    async sendTemplate(name: string, to: string | string[], data: TemplateData) {\n        return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });\n    }\n}\n","import type { EmailAdapter, EmailConfig } from \"./types\";\nimport { MockEmailAdapter } from \"./mock\";\n\n/**\n * Builds the email adapter for the given provider. Providers are loaded\n * lazily via dynamic `import()` so an app only pays for (and only needs\n * installed) the SDK of the provider it actually uses.\n */\nexport async function createEmailAdapter(config: EmailConfig): Promise<EmailAdapter> {\n    switch (config.provider) {\n        case \"mock\":\n            return new MockEmailAdapter();\n        case \"smtp\": {\n            const { SmtpEmailAdapter } = await import(\"./providers/smtp\");\n            return new SmtpEmailAdapter(config);\n        }\n        case \"sendgrid\": {\n            const { SendGridEmailAdapter } = await import(\"./providers/sendgrid\");\n            return new SendGridEmailAdapter(config);\n        }\n        case \"mailgun\": {\n            const { MailgunEmailAdapter } = await import(\"./providers/mailgun\");\n            return new MailgunEmailAdapter(config);\n        }\n        case \"ses\": {\n            const { SesEmailAdapter } = await import(\"./providers/ses\");\n            return new SesEmailAdapter(config);\n        }\n        default:\n            throw new Error(`Provider ${config.provider} not implemented`);\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;AAOO,IAAM,mBAAN,MAA+C;AAAA,EAClD,MAAM,KAAK,UAAwB;AAC/B,WAAO,EAAE,WAAW,QAAQ,KAAK,IAAI,CAAC,IAAI,SAAS,KAAK;AAAA,EAC5D;AAAA,EAEA,MAAM,aAAa,MAAc,IAAuB,MAAoB;AACxE,WAAO,KAAK,KAAK,EAAE,IAAI,SAAS,aAAa,IAAI,IAAI,MAAM,YAAY,IAAI,eAAe,KAAK,UAAU,IAAI,CAAC,GAAG,CAAC;AAAA,EACtH;AACJ;;;ACPA,eAAsB,mBAAmB,QAA4C;AACjF,UAAQ,OAAO,UAAU;AAAA,IACrB,KAAK;AACD,aAAO,IAAI,iBAAiB;AAAA,IAChC,KAAK,QAAQ;AACT,YAAM,EAAE,kBAAAA,kBAAiB,IAAI,MAAM,OAAO,oBAAkB;AAC5D,aAAO,IAAIA,kBAAiB,MAAM;AAAA,IACtC;AAAA,IACA,KAAK,YAAY;AACb,YAAM,EAAE,sBAAAC,sBAAqB,IAAI,MAAM,OAAO,wBAAsB;AACpE,aAAO,IAAIA,sBAAqB,MAAM;AAAA,IAC1C;AAAA,IACA,KAAK,WAAW;AACZ,YAAM,EAAE,qBAAAC,qBAAoB,IAAI,MAAM,OAAO,uBAAqB;AAClE,aAAO,IAAIA,qBAAoB,MAAM;AAAA,IACzC;AAAA,IACA,KAAK,OAAO;AACR,YAAM,EAAE,iBAAAC,iBAAgB,IAAI,MAAM,OAAO,mBAAiB;AAC1D,aAAO,IAAIA,iBAAgB,MAAM;AAAA,IACrC;AAAA,IACA;AACI,YAAM,IAAI,MAAM,YAAY,OAAO,QAAQ,kBAAkB;AAAA,EACrE;AACJ;","names":["SmtpEmailAdapter","SendGridEmailAdapter","MailgunEmailAdapter","SesEmailAdapter"]}
+{"version":3,"sources":["../src/mock.ts","../src/factory.ts"],"sourcesContent":["import type { EmailAdapter, EmailMessage, EmailRecipient, TemplateData } from './types';\nimport { checkRecipients, checkReplyTo } from './headers';\n\n/**\n * In-memory email adapter used for tests and local development.\n * It performs no network I/O and stays silent (no stdout) so it is\n * safe to use inside library code and background workers.\n */\nexport class MockEmailAdapter implements EmailAdapter {\n    async send(message: EmailMessage) {\n        // Checked like the real providers, so a test fails where production would.\n        checkRecipients(message.to);\n        checkRecipients(message.cc, 'cc recipient');\n        checkRecipients(message.bcc, 'bcc recipient');\n        checkReplyTo(message.replyTo);\n        return { messageId: `mock-${Date.now()}`, success: true };\n    }\n\n    async sendTemplate(name: string, to: EmailRecipient | EmailRecipient[], data: TemplateData) {\n        return this.send({\n            to,\n            subject: `Template: ${name}`,\n            html: `Template ${name} with data: ${JSON.stringify(data)}`,\n        });\n    }\n}\n","import type { EmailAdapter, EmailConfig } from './types';\nimport { MockEmailAdapter } from './mock';\n\n/**\n * Builds the email adapter for the given provider. Providers are loaded\n * lazily via dynamic `import()` so an app only pays for (and only needs\n * installed) the SDK of the provider it actually uses.\n */\nexport async function createEmailAdapter(config: EmailConfig): Promise<EmailAdapter> {\n    switch (config.provider) {\n        case 'mock':\n            return new MockEmailAdapter();\n        case 'smtp': {\n            const { SmtpEmailAdapter } = await import('./providers/smtp');\n            return new SmtpEmailAdapter(config);\n        }\n        case 'sendgrid': {\n            const { SendGridEmailAdapter } = await import('./providers/sendgrid');\n            return new SendGridEmailAdapter(config);\n        }\n        case 'mailgun': {\n            const { MailgunEmailAdapter } = await import('./providers/mailgun');\n            return new MailgunEmailAdapter(config);\n        }\n        case 'ses': {\n            const { SesEmailAdapter } = await import('./providers/ses');\n            return new SesEmailAdapter(config);\n        }\n        default:\n            throw new Error(`Provider ${config.provider} not implemented`);\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAQO,IAAM,mBAAN,MAA+C;AAAA,EAClD,MAAM,KAAK,SAAuB;AAE9B,oBAAgB,QAAQ,EAAE;AAC1B,oBAAgB,QAAQ,IAAI,cAAc;AAC1C,oBAAgB,QAAQ,KAAK,eAAe;AAC5C,iBAAa,QAAQ,OAAO;AAC5B,WAAO,EAAE,WAAW,QAAQ,KAAK,IAAI,CAAC,IAAI,SAAS,KAAK;AAAA,EAC5D;AAAA,EAEA,MAAM,aAAa,MAAc,IAAuC,MAAoB;AACxF,WAAO,KAAK,KAAK;AAAA,MACb;AAAA,MACA,SAAS,aAAa,IAAI;AAAA,MAC1B,MAAM,YAAY,IAAI,eAAe,KAAK,UAAU,IAAI,CAAC;AAAA,IAC7D,CAAC;AAAA,EACL;AACJ;;;ACjBA,eAAsB,mBAAmB,QAA4C;AACjF,UAAQ,OAAO,UAAU;AAAA,IACrB,KAAK;AACD,aAAO,IAAI,iBAAiB;AAAA,IAChC,KAAK,QAAQ;AACT,YAAM,EAAE,kBAAAA,kBAAiB,IAAI,MAAM,OAAO,oBAAkB;AAC5D,aAAO,IAAIA,kBAAiB,MAAM;AAAA,IACtC;AAAA,IACA,KAAK,YAAY;AACb,YAAM,EAAE,sBAAAC,sBAAqB,IAAI,MAAM,OAAO,wBAAsB;AACpE,aAAO,IAAIA,sBAAqB,MAAM;AAAA,IAC1C;AAAA,IACA,KAAK,WAAW;AACZ,YAAM,EAAE,qBAAAC,qBAAoB,IAAI,MAAM,OAAO,uBAAqB;AAClE,aAAO,IAAIA,qBAAoB,MAAM;AAAA,IACzC;AAAA,IACA,KAAK,OAAO;AACR,YAAM,EAAE,iBAAAC,iBAAgB,IAAI,MAAM,OAAO,mBAAiB;AAC1D,aAAO,IAAIA,iBAAgB,MAAM;AAAA,IACrC;AAAA,IACA;AACI,YAAM,IAAI,MAAM,YAAY,OAAO,QAAQ,kBAAkB;AAAA,EACrE;AACJ;","names":["SmtpEmailAdapter","SendGridEmailAdapter","MailgunEmailAdapter","SesEmailAdapter"]}

package/dist/mailgun-4CTSFUTK.js

@@ -0,0 +1,8 @@
+import {
+  MailgunEmailAdapter
+} from "./chunk-4OJHFX3J.js";
+import "./chunk-URXCRWND.js";
+export {
+  MailgunEmailAdapter
+};
+//# sourceMappingURL=mailgun-4CTSFUTK.js.map

package/dist/sendgrid-T6ZZERVV.js

@@ -0,0 +1,8 @@
+import {
+  SendGridEmailAdapter
+} from "./chunk-U4ZHXPGW.js";
+import "./chunk-URXCRWND.js";
+export {
+  SendGridEmailAdapter
+};
+//# sourceMappingURL=sendgrid-T6ZZERVV.js.map

package/dist/ses-WL4MNF4F.js

@@ -0,0 +1,8 @@
+import {
+  SesEmailAdapter
+} from "./chunk-IACNO3YI.js";
+import "./chunk-URXCRWND.js";
+export {
+  SesEmailAdapter
+};
+//# sourceMappingURL=ses-WL4MNF4F.js.map

package/dist/smtp-J33QQBJ7.js

@@ -0,0 +1,8 @@
+import {
+  SmtpEmailAdapter
+} from "./chunk-VRF3QYGZ.js";
+import "./chunk-URXCRWND.js";
+export {
+  SmtpEmailAdapter
+};
+//# sourceMappingURL=smtp-J33QQBJ7.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/mailer-kit",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "description": "Envio de correo de Iskra, agnostico del transporte, con adaptadores de SMTP, SendGrid, Mailgun y SES.",
     "keywords": [
         "iskra",
@@ -20,6 +20,9 @@
     },
     "homepage": "https://github.com/fearful/iskra/tree/main/packages/mailer-kit#readme",
     "bugs": "https://github.com/fearful/iskra/issues",
+    "engines": {
+        "bun": ">=1.3.0"
+    },
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",
@@ -47,10 +50,10 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.1",
+        "@iskra-bun/core": "^0.3.0",
         "@aws-sdk/client-sesv2": "^3.600.0",
         "@sendgrid/mail": "^8.1.0",
-        "nodemailer": "^6.9.1"
+        "nodemailer": "^10.0.10"
     },
     "devDependencies": {
         "@types/bun": "^1.3.5",

package/src/factory.ts

@@ -1,5 +1,5 @@
-import type { EmailAdapter, EmailConfig } from "./types";
-import { MockEmailAdapter } from "./mock";
+import type { EmailAdapter, EmailConfig } from './types';
+import { MockEmailAdapter } from './mock';
 
 /**
  * Builds the email adapter for the given provider. Providers are loaded
@@ -8,22 +8,22 @@ import { MockEmailAdapter } from "./mock";
  */
 export async function createEmailAdapter(config: EmailConfig): Promise<EmailAdapter> {
     switch (config.provider) {
-        case "mock":
+        case 'mock':
             return new MockEmailAdapter();
-        case "smtp": {
-            const { SmtpEmailAdapter } = await import("./providers/smtp");
+        case 'smtp': {
+            const { SmtpEmailAdapter } = await import('./providers/smtp');
             return new SmtpEmailAdapter(config);
         }
-        case "sendgrid": {
-            const { SendGridEmailAdapter } = await import("./providers/sendgrid");
+        case 'sendgrid': {
+            const { SendGridEmailAdapter } = await import('./providers/sendgrid');
             return new SendGridEmailAdapter(config);
         }
-        case "mailgun": {
-            const { MailgunEmailAdapter } = await import("./providers/mailgun");
+        case 'mailgun': {
+            const { MailgunEmailAdapter } = await import('./providers/mailgun');
             return new MailgunEmailAdapter(config);
         }
-        case "ses": {
-            const { SesEmailAdapter } = await import("./providers/ses");
+        case 'ses': {
+            const { SesEmailAdapter } = await import('./providers/ses');
             return new SesEmailAdapter(config);
         }
         default:

package/src/headers.ts

@@ -0,0 +1,112 @@
+import type { EmailAddress, EmailRecipient } from './types';
+
+/**
+ * Outbound custom mail headers callers may set on every provider. Anything
+ * else is rejected so a caller cannot spoof Sender / routing headers via the
+ * generic `headers` map. Reply-To is not one: `message.replyTo` sets it, with
+ * its address checked like a recipient's.
+ */
+export const ALLOWED_HEADERS = [
+    'in-reply-to',
+    'references',
+    'list-unsubscribe',
+    'list-unsubscribe-post',
+    'list-id',
+] as const;
+
+/**
+ * Truncate a header value at the first CR/LF. Anything after a line break is an
+ * injected header (or folded continuation) and must be dropped, not preserved.
+ */
+export const stripCrlf = (value: string): string => value.split(/[\r\n]/)[0] ?? '';
+
+/** The `headers` of a message, checked against `allowed` and without CR/LF. */
+export function checkHeaders(
+    headers: Record<string, string> | undefined,
+    allowed: readonly string[] = ALLOWED_HEADERS,
+): Record<string, string> | undefined {
+    if (!headers) return undefined;
+    const checked: Record<string, string> = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === 'reply-to') {
+            throw new Error(`Header "${key}" is not allowed: use message.replyTo`);
+        }
+        if (!allowed.includes(key.toLowerCase())) {
+            throw new Error(`Header "${key}" is not allowed`);
+        }
+        checked[key] = stripCrlf(value);
+    }
+    return checked;
+}
+
+/**
+ * What an address may not contain unquoted: whitespace and control characters,
+ * and what starts a display name, comment, group or list (`<>()[]\,;:"`).
+ * `a@evil.test:b@x.com` is a group that mails b@x.com only.
+ */
+const ADDRESS_SPECIALS = /[\s\p{Cc}<>()[\]\\,;:"]/u;
+
+/** A bare addr-spec: one `@`, no display name, brackets, separators, quotes or whitespace. */
+export function checkEmail(email: string): string {
+    const trimmed = typeof email === 'string' ? email.trim() : '';
+    const at = trimmed.indexOf('@');
+    if (at < 1 || at !== trimmed.lastIndexOf('@') || at === trimmed.length - 1 || ADDRESS_SPECIALS.test(trimmed)) {
+        throw new Error(`Invalid email address: ${JSON.stringify(email)}`);
+    }
+    return trimmed;
+}
+
+/** A display name on one line (CR/LF would start a new header). */
+export const cleanName = (name: string): string => name.replace(/[\r\n]+/g, ' ').trim();
+
+/**
+ * The recipients of a `to`/`cc`/`bcc`/`replyTo` field, one mailbox each. A
+ * string is a single bare address: one value such as
+ * `"bob@x.com <spy@evil.test>, y@x.com"` or `"list: spy@evil.test;"` mailed
+ * other people than the ones an allowlist checked. An object's address is
+ * checked the same way and its name may not hold control characters.
+ */
+export function checkRecipients(
+    value: EmailRecipient | EmailRecipient[] | undefined,
+    field = 'recipient',
+): EmailAddress[] {
+    // null too: an optional field often arrives as null from JSON.
+    if (value === undefined || value === null) return [];
+    return (Array.isArray(value) ? value : [value]).map((recipient) => {
+        if (typeof recipient === 'string') return { address: checkEmail(recipient) };
+        if (typeof recipient !== 'object' || recipient === null || typeof recipient.address !== 'string') {
+            throw new Error(`Invalid ${field}: expected an email address or { name, address }`);
+        }
+        const { name, address } = recipient;
+        if (name !== undefined && (typeof name !== 'string' || /\p{Cc}/u.test(name))) {
+            throw new Error(`Invalid ${field} name: control characters (CR/LF) are not allowed`);
+        }
+        return name ? { name, address: checkEmail(address) } : { address: checkEmail(address) };
+    });
+}
+
+/** `replyTo`, checked like the recipients: one address at most. */
+export function checkReplyTo(value: EmailRecipient | undefined): EmailAddress | undefined {
+    const list = checkRecipients(value, 'replyTo');
+    if (list.length > 1) throw new Error('Invalid replyTo: expected a single address');
+    return list[0];
+}
+
+/** A checked recipient as an RFC 5322 mailbox (see {@link formatAddress}). */
+export const formatRecipient = ({ name, address }: EmailAddress): string => formatAddress({ name, email: address });
+
+/**
+ * `from` as an RFC 5322 mailbox. A display name with special characters is
+ * quoted (with `"` and `\` escaped), or RFC 2047-encoded when it is not
+ * ASCII. Interpolated as is, a name such as `Ana" <ceo@bank.com>, "x` added a
+ * sender of the caller's choice.
+ */
+export function formatAddress(from: { name?: string; email: string }): string {
+    const email = checkEmail(from.email);
+    const name = from.name ? cleanName(from.name) : '';
+    if (!name) return email;
+    // Words of RFC 5322 atext need no quoting.
+    if (/^[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~ ]+$/.test(name)) return `${name} <${email}>`;
+    if (/^[\x20-\x7e]*$/.test(name)) return `"${name.replace(/(["\\])/g, '\\$1')}" <${email}>`;
+    return `=?UTF-8?B?${Buffer.from(name, 'utf8').toString('base64')}?= <${email}>`;
+}

package/src/index.ts

@@ -1,8 +1,9 @@
-export type { EmailConfig, EmailMessage, TemplateData, EmailAdapter } from "./types";
-export { MockEmailAdapter } from "./mock";
-export { createEmailAdapter } from "./factory";
-export { SmtpEmailAdapter } from "./providers/smtp";
-export { SendGridEmailAdapter } from "./providers/sendgrid";
-export { MailgunEmailAdapter } from "./providers/mailgun";
-export { SesEmailAdapter } from "./providers/ses";
-export type { SesClient, SesCommand, SesCommandFactory, SesAdapterDeps } from "./providers/ses";
+export type { EmailConfig, EmailMessage, EmailAddress, EmailRecipient, TemplateData, EmailAdapter } from './types';
+export { checkRecipients, checkReplyTo } from './headers';
+export { MockEmailAdapter } from './mock';
+export { createEmailAdapter } from './factory';
+export { SmtpEmailAdapter } from './providers/smtp';
+export { SendGridEmailAdapter } from './providers/sendgrid';
+export { MailgunEmailAdapter } from './providers/mailgun';
+export { SesEmailAdapter } from './providers/ses';
+export type { SesClient, SesCommand, SesCommandFactory, SesAdapterDeps } from './providers/ses';

package/src/mock.ts

@@ -1,4 +1,5 @@
-import type { EmailAdapter, EmailMessage, TemplateData } from "./types";
+import type { EmailAdapter, EmailMessage, EmailRecipient, TemplateData } from './types';
+import { checkRecipients, checkReplyTo } from './headers';
 
 /**
  * In-memory email adapter used for tests and local development.
@@ -6,11 +7,20 @@ import type { EmailAdapter, EmailMessage, TemplateData } from "./types";
  * safe to use inside library code and background workers.
  */
 export class MockEmailAdapter implements EmailAdapter {
-    async send(_message: EmailMessage) {
+    async send(message: EmailMessage) {
+        // Checked like the real providers, so a test fails where production would.
+        checkRecipients(message.to);
+        checkRecipients(message.cc, 'cc recipient');
+        checkRecipients(message.bcc, 'bcc recipient');
+        checkReplyTo(message.replyTo);
         return { messageId: `mock-${Date.now()}`, success: true };
     }
 
-    async sendTemplate(name: string, to: string | string[], data: TemplateData) {
-        return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });
+    async sendTemplate(name: string, to: EmailRecipient | EmailRecipient[], data: TemplateData) {
+        return this.send({
+            to,
+            subject: `Template: ${name}`,
+            html: `Template ${name} with data: ${JSON.stringify(data)}`,
+        });
     }
 }

package/src/providers/mailgun.ts

@@ -1,26 +1,16 @@
-import type { EmailAdapter, EmailMessage, EmailConfig, TemplateData } from "../types";
+import type { EmailAdapter, EmailMessage, EmailConfig, TemplateData } from '../types';
+import {
+    ALLOWED_HEADERS,
+    checkHeaders,
+    checkRecipients,
+    checkReplyTo,
+    formatAddress,
+    formatRecipient,
+    stripCrlf,
+} from '../headers';
 
-/**
- * Outbound custom mail headers callers are permitted to set. Anything outside
- * this set is rejected so a caller cannot spoof Reply-To / Sender / routing
- * headers via the generic `headers` map.
- */
-const ALLOWED_HEADERS = new Set([
-    "reply-to",
-    "in-reply-to",
-    "references",
-    "list-unsubscribe",
-    "list-unsubscribe-post",
-    "list-id",
-    "x-mailgun-variables",
-    "x-mailgun-tag",
-]);
-
-/**
- * Truncate a header value at the first CR/LF. Anything after a line break is an
- * injected header (or folded continuation) and must be dropped, not preserved.
- */
-const stripCrlf = (value: string): string => value.split(/[\r\n]/)[0] ?? "";
+/** Mailgun's own headers, on top of the ones every provider allows. */
+const MAILGUN_HEADERS = [...ALLOWED_HEADERS, 'x-mailgun-variables', 'x-mailgun-tag'];
 
 export class MailgunEmailAdapter implements EmailAdapter {
     private apiKey: string;
@@ -29,57 +19,56 @@ export class MailgunEmailAdapter implements EmailAdapter {
     private defaultFrom?: { name?: string; email: string };
 
     constructor(config: EmailConfig) {
-        if (!config.apiKey) throw new Error("Mailgun requires apiKey");
-        if (!config.domain) throw new Error("Mailgun requires domain");
+        if (!config.apiKey) throw new Error('Mailgun requires apiKey');
+        if (!config.domain) throw new Error('Mailgun requires domain');
 
         this.apiKey = config.apiKey;
         this.domain = config.domain;
-        this.baseUrl = config.baseUrl || "https://api.mailgun.net/v3";
+        this.baseUrl = config.baseUrl || 'https://api.mailgun.net/v3';
         this.defaultFrom = config.from;
     }
 
     async send(message: EmailMessage): Promise<{ messageId: string; success: boolean }> {
+        const from = message.from || this.defaultFrom;
+        if (!from) throw new Error('From address required');
+
         const form = new FormData();
+        form.append('from', formatAddress(from));
 
-        const from = message.from || this.defaultFrom;
-        if (from) {
-            form.append("from", from.name ? `${from.name} <${from.email}>` : from.email);
-        }
+        // Mailgun parses each field as an address list and builds the headers
+        // itself: every value is one checked mailbox, and nothing carries CR/LF.
+        const list = (field: EmailMessage['to'] | undefined, label?: string) =>
+            checkRecipients(field, label).map(formatRecipient).join(',');
+        const cc = list(message.cc, 'cc recipient');
+        const bcc = list(message.bcc, 'bcc recipient');
+        const replyTo = checkReplyTo(message.replyTo);
 
-        const to = Array.isArray(message.to) ? message.to.join(",") : message.to;
-        form.append("to", to);
-        form.append("subject", message.subject);
+        form.append('to', list(message.to));
+        form.append('subject', stripCrlf(message.subject));
 
-        if (message.text) form.append("text", message.text);
-        if (message.html) form.append("html", message.html);
-        if (message.cc) form.append("cc", Array.isArray(message.cc) ? message.cc.join(",") : message.cc);
-        if (message.bcc) form.append("bcc", Array.isArray(message.bcc) ? message.bcc.join(",") : message.bcc);
-        if (message.replyTo) form.append("h:Reply-To", message.replyTo);
+        if (message.text) form.append('text', message.text);
+        if (message.html) form.append('html', message.html);
+        if (cc) form.append('cc', cc);
+        if (bcc) form.append('bcc', bcc);
+        if (replyTo) form.append('h:Reply-To', formatRecipient(replyTo));
 
-        if (message.headers) {
-            for (const [key, value] of Object.entries(message.headers)) {
-                if (!ALLOWED_HEADERS.has(key.toLowerCase())) {
-                    throw new Error(`Header "${key}" is not allowed`);
-                }
-                form.append(`h:${key}`, stripCrlf(value));
-            }
+        for (const [key, value] of Object.entries(checkHeaders(message.headers, MAILGUN_HEADERS) ?? {})) {
+            form.append(`h:${key}`, value);
         }
 
         if (message.attachments) {
             for (const att of message.attachments) {
-                const content = typeof att.content === "string"
-                    ? new TextEncoder().encode(att.content)
-                    : att.content;
+                const content = typeof att.content === 'string' ? new TextEncoder().encode(att.content) : att.content;
                 const bytes = new Uint8Array(content);
-                const blob = new Blob([bytes], { type: att.contentType || "application/octet-stream" });
-                form.append("attachment", blob, att.filename);
+                const blob = new Blob([bytes], { type: att.contentType || 'application/octet-stream' });
+                form.append('attachment', blob, att.filename);
             }
         }
 
         const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
-            method: "POST",
+            method: 'POST',
             headers: {
-                Authorization: "Basic " + btoa(`api:${this.apiKey}`),
+                Authorization: 'Basic ' + btoa(`api:${this.apiKey}`),
             },
             body: form,
         });
@@ -89,13 +78,17 @@ export class MailgunEmailAdapter implements EmailAdapter {
             throw new Error(`Mailgun API error (${response.status}): ${errorText}`);
         }
 
-        const result = await response.json() as { id: string; message: string };
+        const result = (await response.json()) as { id: string; message: string };
         return { messageId: result.id, success: true };
     }
 
-    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+    async sendTemplate(
+        _templateName: string,
+        _to: string | string[],
+        _data: TemplateData,
+    ): Promise<{ messageId: string; success: boolean }> {
         // No template engine is implemented yet; fail loudly rather than
         // silently sending a placeholder that looks like a real send.
-        throw new Error("sendTemplate not supported by mailgun");
+        throw new Error('sendTemplate not supported by mailgun');
     }
 }

package/src/providers/sendgrid.ts

@@ -1,40 +1,68 @@
-import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from "../types";
-import sgMail from "@sendgrid/mail";
+import type { EmailAdapter, EmailAddress, EmailConfig, EmailMessage, TemplateData } from '../types';
+import { MailService } from '@sendgrid/mail';
+import { checkEmail, checkHeaders, checkRecipients, checkReplyTo, cleanName } from '../headers';
+
+/** SendGrid's form of a checked recipient (it parses a string as `Name <address>`). */
+const toSendGrid = ({ name, address }: EmailAddress) => (name ? { email: address, name } : address);
+
+/** The mail object MailService.send() takes (typed by @sendgrid/helpers, not a direct dependency). */
+type SendGridMail = Extract<Parameters<MailService['send']>[0], { from: unknown }>;
 
 export class SendGridEmailAdapter implements EmailAdapter {
+    /**
+     * A client per adapter: the package's default export is a process-wide
+     * singleton, so the last adapter created set the API key for all of them
+     * (one tenant's mail sent with another tenant's account).
+     */
+    private readonly client = new MailService();
+
     constructor(private config: EmailConfig) {
-        if (!config.apiKey) throw new Error("SendGrid API Key required");
-        sgMail.setApiKey(config.apiKey);
+        if (!config.apiKey) throw new Error('SendGrid API Key required');
+        this.client.setApiKey(config.apiKey);
     }
 
     async send(message: EmailMessage) {
         const from = message.from || this.config.from;
-        if (!from) throw new Error("From address required");
+        if (!from) throw new Error('From address required');
+        const cc = checkRecipients(message.cc, 'cc recipient').map(toSendGrid);
+        const bcc = checkRecipients(message.bcc, 'bcc recipient').map(toSendGrid);
+        const replyTo = checkReplyTo(message.replyTo);
 
         const msg = {
-            to: message.to,
-            from: from.name ? { email: from.email, name: from.name } : from.email,
+            to: checkRecipients(message.to).map(toSendGrid),
+            from: from.name ? { email: checkEmail(from.email), name: cleanName(from.name) } : checkEmail(from.email),
             subject: message.subject,
             text: message.text,
             html: message.html,
-            cc: message.cc as any,
-            bcc: message.bcc as any,
-            replyTo: message.replyTo,
-            attachments: message.attachments?.map(a => ({
+            cc: cc.length > 0 ? cc : undefined,
+            bcc: bcc.length > 0 ? bcc : undefined,
+            replyTo: replyTo && toSendGrid(replyTo),
+            attachments: message.attachments?.map((a) => ({
                 filename: a.filename,
-                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content).toString("base64"),
+                // SendGrid takes base64; a string is text, as with the other
+                // providers (it was sent as is and arrived corrupted).
+                content: Buffer.from(
+                    typeof a.content === 'string' ? Buffer.from(a.content, 'utf8') : a.content,
+                ).toString('base64'),
                 type: a.contentType,
-                disposition: "attachment"
-            }))
-        } as any;
+                disposition: 'attachment',
+            })),
+            headers: checkHeaders(message.headers),
+            // SendGrid's type wants text or html statically present; here both
+            // are optional, and SendGrid's API rejects a mail with neither.
+        } as SendGridMail;
 
-        const [response] = await sgMail.send(msg);
-        return { messageId: response.headers["x-message-id"] as string, success: true };
+        const [response] = await this.client.send(msg);
+        return { messageId: response.headers['x-message-id'] as string, success: true };
     }
 
-    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+    async sendTemplate(
+        _templateName: string,
+        _to: string | string[],
+        _data: TemplateData,
+    ): Promise<{ messageId: string; success: boolean }> {
         // No template engine is implemented yet; fail loudly rather than
         // silently sending a placeholder body that looks like a real send.
-        throw new Error("sendTemplate not supported by sendgrid");
+        throw new Error('sendTemplate not supported by sendgrid');
     }
 }