For implementers

Resolving a handle needs no account

Resolution looks up the whole handle as one string. The answer is the agent's card, signed by whoever serves it (§5.1, §5.3). A handle is also a valid acct: URI, so WebFinger finds the card (§5.2). A resolver asks the domain in the address first, because a domain that serves the records for its own addresses outranks any registrar (§5.5).

These examples use example.agent@commonagent.net, a handle whose domain serves its own records. It exists only as an example: its key was made for this page, and no agent runs behind it.

# the domain's WebFinger record for the handle (RFC 7033)
curl "https://commonagent.net/.well-known/webfinger?resource=acct:example.agent@commonagent.net"

# the card the record links to
curl "https://commonagent.net/api/card/example.agent.json"

# the signing keys, to check the card's signature
curl "https://commonagent.net/api/registrar-key"

For a handle held at a registrar, the card takes one request, GET /api/resolve?handle=<handle>, and the registrar serves WebFinger and its signing keys at the same paths as above. Any conforming registrar serves the same paths and works the same way.

A resolver checks the signature on every card, refuses an unsigned one, and remembers the agent key each handle resolved to, so it can warn when the key changes (§5.3).

What a conforming registrar must do

Section 7 lists the obligations in full. In short, a registrar:

• keeps each handle unique across the whole string, with a cooling-off window before a released name can be claimed again, and never parses handles;
• keeps an append-only, hash-chained history log, and shows each owner only their own entries;
• serves resolution without authentication, signs every card and referral it serves, publishes its signing keys, and refuses to answer when it cannot sign;
• binds a name to an agent only with the proofs of §4, never on email proof alone;
• serves WebFinger for every active handle;
• lets a name leave when its owner moves it, and takes in a name only on a signed referral from the registrar letting go (§5.6);
• limits what callers without an account can cause, per address and overall (§9).

Checking a registrar

Five tests check registrars against each other: moving a name to another registrar, a name leaving, the security of a move, following referrals, and refusing a hostile claim that a name was released. They run as the naming profile of the conformance suite published with Agent Messaging's, using two registrars side by side.

Run a registrar

The Personal Agent Naming registrar is the open-source implementation of this specification, under the Apache 2.0 license. It is one Rust service on Postgres, with a container image at ghcr.io/agentnaming/pan-registrar and a Docker Compose setup in its repository. Its CI runs its own tests and the registrar conformance tests on two registrars side by side.