Skip to content

Relay protocol

  • What it is: a third transport for when LAN cannot reach a paired host. The relay holds no private keys, decides no authorization, and never carries plaintext bodies — only envelopes whose enc field seals the body for the recipient (see Envelope). Tamper and sender enforcement stay receiver-side, exactly like LAN.
  • Enrolment: POST /v1/relay/challenge → single-use nonce; POST /v1/relay/enrol with {host, pubkey, owner_fp, sig} where sig is the host key over the challenge. No anonymous or bearer registration. Enrolment publishes the host’s signed enc-key advertisement (POST /v1/relay/enc-key), readable by any enrolled host (GET /v1/relay/enc-key?host=…).
  • Push: POST /v1/relay/messages {envelopes:[…]} — host-authenticated (same signed-hop shape as LAN). Stored per recipient host queue. Envelopes with no recipient enc key are refused client-side: mail waits in the sender’s outbox rather than flow as plaintext.
  • Pull/ack: GET /v1/relay/messages?after=<cursor> then POST /v1/relay/ack {cursor}; acked rows are dropped. Storage is exactly-once by envelope id across retries.
  • Quotas (per owner, aggregated across the owner’s hosts): queue depth, envelope size, batch size, owner depth, and a per-minute push rate. Over-limit pushes get an honest error and stop at the limit.
  • Metadata the relay operator sees: envelope ids, addresses, subject, sizes, timing, hop counts. Accepted and documented in the threat model.