Skip to content

Instantly share code, notes, and snippets.

@metasikander
Last active December 2, 2024 14:04
Show Gist options
  • Save metasikander/609a538e6a03b2f67e5c8de625baed3e to your computer and use it in GitHub Desktop.
Save metasikander/609a538e6a03b2f67e5c8de625baed3e to your computer and use it in GitHub Desktop.
A small minimal guide on setting up NIP-05 identifier on branle/nostr

This is a very basic guide, just to understand what's needed to set it up.
If you have any questions you can find me at https://nostr.com/8355095016fddbe31fcf1453b26f613553e9758cf2263e190eac8fd96a3d3de9

Prerequisite

Setup static file on server

Create a file that resolves to <domain>/.well-known/nostr.json, and fill it out like this (enter the name you want to use, and input your own public key, make sure its the HEX-key):

{
  "names": {
    "<name>": "<pubkey>"
  }
}

Setup CORS permissions

For branle to be able to execute the file, you have to allow CORS on your webserver.
On nginx you just have to put this in the config:

add_header 'Access-Control-Allow-Origin' '*';

Setup branle/nostr

In branle, go to settings and fill inn your <name>@<your topdomain> in the "NIP-05 Identifier" field.
image

Go you your profile. If everything worked out, you will see a checkmark next to your name (based on your domain).
image

Extra tools

  • NIP-05 Creation Tool: Use this to generate the .well-known/nostr.json file, and also a .htaccess file for Apache if you don't use Nginx

Usual problems

  • CORS: Make sure CORS is correctly set up. You can test it here: https://www.test-cors.org/
  • Pub-key: Only use the HEX-key. Npub-key won't work.
@AnthonieWeyland
Copy link

Good info thanks !

@metasikander
Copy link
Author

Good info thanks !

you're welcome! Share it far and wide! :D

@markjr
Copy link

markjr commented Jan 4, 2023

If you're going to tie a label like an email address to a pubkey, why not just use the DNS to create the linkage as well (I've been having a similar conversation with the lnURL people) - with well-known file paths, you need access to the webserver, the webserver may not be the same host as the hostname component of the email identifier, not to mention, what do do you do when you want to switch servers but retain the same identifier?

You could use scoped TXT records like _nip05 to signal your pubkey:

Given test@example.com:

$ORIGIN example.com.
_nip05.test IN TXT “<pubkey>”
_nip05url.text IN TXT "http://<domain>.well-known/nostr.json"

The first record _nip05 would just be a straight reference to the pubkey.

There could also be a reference type for the well-known file URI, but you get the added flexibility that the file doesn't have to reside on the same webserver as example.com.

See: andrerfneves/lightning-address#27 (comment)

And I also wrote this article:

https://bitcoinmagazine.com/technical/simplifying-bitcoin-addresses-dns

@Dielan
Copy link

Dielan commented Jan 5, 2023

@markjr can you elaborate on this a little more? I think there's plenty of Nostr users/potential Nostr users who either don't currently have any web hosting, or don't want to mess with the hosting they have. I personally experience great dread at the thought of modifying an nginx or apache config. In my case the domain I want to sue for my own NIP05 verification is pointed to a hosted solution I don't control, I just point DNS at it.

Is setting up my own NIP05 verification really as simple as a TXT DNS record for the pubkey?

@markjr
Copy link

markjr commented Jan 6, 2023

@Dielan it isn't that simple, because the protocol doesn't support it, my point is it could be that simple if this was adopted. I think it works better than using a well-known file URL because you need the extra level of indirection in there for changes and for people who have no control over their webserver.

If you're going to use name@example.com as the identifier, then the best place to put NIP05 validation is under example.com because the user has ultimate control over that.

@metasikander
Copy link
Author

have you mentioned this here: https://github.com/nostr-protocol/nips/blob/master/05.md
i think a lot of people want this, and i have seen keybase mentioned several times (wrt what they support).
i imagine the biggest hurdle is to get the clients to support it, but nothing stops anyone from setting it up and asking the client devs to support it.

@dtrammell
Copy link

dtrammell commented Feb 4, 2023

If you're going to tie a label like an email address to a pubkey, why not just use the DNS to create the linkage as well (I've been having a similar conversation with the lnURL people) - with well-known file paths, you need access to the webserver, the webserver may not be the same host as the hostname component of the email identifier, not to mention, what do do you do when you want to switch servers but retain the same identifier?

It's not intended to be an email address. It's verifying that a domain is vouching for a particular user, or that the user exists at the domain. It's just formatted like an email address because that's how email addresses are also formatted. user@domain. This doesn't mean that the user at that domain can necessarily receive email there. For example, there are lots of people on Nostr taking small payments to vouch for other users at their domain. Those usernames likely don't even exist on the system that is hosting the webserver for that domain, nor can receive email there. I can create an entry for "markjr" in my validator at caughq.org, and now that's a valid NIP-05 address, but it is not an email address as I don't host email for you at my domain, nor do you actually have an account on the system.

NIP-05 specifically calls this an "Internet Identifier": https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1

@markjr
Copy link

markjr commented Feb 4, 2023

It's not intended to be an email address. It's verifying that a domain is vouching for a particular user, or that the user exists at the domain. It's just formatted like an email address because that's how email addresses are also formatted. user@domain. This doesn't mean that the user at that domain can necessarily receive email there. For example, there are lots of people on Nostr taking small payments to vouch for other users at their domain. Those usernames likely don't even exist on the system that is hosting the webserver for that domain, nor can receive email there. I can create an entry for "markjr" in my validator at caughq.org, and now that's a valid NIP-05 address, but it is not an email address as I don't host email for you at my domain, nor do you actually have an account on the system.

Perhaps I sounded too literal when I said "like an email address". I know this isn't email, but my point was that email addresses are formatted that way for a reason - they are user @ organization - and they wouldn't have became the de facto standard if they didn't have that additional level of abstraction at the organization level which was implemented via the MX RRType in DNS.

In way, you are saying something similar to what I've been trying to get across. You could create a "markjr" id at caughg.org - but these identifiers, whether they're email addresses in the legacy sense, or these new NIP-05 id's here in Nostr, people tend to want to use them as personal or organizational identities.

Maybe you set up an entire business creating ids and hosting metadata for other people, but a portion of them are going to want to be referenced through their own labels or identifiers.

So I would want to be able to create my identifier for "markjr" @ easydns.com which actually resolves out to my account at caughq.org

The extra level of abstraction also means I have portability - which is very important: If you just create "markjr" @ caughq.org and then shut down (or cancel me), then everything pointing at my now defunct nip05 id is bust and I have to start all over again with a new id. (It's no different than having your Twitter handle suspended.)

With the additional abstraction layer in there, I just create a new account at a new provider and update my DNS TXT record.

@dtrammell
Copy link

dtrammell commented Feb 4, 2023

The extra level of abstraction also means I have portability - which is very important: If you just create "markjr" @ caughq.org and then shut down (or cancel me), then everything pointing at my now defunct nip05 id is bust and I have to start all over again with a new id. (It's no different than having your Twitter handle suspended.)

With the additional abstraction layer in there, I just create a new account at a new provider and update my DNS TXT record.

The NIP-05 spec specifically addresses this portability issue by stating that once resolved, clients MUST manage follows with the pubkey, not the NIP-05 identifier. This way if the identifier breaks, only the identifier is no longer valid. You don't lose all of your followers or anything like that:

https://github.com/nostr-protocol/nips/blob/master/05.md#clients-must-always-follow-public-keys-not-nip-05-addresses

@dtrammell
Copy link

Perhaps I sounded too literal when I said "like an email address". I know this isn't email, but my point was that email addresses are formatted that way for a reason - they are user @ organization - and they wouldn't have became the de facto standard if they didn't have that additional level of abstraction at the organization level which was implemented via the MX RRType in DNS.

They're user@domain, because they were originally intended to point to users of various systems. SSH users that connect to other systems with the user@system convention understand this well. Organizations may have many domains (and sub-domains) and may use one of their root domains that maps clearly to their identity for mail and other services, but that's an abstraction that has simply just become commonplace. A lot of organizations still use the www sub-domain for web services, for example, even though the website is clearly the organization's primary brand website, so I see where you're coming from with the user@organization point.

In the case of NIP-05 however, the organization (through the domain) is simply vouching for identities. There is no other association implied by providing this domain validation. The more technical of us will of course set up validation on our own domains, but the vast majority of Nostr users will use a validation provider to vouch for their identity, with varying levels of verification. So far, these users don't seem to care too much about using these as organizational identifiers other than some vanity points for being verified by the "cool" domain, like NostrPlebs.com (Everyone wants to be a pleb, right? (:

I think you and I are in the tiny minority who will go out of their way to try and map their NIP-05 verification to their own organizational identity.

@duanzan
Copy link

duanzan commented Feb 5, 2023

i ve change my webserver's setup and how long supposed time i should wait for the verifaction process take again?

@metasikander
Copy link
Author

i ve change my webserver's setup and how long supposed time i should wait for the verifaction process take again?

it should work right away, depending on how the client handles it.
does it work in astral.ninja ?

@mad0perator
Copy link

If you're going to tie a label like an email address to a pubkey, why not just use the DNS to create the linkage as well (I've been having a similar conversation with the lnURL people) - with well-known file paths, you need access to the webserver, the webserver may not be the same host as the hostname component of the email identifier, not to mention, what do do you do when you want to switch servers but retain the same identifier?

You could use scoped TXT records like _nip05 to signal your pubkey:

Given test@example.com:

$ORIGIN example.com.
_nip05.test IN TXT “<pubkey>”
_nip05url.text IN TXT "http://<domain>.well-known/nostr.json"

The first record _nip05 would just be a straight reference to the pubkey.

There could also be a reference type for the well-known file URI, but you get the added flexibility that the file doesn't have to reside on the same webserver as example.com.

See: andrerfneves/lightning-address#27 (comment)

And I also wrote this article:

https://bitcoinmagazine.com/technical/simplifying-bitcoin-addresses-dns

Similar to the way DNSLink works for IPFS

@markjr
Copy link

markjr commented Feb 14, 2023

I think you and I are in the tiny minority who will go out of their way to try and map their NIP-05 verification to their own organizational identity.

I don't know if this will be a tiny minority.

Also, from your other reply:

The NIP-05 spec specifically addresses this portability issue by stating that once resolved, clients MUST manage follows with the pubkey, not the NIP-05 identifier. This way if the identifier breaks, only the identifier is no longer valid. You don't lose all of your followers or anything like that:

Thanks for pointing this out - it's good to know.

However, consider this: let's say Nostr really catches on to the point where people are putting their NIP-05 id's in their .sig files. social media handles and stone-age business cards - it doesn't help if a third-party provider goes away or cancels you, all those indelible references to your old NIP-05 break (it's exactly the same with IP addresses, after all).

In any case, I'm working on a NIP-05 ID server that will work for custom domains. We'll see if there's any demand for it.

@daveharig
Copy link

In case you need to convert your Damus Npub to Hex https://nstr.cloud/key.html

@CODLCO
Copy link

CODLCO commented Mar 10, 2023

If you're going to tie a label like an email address to a pubkey, why not just use the DNS to create the linkage as well (I've been having a similar conversation with the lnURL people) - with well-known file paths, you need access to the webserver, the webserver may not be the same host as the hostname component of the email identifier, not to mention, what do do you do when you want to switch servers but retain the same identifier?

You could use scoped TXT records like _nip05 to signal your pubkey:

Given test@example.com:

$ORIGIN example.com.
_nip05.test IN TXT “<pubkey>”
_nip05url.text IN TXT "http://<domain>.well-known/nostr.json"

The first record _nip05 would just be a straight reference to the pubkey.

There could also be a reference type for the well-known file URI, but you get the added flexibility that the file doesn't have to reside on the same webserver as example.com.

See: andrerfneves/lightning-address#27 (comment)

And I also wrote this article:

https://bitcoinmagazine.com/technical/simplifying-bitcoin-addresses-dns

This would be great. Or even if we could have a single name as a txt record maybe?

@davidvkimball
Copy link

Thank you, this guide was very helpful. I believe I've set this up correctly?

https://davidvkimball.com/.well-known/nostr.json?name=_

I want _@davidvkimball.com to be my NIP-05 key.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment