{"id":"abb3faded7bec5dbab7ca2d6944a8bf906a0da04ca6e158cfd6bb558e3569547","pubkey":"b22b06b051fd5232966a9344a634d956c3dc33a7f5ecdcad9ed11ddc4120a7f2","created_at":1786111274,"kind":30817,"tags":[["d","nip-42"],["title","NIP-42"],["alt","Nostr Implementation Possibility: NIP-42"],["i","https://github.com/nostr-protocol/nips/blob/master/42.md","fork"],["client","NostrHub"]],"content":"NIP-42\n======\n\nAuthentication of clients to relays\n-----------------------------------\n\n`draft` `optional` `relay`\n\nThis NIP defines a way for clients to authenticate to relays by signing an ephemeral event.\n\n## Motivation\n\nA relay may want to require clients to authenticate to access restricted resources. For example,\n\n  - A relay may request payment or other forms of whitelisting to publish events -- this can naïvely be achieved by limiting publication to events signed by the whitelisted key, but with this NIP they may choose to accept any events as long as they are published from an authenticated user;\n  - A relay may limit access to `kind: 4` DMs to only the parties involved in the chat exchange, and for that it may require authentication before clients can query for that kind.\n  - A relay may limit subscriptions of any kind to paying users or users whitelisted through any other means, and require authentication.\n\n## Definitions\n\n### New client-relay protocol messages\n\nThis NIP defines a new message, `AUTH`, which relays CAN send when they support authentication and clients can send to relays when they want to authenticate. When sent by relays the message has the following form:\n\n```\n[\"AUTH\", <challenge-string>]\n```\n\nAnd, when sent by clients, the following form:\n\n```\n[\"AUTH\", <signed-event-json>]\n```\n\nClients MAY provide signed events from multiple pubkeys in a sequence of `AUTH` messages. Relays MUST treat all pubkeys as authenticated accordingly.\n\n`AUTH` messages sent by clients MUST be answered with an `OK` message, like any `EVENT` message.\n\n### Canonical authentication event\n\nThe signed event is an ephemeral event not meant to be published or queried, it must be of `kind: 22242` and it should have at least two tags, one for the relay URL and one for the challenge string as received from the relay. Relays MUST exclude `kind: 22242` events from being broadcasted to any client. `created_at` should be the current time. Example:\n\n```yaml\n{\n  \"kind\": 22242,\n  \"tags\": [\n    [\"relay\", \"wss://relay.example.com/\"],\n    [\"challenge\", \"challengestringhere\"]\n  ],\n  // other fields...\n}\n```\n\n### `OK` and `CLOSED` machine-readable prefixes\n\nThis NIP defines two new prefixes that can be used in `OK` (in response to event writes by clients) and `CLOSED` (in response to rejected subscriptions by clients). Which of the two applies is determined by whether a further `AUTH` could change the outcome:\n\n- `\"auth-required: \"` - for when the relay requires an `AUTH` that hasn't been performed yet in order to fulfill the query or write the event. This includes the case of a client that has already authenticated one or more pubkeys but none that is allowed to perform this specific request, since authenticating an additional pubkey may still make the relay fulfill it.\n- `\"restricted: \"` - for when authenticating more pubkeys wouldn't help: the pubkeys that have already performed `AUTH` are not allowed by the relay or are exceeding their authorization, and no additional `AUTH` would change the outcome.\n\n## Protocol flow\n\nAt any moment the relay may send an `AUTH` message to the client containing a challenge. The challenge is valid for the duration of the connection or until another challenge is sent by the relay. The client MAY decide to send its `AUTH` event at any point and the authenticated session is valid afterwards for the duration of the connection.\n\n### `auth-required` in response to a `REQ` message\n\nGiven that a relay is likely to require clients to perform authentication only for certain jobs, like answering a `REQ` or accepting an `EVENT` write, these are some expected common flows:\n\n```\nrelay: [\"AUTH\", \"<challenge>\"]\nclient: [\"REQ\", \"sub_1\", {\"kinds\": [4]}]\nrelay: [\"CLOSED\", \"sub_1\", \"auth-required: we can't serve DMs to unauthenticated users\"]\nclient: [\"AUTH\", {\"id\": \"abcdef...\", ...}]\nclient: [\"AUTH\", {\"id\": \"abcde2...\", ...}]\nrelay: [\"OK\", \"abcdef...\", true, \"\"]\nrelay: [\"OK\", \"abcde2...\", true, \"\"]\nclient: [\"REQ\", \"sub_1\", {\"kinds\": [4]}]\nrelay: [\"EVENT\", \"sub_1\", {...}]\nrelay: [\"EVENT\", \"sub_1\", {...}]\nrelay: [\"EVENT\", \"sub_1\", {...}]\nrelay: [\"EVENT\", \"sub_1\", {...}]\n...\n```\n\nIn this case, the `AUTH` message from the relay could be sent right as the client connects or it can be sent immediately before the `CLOSED` is sent. The only requirement is that _the client must have a stored challenge associated with that relay_ so it can act upon that in response to the `auth-required` `CLOSED` message.\n\n### `auth-required` when a pubkey is missing\n\nSince multiple pubkeys can be authenticated on the same connection, a client may be authenticated and still be missing the pubkey a given request needs. The relay asks for that pubkey with the same prefix:\n\n```\nrelay: [\"AUTH\", \"<challenge>\"]\nclient: [\"AUTH\", {\"id\": \"abcdef...\", ...}]\nrelay: [\"OK\", \"abcdef...\", true, \"\"]\nclient: [\"REQ\", \"sub_1\", {\"authors\": [\"<pubkey-b>\"]}]\nrelay: [\"CLOSED\", \"sub_1\", \"auth-required: not authenticated as <pubkey-b>\"]\nclient: [\"AUTH\", {\"id\": \"abcde2...\", ...}]\nrelay: [\"OK\", \"abcde2...\", true, \"\"]\nclient: [\"REQ\", \"sub_1\", {\"authors\": [\"<pubkey-b>\"]}]\nrelay: [\"EVENT\", \"sub_1\", {...}]\n...\n```\n\nHere the first `AUTH` authenticates some `<pubkey-a>` and the second one authenticates `<pubkey-b>`, both against the same challenge. A relay that answered `restricted:` instead would be telling the client that signing with `<pubkey-b>` is pointless, which is not the case.\n\n### `auth-required` in response to an `EVENT` message\n\nThe same flow is valid for when a client wants to write an `EVENT` to the relay, except now the relay sends back an `OK` message instead of a `CLOSED` message:\n\n```\nrelay: [\"AUTH\", \"<challenge>\"]\nclient: [\"EVENT\", {\"id\": \"012345...\", ...}]\nrelay: [\"OK\", \"012345...\", false, \"auth-required: we only accept events from registered users\"]\nclient: [\"AUTH\", {\"id\": \"abcdef...\", ...}]\nrelay: [\"OK\", \"abcdef...\", true, \"\"]\nclient: [\"EVENT\", {\"id\": \"012345...\", ...}]\nrelay: [\"OK\", \"012345...\", true, \"\"]\n```\n\n## Signed Event Verification\n\nTo verify `AUTH` messages, relays must ensure:\n\n  - that the `kind` is `22242`;\n  - that the event `created_at` is close (e.g. within ~10 minutes) of the current time;\n  - that the `\"challenge\"` tag matches the challenge sent before;\n  - that the `\"relay\"` tag matches the relay URL:\n    - URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough.","sig":"66f2f4040a68bfe534dd5f452b8092ea7ba4f89f493ce6cda202922c7ceaf42e8df9746b42338dfde2ed22aad51d95854c718abf8912555b087cf69c896b60ce"}