agent-protocols 0.10.0 → 0.11.0

package/dist/mail.js

@@ -0,0 +1,752 @@
+/** Agent Mail 1.0. State helpers are process-local; persist snapshots before acknowledging delivery. */
+import { CipherSuite, HkdfSha256 } from "@hpke/core";
+import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+import { sha3_256 } from "@noble/hashes/sha3.js";
+import { Validator } from "@cfworker/json-schema";
+import canonicalize from "canonicalize";
+import nacl from "tweetnacl";
+import { base64UrlDecodeCanonical, base64UrlEncode } from "./encoding.js";
+import { protocolError } from "./errors.js";
+import { MemoryNonceStore, createEvent, formatAgentUrl, parseAgentUrl, parseStrictJson, validateAgentId, validateOrigin, verifyEnvelope, verifyRequestJwt, verifyTimestamp, } from "./identity.js";
+import { MAIL_SCHEMA } from "./mail-schema.js";
+export { MAIL_SCHEMA } from "./mail-schema.js";
+export const MAIL_PROTOCOL = "agent-mail/1.0";
+export const MAIL_MAX_TTL_MS = 30 * 86400000;
+export const MAIL_FUTURE_SKEW_MS = 300000;
+export const MAIL_MAX_PACKET_BYTES = 1048576;
+const encoder = new TextEncoder();
+const INFO = encoder.encode(MAIL_PROTOCOL);
+const clone = (v) => structuredClone(v);
+const validators = new Map();
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+function requireMail(ok, code, message = code) {
+    if (!ok)
+        throw protocolError(code, message);
+}
+function safeTime(now) {
+    requireMail(Number.isSafeInteger(now) && now >= 0, "invalid_request", "clock must be nonnegative safe milliseconds");
+}
+function strictString(value) {
+    requireMail(!LONE_SURROGATE.test(value), "invalid_event", "lone surrogate");
+}
+function jsonValue(value, seen = new Set()) {
+    if (value === null || typeof value === "boolean")
+        return;
+    if (typeof value === "string")
+        return strictString(value);
+    if (typeof value === "number") {
+        requireMail(Number.isFinite(value) &&
+            (!Number.isInteger(value) || Number.isSafeInteger(value)), "invalid_event", "invalid JSON number");
+        return;
+    }
+    requireMail(typeof value === "object", "invalid_event", "non-JSON value");
+    requireMail(!seen.has(value), "invalid_event", "cyclic JSON");
+    requireMail(Array.isArray(value) ||
+        Object.getPrototypeOf(value) === Object.prototype ||
+        Object.getPrototypeOf(value) === null, "invalid_event", "expected plain JSON object");
+    seen.add(value);
+    if (Array.isArray(value))
+        for (const child of value)
+            jsonValue(child, seen);
+    else
+        for (const [key, child] of Object.entries(value)) {
+            strictString(key);
+            requireMail(child !== undefined, "invalid_event", "undefined member");
+            jsonValue(child, seen);
+        }
+    seen.delete(value);
+}
+/** Canonical, strict I-JSON bytes. This never silently drops undefined members. */
+export function mailCanonicalBytes(value) {
+    jsonValue(value);
+    return encoder.encode(canonicalize(value));
+}
+export function validateMailSchema(value, definition = "envelope") {
+    jsonValue(value);
+    let validator = validators.get(definition);
+    if (!validator) {
+        requireMail(Object.hasOwn(MAIL_SCHEMA.$defs, definition), "invalid_request", "unknown Mail schema definition");
+        validator = new Validator({
+            $ref: `#/$defs/${definition}`,
+            $defs: MAIL_SCHEMA.$defs,
+        }, "2020-12");
+        validators.set(definition, validator);
+    }
+    requireMail(validator.validate(value).valid, "invalid_event", `${definition} schema violation`);
+}
+export function decodeMailBytes(value, length) {
+    requireMail(typeof value === "string", "invalid_encoding");
+    const bytes = base64UrlDecodeCanonical(value);
+    requireMail(bytes !== undefined && (length === undefined || bytes.length === length), "invalid_encoding", "invalid canonical base64url or byte length");
+    return bytes;
+}
+function pathId(value, length) {
+    const bytes = typeof value === "string" ? base64UrlDecodeCanonical(value) : undefined;
+    requireMail(bytes?.length === length, "invalid_request", "invalid path ID");
+}
+export function newMailId() {
+    return base64UrlEncode(nacl.randomBytes(16));
+}
+/** Parse `did:agent:<key>/mail/<mailbox_id>[?route=<origin>...]`. */
+export function parseMailAddress(value) {
+    const url = parseAgentUrl(value);
+    requireMail(url.protocol === "mail" &&
+        url.resource !== undefined &&
+        base64UrlDecodeCanonical(url.resource)?.length === 16, "invalid_url", "not a mailbox address");
+    return { owner: url.agent_id, mailbox_id: url.resource, routes: url.routes };
+}
+/** Format the stable address, or a contact address when routes are given. */
+export function formatMailAddress(owner, mailboxId, routes = []) {
+    requireMail(base64UrlDecodeCanonical(mailboxId)?.length === 16, "invalid_url", "mailbox_id must be an id16");
+    return formatAgentUrl({
+        agent_id: owner,
+        protocol: "mail",
+        resource: mailboxId,
+        routes,
+    });
+}
+export function mailTextPart(text, name) {
+    strictString(text);
+    return {
+        media_type: "text/plain",
+        data: base64UrlEncode(encoder.encode(text)),
+        ...(name === undefined ? {} : { name }),
+    };
+}
+/** Returns inert text only; does not render markup or perform network/file actions. */
+export function mailPartText(part) {
+    validateMailSchema(part, "part");
+    requireMail(part.media_type.startsWith("text/"), "invalid_event", "part is not text");
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(decodeMailBytes(part.data));
+    }
+    catch {
+        throw protocolError("invalid_event", "invalid UTF-8 text part");
+    }
+}
+function lifetime(created, expires) {
+    requireMail(created < expires && expires - created <= MAIL_MAX_TTL_MS, "invalid_event", "invalid lifetime");
+}
+function usableX25519(publicKey) {
+    const key = decodeMailBytes(publicKey, 32);
+    // A public, disposable scalar detects all low-order peers; no shared secret is used for encryption.
+    requireMail(nacl.scalarMult(new Uint8Array(32).fill(42), key).some((x) => x !== 0), "invalid_event", "unusable X25519 public key");
+}
+/** Historical verification: shape, signature, owner, intrinsic times, routes, and key. */
+export function validateMailboxCard(card, owner) {
+    validateMailSchema(card, "mailboxCardEnvelope");
+    const c = card;
+    verifyEnvelope(c);
+    if (owner !== undefined)
+        requireMail(c.event.actor === owner, "invalid_actor", "card owner mismatch");
+    const p = c.event.payload;
+    lifetime(c.event.created_at, p.expires_at);
+    requireMail(p.expires_at <= p.receive_until &&
+        p.receive_until - p.expires_at <= MAIL_MAX_TTL_MS, "invalid_event", "invalid receive_until");
+    p.routes.forEach(validateOrigin);
+    usableX25519(p.public_key);
+}
+/** A card usable for new encryption: not future-dated, open (non-empty routes), unexpired. */
+export function validateMailSenderCard(card, owner, now = Date.now()) {
+    safeTime(now);
+    validateMailboxCard(card, owner);
+    const c = card;
+    requireMail(c.event.created_at <= now + MAIL_FUTURE_SKEW_MS, "timestamp_out_of_window", "card is future-dated");
+    requireMail(c.event.payload.routes.length > 0, "mailbox_unavailable", "mailbox closed");
+    requireMail(now < c.event.payload.expires_at, "stale_card", "card expired");
+}
+/** Historical verification of a signed letter; never advances live nonce state. */
+export function validateMailLetter(letter) {
+    validateMailSchema(letter, "messageEnvelope");
+    const l = letter;
+    verifyEnvelope(l);
+    const p = l.event.payload;
+    lifetime(l.event.created_at, p.expires_at);
+    for (const part of p.parts) {
+        decodeMailBytes(part.data);
+        if (part.media_type.startsWith("text/"))
+            mailPartText(part);
+    }
+    if (p.reply_card !== undefined)
+        validateMailboxCard(p.reply_card, l.event.actor);
+}
+export function mailboxPublishEvent(actor, createdAt, nonce, payload) {
+    return createEvent(MAIL_PROTOCOL, "mailbox.publish", actor, createdAt, nonce, clone(payload));
+}
+export function mailMessageEvent(actor, createdAt, nonce, payload) {
+    return createEvent(MAIL_PROTOCOL, "mail.message", actor, createdAt, nonce, clone(payload));
+}
+/** Bind a reply to a known parent: participants, parent letter ID, and thread. */
+export function validateMailReply(reply, parent) {
+    validateMailLetter(reply);
+    validateMailLetter(parent);
+    requireMail(reply.event.payload.in_reply_to === parent.hash &&
+        reply.event.payload.thread_id === parent.event.payload.thread_id &&
+        reply.event.actor === parent.event.payload.to &&
+        reply.event.payload.to === parent.event.actor, "invalid_event", "reply participants/thread binding mismatch");
+}
+/** Validate a packet and return its canonical bytes, computed once for ID and size checks. */
+function packetBytes(packet, expectedId) {
+    validateMailSchema(packet, "packet");
+    const p = packet;
+    decodeMailBytes(p.enc, 32);
+    const ct = decodeMailBytes(p.ciphertext);
+    requireMail(ct.length >= 1040 && ct.length % 1024 === 16, "invalid_packet", "invalid ciphertext length");
+    const bytes = mailCanonicalBytes(p);
+    requireMail(bytes.length <= MAIL_MAX_PACKET_BYTES, "payload_too_large", "packet exceeds 1 MiB");
+    if (expectedId !== undefined)
+        requireMail(base64UrlEncode(sha3_256(bytes)) === expectedId, "invalid_packet", "packet ID mismatch");
+    return bytes;
+}
+export function validateMailPacket(packet, expectedId) {
+    packetBytes(packet, expectedId);
+}
+export function mailPacketId(packet) {
+    return base64UrlEncode(sha3_256(mailCanonicalBytes(packet)));
+}
+export function frameMailBytes(bytes) {
+    requireMail(bytes.length > 0 && bytes.length <= MAIL_MAX_PACKET_BYTES, "invalid_packet", "invalid frame input length");
+    const frame = new Uint8Array(1024 * Math.ceil((4 + bytes.length) / 1024));
+    new DataView(frame.buffer).setUint32(0, bytes.length, false);
+    frame.set(bytes, 4);
+    return frame;
+}
+export function unframeMailLetter(frame) {
+    requireMail(frame.length >= 1024 &&
+        frame.length <= MAIL_MAX_PACKET_BYTES &&
+        frame.length % 1024 === 0, "invalid_packet", "invalid frame length");
+    const n = new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(0, false);
+    requireMail(n > 0 &&
+        n <= frame.length - 4 &&
+        frame.length === 1024 * Math.ceil((4 + n) / 1024), "invalid_packet", "invalid/nonminimal frame length");
+    requireMail(frame.subarray(4 + n).every((x) => x === 0), "invalid_packet", "nonzero padding");
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(frame.subarray(4, 4 + n));
+    }
+    catch {
+        throw protocolError("invalid_packet", "invalid UTF-8 frame");
+    }
+    const letter = parseStrictJson(text);
+    requireMail(canonicalize(letter) === text, "invalid_packet", "noncanonical letter JSON");
+    validateMailLetter(letter);
+    return letter;
+}
+const hpke = () => new CipherSuite({
+    kem: new DhkemX25519HkdfSha256(),
+    kdf: new HkdfSha256(),
+    aead: new Chacha20Poly1305(),
+});
+/** Independent raw X25519 secret. Never derive this from an Identity signing key. */
+export class MailEncryptionKey {
+    secret;
+    destroyed = false;
+    constructor(secret) {
+        requireMail(secret.length === 32, "invalid_private_key");
+        this.secret = new Uint8Array(secret);
+    }
+    static generate() {
+        return new MailEncryptionKey(nacl.randomBytes(32));
+    }
+    static fromBytes(secret) {
+        return new MailEncryptionKey(secret);
+    }
+    publicKey() {
+        requireMail(!this.destroyed, "invalid_private_key", "key destroyed");
+        return base64UrlEncode(nacl.scalarMult.base(this.secret));
+    }
+    /** Sensitive backup material: store only in an owner-controlled encrypted key store. */
+    exportSecret() {
+        requireMail(!this.destroyed, "invalid_private_key", "key destroyed");
+        return new Uint8Array(this.secret);
+    }
+    destroy() {
+        this.secret.fill(0);
+        this.destroyed = true;
+    }
+}
+/** Stateless encryption with fresh HPKE randomness. Pin the card with MailCardCache first. */
+export async function sealMailPacket(letter, card, now = Date.now()) {
+    letter = clone(letter);
+    card = clone(card);
+    validateMailLetter(letter);
+    validateMailSenderCard(card, letter.event.payload.to, now);
+    requireMail(letter.event.created_at <= now + MAIL_FUTURE_SKEW_MS &&
+        now < letter.event.payload.expires_at, "packet_expired", "letter is expired or future-dated");
+    const c = card.event.payload;
+    requireMail(letter.event.payload.expires_at <= c.receive_until, "invalid_packet", "letter exceeds receive_until");
+    const header = {
+        protocol: MAIL_PROTOCOL,
+        mailbox_id: c.mailbox_id,
+        card_hash: card.hash,
+        expires_at: letter.event.payload.expires_at,
+    };
+    const plaintext = frameMailBytes(mailCanonicalBytes(letter));
+    // Check base64/JSON overhead before allocating an HPKE context.
+    const estimate = {
+        header,
+        enc: base64UrlEncode(new Uint8Array(32)),
+        ciphertext: base64UrlEncode(new Uint8Array(plaintext.length + 16)),
+    };
+    requireMail(mailCanonicalBytes(estimate).length <= c.max_packet_bytes, "payload_too_large", "packet exceeds card limit");
+    const suite = hpke();
+    const sender = await suite.createSenderContext({
+        recipientPublicKey: await suite.kem.deserializePublicKey(decodeMailBytes(c.public_key, 32)),
+        info: INFO,
+    });
+    try {
+        const ct = await sender.seal(plaintext, mailCanonicalBytes(header));
+        return {
+            header,
+            enc: base64UrlEncode(new Uint8Array(sender.enc)),
+            ciphertext: base64UrlEncode(new Uint8Array(ct)),
+        };
+    }
+    finally {
+        plaintext.fill(0);
+    } // Context is never reused; JS cannot guarantee erasure of provider-owned/GC copies.
+}
+/** Verify/decrypt a queued letter; expiration of new acceptance is checked by MailInbox. */
+export async function openMailPacket(packet, card, key, owner, now = Date.now(), expectedId) {
+    packet = clone(packet);
+    card = clone(card);
+    safeTime(now);
+    const bytes = packetBytes(packet, expectedId);
+    validateMailboxCard(card, owner);
+    return openVerified(packet, bytes, card, key, owner, now);
+}
+/** Open with a card that was already verified for `owner` (the keyring verifies at `add`). */
+async function openVerified(packet, bytes, card, key, owner, now) {
+    const c = card.event.payload, h = packet.header;
+    requireMail(h.card_hash === card.hash && h.mailbox_id === c.mailbox_id, "invalid_packet", "card/header binding mismatch");
+    requireMail(bytes.length <= c.max_packet_bytes, "payload_too_large", "packet exceeds card limit");
+    requireMail(h.expires_at <= c.receive_until, "invalid_packet", "packet exceeds receive_until");
+    requireMail(key.publicKey() === c.public_key, "invalid_private_key", "recipient secret does not match card");
+    const secret = key.exportSecret();
+    let plaintext;
+    try {
+        const suite = hpke();
+        const ctx = await suite.createRecipientContext({
+            recipientKey: await suite.kem.deserializePrivateKey(secret),
+            enc: decodeMailBytes(packet.enc, 32),
+            info: INFO,
+        });
+        plaintext = new Uint8Array(await ctx.open(decodeMailBytes(packet.ciphertext), mailCanonicalBytes(h)));
+    }
+    catch {
+        throw protocolError("invalid_packet", "HPKE opening failed");
+    }
+    finally {
+        secret.fill(0);
+    }
+    try {
+        const letter = unframeMailLetter(plaintext);
+        requireMail(letter.event.payload.to === owner, "invalid_packet", "letter recipient mismatch");
+        requireMail(letter.event.payload.expires_at === h.expires_at, "invalid_packet", "letter/header expiration mismatch");
+        requireMail(letter.event.created_at <= now + MAIL_FUTURE_SKEW_MS, "timestamp_out_of_window", "future letter");
+        return letter;
+    }
+    finally {
+        plaintext.fill(0);
+    }
+}
+/**
+ * Sender-side card pins: the greatest-nonce card seen per (owner, mailbox),
+ * including closed or expired cards. Persist the snapshot after every observe,
+ * even one that throws because the new pin is unusable.
+ */
+export class MailCardCache {
+    pins = new Map();
+    constructor(snapshot) {
+        if (snapshot) {
+            requireMail(snapshot.version === 1, "invalid_request");
+            for (const card of snapshot.pins) {
+                validateMailSchema(card, "mailboxCardEnvelope");
+                this.pins.set(this.id(card.event.actor, card.event.payload.mailbox_id), clone(card));
+            }
+        }
+    }
+    id(owner, mailbox) {
+        return owner + ":" + mailbox;
+    }
+    snapshot() {
+        return { version: 1, pins: clone([...this.pins.values()]) };
+    }
+    /** Pin a verified card, then (by default) require that it is usable for new encryption. */
+    observe(card, owner, now = Date.now(), requireUsable = true) {
+        card = clone(card);
+        safeTime(now);
+        validateMailboxCard(card, owner);
+        requireMail(card.event.created_at <= now + MAIL_FUTURE_SKEW_MS, "timestamp_out_of_window", "card is future-dated");
+        const id = this.id(owner, card.event.payload.mailbox_id), pin = this.pins.get(id);
+        if (pin && pin.hash !== card.hash)
+            requireMail(card.event.nonce > pin.event.nonce, "stale_card", "card is older than or conflicts with the pinned card");
+        this.pins.set(id, card);
+        if (requireUsable)
+            validateMailSenderCard(card, owner, now);
+        return clone(card);
+    }
+    /** Drop pins old enough that every earlier card of the mailbox has expired. */
+    prune(now = Date.now()) {
+        safeTime(now);
+        for (const [id, pin] of this.pins)
+            if (now >= pin.event.created_at + MAIL_MAX_TTL_MS + MAIL_FUTURE_SKEW_MS)
+                this.pins.delete(id);
+    }
+    async seal(letter, card, now = Date.now()) {
+        return sealMailPacket(letter, this.observe(card, letter.event.payload.to, now), now);
+    }
+}
+/** Retained verified cards and their secrets, looked up by card hash until receive_until. */
+export class MailKeyring {
+    owner;
+    entries = new Map();
+    constructor(owner) {
+        this.owner = owner;
+        validateAgentId(owner);
+    }
+    add(card, key) {
+        card = clone(card);
+        validateMailboxCard(card, this.owner);
+        requireMail(key.publicKey() === card.event.payload.public_key, "invalid_private_key", "recipient secret does not match card");
+        this.entries.get(card.hash)?.key.destroy();
+        this.entries.set(card.hash, {
+            card,
+            key: MailEncryptionKey.fromBytes(key.exportSecret()),
+        });
+    }
+    /** Sensitive snapshot, including raw encryption secrets. Protect it separately from logs and application data. */
+    exportSnapshot() {
+        return {
+            version: 1,
+            owner: this.owner,
+            entries: [...this.entries.values()].map((x) => ({
+                card: clone(x.card),
+                secret: base64UrlEncode(x.key.exportSecret()),
+            })),
+        };
+    }
+    static restore(snapshot) {
+        requireMail(snapshot.version === 1, "invalid_request");
+        const r = new MailKeyring(snapshot.owner);
+        for (const x of snapshot.entries)
+            r.add(x.card, MailEncryptionKey.fromBytes(decodeMailBytes(x.secret, 32)));
+        return r;
+    }
+    prune(now = Date.now()) {
+        safeTime(now);
+        for (const [hash, x] of this.entries)
+            if (now >= x.card.event.payload.receive_until) {
+                x.key.destroy();
+                this.entries.delete(hash);
+            }
+    }
+    async open(packet, now = Date.now(), expectedId) {
+        packet = clone(packet);
+        safeTime(now);
+        const bytes = packetBytes(packet, expectedId);
+        const x = this.entries.get(packet.header.card_hash);
+        requireMail(x, "invalid_packet", "unknown retained card");
+        return openVerified(packet, bytes, x.card, x.key, this.owner, now);
+    }
+}
+/**
+ * Cross-route letter deduplication. The application stores accepted letters;
+ * persist the snapshot with them before deleting relay copies or acting.
+ */
+export class MailInbox {
+    keyring;
+    accepted = new Map();
+    constructor(keyring, snapshot) {
+        this.keyring = keyring;
+        if (snapshot) {
+            requireMail(snapshot.version === 1 && snapshot.owner === keyring.owner, "invalid_request");
+            for (const [id, expires] of snapshot.accepted)
+                this.accepted.set(id, expires);
+        }
+    }
+    snapshot() {
+        return {
+            version: 1,
+            owner: this.keyring.owner,
+            accepted: [...this.accepted],
+        };
+    }
+    has(letterId) {
+        return this.accepted.has(letterId);
+    }
+    async accept(packet, now = Date.now(), expectedId) {
+        const letter = await this.keyring.open(packet, now, expectedId);
+        // No await between lookup and commit: concurrent decryptions cannot both accept.
+        if (this.accepted.has(letter.hash))
+            return { kind: "duplicate", letter };
+        requireMail(now < letter.event.payload.expires_at, "packet_expired", "expired new letter");
+        this.accepted.set(letter.hash, letter.event.payload.expires_at);
+        return { kind: "accepted", letter };
+    }
+    /** Forget letters whose signed expiration has passed; they can no longer be newly accepted. */
+    prune(now = Date.now()) {
+        safeTime(now);
+        for (const [id, expires] of this.accepted)
+            if (now >= expires)
+                this.accepted.delete(id);
+    }
+}
+export function validateMailDiscovery(value, service) {
+    validateMailSchema(value, "discoveryDocument");
+    validateOrigin(service);
+    requireMail(value.service === service, "invalid_response", "discovery origin mismatch");
+}
+function ownerClaims(token, service, now) {
+    safeTime(now);
+    try {
+        return verifyRequestJwt(token, {
+            audience: service,
+            nowSecs: Math.floor(now / 1000),
+        });
+    }
+    catch {
+        throw protocolError("invalid_token", "invalid mailbox owner JWT");
+    }
+}
+/** Identity request JWT for this relay origin whose subject is the mailbox owner. */
+export function validateMailOwnerJwt(token, service, owner, now = Date.now()) {
+    validateOrigin(service);
+    validateAgentId(owner);
+    requireMail(ownerClaims(token, service, now).iss === owner, "permission_denied", "not mailbox owner");
+}
+export function validateMailCardRecord(value, owner, mailboxId, hash) {
+    validateMailSchema(value, "cardAcceptedRecord");
+    const r = value;
+    validateMailboxCard(r.envelope, owner);
+    requireMail((mailboxId === undefined ||
+        r.envelope.event.payload.mailbox_id === mailboxId) &&
+        (hash === undefined || r.envelope.hash === hash), "invalid_response", "card record mismatch");
+}
+export function validateMailDeliveryResult(value, packet) {
+    validateMailSchema(value, "deliveryResult");
+    const r = value;
+    if (packet !== undefined)
+        requireMail(r.packet_id === mailPacketId(packet) &&
+            r.accepted_at < packet.header.expires_at, "invalid_response", "delivery result mismatch");
+}
+export function validateMailPacketRecord(value, mailboxId) {
+    validateMailSchema(value, "packetRecord");
+    const r = value;
+    validateMailPacket(r.packet, r.packet_id);
+    requireMail(r.accepted_at < r.packet.header.expires_at &&
+        (mailboxId === undefined || r.packet.header.mailbox_id === mailboxId), "invalid_response", "packet record mismatch");
+}
+export function validateMailPacketList(value, mailboxId, limit = 100) {
+    validateMailSchema(value, "packetList");
+    const p = value;
+    requireMail(p.result.length <= limit && (!p.next_cursor || p.result.length > 0), "invalid_response", "invalid page size");
+    let seq = 0;
+    for (const r of p.result) {
+        validateMailPacketRecord(r, mailboxId);
+        requireMail(r.seq > seq, "invalid_response", "unordered packets");
+        seq = r.seq;
+    }
+}
+/**
+ * Synchronous process-local relay model. All validation precedes mutation;
+ * persist the snapshot atomically before emitting a successful HTTP response.
+ * The short-lived nonce cache is not part of the snapshot.
+ */
+export class MailRelayStore {
+    origin;
+    boxes = new Map();
+    nonces;
+    clock;
+    maxPackets;
+    maxBytes;
+    constructor(origin, options = {}) {
+        this.origin = origin;
+        validateOrigin(origin);
+        this.nonces = options.nonceStore ?? new MemoryNonceStore();
+        this.clock = options.clock ?? Date.now;
+        this.maxPackets = options.maxPackets ?? 10000;
+        this.maxBytes = options.maxBytes ?? 64 * MAIL_MAX_PACKET_BYTES;
+        requireMail(Number.isSafeInteger(this.maxPackets) &&
+            this.maxPackets > 0 &&
+            Number.isSafeInteger(this.maxBytes) &&
+            this.maxBytes > 0, "invalid_request", "invalid quota");
+        const s = options.snapshot;
+        if (s) {
+            requireMail(s.version === 1 && s.origin === origin, "invalid_request", "snapshot origin mismatch");
+            for (const m of s.mailboxes) {
+                const box = {
+                    current: clone(m.current),
+                    lastSeq: m.last_seq,
+                    bytes: 0,
+                    packets: new Map(),
+                    tombstones: new Map(),
+                };
+                for (const record of m.packets) {
+                    const size = mailCanonicalBytes(record.packet).length;
+                    box.packets.set(record.packet_id, { record: clone(record), size });
+                    box.bytes += size;
+                }
+                for (const t of m.tombstones)
+                    box.tombstones.set(t.packet_id, {
+                        accepted_at: t.accepted_at,
+                        expires_at: t.expires_at,
+                    });
+                this.boxes.set(m.current.envelope.event.payload.mailbox_id, box);
+            }
+        }
+    }
+    snapshot() {
+        return {
+            version: 1,
+            origin: this.origin,
+            mailboxes: [...this.boxes.values()].map((b) => ({
+                current: clone(b.current),
+                last_seq: b.lastSeq,
+                packets: [...b.packets.values()].map((p) => clone(p.record)),
+                tombstones: [...b.tombstones].map(([packet_id, t]) => ({
+                    packet_id,
+                    ...t,
+                })),
+            })),
+        };
+    }
+    discovery() {
+        return { protocol: MAIL_PROTOCOL, service: this.origin };
+    }
+    publish(card, now = this.clock()) {
+        card = clone(card);
+        safeTime(now);
+        validateMailboxCard(card);
+        const p = card.event.payload, b = this.boxes.get(p.mailbox_id);
+        if (b) {
+            const current = b.current.envelope;
+            requireMail(current.event.actor === card.event.actor, "mailbox_conflict", "mailbox belongs to another owner");
+            if (current.hash === card.hash)
+                return clone(b.current);
+            if (card.event.nonce <= current.event.nonce)
+                throw protocolError("nonce_not_greater", "card nonce does not advance", {
+                    max_nonce: current.event.nonce,
+                });
+        }
+        else
+            requireMail(p.routes.includes(this.origin), "permission_denied", "first card must list this relay");
+        verifyTimestamp(card.event.created_at, now, MAIL_FUTURE_SKEW_MS);
+        // The final fallible step, so a rejected card consumes no nonce.
+        this.nonces.checkAndUpdate(card.event.actor, card.event.nonce, now, 2 * MAIL_FUTURE_SKEW_MS);
+        const record = { envelope: card, accepted_at: now };
+        if (b)
+            b.current = record;
+        else
+            this.boxes.set(p.mailbox_id, {
+                current: record,
+                lastSeq: 0,
+                bytes: 0,
+                packets: new Map(),
+                tombstones: new Map(),
+            });
+        return clone(record);
+    }
+    card(mailboxId) {
+        pathId(mailboxId, 16);
+        const b = this.boxes.get(mailboxId);
+        requireMail(b, "mailbox_unavailable");
+        return clone(b.current);
+    }
+    publishJson(text, now = this.clock()) {
+        requireMail(encoder.encode(text).length <= MAIL_MAX_PACKET_BYTES, "payload_too_large");
+        return this.publish(parseStrictJson(text), now);
+    }
+    deliverJson(mailboxId, text, now = this.clock()) {
+        requireMail(encoder.encode(text).length <= MAIL_MAX_PACKET_BYTES, "payload_too_large");
+        return this.deliver(mailboxId, parseStrictJson(text), now);
+    }
+    deliver(mailboxId, packet, now = this.clock()) {
+        packet = clone(packet);
+        safeTime(now);
+        pathId(mailboxId, 16);
+        const bytes = packetBytes(packet), size = bytes.length;
+        const h = packet.header;
+        requireMail(h.mailbox_id === mailboxId, "invalid_packet", "path mailbox mismatch");
+        const b = this.boxes.get(mailboxId);
+        requireMail(b, "mailbox_unavailable");
+        const id = base64UrlEncode(sha3_256(bytes)), prior = b.tombstones.get(id);
+        if (prior)
+            return { packet_id: id, accepted_at: prior.accepted_at };
+        const c = b.current.envelope, p = c.event.payload;
+        requireMail(p.routes.includes(this.origin), "mailbox_unavailable");
+        requireMail(h.card_hash === c.hash && now < p.expires_at, "stale_card");
+        requireMail(now < h.expires_at, "packet_expired");
+        requireMail(h.expires_at <= p.receive_until &&
+            h.expires_at - now <= MAIL_MAX_TTL_MS + MAIL_FUTURE_SKEW_MS, "invalid_packet", "packet lifetime exceeds bound");
+        requireMail(size <= p.max_packet_bytes, "payload_too_large", "packet exceeds card limit");
+        this.dropExpired(b, now);
+        requireMail(b.packets.size < this.maxPackets &&
+            b.bytes + size <= this.maxBytes &&
+            b.lastSeq < Number.MAX_SAFE_INTEGER, "rate_limited", "mailbox storage quota exhausted");
+        b.lastSeq += 1;
+        b.packets.set(id, {
+            record: { packet_id: id, packet, accepted_at: now, seq: b.lastSeq },
+            size,
+        });
+        b.bytes += size;
+        b.tombstones.set(id, { accepted_at: now, expires_at: h.expires_at });
+        return { packet_id: id, accepted_at: now };
+    }
+    ownerBox(mailboxId, jwt, now) {
+        pathId(mailboxId, 16);
+        const claims = ownerClaims(jwt, this.origin, now);
+        const b = this.boxes.get(mailboxId);
+        requireMail(b, "mailbox_unavailable");
+        requireMail(claims.iss === b.current.envelope.event.actor, "permission_denied", "not mailbox owner");
+        return b;
+    }
+    list(mailboxId, jwt, options = {}) {
+        const now = options.now ?? this.clock();
+        safeTime(now);
+        const b = this.ownerBox(mailboxId, jwt, now), limit = options.limit ?? 100, cursor = options.cursor;
+        requireMail(Number.isSafeInteger(limit) && limit >= 1 && limit <= 1000, "invalid_request", "invalid limit");
+        // The cursor is the last returned seq; ownership is checked by the JWT.
+        requireMail(cursor === undefined ||
+            (/^(0|[1-9][0-9]*)$/.test(cursor) &&
+                Number.isSafeInteger(Number(cursor))), "invalid_request", "invalid cursor");
+        const after = cursor === undefined ? 0 : Number(cursor);
+        const rows = [...b.packets.values()]
+            .map((x) => x.record)
+            .filter((r) => r.seq > after && now < r.packet.header.expires_at);
+        const result = clone(rows.slice(0, limit));
+        return rows.length > limit
+            ? { result, next_cursor: String(result.at(-1).seq) }
+            : { result };
+    }
+    delete(mailboxId, packetId, jwt, now = this.clock()) {
+        const b = this.ownerBox(mailboxId, jwt, now);
+        pathId(packetId, 32);
+        const stored = b.packets.get(packetId);
+        if (stored) {
+            b.packets.delete(packetId);
+            b.bytes -= stored.size;
+        }
+    }
+    /** Drop expired packets and tombstones, then forget mailboxes whose current card's `receive_until` passed. */
+    prune(now = this.clock()) {
+        safeTime(now);
+        for (const [mailboxId, b] of this.boxes) {
+            this.dropExpired(b, now);
+            for (const [id, t] of b.tombstones)
+                if (now >= t.expires_at)
+                    b.tombstones.delete(id);
+            if (now >= b.current.envelope.event.payload.receive_until)
+                this.boxes.delete(mailboxId);
+        }
+    }
+    dropExpired(b, now) {
+        for (const [id, x] of b.packets)
+            if (now >= x.record.packet.header.expires_at) {
+                b.packets.delete(id);
+                b.bytes -= x.size;
+            }
+    }
+}
+//# sourceMappingURL=mail.js.map