Keylist management in practice

A mediation grant says we will carry mail for you. The keylist says for which addresses. It is the smaller idea and it causes most of the operational surprises, so it is worth understanding concretely rather than as a protocol diagram.

What a keylist is

A list of recipient keys the mediator will accept and queue messages for, held per mediation. Your agent adds keys with a keylist-update; the mediator confirms which updates it applied.

A message addressed to a key that is not on the list is not queued. That is the single most useful fact on this page: when mail seems to vanish, check the keylist before you suspect the queue, the sender, or the network. The mediator is not silently dropping your messages: it never accepted them, because it was never told that address was yours.

The normal lifecycle

1. Grant: you are mediated. The keylist starts empty.
2. Add, for each recipient key you want mail for, send a keylist-update. Confirmation tells you what was actually applied; do not assume.
3. Publish, put the mediator's routing key and endpoint in the DID document for that identity. The forward message and routing keys covers why both halves are required, a key on the list with nothing published receives nothing.
4. Remove, when you retire an identity, remove its key. The mediator stops accepting for it.

Churn is normal, not exceptional

Because a distinct key per correspondent is the strongest privacy control available to you, a well-behaved agent adds and removes keys routinely, see pairwise DID.

Build for that. An integration that treats keylist updates as rare setup will accumulate stale entries, and stale entries are exactly what a mediator keeps accepting mail for long after you stopped reading it.

The two failure modes worth naming

Drift between the keylist and your DID documents. These are two separate publications and nothing keeps them in step for you. A key on the mediator's list but absent from any DID document is harmless but pointless; a routing key published in a DID document that the mediator does not hold on any keylist is a black hole, correspondents send confidently and nothing is ever queued.

Removing a key while messages are queued for it. Decide deliberately what should happen to mail already held for an address you are retiring, rather than discovering the answer in production.

What the keylist tells the mediator about you

It groups your identities. A keylist is, by construction, a statement that these keys belong to the same mediated agent, so pairwise keys that look unrelated to the outside world are visibly related to the mediator.

That is not a flaw to be fixed; it is what mediation requires. It is also precisely the sort of thing a privacy page should say rather than leave implied: what a mediator can and cannot see.

Operationally

Agents and their mediations live on the authenticated operator plane:

curl -s -o /dev/null -w '%{http_code}\n' https://relay.solidus.network/v1/agents
# 401

The public console preview renders sample data and says so: the keylists visible there are illustrative. See reading the operator console.

Relay implements Coordinate Mediation 2.0 and Pickup 3.0; no independent DIDComm conformance suite has been run, so "implements" is the claim and "conformant" is not.