@runeditrun/rer 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,102 @@
+import { fail } from '../core/errors.mjs';
+import { bounded, hostname, readJson } from './common.mjs';
+import { record } from './records.mjs';
+
+const types = { MX: 15, TXT: 16, CNAME: 5 };
+
+// DNS presentation strings can contain several quoted character strings.
+export function decodeTxt(value) {
+  if (typeof value !== 'string' || value.length > 16384) fail('doctor_dns_response_invalid');
+  let result = '', offset = 0, chunks = 0;
+  while (offset < value.length) {
+    while (value[offset] === ' ') offset++;
+    if (offset === value.length) break;
+    if (value[offset++] !== '"') fail('doctor_dns_response_invalid');
+    chunks++;
+    let closed = false;
+    while (offset < value.length) {
+      const char = value[offset++];
+      if (char === '"') { closed = true; break; }
+      if (char !== '\\') { result += char; continue; }
+      if (offset === value.length) fail('doctor_dns_response_invalid');
+      const decimal = value.slice(offset, offset + 3);
+      if (/^\d{3}$/.test(decimal)) {
+        if (Number(decimal) > 255) fail('doctor_dns_response_invalid');
+        result += String.fromCharCode(Number(decimal)); offset += 3;
+      } else result += value[offset++];
+    }
+    if (!closed || (offset < value.length && value[offset] !== ' ')) fail('doctor_dns_response_invalid');
+  }
+  if (!chunks) fail('doctor_dns_response_invalid');
+  return result;
+}
+
+/** Fixed public DNS resolver: no caller-controlled host or credentials. */
+export async function resolveDns({ name, type, signal }, fetcher = globalThis.fetch) {
+  const url = new URL('https://cloudflare-dns.com/dns-query');
+  url.searchParams.set('name', name); url.searchParams.set('type', type);
+  const response = await fetcher(url, { headers: { accept: 'application/dns-json' }, redirect: 'manual', signal });
+  if (response.status !== 200) return { status: 'error' };
+  const data = await readJson(response, 65536);
+  if (!data || data.TC === true || ![0, 3].includes(data.Status)) return { status: 'error' };
+  if (data.Status === 3) return { status: 'missing', records: [] };
+  if (data.Answer !== undefined && (!Array.isArray(data.Answer) || data.Answer.length > 128)) return { status: 'error' };
+  const records = [];
+  for (const answer of data.Answer ?? []) {
+    if (answer.type !== types[type] || hostname(answer.name, true) !== name) continue;
+    let value = answer.data, priority;
+    if (type === 'TXT') value = decodeTxt(value);
+    if (type === 'MX') {
+      const parts = /^(\d+)\s+(\S+)$/.exec(value);
+      if (!parts) return { status: 'error' };
+      priority = Number(parts[1]); value = parts[2];
+    }
+    // A null MX explicitly means this name does not accept mail.
+    if (type === 'MX' && value === '.') continue;
+    records.push(record({ type, name, value, ...(priority === undefined ? {} : { priority }) }));
+  }
+  return { status: records.length ? 'ok' : 'missing', records };
+}
+
+function same(a, b) {
+  return a.type === b.type && a.name === b.name && a.value === b.value && a.priority === b.priority;
+}
+
+export async function checkDns(items, dependencies) {
+  const resolver = dependencies.resolveDns ?? (query => resolveDns(query, dependencies.fetch));
+  const cache = new Map();
+  function lookup(expected) {
+    const key = `${expected.type}:${expected.name}`;
+    if (!cache.has(key)) cache.set(key, bounded(signal => resolver({ name: expected.name, type: expected.type, signal }), 8000)
+      .then(result => {
+        if (!result || !['ok', 'missing', 'error'].includes(result.status)) return { status: 'error' };
+        if (result.status === 'error') return { status: 'error' };
+        if (!Array.isArray(result.records) || result.records.length > 128) return { status: 'error' };
+        const records = result.records.map(record).filter(item => item.name === expected.name && item.type === expected.type);
+        if (result.status === 'missing' && records.length) return { status: 'error' };
+        return { status: records.length ? 'ok' : 'missing', records };
+      }).catch(() => ({ status: 'error' })));
+    return cache.get(key);
+  }
+  return Promise.all(items.map(async item => {
+    if (!item.records.length) return item;
+    const checks = await Promise.all(item.records.map(async expected => {
+      const found = await lookup(expected);
+      let state = found.status === 'error' ? 'error' : found.status === 'missing' ? 'missing' : 'mismatch';
+      if (found.status === 'ok') {
+        const prefix = item.id === 'spf' ? /^v=spf1(?:\s|$)/i : item.id === 'dmarc' ? /^v=DMARC1;/i : null;
+        const policies = prefix ? found.records.filter(row => row.type === 'TXT' && prefix.test(row.value)) : [];
+        if (found.records.some(row => same(row, expected)) && policies.length <= 1) state = 'match';
+      }
+      return { type: expected.type, name: expected.name, state };
+    }));
+    const state = ['error', 'missing', 'mismatch'].find(value => checks.some(check => check.state === value)) ?? 'match';
+    const next = {
+      error: 'DNS lookup failed or returned malformed data. Check resolver availability and retry the DNS check; no record absence is inferred.',
+      missing: 'Publish the missing records from provider setup, allow DNS propagation, then check again.',
+      mismatch: 'Compare the published values and MX priorities with provider setup; remove duplicate SPF/DMARC policies and correct mismatches.',
+      match: 'The queried records match this setup plan. Verify provider domain status and actual delivered authentication separately.',
+    };
+    return { ...item, status: state === 'match' ? 'pass' : 'fail', nextSteps: [next[state]], evidence: { state, checks } };
+  }));
+}

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

@@ -0,0 +1,28 @@
+import { fail } from '../core/errors.mjs';
+import { hostname, object } from './common.mjs';
+import { recordPlan, dnsPlan } from './records.mjs';
+import { checkDns } from './dns.mjs';
+import { runProbe, validateProbe } from './probe.mjs';
+
+/** Portable structured setup diagnosis. No network operation without live:true. */
+export async function mailDoctor(options, dependencies = {}) {
+  object(options, ['domain', 'provider', 'dnsRecords', 'live', 'send', 'receive', 'timeoutMs', 'pollIntervalMs']);
+  const domain = hostname(options.domain);
+  if (!['sendgrid', 'resend', 'cloudflare'].includes(options.provider)) fail('invalid_doctor_provider');
+  if (options.live !== undefined && typeof options.live !== 'boolean') fail('invalid_doctor_live');
+  object(dependencies, ['fetch', 'resolveDns', 'sender'], 'invalid_doctor_dependencies');
+  if (dependencies.fetch !== undefined && typeof dependencies.fetch !== 'function' || dependencies.resolveDns !== undefined && typeof dependencies.resolveDns !== 'function') fail('invalid_doctor_dependencies');
+  const plan = recordPlan(options.dnsRecords);
+  let items = dnsPlan(domain, options.provider, plan);
+  if (options.live) {
+    // Validate every credential/address before DNS or sending has any effect.
+    const liveOptions = { ...options, domain };
+    validateProbe(liveOptions);
+    const [dns, probe] = await Promise.all([checkDns(items, dependencies), runProbe(liveOptions, dependencies)]);
+    items = [...dns, ...probe];
+  } else items.push(
+    { id: 'send', status: 'not_checked', nextSteps: ['Configure a verified sender and an explicit provider API credential; run the live test only for an owner-approved test inbox.'], evidence: { state: 'unchecked' } },
+    { id: 'receive', status: 'not_checked', nextSteps: ['Enable receiving on an owner test mailbox in Resend and configure its readback API credential; the live test matches a fresh random subject and body.'], evidence: { state: 'unchecked' } },
+  );
+  return { domain, provider: options.provider, items };
+}

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

@@ -0,0 +1,66 @@
+import { createMailSender } from '../sender.mjs';
+import { fail } from '../core/errors.mjs';
+import { parseAddress, validateConfig, validateSendResult } from '../core/validation.mjs';
+import { bounded, credential, digest, integer, object } from './common.mjs';
+import { receiveProbe } from './receive.mjs';
+
+export function validateProbe(options) {
+  object(options.send, ['config', 'from', 'to'], 'doctor_send_config_required');
+  validateConfig(options.send.config);
+  if (options.send.config.provider !== options.provider || options.send.config.mode !== 'production') fail('doctor_remote_production_required');
+  const from = parseAddress(options.send.from).email;
+  if (from.split('@')[1].toLowerCase() !== options.domain) fail('doctor_sender_domain_mismatch');
+  const to = parseAddress(options.send.to).email;
+  object(options.receive, ['provider', 'apiKey'], 'doctor_receive_config_required');
+  if (options.receive.provider !== 'resend') fail('doctor_receive_provider_unsupported');
+  credential(options.receive.apiKey);
+  return {
+    from, to,
+    timeoutMs: integer(options.timeoutMs ?? 60000, 100, 120000, 'invalid_doctor_timeout'),
+    pollIntervalMs: integer(options.pollIntervalMs ?? 2000, 100, 10000, 'invalid_doctor_poll_interval'),
+  };
+}
+
+export async function runProbe(options, dependencies) {
+  const config = validateProbe(options);
+  let sender;
+  try {
+    sender = dependencies.sender ?? createMailSender(options.send.config, { fetch: dependencies.fetch });
+    if (!sender || typeof sender.send !== 'function') fail('doctor_sender_unavailable');
+  } catch {
+    return [
+      { id: 'send', status: 'fail', nextSteps: ['Check sender configuration and install the complete mail module before retrying.'], evidence: { state: 'configuration_error' } },
+      { id: 'receive', status: 'not_checked', nextSteps: ['Complete sender configuration before testing receipt.'], evidence: { state: 'unchecked' } },
+    ];
+  }
+  const correlationId = crypto.randomUUID();
+  const probe = {
+    deliveryId: correlationId, from: config.from, to: [config.to],
+    subject: `Mail doctor ${correlationId}`,
+    text: `Mail doctor receive correlation: ${correlationId}`,
+  };
+  const startedAt = Date.now();
+  let result;
+  try {
+    result = validateSendResult(await bounded(() => sender.send(probe), 16000), options.provider);
+  } catch {
+    result = { provider: options.provider, status: 'uncertain', providerMessageId: null };
+  }
+  const accepted = result.status === 'accepted' && (!result.recipientResults ||
+    result.recipientResults.some(row => parseAddress(row.recipient).email.toLowerCase() === config.to.toLowerCase() && row.status === 'accepted'));
+  const send = {
+    id: 'send', status: accepted ? 'pass' : result.status === 'uncertain' ? 'pending' : 'fail',
+    nextSteps: [accepted ? 'The provider accepted the submission. Inspect independent mailbox receipt below.' :
+      result.status === 'uncertain' ? 'Submission is uncertain. Reconcile provider and mailbox records before any resend.' :
+      'The provider did not accept the test recipient. Check sender verification, credentials, limits and suppression; no retry was attempted.'],
+    evidence: {
+      state: result.status, recipientAccepted: accepted, correlationId,
+      providerMessageIdSha256: result.providerMessageId ? await digest(result.providerMessageId) : null,
+      startedAt: new Date(startedAt).toISOString(),
+    },
+  };
+  const receive = accepted || result.status === 'uncertain'
+    ? await receiveProbe({ apiKey: options.receive.apiKey, probe, startedAt, timeoutMs: config.timeoutMs, pollIntervalMs: config.pollIntervalMs }, dependencies)
+    : { id: 'receive', status: 'not_checked', nextSteps: ['Resolve the rejected submission before initiating another test.'], evidence: { state: 'unchecked' } };
+  return [send, receive];
+}

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

@@ -0,0 +1,81 @@
+import { fail } from '../core/errors.mjs';
+import { parseAddress } from '../core/validation.mjs';
+import { bounded, digest, readJson } from './common.mjs';
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function mailbox(value) {
+  try { return parseAddress(value).email.toLowerCase(); } catch { return null; }
+}
+function candidate(email, probe, startedAt, now) {
+  const received = Date.parse(email?.created_at);
+  return email && uuid.test(email.id) && email.subject === probe.subject &&
+    mailbox(email.from) === mailbox(probe.from) && Array.isArray(email.to) && email.to.some(value => mailbox(value) === mailbox(probe.to[0])) &&
+    Number.isFinite(received) && received >= startedAt - 1000 && received <= now + 1000;
+}
+
+/** Read received mail only; never read sent-message status as delivery proof. */
+export async function receiveProbe({ apiKey, probe, startedAt, timeoutMs, pollIntervalMs }, dependencies = {}) {
+  const deadline = Date.now() + timeoutMs;
+  const fetcher = dependencies.fetch ?? globalThis.fetch;
+  let polls = 0, requests = 0;
+  async function get(path) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) fail('doctor_receive_timeout');
+    requests++;
+    return bounded(async signal => {
+      const response = await fetcher(`https://api.resend.com${path}`, {
+        method: 'GET', redirect: 'manual', signal, headers: { authorization: `Bearer ${apiKey}` },
+      });
+      if (response.status !== 200) fail('doctor_readback_failed');
+      return readJson(response);
+    }, Math.min(8000, remaining));
+  }
+  try {
+    while (Date.now() < deadline && polls < 30) {
+      polls++;
+      let after = '';
+      for (let page = 0; page < 3; page++) {
+        const list = await get(`/emails/receiving?limit=100${after ? `&after=${after}` : ''}`);
+        if (!list || list.object !== 'list' || !Array.isArray(list.data) || list.data.length > 100 || typeof list.has_more !== 'boolean') fail('doctor_readback_failed');
+        for (const summary of list.data) {
+          if (!candidate(summary, probe, startedAt, Date.now())) continue;
+          const email = await get(`/emails/receiving/${summary.id}`);
+          if (email?.id !== summary.id || email.object !== 'email' || !candidate(email, probe, startedAt, Date.now()) ||
+              typeof email.text !== 'string' || email.text.trimEnd() !== probe.text ||
+              typeof email.message_id !== 'string' || !/^<[^\s<>]{1,990}>$/.test(email.message_id)) fail('doctor_readback_conflict');
+          return {
+            id: 'receive', status: 'pass', nextSteps: ['Retain this independent received-mail receipt with the exact source SHA and protected workflow run.'],
+            evidence: {
+              state: 'received', source: 'resend_received_email_api', inboxMessageId: email.id,
+              rfcMessageIdSha256: await digest(email.message_id), receivedAt: new Date(Date.parse(email.created_at)).toISOString(),
+              correlationId: probe.deliveryId, bodySha256: await digest(probe.text),
+              recipientSha256: await digest(mailbox(probe.to[0])), polls, requests,
+            },
+          };
+        }
+        if (!list.has_more) break;
+        const cursor = list.data.at(-1)?.id;
+        if (!uuid.test(cursor ?? '') || cursor === after) fail('doctor_readback_failed');
+        after = cursor;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining > 0 && polls < 30) {
+        const nextPollAt = Math.min(deadline, Date.now() + pollIntervalMs);
+        // A timer can wake before the wall-clock boundary due to rounding.
+        // Recheck the intended wake time before spending another provider read.
+        while (Date.now() < nextPollAt) {
+          await new Promise(resolve => setTimeout(resolve, Math.max(1, nextPollAt - Date.now())));
+        }
+      }
+    }
+  } catch {
+    if (Date.now() < deadline) return {
+      id: 'receive', status: 'fail', nextSteps: ['Mailbox readback failed or returned conflicting data. Check receiving permissions and the retained provider message; no resend was attempted.'],
+      evidence: { state: 'error', polls, requests, correlationId: probe.deliveryId },
+    };
+  }
+  return {
+    id: 'receive', status: 'pending', nextSteps: ['No matching received message appeared within the bounded mailbox scan. Inspect routing, spam and provider records before considering another send.'],
+    evidence: { state: 'timeout', polls, requests, correlationId: probe.deliveryId, maxPagesPerPoll: 3, maxMessagesPerPage: 100 },
+  };
+}

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

@@ -0,0 +1,45 @@
+import { fail } from '../core/errors.mjs';
+import { hostname, integer, object } from './common.mjs';
+
+export const DNS_IDS = ['mx', 'spf', 'dkim', 'dmarc'];
+
+export function record(value) {
+  object(value, ['type', 'name', 'value', 'priority'], 'invalid_doctor_record');
+  if (!['MX', 'TXT', 'CNAME'].includes(value.type) || typeof value.value !== 'string' || !value.value.trim() || value.value.length > 4096 || /[\x00-\x1f\x7f]/.test(value.value)) fail('invalid_doctor_record');
+  const result = { type: value.type, name: hostname(value.name, true), value: value.value };
+  if (value.type === 'MX') result.priority = integer(value.priority, 0, 65535, 'invalid_doctor_priority');
+  else if (value.priority !== undefined) fail('invalid_doctor_priority');
+  if (value.type !== 'TXT') result.value = hostname(value.value);
+  return result;
+}
+
+export function recordPlan(input = {}) {
+  object(input, DNS_IDS, 'invalid_doctor_records');
+  const plan = {};
+  let total = 0;
+  for (const id of DNS_IDS) {
+    const values = input[id] ?? [];
+    if (!Array.isArray(values) || (total += values.length) > 32) fail('invalid_doctor_records');
+    plan[id] = values.map(record);
+    for (const item of plan[id]) {
+      if ((id === 'mx' && item.type !== 'MX') || (id === 'dmarc' && (item.type !== 'TXT' || !item.name.startsWith('_dmarc.') || !/^v=DMARC1;/i.test(item.value))) ||
+          (id === 'spf' && !(item.type === 'CNAME' || item.type === 'TXT' && /^v=spf1(?:\s|$)/i.test(item.value))) ||
+          (id === 'dkim' && (!item.name.includes('._domainkey.') || !['TXT', 'CNAME'].includes(item.type)))) fail('invalid_doctor_record_kind');
+    }
+  }
+  return plan;
+}
+
+export function dnsPlan(domain, provider, plan) {
+  const setup = {
+    mx: `Copy the receiving service's MX host and priority for ${domain}; sending and receiving MX may be different.`,
+    spf: `Copy ${provider}'s exact SPF TXT or return-path CNAME name and value from domain setup; keep one SPF policy per name.`,
+    dkim: `Copy every ${provider} DKIM selector and TXT public key or CNAME target from domain setup; no selector or key can be inferred.`,
+    dmarc: `Choose a DMARC policy and supply its TXT record at _dmarc.${domain}; confirm alignment with your sending domain.`,
+  };
+  return DNS_IDS.map(id => ({
+    id, status: plan[id].length ? 'pending' : 'not_checked', records: plan[id],
+    nextSteps: [plan[id].length ? 'Review these explicit setup records, publish them through your DNS administrator, then request a live DNS check.' : setup[id]],
+    evidence: { state: 'unchecked', expectedRecordsSupplied: plan[id].length > 0 },
+  }));
+}

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

@@ -0,0 +1,268 @@
+# Verified delivery-event intake
+
+Public exports from `src/events/index.mjs` (re-export these from the mail facade):
+
+* `verifyWebhook(input): Promise<boolean>` — the frozen IF-056-MAIL-v1 signature.
+* `MAX_WEBHOOK_BYTES` — 32 MiB, including signed Inbound Parse multipart bytes.
+* `createDeliveryEventIntake(options)` — authenticated normalization plus atomic
+  durable receipt and recipient-state storage. No public unverified normalizer.
+
+## Signature verification
+
+`verifyWebhook({provider, rawBody, headers, key, now, toleranceSeconds = 300})`
+takes a `Uint8Array`, `Headers`, and epoch milliseconds. Only SendGrid and Resend
+are supported. It returns false for malformed inputs, keys, signature encodings,
+or timestamps. Tolerance is an integer from zero through 3600 seconds, inclusive;
+both clock boundaries are inclusive. The raw body is copied before asynchronous
+verification. SendGrid verifies SHA-256 ECDSA with a canonical base64 P-256 SPKI
+key and strict ASN.1 DER signature. Resend verifies Svix v1 HMAC-SHA256 over the
+original `id.timestamp.` prefix and raw bytes, including all valid rotation
+signatures. Base64 may omit padding but must retain canonical zero padding bits;
+whitespace and URL-safe substitutions are rejected. Svix signing keys must have
+the `whsec_` prefix and decode to 16–64 bytes.
+
+This stateless primitive does **not** prevent replay within the clock window,
+validate a provider schema, authenticate a mail sender, or authorize a tenant.
+Delivery routes should use the complete intake below. Signed Inbound Parse can
+use the primitive on the original multipart bytes before invoking inbound
+normalization; the application separately owns inbound authorization and durable
+replay protection. Bound streamed HTTP reads before materializing `rawBody`.
+
+## Complete HTTP intake
+
+```js
+const intake = createDeliveryEventIntake({
+  provider: 'resend', // or 'sendgrid'
+  tenantId,          // trusted server-side routing, never request JSON
+  eventNamespace,    // stable webhook/account identity across key rotations
+  key,              // configured for this endpoint and tenant
+  storage: ctx.storage, // real DurableObjectStorage, described below
+  authorize: async event => {
+    return await applicationOwnsMessageAndAllRecipients(event);
+  },
+  clock: Date.now,   // optional, returns epoch milliseconds
+  toleranceSeconds: 300, // optional
+});
+const results = await intake.ingestWebhook({ rawBody, headers });
+```
+
+The mandatory `authorize(event)` must return exactly true for every event in the
+batch. It runs only after successful signature and schema verification, and must
+check the server-selected tenant, provider message (or SendGrid signed delivery
+correlation), and **every** recipient against application records. It must be a
+read-only authorization decision, never a delivery side effect. A provider
+signature authenticates the configured provider endpoint; it does not authorize
+an arbitrary signed `rer_delivery_id`, product marker, mailbox, or tenant.
+
+Each frozen authorization event has:
+
+```js
+{
+  provider, tenantId, eventNamespace,
+  eventId, providerMessageId, type,
+  status, // accepted|deferred|delivered|bounced|failed|rejected|complained|null
+  occurredAt, // epoch milliseconds, from provider event time
+  recipients: ['mailbox@example.com'],
+  deliveryId, product, // signed SendGrid custom args, otherwise null
+  fingerprint, // SHA-256 hex of full provider event payload
+}
+```
+
+SendGrid arrays remain distinct events, keyed by `sg_event_id`; each recipient
+keeps its own state. Resend uses the signed `svix-id` as event identity and keeps
+the provider's `data.to` recipient list. Email local-part case is preserved. All
+required IDs are nonempty, bounded and control-free; missing message identities,
+recipient addresses or times fail. Only known delivery/tracking event types are
+accepted; inbound events belong to the inbound pipeline. Open/click/unsubscribe
+events retain receipts with `status: null` and cannot change delivery state.
+
+HTTP intake permits at most 1 MiB of raw bytes and 1000 events or recipients.
+Exact limits succeed; malformed UTF-8/JSON or any invalid/unauthorized event
+rejects the whole batch before storage. Stored event timestamps may be old
+(provider retries are legitimate), but cannot exceed the clock by five minutes.
+Fresh request signatures remain required on every retry.
+
+The result is an array in input event order:
+
+```js
+{ eventId, outcome: 'stored', recipients: [
+  { recipient, applied: true, state: { status, occurredAt, eventId } },
+] }
+// Replay, no state mutation:
+{ eventId, outcome: 'duplicate', recipients: [] }
+```
+
+Duplicate retries can be acknowledged without repeating application effects.
+Same ID with a different fingerprint throws `event_identity_conflict`, rolling
+back the entire batch. SendGrid fingerprints use the exact original JSON bytes
+of each event, independently of its array position, surrounding whitespace or
+other batch members. Internal event whitespace changes conflict conservatively.
+Resend fingerprints cover the complete raw body. Every provider field therefore
+participates, including fields not selected for the normalized record.
+
+## Durable storage seam and state policy
+
+`storage.transaction(async tx => ...)`, `tx.get(key)` and `tx.put(key, value)`
+match real Cloudflare Durable Object storage. The supplied implementation must
+provide serializable, rollback-on-throw, durably committed transactions across
+all concurrent calls and restarts. Route a given namespace consistently to the
+same Durable Object. A Node host can supply the same methods backed by its real
+transactional database; this module has no Node imports or process-local store.
+Plain KV, a Map, check-then-put, and an in-process mutex are insufficient.
+There is no automatic storage selection and no in-memory fallback.
+
+Receipt keys hash the tuple `[provider, tenantId, eventNamespace, eventId]` and
+state keys hash `[provider, tenantId, eventNamespace, providerMessageId, recipient]`
+with SHA-256 over JSON, prefixed `mail-events:v1:receipt:` or
+`mail-events:v1:state:`. Receipts store the entire normalized authorization event,
+including fingerprint. States store `{status, occurredAt, eventId}`. Both writes
+commit together. No expiry or pruning runs implicitly: retain receipts through
+the provider's possible replay period, and retain final state for the full
+application delivery lifetime. Deleting records weakens these guarantees.
+
+A terminal state cannot become accepted or deferred. A terminal event can
+finalize a pending state even when received out of order. A newer terminal fact
+may supersede an older terminal fact (for example a complaint after delivery).
+Older/equal-time events never replace an existing terminal state; equal-time
+conflicting terminal facts retain the first committed state, while both receipts
+remain available. Application policy can inspect the retained facts separately.
+Delivery means recipient mail-server acceptance, not evidence of human receipt.
+
+No application callback runs inside the transaction, and this API does not
+promise exactly-once external side effects. Consume persisted receipts using an
+application-owned durable workflow/outbox; do not equate a successful return with
+atomic completion of a separate external action. Storage/authorization exceptions
+are redacted; validation errors carry fixed `.code` values.
+
+## Cloudflare trusted queue boundary
+
+Configure `provider: 'cloudflare'`, omit `key`, and supply:
+
+```js
+cloudflareSource: { queue, accountId, zoneId, domain, eventSubscriptionId }
+```
+
+The returned object has **only** `consumeQueue(batch)`, not `ingestWebhook`.
+Invoke it only from the actual Worker `queue(batch, env, ctx)` consumer for an
+Event Subscription queue with controlled producer permissions. Match the
+configured queue, sending domain, zone, account, subscription, schema version 1
+and `email.sending` source. It supports documented delivered/deferred/bounced/
+failed/rejected/complained events and validates their terminal flags. The same
+mandatory application authorization and durable transaction apply. The entire
+batch is bounded to 1 MiB after queue-body JSON serialization and 1000 messages;
+the serialized full event supplies the fingerprint.
+
+Queue name and event fields are validation, not authentication. Anyone can forge
+a JavaScript object with those properties: never turn HTTP JSON into a queue
+batch or expose `consumeQueue` through an unauthenticated HTTP/RPC method. The
+trusted Cloudflare queue invocation and producer controls are the boundary.
+For Durable Object storage, the queue handler may forward
+`{queue: batch.queue, messages: batch.messages.map(({body}) => ({body}))}` through
+its **private Durable Object binding** to an application-owned method which
+constructs this intake with `this.ctx.storage`. This transports the authenticated
+queue data without trying to serialize runtime ACK functions. Keep that method
+inaccessible from public HTTP and validate the configured source there too.
+Call `batch.ackAll()` only after `consumeQueue` resolves; on a throw, retain/retry
+or quarantine according to application policy. The module never ACKs first and
+never invents a Cloudflare HTTP signature. Routing inbound email is a separate
+Worker `email` event and does not enter this delivery pipeline.
+
+## Verification and references
+
+From the Base root, with the module's existing development dependency available:
+
+```sh
+node --test modules/mail/tests/events/verify.test.mjs
+node --test modules/mail/tests/events/boundaries.test.mjs
+node --test modules/mail/tests/events/workerd.test.mjs
+```
+
+If using an existing cached dependency in another checkout, set
+`MAIL_MINIFLARE_MODULE` to its absolute `miniflare/dist/src/index.js` path; no
+installation is required. Tests create/dispose actual workerd and SQLite-backed
+Durable Objects, test races, atomic rollback and full runtime restart, and remove
+their temporary storage. Provider fixtures and test routes exist only in tests.
+The tests cover crypto in Node and workerd, but hosted proof remains
+**PENDING**. No live provider API, mail, or deployment is exercised.
+
+Primary contracts checked 6 October 2026:
+
+* [SendGrid security](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features)
+* [SendGrid signed multipart](https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/securing-your-parse-webhooks)
+* [SendGrid event fields](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event)
+* [Resend verification](https://resend.com/docs/webhooks/verify-webhooks-requests)
+* [Svix framing and published test vector](https://docs.svix.com/receiving/verifying-payloads/how-manual)
+* [Resend recipient event scope](https://www.resend.com/changelog/webhook-event-visibility)
+* [Cloudflare event schemas](https://developers.cloudflare.com/email-service/platform/event-subscriptions/)
+* [Durable Object storage transactions](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/)
+
+## Messaging events and real D1 storage
+
+```js
+import { createDeliveryEventIntake, createD1EventStore } from './modules/mail/index.mjs';
+const intake = createDeliveryEventIntake({
+  provider: 'messaging', tenantId: trustedTenant, eventNamespace: 'messaging-link',
+  messagingSource: {
+    serviceOrigin: 'https://messaging.example.com',
+    installId: localInstallId,
+    jwks: pinnedEventJwks, // public ES256 keys obtained when linking
+  },
+  store: createD1EventStore({ db: env.DB }),
+  authorize: event => ownsDelivery(event.deliveryId, event.providerMessageId,
+    event.recipients, event.tenantId),
+});
+// Bound the read to 1 MiB before allocating; this is the actual compact JWS body.
+const results = await intake.ingestWebhook({ rawBody, headers: request.headers });
+```
+
+For the exact independent wire format, signature envelope and closed detail
+fields, see [Messaging v1](../adapters/messaging/README.md). `key` is forbidden for
+this source. The event JWKS is copied when constructing intake; mutating the
+caller configuration cannot change an existing trust root. No network lookup
+runs during verification. Messaging's envelope clock tolerance is fixed at 60s;
+the existing `toleranceSeconds` option still configures Resend/SendGrid only.
+HTTPS service origins are required; explicit `mode:'test'|'development'` permits
+HTTP loopback for local integration. The signature establishes the service and
+installation; application authorization must still check every correlated
+message and recipient. All schema validation and whole-batch authorization
+finish before any SQL effect. Normalized `detail` is frozen before authorization.
+
+Apply `src/events/d1-schema.sql` as a new application migration before using the
+store. This additive schema owns only `rer_mail_event_receipts` and
+`rer_mail_event_states`; it leaves existing application and DO storage intact.
+Pass the constructed store as `store`, and omit `storage`. Existing DO users keep
+`storage:ctx.storage` unchanged. The D1 store also accepts authenticated Resend,
+SendGrid and Cloudflare intake; choosing the database does not change a source's
+authentication boundary. Only the real D1 constructor's stores are accepted,
+with no process-local fallback or arbitrary unverified normalizer.
+
+Every `commit` issues exactly one D1 `batch()` containing all receipt inserts,
+conditional recipient-state upserts and state reads. The D1 transaction is the
+concurrency and rollback boundary; no process mutex or preliminary read is used.
+Receipts have a primary key on `(provider,tenant_id,event_namespace,event_id)`.
+A conflicting fingerprint intentionally violates the named
+`rer_mail_event_identity_conflict` SQL CHECK; D1 rolls back the **whole batch**,
+including receipts and states inserted earlier in it. Other SQL errors also roll
+back the transaction and return a redacted `event_storage_failed` error.
+
+Each insert carries a random commit token and its batch ordinal. Conditional
+state writes require that exact receipt token/ordinal, so concurrent duplicates,
+repeated events within one batch and post-restart retries cannot reapply state.
+Receipt `event_json` stores the full normalized event, including correlation and
+detail; state keys include provider, tenant, namespace, provider message ID and
+case-preserved mailbox. Terminal-state ordering is the same as the DO store.
+Stored result reads occur within the same batch, so each event's returned state
+reflects its place in that batch. Duplicate results have no recipient effects.
+
+D1 bind/statement limits still apply to the host's database. Oversized batches
+fail atomically rather than being split into partial commits. Applications should
+size service pushes accordingly. Receipts and state are retained until the app
+explicitly prunes or erases them; this module has no implicit cleanup. The app
+owns an atomic business workflow for any external effects after intake, just as
+with the DO store.
+
+`tests/events/d1-workerd.test.mjs` drives public intake against real workerd D1.
+It covers signature/issuer/audience/key/time refusal, whole-batch schema and
+ownership checks, duplicate/conflicting races, rollback after an earlier insert,
+forced SQL failure rollback, restart duplicates, tenant/namespace isolation,
+local-part case and terminal ordering. The existing DO/Queue smoke remains.

package/modules/mail/src/events/d1-schema.sql

@@ -0,0 +1,25 @@
+-- Additive migration. Never drop existing delivery receipts or state.
+CREATE TABLE IF NOT EXISTS rer_mail_event_receipts (
+  provider TEXT NOT NULL,
+  tenant_id TEXT NOT NULL,
+  event_namespace TEXT NOT NULL,
+  event_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  event_json TEXT NOT NULL,
+  commit_token TEXT NOT NULL,
+  ordinal INTEGER NOT NULL,
+  conflict INTEGER NOT NULL DEFAULT 0 CONSTRAINT rer_mail_event_identity_conflict CHECK (conflict = 0),
+  PRIMARY KEY (provider, tenant_id, event_namespace, event_id)
+);
+CREATE TABLE IF NOT EXISTS rer_mail_event_states (
+  provider TEXT NOT NULL,
+  tenant_id TEXT NOT NULL,
+  event_namespace TEXT NOT NULL,
+  provider_message_id TEXT NOT NULL,
+  recipient TEXT NOT NULL,
+  status TEXT NOT NULL,
+  occurred_at INTEGER NOT NULL,
+  event_id TEXT NOT NULL,
+  terminal INTEGER NOT NULL CHECK (terminal IN (0, 1)),
+  PRIMARY KEY (provider, tenant_id, event_namespace, provider_message_id, recipient)
+);