NIP-05: Mapping Nostr keys to DNS-based internet identifiers
Human names without replacing keys
NIP-05 exists because raw public keys are terrible social objects. They are sovereign and portable, but they are not memorable. A user can own a key and still need a handle that another person can read, type, search or recognize. NIP-05 bridges that gap with DNS.
The standard lets a kind 0 metadata event include a nip05 value such as alice@example.com. A client then checks https://example.com/.well-known/nostr.json?name=alice and confirms whether the domain maps that name back to the same public key. If it matches, the client can display the identifier.
The critical point is that NIP-05 does not replace the public key. The key remains the account. The DNS name is a readable pointer and, sometimes, an attestation that a domain operator is willing to associate a name with a key.
The well-known lookup and its boundaries
The lookup is deliberately web-shaped. The client splits the identifier into local part and domain, fetches the well-known JSON endpoint, and reads a names object mapping local names to lowercase hex public keys. The local part is restricted to a-z0-9-_., even though the linked internet-identifier reference is broader.
The optional but recommended relays object can map pubkeys to relay URLs. That turns NIP-05 into more than a display badge: it can also help clients find where a user's events may live. The source is careful, though. Clients follow public keys, not NIP-05 addresses. If a domain later maps the same name to a different key, a client must not silently replace the followed pubkey.
The notes section is unusually important. It says NIP-05 is identification, not verification. That line prevents a lot of product confusion. A domain can be meaningful when it is controlled by a person, company or project you already trusts. But a green check beside a NIP-05 name is not proof that the person is who the user thinks they are.
A small spec with many trust repairs
NIP-05 entered the visible NIPs repository in May 2022. David A. Harding added early CORS guidance in May 2022, because browser clients need cross-origin access to the well-known JSON. In December 2022, commits clarified that NIP-05 identifiers must not be treated as primary keys and that keys must be hex. Those two points became central to safe implementation.
The later history reads like a series of trust repairs. In March 2024, utxo made the relays attribute recommended. In August 2024, dtonon added the identification-versus-verification note. In February 2026, Vitor Pamplona's PR #2208 explicitly required lowercase for hex keys and names. Each change closes a small product ambiguity that could otherwise become a user-facing trust bug.
This is why NIP-05 deserves a real article rather than a short definition. It is not just 'Nostr usernames.' It is a negotiated boundary between key sovereignty, DNS convenience, web hosting, browser security and user psychology.
Why clients need to be strict
NIP-05 is simple to demo and easy to implement badly. A client has to fetch the well-known JSON, handle CORS failure, ignore redirects, require lowercase hex keys, compare the result with the pubkey in metadata and decide what to show when the mapping changes.
The product surface is deceptively sensitive. If the UI treats a NIP-05 name like a verified identity badge, users may overtrust it. If the UI ignores it entirely, users lose one of the few human-readable handles in the network. The best implementations make the identifier useful without hiding the key model.
Block's engineering write-up on trust in NIP-05 identifiers is useful here because it focuses on the social meaning of the mapping. A NIP-05 identifier can tell you something about a relationship to a domain, but what it means depends on who controls that domain and why the user trusts it.
DNS convenience reintroduces DNS risk
NIP-05 is useful precisely because it borrows from the web. That also means it inherits web risks: domain loss, server compromise, CORS mistakes, redirects, stale JSON, misleading names and the temptation to present DNS control as identity truth.
The most important client rule is also the easiest to forget: follow the pubkey, not the NIP-05 address. If the domain mapping changes, the identifier becomes invalid for that key; the user's follow list does not magically move to a new key. That one product choice preserves the sovereignty model Nostr is trying to protect.
Read NIP-05 in the wild
NIP-05 gives a public key a human-readable internet handle. That sounds like a username, but it is closer to a signed identity pointer backed by a domain. The domain helps other people recognize a key; it does not replace the key or magically prove the human behind it.
The risk sits exactly where the convenience sits. Domains expire, teams change DNS, JSON files break, and names can be reassigned. A good client treats NIP-05 as useful evidence, not as the identity itself.
What changes when you actually use it
For you, NIP-05: Mapping Nostr keys to DNS-based internet identifiers is felt when identity stops being a username and becomes authority. A client, signer, name, proof or auth event may look like account plumbing, but it decides who can publish, approve, connect, recover or be recognized. Read NIP-19 beside it so you can tell the difference between a convenient identity surface and the key material that actually controls the account.
What changes for builders and operators
For builders, NIP-05: Mapping Nostr keys to DNS-based internet identifiers means making authority visible before action. A signer prompt, name proof, delegation, encrypted key, external identity or HTTP auth event needs plain language around scope, expiry, destination and recovery. If a person has to guess what they are authorizing, the protocol has already lost the trust battle.
What the official file makes concrete
The official file is organized around Example, Finding users from their NIP-05 identifier, Notes, Identification, not verification, User discovery implementation suggestion, Clients must always follow public keys, not NIP-05 addresses, Public keys must be in hex format, Showing just the domain as an identifier. Inspect user metadata, "names", <name>, pubkey, "relays", npub, /.well-known/nostr.json?name=<local-part> because these are the pieces most likely to surface as product behavior. Read it beside NIP-19 before treating it as isolated.
NIP-05: Mapping Nostr keys to DNS-based internet identifiers is an authority path, not decoration. A name, key, signer, delegation or auth event decides who can act as you.
Where it breaks
The failure mode in NIP-05: Mapping Nostr keys to DNS-based internet identifiers is authority drift. A name resolves to an old key, a signer approves too broadly, an auth event gets replayed, a delegation lasts too long or a private key backup gives false comfort. The product has to keep control boundaries visible after onboarding, not only during setup.
Where this appears outside the markdown
In the ecosystem, NIP-05: Mapping Nostr keys to DNS-based internet identifiers usually appears at the doorway: account setup, profile recognition, signer approval, cross-platform proof, remote signing, HTTP auth or recovery. That doorway needs unusually clear language because identity mistakes are sticky. Once a key, signer or proof is trusted in the wrong place, every later feature inherits the confusion.
The nearby-standard trap
The nearby-standard trap in NIP-05: Mapping Nostr keys to DNS-based internet identifiers is confusing recognition with control. A name, signer, URI, encrypted key, delegation or auth signature may all sit near identity, but they answer different questions. Read NIP-19 and ask one thing each time: who can act, who can verify, and what can be revoked?
Language that keeps the feature honest
Good product copy for NIP-05: Mapping Nostr keys to DNS-based internet identifiers names the authority. It says whether you are sharing a public key, approving a signature, trusting a domain, exporting an encrypted secret, delegating power or authenticating to a service. Small labels matter because identity mistakes do not feel small after they happen.
What this page does not promise
NIP-05: Mapping Nostr keys to DNS-based internet identifiers does not make identity effortless or risk-free. It can help keys, names, signers, delegation or authentication become portable, but it cannot decide who you trust, how you back up secrets or whether a domain, app or signer deserves authority. Read NIP-19 as a control map before handing any interface the power to sign, verify or speak for you.
Read it as a field test
Start NIP-05: Mapping Nostr keys to DNS-based internet identifiers with the moment of authority: signing, naming, delegation, authentication, encryption or recovery. Then ask which key or service can act. The source terms user metadata, "names", <name>, pubkey, "relays", npub are useful because they turn vague identity language into concrete control points. Without that, a friendly login screen can hide the most important security decision.
Where the standard earns trust
The source links give you places to test the interpretation in public: PR #2208, Block Engineering: Trust in NIP-05 Identifiers, RFC 5322 address grammar, MDN CORS. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-05 source is the anchor for exact wording, and NIP-05 commit history shows how that wording moved over time. The strongest secondary clues here are PR #2208, Block Engineering: Trust in NIP-05 Identifiers, RFC 5322 address grammar. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-05: Mapping Nostr keys to DNS-based internet identifiers: first the human promise, then user metadata, "names", <name>, pubkey, "relays", npub, then the implementation record, then the real-world failure case. That order keeps NIP-05 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Who gains authority when this NIP is used: your key, a signer, a domain, a delegated key, a wallet or a web service?
- Can you revoke, rotate, back up or inspect that authority before something goes wrong?
- Does the interface separate public recognition from private signing power in language you can act on?
What to verify before you rely on it
- Find
user metadata,"names",<name>,pubkey,"relays"in the official file and check where the UI exposes the same concept. - Read NIP-19 as context before treating NIP-05 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-05: Mapping Nostr keys to DNS-based internet identifiers in that order: Official NIP-05 source for the current wording; NIP-05 commit history for the change record; PR #2208, Block Engineering: Trust in NIP-05 Identifiers, RFC 5322 address grammar for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
