mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-11-09 22:09:06 -05:00
69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
NIP-42
|
|
======
|
|
|
|
Authentication of clients to relays
|
|
-----------------------------------
|
|
|
|
`draft` `optional` `author:Semisol` `author:fiatjaf`
|
|
|
|
This NIP defines a way for clients to authenticate to relays by signing an ephemeral event.
|
|
|
|
## Motivation
|
|
|
|
A relay may want to require clients to authenticate to access restricted resources. For example,
|
|
|
|
- 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;
|
|
- 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.
|
|
- A relay may limit subscriptions of any kind to paying users or users whitelisted through any other means, and require authentication.
|
|
|
|
## Protocol flow
|
|
|
|
This NIP defines a new message, `AUTH`, which clients can send to relays when they want to authenticate. The message is of the following form:
|
|
|
|
```
|
|
["AUTH", <signed-event>]
|
|
```
|
|
|
|
The signed event is an ephemeral event not meant to be published or queried, it must be of `kind: 22242` and content must be set to the
|
|
WebSocket URL of the relay. `created_at` should be the current time. Example:
|
|
|
|
```json
|
|
{
|
|
"id": "...",
|
|
"pubkey": "...",
|
|
"created_at": 1669695536,
|
|
"kind": 22242,
|
|
"tags": [],
|
|
"content": "wss://relay.example.com/",
|
|
"sig": "..."
|
|
}
|
|
```
|
|
|
|
The client may send an auth message right before performing an action for which it knows authentication will be required -- for example, right
|
|
before requesting `kind: 4` chat messages --, or it may do right on connection start or at some other moment it deems best.
|
|
|
|
Upon receiving a message from an unauthenticated user it can't fulfill without authentication, a relay may choose to notify the client. For
|
|
that it can use a `NOTICE` message with a standard prefix `"restricted: "` that is readable both by humans and machines, for example:
|
|
|
|
```
|
|
["NOTICE", "restricted: we can't serve DMs to unauthenticated users, does your client implement NIP-42?"]
|
|
```
|
|
|
|
or it can return an `OK` message noting the reason an event was not written using the same prefix:
|
|
|
|
```
|
|
["OK", "b1a649ebe8...", false, "restricted: we do not accept events from unauthenticated users, please sign up at https://example.com/"]
|
|
```
|
|
|
|
## Signed Event Verification
|
|
|
|
To verify `AUTH` messages, relays must ensure:
|
|
|
|
- that the `kind` is `22242`
|
|
- that the event was recently signed (~10 minutes, by `created_at`)
|
|
- that the `content` field matches the relay URL
|
|
- URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough.
|