How it works
A key, a proof, a recognition.
wellknown.id replaces accounts and passwords with a key your browser holds for you. Here is what happens, and what everyone involved gets to know.
01 · A key, not an account
Your identity is a key made in your browser.
The first time you use wellknown.id, your browser creates an Ed25519 key pair. The private half is stored as a non-extractable key: the browser will use it to sign, but will never hand it to any script, including ours. It lives in your browser’s storage for wellknown.id, so websites can’t reach it.
The public half becomes your identifier, written as a did:key: a string like
Because the key never leaves the device, losing the device means losing that key. Linking devices and recovery through people you trust are on the roadmap.
02 · A proof for every sign-in
You prove you hold the key, afresh each time.
When a site asks you to sign in, wellknown.id gives your browser a single-use challenge. Your browser signs a message made of that challenge and the site’s identifier, and sends back the signature with your did:key. wellknown.id checks the signature and, only then, hands the site a signed OpenID Connect ID token naming your key.
Because the site’s identifier is part of what you sign, a signature made for one site is useless at another. Because the challenge is single-use and expires after five minutes, a signature can’t be replayed either.
03 · Recognised where you choose
Sites say who they are, on their own domain.
There is no registration with wellknown.id. A site publishes a small file at /.well-known/id listing its public key and the addresses it may send you back to. Its identifier is a fingerprint of that key. On every sign-in, wellknown.id fetches the file from the site’s own domain and checks that the request matches it exactly, so an impostor can’t borrow a real site’s name.
04 · In your browser
The browser’s own dialog where it has one.
Browsers are adding sign-in to their own interface through a standard called FedCM. Where it’s available, as in Chrome, the account chooser is the browser’s, which a page can’t imitate. Elsewhere a small window from wellknown.id does the same job, and if pop-ups are blocked the page itself visits wellknown.id and comes straight back.
05 · What everyone learns
As little as possible.
A site learns your did:key and that you proved you hold it just now. No name, no email, no password. Today your did:key is the same at every site, which means sites could compare notes. A different identifier for every site is on the roadmap.
wellknown.id keeps no user database. After you sign in, your browser holds a signed cookie naming your did:key for up to twelve hours, so the browser’s own sign-in dialog can offer it; that is all.
06 · Built on open standards
Nothing proprietary to adopt.
- OpenID Connect (authorization code flow with PKCE), so sites use libraries they already trust.
- FedCM, the browser’s federated sign-in interface.
- did:key and Ed25519 for identifiers and signatures.
- karu, a readable policy language, for the rules sites set (coming next).