NIP-05

Mapping Nostr keys to DNS-based internet identifiers

draft optional author:fiatjaf

On events of type 0 (set_metadata) one can specify the key "nip05" with an internet identifier (an email-like address) as the value. Although there is a link to a very liberal "internet identifier" specification above, NIP-05 assumes the <local-part> part will be restricted to the characters a-z0-9-_., case insensitive.

Upon seeing that, the client splits the identifier into <local-part> and <domain> and use these values to make a GET request to https://<domain>/.well-known/nostr.json?name=<local-part>.

The result should be a JSON document object with a key "names" that should then be a mapping of names to public keys. If the public key for the given <name> matches the pubkey from the set_metadata event, the client then concludes that the given pubkey can indeed be referenced by its identifier.

Example

If a client sees an event like this:

{
  "pubkey": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9",
  "kind": 0,
  "content": "{\"name\": \"bob\", \"nip05\": \"bob@example.com\"}"
  ...
}

It will make a GET request to https://example.com/.well-known/nostr.json?name=bob and get back a response that will look like

{
  "names": {
    "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9"
  }
}

That will mean everything is alright.

Notes

User Discovery implementation suggestion

A client can also use this to allow users to search other profiles. If a client has a search box or something like that, a user may be able to type "bob@example.com" there and the client would recognize that and do the proper queries to obtain a pubkey and suggest that to the user.

Showing just the domain as an identifier

Clients may treat the identifier _@domain as the "root" identifier, and choose to display it as just the <domain>. For example, if Bob owns bob.com, he may not want an identifier like bob@bob.com as that is redundant. Instead Bob can use the identifier _@bob.com and expect Nostr clients to show and treat that as just bob.com for all purposes.

Reasoning for the `/.well-known/nostr.json?name=<local-part>` format

By adding the <local-part> as a query string instead of as part of the path the protocol can support both dynamic servers that can generate JSON on-demand and static servers with a JSON file in it that may contain multiple names.

2.6 KiB Raw Blame History