@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/mail/src/events/d1-storage.mjs

@@ -0,0 +1,76 @@
+import { fail } from '../core/errors.mjs';
+
+const terminal = new Set(['delivered', 'bounced', 'failed', 'rejected', 'complained']);
+// Only this constructor's stores can be passed as the intake's explicit store.
+const stores = new WeakSet();
+export const isD1EventStore = store => stores.has(store);
+const receipt = `INSERT INTO rer_mail_event_receipts
+  (provider, tenant_id, event_namespace, event_id, fingerprint, event_json, commit_token, ordinal)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(provider, tenant_id, event_namespace, event_id) DO UPDATE SET conflict = 1
+    WHERE rer_mail_event_receipts.fingerprint <> excluded.fingerprint
+  RETURNING event_id`;
+const state = `INSERT INTO rer_mail_event_states
+  (provider, tenant_id, event_namespace, provider_message_id, recipient, status, occurred_at, event_id, terminal)
+  SELECT ?, ?, ?, ?, ?, ?, ?, ?, ? WHERE EXISTS (
+    SELECT 1 FROM rer_mail_event_receipts WHERE provider = ? AND tenant_id = ? AND event_namespace = ?
+      AND event_id = ? AND commit_token = ? AND ordinal = ?)
+  ON CONFLICT(provider, tenant_id, event_namespace, provider_message_id, recipient) DO UPDATE SET
+    status = excluded.status, occurred_at = excluded.occurred_at, event_id = excluded.event_id, terminal = excluded.terminal
+  WHERE (excluded.terminal = 1 AND rer_mail_event_states.terminal = 0)
+     OR (excluded.occurred_at > rer_mail_event_states.occurred_at
+         AND (rer_mail_event_states.terminal = 0 OR excluded.terminal = 1))
+  RETURNING status, occurred_at, event_id`;
+const read = `SELECT status, occurred_at, event_id FROM rer_mail_event_states
+  WHERE provider = ? AND tenant_id = ? AND event_namespace = ? AND provider_message_id = ? AND recipient = ?`;
+function conflict(error) {
+  for (let current = error, count = 0; current && count < 5; current = current.cause, count++) {
+    if (typeof current.message === 'string' && current.message.includes('rer_mail_event_identity_conflict')) return true;
+  }
+  return false;
+}
+/** D1 batch is one real SQL transaction. No read-before-write and no mutex. */
+export function createD1EventStore({ db } = {}) {
+  if (!db || typeof db.prepare !== 'function' || typeof db.batch !== 'function') fail('event_storage_required');
+  const store = Object.freeze({
+    async commit(events) {
+      try {
+        const token = crypto.randomUUID();
+        const statements = [], layout = [];
+        for (const [ordinal, event] of events.entries()) {
+          const scope = [event.provider, event.tenantId, event.eventNamespace];
+          const entry = { eventId: event.eventId, receipt: statements.length, recipients: [] };
+          statements.push(db.prepare(receipt).bind(...scope, event.eventId, event.fingerprint, JSON.stringify(event), token, ordinal));
+          for (const recipient of event.recipients) {
+            const indices = { recipient, update: null, read: null };
+            if (event.status !== null) {
+              indices.update = statements.length;
+              statements.push(db.prepare(state).bind(...scope, event.providerMessageId, recipient, event.status,
+                event.occurredAt, event.eventId, terminal.has(event.status) ? 1 : 0,
+                ...scope, event.eventId, token, ordinal));
+            }
+            indices.read = statements.length;
+            statements.push(db.prepare(read).bind(...scope, event.providerMessageId, recipient));
+            entry.recipients.push(indices);
+          }
+          layout.push(entry);
+        }
+        if (!statements.length) return [];
+        const results = await db.batch(statements);
+        if (results.some(result => result.success === false)) throw new Error();
+        return layout.map(entry => {
+          if (!results[entry.receipt].results.length) return { eventId: entry.eventId, outcome: 'duplicate', recipients: [] };
+          return { eventId: entry.eventId, outcome: 'stored', recipients: entry.recipients.map(item => {
+            const row = results[item.read].results[0];
+            return { recipient: item.recipient, applied: item.update !== null && results[item.update].results.length > 0,
+              state: row ? { status: row.status, occurredAt: row.occurred_at, eventId: row.event_id } : null };
+          }) };
+        });
+      } catch (error) {
+        fail(conflict(error) ? 'event_identity_conflict' : 'event_storage_failed');
+      }
+    },
+  });
+  stores.add(store);
+  return store;
+}

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

@@ -0,0 +1,3 @@
+export { verifyWebhook, MAX_WEBHOOK_BYTES } from './verify.mjs';
+export { createDeliveryEventIntake } from './intake.mjs';
+export { createD1EventStore } from './d1-storage.mjs';

package/modules/mail/src/events/intake.mjs

@@ -0,0 +1,201 @@
+import { fail } from '../core/errors.mjs';
+import { parseAddress } from '../core/validation.mjs';
+import { verifyWebhook } from './verify.mjs';
+import { createDurableEventStore } from './storage.mjs';
+import { isD1EventStore } from './d1-storage.mjs';
+import { pinnedKeys, verifyEventJws } from '../adapters/messaging/jws.mjs';
+import { serviceOrigin, identity, closed } from '../adapters/messaging/contract.mjs';
+import { messagingEvent } from '../adapters/messaging/event-schema.mjs';
+
+const MAX_EVENT_BYTES = 1024 * 1024;
+const MAX_EVENTS = 1000;
+const encoder = new TextEncoder();
+const sgStatuses = { processed: 'accepted', deferred: 'deferred', delivered: 'delivered', bounce: 'bounced', dropped: 'rejected', spamreport: 'complained', open: null, click: null, unsubscribe: null, group_unsubscribe: null, group_resubscribe: null };
+const resendStatuses = { 'email.sent': 'accepted', 'email.delivery_delayed': 'deferred', 'email.delivered': 'delivered', 'email.bounced': 'bounced', 'email.failed': 'failed', 'email.suppressed': 'rejected', 'email.complained': 'complained', 'email.opened': null, 'email.clicked': null };
+const cfStatuses = new Set(['delivered', 'deferred', 'bounced', 'failed', 'rejected', 'complained']);
+
+function bounded(value, max = 512) {
+  if (typeof value !== 'string' || !value.length || value.length > max || value.trim() !== value || /[\x00-\x1f\x7f]/.test(value)) fail('invalid_event_identity');
+  return value;
+}
+function object(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('invalid_event_schema');
+  return value;
+}
+function recipient(value) {
+  const parsed = parseAddress(value);
+  if (parsed.name || parsed.email !== value) fail('invalid_event_recipient');
+  // Preserve local-part case; lowering it can merge distinct mailbox identities.
+  return value;
+}
+function epoch(value, now) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > now + 300_000) fail('invalid_event_timestamp');
+  return value;
+}
+function date(value, now) {
+  if (typeof value !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)$/.test(value)) fail('invalid_event_timestamp');
+  const day = new Date(`${value.slice(0, 10)}T00:00:00.000Z`);
+  if (!Number.isFinite(day.getTime()) || day.toISOString().slice(0, 10) !== value.slice(0, 10) ||
+      Number(value.slice(11, 13)) > 23 || Number(value.slice(14, 16)) > 59 || Number(value.slice(17, 19)) > 59) fail('invalid_event_timestamp');
+  return epoch(Date.parse(value), now);
+}
+async function fingerprint(bytes) {
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+// Called only on already authenticated, successfully parsed JSON arrays. Slice
+// each original event, so batching/reordering does not alter an event fingerprint.
+function eventSlices(text) {
+  const slices = [];
+  let depth = 0, quoted = false, escaped = false, start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') quoted = false;
+      continue;
+    }
+    if (char === '"') quoted = true;
+    else if (char === '[' || char === '{') {
+      if (depth === 1) start = i;
+      depth++;
+    } else if (char === ']' || char === '}') {
+      depth--;
+      if (depth === 1) slices.push(text.slice(start, i + 1));
+    }
+  }
+  return slices;
+}
+
+/** Only returned intake methods can reach these private normalizers. */
+function sendgrid(event, now) {
+  object(event);
+  if (!Object.hasOwn(sgStatuses, event.event)) fail('unsupported_delivery_event');
+  if (!Number.isSafeInteger(event.timestamp) || event.timestamp < 0) fail('invalid_event_timestamp');
+  return {
+    eventId: bounded(event.sg_event_id), providerMessageId: bounded(event.sg_message_id, 1024),
+    type: event.event, status: sgStatuses[event.event], occurredAt: epoch(event.timestamp * 1000, now),
+    recipients: [recipient(event.email)],
+    deliveryId: event.rer_delivery_id === undefined ? null : bounded(event.rer_delivery_id),
+    product: event.rer_product === undefined ? null : bounded(event.rer_product),
+  };
+}
+function resend(event, headers, now) {
+  object(event); object(event.data);
+  if (!Object.hasOwn(resendStatuses, event.type)) fail('unsupported_delivery_event');
+  if (!Array.isArray(event.data.to) || !event.data.to.length || event.data.to.length > MAX_EVENTS) fail('invalid_event_recipients');
+  const recipients = event.data.to.map(recipient);
+  if (new Set(recipients).size !== recipients.length) fail('invalid_event_recipients');
+  return {
+    eventId: bounded(headers.get('svix-id')), providerMessageId: bounded(event.data.email_id, 1024),
+    type: event.type, status: resendStatuses[event.type], occurredAt: date(event.created_at, now),
+    recipients, deliveryId: null, product: null,
+  };
+}
+function cloudflare(event, source, now) {
+  object(event); object(event.source); object(event.metadata); object(event.payload); object(event.payload.delivery);
+  const status = event.payload.delivery.status;
+  if (!cfStatuses.has(status) || event.type !== `cf.email.sending.message.${status}` ||
+      event.payload.terminal !== (status !== 'deferred') || event.metadata.eventSchemaVersion !== 1 ||
+      event.source.type !== 'email.sending') fail('invalid_event_schema');
+  if (event.source.zoneId !== source.zoneId || event.source.domain !== source.domain ||
+      event.metadata.accountId !== source.accountId || event.metadata.eventSubscriptionId !== source.eventSubscriptionId) fail('event_source_unauthorized');
+  return {
+    eventId: bounded(event.payload.eventId), providerMessageId: bounded(event.payload.messageId, 1024),
+    type: event.type, status, occurredAt: date(event.metadata.eventTimestamp, now),
+    recipients: [recipient(event.payload.recipient)], deliveryId: null, product: null,
+  };
+}
+
+export function createDeliveryEventIntake(options) {
+  object(options);
+  const { provider, key, storage, authorize, clock = Date.now, toleranceSeconds = 300 } = options;
+  const tenantId = bounded(options.tenantId, 256);
+  const eventNamespace = bounded(options.eventNamespace, 256);
+  if (!['sendgrid', 'resend', 'cloudflare', 'messaging'].includes(provider) || typeof authorize !== 'function' || typeof clock !== 'function') fail('invalid_event_config');
+  if (!Number.isSafeInteger(toleranceSeconds) || toleranceSeconds < 0 || toleranceSeconds > 3600) fail('invalid_event_config');
+  if (['sendgrid', 'resend'].includes(provider) && (typeof key !== 'string' || !key.length)) fail('event_key_required');
+  if (['cloudflare', 'messaging'].includes(provider) && key !== undefined) fail('unsupported_event_key');
+  if (options.store !== undefined && (storage !== undefined || !isD1EventStore(options.store))) fail('invalid_event_store');
+  const store = options.store ?? createDurableEventStore(storage);
+  let messagingSource;
+  if (provider === 'messaging') {
+    const source = closed(options.messagingSource, ['serviceOrigin', 'installId', 'jwks'], 'invalid_event_config');
+    if (options.mode !== undefined && !['production', 'development', 'test'].includes(options.mode)) fail('invalid_event_config');
+    messagingSource = { serviceOrigin: serviceOrigin(source.serviceOrigin, options.mode ?? 'production'),
+      installId: identity(source.installId, 256), jwks: pinnedKeys(source.jwks) };
+  }
+  const source = provider === 'cloudflare' ? { ...object(options.cloudflareSource) } : null;
+  if (source) {
+    for (const field of ['queue', 'zoneId', 'domain', 'accountId', 'eventSubscriptionId']) bounded(source[field]);
+  }
+  function now() {
+    let value;
+    try { value = clock(); } catch { fail('invalid_event_clock'); }
+    if (!Number.isSafeInteger(value) || value < 0) fail('invalid_event_clock');
+    return value;
+  }
+  async function persist(records) {
+    // Complete schema/authorization of the whole batch before the first write.
+    for (const event of records) {
+      Object.freeze(event.recipients); if (event.detail) Object.freeze(event.detail); Object.freeze(event);
+      let permitted;
+      try { permitted = await authorize(event); } catch { fail('event_unauthorized'); }
+      if (permitted !== true) fail('event_unauthorized');
+    }
+    return store.commit(records);
+  }
+  async function record(event, bytes) {
+    return { ...event, provider, tenantId, eventNamespace, fingerprint: await fingerprint(bytes) };
+  }
+  if (provider === 'cloudflare') return Object.freeze({
+    async consumeQueue(batch) {
+      // This method is solely for the trusted Worker queue handler. Runtime
+      // objects are not an HTTP authentication protocol (see README).
+      if (!batch || batch.queue !== source.queue || !Array.isArray(batch.messages) ||
+          !batch.messages.length || batch.messages.length > MAX_EVENTS) fail('invalid_event_queue');
+      const timestamp = now();
+      const pending = [];
+      let total = 0;
+      for (const message of batch.messages) {
+        object(message);
+        let text, event;
+        try { text = JSON.stringify(message.body); event = JSON.parse(text); } catch { fail('invalid_event_schema'); }
+        const bytes = encoder.encode(text); total += bytes.length;
+        if (total > MAX_EVENT_BYTES) fail('event_body_too_large');
+        pending.push([cloudflare(event, source, timestamp), bytes]);
+      }
+      return persist(await Promise.all(pending.map(([event, bytes]) => record(event, bytes))));
+      // Caller ACKs only after resolution; throws leave the queue retryable.
+    },
+  });
+  return Object.freeze({
+    async ingestWebhook(input) {
+      if (!(input?.rawBody instanceof Uint8Array) || input.rawBody.length > MAX_EVENT_BYTES || !(input.headers instanceof Headers)) fail('invalid_event_input');
+      const rawBody = new Uint8Array(input.rawBody);
+      const headers = new Headers(input.headers);
+      const timestamp = now();
+      if (provider === 'messaging') {
+        const events = await verifyEventJws(rawBody, messagingSource, timestamp);
+        if (!Array.isArray(events) || !events.length || events.length > MAX_EVENTS) fail('invalid_event_batch');
+        const normalized = events.map(event => messagingEvent(event, timestamp));
+        return persist(await Promise.all(normalized.map(event => record({
+          eventId: event.id, providerMessageId: event.messageId, deliveryId: event.deliveryId,
+          type: event.type, status: event.type === 'suppressed' ? 'rejected' : event.type,
+          occurredAt: Date.parse(event.occurredAt), recipients: [event.recipient], product: null, detail: event.detail,
+        }, encoder.encode(JSON.stringify(event))))));
+      }
+      if (!await verifyWebhook({ provider, rawBody, headers, key, now: timestamp, toleranceSeconds })) fail('event_signature_invalid');
+      let text, payload;
+      try { text = new TextDecoder('utf-8', { fatal: true }).decode(rawBody); payload = JSON.parse(text); } catch { fail('invalid_event_json'); }
+      if (provider === 'resend') return persist([await record(resend(payload, headers, timestamp), rawBody)]);
+      if (!Array.isArray(payload) || !payload.length || payload.length > MAX_EVENTS) fail('invalid_event_batch');
+      const normalized = payload.map(event => sendgrid(event, timestamp));
+      const slices = eventSlices(text);
+      if (slices.length !== normalized.length) fail('invalid_event_batch');
+      return persist(await Promise.all(normalized.map((event, index) => record(event, encoder.encode(slices[index])))));
+    },
+  });
+}

package/modules/mail/src/events/storage.mjs

@@ -0,0 +1,52 @@
+import { fail, MailValidationError } from '../core/errors.mjs';
+
+const terminal = new Set(['delivered', 'bounced', 'failed', 'rejected', 'complained']);
+
+/** A real DurableObjectStorage transaction; no process-local deduplication. */
+export function createDurableEventStore(storage) {
+  if (!storage || typeof storage.transaction !== 'function') fail('event_storage_required');
+  return Object.freeze({
+    async commit(events) {
+      try {
+        return await storage.transaction(async tx => {
+          const results = [];
+          for (const event of events) {
+            const namespace = [event.provider, event.tenantId, event.eventNamespace];
+            const receiptKey = await key('receipt', [...namespace, event.eventId]);
+            const prior = await tx.get(receiptKey);
+            if (prior) {
+              if (prior.fingerprint !== event.fingerprint) fail('event_identity_conflict');
+              results.push({ eventId: event.eventId, outcome: 'duplicate', recipients: [] });
+              continue;
+            }
+            const recipients = [];
+            for (const recipient of event.recipients) {
+              const stateKey = await key('state', [...namespace, event.providerMessageId, recipient]);
+              const previous = await tx.get(stateKey);
+              // Final delivery facts never become accepted/deferred. Newer terminal
+              // facts (e.g. a later complaint) may supersede earlier terminal facts.
+              const apply = event.status !== null && (!previous ||
+                (terminal.has(event.status) && !terminal.has(previous.status)) ||
+                (event.occurredAt > previous.occurredAt &&
+                (!terminal.has(previous.status) || terminal.has(event.status))));
+              const state = apply ? { status: event.status, occurredAt: event.occurredAt, eventId: event.eventId } : previous ?? null;
+              if (apply) await tx.put(stateKey, state);
+              recipients.push({ recipient, applied: apply, state });
+            }
+            await tx.put(receiptKey, event);
+            results.push({ eventId: event.eventId, outcome: 'stored', recipients });
+          }
+          return results;
+        });
+      } catch (error) {
+        if (error instanceof MailValidationError && error.code === 'event_identity_conflict') throw error;
+        fail('event_storage_failed');
+      }
+    },
+  });
+}
+
+async function key(kind, tuple) {
+  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(tuple)));
+  return `mail-events:v1:${kind}:${Array.from(new Uint8Array(hash), byte => byte.toString(16).padStart(2, '0')).join('')}`;
+}

package/modules/mail/src/events/verify.mjs

@@ -0,0 +1,92 @@
+import { encodeBase64 } from '../core/validation.mjs';
+
+// Inbound Parse also uses this verifier; delivery intake applies a smaller cap.
+export const MAX_WEBHOOK_BYTES = 32 * 1024 * 1024;
+const encoder = new TextEncoder();
+
+function base64(value, max) {
+  if (typeof value !== 'string' || !value.length || value.length > max ||
+      !/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 === 1) throw new Error();
+  const bytes = Uint8Array.from(atob(value), c => c.charCodeAt(0));
+  const canonical = encodeBase64(bytes);
+  if (value !== canonical && value !== canonical.replace(/=+$/, '')) throw new Error();
+  return bytes;
+}
+
+/** Strict DER INTEGERs; WebCrypto expects fixed-width unsigned r || s. */
+function derToP1363(bytes) {
+  if (bytes.length < 8 || bytes.length > 72 || bytes[0] !== 0x30 || bytes[1] !== bytes.length - 2) throw new Error();
+  const result = new Uint8Array(64);
+  let offset = 2;
+  for (let part = 0; part < 2; part++) {
+    if (bytes[offset++] !== 2) throw new Error();
+    const length = bytes[offset++];
+    if (!length || length > 33 || offset + length > bytes.length) throw new Error();
+    let integer = bytes.subarray(offset, offset + length);
+    offset += length;
+    if (integer[0] & 0x80) throw new Error();
+    if (integer[0] === 0 && integer.length > 1) {
+      if (!(integer[1] & 0x80)) throw new Error();
+      integer = integer.subarray(1);
+    }
+    if (integer.length > 32 || integer.every(byte => byte === 0)) throw new Error();
+    result.set(integer, part * 32 + 32 - integer.length);
+  }
+  if (offset !== bytes.length) throw new Error();
+  return result;
+}
+
+function signedBytes(prefix, raw) {
+  const first = encoder.encode(prefix);
+  const bytes = new Uint8Array(first.length + raw.length);
+  bytes.set(first); bytes.set(raw, first.length);
+  return bytes;
+}
+
+export async function verifyWebhook(input) {
+  try {
+    const { provider, rawBody, headers, key, now, toleranceSeconds = 300 } = input;
+    if (!['sendgrid', 'resend'].includes(provider) || !(rawBody instanceof Uint8Array) ||
+        rawBody.length > MAX_WEBHOOK_BYTES || !(headers instanceof Headers) ||
+        !Number.isSafeInteger(now) || now < 0 || !Number.isSafeInteger(toleranceSeconds) ||
+        toleranceSeconds < 0 || toleranceSeconds > 3600) return false;
+    // Copy before the first await; callers cannot mutate the verified bytes mid-flight.
+    const raw = new Uint8Array(rawBody);
+    const timestamp = headers.get(provider === 'sendgrid' ? 'x-twilio-email-event-webhook-timestamp' : 'svix-timestamp');
+    if (!/^(0|[1-9][0-9]{0,12})$/.test(timestamp ?? '')) return false;
+    const milliseconds = Number(timestamp) * 1000;
+    if (!Number.isSafeInteger(milliseconds) || Math.abs(now - milliseconds) > toleranceSeconds * 1000) return false;
+    if (provider === 'sendgrid') {
+      const spki = base64(key, 256);
+      const signature = derToP1363(base64(headers.get('x-twilio-email-event-webhook-signature'), 128));
+      const publicKey = await crypto.subtle.importKey('spki', spki, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['verify']);
+      // Reject trailing bytes, alternate/noncanonical ASN.1, and wrong algorithms.
+      const exported = new Uint8Array(await crypto.subtle.exportKey('spki', publicKey));
+      if (encodeBase64(spki) !== encodeBase64(exported)) return false;
+      return await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, publicKey, signature, signedBytes(timestamp, raw));
+    }
+    const id = headers.get('svix-id');
+    const signatures = headers.get('svix-signature');
+    if (!/^[A-Za-z0-9_-]{1,512}$/.test(id ?? '') || typeof key !== 'string' || !key.startsWith('whsec_') ||
+        !signatures || signatures.length > 4096) return false;
+    const secret = base64(key.slice(6), 128);
+    if (secret.length < 16 || secret.length > 64) return false;
+    const tokens = signatures.split(' ');
+    if (tokens.length > 16) return false;
+    // Validate the entire header, including entries after a valid rotation key.
+    const candidates = tokens.map(token => {
+      const match = /^(v[1-9][0-9]*),([A-Za-z0-9+/]+={0,2})$/.exec(token);
+      if (!match) throw new Error();
+      const bytes = base64(match[2], 256);
+      if (match[1] === 'v1' && bytes.length !== 32) throw new Error();
+      return { version: match[1], bytes };
+    });
+    const hmac = await crypto.subtle.importKey('raw', secret, { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const signed = signedBytes(`${id}.${timestamp}.`, raw);
+    let verified = false;
+    for (const candidate of candidates) {
+      if (candidate.version === 'v1') verified = (await crypto.subtle.verify('HMAC', hmac, candidate.bytes, signed)) || verified;
+    }
+    return verified;
+  } catch { return false; }
+}

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

@@ -0,0 +1,137 @@
+# Inbound normalization
+
+Import `normalizeInbound` from `modules/mail/src/inbound/index.mjs` (also exposed
+by the assembled mail facade). It returns the frozen `InboundMessage` contract.
+These are transport parsers, not authentication or HTTP handlers. No route or
+persistent storage is installed. HTML, text, filenames and sender claims remain
+untrusted content; the consuming application owns rendering sanitization,
+authorization, deduplication, durable quarantine and sender-authentication policy.
+
+## Trust boundary and provider inputs
+
+- Cloudflare: call only from the Worker `email(message, env, ctx)` event, passing
+  `{provider:'cloudflare', message}`. The real `raw` byte stream is parsed; its
+  actual length must equal `rawSize`. `from` and `to` are the SMTP envelope values.
+  Headers and threading come from the original MIME stream, avoiding synthetic
+  JSON conversion and duplicate-header loss through `Headers`.
+- SendGrid: bound and retain the original HTTP multipart bytes, authenticate
+  those exact bytes with the configured Inbound Parse signature key, then pass
+  `{provider:'sendgrid', rawBody:Uint8Array, contentType}`. Never call parsing or
+  store/hydrate a message before successful verification. The normalizer accepts
+  both parsed fields/binary attachment parts and the provider's raw `email`
+  field. Duplicate fields, mismatched attachment counts/metadata, malformed
+  boundaries and invalid transfer encoding reject the whole message.
+- Resend: verify the exact Svix webhook bytes, validate `type:'email.received'`,
+  and extract the authenticated event's `data.email_id`. Only then retrieve
+  `GET https://api.resend.com/emails/receiving/{email_id}?html_format=cid` using
+  the fixed API origin, an authorized server credential, a bounded response
+  reader, a deadline and `redirect:'manual'`. Pass the response object as `email`
+  and the original authenticated ID as **`signedEmailId`**. The normalizer
+  requires `email.id === signedEmailId` before any attachment callback. Do not
+  fill `signedEmailId` from the hydrated response. Requesting `html_format=cid`
+  preserves original inline image references across providers; the normalizer
+  preserves the returned HTML and does not rewrite provider data-URI HTML.
+
+A successful webhook signature authenticates the provider's transport, not the
+person named in the mail's From header. Supplying a `signedEmailId` value does
+not perform cryptographic verification; the verified caller is the trust boundary.
+The events unit owns `verifyWebhook`. This unit neither fabricates verification
+nor retries a failed transport.
+
+## Resend attachment hydration
+
+Resend's received-email response contains attachment metadata, not file bytes.
+Every entry requires `id`, `filename`, `content_type`, a nonnegative integer
+`size`, and optional `content_disposition` / `content_id`. Supply an asynchronous
+`fetchAttachment(attachment) -> Uint8Array` on the input when attachments exist.
+The callback receives a frozen object containing only
+`{emailId,id,filename,content_type,content_disposition,content_id,size}`. Provider
+IDs are bounded safe path segments; URLs and arbitrary response fields are not
+passed through. All message metadata and declared aggregate limits are checked
+before the first callback. Missing hydration, duplicate IDs, oversized bytes,
+or actual length differing from `size` fail the entire result. Callbacks must
+be read-only: an eventual failure cannot undo a caller's storage side effects.
+
+A real safe implementation is included:
+
+```js
+import { normalizeInbound, createResendAttachmentFetcher } from './index.mjs';
+// After verified event validation and identity-bound email retrieval:
+const fetchAttachment = createResendAttachmentFetcher({
+  apiKey, maxAttachmentBytes: limits.maxAttachmentBytes,
+});
+const message = await normalizeInbound({
+  provider: 'resend', signedEmailId, email, fetchAttachment,
+}, limits);
+```
+
+`createResendAttachmentFetcher({apiKey,maxAttachmentBytes}, {fetch?,clock?})`
+uses the fixed Resend attachment API and verifies returned ID, filename, MIME
+metadata and size against the received-email entry. It permits only the documented
+`https://inbound-cdn.resend.com/{emailId}/attachments/{id}` download location,
+requires an unexpired URL, refuses redirects on both requests, and sends the
+API credential only to `api.resend.com`. The download request has no authorization
+headers. API metadata is bounded to 64 KiB; streamed content is bounded by the
+expected size and configured attachment limit. One 15-second abort deadline
+covers both requests and bodies. Errors are fixed and redacted. There is no
+configurable arbitrary download origin. A provider CDN contract change fails
+closed and requires an explicit source update.
+
+A custom callback must enforce the same identity/metadata, origin, redirect,
+timeout and streaming checks. A callback is trusted application code, not
+untrusted webhook input. Neither helper retrieves email metadata before the
+caller has verified the webhook.
+
+## Limits and normalization details
+
+All five limit values must be positive safe integers. Exact limits succeed.
+`maxRawBytes` measures actual Cloudflare stream bytes or SendGrid multipart bytes,
+and checks Cloudflare's claimed size too. For Resend's object input it measures
+the UTF-8 JSON serialization of the hydrated response; this is not a claim to
+have inspected the original SMTP message or the original HTTP whitespace.
+The caller must also bound the actual HTTP response stream during hydration.
+Downloaded files have separate individual and aggregate actual-byte limits.
+
+`maxBodyBytes` is aggregate text plus HTML, checked against both decoded source
+bytes and the resulting UTF-8 bytes (the larger size for each body part).
+`maxAttachments`, `maxAttachmentBytes`, and `maxTotalAttachmentBytes` apply to
+all decoded files, including inline and unnamed MIME parts. Both claimed Resend
+sizes and actual hydrated bytes are checked. Results are returned only after
+all parsing and hydration succeeds; errors never contain partial messages.
+Oversized Cloudflare/download streams are cancelled.
+
+MIME supports nested multipart alternatives/mixed/related, folded headers,
+RFC 2047 encoded words, RFC 2231 extended/continued filenames, base64,
+quoted-printable, 7bit/8bit/binary and Web `TextDecoder` character sets. Invalid
+encodings, duplicate singleton headers, incomplete multiparts and nesting over
+30 levels fail closed. Multiple body parts of the same media type are joined
+with a newline, which also counts toward the output body limit. Unsupported
+media types are retained as attachments instead of silently discarded.
+
+Output addresses are mailbox addresses (display names are parsed but not
+returned). Cloudflare uses its event envelope; SendGrid and Resend use their
+provided sender/recipient fields. Empty subjects are preserved; absent optional
+thread/body fields use null or empty arrays. Message-ID and ordered References
+retain their angle-bracket values. Content-IDs are normalized without angle
+brackets; an absent content ID is null. Unnamed MIME files retain filename `''`.
+No caller-owned input objects or attachment buffers are mutated.
+
+## Checks and references
+
+From the Base worktree:
+
+```sh
+node --test modules/mail/tests/inbound/normalization.test.mjs modules/mail/tests/inbound/boundaries.test.mjs modules/mail/tests/inbound/hydration.test.mjs
+node --test modules/mail/tests/inbound/workerd.test.mjs
+```
+
+The latter uses actual workerd through the module's Miniflare harness without
+Node compatibility, with three provider fixtures and the safe hydration protocol.
+Fixtures and provider responses live only under `./tests/inbound`. These checks do
+not prove hosted mail receipt; owner-authorized domain, provider configuration,
+signed routing and send/receive correlation evidence remain separate acceptance.
+
+Provider schemas consulted: [Cloudflare email event](https://developers.cloudflare.com/email-service/api/route-emails/email-handler/),
+[SendGrid Inbound Parse fields](https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/setting-up-the-inbound-parse-webhook),
+[Resend received email](https://resend.com/docs/api-reference/emails/retrieve-received-email),
+and [Resend attachment metadata/download](https://resend.com/docs/api-reference/emails/retrieve-received-email-attachment).

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

@@ -0,0 +1,91 @@
+import { fail } from '../core/errors.mjs';
+import { encodeBase64 } from '../core/validation.mjs';
+export const utf8 = new TextEncoder();
+export function record(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail('invalid_inbound');
+  return value;
+}
+export function limitsFor(value) {
+  record(value);
+  for (const key of ['maxRawBytes', 'maxBodyBytes', 'maxAttachments', 'maxAttachmentBytes', 'maxTotalAttachmentBytes']) {
+    if (!Number.isSafeInteger(value[key]) || value[key] <= 0) fail('invalid_inbound_limits');
+  }
+  return { ...value };
+}
+export function bounded(size, limit, code) { if (size > limit) fail(code); }
+export function binary(bytes) {
+  let value = '';
+  for (let i = 0; i < bytes.length; i += 8192) value += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  return value;
+}
+export const unbinary = value => Uint8Array.from(value, c => c.charCodeAt(0));
+export function decode(bytes, charset = 'utf-8') {
+  try { return new TextDecoder(charset, { fatal: true }).decode(bytes); } catch { fail('invalid_inbound_charset'); }
+}
+export function base64(value) {
+  const compact = value.replace(/[\r\n\t ]/g, '');
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(compact)) fail('invalid_inbound_base64');
+  let bytes;
+  try { bytes = unbinary(atob(compact)); } catch { fail('invalid_inbound_base64'); }
+  if (encodeBase64(bytes) !== compact) fail('invalid_inbound_base64');
+  return bytes;
+}
+export function quotedPrintable(value, word = false) {
+  const source = word ? value.replace(/_/g, ' ') : value;
+  let result = '';
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] !== '=') {
+      if (/[^\x20-\x7e\t\r\n]/.test(source[i])) fail('invalid_inbound_encoding');
+      result += source[i]; continue;
+    }
+    const next = source.slice(i + 1, i + 3);
+    if (!word && next === '\r\n') { i += 2; continue; }
+    if (!word && source[i + 1] === '\n') { i++; continue; }
+    if (!/^[a-f0-9]{2}$/i.test(next)) fail('invalid_inbound_encoding');
+    result += String.fromCharCode(parseInt(next, 16)); i += 2;
+  }
+  return unbinary(result);
+}
+export function transfer(bytes, encoding = '7bit') {
+  switch (encoding.toLowerCase()) {
+    case 'base64': return base64(binary(bytes));
+    case 'quoted-printable': return quotedPrintable(binary(bytes));
+    case '7bit': if (bytes.some(byte => byte > 127)) fail('invalid_inbound_encoding'); return bytes;
+    case '8bit': case 'binary': return bytes;
+    default: fail('invalid_inbound_encoding');
+  }
+}
+export async function readStream(stream, max) {
+  if (!stream || typeof stream.getReader !== 'function') fail('invalid_inbound_stream');
+  const reader = stream.getReader(); const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!(value instanceof Uint8Array)) fail('invalid_inbound_stream');
+      size += value.byteLength; bounded(size, max, 'inbound_raw_limit'); chunks.push(value.slice());
+    }
+  } catch (error) {
+    try { await reader.cancel(); } catch { /* Preserve the original redacted failure. */ }
+    throw error;
+  } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+  return bytes;
+}
+export function bodyBudget(limits) {
+  let bodySize = 0, attachmentSize = 0, attachmentCount = 0;
+  return {
+    body(text, originalSize = 0) {
+      bodySize += Math.max(originalSize, utf8.encode(text).length);
+      bounded(bodySize, limits.maxBodyBytes, 'inbound_body_limit');
+    },
+    attachment(bytes) {
+      if (!(bytes instanceof Uint8Array)) fail('invalid_inbound_attachment');
+      bounded(++attachmentCount, limits.maxAttachments, 'inbound_attachment_count');
+      bounded(bytes.length, limits.maxAttachmentBytes, 'inbound_attachment_limit');
+      attachmentSize += bytes.length;
+      bounded(attachmentSize, limits.maxTotalAttachmentBytes, 'inbound_attachments_limit');
+    },
+  };
+}