@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/mail/src/core/validation.mjs

@@ -0,0 +1,172 @@
+import { fail } from './errors.mjs';
+import { validateMessagingConfig, validateMessagingResult, identity, rfc3339 } from '../adapters/messaging/contract.mjs';
+
+const providers = ['sendgrid', 'resend', 'cloudflare', 'development', 'messaging'];
+const controls = /[\x00-\x1f\x7f]/;
+const fields = new Set(['deliveryId', 'from', 'to', 'subject', 'text', 'html', 'cc', 'bcc', 'replyTo', 'headers', 'attachments', 'unsubscribe', 'customArgs', 'asmGroupId', 'subscriptionTracking', 'kind', 'expiresAt']);
+const reservedHeaders = new Set(['x-sg-id', 'x-sg-eid', 'received', 'dkim-signature', 'content-type', 'content-transfer-encoding', 'mime-version', 'to', 'from', 'subject', 'reply-to', 'cc', 'bcc', 'return-path', 'sender']);
+const reservedArgs = new Set(['rer_delivery_id', 'email', 'event', 'timestamp', 'sg_event_id', 'sg_message_id']);
+
+function record(value, code) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail(code);
+  return value;
+}
+function keys(value, allowed, code) {
+  record(value, code);
+  if (Reflect.ownKeys(value).some(key => typeof key !== 'string' || !allowed.has(key))) fail(code);
+}
+function bounded(value, limit, code, empty = false) {
+  if (typeof value !== 'string' || (!empty && !value.trim()) || value.length > limit || controls.test(value)) fail(code);
+}
+
+export function validateConfig(config, dependencies = {}) {
+  keys(config, new Set(['provider', 'mode', 'apiKey', 'accountId', 'serviceOrigin', 'installId', 'kid', 'signingKey']), 'invalid_config');
+  record(dependencies, 'invalid_dependencies');
+  if (!providers.includes(config.provider)) fail('invalid_provider');
+  if (!['production', 'development', 'test'].includes(config.mode)) fail('invalid_mode');
+  if (dependencies.fetch !== undefined && typeof dependencies.fetch !== 'function') fail('invalid_fetch');
+  if (dependencies.clock !== undefined && typeof dependencies.clock !== 'function') fail('invalid_clock');
+  if (dependencies.timeoutMilliseconds !== undefined &&
+      (!Number.isSafeInteger(dependencies.timeoutMilliseconds) || dependencies.timeoutMilliseconds <= 0)) fail('invalid_timeout');
+  if (config.provider === 'messaging') return validateMessagingConfig(config, dependencies) ?? config;
+  if (['serviceOrigin', 'installId', 'kid', 'signingKey'].some(field => config[field] !== undefined) || dependencies.serviceBinding !== undefined) fail('unsupported_provider_setting');
+  if (config.provider === 'development') {
+    if (config.mode !== 'development') fail('development_mode_required');
+    if (config.apiKey !== undefined || config.accountId !== undefined) fail('unsupported_development_config');
+    if (!dependencies.outbox || typeof dependencies.outbox.put !== 'function') fail('development_outbox_required');
+  } else {
+    if (typeof config.apiKey !== 'string' || !config.apiKey.trim()) fail('api_key_required');
+    bounded(config.apiKey, 4096, 'invalid_api_key');
+    if (/\s/.test(config.apiKey)) fail('invalid_api_key');
+    if (config.provider === 'cloudflare') {
+      if (typeof config.accountId !== 'string' || !/^[a-f0-9]{32}$/i.test(config.accountId)) fail('cloudflare_account_required');
+    } else if (config.accountId !== undefined) fail('unsupported_account_id');
+  }
+  return config;
+}
+
+export function parseAddress(value) {
+  bounded(value, 998, 'invalid_address');
+  const match = value.trim().match(/^(?:(.*?)\s*<([^<>]+)>|([^<>]+))$/u);
+  const email = (match?.[2] ?? match?.[3] ?? '').trim();
+  // Conservative mailbox subset; never serialize multiple mailboxes as one.
+  const parts = email.split('@');
+  if (parts.length !== 2 || !parts[0] || parts[0].length > 64 || email.length > 254 ||
+      !/^[^\s@<>(),:;"\\]+$/u.test(parts[0]) || parts[0].startsWith('.') || parts[0].endsWith('.') || parts[0].includes('..') ||
+      !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(parts[1])) fail('invalid_address');
+  let name = match?.[1]?.trim();
+  if (name?.startsWith('"') && name.endsWith('"')) name = name.slice(1, -1);
+  if (name && /[<>"\\]/.test(name)) fail('invalid_address');
+  return name ? { email, name } : { email };
+}
+
+export function validateHeaders(headers = {}) {
+  record(headers, 'invalid_headers');
+  const names = new Set();
+  for (const name of Reflect.ownKeys(headers)) {
+    if (typeof name !== 'string' || !/^[!#$%&'*+.^_`|~0-9a-z-]+$/i.test(name) || name.length > 998) fail('invalid_header_name');
+    const lower = name.toLowerCase();
+    if (reservedHeaders.has(lower) || names.has(lower)) fail('reserved_or_duplicate_header');
+    names.add(lower);
+    bounded(headers[name], 8192, 'invalid_header_value', true);
+  }
+  return headers;
+}
+
+function addresses(values, required = false) {
+  if (!Array.isArray(values) || (required && !values.length)) fail('invalid_recipients');
+  for (const value of values) parseAddress(value);
+}
+function validateAttachment(attachment) {
+  keys(attachment, new Set(['filename', 'contentType', 'content', 'disposition', 'contentId']), 'invalid_attachment');
+  bounded(attachment.filename, 998, 'invalid_attachment_filename');
+  bounded(attachment.contentType, 255, 'invalid_attachment_content_type');
+  if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(attachment.contentType)) fail('invalid_attachment_content_type');
+  if (!(attachment.content instanceof Uint8Array)) fail('invalid_attachment_content');
+  if (attachment.disposition !== undefined && !['attachment', 'inline'].includes(attachment.disposition)) fail('invalid_attachment_disposition');
+  if (attachment.contentId !== undefined) {
+    bounded(attachment.contentId, 998, 'invalid_attachment_content_id');
+    if (/[\s<>]/.test(attachment.contentId)) fail('invalid_attachment_content_id');
+  }
+  if (attachment.disposition === 'inline' && !attachment.contentId) fail('inline_content_id_required');
+}
+function validateUnsubscribe(value) {
+  keys(value, new Set(['url', 'mailto', 'oneClick']), 'invalid_unsubscribe');
+  bounded(value.url, 8192, 'invalid_unsubscribe_url');
+  let url;
+  try { url = new URL(value.url); } catch { fail('invalid_unsubscribe_url'); }
+  if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || /[<>]/.test(value.url) || /%0[ad]/i.test(value.url)) fail('invalid_unsubscribe_url');
+  if (value.mailto !== undefined) {
+    const mailbox = value.mailto.startsWith?.('mailto:') ? value.mailto.slice(7) : value.mailto;
+    const parsed = parseAddress(mailbox);
+    if (parsed.name || parsed.email !== mailbox) fail('invalid_unsubscribe_mailto');
+  }
+  if (value.oneClick !== undefined && typeof value.oneClick !== 'boolean') fail('invalid_unsubscribe_one_click');
+}
+
+export function validateMessage(message, provider) {
+  keys(message, fields, 'invalid_message');
+  if (provider !== undefined && !providers.includes(provider)) fail('invalid_provider');
+  bounded(message.deliveryId, 512, 'invalid_delivery_id');
+  if (provider === 'messaging') {
+    identity(message.deliveryId, 512, 'invalid_delivery_id');
+    if (message.deliveryId === '.' || message.deliveryId === '..') fail('invalid_delivery_id');
+    try { encodeURIComponent(message.deliveryId); } catch { fail('invalid_delivery_id'); }
+    if (!['auth', 'transactional', 'bulk'].includes(message.kind)) fail('invalid_message_kind');
+    if (!Array.isArray(message.to) || message.to.length !== 1 || message.cc !== undefined || message.bcc !== undefined) fail('messaging_one_recipient_required');
+    if (message.expiresAt !== undefined) rfc3339(message.expiresAt, 'invalid_message_expiry');
+  } else if (provider !== undefined && (message.kind !== undefined || message.expiresAt !== undefined)) fail('unsupported_provider_setting');
+  if (message.kind !== undefined && !['auth', 'transactional', 'bulk'].includes(message.kind)) fail('invalid_message_kind');
+  if (message.expiresAt !== undefined) rfc3339(message.expiresAt, 'invalid_message_expiry');
+  parseAddress(message.from);
+  addresses(message.to, true);
+  if (message.cc !== undefined) addresses(message.cc);
+  if (message.bcc !== undefined) addresses(message.bcc);
+  if (message.replyTo !== undefined) parseAddress(message.replyTo);
+  bounded(message.subject, 998, 'invalid_subject', true);
+  for (const field of ['text', 'html']) if (message[field] !== undefined && typeof message[field] !== 'string') fail('invalid_body');
+  if (!message.text?.trim() && !message.html?.trim()) fail('body_required');
+  if (message.headers !== undefined) validateHeaders(message.headers);
+  if (message.attachments !== undefined) {
+    if (!Array.isArray(message.attachments)) fail('invalid_attachments');
+    for (const attachment of message.attachments) validateAttachment(attachment);
+  }
+  if (message.unsubscribe !== undefined) validateUnsubscribe(message.unsubscribe);
+  const settings = ['customArgs', 'asmGroupId', 'subscriptionTracking'];
+  if (provider && !['sendgrid', 'development'].includes(provider) && settings.some(key => message[key] !== undefined)) fail('unsupported_provider_setting');
+  if (message.asmGroupId !== undefined && (!Number.isSafeInteger(message.asmGroupId) || message.asmGroupId <= 0)) fail('invalid_asm_group');
+  if (message.subscriptionTracking !== undefined && typeof message.subscriptionTracking !== 'boolean') fail('invalid_subscription_tracking');
+  const args = message.customArgs ?? {};
+  if (message.customArgs !== undefined) record(message.customArgs, 'invalid_custom_args');
+  for (const key of Reflect.ownKeys(args)) {
+    if (typeof key !== 'string' || !key || controls.test(key) || reservedArgs.has(key) || typeof args[key] !== 'string') fail('invalid_custom_arg');
+  }
+  if (new TextEncoder().encode(JSON.stringify({ ...args, rer_delivery_id: message.deliveryId })).byteLength > 10_000) fail('custom_args_too_large');
+  return message;
+}
+
+export function encodeBase64(bytes) {
+  if (!(bytes instanceof Uint8Array)) fail('invalid_attachment_content');
+  let binary = '';
+  for (let offset = 0; offset < bytes.length; offset += 8192) binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+  return btoa(binary);
+}
+
+export function validateSendResult(result, provider) {
+  if (provider === 'messaging') return validateMessagingResult(result);
+  keys(result, new Set(['provider', 'status', 'providerMessageId', 'code', 'recipientResults']), 'invalid_send_result');
+  if (!providers.includes(provider) || result.provider !== provider || !['accepted', 'rejected', 'rate_limited', 'uncertain', 'development'].includes(result.status)) fail('invalid_send_result');
+  if ((provider === 'development') !== (result.status === 'development')) fail('invalid_send_result');
+  if (result.providerMessageId !== null) bounded(result.providerMessageId, 1024, 'invalid_provider_message_id');
+  if (result.status === 'development' && result.providerMessageId !== null) fail('invalid_send_result');
+  if (result.code !== undefined && (typeof result.code !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(result.code))) fail('invalid_result_code');
+  if (result.recipientResults !== undefined) {
+    if (!Array.isArray(result.recipientResults)) fail('invalid_recipient_results');
+    for (const item of result.recipientResults) {
+      keys(item, new Set(['recipient', 'status']), 'invalid_recipient_result');
+      parseAddress(item.recipient);
+      if (!['accepted', 'rejected', 'rate_limited', 'uncertain'].includes(item.status)) fail('invalid_recipient_status');
+    }
+  }
+  return result;
+}

package/modules/mail/src/development/index.d.mts

@@ -0,0 +1,37 @@
+export interface DevelopmentMessage {
+  deliveryId: string;
+  from: string;
+  to: string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  cc?: string[];
+  bcc?: string[];
+  replyTo?: string;
+  headers?: Record<string, string>;
+  attachments?: Array<{ filename: string; contentType: string; content: Uint8Array; disposition?: 'attachment' | 'inline'; contentId?: string }>;
+  customArgs?: Record<string, string>;
+  asmGroupId?: number;
+  subscriptionTracking?: boolean;
+}
+export interface DevelopmentCapture { id: string; createdAt: number; message: DevelopmentMessage }
+export type DevelopmentOutboxListMessage = Omit<DevelopmentMessage, 'attachments'>;
+export interface DevelopmentOutboxListCapture { id: string; createdAt: number; message: DevelopmentOutboxListMessage }
+export interface DevelopmentOutbox {
+  put(message: DevelopmentMessage): Promise<void>;
+  list(): Promise<DevelopmentOutboxListCapture[]>;
+  get(id: string): Promise<DevelopmentCapture | null>;
+}
+export interface DevelopmentD1Statement { bind(...values: unknown[]): DevelopmentD1Statement }
+export interface DevelopmentD1Database {
+  prepare(sql: string): DevelopmentD1Statement;
+  batch(statements: DevelopmentD1Statement[]): Promise<Array<{ success: boolean; results: unknown[] }>>;
+}
+export function createD1DevelopmentOutbox(options: { db: DevelopmentD1Database; maxMessages?: number; maxAgeMs?: number; clock?: () => number }): DevelopmentOutbox;
+export function createDevelopmentOutboxHandler(options: {
+  local: boolean; origin: string; outbox: Pick<DevelopmentOutbox, 'list' | 'get'>; path?: string;
+  /** The seed's served theme stylesheet, a root-relative `.css` path such as '/rer-theme.css'; other values throw. */
+  theme?: string;
+}): (request: Request) => Promise<Response | null>;
+export function sendDevelopment(config: { provider: 'development'; mode: 'development' }, message: DevelopmentMessage,
+  dependencies: { outbox: Pick<DevelopmentOutbox, 'put'>; clock?: () => number }): Promise<{ provider: 'development'; status: 'development'; providerMessageId: null }>;

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

@@ -0,0 +1,35 @@
+import { MailValidationError, fail } from '../core/errors.mjs';
+import { validateConfig, validateMessage } from '../core/validation.mjs';
+import { sendResult } from '../core/transport.mjs';
+
+export { createD1DevelopmentOutbox } from './outbox.mjs';
+export { createDevelopmentOutboxHandler } from './viewer.mjs';
+
+function validate(operation, errorCode) {
+  try {
+    return operation();
+  } catch (error) {
+    if (error instanceof MailValidationError) throw error;
+    fail(errorCode);
+  }
+}
+
+/** Store one explicitly selected development message without contacting a provider. */
+export async function sendDevelopment(config, message, dependencies = {}) {
+  validate(() => validateConfig(config, dependencies), 'invalid_config');
+  if (validate(() => config.provider, 'invalid_config') !== 'development') fail('development_provider_required');
+
+  validate(() => validateMessage(message, 'development'), 'invalid_message');
+  if (validate(() => message.unsubscribe, 'invalid_message') !== undefined) fail('unsubscribe_not_assembled');
+
+  const snapshot = validate(() => structuredClone(message), 'invalid_message');
+  validate(() => validateMessage(snapshot, 'development'), 'invalid_message');
+
+  try {
+    await dependencies.outbox.put(snapshot);
+  } catch {
+    fail('development_outbox_failed');
+  }
+
+  return sendResult('development', 'development', null);
+}

package/modules/mail/src/development/outbox.mjs

@@ -0,0 +1,78 @@
+import { validateMessage, encodeBase64 } from '../core/validation.mjs';
+import { fail } from '../core/errors.mjs';
+
+function positive(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError('Invalid development outbox retention');
+  return value;
+}
+
+function restore(row) {
+  const message = JSON.parse(row.message);
+  if (message.attachments) message.attachments = message.attachments.map(attachment => ({
+    ...attachment, content: Uint8Array.from(atob(attachment.content), character => character.charCodeAt(0)),
+  }));
+  return { id: row.id, createdAt: row.created_at, message };
+}
+
+function summarize(row) {
+  const message = JSON.parse(row.message);
+  delete message.attachments;
+  return { id: row.id, createdAt: row.created_at, message };
+}
+
+/** Durable local capture; each capture has its own ID, even for repeated delivery IDs. */
+export function createD1DevelopmentOutbox({ db, maxMessages = 100, maxAgeMs = 7 * 24 * 60 * 60 * 1000, clock = Date.now } = {}) {
+  if (!db || typeof db.prepare !== 'function' || typeof db.batch !== 'function' || typeof clock !== 'function') {
+    throw new TypeError('Invalid development outbox configuration');
+  }
+  positive(maxMessages); positive(maxAgeMs);
+  function now() {
+    const value = clock();
+    if (!Number.isSafeInteger(value) || value < 0 || value > 8_640_000_000_000_000) throw new TypeError('Invalid development outbox clock');
+    return value;
+  }
+  const statement = (sql, ...values) => db.prepare(sql).bind(...values);
+  function retention(time) {
+    return [
+      statement('DELETE FROM rer_mail_development_outbox WHERE created_at <= ?', time - maxAgeMs),
+      statement(`DELETE FROM rer_mail_development_outbox WHERE sequence NOT IN
+        (SELECT sequence FROM rer_mail_development_outbox ORDER BY created_at DESC, sequence DESC LIMIT ?)`, maxMessages),
+    ];
+  }
+  async function batch(statements) {
+    const results = await db.batch(statements);
+    if (!Array.isArray(results) || results.length !== statements.length || results.some(result => result.success !== true)) {
+      throw new Error('Development outbox storage failed');
+    }
+    return results.at(-1);
+  }
+  return Object.freeze({
+    async put(message) {
+      validateMessage(message, 'development');
+      if (message.unsubscribe !== undefined) fail('unsubscribe_not_assembled');
+      const snapshot = structuredClone(message);
+      validateMessage(snapshot, 'development');
+      if (snapshot.unsubscribe !== undefined) fail('unsubscribe_not_assembled');
+      if (snapshot.attachments) snapshot.attachments = snapshot.attachments.map(attachment => ({
+        ...attachment, content: encodeBase64(attachment.content),
+      }));
+      const time = now();
+      await batch([
+        statement('INSERT INTO rer_mail_development_outbox(id, created_at, message) VALUES (?, ?, ?)', crypto.randomUUID(), time, JSON.stringify(snapshot)),
+        ...retention(time),
+      ]);
+    },
+    async list() {
+      const time = now();
+      const result = await batch([statement(`SELECT id, created_at, message FROM rer_mail_development_outbox
+        WHERE created_at > ? ORDER BY created_at DESC, sequence DESC LIMIT ?`, time - maxAgeMs, maxMessages)]);
+      return result.results.map(summarize);
+    },
+    async get(id) {
+      if (typeof id !== 'string' || !id || id.length > 128) throw new TypeError('Invalid development outbox ID');
+      const result = await batch([statement(`SELECT id, created_at, message FROM rer_mail_development_outbox
+        WHERE id = ? AND created_at > ?`, id, now() - maxAgeMs)]);
+      return result.results.length ? restore(result.results[0]) : null;
+    },
+  });
+}

package/modules/mail/src/development/schema.sql

@@ -0,0 +1,9 @@
+-- Additive local-development storage. Apply explicitly to the local D1 database.
+CREATE TABLE IF NOT EXISTS rer_mail_development_outbox (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  created_at INTEGER NOT NULL,
+  message TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS rer_mail_development_outbox_order
+  ON rer_mail_development_outbox(created_at DESC, sequence DESC);

package/modules/mail/src/development/viewer-html.mjs

@@ -0,0 +1,42 @@
+export const style = `*{box-sizing:border-box}body{margin:0;background:#f5f7fa;color:#17212e;font:16px/1.6 system-ui,sans-serif}main{max-width:52rem;margin:0 auto;padding:24px 16px}h1{font-size:1.75rem;line-height:1.2}article{margin:20px 0;padding:20px;background:white;border:1px solid #cad2dc;border-radius:12px}h2{font-size:1.2rem}h1,h2,p,a,pre{overflow-wrap:anywhere;word-break:normal}pre{white-space:pre-wrap;font:inherit}a{color:#174fb5}a.open{display:block;padding:16px;margin:20px 0;border-radius:8px;background:#174fb5;color:white;font-weight:700;text-align:center;text-decoration:none;min-height:56px}small{color:#465569}`;
+
+// Added only when the seed declares a theme: its linked rer-theme.css supplies the
+// --rer-* tokens. Each falls back to the plain sheet's value, and the focus ring is
+// always drawn, so a theme that fails to load leaves a readable, usable page.
+export const themedStyle = `.rer-themed body{background:var(--rer-page,#f5f7fa);color:var(--rer-text,#17212e);font-family:var(--rer-font-body,system-ui,sans-serif)}.rer-themed h1,.rer-themed h2{font-family:var(--rer-font-heading,var(--rer-font-body,system-ui,sans-serif))}.rer-themed article{background:var(--rer-surface,#fff);border-color:var(--rer-border,#cad2dc);border-radius:var(--rer-radius,12px)}.rer-themed p,.rer-themed small{color:var(--rer-muted,#465569)}.rer-themed h2,.rer-themed pre{color:var(--rer-text,#17212e)}.rer-themed a{color:var(--rer-link,#174fb5)}.rer-themed a.open{background:var(--rer-accent,#174fb5);color:var(--rer-accent-text,#fff);border-radius:var(--rer-radius,8px)}.rer-themed :focus-visible{outline:3px solid var(--rer-focus,#17212e);outline-offset:3px}`;
+
+export function escape(value) {
+  return String(value).replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+}
+
+// Read link candidates as data only. Never parse or mount mail HTML in the page.
+export function firstLink(message) {
+  for (const body of [message.text, message.html]) {
+    if (typeof body !== 'string') continue;
+    for (const match of body.matchAll(/https?:\/\/[^\s<>"']+/gi)) {
+      try {
+        const candidate = match[0].replace(/&amp;/g, '&').replace(/[.,;!?]+$/, '');
+        const url = new URL(candidate);
+        if (['http:', 'https:'].includes(url.protocol) && url.hostname && !url.username && !url.password) return url.href;
+      } catch { /* Malformed candidates are ordinary message text. */ }
+    }
+  }
+  return null;
+}
+
+function metadata(row) {
+  return `<h2>${escape(row.message.subject || '(No subject)')}</h2><p>To: ${escape(row.message.to.join(', '))}</p><p>Received: <time datetime="${escape(new Date(row.createdAt).toISOString())}">${escape(new Date(row.createdAt).toUTCString())}</time></p>`;
+}
+
+export function document(body, theme) {
+  return `<!doctype html><html lang="en"${theme ? ' class="rer-themed"' : ''}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex, nofollow"><title>Development outbox</title>${theme ? `<link rel="stylesheet" href="${escape(theme)}">` : ''}<style>${theme ? style + themedStyle : style}</style></head><body><main><h1>Development outbox</h1><p>Messages captured on this computer. No email was sent.</p>${body}</main></body></html>`;
+}
+
+export function listing(rows, path) {
+  return rows.length ? rows.map(row => `<article>${metadata(row)}<p><a href="${escape(`${path}?message=${encodeURIComponent(row.id)}`)}">Read message</a></p></article>`).join('') : '<p>No messages yet.</p>';
+}
+
+export function detail(row, path) {
+  const link = firstLink(row.message);
+  return `<p><a href="${escape(path)}">All messages</a></p><article>${metadata(row)}${link ? `<a class="open" href="${escape(link)}" rel="noreferrer noopener">Open this link</a>` : ''}<h2>Message text</h2><pre>${escape(row.message.text || row.message.html || '')}</pre>${row.message.attachments?.length ? `<p>${row.message.attachments.length} attachment(s) stored with this message.</p>` : ''}</article>`;
+}

package/modules/mail/src/development/viewer.mjs

@@ -0,0 +1,65 @@
+import { detail, document, listing, style, themedStyle } from './viewer-html.mjs';
+
+function localOrigin(origin) {
+  if (typeof origin !== 'string') return null;
+  try {
+    const url = new URL(origin);
+    const ipv4 = url.hostname.split('.');
+    const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' ||
+      (ipv4.length === 4 && ipv4[0] === '127' && ipv4.every(part => /^(0|[1-9]\d{0,2})$/.test(part) && Number(part) <= 255));
+    return loopback && ['http:', 'https:'].includes(url.protocol) && url.origin === origin ? url : null;
+  } catch { return null; }
+}
+
+function routePath(path) {
+  return typeof path === 'string' && /^\/(?:[A-Za-z0-9_-]+\/?)+$/.test(path) && !path.includes('//');
+}
+
+// The seed's own served stylesheet, in the grammar operator-auth branding accepts.
+function themePath(theme) {
+  return typeof theme === 'string' && /^\/(?!\/)[A-Za-z0-9._~/-]{1,200}\.css$/.test(theme) && !theme.includes('//') && !theme.includes('/.');
+}
+
+/** Opt-in local route. Rejected requests return null without touching the outbox. */
+export function createDevelopmentOutboxHandler({ local, origin, outbox, path = '/__dev/outbox', theme } = {}) {
+  if (theme !== undefined && !themePath(theme)) throw new TypeError('Declare the outbox theme as a same-origin path to the seed\'s served .css file');
+  const configured = local === true ? localOrigin(origin) : null;
+  if (!configured || !routePath(path)) return async () => null;
+  if (!outbox || typeof outbox.list !== 'function' || typeof outbox.get !== 'function') throw new TypeError('Invalid development outbox reader');
+  const sheet = theme ? style + themedStyle : style;
+  const styles = hash => theme ? `style-src 'self' 'sha256-${hash}'; font-src 'self'; img-src 'self'` : `style-src 'sha256-${hash}'`;
+  let hash;
+  async function response(body, status = 200, head = false) {
+    hash ??= crypto.subtle.digest('SHA-256', new TextEncoder().encode(sheet)).then(bytes => btoa(String.fromCharCode(...new Uint8Array(bytes))));
+    return new Response(head ? null : document(body, theme), { status, headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'X-Robots-Tag': 'noindex, nofollow',
+      'X-Content-Type-Options': 'nosniff',
+      'Referrer-Policy': 'no-referrer',
+      'Content-Security-Policy': `default-src 'none'; script-src 'none'; ${styles(await hash)}; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; object-src 'none'`,
+      ...(status === 405 ? { Allow: 'GET, HEAD' } : {}),
+    } });
+  }
+  return async function handle(request) {
+    let url;
+    try { url = new URL(request.url); } catch { return null; }
+    if (url.origin !== configured.origin || url.username || url.password || request.headers.get('host') !== configured.host || url.pathname !== path) return null;
+    const requestOrigin = request.headers.get('origin');
+    if ((requestOrigin !== null && requestOrigin !== configured.origin) || request.headers.get('sec-fetch-site') === 'cross-site') return null;
+    const head = request.method === 'HEAD';
+    if (request.method !== 'GET' && !head) return response('<p>Use GET to read messages.</p>', 405);
+    if ([...url.searchParams.keys()].some(key => key !== 'message') || url.searchParams.getAll('message').length > 1) return response('<p>Invalid message request.</p>', 400, head);
+    try {
+      if (url.searchParams.has('message')) {
+        const id = url.searchParams.get('message');
+        if (!id || id.length > 128) return response('<p>Invalid message request.</p>', 400, head);
+        const row = await outbox.get(id);
+        return response(row ? detail(row, path) : '<p>Message not found or expired.</p>', row ? 200 : 404, head);
+      }
+      return response(listing(await outbox.list(), path), 200, head);
+    } catch {
+      return response('<p>The development outbox is unavailable.</p>', 503, head);
+    }
+  };
+}

package/modules/mail/src/doctor/README.md

@@ -0,0 +1,107 @@
+# Mail doctor API
+
+`mailDoctor(options, dependencies = {})` is portable ESM. Import from the public
+mail facade, or directly from
+`modules/mail/src/doctor/index.mjs`. No Node APIs enter this runtime graph.
+
+```js
+const result = await mailDoctor({
+  domain: 'mail.example.com', provider: 'resend', live: false,
+  dnsRecords: { mx: [], spf: [], dkim: [], dmarc: [] },
+});
+```
+
+Each supplied DNS group contains `{type, name, value, priority?}` records. Types
+are uppercase `MX`, `TXT`, `CNAME`; names are fully qualified (a final dot is
+optional). MX requires numeric priority. Supply unquoted TXT values, including
+the complete SPF/DMARC policy. SPF supports a provider return-path CNAME; DKIM
+supports TXT or CNAME at the provider-assigned `selector._domainkey` name. Do
+not guess a selector, public key, MX host, SPF include or return-path value.
+Copy exact values from the selected provider's domain setup. Receiving MX may
+belong to a different receiving provider and domain from the sender. All four
+groups can therefore contain names other than `domain`.
+
+The six ordered items are `mx`, `spf`, `dkim`, `dmarc`, `send`, `receive`. Each
+has `status`, `nextSteps`, optional `records`, and redacted `evidence`. A plan
+has only `pending`/`not_checked` items. Supplied records remain a plan until
+queried. Missing setup values have actionable instructions and empty records;
+they are never invented or treated as published records.
+
+For explicit live operation add:
+
+```js
+{
+  live: true,
+  send: {config: senderConfig, from: verifiedSender, to: ownerTestInbox},
+  receive: readbackConfig,
+  timeoutMs: 60000, pollIntervalMs: 2000
+}
+```
+
+`senderConfig` is an ordinary mail sender configuration, for example
+`{provider: 'resend', mode: 'production', apiKey}` with the sending credential
+as `apiKey`. `readbackConfig` is `{provider: 'resend', apiKey}` with a separate
+readback credential as `apiKey`. Both credentials come from the environment.
+
+Sender provider must agree with `options.provider`; sending domain must match
+`domain`. SendGrid and Cloudflare senders use the same facade (Cloudflare also
+requires `config.accountId`). The built-in readback is an actual Resend receiving
+mailbox, independent of the sending provider. An existing arbitrary mailbox
+cannot be proven by this readback: provision an approved Resend receiving address
+or implement a separately reviewed readback before claiming proof. All live
+inputs validate before any effect. Complete live config is required even when
+some DNS setup values have not yet been supplied.
+
+DNS uses a fixed Cloudflare DNS-over-HTTPS endpoint and bounded GETs. Comparison
+reports `match`, `missing`, `mismatch`, `error` or `unchecked` in evidence. Empty
+NOERROR/NXDOMAIN means missing; resolver transport failures, malformed responses
+and other DNS response codes mean error. TXT character strings are concatenated;
+MX priorities and CNAME hostnames compare canonically. Duplicate SPF/DMARC
+policies fail. A matching explicit record plan does not prove full recursive SPF
+evaluation, DKIM message signatures or DMARC alignment. Undeclared selectors,
+parent-domain DMARC discovery and provider dashboard verification are outside
+this check. A missing plan remains unchecked even in live mode.
+
+Live sends exactly once through `createMailSender`; there is no retry. Every run
+creates a random UUID in the subject and plain-text body. `send:pass` means
+provider acceptance only. `receive:pass` requires an independent received-mail
+list and detail read, matching received ID, exact sender/recipient, fresh receipt
+time (one-second timestamp tolerance), exact subject/body and an RFC Message-ID.
+Uncertain submissions may be read back but retain their uncertain send result.
+No send response or sent-mail status endpoint can establish receipt.
+
+The default receive timeout is 60 seconds, configurable from 100 to 120000 ms;
+poll spacing is 100–10000 ms. Limits are 30 polls, three pages of 100 messages per
+poll, eight seconds per HTTP request and 256 KiB per receive response. A busy
+mailbox exceeding that scan remains pending. DNS performs at most 32 distinct
+eight-second queries concurrently; send has a 16-second outer bound. DNS and
+send/readback run concurrently, after validation. Redirects are refused. Only
+fixed provider origins are fetched; response IDs must be UUIDs before use in
+paths, and remote attachment/raw-download URLs are never followed.
+
+Dependencies are `{fetch?, resolveDns?, sender?}`. `fetch` is the standard Web
+fetch host/test seam. `resolveDns({name,type,signal})` returns
+`{status:'ok'|'missing'|'error',records:[{type,name,value,priority?}]}`; errors can
+omit records. The injected resolver must honor abort; the caller also bounds
+the wait. `sender:{send(message)}` is an explicit unit-test seam using the frozen
+sender result contract. Production omits it and loads the real sender facade.
+Do not expose dependency selection to application users. There is no fixture
+provider, automatic outbox selection, custom URL, or dynamic code loader.
+
+Evidence contains the random correlation ID, actual received-mail UUID, hashes
+of send-provider/RFC message IDs, recipient and body, timing and counts. It never
+returns credentials, message content, arbitrary headers, raw responses or remote
+error messages. API keys belong only in private process/config memory. A UI
+calling this function owns user authorization and test-inbox approval.
+
+Run unit checks: `node --test modules/mail/tests/doctor/*.test.mjs`. These tests
+inject explicit sender and network fixtures only under `./tests/doctor`; they prove
+protocol/conformance, not delivery. `tests/assembly/workerd.test.mjs` exercises
+the doctor through the real facade and all three sending adapters in workerd. See `../../live-proof/README.md` for protected proof.
+
+Primary contracts checked 2026-10-06:
+
+- [Cloudflare DNS JSON](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/)
+- [Resend received-mail listing](https://resend.com/docs/api-reference/emails/list-received-emails)
+- [Resend received-mail retrieval](https://resend.com/docs/api-reference/emails/retrieve-received-email)
+- [Resend pagination](https://resend.com/docs/api-reference/pagination)

package/modules/mail/src/doctor/common.mjs

@@ -0,0 +1,64 @@
+import { fail } from '../core/errors.mjs';
+
+export function object(value, allowed, code = 'invalid_doctor_options') {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+      Reflect.ownKeys(value).some(key => typeof key !== 'string' || !allowed.includes(key))) fail(code);
+  return value;
+}
+
+export function hostname(value, underscore = false) {
+  if (typeof value !== 'string' || value.length > 253) fail('invalid_doctor_domain');
+  const name = value.toLowerCase().replace(/\.$/, '');
+  const label = underscore ? /^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/ : /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+  if (!name.includes('.') || !name.split('.').every(part => label.test(part)) || /^\d+(\.\d+)+$/.test(name)) fail('invalid_doctor_domain');
+  return name;
+}
+
+export function integer(value, min, max, code) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail(code);
+  return value;
+}
+
+export function credential(value) {
+  if (typeof value !== 'string' || !value || value.length > 4096 || /\s|[\x00-\x1f\x7f]/.test(value)) fail('doctor_credential_required');
+  return value;
+}
+
+// Both the request and body read share a deadline. Never include remote errors.
+export async function bounded(operation, timeoutMs, code = 'doctor_timeout') {
+  const controller = new AbortController();
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => operation(controller.signal)),
+      new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error(code)); }, timeoutMs); }),
+    ]);
+  } finally { clearTimeout(timer); }
+}
+
+export async function readJson(response, maxBytes = 262144) {
+  if (!response.body || (Number(response.headers.get('content-length')) > maxBytes)) fail('doctor_response_limit');
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) fail('doctor_response_limit');
+      chunks.push(value);
+    }
+  } catch { void reader.cancel().catch(() => {}); fail('doctor_response_invalid'); }
+  finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { fail('doctor_response_invalid'); }
+}
+
+export async function digest(value) {
+  const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
+  return [...new Uint8Array(bytes)].map(byte => byte.toString(16).padStart(2, '0')).join('');
+}