From 6a70967f0eb6e7b00fc811e34631f8db046d6e1f Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Sat, 7 Jan 2023 19:53:42 -0300 Subject: [PATCH] add challenge from relay. --- 42.md | 37 +++++++++++++++++++++++++++---------- README.md | 1 + 2 files changed, 28 insertions(+), 10 deletions(-) diff --git a/42.md b/42.md index 4c884a9a..93bb3e39 100644 --- a/42.md +++ b/42.md @@ -19,16 +19,23 @@ A relay may want to require clients to authenticate to access restricted resourc 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 +## Definitions -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: +This 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 is of the following form: ``` -["AUTH", ] +["AUTH", ] ``` -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: +And, when sent by clients, of the following form: + +``` +["AUTH", ] +``` + +The 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. `created_at` should be the current time. Example: ```json { @@ -36,18 +43,27 @@ WebSocket URL of the relay. `created_at` should be the current time. Example: "pubkey": "...", "created_at": 1669695536, "kind": 22242, - "tags": [], - "content": "wss://relay.example.com/", + "tags": [ + ["relay", "wss://relay.example.com/"], + ["challenge", "challengestringhere"] + ], + "content": "", "sig": "..." } ``` +## Protocol flow + +At any moment the relay may send an `AUTH` message to the client containing a challenge. After receiving that the client may decide to +authenticate itself or not. The challenge is expected to be valid for the duration of the connection or until a next challenge is sent by +the relay. + 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. The authentication is expected to last for the duration of the WebSocket connection. 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: +that it can use a `NOTICE` or `OK` 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?"] @@ -56,7 +72,7 @@ that it can use a `NOTICE` message with a standard prefix `"restricted: "` that 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/"] +["OK", , false, "restricted: we do not accept events from unauthenticated users, please sign up at https://example.com/"] ``` ## Signed Event Verification @@ -65,5 +81,6 @@ To verify `AUTH` messages, relays must ensure: - that the `kind` is `22242`; - that the event `created_at` is close (e.g. within ~10 minutes) of the current time; - - that the `content` field matches the relay URL: + - that the `"challenge"` tag matches the challenge sent before; + - that the `"relay"` tag matches the relay URL: - URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough. diff --git a/README.md b/README.md index f627f4d1..05737b19 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh | NOTICE | used to send human-readable messages to clients | [1](01.md) | | EOSE | used to notify clients all stored events have been sent | [15](15.md) | | OK | used to notify clients if an EVENT was successuful | [20](20.md) | +| AUTH | used to send authentication challenges | [42](42.md) | Please update these lists when proposing NIPs introducing new event kinds.