@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/mail/src/inbound/headers.mjs

@@ -0,0 +1,143 @@
+import { fail } from '../core/errors.mjs';
+import { parseAddress } from '../core/validation.mjs';
+import { base64, decode, quotedPrintable, record } from './bytes.mjs';
+const singleton = new Set(['message-id', 'in-reply-to', 'references', 'subject', 'from', 'to', 'content-type', 'content-transfer-encoding', 'content-disposition', 'content-id']);
+export function headerText(value, empty = true) {
+  if (typeof value !== 'string' || (!empty && !value) || /[\x00-\x08\x0a-\x1f\x7f]/.test(value)) fail('invalid_inbound_header');
+  return value;
+}
+export function unfold(value) {
+  if (typeof value !== 'string') fail('invalid_inbound_header');
+  return headerText(value.replace(/\r?\n[ \t]+/g, ' ')).trim();
+}
+export function parseHeaders(value) {
+  if (typeof value !== 'string' || /\r(?!\n)/.test(value)) fail('invalid_inbound_headers');
+  const map = new Map(); let previous = null;
+  for (const line of value.split(/\r?\n/)) {
+    if (!line) { previous = null; continue; }
+    if (/^[ \t]/.test(line)) {
+      if (!previous) fail('invalid_inbound_headers');
+      map.set(previous, `${map.get(previous)} ${headerText(line.trim())}`); continue;
+    }
+    const match = /^([!#$%&'*+.^_`|~0-9A-Za-z-]+):[ \t]*(.*)$/.exec(line);
+    if (!match) fail('invalid_inbound_headers');
+    previous = match[1].toLowerCase();
+    if (map.has(previous) && singleton.has(previous)) fail('duplicate_inbound_header');
+    const text = headerText(match[2].trim());
+    map.set(previous, map.has(previous) ? `${map.get(previous)}, ${text}` : text);
+  }
+  return map;
+}
+export function objectHeaders(value = {}) {
+  record(value); const map = new Map();
+  for (const [key, val] of Object.entries(value)) {
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(key) || map.has(key.toLowerCase())) fail('invalid_inbound_headers');
+    map.set(key.toLowerCase(), unfold(val));
+  }
+  return map;
+}
+export function words(value) {
+  // RFC 2047 suppresses whitespace between adjacent encoded words.
+  const source = value.replace(/(\?=)[ \t]+(?==\?)/g, '$1');
+  const result = source.replace(/=\?([^?\s]+)\?([bq])\?([^?]*)\?=/gi, (_, charset, encoding, content) => {
+    if (/[^\x21-\x7e]/.test(content)) fail('invalid_inbound_encoded_word');
+    return decode(encoding.toLowerCase() === 'b' ? base64(content) : quotedPrintable(content, true), charset);
+  });
+  if (/=\?/.test(result)) fail('invalid_inbound_encoded_word');
+  return headerText(result);
+}
+export function parameterized(value) {
+  headerText(value); let i = 0;
+  while (i < value.length && value[i] !== ';') i++;
+  const type = value.slice(0, i).trim().toLowerCase(); const params = new Map();
+  while (i < value.length) {
+    i++; while (/[ \t]/.test(value[i] ?? '') && i < value.length) i++;
+    const rest = value.slice(i); const name = /^([a-z0-9!#$%&'*+.^_`|~-]+)[ \t]*=[ \t]*/i.exec(rest);
+    if (!name) fail('invalid_inbound_mime');
+    i += name[0].length; let text = '';
+    if (value[i] === '"') {
+      i++; let closed = false;
+      while (i < value.length) {
+        const char = value[i++];
+        if (char === '"') { closed = true; break; }
+        if (char === '\\') { if (i >= value.length) fail('invalid_inbound_mime'); text += value[i++]; }
+        else text += char;
+      }
+      if (!closed) fail('invalid_inbound_mime');
+      while (i < value.length && /[ \t]/.test(value[i])) i++;
+      if (i < value.length && value[i] !== ';') fail('invalid_inbound_mime');
+    } else {
+      const start = i; while (i < value.length && value[i] !== ';') i++;
+      text = value.slice(start, i).trim();
+      if (!text || /[\s"\\]/.test(text)) fail('invalid_inbound_mime');
+    }
+    const key = name[1].toLowerCase();
+    if (params.has(key)) fail('invalid_inbound_mime'); params.set(key, text);
+  }
+  return { type, params };
+}
+function extended(value) {
+  const match = /^([^']+)'[^']*'(.*)$/.exec(value);
+  if (!match) fail('invalid_inbound_mime');
+  const bytes = []; const content = match[2];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '%') {
+      if (!/^[a-f0-9]{2}$/i.test(content.slice(i + 1, i + 3))) fail('invalid_inbound_mime');
+      bytes.push(parseInt(content.slice(i + 1, i + 3), 16)); i += 2;
+    } else { if (content.charCodeAt(i) > 127) fail('invalid_inbound_mime'); bytes.push(content.charCodeAt(i)); }
+  }
+  return decode(new Uint8Array(bytes), match[1]);
+}
+export function parameter(params, name) {
+  if (params.has(`${name}*`)) return headerText(extended(params.get(`${name}*`)));
+  const pieces = [...params.keys()].filter(key => key.startsWith(`${name}*`));
+  if (pieces.length) {
+    let joined = '', encoded = false;
+    for (let index = 0; index < pieces.length; index++) {
+      const key = `${name}*${index}`;
+      if (params.has(`${key}*`)) { if (params.has(key)) fail('invalid_inbound_mime'); encoded = true; joined += params.get(`${key}*`); }
+      else if (params.has(key)) joined += params.get(key);
+      else fail('invalid_inbound_mime');
+    }
+    return headerText(encoded ? extended(joined) : words(joined));
+  }
+  return params.has(name) ? words(params.get(name)) : null;
+}
+export function contentType(value = 'application/octet-stream') {
+  if (typeof value !== 'string' || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(value)) fail('invalid_inbound_content_type');
+  return value.toLowerCase();
+}
+export function contentId(value) {
+  if (value == null || value === '') return null;
+  headerText(value); const id = value.startsWith('<') && value.endsWith('>') ? value.slice(1, -1) : value;
+  if (!id || /[\s<>]/.test(id)) fail('invalid_inbound_content_id'); return id;
+}
+export function address(value) { return parseAddress(words(unfold(value))).email; }
+export function addresses(value) {
+  if (Array.isArray(value)) { if (!value.length) fail('invalid_inbound_recipients'); return value.map(address); }
+  const source = unfold(value); const parts = []; let part = '', quoted = false, angle = false, escape = false;
+  for (const char of source) {
+    if (escape) { part += char; escape = false; continue; }
+    if (char === '\\' && quoted) { part += char; escape = true; continue; }
+    if (char === '"') quoted = !quoted;
+    if (!quoted && char === '<') { if (angle) fail('invalid_inbound_recipients'); angle = true; }
+    if (!quoted && char === '>') { if (!angle) fail('invalid_inbound_recipients'); angle = false; }
+    if (char === ',' && !quoted && !angle) { parts.push(address(part)); part = ''; } else part += char;
+  }
+  if (quoted || angle || escape) fail('invalid_inbound_recipients');
+  parts.push(address(part)); return parts;
+}
+export function messageIds(value) {
+  if (value == null || value === '') return [];
+  const source = unfold(value); const ids = source.match(/<[^<>\s]+>/g) ?? [];
+  if (!ids.length || source.replace(/<[^<>\s]+>/g, '').trim()) fail('invalid_inbound_thread');
+  return ids;
+}
+export function metadata(headers, from, to, subject) {
+  const ids = messageIds(headers.get('message-id'));
+  if (ids.length > 1) fail('invalid_inbound_thread');
+  const reply = messageIds(headers.get('in-reply-to'));
+  return { messageId: ids[0] ?? null, from: address(from), to: addresses(to),
+    subject: words(unfold(subject ?? headers.get('subject') ?? '')),
+    inReplyTo: reply.length ? reply.join(' ') : null, references: messageIds(headers.get('references')) };
+}

package/modules/mail/src/inbound/index.mjs

@@ -0,0 +1,29 @@
+import { fail, MailValidationError } from '../core/errors.mjs';
+import { bounded, limitsFor, readStream, record } from './bytes.mjs';
+import { parseMime } from './mime.mjs';
+import { normalizeResend } from './resend.mjs';
+import { normalizeSendGrid } from './sendgrid.mjs';
+/** Trusted transport parser. Verify webhook bytes BEFORE calling or hydrating. */
+export async function normalizeInbound(input, limits) {
+  try {
+    record(input); limits = limitsFor(limits); let result;
+    switch (input.provider) {
+      case 'cloudflare': {
+        const message = input.message;
+        if (!message || !(message.headers instanceof Headers) || !Number.isSafeInteger(message.rawSize) || message.rawSize < 0) fail('invalid_inbound_message');
+        bounded(message.rawSize, limits.maxRawBytes, 'inbound_raw_limit');
+        const raw = await readStream(message.raw, limits.maxRawBytes);
+        if (raw.length !== message.rawSize) fail('inbound_raw_size_mismatch');
+        result = parseMime(raw, limits, { from: message.from, to: message.to }); break;
+      }
+      case 'sendgrid': result = normalizeSendGrid(input, limits); break;
+      case 'resend': result = await normalizeResend(input, limits); break;
+      default: fail('invalid_inbound_provider');
+    }
+    return { provider: input.provider, ...result };
+  } catch (error) {
+    if (error instanceof MailValidationError) throw error;
+    fail('invalid_inbound');
+  }
+}
+export { createResendAttachmentFetcher } from './resend-attachment.mjs';

package/modules/mail/src/inbound/mime.mjs

@@ -0,0 +1,36 @@
+import { fail } from '../core/errors.mjs';
+import { bodyBudget, bounded, decode, transfer, utf8 } from './bytes.mjs';
+import { contentId, contentType, headerText, metadata, parameter, parameterized } from './headers.mjs';
+import { entity, multipart } from './multipart.mjs';
+export function parseMime(bytes, limits, envelope) {
+  const root = entity(bytes); const budget = bodyBudget(limits);
+  const text = [], html = [], attachments = [];
+  function visit(part, depth = 0) {
+    if (depth > 30) fail('inbound_mime_depth');
+    const type = parameterized(part.headers.get('content-type') ?? 'text/plain');
+    contentType(type.type);
+    const disposition = parameterized(part.headers.get('content-disposition') ?? 'inline');
+    if (!['inline', 'attachment'].includes(disposition.type)) fail('invalid_inbound_disposition');
+    const filename = parameter(disposition.params, 'filename') ?? parameter(type.params, 'name');
+    const isAttachment = disposition.type === 'attachment' || filename !== null;
+    const encoding = part.headers.get('content-transfer-encoding');
+    if (type.type.startsWith('multipart/') && !isAttachment) {
+      if (encoding && !['7bit', '8bit', 'binary'].includes(encoding.toLowerCase())) fail('invalid_inbound_encoding');
+      for (const child of multipart(part.body, type.params.get('boundary'))) visit(entity(child), depth + 1);
+      return;
+    }
+    const decoded = transfer(part.body, encoding ?? '8bit');
+    if (!isAttachment && ['text/plain', 'text/html'].includes(type.type)) {
+      const value = decode(decoded, type.params.get('charset') ?? 'utf-8');
+      budget.body(value, decoded.length);
+      (type.type === 'text/plain' ? text : html).push(value);
+    } else {
+      budget.attachment(decoded);
+      attachments.push({ filename: headerText(filename ?? ''), contentType: type.type, content: decoded.slice(), contentId: contentId(part.headers.get('content-id')) });
+    }
+  }
+  visit(root);
+  const plain = text.length ? text.join('\n') : null, rich = html.length ? html.join('\n') : null;
+  bounded(utf8.encode(plain ?? '').length + utf8.encode(rich ?? '').length, limits.maxBodyBytes, 'inbound_body_limit');
+  return { ...metadata(root.headers, envelope?.from ?? root.headers.get('from'), envelope?.to ?? root.headers.get('to')), text: plain, html: rich, attachments };
+}

package/modules/mail/src/inbound/multipart.mjs

@@ -0,0 +1,27 @@
+import { fail } from '../core/errors.mjs';
+import { binary, decode } from './bytes.mjs';
+import { parseHeaders } from './headers.mjs';
+export function entity(bytes) {
+  const source = binary(bytes); const divider = /\r?\n\r?\n/.exec(source);
+  if (!divider) fail('invalid_inbound_mime');
+  return { headers: parseHeaders(decode(bytes.subarray(0, divider.index))), body: bytes.subarray(divider.index + divider[0].length) };
+}
+export function multipart(bytes, boundary) {
+  if (typeof boundary !== 'string' || !/^[0-9A-Za-z'()+_,\-./:=? ]{1,70}$/.test(boundary) || boundary.endsWith(' ')) fail('invalid_inbound_boundary');
+  const escaped = boundary.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const marker = new RegExp(`^--${escaped}(--)?[ \\t]*(?:\\r?\\n|$)`, 'gm');
+  const source = binary(bytes); const parts = []; let start = null, closed = false;
+  for (const match of source.matchAll(marker)) {
+    if (closed) fail('invalid_inbound_multipart');
+    if (start !== null) {
+      let end = match.index;
+      if (source[end - 1] === '\n') { end--; if (source[end - 1] === '\r') end--; }
+      if (end <= start) fail('invalid_inbound_multipart');
+      parts.push(bytes.subarray(start, end));
+    }
+    if (match[1]) { if (start === null) fail('invalid_inbound_multipart'); closed = true; }
+    else start = match.index + match[0].length;
+  }
+  if (!closed || !parts.length) fail('invalid_inbound_multipart');
+  return parts;
+}

package/modules/mail/src/inbound/resend-attachment.mjs

@@ -0,0 +1,43 @@
+import { fail, MailValidationError } from '../core/errors.mjs';
+import { validateConfig } from '../core/validation.mjs';
+import { decode, readStream } from './bytes.mjs';
+import { attachmentMetadata } from './resend.mjs';
+/** Call only after authenticating email.received and binding the hydrated email ID. */
+export function createResendAttachmentFetcher({ apiKey, maxAttachmentBytes }, dependencies = {}) {
+  validateConfig({ provider: 'resend', mode: 'production', apiKey }, dependencies);
+  if (!Number.isSafeInteger(maxAttachmentBytes) || maxAttachmentBytes <= 0) fail('invalid_inbound_limits');
+  const fetcher = dependencies.fetch ?? globalThis.fetch;
+  const clock = dependencies.clock ?? Date.now;
+  return async expected => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15_000);
+    try {
+      const item = attachmentMetadata(expected, expected.emailId);
+      if (item.size > maxAttachmentBytes) fail('inbound_attachment_limit');
+      // Fixed API origin, escaped identifiers, and manual redirects prevent credential forwarding.
+      const response = await fetcher(`https://api.resend.com/emails/receiving/${encodeURIComponent(item.emailId)}/attachments/${encodeURIComponent(item.id)}`, {
+        method: 'GET', headers: { authorization: `Bearer ${apiKey}`, accept: 'application/json' }, redirect: 'manual', signal: controller.signal,
+      });
+      if (response.status !== 200) fail('inbound_attachment_fetch_failed');
+      const data = JSON.parse(decode(await readStream(response.body, 65_536)));
+      const actual = attachmentMetadata(data, item.emailId);
+      for (const key of ['id', 'filename', 'content_type', 'content_disposition', 'content_id', 'size']) {
+        if (actual[key] !== item[key]) fail('inbound_attachment_metadata_mismatch');
+      }
+      const url = new URL(data.download_url);
+      // The documented provider CDN is the only accepted download origin.
+      if (url.origin !== 'https://inbound-cdn.resend.com' || url.username || url.password || url.hash ||
+          url.pathname !== `/${item.emailId}/attachments/${item.id}` || !Number.isFinite(Date.parse(data.expires_at)) || Date.parse(data.expires_at) <= clock()) fail('unsafe_inbound_attachment_url');
+      const download = await fetcher(url.href, { method: 'GET', redirect: 'manual', signal: controller.signal });
+      if (download.status !== 200) fail('inbound_attachment_fetch_failed');
+      const length = download.headers.get('content-length');
+      if (length !== null && (!/^\d+$/.test(length) || Number(length) !== item.size)) fail('inbound_attachment_size_mismatch');
+      const bytes = await readStream(download.body, Math.min(item.size, maxAttachmentBytes));
+      if (bytes.length !== item.size) fail('inbound_attachment_size_mismatch');
+      return bytes;
+    } catch (error) {
+      if (error instanceof MailValidationError) throw error;
+      fail('inbound_attachment_fetch_failed');
+    } finally { clearTimeout(timer); }
+  };
+}

package/modules/mail/src/inbound/resend.mjs

@@ -0,0 +1,54 @@
+import { fail } from '../core/errors.mjs';
+import { bodyBudget, bounded, record, utf8 } from './bytes.mjs';
+import { contentId, contentType, headerText, metadata, objectHeaders } from './headers.mjs';
+export function providerId(value) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(value)) fail('invalid_inbound_provider_id');
+  return value;
+}
+export function attachmentMetadata(value, emailId) {
+  record(value); providerId(emailId);
+  const id = providerId(value.id);
+  if (!Number.isSafeInteger(value.size) || value.size < 0) fail('invalid_inbound_attachment_size');
+  if (value.content_disposition != null && !['inline', 'attachment'].includes(value.content_disposition)) fail('invalid_inbound_disposition');
+  return Object.freeze({ emailId, id, filename: headerText(value.filename), content_type: contentType(value.content_type),
+    content_disposition: value.content_disposition ?? null, content_id: contentId(value.content_id), size: value.size });
+}
+export async function normalizeResend(input, limits) {
+  const email = record(input.email);
+  const id = providerId(email.id);
+  if (id !== providerId(input.signedEmailId)) fail('inbound_identity_mismatch');
+  // Hydrated API JSON is the available raw representation, not the SMTP original.
+  let raw; try { raw = JSON.stringify(email); } catch { fail('invalid_inbound_raw'); }
+  bounded(utf8.encode(raw).length, limits.maxRawBytes, 'inbound_raw_limit');
+  const headers = objectHeaders(email.headers);
+  if (email.message_id != null) {
+    if (headers.has('message-id') && headers.get('message-id') !== email.message_id) fail('inbound_identity_mismatch');
+    headers.set('message-id', email.message_id);
+  }
+  const result = metadata(headers, email.from, email.to, email.subject);
+  const text = email.text ?? null, html = email.html ?? null;
+  if ((text !== null && typeof text !== 'string') || (html !== null && typeof html !== 'string')) fail('invalid_inbound_body');
+  const budget = bodyBudget(limits);
+  if (text !== null) budget.body(text);
+  if (html !== null) budget.body(html);
+  if (!Array.isArray(email.attachments)) fail('invalid_inbound_attachments');
+  bounded(email.attachments.length, limits.maxAttachments, 'inbound_attachment_count');
+  const declared = email.attachments.map(item => attachmentMetadata(item, id));
+  if (new Set(declared.map(item => item.id)).size !== declared.length) fail('duplicate_inbound_attachment');
+  let total = 0;
+  for (const item of declared) {
+    bounded(item.size, limits.maxAttachmentBytes, 'inbound_attachment_limit'); total += item.size;
+    bounded(total, limits.maxTotalAttachmentBytes, 'inbound_attachments_limit');
+  }
+  if (text === null && html === null && !declared.length) fail('invalid_inbound_body');
+  if (declared.length && typeof input.fetchAttachment !== 'function') fail('inbound_attachment_fetch_required');
+  const attachments = [];
+  for (const item of declared) {
+    // Only verified identifiers and sanitized metadata cross this seam; never URLs.
+    const content = await input.fetchAttachment(item);
+    budget.attachment(content);
+    if (content.length !== item.size) fail('inbound_attachment_size_mismatch');
+    attachments.push({ filename: item.filename, contentType: item.content_type, content: content.slice(), contentId: item.content_id });
+  }
+  return { ...result, text, html, attachments };
+}

package/modules/mail/src/inbound/sendgrid.mjs

@@ -0,0 +1,60 @@
+import { fail } from '../core/errors.mjs';
+import { bodyBudget, bounded, decode, record, transfer } from './bytes.mjs';
+import { contentId, contentType, headerText, metadata, parameter, parameterized, parseHeaders } from './headers.mjs';
+import { entity, multipart } from './multipart.mjs';
+import { parseMime } from './mime.mjs';
+function json(value) {
+  try { return record(JSON.parse(value)); } catch { fail('invalid_inbound_json'); }
+}
+export function normalizeSendGrid(input, limits) {
+  if (!(input.rawBody instanceof Uint8Array)) fail('invalid_inbound_raw');
+  bounded(input.rawBody.length, limits.maxRawBytes, 'inbound_raw_limit');
+  const formType = parameterized(input.contentType);
+  if (formType.type !== 'multipart/form-data') fail('invalid_inbound_content_type');
+  const fields = new Map(), files = new Map();
+  for (const raw of multipart(input.rawBody, formType.params.get('boundary'))) {
+    const part = entity(raw); const disposition = parameterized(part.headers.get('content-disposition') ?? '');
+    const name = disposition.params.get('name');
+    if (disposition.type !== 'form-data' || !name || fields.has(name) || files.has(name)) fail('invalid_inbound_form');
+    const filename = parameter(disposition.params, 'filename');
+    const bytes = transfer(part.body, part.headers.get('content-transfer-encoding') ?? 'binary');
+    if (filename !== null) {
+      if (!/^attachment\d+$/.test(name)) fail('invalid_inbound_form');
+      const type = parameterized(part.headers.get('content-type') ?? 'application/octet-stream');
+      files.set(name, { filename, contentType: contentType(type.type), content: bytes.slice(), contentId: contentId(part.headers.get('content-id')) });
+    } else fields.set(name, { bytes, type: parameterized(part.headers.get('content-type') ?? 'text/plain') });
+  }
+  const charsets = fields.has('charsets') ? json(decode(fields.get('charsets').bytes)) : {};
+  for (const value of Object.values(charsets)) if (typeof value !== 'string') fail('invalid_inbound_charset');
+  const field = name => fields.has(name) ? decode(fields.get(name).bytes, fields.get(name).type.params.get('charset') ?? charsets[name] ?? 'utf-8') : undefined;
+  if (fields.has('email')) {
+    if (files.size || fields.has('text') || fields.has('html')) fail('ambiguous_inbound_mime');
+    return parseMime(fields.get('email').bytes, limits);
+  }
+  const headers = parseHeaders(field('headers') ?? '');
+  const result = metadata(headers, field('from') ?? headers.get('from'), field('to') ?? headers.get('to'), field('subject'));
+  const text = field('text') ?? null, html = field('html') ?? null;
+  if (text === null && html === null && files.size === 0) fail('invalid_inbound_body');
+  const count = field('attachments') ?? '0';
+  if (!/^(?:0|[1-9]\d*)$/.test(count) || Number(count) !== files.size) fail('invalid_inbound_attachment_count');
+  const info = fields.has('attachment-info') ? json(field('attachment-info')) : {};
+  const ids = fields.has('content-ids') ? json(field('content-ids')) : {};
+  for (const name of Object.keys(info)) if (!files.has(name)) fail('invalid_inbound_attachment_metadata');
+  const reverseIds = new Map();
+  for (const [id, name] of Object.entries(ids)) {
+    if (typeof name !== 'string' || !files.has(name) || reverseIds.has(name)) fail('invalid_inbound_attachment_metadata');
+    reverseIds.set(name, contentId(id));
+  }
+  const budget = bodyBudget(limits); const attachments = [];
+  if (text !== null) budget.body(text, fields.get('text').bytes.length);
+  if (html !== null) budget.body(html, fields.get('html').bytes.length);
+  for (const [name, file] of files) {
+    const details = info[name] === undefined ? {} : record(info[name]);
+    if (details.filename !== undefined && headerText(details.filename) !== file.filename) fail('inbound_attachment_metadata_mismatch');
+    if (details.type !== undefined && contentType(details.type) !== file.contentType) fail('inbound_attachment_metadata_mismatch');
+    const identifiers = [file.contentId, contentId(details['content-id']), reverseIds.get(name)].filter(id => id != null);
+    if (new Set(identifiers).size > 1) fail('inbound_attachment_metadata_mismatch');
+    budget.attachment(file.content); attachments.push({ ...file, contentId: identifiers[0] ?? null });
+  }
+  return { ...result, text, html, attachments };
+}

package/modules/mail/src/sender.mjs

@@ -0,0 +1,33 @@
+import { validateConfig, validateMessage, validateSendResult } from './core/validation.mjs';
+import { fail } from './core/errors.mjs';
+import { sendSendGrid } from './adapters/sendgrid/index.mjs';
+import { sendResend } from './adapters/resend/index.mjs';
+import { sendCloudflare } from './adapters/cloudflare/index.mjs';
+import { sendMessaging, reconcileMessaging, eraseMessaging } from './adapters/messaging/index.mjs';
+import { sendDevelopment } from './development/index.mjs';
+import { applyUnsubscribeHeaders } from './unsubscribe/index.mjs';
+
+const transports = { sendgrid: sendSendGrid, resend: sendResend, cloudflare: sendCloudflare, development: sendDevelopment, messaging: sendMessaging };
+
+/** Explicit configuration; a missing/failed provider never selects another path. */
+export function createMailSender(config, dependencies = {}) {
+  validateConfig(config, dependencies);
+  let configured;
+  try { configured = Object.freeze(structuredClone(config)); } catch { fail('invalid_config'); }
+  const host = Object.freeze({ ...dependencies });
+  const transport = transports[configured.provider];
+  return Object.freeze({
+    ...(configured.provider === 'messaging' ? {
+      reconcile: deliveryId => reconcileMessaging(configured, deliveryId, host),
+      erase: address => eraseMessaging(configured, address, host),
+    } : {}),
+    async send(message) {
+      validateMessage(message, configured.provider);
+      let snapshot;
+      try { snapshot = structuredClone(message); } catch { fail('invalid_message'); }
+      const prepared = applyUnsubscribeHeaders(snapshot);
+      validateMessage(prepared, configured.provider);
+      return validateSendResult(await transport(configured, prepared, host), configured.provider);
+    },
+  });
+}

package/modules/mail/src/sendgrid-email/index.d.mts

@@ -0,0 +1,33 @@
+export interface SendGridMessage {
+  readonly from: string
+  readonly to: readonly string[]
+  readonly subject: string
+  readonly text: string
+  readonly html?: string | null
+  readonly replyTo?: string
+  readonly headers?: Readonly<Record<string, string>>
+  /** `content` is a base64 string. `type` defaults to application/octet-stream. */
+  readonly attachments?: readonly { readonly content: string; readonly filename: string; readonly type?: string }[]
+  readonly asmGroupId?: number
+  readonly subscriptionTracking?: boolean
+  readonly customArgs?: Readonly<Record<string, string>>
+  /** Durable local command ID for correlation; SendGrid does not deduplicate it. */
+  readonly deliveryId: string
+}
+
+export class SendGridSendError extends Error {
+  readonly outcome: 'rejected' | 'rate_limited' | 'ambiguous'
+  readonly status: number | undefined
+  constructor(outcome: 'rejected' | 'rate_limited' | 'ambiguous', message: string, status?: number)
+}
+
+/** Validated wire envelope, also usable as a durable claim fingerprint. */
+export function serializeSendGridMessage(message: SendGridMessage): string
+
+/** One attempt only. Acceptance and a provider receipt are distinct evidence. */
+export function sendSendGrid(input: {
+  readonly apiKey: string
+  readonly message: SendGridMessage
+  readonly fetch?: typeof globalThis.fetch
+  readonly timeoutMilliseconds?: number
+}): Promise<{ provider: 'sendgrid'; providerMessageId: string | null; state: 'accepted' }>

package/modules/mail/src/sendgrid-email/index.mjs

@@ -0,0 +1,86 @@
+import { MailValidationError } from '../core/errors.mjs';
+import { sendSendGrid as submit, serializeSendGridMessage as serialize } from '../adapters/sendgrid/index.mjs';
+
+// The API of the former `modules/sendgrid-email` module, kept for existing adopters.
+// It owns no transport: every request is built and sent by the one SendGrid adapter
+// in this module, so both import paths put identical requests on the wire.
+
+export class SendGridSendError extends Error {
+  constructor(outcome, message, status) {
+    super(message);
+    this.name = 'SendGridSendError';
+    this.outcome = outcome;
+    this.status = status;
+  }
+}
+
+function rejected(message) { return new SendGridSendError('rejected', message); }
+
+// Diagnostics carry only the fixed validation code, never input values.
+function invalid(error) {
+  if (error instanceof MailValidationError) return rejected(`SendGrid message or key is invalid (${error.code}).`);
+  return rejected('SendGrid message or key is invalid.');
+}
+
+function decodeAttachment(attachment) {
+  const content = attachment?.content;
+  if (typeof content !== 'string' || !content || !/^[A-Za-z0-9+/\s]*={0,2}\s*$/.test(content)) throw rejected('Attachment content must be base64.');
+  let binary;
+  try { binary = atob(content); } catch { throw rejected('Attachment content must be base64.'); }
+  return {
+    filename: attachment.filename,
+    contentType: attachment.type ?? 'application/octet-stream',
+    content: Uint8Array.from(binary, character => character.charCodeAt(0)),
+  };
+}
+
+// Only the former module's fields are read, so unknown fields stay ignored as before.
+function toMailMessage(message) {
+  if (!message || typeof message !== 'object') throw rejected('SendGrid message is required.');
+  const mapped = { deliveryId: message.deliveryId, from: message.from, to: message.to, subject: message.subject, text: message.text };
+  if (message.html) mapped.html = message.html;
+  if (message.replyTo) mapped.replyTo = message.replyTo;
+  for (const field of ['headers', 'customArgs', 'asmGroupId', 'subscriptionTracking']) {
+    if (message[field] !== undefined) mapped[field] = message[field];
+  }
+  if (message.attachments?.length) mapped.attachments = message.attachments.map(decodeAttachment);
+  return mapped;
+}
+
+/** Validated wire envelope, also usable as a durable claim fingerprint. */
+export function serializeSendGridMessage(message) {
+  try { return serialize(toMailMessage(message)); } catch (error) {
+    throw error instanceof SendGridSendError ? error : invalid(error);
+  }
+}
+
+/** One attempt only. Acceptance and a provider receipt are distinct evidence. */
+export async function sendSendGrid(input) {
+  if (typeof input?.apiKey !== 'string' || !input.apiKey.trim()) throw rejected('SendGrid API key is required.');
+  const message = toMailMessage(input.message);
+  const baseFetch = input.fetch ?? globalThis.fetch;
+  let httpStatus;
+  // The adapter result classifies the outcome; the exact HTTP status is kept for callers.
+  const observedFetch = async (url, init) => {
+    const response = await baseFetch(url, init);
+    httpStatus = response?.status;
+    return response;
+  };
+  const dependencies = { fetch: observedFetch };
+  if (input.timeoutMilliseconds !== undefined) dependencies.timeoutMilliseconds = input.timeoutMilliseconds;
+  let result;
+  try {
+    result = await submit({ provider: 'sendgrid', mode: 'production', apiKey: input.apiKey }, message, dependencies);
+  } catch (error) { throw invalid(error); }
+  switch (result.status) {
+    case 'accepted':
+      return { provider: 'sendgrid', providerMessageId: result.providerMessageId, state: 'accepted' };
+    case 'rate_limited':
+      throw new SendGridSendError('rate_limited', 'SendGrid rate limited this submission.', httpStatus);
+    case 'rejected':
+      throw new SendGridSendError('rejected', `SendGrid rejected this submission (${httpStatus}).`, httpStatus);
+    default:
+      if (httpStatus === undefined) throw new SendGridSendError('ambiguous', 'SendGrid submission did not return a receipt; reconcile before resending.');
+      throw new SendGridSendError('ambiguous', `SendGrid returned an unconfirmed submission status (${httpStatus}); reconcile before resending.`, httpStatus);
+  }
+}