relayted blog

NIP guide

NIP-42 for relay operators: authentication that clients can work with

labsPublished 3 min read
NIP-42 for relay operators: authentication that clients can work with

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:

  1. The relay sends ["AUTH", "<challenge>"] to the client, usually right after the connection opens.
  2. The client answers with ["AUTH", <event>]. The event is signed with the key it wants to prove, has kind 22242 and carries two tags: relay (the relay's URL) and challenge (the string it received). It is never stored or broadcast.
  3. 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:

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:

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

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.