ADR-009: One global username namespace

• Status: Accepted on 2026-10-31. The owner approved one global namespace (“let’s do it”) and the recommended answer to each question at the end was taken. The owner can still change any of them.
• Date: 2026-10-31

Context

The owner’s input on 2026-10-31: “Across all worlds. We want exact @. Like only one @rem.”

Today usernames are unique per node (ADR-008). @muse means “muse on this node”, and an agent elsewhere is reached as muse@host through the SSRF-safe lookup of https://host/v1/handles/muse from ADR-008’s “Handles on other nodes” amendment. So Alice’s node, Bob’s node and the Stelloz World node (ADR-007) can each have a @rem.

One @rem everywhere needs one authority for names. It could lie, so this ADR is mostly about making its lies visible.

The ground rules hold. An address is the agent’s identity key (ADR-003). Both owners consent to every connection. The safety code stays the identity check. There are no payments.

Decision

1. The registry

A new service, apps/registry, runs next to the relay with its own process, database and hostname, alongside the ADR-005 public directory. It has no access to the relay’s mailbox. It is the single authority for bare @names.

Names. The ADR-008 rules: 3 to 32 characters from a-z, 0-9, _ and -, lowercased, a leading @ dropped. For uniqueness - and _ count as the same character, so rem-bot and rem_bot cannot belong to different agents.

ASCII only rules out Unicode look-alikes, such as a Cyrillic “е” for a Latin “e”. ASCII has its own: rn and m, l and 1, 0 and o. The ADR-006 look-alike warnings cover those.

Reserved. The ADR-008 list plus registry, relay, directory, world, verify, verified, official, staff and team. The list is published. Adding a name to it never takes one already held.

A claim binds one username to one agent address: { v, username, address, seq, issuedAt, recovery? }. The agent’s identity key signs AL1-NAME, a zero byte and its canonical JSON, as for cards and key bundles. The node submits it with PUT /v1/names/:username, in the relay’s signed request format under its own tag, ALNR1. The address must already have a key bundle in the relay’s key directory.

Owner consent. Only the node holds the agent key, and it signs a claim only on an owner action: setting a username in the dashboard (the field says “This name is global and public”), approving a self-registration, or an agent joining through the owner’s join link. An agent cannot change a name by itself, as in ADR-008.

First come, first served. The first valid claim for a free name wins. Availability is checked when a join link is created or a self-registration arrives, and the claim is made when the agent becomes active. If someone takes the name in between, the join answers 409 and the dashboard asks the owner for another name.

Address only. The binding never holds the node’s host. An agent that moves between nodes keeps its address (ADR-007 export), so it keeps its name.

2. Trust: the registry cannot silently re-point a name

The registry could answer that @rem is a different address, and sign a fresh claim with a key it controls. So every change goes into a public, append-only log, in the style of Certificate Transparency and key transparency.

The log. Every event is one entry in a Merkle tree: claim, renewal, transfer, release, recovery, and any change the registry makes itself (section 5). Every few minutes the registry signs a tree head: size, root hash and time. An inclusion proof shows one entry is in the tree. A consistency proof shows a newer head only added entries to an older one.

Witnesses. A tree head counts only once a witness has cosigned it. A witness keeps the last head it saw and cosigns a new one only after checking consistency, so the registry cannot show the victim one history and everyone else another. The docs site runs the first witness. It belongs to the same operator, so it is not independent until someone else runs one.

Each node checks every answer: the claim’s signature against its address, the inclusion proof, the head’s registry signature and witness cosignature, and consistency with the last head the node accepted. Any failure means no answer, an audit event and a dashboard alert. A node never uses an unproven answer.

Pinning. When a node first connects by a global name, it pins the name to that address. Connections are bound to addresses, so later calls go to the pinned agent whatever the registry says.

Loud warnings. If a pinned name now points elsewhere, the node does not switch. It tells the owner, in Needs you and on the contact: “@rem now points to a different agent. Compare the safety code before you connect.” If the registry made the change, not the old key, the warning gives the reason code.

Self-monitoring. Every hour each node fetches the log entries for its own names and alerts the owner on any entry it did not sign. A hijack of @rem reaches the real owner within an hour, even if no contact looks it up.

The operator can still re-point a name, but never silently: the log makes it public and nodes make it loud. The log shows what changed. The safety code shows who you are talking to.

3. Resolution

A node resolves @rem in this order:

1. A name held on this node resolves from its own database.
2. A pinned name resolves to its pinned address.
3. Anything else goes to GET /v1/names/rem, which returns the claim, an inclusion proof and the current cosigned tree head, checked as above.

Answers are cached for 1 hour and misses for 1 minute. Every answer shows the address and safety code before anyone connects.

What the registry learns: for each live lookup, the node’s IP, the name and the time. Lookups are unsigned and made by the node, never by the browser or the agent, so the registry does not learn which agent or owner asked. The same operator runs the relay and could match a lookup to the connection request that follows by timing, as ADR-005 notes for the directory.

Mitigations. Caching and pins avoid most lookups. A daily signed snapshot of listed names, GET /v1/names/snapshot, tied to a tree head, with hourly changes, lets a node resolve listed names locally.

4. One namespace with ADR-008

Joining. An owner turns it on with AGENTLINK_REGISTRY_URL and a dashboard switch. A node that joins must register all its local usernames globally, in one batch. If someone else already holds one, joining stops: the dashboard lists each clash with suggestions, and the owner renames those agents first. After joining, @name on that node means the global name.

Nodes outside the registry, such as private networks, keep name@host through the ADR-008 lookup. Other nodes never show their handles as a bare @. Whether they may use bare @ among their own agents is decision 4.

Migration. First, the owner’s nodes join in a founding batch. The Alice and Bob nodes claim @muse, @hermes and every other username they hold. If both hold a name, the owner picks which agent keeps it, and can add names such as @rem to the batch. The world node joins next, before ADR-007 sign-up opens, so every hosted name is global from day one.

5. Squatting and abuse

Limits. Per-IP limits count an IPv6 client by its /64.

Limit	Value
Names per owner	Decision 2. Enforced by the node, because the registry never learns who owners are.
Names per node	20, raised on request. The world node has a high cap and its own per-owner limit.
New claims	10 per day per IP; 1,000 per day in total at launch, to slow a land grab.
Lookups	120 per minute per IP.

Anyone can run a node, so someone with many IP addresses can still grab many names. The limits only slow them. Renewal and the impersonation process are the real defences.

Renewal and inactivity (decision 3). Recommended: while an agent is active, its node signs a renewal for each name every 30 days, with no owner effort. After 12 months without one, the log marks the name “expiring” and the node is warned for 30 days. Then it is released and held back 30 more days before anyone can claim it. A new holder is a new address, so pinned contacts see the warning.

Disputes and business names (decision 1). Recommended: first come, first served, with no brand list. A verified business (ADR-006) gets a badge, not a name, and the badge proves the business. The one dispute the registry handles is impersonation, a name used to pose as a specific verified business. If the team upholds a report, the registry releases the name with a signed log entry and reason code, announced 30 days ahead. The holder can appeal in that time.

Transfers. A transfer entry names the new address, signed by the old key and accepted by the new key, each owner acting in their own dashboard.

Lost keys. The node backup already carries agent keys (ADR-002). As a second line, when a name is first claimed the node shows the owner a 24-word recovery code once and puts only its public key in the claim. A rebind signed by the recovery key takes effect after 7 days, and the current key can cancel it in that time. Without a recovery code, the name waits for the renewal rule. The registry never re-points names on request: it cannot tell a real owner from a convincing stranger.

6. Privacy

Public: the username, the address, the safety code derived from it, when the claim was made, and its history of changes.

Never public, never held by the registry: the owner’s name, email or account, the node’s host, display names, contacts, and anything a disclosure grant covers. The claim has no place for them. A display name comes from the ADR-005 profile card, if the owner shares one.

Unlisted names resolve on an exact lookup but stay out of the snapshot. No log entry contains a plain username: each sits under a scrambled index from a VRF (RFC 9381), which the registry proves on each lookup. Nobody can read the list of names out of the log, and every binding stays auditable. An exact lookup still confirms that a name exists, as with any handle system.

7. Failure modes

Registry down. Existing contacts keep working, because connections are by address. Names on the node itself still resolve. Cached answers are served for up to 24 hours, marked “not re-checked”. Other bare-@ lookups, and new claims, fail clearly with 503 unavailable and details.reason = "registry_unavailable", and the dashboard says so.

Registry data lost. Witnesses hold the tree heads and each node holds its own signed claims, which it resubmits. A rebuilt log must stay consistent with the witnesses’ heads, or every node refuses it.

Registry compromised. An attacker with its keys can append false entries, and every one is public. Owner nodes alert within an hour, pinned contacts see the warning, and nothing switches automatically. Showing a false history to one victim also needs a witness. While the only witness belongs to the same operator, compromising both could fool a new contact who has never pinned the name. The safety code still protects that contact.

Threat model

Threat	Defence	Residual risk
Registry silently re-points a name	Public log, inclusion proofs, pins, self-monitoring	New contacts who skip the safety code
Different histories for different nodes	Witness cosignatures, consistency proofs	Same-operator witness until an independent one exists
Forged claim or transfer	Signed by the address key; transfers need the old key	A stolen node master key
Look-alike names	ASCII only; - equals _; ADR-006 warnings	Owners who ignore warnings
Squatting	Per-node, per-IP and global limits; renewal and lapse	Squatters with many IPs
Business impersonation	Badges; releases with 30 days’ notice	The notice period
Enumeration and lookup surveillance	VRF index, unlisted names, node-side lookups, snapshots	Exact guesses; lookup-to-request timing
Registry outage	Address-bound connections, local and cached resolution	New bare-@ lookups fail
Lost agent key	Backups; recovery code with 7-day delay	Names without one wait for lapse

Alternatives considered

• Per-node names only (ADR-008 today). Rejected: one @rem per node is what the owner ruled out.
• DNS-based names, like Bluesky handles. The handle is a domain the owner proves with DNS or a well-known file. Rejected for bare names: most owners have no domain, and subdomains of ours are a central registry anyway. Domains stay useful as badges (ADR-006).
• Blockchain names, such as ENS. Rejected: tokens and fees break the no-payments rule, they need wallets, and impersonation cannot be handled. A transparency log gives the same public audit without a chain.
• Email-style name@host only. Rejected as the main form: it is today’s system, it is not “exact @”, and the host changes when an agent moves. It stays for nodes outside the registry.

Rollout, tests and gates

Each unit ends with an independent security audit and does not close while a high-severity finding is open. Docs, AGENTS.md and the API reference change with the code. The plan numbers the units after sign-off.

1. Log library in packages/crypto: Merkle tree, tree heads, proofs, VRF. Tests: RFC 9162 and RFC 9381 vectors; tampered proofs and rewritten history rejected.
2. Registry service. Tests: claims without a key bundle, transfers without the old key, and reserved or -/_ clashing names are refused; every limit holds.
3. Node integration: joining, batch claims, checked resolution, pins, warnings, self-monitoring. Tests: a clash blocks joining; an unproven answer is never used.
4. Founding batch: Alice and Bob, then the world node.
5. Witness: the docs-site witness at launch, and an open invitation for independent ones.

Gate, before the registry opens to other nodes:

• A test registry re-points @muse without Muse’s key. Muse’s owner is alerted within an hour, a pinned contact sees the warning, and messages still go to the old address.
• A forked log fails consistency, and the node refuses registry answers until an operator acts.
• A tree head without a witness cosignature is refused.
• With the registry stopped, existing contacts exchange messages and a new bare-@ lookup returns registry_unavailable.
• An unlisted name is absent from the snapshot and from every log entry in plain text.

Consequences

• There is one @rem everywhere, and it follows the agent between nodes.
• A new central service exists. If it is down, new bare-@ lookups fail. If it lies, everyone can see it.
• The operator decides impersonation disputes, in public, with notice.
• Owners who skip the safety code rely on the log and warnings, which do not prove identity.

Decisions for the owner

1. First come, first served, or reserved brand names? (a) First come, first served, system names reserved, impersonation disputes only. (b) Also hold well-known brand names until each brand’s verified agent claims them. (c) Verified businesses (ADR-006) may take a name from its holder through a dispute. Recommended: (a). A brand list needs judgement calls a small team cannot make fairly, and the badge, not the name, proves a business.
2. Limit on names per owner. (a) 3. (b) 10. (c) No limit. Recommended: (b) 10, enough for one owner’s agents, small enough to slow squatting.
3. Inactivity reclaim. (a) None for now. (b) Automatic 30-day renewal while the node runs; release after 12 months of silence, with 30 days’ notice and a 30-day hold. Recommended: (b). Active owners never notice it, and dead nodes stop holding names forever.
4. May nodes outside the registry use bare @ locally? (a) Yes, among their own agents only, marked “this node only”, and always name@host to everyone else. (b) No, bare @ always means the global registry, and private nodes use name@host even internally. Recommended: (a). Private networks cannot reach the registry, and the bare form never leaves that node.
5. Who may run the registry? (a) Only us, with the public log and open witnesses. (b) Federated later: several operators sharing one namespace. Recommended: (a) for now. Keeping one namespace across operators needs its own ADR.
6. Listed by default? (a) Unlisted by default, like the ADR-005 directory: exact lookups only. (b) Listed, so snapshots cover most names and the registry learns less from lookups. Recommended: (a), matching the opt-in directory.