Handles and lookups

A handle is an optional name that lets someone find you without a phone number. This page says exactly what the directory learns when someone looks you up today, and what changes before Pigeon opens to the public.

What a handle is Built

Optional, and one at a time per account.
3 to 24 characters from a-z, 0-9, . and _, starting with a letter.
Look-alikes collide: sam.k, sam_k and samk count as one name, as do paypa1 and paypal (the Unicode UTS 39 “skeleton”).
Names such as admin, support and anything starting with pigeon are reserved.
A handle can be unlisted: lookups get “not found”, but nobody else can take it.

Contacts are bound to keys, not to handles. If you rename, or a name is later reused, nobody's existing chat with you moves to someone else. A lookup warns when a name has had an earlier owner.

Renames and released names Built

A rename can happen once every 7 days.
A released or renamed handle is held for 30 days, during which only its last owner can take it back.
An inactive account gets a notice at 12 months and loses its handle at 13; with the 30-day hold, the name is free after 425 days.

What the directory learns today

The directory server is built; the desktop app's handle screens are in place but not yet connected to it Planned.

When you claim a handle, the directory sees the handle, your account, your network address and the time.
What it stores is a lookup id, a sealed record and a hash of the owner. It stores no handle text; a test checks that.
When someone looks a name up, the directory could learn “this network address looked up @sam.k at 14:02”. It keeps no lookup log, and a test checks that too, but that's a promise, not something it's unable to do.

Mitigations already in place: lookup is exact-match only, never a browsable list; lookups carry no account id and go to a host used for nothing else; every batch is exactly 4 lookups and every answer is a 2,048-byte frame, found or not; and lookups are rate-limited (starting values: 20 an hour, 100 a day, 10 misses an hour).

Every answer is checked against the account's key history on your device. Until the key log ships, a found contact shows as “pending verification”.

Private lookup Planned

The design commits to making lookups private before any public release:

Lookup ids computed with an oblivious pseudorandom function (OPRF), so the directory can't turn an id back into a name.
Lookups sent through an Oblivious HTTP relay (RFC 9458) run by an independent operator, so the directory never sees who is asking.
Private information retrieval or k-anonymous buckets once the directory is big enough for them to help.
Key transparency, so everyone sees the same owner for a handle.

There's no address-book upload and no phone-number matching. Finding friends from your contacts, if it ever comes, would be opt-in private set intersection.

Sources: ADR-0005 (identity and handles, decisions 7 and 9, amendment 5), docs/specs/handle-v1.md (sections 1 to 6), docs/specs/contacts-v1.md.