How Mediators Work
Mediators are encryption-blind relay servers that route messages and store ciphertext through two communication channels.
Formal spec: DCTRL-0004 — Mediator Protocol defines the HTTP API, command wire format, WebSocket protocol, and all error codes.
Mediators are the infrastructure layer of Decentrl. They're lightweight servers that do exactly two things: route encrypted messages and store encrypted data. They never see plaintext.
What a Mediator Sees
When Alice sends Bob a message through a mediator, the mediator sees:
- Sender DID —
did:decentrl:z6MkpT...(Alice's public identity) - Recipient DID —
did:decentrl:z6MkqR...(Bob's public identity) - Timestamp — when the command was sent
- Encrypted payload — opaque ciphertext
- Encrypted tags — opaque blobs for indexing
The mediator does not see: message content, conversation topics, read receipts, device info, location, or any application-level metadata.
Two Communication Channels
The protocol defines two channels that serve distinct purposes:
DIRECT_AUTHENTICATED
Used for identity-to-mediator administrative operations. The sender signs the command; the mediator verifies the signature against the sender's DID document and checks for an active registration contract.
| Command | Purpose |
|---|---|
REQUEST_COMMUNICATION_CONTRACT | Send a contract request (for registration or forwarding) |
COMMUNICATION_CONTRACT_RESPONSE | Deliver signed contract response |
QUERY_PENDING_COMMUNICATION_CONTRACT_REQUESTS | List inbound pending contract requests |
ACKNOWLEDGE_PENDING_COMMUNICATION_CONTRACT_REQUESTS | Clear processed requests |
SAVE_COMMUNICATION_CONTRACT | Store a completed contract |
QUERY_COMMUNICATION_CONTRACTS | List active contracts |
QUERY_PENDING_EVENTS | List unacknowledged events from others |
ACKNOWLEDGE_PENDING_EVENTS | Mark events as processed |
SAVE_EVENTS | Store encrypted events |
QUERY_EVENTS | Query stored events with tag filters |
UPDATE_EVENT_TAGS | Replace tags on stored events |
TWO_WAY_PRIVATE
Used for encrypted event delivery between identities. When Alice sends Bob an event:
- The mediator verifies Alice's signature on the command
- Checks that Bob is registered with this mediator
- Checks that a valid, non-expired communication contract exists between Alice and Bob
- Stores the payload as a pending event for Bob
The payload is an opaque encrypted string. The mediator stores it without any ability to inspect its contents.
Authorization Model
Every command to a mediator must be signed. The mediator resolves the sender's DID, extracts their public signing key, and verifies the signature. Additionally:
- DIRECT_AUTHENTICATED commands require an active registration contract (client-to-mediator contract)
- TWO_WAY_PRIVATE commands require both an active registration contract and a valid bilateral communication contract between sender and recipient
No unsigned command is ever processed. No command without proper contracts is ever accepted.