`CLOSED` messages for relays that want to reject REQs and NIP-42 `AUTH` integration (#902)

Co-authored-by: monlovesmango <96307647+monlovesmango@users.noreply.github.com>

1 files changed, 45 insertions, 24 deletions

diff --git a/42.md b/42.md
index e380e89..07a0486 100644
--- a/42.md
+++ b/42.md
@@ -12,17 +12,15 @@ This NIP defines a way for clients to authenticate to relays by signing an ephem
 
 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 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.
 
 ## 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:
+### New client-relay protocol messages
+
+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:
 
 ```json
 ["AUTH", <challenge-string>]
@@ -34,10 +32,11 @@ And, when sent by clients, of the following form:
 ["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 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:
+`AUTH` messages sent by clients should be answered with an `OK` message, like any `EVENT` message.
+
+### Canonical authentication event
+
+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. Relays MUST exclude `kind: 22242` events from being broadcasted to any client. `created_at` should be the current time. Example:
 
 ```json
 {
@@ -50,27 +49,49 @@ Relays MUST exclude `kind: 22242` events from being broadcasted to any client.
 }
 ```
 
+### `OK` and `CLOSED` machine-readable prefixes
+
+This 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):
+
+- `"auth-required: "` - for when a client has not performed `AUTH` and the relay requires that to fulfill the query or write the event.
+- `"restricted: "` - for when a client has already performed `AUTH` but the key used to perform it is still not allowed by the relay or is exceeding its authorization.
+
 ## 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.
+At 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.
 
-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.
+### `auth-required` in response to a `REQ` message
 
-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` or `OK` message with a standard prefix `"restricted: "` that is readable both by humans and machines, for example:
+Given 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:
 
-```json
-["NOTICE", "restricted: we can't serve DMs to unauthenticated users, does your client implement NIP-42?"]
+```
+relay: ["AUTH", "<challenge>"]
+client: ["REQ", "sub_1", {"kinds": [4]}]
+relay: ["CLOSED", "sub_1", "auth-required: we can't serve DMs to unauthenticated users"]
+client: ["AUTH", {"id": "abcdef...", ...}]
+relay: ["OK", "abcdef...", true, ""]
+client: ["REQ", "sub_1", {"kinds": [4]}]
+relay: ["EVENT", "sub_1", {...}]
+relay: ["EVENT", "sub_1", {...}]
+relay: ["EVENT", "sub_1", {...}]
+relay: ["EVENT", "sub_1", {...}]
+...
 ```
 
-or it can return an `OK` message noting the reason an event was not written using the same prefix:
+In 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.
 
-```json
-["OK", <event-id>, false, "restricted: we do not accept events from unauthenticated users, please sign up at https://example.com/"]
+### `auth-required` in response to an `EVENT` message
+
+The 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:
+
+```
+relay: ["AUTH", "<challenge>"]
+client: ["EVENT", {"id": "012345...", ...}]
+relay: ["OK", "012345...", false, "auth-required: we only accept events from registered users"]
+client: ["AUTH", {"id": "abcdef...", ...}]
+relay: ["OK", "abcdef...", true, ""]
+client: ["EVENT", {"id": "012345...", ...}]
+relay: ["OK", "012345...", true, ""]
 ```
 
 ## Signed Event Verification