Claiming a handle

A handle is a human-readable alias onto a key address. /gh/bekirdag is easier to publish in a README than /k/za21mg7q4nfepakf34acbz5ssw.

Handles are optional. Everything works without one.

What it costs you#

A claim is written permanently to a public, append-only transparency log. That log exists so nobody — including the registry operator — can quietly change who a name points to. The same property means entries cannot be edited or deleted.

Each entry publicly and permanently records the handle, the public key it binds, the identity the provider vouched for, and the time of the claim.

Claim it#

pigeonpost handle claim /gh/yourname \
  --registry https://registry.pigeonpost.dev \
  --github-code <code>

The handle name must match your GitHub login. The code is an OAuth authorization code — your browser gets it by authorizing the Pigeonpost registry application, and it expires within minutes, so fetch it immediately before claiming.

Google works the same way with --google-token <id_token>, which binds /google/<subject>.

What the registry checks#

1. 1. Proof of possession — the request is signed by the key being bound, so nobody

can bind a handle to someone else's key

1. 2. Identity — the authorization code is exchanged with the provider server-side;

the code alone is never accepted as a credential

1. 3. Subject match — the account you proved must equal the handle you asked for

Resolve one#

pigeonpost handle resolve /gh/yourname --registry https://registry.pigeonpost.dev

This verifies the inclusion proof locally rather than believing the registry's answer. That check is the reason the registry is not a trusted party in any meaningful sense: a registry that lies about a binding produces a proof that does not verify.

Audit the log#

pigeonpost handle checkpoint --registry https://registry.pigeonpost.dev --key <hex>

A checkpoint is a signed tree head. Pin the key out of band and every later checkpoint proves the log only ever appended — a rewrite is detected, not trusted not to happen. The whole log is downloadable at /v1/log/dump, so a fork keeps every name.

Rotating#

Claim again with a different key and a fresh proof. The registry appends a rotation entry rather than mutating the old one, so the binding history stays publicly auditable. Control of the provider account is what grants the handle, so you cannot lose it by binding the wrong key.