Module mail 

Agent Mail 1.0: signed cards and letters, HPKE packets, and explicit local state.

Relays never receive decryption keys. A verified letter is untrusted content, not authorization to execute a task. State helpers are in-memory models; applications must persist snapshots atomically before acknowledging delivery. Relay paths are fixed at {route}/v1/mailboxes.

Structs

DeliveryResult

Anonymous delivery result. It never carries the mailbox seq.

MailAddress

A parsed mailbox address (Mail Section 3.3). routes is empty for the stable form.

MailCardCache

Sender-side pins: the greatest-nonce card seen per (owner, mailbox), including closed or expired cards. Save snapshot() after every observation, even one that returns an error for an unusable new pin.

MailEncryptionKey

Independent X25519 secret. Debug output and implicit serialization are absent. export_secret is explicit and returns a buffer zeroized on drop.

MailInbox

Cross-route letter deduplication. The application stores accepted letters; persist the inbox snapshot with them before deleting relay copies or acting. accept never executes content or sends replies.

MailKeyring

Retained verified cards and their secrets, by card hash, through receive_until.

MailPart

MailRelayStore

Framework-neutral in-memory relay model, NOT a hosted or durable service. All outputs are owned copies. Save/restore snapshots atomically in a real service; enforce admission limits and serialized access outside this model. The short-lived Identity nonce cache is not part of the snapshot.

MailboxCardPayload

MessagePayload

Packet

PacketHeader

PacketRecord

Enums

InboxAcceptance

Constants

FUTURE_SKEW_MS

MAX_PACKET_BYTES

MAX_TTL_MS

PROTOCOL

SCHEMA_JSON

Functions

canonical_bytes

decode_bytes

decrypt_packet

Stateless authenticated opening of a historical packet. This verifies shape, cryptography and future skew; callers must enforce new-acceptance expiry and durable deduplication (MailInbox implements those state transitions).

encode_bytes

encrypt_letter

Production encryption: fresh system randomness, one HPKE context per packet. Caller should observe the card with CardCache before using it.

format_mail_address

Format the stable address, or a contact address when routes are given.

frame_bytes

Exact framing, also useful for boundary conformance tests. Inputs are bounded.

hash_bytes

packet_id

parse_card

parse_letter

parse_mail_address

Parse did:agent:<key>/mail/<mailbox_id>[?route=<origin>...] (Mail Section 3.3).

parse_packet

random_id

sign_card

sign_message

validate_card

Historical verification: checks intrinsic validity, not live-write freshness.

validate_card_for_sending

validate_discovery

Informational discovery document; it never supplies delivery paths.

validate_letter

Verify a letter as a historical object. Freshness/deduplication is performed by MailInbox, so a delayed low-nonce letter is never rejected here.

validate_mail_schema

Validate a named structural definition; signatures and semantics are separate.

validate_packet

validate_reply

Bind a reply to a known parent: participants, parent letter ID, and thread.

verify_owner_jwt

Identity request JWT for this relay origin whose subject is the mailbox owner.

Type Aliases

Letter

MailboxCard