Short answer
With NIP-42 the relay sends a challenge, the client answers with a signed kind 22242 event carrying the relay and challenge tags, and the relay replies with OK. The relay must check kind, challenge, relay domain and a created_at close to now. Use the auth-required: prefix for clients that have not authenticated and restricted: for authenticated keys that are not allowed, and keep limitation.auth_required in NIP-11 truthful.
What NIP-42 does
NIP-42 lets a relay ask a client to prove that it controls a public key. The flow has three steps:
- The relay sends
["AUTH", "<challenge>"]to the client, usually right after the connection opens. - The client answers with
["AUTH", <event>]. The event is signed with the key it wants to prove, has kind22242and carries two tags:relay(the relay's URL) andchallenge(the string it received). It is never stored or broadcast. - The relay replies with a normal
OK. From then on the connection counts as authenticated for that key.
The signature alone is not enough. The relay has to check that the event is kind 22242, that the challenge is the one it issued on this very connection, that the relay tag matches its own address (the domain is what counts) and that created_at is close to the current time. The specification suggests about ten minutes. Skip one of these checks and you open the door to replayed or redirected authentication events.
Telling clients what they need to do
A relay that requires authentication must say so in a way clients can act on. Two prefixes are defined for the machine-readable part of a message:
auth-required:The client has not authenticated yet. The relay uses it inOK falsefor an EVENT and inCLOSEDfor a REQ. A client that sees it should authenticate and retry.restricted:The client is authenticated, but the key is not allowed to do this. Authenticating again will not help.
Mixing the two up is the most common mistake. A relay that answers an unauthenticated client with restricted: leaves it guessing; a relay that answers an authenticated but unauthorised client with auth-required: sends it into a loop.
Rejected requests must be rejected cleanly: a REQ that is not allowed gets a CLOSED message with the prefix, an EVENT that is not allowed gets OK with false and the prefix. A silent drop or a dropped connection is not an answer.
Declared versus real behaviour
The NIP-11 field limitation.auth_required is a promise (NIP-11 guide). Two things can go wrong:
- It says
true, but reads work without authentication. The relay is more open than it claims. - It says
falseor nothing, but the relay refuses everything until a client has authenticated. Clients that trust the document never even try.
The same applies to the list of supported NIPs. If 42 is in the list, the relay must send a challenge and accept a valid answer. If it is not, a relay that still sends challenges confuses clients that never asked for them.
What to test by hand
- Connect and wait for the challenge. Does one arrive? Is it different on every connection?
- Send a correct AUTH event. Expect
OK true. - Send AUTH events with a wrong challenge, a wrong
relaytag, a wrong kind, a timestamp an hour old and a broken signature. Each must be rejected. - Try to publish and to read without authenticating, then again after authenticating. Check the exact prefix in each rejection.
- Use a challenge from one connection on another. It must not work.
Running it with labs
The Conformance check of labs compares what your relay advertises with what it does, including auth_required and the NIP-42 entry in the supported NIPs. If your relay demands authentication, labs answers the challenge with a throwaway key generated for the test run, so the other checks can proceed. Every comparison shows the advertised value, the observed behaviour and a verdict.
A relay that stays closed even after authentication, for example a pure whitelist relay, refuses the test events. The check then stops and the amount is refunded. The call for a script is described in How to test a Nostr relay with one API call; the base protocol is covered in the NIP-01 guide.
FAQ
What is the difference between auth-required and restricted?
auth-required: means the client has not authenticated yet and should authenticate and retry. restricted: means the client is authenticated but not allowed, so retrying does not help.
What must the relay verify in an AUTH event?
Kind 22242, the challenge issued on this connection, the relay tag matching its own domain, a created_at close to the current time (about ten minutes is suggested) and the signature.
How should a relay reject a REQ that is not allowed?
With a CLOSED message that carries the prefix. A rejected EVENT gets OK false with the prefix. A silent drop is not an answer.
Where do I declare that authentication is required?
In the NIP-11 document, limitation.auth_required, and by listing 42 in supported_nips.
Can labs test a relay that requires authentication?
Yes. The Conformance test answers the challenge with a throwaway key. If the relay stays closed even then, the check stops and the amount is refunded.
