@runeditrun/rer 0.0.0-stage → 0.1.1

package/modules/mail/src/adapters/cloudflare/index.mjs

@@ -0,0 +1,47 @@
+import { fail } from '../../core/errors.mjs';
+import { encodeBase64, parseAddress, validateConfig, validateMessage } from '../../core/validation.mjs';
+import { classifyHttpStatus, requestProvider, sendResult } from '../../core/transport.mjs';
+import { validateCloudflareHeaders } from './headers.mjs';
+import { cloudflareResult, readCloudflareResponse } from './response.mjs';
+
+function address(value) {
+  const { email, name } = parseAddress(value);
+  return name === undefined ? email : { address: email, name };
+}
+
+/** Cloudflare Email Sending REST API, independent of Email Routing send bindings. */
+export async function sendCloudflare(config, message, dependencies = {}) {
+  validateConfig(config, dependencies);
+  if (config.provider !== 'cloudflare') fail('cloudflare_provider_required');
+  if (message && Object.hasOwn(message, 'unsubscribe')) fail('unsubscribe_requires_facade');
+  validateMessage(message, 'cloudflare');
+  validateCloudflareHeaders(message.headers);
+  const body = { from: address(message.from), to: message.to.map(address), subject: message.subject };
+  for (const field of ['text', 'html', 'headers']) if (message[field] !== undefined) body[field] = message[field];
+  for (const field of ['cc', 'bcc']) if (message[field] !== undefined) body[field] = message[field].map(address);
+  if (message.replyTo !== undefined) body.reply_to = address(message.replyTo);
+  if (message.attachments !== undefined) body.attachments = message.attachments.map(attachment => {
+    // The structured REST schema permits content_id only on inline attachments.
+    if (attachment.contentId !== undefined && attachment.disposition !== 'inline') fail('cloudflare_unsupported_attachment_content_id');
+    return {
+      filename: attachment.filename, type: attachment.contentType,
+      content: encodeBase64(attachment.content), disposition: attachment.disposition ?? 'attachment',
+      ...(attachment.contentId === undefined ? {} : { content_id: attachment.contentId }),
+    };
+  });
+  const serialized = JSON.stringify(body);
+  if (new TextEncoder().encode(serialized).byteLength > 5 * 1024 * 1024) fail('cloudflare_message_too_large');
+  const recipients = [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])].map(value => parseAddress(value).email);
+  const response = await requestProvider(
+    `https://api.cloudflare.com/client/v4/accounts/${config.accountId}/email/sending/send`,
+    { method: 'POST', headers: { Authorization: `Bearer ${config.apiKey}`, 'Content-Type': 'application/json' }, body: serialized },
+    dependencies,
+  );
+  if (response === null) return sendResult('cloudflare', 'uncertain', null, 'cloudflare_transport_failed');
+  const status = classifyHttpStatus(response.status);
+  if (status !== null) {
+    void response.body?.cancel().catch(() => {});
+    return sendResult('cloudflare', status, null, 'cloudflare_http_error');
+  }
+  return cloudflareResult(await readCloudflareResponse(response), recipients);
+}

package/modules/mail/src/adapters/cloudflare/response.mjs

@@ -0,0 +1,99 @@
+import { safeProviderMessageId, sendResult } from '../../core/transport.mjs';
+import { parseAddress } from '../../core/validation.mjs';
+
+const provider = 'cloudflare';
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+// The domain is case-insensitive; do not collapse distinct case-sensitive local parts.
+export function mailboxKey(email) {
+  const at = email.lastIndexOf('@');
+  return email.slice(0, at + 1) + email.slice(at + 1).toLowerCase();
+}
+
+export function cloudflareResult(body, recipients) {
+  const unknown = () => sendResult(provider, 'uncertain', null, 'cloudflare_invalid_response');
+  if (!record(body) || typeof body.success !== 'boolean' || !Array.isArray(body.errors)) return unknown();
+  if (body.success === false) {
+    // A contradictory result may reflect a send that already took effect.
+    if (body.result !== null && body.result !== undefined) return unknown();
+    const codes = body.errors.map(error => error?.code);
+    const status = codes.some(code => [10002, 10003, 10100].includes(code)) ? 'uncertain'
+      : codes.includes(10004) ? 'rate_limited' : 'rejected';
+    return sendResult(provider, status, null, 'cloudflare_provider_error');
+  }
+  if (body.errors.length || !record(body.result)) return unknown();
+  const result = body.result;
+  const id = safeProviderMessageId(result.message_id);
+  if (result.message_id !== undefined && result.message_id !== null && id === null) return unknown();
+  const groups = [
+    ['delivered', 'accepted'], ['queued', 'accepted'],
+    ['permanent_bounces', 'rejected'], ['suppressed_recipients', 'rejected'],
+  ];
+  const outcomes = new Map();
+  const requested = new Map(recipients.map(recipient => [mailboxKey(recipient), recipient]));
+  let malformed = false;
+  for (const [field, status] of groups) {
+    const list = result[field];
+    if (field === 'suppressed_recipients' && list === undefined) continue;
+    if (!Array.isArray(list)) { malformed = true; continue; }
+    for (const value of list) {
+      let email;
+      try {
+        const parsed = parseAddress(value);
+        if (parsed.name || parsed.email !== value) { malformed = true; continue; }
+        email = mailboxKey(parsed.email);
+      } catch { malformed = true; continue; }
+      if (!requested.has(email)) { malformed = true; continue; }
+      if (outcomes.has(email)) {
+        // Even repeated identical groups have ambiguous recipient cardinality.
+        outcomes.set(email, 'uncertain');
+        malformed = true;
+      } else outcomes.set(email, status);
+    }
+  }
+  const recipientResults = [...requested].map(([key, recipient]) => ({
+    recipient, status: outcomes.get(key) ?? 'uncertain',
+  }));
+  if (malformed || recipientResults.some(item => item.status === 'uncertain')) {
+    return sendResult(provider, 'uncertain', id, 'cloudflare_incomplete_recipient_results', recipientResults);
+  }
+  const accepted = recipientResults.filter(item => item.status === 'accepted').length;
+  if (accepted === recipientResults.length) return sendResult(provider, 'accepted', id, undefined, recipientResults);
+  if (accepted === 0) return sendResult(provider, 'rejected', id, 'cloudflare_recipients_rejected', recipientResults);
+  // The common result union has no partial status. Never encourage retrying the batch.
+  return sendResult(provider, 'uncertain', id, 'cloudflare_partial_recipient_failure', recipientResults);
+}
+
+export async function readCloudflareResponse(response) {
+  // Bound both bytes and time after response headers; errors never expose the body.
+  let reader;
+  try { reader = response.body?.getReader(); } catch { return null; }
+  if (!reader) return null;
+  let timer;
+  let finished = false;
+  const read = async () => {
+    const chunks = [];
+    let length = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (finished) return null;
+      if (done) break;
+      length += value.byteLength;
+      if (length > 1024 * 1024) return null;
+      chunks.push(value);
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  };
+  try {
+    return await Promise.race([
+      read().catch(() => null),
+      new Promise(resolve => { timer = setTimeout(() => resolve(null), 15_000); }),
+    ]);
+  } finally {
+    finished = true;
+    clearTimeout(timer);
+    void reader.cancel().catch(() => {});
+  }
+}

package/modules/mail/src/adapters/messaging/README.md

@@ -0,0 +1,92 @@
+# Messaging v1 wire and Base client
+
+Normative phase-1 wire choices for independent implementations and the concurrent
+Messaging core. Linking, production credentials and deployment are separate.
+
+`createMailSender({provider:'messaging', mode, serviceOrigin, installId, kid,
+signingKey}, {fetch?, serviceBinding?, clock?, timeoutMilliseconds?})` exposes
+`send(message)`, `reconcile(deliveryId)`, and `erase(address)`. `signingKey` is a
+private ES256 P-256 JWK; no API key or direct provider settings are allowed.
+Configuration and each message are snapshotted before asynchronous work.
+`serviceOrigin` is an exact HTTPS origin (HTTP loopback only in test/development).
+A `serviceBinding` is a Worker Fetcher with `fetch`; it replaces the HTTP edge,
+never signature authentication. Do not configure both fetch and serviceBinding.
+
+Every request has `RER-Signature: <compact JWS>`. Protected header is
+`{alg:'ES256',kid,typ:'JWT'}`. Claims are `{iss:installId,aud:serviceOrigin,
+iat:<integer epoch seconds>,method,path,bodySha256:<lowercase SHA-256 hex>}`.
+The signature is the JOSE 64-byte P1363 ECDSA signature. Hash the exact UTF-8
+request bytes; GET hashes zero bytes. Path is the URL's encoded pathname,
+including `encodeURIComponent(deliveryId)` for reconciliation. Request verification
+permits iat within +/-60 seconds. Never follow redirects or retry automatically.
+
+`POST /v1/mail`: JSON fields `deliveryId`, required `kind` (`auth`,
+`transactional`, `bulk`), `from`, `to` (ONE address string, not array), `subject`,
+optional `replyTo`, `text`, `html`, `headers`, `attachments`, `expiresAt`.
+Base's public message still uses a one-element `to` array. `cc`/`bcc` are refused.
+Messaging delivery IDs retain Base's 512-character limit and must have no
+surrounding whitespace, so sends can be reconciled and correlated with events.
+Internal spaces, Unicode, slashes, query and fragment characters are preserved;
+`.` and `..` and strings that cannot be URL-encoded are refused before dispatch.
+Address strings preserve display names and local-part case. `expiresAt` is an
+RFC3339 timestamp; Base carries it only for Messaging (other transports cannot
+promise expiry). Attachments are `{filename,contentType,content:<canonical padded
+base64>,disposition?,contentId?}`; no byte conversion through text. Text plus HTML
+is at most 1 MiB UTF-8; decoded attachments total at most 5 MiB; entire JSON body
+at most 8 MiB. Headers are Base's allowed subset of `List-*`, `Auto-Submitted`,
+`In-Reply-To`, `References`, `Message-ID`, `X-*`; `replyTo` supplies Reply-To.
+Base applies its unsubscribe assembly before signing.
+
+The send response is the JSON result itself, without an envelope:
+`{provider:'messaging',status,providerMessageId,code?,suppression?,retryAfter?}`.
+Accepted has a nonempty Messaging message id and no code. Development has null
+providerMessageId and no code. All other states have null providerMessageId.
+Rejected codes: suppressed, kind_not_granted, sender_not_granted, app_paused,
+invalid, unsubscribe_missing, expired, provider_rejected_recipient, key_reused.
+Only suppressed requires `suppression: hard_bounce|complaint|provider`.
+Rate-limited codes: app_cap, recipient_limit, provider_rate_limited,
+providers_unavailable; these require `retryAfter`, an integer epoch timestamp in
+seconds (schedule at this time, not a duration). Uncertain codes: ambiguous,
+in_progress, orphaned; in_progress requires retryAfter, other uncertain codes
+may carry it. No other fields or status/code combinations are accepted.
+Application responses are HTTP 200. HTTP errors, malformed/overlong response
+bodies, timeouts and network failures map to uncertain/ambiguous without echoing
+response fields or issuing a second request. The default client deadline is 15s,
+including body reading; Messaging's own send budget is 10s.
+
+`GET /v1/messages/{deliveryId}` sends no body. HTTP 200 returns
+`{deliveryId,messageId,state,result,attempts,lastEvent}`; state is sending or a
+send-result status, result is null while sending and otherwise the above result.
+Attempts are `{provider,outcome,httpStatus,code,durationMs}`: provider is resend,
+sendgrid, cloudflare or development; outcome is started, accepted, rejected,
+rate_limited or uncertain; HTTP status and code may be null; durationMs is a
+nonnegative integer or null. `lastEvent` is null or the event object below.
+An authenticated 404 returns null. Other failures throw a fixed redacted
+MailValidationError; they do not imply a send outcome.
+
+`POST /v1/erase` sends exactly `{address:<bare mailbox preserving case>}`;
+HTTP 200 returns `{erased:true}`. Erasure is idempotent and scoped by signed iss.
+Failures throw a fixed redacted error; a timeout does not prove erasure failed.
+
+## Event wire
+
+The raw POST body is the compact JWS itself (UTF-8), not JSON wrapping it.
+Protected header is `{alg:'ES256',kid,typ:'JWT'}`. Payload is
+`{iss:serviceOrigin,aud:installId,iat:<integer epoch seconds>,events:[...]}`.
+Each event is `{id,messageId,deliveryId,recipient,occurredAt,type,detail}`.
+Recipient is a bare mailbox with local-part case preserved; occurredAt is RFC3339.
+Types: accepted, delivered, deferred, bounced, complained, failed, suppressed.
+`detail` is a closed object, with optional `bounce: 'hard'|'soft'`,
+`suppression: 'hard_bounce'|'complaint'|'provider'`, and `code` (a bounded machine
+code matching `[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}`). Bounce classification is allowed
+only on bounced; suppression only on suppressed. No free-form provider text.
+
+Intake uses `messagingSource:{serviceOrigin,installId,jwks:{keys:[publicJwk,...]}}`
+pinned at link time. No remote key lookup, jku, x5u, embedded jwk, algorithm
+negotiation or unsigned JSON ingestion. Key rotation replaces the configured
+pinned set. Signature, issuer, audience and +/-60s iat are checked before events
+have any effect. Each normalized record carries `eventId:id`,
+`providerMessageId:messageId`, `deliveryId`, `recipients:[recipient]`, `detail`,
+and `status:type` except suppressed maps to rejected. Stable receipts fingerprint
+the validated event fields in fixed order, independent of batch order, envelope
+clock, signing key rotation or JSON property order. A changed field conflicts.

package/modules/mail/src/adapters/messaging/contract.mjs

@@ -0,0 +1,66 @@
+import { fail } from '../../core/errors.mjs';
+
+export function closed(value, fields, code = 'invalid_messaging_response') {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+      Reflect.ownKeys(value).some(key => typeof key !== 'string' || !fields.includes(key))) fail(code);
+  return value;
+}
+export function identity(value, max = 512, code = 'invalid_messaging_identity') {
+  if (typeof value !== 'string' || !value.length || value.trim() !== value || value.length > max || /[\x00-\x1f\x7f]/.test(value)) fail(code);
+  return value;
+}
+export function serviceOrigin(value, mode = 'production') {
+  let url;
+  try { url = new URL(value); } catch { fail('invalid_messaging_origin'); }
+  const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
+  if (url.origin !== value || url.username || url.password ||
+      !(url.protocol === 'https:' || (mode !== 'production' && url.protocol === 'http:' && loopback))) fail('invalid_messaging_origin');
+  return value;
+}
+export function rfc3339(value, code = 'invalid_messaging_timestamp') {
+  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(code);
+  const day = new Date(`${value.slice(0, 10)}T00:00:00.000Z`);
+  const time = Date.parse(value);
+  if (!Number.isSafeInteger(time) || time < 0 || !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 ||
+      (value.endsWith('Z') === false && (Number(value.slice(-5, -3)) > 23 || Number(value.slice(-2)) > 59))) fail(code);
+  return time;
+}
+export function validateMessagingConfig(config, dependencies) {
+  serviceOrigin(config.serviceOrigin, config.mode);
+  identity(config.installId, 256, 'invalid_messaging_install');
+  identity(config.kid, 256, 'invalid_messaging_key');
+  if (config.apiKey !== undefined || config.accountId !== undefined) fail('unsupported_messaging_config');
+  const jwk = config.signingKey;
+  if (!jwk || jwk.kty !== 'EC' || jwk.crv !== 'P-256' ||
+      !['x', 'y', 'd'].every(field => typeof jwk[field] === 'string' && /^[A-Za-z0-9_-]{43}$/.test(jwk[field])) ||
+      (jwk.alg !== undefined && jwk.alg !== 'ES256') || (jwk.use !== undefined && jwk.use !== 'sig') ||
+      (jwk.key_ops !== undefined && (!Array.isArray(jwk.key_ops) || jwk.key_ops.length !== 1 || jwk.key_ops[0] !== 'sign')) ||
+      (jwk.kid !== undefined && jwk.kid !== config.kid)) fail('invalid_messaging_key');
+  if (dependencies.serviceBinding !== undefined && (!dependencies.serviceBinding || typeof dependencies.serviceBinding.fetch !== 'function')) fail('invalid_service_binding');
+  if (dependencies.serviceBinding !== undefined && dependencies.fetch !== undefined) fail('ambiguous_messaging_transport');
+}
+const codes = {
+  rejected: ['suppressed', 'kind_not_granted', 'sender_not_granted', 'app_paused', 'invalid', 'unsubscribe_missing', 'expired', 'provider_rejected_recipient', 'key_reused'],
+  rate_limited: ['app_cap', 'recipient_limit', 'provider_rate_limited', 'providers_unavailable'],
+  uncertain: ['ambiguous', 'in_progress', 'orphaned'],
+};
+export function validateMessagingResult(result) {
+  const invalid = 'invalid_send_result';
+  closed(result, ['provider', 'status', 'providerMessageId', 'code', 'suppression', 'retryAfter'], invalid);
+  if (result.provider !== 'messaging' || typeof result.status !== 'string') fail(invalid);
+  if (result.status === 'accepted') identity(result.providerMessageId, 1024, invalid);
+  else if (result.providerMessageId !== null) fail(invalid);
+  if (['accepted', 'development'].includes(result.status)) {
+    if (Object.hasOwn(result, 'code')) fail(invalid);
+  } else if (!(Object.hasOwn(codes, result.status) && codes[result.status].includes(result.code))) fail(invalid);
+  if (result.code === 'suppressed') {
+    if (!['hard_bounce', 'complaint', 'provider'].includes(result.suppression)) fail(invalid);
+  } else if (Object.hasOwn(result, 'suppression')) fail(invalid);
+  const retryable = ['rate_limited', 'uncertain'].includes(result.status);
+  if (Object.hasOwn(result, 'retryAfter') && (!retryable || !Number.isSafeInteger(result.retryAfter) || result.retryAfter < 0)) fail(invalid);
+  if ((result.status === 'rate_limited' || result.code === 'in_progress') && result.retryAfter === undefined) fail(invalid);
+  return result;
+}

package/modules/mail/src/adapters/messaging/event-schema.mjs

@@ -0,0 +1,28 @@
+import { fail } from '../../core/errors.mjs';
+import { parseAddress } from '../../core/validation.mjs';
+import { closed, identity, rfc3339 } from './contract.mjs';
+
+export function messagingEvent(value, now) {
+  closed(value, ['id', 'messageId', 'deliveryId', 'recipient', 'occurredAt', 'type', 'detail'], 'invalid_event_schema');
+  const id = identity(value.id), messageId = identity(value.messageId, 1024), deliveryId = identity(value.deliveryId);
+  const parsed = parseAddress(value.recipient);
+  if (parsed.name || parsed.email !== value.recipient) fail('invalid_event_recipient');
+  const occurredAt = rfc3339(value.occurredAt, 'invalid_event_timestamp');
+  if (occurredAt > now + 300_000) fail('invalid_event_timestamp');
+  if (!['accepted', 'delivered', 'deferred', 'bounced', 'complained', 'failed', 'suppressed'].includes(value.type)) fail('unsupported_delivery_event');
+  closed(value.detail, ['bounce', 'suppression', 'code'], 'invalid_event_detail');
+  const detail = {};
+  if (Object.hasOwn(value.detail, 'bounce')) {
+    if (value.type !== 'bounced' || !['hard', 'soft'].includes(value.detail.bounce)) fail('invalid_event_detail');
+    detail.bounce = value.detail.bounce;
+  }
+  if (Object.hasOwn(value.detail, 'suppression')) {
+    if (value.type !== 'suppressed' || !['hard_bounce', 'complaint', 'provider'].includes(value.detail.suppression)) fail('invalid_event_detail');
+    detail.suppression = value.detail.suppression;
+  }
+  if (Object.hasOwn(value.detail, 'code')) {
+    if (typeof value.detail.code !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/.test(value.detail.code)) fail('invalid_event_detail');
+    detail.code = value.detail.code;
+  }
+  return { id, messageId, deliveryId, recipient: value.recipient, occurredAt: value.occurredAt, type: value.type, detail };
+}

package/modules/mail/src/adapters/messaging/index.mjs

@@ -0,0 +1,61 @@
+import { fail } from '../../core/errors.mjs';
+import { parseAddress } from '../../core/validation.mjs';
+import { closed, identity, validateMessagingResult } from './contract.mjs';
+import { serializeMessagingMessage } from './serialize.mjs';
+import { messagingRequest } from './request.mjs';
+import { messagingEvent } from './event-schema.mjs';
+
+const ambiguous = () => ({ provider: 'messaging', status: 'uncertain', providerMessageId: null, code: 'ambiguous' });
+export async function sendMessaging(config, message, dependencies) {
+  const bytes = serializeMessagingMessage(message);
+  const response = await messagingRequest(config, dependencies, 'POST', '/v1/mail', bytes);
+  if (response?.status !== 200) return ambiguous();
+  try { return validateMessagingResult(response.value); } catch { return ambiguous(); }
+}
+export async function reconcileMessaging(config, deliveryId, dependencies) {
+  identity(deliveryId, 512, 'invalid_delivery_id');
+  // Dot-only segments are normalized by URL/fetch even when percent encoded.
+  if (deliveryId === '.' || deliveryId === '..') fail('invalid_delivery_id');
+  let segment;
+  try { segment = encodeURIComponent(deliveryId); } catch { fail('invalid_delivery_id'); }
+  const response = await messagingRequest(config, dependencies, 'GET', `/v1/messages/${segment}`);
+  if (response?.status === 404) return null;
+  try {
+    if (response?.status !== 200) throw new Error();
+    const value = closed(response.value, ['deliveryId', 'messageId', 'state', 'result', 'attempts', 'lastEvent']);
+    if (value.deliveryId !== deliveryId) throw new Error();
+    identity(value.messageId, 1024);
+    if (value.state === 'sending') { if (value.result !== null) throw new Error(); }
+    else {
+      validateMessagingResult(value.result);
+      if (value.state !== value.result.status || (value.result.status === 'accepted' && value.result.providerMessageId !== value.messageId)) throw new Error();
+    }
+    if (!Array.isArray(value.attempts) || value.attempts.length > 1000) throw new Error();
+    for (const attempt of value.attempts) {
+      closed(attempt, ['provider', 'outcome', 'httpStatus', 'code', 'durationMs']);
+      if (!['resend', 'sendgrid', 'cloudflare', 'development'].includes(attempt.provider) ||
+          !['started', 'accepted', 'rejected', 'rate_limited', 'uncertain'].includes(attempt.outcome) ||
+          !(attempt.httpStatus === null || (Number.isInteger(attempt.httpStatus) && attempt.httpStatus >= 100 && attempt.httpStatus <= 599)) ||
+          !(attempt.code === null || (typeof attempt.code === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/.test(attempt.code))) ||
+          !(attempt.durationMs === null || (Number.isSafeInteger(attempt.durationMs) && attempt.durationMs >= 0))) throw new Error();
+    }
+    if (value.lastEvent !== null) {
+      const event = messagingEvent(value.lastEvent, (dependencies.clock ?? Date.now)());
+      if (event.messageId !== value.messageId || event.deliveryId !== deliveryId) throw new Error();
+      value.lastEvent = event;
+    }
+    return value;
+  } catch { fail('messaging_reconciliation_failed'); }
+}
+export async function eraseMessaging(config, address, dependencies) {
+  const parsed = parseAddress(address);
+  if (parsed.name || parsed.email !== address) fail('invalid_erase_address');
+  const bytes = new TextEncoder().encode(JSON.stringify({ address }));
+  const response = await messagingRequest(config, dependencies, 'POST', '/v1/erase', bytes);
+  try {
+    if (response?.status !== 200) throw new Error();
+    const value = closed(response.value, ['erased']);
+    if (value.erased !== true) throw new Error();
+    return value;
+  } catch { fail('messaging_erasure_failed'); }
+}

package/modules/mail/src/adapters/messaging/jws.mjs

@@ -0,0 +1,68 @@
+import { fail } from '../../core/errors.mjs';
+import { identity, closed } from './contract.mjs';
+
+const encoder = new TextEncoder();
+export function base64url(bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  return btoa(binary).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function decode(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error();
+  const bytes = Uint8Array.from(atob(value.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
+  if (base64url(bytes) !== value) throw new Error();
+  return bytes;
+}
+function json(value) { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(decode(value))); }
+export async function bodyDigest(bytes) {
+  return Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)), value => value.toString(16).padStart(2, '0')).join('');
+}
+export async function signRequest(config, method, path, bytes, now) {
+  try {
+    if (!Number.isSafeInteger(now) || now < 0) fail('invalid_messaging_clock');
+    const protectedPart = base64url(encoder.encode(JSON.stringify({ alg: 'ES256', kid: config.kid, typ: 'JWT' })));
+    const claims = { iss: config.installId, aud: config.serviceOrigin, iat: Math.floor(now / 1000), method, path, bodySha256: await bodyDigest(bytes) };
+    const payload = base64url(encoder.encode(JSON.stringify(claims)));
+    const key = await crypto.subtle.importKey('jwk', config.signingKey, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, key, encoder.encode(`${protectedPart}.${payload}`));
+    return `${protectedPart}.${payload}.${base64url(new Uint8Array(signature))}`;
+  } catch { fail('messaging_signing_failed'); }
+}
+
+export function pinnedKeys(jwks) {
+  closed(jwks, ['keys'], 'invalid_event_config');
+  if (!Array.isArray(jwks.keys) || !jwks.keys.length || jwks.keys.length > 16) fail('invalid_event_config');
+  const seen = new Set();
+  for (const key of jwks.keys) {
+    closed(key, ['kty', 'crv', 'x', 'y', 'kid', 'alg', 'use', 'key_ops', 'ext'], 'invalid_event_config');
+    identity(key.kid, 256, 'invalid_event_config');
+    if (seen.has(key.kid) || key.kty !== 'EC' || key.crv !== 'P-256' ||
+        !['x', 'y'].every(field => typeof key[field] === 'string' && /^[A-Za-z0-9_-]{43}$/.test(key[field])) ||
+        (key.alg !== undefined && key.alg !== 'ES256') || (key.use !== undefined && key.use !== 'sig') ||
+        (key.key_ops !== undefined && (!Array.isArray(key.key_ops) || key.key_ops.length !== 1 || key.key_ops[0] !== 'verify'))) fail('invalid_event_config');
+    seen.add(key.kid);
+  }
+  return structuredClone(jwks);
+}
+/** No remote key lookup. Parse only the header until the signature is verified. */
+export async function verifyEventJws(rawBody, source, now) {
+  try {
+    const compact = new TextDecoder('utf-8', { fatal: true }).decode(rawBody);
+    const parts = compact.split('.');
+    if (parts.length !== 3) throw new Error();
+    const header = json(parts[0]);
+    closed(header, ['alg', 'kid', 'typ'], 'event_signature_invalid');
+    if (header.alg !== 'ES256' || (header.typ !== undefined && header.typ !== 'JWT')) throw new Error();
+    const jwk = source.jwks.keys.find(key => key.kid === header.kid);
+    if (!jwk) throw new Error();
+    const signature = decode(parts[2]);
+    if (signature.length !== 64) throw new Error();
+    const key = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+    if (!await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, signature, encoder.encode(`${parts[0]}.${parts[1]}`))) throw new Error();
+    const payload = json(parts[1]);
+    closed(payload, ['iss', 'aud', 'iat', 'events'], 'event_signature_invalid');
+    if (payload.iss !== source.serviceOrigin || payload.aud !== source.installId ||
+        !Number.isSafeInteger(payload.iat) || payload.iat < 0 || Math.abs(now - payload.iat * 1000) > 60_000) throw new Error();
+    return payload.events;
+  } catch { fail('event_signature_invalid'); }
+}

package/modules/mail/src/adapters/messaging/request.mjs

@@ -0,0 +1,52 @@
+import { fail } from '../../core/errors.mjs';
+import { signRequest } from './jws.mjs';
+
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+async function jsonBody(response, signal) {
+  if (!response.body) throw new Error();
+  const reader = response.body.getReader();
+  const cancel = () => { void reader.cancel().catch(() => {}); };
+  signal.addEventListener('abort', cancel, { once: true });
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > MAX_RESPONSE_BYTES) throw new Error();
+      chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  } finally { signal.removeEventListener('abort', cancel); cancel(); }
+}
+/** Exactly one signed exchange, bounded through response-body consumption. */
+export async function messagingRequest(config, dependencies, method, path, body = new Uint8Array()) {
+  let now;
+  try { now = (dependencies.clock ?? Date.now)(); } catch { fail('invalid_messaging_clock'); }
+  const signature = await signRequest(config, method, path, body, now);
+  const timeout = dependencies.timeoutMilliseconds ?? 15_000;
+  const controller = new AbortController();
+  const fetcher = dependencies.serviceBinding
+    ? dependencies.serviceBinding.fetch.bind(dependencies.serviceBinding)
+    : dependencies.fetch ?? globalThis.fetch;
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(async () => {
+        const response = await fetcher(`${config.serviceOrigin}${path}`, {
+          method, redirect: 'manual', signal: controller.signal,
+          headers: { 'RER-Signature': signature, ...(method === 'GET' ? {} : { 'Content-Type': 'application/json' }) },
+          ...(method === 'GET' ? {} : { body }),
+        });
+        if (!(response instanceof Response)) return null;
+        if (response.status !== 200) { void response.body?.cancel().catch(() => {}); return { status: response.status, value: null }; }
+        return { status: 200, value: await jsonBody(response, controller.signal) };
+      }).catch(() => null),
+      new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(null); }, timeout); }),
+    ]);
+  } finally { clearTimeout(timer); controller.abort(); }
+}

package/modules/mail/src/adapters/messaging/serialize.mjs

@@ -0,0 +1,21 @@
+import { fail } from '../../core/errors.mjs';
+import { validateMessage, encodeBase64 } from '../../core/validation.mjs';
+
+const encoder = new TextEncoder();
+export function serializeMessagingMessage(message) {
+  validateMessage(message, 'messaging');
+  if (message.unsubscribe !== undefined) fail('unconsumed_unsubscribe');
+  if (encoder.encode(message.text ?? '').length + encoder.encode(message.html ?? '').length > 1024 * 1024) fail('messaging_body_too_large');
+  let attachmentBytes = 0;
+  for (const attachment of message.attachments ?? []) attachmentBytes += attachment.content.byteLength;
+  if (attachmentBytes > 5 * 1024 * 1024) fail('messaging_attachments_too_large');
+  for (const name of Object.keys(message.headers ?? {})) {
+    if (!/^(?:list-[a-z0-9-]+|x-[a-z0-9-]+|auto-submitted|in-reply-to|references|message-id)$/i.test(name)) fail('unsupported_messaging_header');
+  }
+  const { to, attachments, ...rest } = message;
+  const body = encoder.encode(JSON.stringify({ ...rest, to: to[0], ...(attachments === undefined ? {} : {
+    attachments: attachments.map(attachment => ({ ...attachment, content: encodeBase64(attachment.content) })),
+  }) }));
+  if (body.length > 8 * 1024 * 1024) fail('messaging_request_too_large');
+  return body;
+}