For the complete documentation index, see llms.txt. The full corpus is available at llms-full.txt. This page is also available as Markdown by appending
.mdto the URL.
Your signing key
Your Ed25519 signing key is the identity. Not your login, not your handle, not your domain. It is generated in your browser, it never reaches our servers, and everything public about you is a document that key signed.
Why the key and not the login
Section titled “Why the key and not the login”Login answers one question: which identity row you are allowed to edit. It cannot sign, so it cannot produce a proof, so nobody who steals a session can become you.
That boundary is the point of the product. Merge login authority with proof authority and you get a service where the operator can sign as any user, which means every proof is really a statement about the operator instead of about the person. Keeping them apart is what makes the proof survive us.
The same logic covers the destructive actions. Renaming a handle and deleting an identity never touch the manifest, so a stolen session could once vandalise an identity it could not forge. Both now need a signature from the identity’s key as well as a login.
Why the key and not the domain
Section titled “Why the key and not the domain”A domain is a lease. It expires, it gets seized, it gets bought by somebody else. If a domain were the identity, whoever holds it next would inherit you.
Under this design the next holder inherits a name and nothing else. A file can still be hosted at that address, but it cannot carry your signature, so verification fails and the identity does not move. See Anchoring.
Where the key actually lives
Section titled “Where the key actually lives”| Copy | Where | Protected by |
|---|---|---|
| Working copy | In the page, and in this browser’s IndexedDB for 7 days after you unlock | Non-extractable: it can sign while the app is open, and the raw bytes cannot be read back out |
| Encrypted backup | This browser’s local storage, and the file you downloaded | Your passphrase, via PBKDF2 (210,000 iterations) into AES-GCM |
| Passkey unlock, optional | This device’s authenticator | Face ID, fingerprint, or device unlock |
We hold the public half. That is all we need to check a signature, and all anyone needs to check yours.
Signed in and still unable to sign. The session knows who you are and holds no key, so the profile is readable and the proof is not editable. That is the whole model in one screen.
Back it up properly
Section titled “Back it up properly”Download the encrypted backup and put it somewhere that is not the device you use every day. Losing the device is the exact situation the backup exists for.
Your passphrase is the only thing that opens it. It is not stored anywhere and it cannot be reset, so keep it in your password manager, not in your head.
Passkeys
Section titled “Passkeys”A passkey saves you typing the passphrase every time. It does not replace the passphrase.
- With PRF support (Apple, Windows Hello, Android, recent 1Password and Bitwarden) the authenticator derives the unlock secret itself, and it exists only for the moment of unlock.
- Without PRF, the key is wrapped with a random secret held in this browser and a successful passkey check is required before anything decrypts. That is a convenience on this device, not a hardware-bound secret.
Either way the passphrase backup stays the strong path, so no authenticator can ever lock you out. Exporting a backup or changing a passkey still needs a fresh passphrase unlock, because those operations need the raw key.
Moving to another device
Section titled “Moving to another device”Move the encrypted backup, not the key. The file is already encrypted, so the passphrase stays in your head and the file can travel by any route you like. On the other device, import it and unlock it.
The QR transfer in the mobile app does the same thing: the code carries the encrypted backup, and the passphrase is still needed to open it. A code has a size limit of about 2.9 KB, so use the file if the transfer refuses.
Changing the passphrase
Section titled “Changing the passphrase”Changing it re-wraps the copy you are working with. Your key, your handle, and your published history are all untouched, because none of them depend on the passphrase.
What does not change: backup files you already downloaded, and any QR code or printout made from one. Those stay encrypted under the old passphrase, and they keep working with it forever. Export a fresh backup if you want everything on the new one.
In the Android app
Section titled “In the Android app”Everything about the key is on the Keys tab: which key this phone holds, its key ID and did:key, whether it is unlocked, and the keys this device has pinned for other people.
Getting the key onto the phone
Section titled “Getting the key onto the phone”Two ways in, and only one of them is right for an identity that already exists.
- Scan it. On realhandles.com open the Profile tab, choose Show as QR code, and scan that from the Keys tab. The code carries the encrypted backup, so the passphrase is still needed to open it, and a code tops out around 2.9 KB. Use the file if the transfer refuses.
- Make it here. Only when you are starting from nothing. Claim your handle on the Identity tab generates the key on the device. Doing this when you already have an identity makes a second, unrelated key, which is not what you want.
Sending the key back out is Send key to another device, as a QR code or as realhandles-key.json. What travels is the encrypted backup, never the key itself, and the app says so before it puts anything on screen or into a share sheet.
Biometric unlock is not a passkey
Section titled “Biometric unlock is not a passkey”The website has passkeys. The app has biometric unlock. They do the same job and they are different mechanisms, and neither one travels to the other: setting up a passkey in your browser does nothing for the phone, and turning on biometric unlock does nothing for the browser. Both are per device, and a passkey is per browser on top of that.
What biometric unlock actually does: your backup passphrase is kept on the phone, held by hardware that will not release it without your fingerprint or face. Unlocking then works the same as typing the passphrase, because it is the passphrase.
- Your passphrase never stops working, and it stays the only thing that opens your backup on any other device.
- Adding a new fingerprint or face to the phone erases the stored passphrase. That is the design: somebody who enrols a finger on a phone found unlocked gets nothing. Type the passphrase once and turn it back on.
- Turning it off destroys the stored passphrase copy and touches neither your key nor your backup.
Changing the passphrase, and removing the key
Section titled “Changing the passphrase, and removing the key”Change backup passphrase re-wraps the copy on that phone and nothing else. The backup you downloaded, and any QR code made from it, still open with the old passphrase.
Remove from this device takes the key off the phone. If that was the only copy, the identity goes with it, and nobody can restore it, RealHandles included.