Module mail 

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

Relays never receive decryption keys. A verified message 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

Sender-authenticated 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 message deduplication. The application stores accepted messages; 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

PacketHeader

PacketPayload

PacketRecord

Enums

InboxAcceptance

Constants

FUTURE_SKEW_MS

MAX_PACKET_BYTES

MAX_TTL_MS

PROTOCOL

SCHEMA_JSON

Functions

canonical_bytes

create_mail_message

decode_bytes

decrypt_packet

Historical verification and opening; inbox acceptance handles expiry and dedup.

encode_bytes

encrypt_message

Encrypt immutable plaintext with fresh HPKE randomness, then sign the packet.

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

mail_packet_aad

Exact context bound to encryption, derived from the verified outer event.

packet_id

parse_card

parse_mail_address

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

parse_message

parse_packet

random_id

sign_card

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_mail_schema

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

validate_message

Validate immutable plaintext. Authentication comes from its signed packet.

validate_packet

validate_reply

Bind an immutable reply to both participants and its parent’s logical ID.

verify_owner_jwt

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

Type Aliases

MailboxCard

Packet

The signed mail.submit envelope: the wire object relays store and recipients open.