add challenge from relay.

2 files changed, 28 insertions, 10 deletions

diff --git a/42.md b/42.md
index 4c884a9..93bb3e3 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 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", <challenge-string>]
+```
 
-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:
+And, when sent by clients, of the following form:
 
 ```
-["AUTH", <signed-event>]
+["AUTH", <signed-event-json>]
 ```
 
-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:
+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", <event-id>, 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 f627f4d..05737b1 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.