# RealHandles, full documentation corpus Every page below is sourced from https://docs.realhandles.com, in sidebar order. Pages are separated by `---` and prefixed with their canonical URL. --- # Getting started URL: https://docs.realhandles.com/get-started/getting-started/ Description: Create an identity, generate a signing key, and publish your first signed manifest. At the end of setup you have three things: a handle at `realhandles.com/`, an Ed25519 signing key that only you hold, and a signed file that ties the two together and can be checked by anyone, with no help from us. ## Do it in this order Verify at least one account **before** you pick a handle. The handle gate reads the proofs already attached to your login, so a handle of 8 characters or fewer is only offered once you hold a matching proof. Proofs are stored against the login, not against an identity, which is exactly why you can verify before you have claimed anything. If you would rather not decide yet, onboarding fills in a long default handle for you. Long handles are open to anyone, so nothing is at stake in taking one, and you can move to a short one later once you have proved it. ## Setting up ### Web 1. **Sign in.** This answers one question: which identity row you are allowed to edit. It never signs anything on your behalf. See [Your signing key](https://docs.realhandles.com/key/your-signing-key/). 2. **Verify an account.** GitHub, X, YouTube, Bluesky, TikTok, Threads, Substack, LinkedIn, a domain, a wallet, a Nostr key. See [Verifying an account](https://docs.realhandles.com/accounts/verifying-an-account/). 3. **Pick a handle.** The tier is decided by length. See the table below. 4. **Make your key.** It is generated in your browser. You choose an Unlock Phrase and download an Identity Backup file. 5. **Publish.** Your key signs a manifest listing your accounts, and that signed file becomes your public proof. ### Android **Claim your handle**, on the Identity tab, is the same five steps in the same order. Pick the name, the phone generates the key, you set an Unlock Phrase and save the Identity Backup somewhere that is not the device, and only then is the handle claimed and the public key registered. The private half never leaves the device. If you already have an identity, do not make a second key. Move the one you have: on realhandles.com open the Profile tab, choose Show as QR code, and scan it from the Keys tab in the app. See [Your signing key](https://docs.realhandles.com/key/your-signing-key/). Publishing is **Publish & re-sign** on the Identity tab, and it needs the key on the device and unlocked, which is the same rule the website follows. ## Which handles you can take | Length | Tier | What it takes | | --- | --- | --- | | 9 or more | Open | First come, first served. A matching proof adds a namesake badge. | | 3 to 8 | Protected | One matching verified account on a key platform, or a matching domain you control. | | 1 to 2 | Reserved | A strong match: a matching `.com`, or a matching handle on X, YouTube, TikTok, Instagram, or LinkedIn. | A match means the proof carries the same name as the handle: `@ben` on X for `/ben`, or `ben.com` for `/ben`. Cheap TLDs score below the protected threshold on purpose, so nobody takes a scarce name by spending a dollar on a domain. The scarcity is borrowed from the source platform: `@ben` on X is globally unique and hard to get, which is what makes holding it a real claim to the name. ![The RealHandles dashboard, showing the sign button and the Verify, Claim, Disavow, Profile, Keys and Data tabs](https://docs.realhandles.com/_astro/dashboard.D1euRiyU.png) The dashboard once the key is unlocked. Everything you can change lives under one of those five tabs, and the sign button at the top is what makes any of it public. ## Save exactly two things - **Your Identity Backup, plus the Unlock Phrase.** The file is useless without the Unlock Phrase, and the Unlock Phrase is useless without the file. Keep the file somewhere that is not the device you use every day. - **Your Emergency Kit.** It is a key you designate in advance, published inside your manifest, and it is the only way back in if the signing key is gone. See [Recovery and rotation](https://docs.realhandles.com/key/recovery-and-rotation/). > **Caution:** There is no reset link. A reset link would mean somebody other than you, including us, could sign as you. That is the failure mode this whole design exists to avoid. ## The part that surprises everyone Changing something on RealHandles does not change your proof. An added account, a new anchor, a reordered list: all of it lands on `realhandles.com` immediately, and reaches your signed proof only when you publish again and your key signs the new version. Until you do, anyone verifying you sees the previous version, which is the correct answer to give. [The signed manifest](https://docs.realhandles.com/how-it-works/the-signed-manifest/) explains why it works that way. ## What you end up with ![A published RealHandles profile, showing verified accounts above claimed ones](https://docs.realhandles.com/_astro/public-profile.B3QLF-u0.png) Verified accounts sit above claimed ones, under separate headings, with the badges that say what has been checked: how many accounts are verified, the trust score, whether the handle is a namesake, whether the history is anchored in Bitcoin, and how many signed versions exist. ## Where to go next - [Verifying an account](https://docs.realhandles.com/accounts/verifying-an-account/) for a stronger handle or a higher trust score. - [Claiming an account](https://docs.realhandles.com/accounts/claiming-an-account/) for the platforms that cannot be verified at all. - [Disavowals](https://docs.realhandles.com/accounts/disavowals/) if somebody is already impersonating you. - [Your signing key](https://docs.realhandles.com/key/your-signing-key/) for what you are actually holding. - [Reading the history](https://docs.realhandles.com/how-it-works/reading-the-history/) for how to audit an identity, including somebody else's. - [Exporting your data](https://docs.realhandles.com/data/exporting-your-data/) for every file you can take with you. --- # Verifying an account URL: https://docs.realhandles.com/accounts/verifying-an-account/ Description: Prove you control an account on another platform, and what counts as a real proof. An account is **Verified** when a first party confirmed you control it: the platform itself, a post only the account holder could have made, a DNS record, or a signature from the key behind the account. Everything else is **Claimed**, which is your word and nothing more. The distinction is not decoration. If the two were mixed together the word verified would stop meaning anything, which would make the whole directory worthless. ![The same profile with a Verified accounts section above a Claimed accounts section, each with its own explanation](https://docs.realhandles.com/_astro/public-profile.B3QLF-u0.png) The two lists are drawn apart on purpose, and the claimed one says plainly that RealHandles has not confirmed anything about it. Some rows on a public profile do something other than open a link. A payment or wallet address, and a Signal or WhatsApp username, carry a copy button, because copying is the honest action for an address nobody wants to retype and for a username that has no reliable link. A contact email is the deliberate exception: it reads **Show email** until a visitor asks for it, and only then does it become a `mailto` link with a copy button beside it. Nothing about the address sits in a ready-to-copy control on first paint, so a scraper reading the page does not collect it for free. See [Claiming an account](https://docs.realhandles.com/accounts/claiming-an-account/). ## Verify before you claim a handle Proofs attach to your login, not to an identity. That is deliberate: a handle of 8 characters or fewer needs a matching proof, and you would otherwise have to claim the handle before you could prove you deserved it. Verify first, then claim. ## The methods | Method | What it proves | Status | Can hold a short handle | | --- | --- | --- | --- | | Sign in with the platform (OAuth) | The platform says this account is yours | Verified | Yes, on a key platform | | Post a one-time token (X, TikTok) | Only the account holder could publish it, and the platform tells us the author | Verified | Yes | | Token in your channel description (YouTube) | Same, read back through the platform's own API | Verified | Yes | | Token at the start of a profile's description (LinkedIn, Facebook Pages, Threads) | Only the account holder could write it, read back from what the page itself publishes | Verified | Yes on LinkedIn, no on Facebook and Threads | | Token in your profile bio (Substack) | Same, read back through Substack's public profile, by handle | Verified | No | | Bluesky handle lookup (atproto) | The public atproto record resolves to you | Verified | Yes | | Domain control (file or DNS TXT) | You control the domain | Verified | Yes, and it is the strongest | | Wallet signature (Ethereum, Solana) | The address signed our challenge | Verified | No | | Lightning Address (LUD-16) | The address's `/.well-known/lnurlp/` endpoint answers as LNURL-pay | Verified | No | | Nostr signature | The key behind the account signed our challenge | Verified | No | | Mutual `rel="me"` link | You listed the page and the page links back to this exact profile | Verified | No, see below | | Token somewhere on a page | Somebody edited that page | Claimed | No | | Self-attested | Nothing | Claimed | No | Live OAuth platforms today: GitHub, Discord, Twitch, GitLab, Dribbble. The two platforms people ask about are no longer a flat no, and they are no longer the same answer as each other. LinkedIn reaches Verified with a token at the start of your About section or in your headline, read back from what the page itself publishes. Instagram publishes nothing you wrote in the place a token could go, so the only route Meta left is a sign-in, it reaches Business and Creator accounts only, and it is switched on per deployment. Where it is not offered, an Instagram account lands as [Claimed](https://docs.realhandles.com/accounts/claiming-an-account/). ![Three proofs, three different methods](https://docs.realhandles.com/_astro/verified-list.BZfwjXQ0.png) Three proofs, three different methods. A domain verified by DNS sits in the same list as an OAuth sign-in and a posted token, because all three are first-party checks. ## Why some verified proofs still cannot hold a short handle Three separate questions get asked about every proof, and a proof can pass one and fail the next. 1. **Is it verified?** Did a first party confirm control. 2. **Does it add to the trust score?** Every verified proof does. Claims do not. 3. **Can it reserve a scarce handle?** Only a domain, or a matching handle on a curated key platform, proved by a method other than `rel="me"`. The third bar is the strict one, and the reason is scarcity, not strength of evidence. `@ben` on X is globally unique and hard to get, so holding it really is a claim to the name "ben". A `rel="me"` link on a page you built, or an account on a platform where anyone can register any name, proves you control that thing but proves nothing about the name. A namesake could mint one just as easily as you can, so it never takes a scarce name from somebody who can prove it. Same logic for domains. A matching `.com` scores highest, established TLDs score below it, and anything else scores under the protected threshold. Otherwise `ben.xyz` for a dollar would beat a person who actually holds `@ben`. > **Note:** A proof that cannot hold a short handle is still worth having. It shows Verified on your profile and it counts toward your trust score, which is what makes the rest of your identity believable. ## Where a verification starts Both clients ask the same first question now, in the same order, from the same list of five types: a social media profile, a link-in-bio page, a domain, a crypto wallet, or a Nostr key. You are never asked to pick a method. Nobody holds a method, people hold a thing, and which proof that thing can reach is our problem rather than yours. ### Web Verification lives on the **Verify** tab, and it starts with a paste box: drop in a link, a domain, an npub or a wallet address and the server answers with everything that thing supports, strongest first. Under it are the same five types as tiles, which double as the answer to "what can this product even do". Claiming is offered after them rather than as a sixth tile, because a claim is not a verification and putting it in the row would set it beside five proofs at the same weight. The social tile holds the one-click platform sign-ins, and under them the post-a-token form. That dropdown only lists platforms that can reach Verified, which is why it is shorter than the list of platforms you can claim. X and TikTok take the token in a post and want the post URL back. YouTube, Bluesky, and Substack take the token in the channel description or bio and are checked by handle, so there is no URL to paste. LinkedIn, Facebook, and Threads take it at the start of the About section, Page description, or bio, and want the profile URL back, because each of them cuts the description it publishes short. The **Verify** button on a Claimed account opens the same form with the platform and handle filled in, and on Threads and Facebook the profile URL too. ### Android Verifying lives under **Identity > Verify**. ![The Verify section, listing verified profiles with the reorder toggle](https://docs.realhandles.com/_astro/mobile-verify-section.CBZDTUm-.png) Actions at the top, then every verified account. Each row reorders with arrows or a typed position, and the order you save is the order the manifest publishes. **Add an online profile** is the way in for anything with a link. Paste it and the server answers with everything that link supports, strongest first. Paste `github.com/yourname` and you are offered the GitHub sign-in. Paste a page nothing can confirm and you are offered a [claim](https://docs.realhandles.com/accounts/claiming-an-account/) instead. Before anything happens the screen says which one you are about to get, and whether that proof is strong enough to reserve a short handle. ![The Add an online profile screen, asking for a link](https://docs.realhandles.com/_astro/mobile-add-account.Db2hqrDV.png) One way in, whatever the platform. Paste a profile link and the app works out which proofs are possible for that service, then routes to the strongest one. Under it is the same list of five types the website shows, in the same order and the same words. The first two go back to the paste screen, because a profile and a page both have a link. The other three are the cases a link cannot reach: **Domain**, **Crypto wallet**, and **Nostr key**. The wallet row asks **Which wallet?** before it does anything, because Ethereum, Solana and a Lightning Address are three different checks behind one word. Posting a token works the way it does on the website: the app issues the token, you publish it, then paste the link to the post and run the check. ## Signing in with the platform (OAuth) The strongest and fastest proof, because the platform itself answers. It asks before it tells us anything, and the proof is verified the moment you land back and not yet public. That second half is the part people miss. ### Web ![The one-click OAuth row: GitHub, Discord, Twitch, Dribbble and GitLab](https://docs.realhandles.com/_astro/oauth-buttons.CYSoM6lX.png) Pick one and it sends you there and back. ![The Discord consent screen, listing what RealHandles can and cannot see](https://docs.realhandles.com/_astro/discord-consent.-_xrq_WX.png) The platform asks before it tells us anything. RealHandles requests your username and which servers you are in, and the screen states outright that it cannot read or send your messages. ![The verification success message, saying the proof is saved but not yet published](https://docs.realhandles.com/_astro/oauth-success.BhVg0ZaC.png) Verified the moment you land back, and not yet public. One thing to expect: if the desktop app is installed, the platform may try to hand the login to it and the browser tab will look stuck. Use the link to continue in the browser, or quit the app. ### Android Signing in with the platform works in the app. The app asks realhandles.com for a start URL, opens it in the phone's browser, and the finished handshake comes back to the app on a deep link. Two things about that return are worth knowing, because they explain what you see: - Nothing the return link says is displayed. The wording names the platform **the app** started, not whatever the link carried. - What happened is read back from realhandles.com afterwards, because the server is the only party that knows whether a proof was actually created. If the copy of realhandles.com being talked to cannot hand the result back to the app, the app refuses to start rather than strand you in a browser tab, and says to use the website for that one. If you administer servers or organizations on that platform, you are offered them next, in both clients: ![The Discord server picker, asking for a permanent invite link](https://docs.realhandles.com/_astro/discord-server-picker.CEKbvU8y.png) Being an admin proves control regardless of who signed in, so these can be verified as first-party accounts too. Discord has no public server URL, so a permanent invite link stands in for one. ## Domain proofs Publish a one-time token at `/.well-known/realhandles-challenge.txt`, or add it as a DNS TXT record. Either one on its own is enough. The token is yours and does not expire, so setting it up on a computer later is fine. A check that fails right after you set it up is normal. DNS changes and caches take minutes to hours to reach us. Nothing is lost, so wait and check again. ### Web ![The domain verification step, showing the challenge token to publish](https://docs.realhandles.com/_astro/domain-challenge._DiqYdWP.png) The token can go in a DNS TXT record on the domain, or in a file at `/.well-known/realhandles-challenge.txt`. It stays valid while DNS propagates, so there is no race to win. ### Android **Domain** is one of the five type rows, because a domain has no profile link to paste. Name the domain, take the token, publish it, then press **Check now**. Nothing is waiting on the phone, so leaving the screen and finishing the DNS record on a computer later works fine. A verified domain is separate from an [anchor](https://docs.realhandles.com/how-it-works/anchoring/), which is where a copy of your signed identity is hosted. Proving `ben.com` and anchoring at `ben.com` are two different actions. ## Wallets, Lightning and Nostr keys A wallet and a Nostr key are keypairs already, so a signature over our challenge settles it outright. No platform is asked and no page is read. - The challenge is tied to your login and your key, so a signature made for it cannot be replayed somewhere else. - The server recovers which address or public key signed. That address, not one you typed, is what gets recorded. - A signature is public. Producing one proves the wallet without opening it, and no transaction is made. Ethereum and Solana are both verified this way, and they are two checks rather than one. Ethereum recovers the signer from the signature itself, so the address is an output. Solana cannot, so you name the address and the signature is checked against it. That is why they are offered as two actions and not one wallet button. If the address has a primary ENS name, or the Nostr key has a confirmed NIP-05, your profile publishes the readable name instead of the raw string. The key underneath is still what the identity rests on. ### A Lightning Address is the exception A Lightning Address is the `you@example.com` shape wallets already use (LUD-16), and it is the one Verified thing here with no signature and no private key involved on your side. We resolve it the way a wallet would, to `https://example.com/.well-known/lnurlp/you`, and Verified means that endpoint answered as an LNURL-pay request. Read what that does and does not say. It is a first-party check, because the answer comes from the host that runs your address rather than from you. It is a weaker statement than a signature, because it proves the address resolves and can be paid, not that a key proved anything. So it shows Verified, it counts toward your trust score, and it never reserves a short handle. It is counted as a wallet on your profile rather than as an account, which is why a count can read "1 verified account and 1 wallet". > **Note:** A contact email looks identical to a Lightning Address and is a completely different thing. Email is [Claimed](https://docs.realhandles.com/accounts/claiming-an-account/) only, nothing checks it, and it is hidden behind a click on your public page. #### Web The **Crypto wallet** tile holds all three, one row each. **Verify Ethereum** signs the challenge in the browser wallet. **Verify Solana** signs it in Phantom or another Solana wallet. **Verify Lightning** takes the address and resolves it, with no wallet app involved at all. Bitcoin, Polygon, Base and anything else can be listed as **Claimed** addresses instead, under Claim, because nothing there is being checked. One Ethereum verify proves the key and not the label: see [Claiming an account](https://docs.realhandles.com/accounts/claiming-an-account/) for why Polygon and Base are labels you list rather than chains we check. #### Android Two of the five type rows, for the same reason a domain gets one: a keypair has no profile link. - **Nostr key.** Signing is handed to a NIP-55 signer app such as Amber. The secret key stays inside the signer and is never seen by RealHandles or by the app. - **Crypto wallet.** It asks **Which wallet?** first, then branches three ways. **Solana hands off to Phantom** when Phantom is installed. Press **Open Phantom**, approve the connection and then the signature, and it returns on its own. ![The Solana screen on Android, offering Open Phantom with paste-back underneath](https://docs.realhandles.com/_astro/mobile-verify-solana.DGbnJQUi.png) Nothing is copied and nothing is typed, which matters more here than convenience: a Solana signature cannot be traced back to the account that made it, so the address has to be supplied alongside it, and a person carrying an address across by hand can pick the wrong account without noticing. Phantom reports the address itself, so that mistake stops being possible. The approval screen shows no RealHandles logo, because Phantom reads app branding from a web address and the return has to use a private one to come back to the app at all. **Any other Solana wallet** uses the same paste-back the website falls back to: the app shows the exact message, you sign it wherever you like, and you paste the signature and the address. The screen names the address you are about to claim, in full, before it submits. **Ethereum** shows you the exact message, you sign it in the wallet app and paste the signature back. No transaction and no gas. **A Lightning Address** needs no wallet app at all: the app resolves the address itself. ![The Lightning screen on Android: one field and no wallet app](https://docs.realhandles.com/_astro/mobile-verify-lightning.Dp7eI_IF.png) ## After you verify, publish A new proof lands on `realhandles.com` immediately and reaches your signed manifest only when you publish and re-sign. Until then, anyone verifying you independently sees the previous version. See [The signed manifest](https://docs.realhandles.com/how-it-works/the-signed-manifest/). ## Hiding an account Hiding keeps the account and everything it has already proved. It stays attached to your identity and it still counts toward the handles you are allowed to hold. What changes is that the next version you publish leaves it out of the public manifest. So hiding on its own changes nothing for anyone checking you: it comes off your public proof when you publish, and showing it again later is a publish of its own, not an undo. ### Web The eye on each account row toggles both ways. A hidden row stays on the list, dimmed, and the eye turns it back on. ### Android The eye on each row toggles both ways, in the ordinary list and while you are arranging it. A hidden row stays on the list, badged **HIDDEN**, which is the point: the one screen that can put an account back is the screen it was missing from for as long as hiding dropped it. ## Hiding your whole profile Hiding one account and hiding everything are different actions, and the second one is not a bigger version of the first. Whole-profile visibility is a field in your signed manifest, applied by re-signing, so your key authorizes it and a login alone never can, exactly as with renaming and deleting. Hidden means removed from the directory, search and your public page. Your signed history stays verifiable, because it always was. That is deliberate rather than an oversight: your chain and its timestamps keep serving, because being able to withhold verification data on request would make us the gatekeeper of who can be verified, which is the one role this product refuses. The commitments are in Bitcoin either way, so erasure is not a promise anyone could keep. Your handle stays yours. Anyone opening `realhandles.com/yourname` is told the profile is hidden, not that the name is free. ### Web **Profile visibility** is at the bottom of the **Profile** tab, with a badge saying which state you are in. **Hide my profile** and **Publish my profile again** both need your key unlocked, because both are a new signature. ### Android The visibility footer at the bottom of **Identity > Profile** says **Published** or **Hidden**, with **HIDE** or **PUBLISH** beside it. The app both sets and preserves the state, so hiding from the phone is a real publish rather than a request to the website. --- # Claiming an account URL: https://docs.realhandles.com/accounts/claiming-an-account/ Description: Assert an account you cannot verify, and what a claim is worth to someone reading it. A claim is your signed word that an account is yours. Nothing checks it. It shows as **Claimed** on your profile, kept in its own section so a reader can tell at a glance what was checked and what was not. ## What a claim does and does not do | | Claim | Verified account | | --- | --- | --- | | Shown on your profile | Yes, under Claimed | Yes, under Verified | | Goes into your signed manifest | Yes, once you publish | Yes, once you publish | | Counts toward your trust score | No | Yes | | Can hold a short handle | Never | On a key platform or a domain | Scarce handles are backed by something you actually proved, so no number of claims takes one from somebody who can prove it. ## When a claim is the right answer Use one when the platform gives no way to prove anything: no OAuth app, no readable page, no post the platform will confirm the author of. That is most of the long tail. A claim is not worthless in that situation, but its value is borrowed. It is believable in proportion to everything around it. An identity with a verified domain and four verified platform accounts saying "this Goodreads profile is also me" is credible. The same sentence on an identity with nothing verified is just a sentence. ## Adding one ### Web Claiming has a tab of its own, **Claim**, which holds your claimed list and three separate forms under it: **Claim a profile (self-attested)**, **Contact email**, and **Crypto wallets**. They sit apart from verification on purpose: the stronger routes are offered first on the **Verify** tab, and this is what is left when none of them apply. Fill in the platform, the handle, and a link to the account if you have one, then press **Add claimed profile**. Pasting an Orynth profile link fills in the platform and the handle for you. The new row joins the same list as your verified accounts, in its own Claimed group. Reordering is a drag by the grip on the left. On a touch screen, press the reorder toggle above the list to swap the grips for up and down buttons. ![The Claim tab on realhandles.com, listing claimed profiles and offering to add one](https://docs.realhandles.com/_astro/claim-desktop.75A6Yq1t.png) ### Android Claims live under **Identity > Claim**, kept in a separate section from Verify for the same reason the public profile keeps the two lists apart. ![The Claim section, listing self-attested accounts](https://docs.realhandles.com/_astro/mobile-claim-section.Bcv5En9x.png) Claimed accounts are kept apart from verified ones for the same reason the website separates them: they are your word, they add nothing to the trust score, and they never satisfy the handle reservation gate. Only a first-party verified proof moves that number. Adding one starts where a verification starts: **Add an account**, paste the link. If nothing can confirm that link the app says so and offers to record it as Claimed. If something can confirm it, the stronger route is offered first, which is the right default. Either way you see which one you are getting before you commit to it. You can also enter a claim by hand, with the platform, the handle, and an optional profile link. Each row has arrows to step it up or down, and a third control that opens To top, To bottom, and a box to type a position, so moving a row from eighty to three is one action rather than seventy-seven taps. Moves are held until you save them, and the order you set here is the order the manifest publishes. ## Contact email A contact email is a public mailbox on your profile, claimed the same way anything else is. Two things about it are worth saying plainly. **It is not your login.** The address you sign in with is never published, and nothing links the two. Publishing a contact email is a separate decision about a separate address, which is the point of having the field at all. **It is Claimed and only Claimed.** Nothing checks it. It adds nothing to your trust score and it never reserves a short handle. A [Lightning Address](https://docs.realhandles.com/accounts/verifying-an-account/) has exactly the same `you@example.com` shape and is a different thing entirely, so read the platform on the row rather than the address. On your public page the address is behind a click. The row reads **Show email** until a visitor asks for it, and only then does it become a `mailto` link with a copy button beside it. That keeps it off the screen when you hold your phone up in a room. It does not hide it from a scraper: the address is in the page source and in your signed manifest, which are both public. ### Web **Contact email** is the second form on the **Claim** tab. Type the address and press **Add as claimed**. ### Android The app has no separate form for it. Enter it as an ordinary claim, with `email` as the platform and the address as the handle. The public page treats it the same way the website does, click-to-reveal included, because that rule lives with the profile row rather than with the form that created it. ![Contact email and the wallet picker on Android](https://docs.realhandles.com/_astro/mobile-claim-extras.BxafnA1B.png) ## Crypto wallets Ethereum, Solana and a Lightning Address can be [verified](https://docs.realhandles.com/accounts/verifying-an-account/). Everything else in this space is listed rather than checked, and a claimed wallet is worth what any other claim is worth: it shows on your profile, it adds nothing to your trust score, and it never holds a short handle. The chains offered are Ethereum, Solana, Bitcoin, Lightning, Polygon, Base and Other. > **Caution:** Polygon and Base are display labels, not checks. The same key may well work on other EVM chains on-chain, and we have no way to know which ones you actually use, so we show what you list and nothing more. Verifying an Ethereum address does not make a Base row appear, and adding a Base row proves nothing about Base. A wallet is counted as a wallet on your profile rather than as an account, so a count reads "2 verified accounts and 1 wallet" instead of calling an address an account. ### Web **Crypto wallets** is the third form on the **Claim** tab: pick the chain, paste the address or `name.eth`, then **Add as claimed**. ### Android Enter it as an ordinary claim, with the chain as the platform and the address as the handle. ## Signal and WhatsApp Both can be claimed by username, and both deliberately have no link on your public profile. The row offers copy instead. That is not a missing feature. A working `signal.me` or `wa.me` link cannot be derived reliably from a username alone, and a link that resolves to the wrong person, or to nothing, is worse than no link on a page whose entire job is saying which account is yours. Copying the username is the honest action, so that is the action the row offers. The same copy button appears on every payment and wallet row, for a different reason: an address nobody wants to retype is exactly the thing a visitor came to take with them. ## Upgrading a claim later Nothing is stuck. If a platform becomes verifiable, [verify](https://docs.realhandles.com/accounts/verifying-an-account/) the same account and the row moves from Claimed to Verified. What was already published stays published, because the history is append-only, and the next version you sign carries the new status. ## It is still a signed statement A claim is not a note in our database. Once you publish, it is inside a document signed by your key, which means you are on the record as having said it. That is the honest trade: nothing checked it, but you cannot later pretend you did not say it. ## Publish for it to count Adding a claim changes `realhandles.com` straight away and changes your signed proof only when you publish. Until then no key has vouched for it, so a reader has only our word for it. See [The signed manifest](https://docs.realhandles.com/how-it-works/the-signed-manifest/). --- # Disavowals URL: https://docs.realhandles.com/accounts/disavowals/ Description: Say publicly that an account is not you, in a way anyone can check. A disavowal is the inverse of a claim: a signed statement that an account is **not** you, or that you are not on a platform at all. It sits in the same signed manifest as everything else, so it carries the same weight as the accounts you claim. ## Two kinds **This account or address is not me.** Names one specific thing: a profile by handle or link, a wallet address, or an email address. Use it for a known impersonator, or for a same-name person who is not doing anything wrong but keeps getting mistaken for you. A Solana or Phantom username held by a stranger is exactly the case people arrive with, and it belongs here as much as a social account does. **I am not on this platform.** Declares that you have no account there at all, which makes every account on that platform claiming to be you fake by definition. Stronger than listing impersonators one at a time, and it does not go stale as new ones appear. ## What you can say A disavowal needs a platform, and the platform can be `solana`, `ethereum`, `lightning`, `email`, `signal` or `whatsapp` as readily as it can be `x` or `instagram`. An account disavowal also needs a handle or an address, because a statement that does not say which one is not a statement about anything. A short note is optional, and it is the part that does the work for a reader: "known impersonator", or "same name, different person". Order matters. The list is shown in the order you set, so put the one people keep falling for at the top. ## Writing one Both clients ask the same first question, because the two kinds are different statements rather than two settings on one statement. ### Web The **Disavow** tab holds a form above your list. The first field is the choice between **A specific account or address is not me** and **I am never on a platform**, and picking the platform option puts the handle and link fields away, because they no longer apply. Then the platform, the **Disavowed handle or address**, an optional link, and the optional note. **Add to disavow list** puts it on the list below. ![The disavow panel, for stating publicly that an account is not you](https://docs.realhandles.com/_astro/disavow.Ce6OiQWQ.png) A disavowal is signed into the manifest exactly like a verified account, so it carries the same weight as the rest of the identity rather than being a note on the side. Each row on the list carries up and down arrows, a pencil, and a remove control. The pencil refills the form above with that entry, including the choice of kind, so a statement written about one account can be turned into a statement about the whole platform without deleting anything. ### Android Disavowals get a section of their own: **Identity > Disavow**. ![The Disavow section, for stating publicly that an account is not you](https://docs.realhandles.com/_astro/mobile-disavow.mNFFUlPW.png) A disavowal is signed into the manifest exactly like a verified account, so it carries the same weight rather than being a note on the side. Adding one asks the same first question the website does, as two choices at the top of the form: **One account or address**, which names one account, wallet address or email that is not you, or **A whole platform**, which says you have no account there at all. Everything after that is the platform, the **Handle or address**, an optional link, and the note that does the real work for a reader. Published statements reorder with the same arrows and jump-to-position control as accounts, and the order you set is the order the manifest publishes, so the impersonator people keep falling for goes at the top. Correcting one that is already published is on the row itself, under Options. What a statement covers cannot be edited there: a disavowal of one account never becomes a disavowal of the whole platform by an edit, because those are different statements. Remove the old one and add the one you meant. ## Publish for it to count The statement lands on `realhandles.com` immediately and enters your signed proof when you publish and re-sign. Until then, anyone verifying you independently sees the previous version with no disavowal in it. See [The signed manifest](https://docs.realhandles.com/how-it-works/the-signed-manifest/). Editing or removing one changes what you publish from now on. Versions you already signed keep what they said, because the history is append-only, and that is what makes editing an old version impossible for us as well as for you. ## Reporting somebody else's impersonator Disavowals are what **you** say about accounts elsewhere. Reporting is what anybody says about a RealHandles profile, and it needs no account at all, because the person being impersonated usually does not have one. A human reads reports. This is the one thing in the product you do about someone else, so it is deliberately kept off the signed manifest. Your key says what is yours and what is not yours. It does not adjudicate other people. ### Web Every public profile carries a **Report it** link at the bottom, which opens the report form with that username already filled in. It asks for a reason, the details, and an email to follow up on. No sign-in, and no identity of your own. ### Android Reporting is deliberately somewhere else in the app, under **Identity > Data**, and needs no identity of your own. --- # Build a /verify page URL: https://docs.realhandles.com/accounts/build-a-verify-page/ Description: List the accounts that are really you on your own site, read from your RealHandles profile. A /verify page is a page on your own site that lists every account that is really you, so people can tell you from an impersonator. It is a [slash page](https://slashpages.net/#verify), like `/now` and `/uses`. Your RealHandles profile already holds that list, signed by your key, so your page can read it from there instead of keeping a second copy. ## What the page needs - **Every account as a link with `rel="me"`.** That attribute is how Mastodon, RealHandles, and other verifiers recognize a link as yours. Put the links in the page's HTML: those tools read the HTML and do not run JavaScript, so a list that a script adds after the page loads is invisible to them. - **A link to your RealHandles profile**, also with `rel="me"`, so anyone can check the list without trusting your site. That is the whole convention. Everything below is optional. ## Read your profile Your profile is public at this address, with no key or sign-in, from a browser or a build: ``` https://realhandles.com/api/identity/ ``` The fields a /verify page uses: | Field | What it holds | | --- | --- | | `accounts.verified` | Accounts RealHandles has verified. | | `accounts.claimed` | Accounts you listed that are not verified. | | `disavowed` | Accounts, and whole platforms, you have signed as not you. | | `profile` | The address of your RealHandles profile. | Each account has `platform`, `handle`, `url`, `label`, and `kind`. `label` is the platform's display name, such as `Product Hunt`, and `kind` is `account`, `domain`, or `wallet`. Each disavowal has `kind` (`account` or `platform`), `platform`, and `label`, plus `handle` and `url` when it names one account. > **Caution:** Decide whether an account is verified by which list it is in, never by its `method` field. The account's owner wrote `method`, and a signature proves who wrote it, not that it is true. ## Build the list into the page Fetch your profile when your site builds, and write the links into the HTML. In [Astro](https://astro.build), for example: ```astro --- const res = await fetch('https://realhandles.com/api/identity/yourhandle'); if (!res.ok) throw new Error(`RealHandles returned ${res.status}`); const { accounts, profile } = await res.json(); const all = [...accounts.verified, ...accounts.claimed].filter((a) => a.kind !== 'wallet' && a.url); --- ``` Any static site generator works the same way. Fail the build when the request fails, as above, rather than publish an empty list: your host keeps serving the last good deploy. An account you add on RealHandles appears on your page the next time the site builds. ## Mark what is verified To mark the accounts RealHandles has verified, ask again in the browser on every visit, and mark only links whose address is in `accounts.verified`. A mark written in at build time can outlive the verification it shows. If the request fails, draw no marks. ```js const key = (u) => { const x = new URL(u, location.href); return (x.hostname.replace(/^www\./, '') + x.pathname.replace(/\/+$/, '')).toLowerCase(); }; const res = await fetch('https://realhandles.com/api/identity/yourhandle').catch(() => null); const verified = res?.ok ? (await res.json()).accounts.verified : []; const urls = new Set(verified.map((a) => key(a.url))); for (const link of document.querySelectorAll('a[rel="me"]')) { if (urls.has(key(link.href))) link.classList.add('verified'); } ``` Responses are cached for up to five minutes, so checking on every visit is fine on a busy page. ## Wallets and accounts that are not you - **Wallets** are the accounts with `kind` set to `wallet`. Show the address from `handle` as text rather than as a `rel="me"` link, because a block explorer page is not you. - **Disavowals** are in `disavowed`. You can link to the account so people can recognize it, but never with `rel="me"`, which would claim the opposite. ## An example [davidvkimball.com/verify](https://davidvkimball.com/verify) reads its wallets and disavowals from RealHandles when the site builds, and marks verified accounts in the browser on every visit. ## Starting from a page you already have If you already have a /verify page, import it: paste its address into **Import your profiles**, on the **Claim** tab of the dashboard or in the app. RealHandles reads the `rel="me"` links and adds each account as Claimed, and you verify them from there. See [Verifying an account](https://docs.realhandles.com/accounts/verifying-an-account/). Once the accounts are on your profile, you can build the page from it as above. --- # Your signing key URL: https://docs.realhandles.com/key/your-signing-key/ Description: The Ed25519 key that is the root of trust, where it lives, and how to back it up. Your Ed25519 signing key is the identity. Not your login, not your handle, not your domain. It is generated on your own device, it never reaches our servers, and everything public about you is a document that key signed. ## 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 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](https://docs.realhandles.com/how-it-works/anchoring/). ## Where the key actually lives We hold the public half. That is all we need to check a signature, and all anyone needs to check yours. Everything else is on the device in front of you. ### Web | 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 | | Identity Backup | This browser's local storage, and the file you downloaded | Your Unlock Phrase, via PBKDF2 (210,000 iterations) into AES-GCM | | Passkey unlock, optional | This device's authenticator | Face ID, fingerprint, or device unlock | ![The Keys tab on realhandles.com: where the key lives, the Identity Backup, the Emergency Kit, a passkey, rotation, and removing the key from this browser](https://docs.realhandles.com/_astro/key-locked.DPlhnnML.png) 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. ### Android 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. ![The Keys screen on Android, with the signing key locked and the Identity Backup on the device](https://docs.realhandles.com/_astro/mobile-keys.B0VEKadB.png) Biometric unlock is a convenience over the Unlock Phrase, never a replacement. Enrolling a new fingerprint invalidates the wrapped key on purpose. ## Back it up properly Download the Identity Backup and put it somewhere that is not the device you use every day. Losing the device is the exact situation the Identity Backup exists for. Your Unlock Phrase 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. > **Caution:** If you lose both the Identity Backup and the Unlock Phrase, and you have no Emergency Kit, you are locked out. This works like self-custody, and it works that way on purpose: an identity nobody else can sign for is also an identity nobody else can steal. Set up a [Emergency Kit](https://docs.realhandles.com/key/recovery-and-rotation/) so that "both are gone" is not the end of the story. ## Unlocking without typing the Unlock Phrase Each client has a shortcut, and they are different mechanisms. 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. Whichever you use, the Unlock Phrase stays the strong path, so no authenticator can ever lock you out. ### Web **Add a passkey** is on the **Profile** tab, and it needs your key unlocked first. A passkey saves you typing the Unlock Phrase every time. It does not replace the Unlock Phrase. - **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. Even a passkey that syncs across your devices only unlocks the key material stored in this browser, because that is the only place it exists. Exporting an Identity Backup or changing a passkey still needs a fresh Unlock Phrase unlock, because those operations need the raw key. ### Android The app has biometric unlock instead. Your Unlock Phrase is kept on the device, held by hardware that will not release it without your fingerprint or face. Unlocking then works the same as typing the Unlock Phrase, because it *is* the Unlock Phrase. - Your Unlock Phrase never stops working, and it stays the only thing that opens your Identity Backup on any other device. - Adding a new fingerprint or face to the phone erases the stored Unlock Phrase. That is the design: somebody who enrols a finger on a phone found unlocked gets nothing. Type the Unlock Phrase once and turn it back on. - Turning it off destroys the stored Unlock Phrase copy and touches neither your key nor your Identity Backup. ## Moving to another device Move the Identity Backup, not the key. The file is already encrypted, so the Unlock Phrase stays in your head and the file can travel by any route you like. On the other device, import it and unlock it. A QR code carries the same Identity Backup, and it tops out at about 2.9 KB, so use the file if a transfer refuses. ### Web **Download Identity Backup** and **Show as QR code** are both on the **Profile** tab, under **Advanced: Identity Backup, Unlock Phrase, and key rotation**. The QR code is what the Android app scans, so a key reaches a phone without a file crossing between them. Show it to your own camera only. It is useless without your Unlock Phrase, and it is one guessed Unlock Phrase away from being your key, so it does not belong on a call or a stream. ### Android 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 Identity Backup, so the Unlock Phrase is still needed to open it. - **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 Identity Backup, never the key itself, and the app says so before it puts anything on screen or into a share sheet. ![The key transfer screen, offering the Identity Backup as a QR code or a file](https://docs.realhandles.com/_astro/mobile-key-transfer.DqxL3gZm.png) The QR carries the Unlock Phrase-encrypted envelope, never the raw key. Anyone who photographs it and knows the Unlock Phrase owns the identity. ## Changing the Unlock Phrase 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 Unlock Phrase. What does not change: Identity Backups you already downloaded, and any QR code or printout made from one. Those stay encrypted under the old Unlock Phrase, and they keep working with it forever. Export a fresh Identity Backup if you want everything on the new one. If the goal is to stop an old Identity Backup working at all, that is a [rotation](https://docs.realhandles.com/key/recovery-and-rotation/), not an Unlock Phrase change. ### Web **Change Unlock Phrase** sits next to the Identity Backup buttons on the **Profile** tab, under the same Advanced section, and it re-encrypts the copy this browser holds. ### Android **Change Unlock Phrase** re-wraps the copy on that phone and nothing else. **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. --- # Recovery and rotation URL: https://docs.realhandles.com/key/recovery-and-rotation/ Description: Replace a key you still hold, and take back an identity whose key is gone. Two different problems, two different answers. - **Rotation** is for a key you still have and no longer want. The old key signs the handoff. - **Recovery** is for a key that is gone. Keys you named in advance sign the handoff instead. Both change the signing key. Neither one involves a login, a support ticket, or us. There is no third path, and adding one would mean somebody other than you could sign as you. > **If you are reading the file rather than the screen:** The **Emergency Kit** is called `recovery` in a signed manifest, and the key inside it is labeled `recovery key`. Those names are part of the wire format that every verifier reads, so they do not change when the wording on screen does. Renaming them would invalidate every proof already published. ## Where you do this ### Web Both live on the **Keys** tab of the dashboard. **Rotate signing key** is disabled until your current key is unlocked, because only that key can authorize a new one. ![The Rotate your signing key panel on the Keys tab](https://docs.realhandles.com/_astro/rotate-key.DSGJydH4.png) The Emergency Kit has its own panel on the same tab, showing whether one is set and offering to replace it. ![The Emergency Kit panel, showing a kit is set and offering to replace it](https://docs.realhandles.com/_astro/emergency-kit.DDZCmKqH.png) The lost-key path is on the unlock screen rather than in the dashboard, for the obvious reason that you cannot get into the dashboard. Upload the Emergency Kit file, or type the Emergency Kit. If the identity never published a policy, that screen says so plainly instead of offering a route that does not exist. ### Android Both are in the app, on the **Keys** tab, and both have been run end to end against a published chain. The phone is a full client here, not a viewer. ![The Keys tab on Android, with Rotate signing key, Set up an Emergency Kit and Use an Emergency Kit](https://docs.realhandles.com/_astro/mobile-keys-recovery.C6nOzmAM.png) **Rotate signing key** generates the new key on the device and has the current key sign the handoff there, which is the honest place for it: the key is on this phone, in an encrypted envelope this phone holds, so the signature that authorizes its replacement can only be produced here. **Set up an Emergency Kit** names a key in advance. **Use an Emergency Kit** is the other direction, for when the signing key is gone. The app also shows the result. The signed history under **Identity > Data** names a rotation or a recovery on the version that carried it, and says whether the handoff was authorized. See [Reading the history](https://docs.realhandles.com/how-it-works/reading-the-history/). ## Rotation You generate a new key, and your **old** key signs a statement authorizing exactly that new key at exactly that point in your history. The new manifest carries both: it is signed by the new key, and it contains the old key's authorization. That is what makes it a handoff rather than a stranger appearing. Anyone who had pinned the old key sees an authorization the old key produced, and follows it forward. Somebody who has only stolen the new key cannot produce that authorization. The server checks four things before it accepts the change: 1. The manifest verifies under the key that signed it. 2. Its position in your history matches the one we actually hold. The authorization is bound to a position, so it cannot be saved up and replayed later. 3. The named previous key is the one currently registered to you. 4. The old key's signature covers exactly this key change, byte for byte. ### Two things break on purpose when you rotate **Your anchor drops back to unchecked.** The file hosted on your domain was signed by the retired key, so it is no longer proof of anything. Re-host and re-verify. Leaving a green badge on a file that no longer verifies would be a lie. See [Anchoring](https://docs.realhandles.com/how-it-works/anchoring/). **Your old Identity Backup stops unlocking this identity.** It still opens, and it still contains the old key, which is now the wrong key. Take a fresh Identity Backup, which the flow requires before it lets you finish. ## Recovery An Emergency Kit is a key you designate **in advance**, inside your published manifest, and it is the only thing that can take an identity back when the signing key is gone. Signup asks you to save exactly one thing for this: your Emergency Kit. Set up later and it is still the same mechanism, just later. The policy has a threshold, which is why it is a policy and not a single field. One printed Emergency Kit is a threshold of one, and that is what this product creates today. > **Caution:** A designated Emergency Kit is as powerful as your signing key. Whoever holds enough of them can take the identity. The threshold is the only dial that makes that harder, so treat a printed Emergency Kit exactly like the key itself. ### The rule that makes recovery safe The policy that counts is the one published **before** the recovery, never the one the recovering entry declares about itself. Otherwise an attacker could simply arrive naming a fresh set of Emergency Kits and approve the takeover with them. Every time you re-sign, the current policy is carried forward automatically, so an ordinary publish never quietly strips an Emergency Kit you set up months ago. If you never published a policy, there is nothing to recover with, and a lost key is final. That is the honest consequence of having no reset link. ## What this actually guarantees **Guaranteed.** Anyone reading your full history can tell an authorized key change from an unauthorized one. Both a rotation and a recovery leave a signed record inside the chain, and neither can be forged by somebody holding only the new key. We cannot forge one either, because we never hold a key that can sign the statement. **Not guaranteed.** A verifier who has only ever seen your latest manifest pins whatever key signed it, and cannot tell whether that key arrived legitimately. Catching an unauthorized swap requires the history, which is why every version is kept and served. See [Reading the history](https://docs.realhandles.com/how-it-works/reading-the-history/). Also not guaranteed: that an Emergency Kit stays in the right hands. The protocol enforces that the holder was designated by you. It cannot know who is holding it now. --- # The signed manifest URL: https://docs.realhandles.com/how-it-works/the-signed-manifest/ Description: The JWS document that holds the identity, and the rules a server applies before storing it. The manifest is your identity. It is a compact JWS, signed by your key, whose payload lists your accounts, your disavowals, your anchor, your position in your own history, and the recovery policy in force. Our database is a cache of it. Everything we serve could be rebuilt from the signed file, and nothing we hold outranks it. ## What the file looks like ```jsonc { "$schema": "https://realhandles.com/schema/realhandles-v1.json", "jws": "eyJ...", // authoritative: compact JWS (EdDSA), payload = the manifest "manifest": { ... }, // human-readable mirror, never trusted on its own "publicKeyJwk": { ... }, // convenience copy of the signing public key "keyId": "base64url(SHA-256(pubkey))" } ``` Only `jws` counts. The `manifest` field is there so a person can read the file without decoding anything, and a verifier that finds the two disagreeing ignores the mirror and believes the signature. That is why verification re-parses the manifest from the bytes the signature covered, rather than from the copy sitting next to it. ## The question verification asks **Is this signed by the key I already trust?** Never "does a file exist at this domain", never "did the API return 200", never "is this person logged in". Those questions all have answers that somebody else can arrange. A signature has exactly one producer. The `keyId` is `base64url(SHA-256(...))` of the public key, canonicalized to `{crv, kty, x}` so it comes out the same on every platform. That fingerprint is what a verifier pins when it decides to trust you. ## The server never signs The server does exactly three things with a manifest: verify it, decide whether the key that signed it is allowed to, and store it. It holds no private key, so it has no way to produce a manifest on your behalf even if it wanted to. That is what makes "the key is the root of trust" a fact about the system rather than a promise about our conduct. ## What the server checks before storing 1. **The signature verifies**, and the `keyId` matches the embedded public key. 2. **The chain position is right.** Its `seq` and `prev` must continue from the head we actually hold. Get this wrong and you are told to reload and sign again, which is the normal outcome when two devices publish close together. Nothing is lost. 3. **The signing key is allowed.** Either it is the key already registered to you, or the manifest carries an authorized [rotation or recovery](https://docs.realhandles.com/key/recovery-and-rotation/). A login gets you nowhere here. It decides which identity row you may write to, and then the signature decides whether the write is legitimate. ## Why your edit is not public until you re-sign This is the single most confusing thing about the model, so here it is plainly. Adding an account, verifying a domain, writing a disavowal, or reordering a list changes **our copy** immediately. Your profile on `realhandles.com` shows it right away. Your signed proof does not contain it, because nothing has signed it yet. Until you publish and your key signs the new version: - Anyone verifying you independently sees the previous version, which is the correct answer to give. - The change exists only as our word for it, which is exactly the kind of claim this product exists to stop people from having to accept. - The dashboard says so, and the mobile app says so, because the alternative would be showing you a proof that is not one. The fix is not a background job. It is a signature, and only you can produce it. Publish. ## Publishing a new version ### Web ![One manifest lists every published account and the anchor](https://docs.realhandles.com/_astro/signed-proof.BsQIsKxO.png) One manifest lists every published account and the anchor. Re-signing is what moves an edit from the server into something anyone can check. The sign button at the top of the dashboard is what does it, and it names the state you are in rather than making you work it out: **Sign & publish changes** next to an **Unpublished changes** badge while something is waiting, **Sign / update manifest** when nothing is, and **Unlock your key to sign** when the key is locked. The badge is a button. Click **Unpublished changes** and you get the list of what publishing would actually change, compared against the manifest you have already signed: accounts added, removed, reordered or edited, disavowals in either direction, your display name, your anchor, whether the profile is public, the completeness claim, and an Emergency Kit being published, replaced or removed. ![The publish preview, listing what a publish would change](https://docs.realhandles.com/_astro/publish-preview.CHI37PH2.png) It is read-only, and deliberately has no publish button. Deciding what to sign and signing it are separate acts, because a signature is public, permanent and yours. An account row is worth reading closely there. If a published account **id** would be dropped, the list says so in those words rather than calling it an edit, because that is the difference between a routine change and the one move somebody makes after taking a handle over. See [Verifying an account](https://docs.realhandles.com/accounts/verifying-an-account/). ### Android The app signs manifests. The rule that the server never signs is unchanged by that, and so is the rule that only your key can produce a version: the app has to hold the key and have it unlocked, and it says which of those is missing rather than offering a publish button that could only fail. The Identity tab carries the same split this page describes. A banner reads **Saved, but not published yet** while your changes are on realhandles.com and not yet in anything signed. **Publish & re-sign** is what closes it: your key signs the current state and a new entry joins your history. The banner is also a way in. **See what would change** on it opens **What publishing would change**, the same read-only list of pending changes the dashboard's badge opens, built from the same rules. It is a reading aid and it never refuses anything: the point is that the only way to learn what a publish would do used to be publishing and comparing afterwards, which is the wrong order for an irreversible, public, signed act. A second mechanism sits behind it, and this one the app has and the dashboard does not. If the version about to be signed would drop something the last one carried, the app asks first and names what is going. That one is a safety gate rather than a preview, which is why it is not folded into the list above: merging them would give you either a gate that nags about ordinary edits or a preview that stays quiet about the one change worth stopping for. Publishing cannot be undone, and the correct moment to notice a missing account is before the signature, not after. Two devices publishing close together produce the ordinary chain-position rejection described above. The app answers it the same way: reload and sign again. Nothing is lost. ![The Data section, gathering the anchor, the history, the export and the destructive actions](https://docs.realhandles.com/_astro/mobile-publish.DPjOOcqh.png) Report and delete sit apart from each other in the Data section, with delete last, because a misclick between flagging someone else and destroying your own identity is not recoverable. ## What is inside the payload | Field | Purpose | | --- | --- | | `subject` | Handle, display name, public key, keyId | | `accounts` | Verified and claimed accounts, in the order you set | | `disavowed` | Signed "not me" statements | | `anchor` | One rotatable pointer to a hosted copy. Not the identity | | `visibility` | Whether the profile is public or hidden. Absent means public | | `seq`, `prev` | Position in your history and the hash of the version before it | | `rotation` | Present only on a version that changes the signing key | | `recovery` | Keys authorized in advance to take the identity back | | `issued`, `statement` | When, and the human-readable claim | `seq` and `prev` are optional for backward compatibility: a manifest without them is treated as the first version. Everything else about the format is additive by design, so an old verifier does not break when a new field appears. ## Verifying one yourself The reference verifier is published as [`@realhandles/verify`](https://www.npmjs.com/package/@realhandles/verify) and is the exact code this site runs, extracted verbatim. The spec, JSON Schema, and conformance vectors, including invalid ones that must fail, live in [realhandles/spec](https://github.com/realhandles/spec). ![The verify page on realhandles.com, which fetches a manifest and checks its signature](https://docs.realhandles.com/_astro/verify-page.CjLN_Z99.png) The page above runs the same check in your browser. It fetches the manifest and tests the signature against the key in the file, so a wrong answer from this server would be visible rather than persuasive. Neither is required. It is a standard EdDSA JWS, so any JOSE library reaches the same conclusion, which is the entire point of choosing a boring format. --- # Anchoring URL: https://docs.realhandles.com/how-it-works/anchoring/ Description: How a domain anchors an identity without ever becoming the identity. An anchor is a copy of your signed identity, hosted somewhere you control. It is optional, it is one pointer among possible many, and it is never the identity. Your key is. ## What an anchor buys you One thing, and it is a big thing: if RealHandles disappears, the file you hosted is still there and still verifies against your key. Somebody who saved your `keyId` years ago can check it with no working RealHandles and no cooperation from anyone. That is the whole value. An anchor does not make you more verified, it does not raise your trust score, and it does not affect which handle you can hold. ## The two forms **A full manifest** is self-contained. It survives us being gone, which is the point. It needs re-hosting every time you publish a new version, or the copy on your domain goes stale. **A pointer** is signed once and hosted once. It proves you control the location and points at the always-current proof on RealHandles. Publishing again never means touching your server. The trade is that it is not self-contained: if RealHandles is gone, the pointer proves you control the domain but cannot show anyone what you claimed. Either form goes at `/.well-known/realhandles.json` on your domain, or at a raw file URL you control. ## Why a lapsed domain cannot take your identity Every check asks the same question: **is this file signed by the key we already trust?** A domain that lapses, or gets seized, or gets bought by somebody with your name hands over control of an address and nothing to sign with. Any file hosted at that location fails verification, because the signature is not yours and cannot be made to be. So the worst case is that your anchor goes from verified to lapsed. Your key, your handle, your accounts, and your signed history are untouched, and nobody verifying you is misled for a moment. This is the `did:plc` property: follow the key, not the name. The reverse also holds. Moving your anchor to a different domain changes nothing about who you are. It drops back to unchecked until the new location is confirmed, and that is all. ## When an anchor goes back to unchecked - You moved it, or changed where we look. - You [rotated your key](https://docs.realhandles.com/key/recovery-and-rotation/). The hosted file was signed by the retired key, so it no longer proves anything about the current one. Re-host and re-verify. - The check ran and the file was missing, unreadable, or signed by a key that is not yours. A check only reads the file. It never writes anything and never changes your identity, so running it as often as you like costs nothing. ## Anchoring is not the same as a domain proof They are easy to confuse because both involve a domain you own. | | Domain proof | Anchor | | --- | --- | --- | | What it proves | You control the domain | A copy of your signed identity lives at a place you control | | How | A one-time token in a file or a DNS TXT record | A signed file hosted at a known path | | Effect on trust score | Yes | None | | Effect on which handle you can hold | Yes, and it is the strongest kind of match | None | | Why you want it | Stronger identity, scarcer handle | Your proof outlives RealHandles | You can do both with the same domain. They are separate actions and either works without the other. See [Verifying an account](https://docs.realhandles.com/accounts/verifying-an-account/) for the proof side. ## Anchoring on a Gist, start to finish A Gist is the route when there is no domain to host on, and it is the one worth walking through because two steps in it are not obvious. 1. On the **Publish** tab, under **Where to host it**, choose **GitHub Gist (no domain needed)**. 2. Press **Download pointer file** while the URL box is still empty. This looks like it cannot work, since the box wants a Gist that does not exist and the Gist wants a file you do not have. It works anyway: saving the location is skipped when the box is blank, so the download goes ahead. The file is small and contains nothing private, just your key id, your public key, the canonical URL of your profile, and a signature over the three. 3. Create a **public** Gist with a file named `realhandles.json` and paste the downloaded contents into it. Public rather than secret, because an anchor exists to be found. Nothing in the file is secret either: it is the same public key already published on your profile. 4. Copy the **Raw** URL, then delete the commit hash from it. This is the step that quietly breaks anchors. GitHub hands you a Raw link pinned to the exact revision: ``` https://gist.githubusercontent.com/you/GIST_ID/raw/4cc92f1bffca7219246de.../realhandles.json ``` That URL will serve this version of the file forever, so if you ever replace the pointer the anchor keeps reading the old one. Remove the hash segment and use the form that always follows the latest revision: ``` https://gist.githubusercontent.com/you/GIST_ID/raw/realhandles.json ``` 5. Paste that URL into **Gist raw URL**, press **Save anchor location**, then press **Verify anchor**. ![The anchor panel showing a verified Gist, with the Anchored badge and the time it was last checked](https://docs.realhandles.com/_astro/anchor-panel.DQwNZ2A9.png) A pass reads **Anchored**, and says what it found: a signed pointer by a key it already trusts. It is checking the signature, not just that a file exists, so a Gist containing somebody else's pointer fails here rather than passing quietly. A pointer never needs touching again. It names your profile rather than copying it, so publishing a new version of your manifest does not invalidate it. A full manifest is the other trade: self-contained, and therefore stale the moment you re-sign unless you re-host it. ## Where you set it ### Web The anchor panel is on the **Publish** tab of the dashboard. ![The anchor panel, offering a domain or a GitHub Gist as the host](https://docs.realhandles.com/_astro/anchor-panel.DQwNZ2A9.png) A pointer file is signed once and hosted once. A full manifest is self-contained and keeps working even if RealHandles is gone, which is the case the anchor exists for. A Gist works when there is no domain to host on. **Save anchor location** records where we should look, the two download buttons hand you the file to put there, and **Verify anchor** reads it back. ### Android **Identity > Data > Anchor your identity elsewhere.** ![The anchor screen, for hosting a signed pointer somewhere you control](https://docs.realhandles.com/_astro/mobile-anchor.BF1Xe_B8.png) A domain you control, or a Gist when there is no domain. The screen offers the same two hosts as the website, and prefills any domain you have already proved so the name does not have to be retyped. For a Gist it insists on the raw file URL, because the Gist page itself is HTML and a check against that finds no JSON. The status line is the one on this page: anchored, lapsed, or not checked, with when it was last read. **Check anchor** runs it again, and the app repeats what is true, that a check only reads the file and can be run as often as you like. Moving an anchor that currently verifies asks for a confirmation first, and says what actually happens: the location drops back to unchecked until the new one is confirmed, and your key, your handle and your verified accounts are untouched. The app also asks which file you hosted, a pointer or a full manifest. That answer is only so the advice after your next publish is correct: a full manifest needs re-hosting every time, and a pointer never does. --- # Reading the history URL: https://docs.realhandles.com/how-it-works/reading-the-history/ Description: The sigchain, the OpenTimestamps proof, and how to audit an identity end to end. Every version of an identity that has ever been published is kept, and every version is signed. The chain proves order and authorship. Bitcoin timestamps prove time. Together they mean nobody can rewrite the past quietly, including us. ## The chain Each manifest carries two fields inside the signed payload: - `seq`: its place in line. The first version is 0, and each new one adds 1. - `prev`: `base64url(SHA-256(...))` of the previous version's JWS. Because `prev` is covered by the signature, editing any old version changes its hash, which breaks the link every later version depends on. The history is append-only, and it is append-only as a matter of arithmetic rather than policy. Fetch the whole thing, oldest first: ``` GET https://realhandles.com//realhandles-chain.json ``` ## What a valid chain means `verifyChain` in [`@realhandles/verify`](https://www.npmjs.com/package/@realhandles/verify) checks all of it: 1. Every entry's signature verifies against the public key inside it. 2. `seq` starts at 0 and increments by 1, with no gaps. 3. Each `prev` equals the hash of the entry before it. 4. The signing key stays the same, unless an entry carries a key change that was properly authorized. On a key change it checks the authorization the same way the server did: either the previous key signed the handoff, or enough keys the identity had **already published** as Emergency Kits signed it. The recovery policy it judges against is the one in force before that entry, never the one the entry declares about itself. See [Recovery and rotation](https://docs.realhandles.com/key/recovery-and-rotation/). If you pin a key, pin the **genesis** key. The chain then proves the current key from it, which is exactly the property that lets someone follow you through a rotation without having to be told. ## Reading the outcomes | What you see | What it means | | --- | --- | | Chain valid, same key throughout | Nothing has changed hands. | | Chain valid, key changed with a handoff signed by the old key | An ordinary rotation. Same person, new key. | | Chain valid, key changed with enough designated recovery signatures | A recovery. The identity came back through keys named in advance. | | Key changed with no authorization in the entry | Do not trust it. The chain says so, in the entry itself. | | Key differs from the one you saw before, and no handoff anywhere in the history | The identity you are looking at is not the one you saw before, whatever the handle says. | ## Bitcoin timestamps The chain proves order and authorship, but it does not prove when, and every entry in it lives in our database. An operator with database access could in principle fabricate a whole consistent history and date it to last year. Nothing inside the chain would contradict that. OpenTimestamps closes it. The SHA-256 of each version's JWS is submitted to public calendars and committed into the Bitcoin blockchain. That digest is the same one the next version records as its `prev`, so a timestamp on one entry transitively pins everything before it. Free, and no coins involved. ``` GET https://realhandles.com//realhandles.ots ``` Timestamping runs on a schedule rather than at the moment you publish, because nothing about saving your own signed manifest should depend on a third party being up. The honest consequence: a proof attests "existed no later than this block", a little after you pressed publish. An upper bound on the date is what a timestamp proves anyway. A version showing as pending simply has not made it into a block yet. It does not mean anything is wrong. ## Auditing an identity yourself 1. Fetch `realhandles-chain.json` and run `verifyChain` over it. 2. Compare the resulting key to whatever you pinned last time. If you have never seen this identity before, pin the genesis key now. 3. Fetch `realhandles.ots` and check it with the standard `ots` CLI against the corresponding JWS. Step 3 is the one that matters if you do not want to take our word for anything. What the dashboard shows about Bitcoin status is us reporting on ourselves. The `.ots` file is checkable without us, and we deliberately do not verify the Bitcoin attestation for you: doing that properly needs a block header source, and handing it to your own OpenTimestamps tooling is the more honest answer. ## Your own history ### Web The dashboard links it from the **Publish** tab. **View signed history** opens `realhandles-chain.json`, and **Download .ots proof** hands you the file step 3 needs. The badge beside them says whether the current version is committed to a Bitcoin block yet or still waiting for one. ### Android **Identity > Data > Signed history.** ![The signed history on Android, one entry per published version](https://docs.realhandles.com/_astro/mobile-history.CsolZYSO.png) Anything this phone has not verified for itself is attributed rather than asserted, including the Bitcoin timestamps, which the app does not open the proof file to check. Every published version, in order, with what changed at each one written out in words: a handle change, an account added or removed, an anchor moved, a recovery policy published or removed, and a key change with whether the handoff was authorized. **Check this history** runs steps 1 and 2 of the audit above in the app. Every signature and every link is checked on the device, and the result says so plainly, "Checked on this phone", rather than reporting what a server concluded. Step 3 is not done for you, deliberately. The app does not fetch the `.ots` file and never asks a Bitcoin node anything, so a version reading as confirmed is RealHandles reporting on RealHandles, and the app words it that way. Check the proof file with any OpenTimestamps tool if you want the date to rest on something other than our word. ## Checking somebody else Reading a history is how you decide whether to trust a stranger, so it is a different job from looking at your own and both clients keep it on a separate screen. ### Web ![The RealHandles directory, listing published identities](https://docs.realhandles.com/_astro/directory.BXS7dAZr.png) The directory lists published identities. Every profile it links to serves its own manifest and history at fixed paths, so anything here can be audited by the steps above without asking this site to vouch for it. For a handle you were handed rather than found, `realhandles.com/verify` takes the name and runs the check in your browser, using the same [`@realhandles/verify`](https://www.npmjs.com/package/@realhandles/verify) code the steps above call for. ### Android The search icon in the top right of the header takes a handle, fetches the proof, and verifies the signature and the whole chain on the device. Any profile you open from the **Directory** offers the same check, so a name you found and a name you were handed end up on the same screen. It is not a tab of its own: checking is what you do once when somebody claims to be somebody, not something you do daily. ![The check screen, for checking someone else](https://docs.realhandles.com/_astro/mobile-check.xkEayXyc.png) This is what checks a handle you were handed. It verifies the signature on the device, so a wrong answer from the server would be visible rather than persuasive. It also does the pinning this page recommends, without being asked. The genesis key of every handle you check is remembered, listed on the Keys tab, and compared on every later check. If the key signing a handle now is not the one you trusted before, and nothing in the history authorizes the change, the app stops and says the name is being held by a stranger until that is explained. An authorized rotation passes through quietly, which is the property that lets you follow somebody through a key change without being told. --- # Exporting your data URL: https://docs.realhandles.com/data/exporting-your-data/ Description: Take the whole identity with you: manifest, chain, proofs, and timestamps. Everything that matters about your identity is a file you can download right now, and the important ones are public, so you do not even need to be signed in to fetch them. ## The files | File | Where | What it is for | | --- | --- | --- | | `realhandles.json` | `realhandles.com//realhandles.json` | Your current signed manifest. The proof itself. | | `realhandles-chain.json` | `realhandles.com//realhandles-chain.json` | Every version ever published, oldest first. | | `realhandles.ots` | `realhandles.com//realhandles.ots` | The OpenTimestamps proof that the current version existed by a given Bitcoin block. | | `did.json` | `realhandles.com//did.json` | A W3C DID document, so the profile resolves as a `did:web` for standard DID tooling. | | `realhandles-.json` | The Export action in your dashboard | Our full copy: handle, profile, accounts, anchor, and the signed manifest. | | `realhandles-key.json` | Downloaded when you make or re-wrap your key | Your Identity Backup. | The first four are URLs and need no app at all. Anything that can fetch a page can fetch them. ## What each one is actually for **`realhandles.json` is the one that survives us.** It is a compact JWS signed by your key. Anyone can check it against your public key with off-the-shelf tooling and no access to RealHandles. If this site disappeared tomorrow, this file still proves what it proves. **`realhandles-chain.json` is the audit trail.** The current manifest tells you what is true now. The chain tells you how it got that way, including any key change and whether it was authorized. See [Reading the history](https://docs.realhandles.com/how-it-works/reading-the-history/). **The dashboard export is the directory copy.** It lists what we hold: your handle, your profile, your accounts, your anchor, and the signed manifest. Useful as a single snapshot, and honest about the split: the signed manifest inside it verifies independently, and the rest is our record. **`realhandles-key.json` is not an export of your identity.** It is an encrypted copy of your signing key, and it is the only file on this page that must stay private. See [Your signing key](https://docs.realhandles.com/key/your-signing-key/). > **Caution:** Your private key is not in any export, and it never can be. We do not have it. ## Taking the export Both clients produce the same file. What differs is what you can do with it once it exists. ### Web **Export everything as JSON**, on the **Data** tab, downloads it. Next to it is **Verify my proof independently**, which runs the same check a stranger would run. ![Everything held about you in one file](https://docs.realhandles.com/_astro/data-export.7vACHv_J.png) Everything held about you in one file. The signed manifest inside it verifies without RealHandles, which is the point of the export. ### Android **Identity > Data > Export everything** produces the same file the dashboard export does. ![The export screen, offering to save or share the signed JSON](https://docs.realhandles.com/_astro/mobile-export.CV-WqXmo.png) Sharing is offered only below 256 KB, because Android moves an app-to-app payload through a buffer the whole app shares and going over means the share sheet silently never appears. Before it hands anything over the screen shows what is in it: the handle, the number of accounts, how many signed versions exist, the key that signed the current one, and the first few lines of the JSON. If nothing has been published yet it says that outright, because a directory copy with no signature in it is worth knowing about before you file it away. Two ways out of the app. **Save it on this phone** writes the file. **Share my export** hands it to another app, behind a confirmation, because the share sheet puts a cloud drive and a group chat one tap from a file naming every account on your identity. Past 256 KB the share route is withheld and only saving is offered. Android moves an app-to-app payload through a single one megabyte buffer shared by everything the app has in flight, so a payload may safely use only a fraction of it; going over throws in the sending app and the share sheet simply never appears. ## Verifying an export yourself ```ts import { verifySignedManifest } from '@realhandles/verify'; const file = await fetch('https://realhandles.com/david/realhandles.json').then((r) => r.json()); const { valid, keyId, manifest } = await verifySignedManifest(file); ``` `@realhandles/verify` is the same verification code this site runs, published on npm and open source. Using it is convenient rather than required: the format is a standard EdDSA JWS, so any JOSE library gets the same answer. ## Importing what you already have ### Web The other direction works too. Point the importer at a page you control, or upload a file, and it pulls out profiles from `rel="me"` links, `schema.org` `sameAs`, or a plain JSON link list, then marks the ones already attached to you. It is a shortcut for entering accounts, not a proof. Each one still has to be verified or claimed. See [Verifying an account](https://docs.realhandles.com/accounts/verifying-an-account/). ### Android There is no importer in the app. Reading `rel="me"` links off a page you control is website only, so bulk-entering accounts that way is a job for a computer. Sending your key out is also not treated as data here. The app handles it as a key transfer, under **Keys > Send key to another device**, rather than as part of an export. See [Your signing key](https://docs.realhandles.com/key/your-signing-key/). ## Leaving Deleting the identity takes it off our files. Everything you already published stays published: copies people downloaded, the anchor file on your own domain, and the Bitcoin timestamps, none of which we can recall. Export first if you want a copy of the directory record.