CLOSED messages for relays that want to reject REQs and NIP-42 AUTH integration

01.md

@@ -145,6 +145,7 @@ Relays can send 4 types of messages, which must also be JSON arrays, according t
   * `["EVENT", <subscription_id>, <event JSON as defined above>]`, used to send events requested by clients.
   * `["OK", <event_id>, <true|false>, <message>]`, used to indicate acceptance or denial of an `EVENT` message.
   * `["EOSE", <subscription_id>]`, used to indicate the _end of stored events_ and the beginning of events newly received in real-time.
+  * `["CLOSED", <subscription_id>, <message>]`, used to indicate that a subscription was ended on the server side.
   * `["NOTICE", <message>]`, used to send human-readable error messages or other things to clients.
 
 This NIP defines no rules for how `NOTICE` messages should be sent or treated.
@@ -161,3 +162,9 @@ This NIP defines no rules for how `NOTICE` messages should be sent or treated.
   * `["OK", "b1a649ebe8...", false, "invalid: event creation date is too far off from the current time. Is your system clock in sync?"]`
   * `["OK", "b1a649ebe8...", false, "pow: difficulty 26 is less than 30"]`
   * `["OK", "b1a649ebe8...", false, "error: could not connect to the database"]`
+- `CLOSED` messages MUST be sent when the relay in response to a `REQ` when the relay refuses to fulfill it. It can also be sent when a relay decides to kill a subscription on its side before a client has disconnected or sent a `CLOSE`. This message uses the same pattern of `OK` messages with the machine-readable prefix and human-readable message. The standardized machine-readable prefixes are: `duplicate`, `unsupported` and `error` for when none of that fits. Some examples:
+
+  * `["CLOSED", "sub1", "duplicate: sub1 already opened"]`
+  * `["CLOSED", "sub1", "unsupported: filter contains unknown elements"]`
+  * `["CLOSED", "sub1", "error: could not connect to the database"]`
+  * `["CLOSED", "sub1", "error: shutting down idle subscription"]`

42.md

@@ -21,6 +21,8 @@ A relay may want to require clients to authenticate to access restricted resourc
 
 ## Definitions
 
+### 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:
 
@@ -34,6 +36,10 @@ And, when sent by clients, of the following form:
 ["AUTH", <signed-event-json>]
 ```
 
+`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.
@@ -50,27 +56,56 @@ 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.
+
 ## 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 be valid for the duration of
+the connection or until a next 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.
+
+### `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:
 
 ```json
-["OK", <event-id>, false, "restricted: we do not accept events from unauthenticated users, please sign up at https://example.com/"]
+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

README.md

@@ -171,6 +171,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 | `EVENT`  | used to send events requested to clients                | [01](01.md) |
 | `NOTICE` | used to send human-readable messages to clients         | [01](01.md) |
 | `OK`     | used to notify clients if an EVENT was successful       | [01](01.md) |
+| `CLOSED` | used to notify clients that a REQ was ended and why     | [01](01.md) |
 | `AUTH`   | used to send authentication challenges                  | [42](42.md) |
 | `COUNT`  | used to send requested event counts to clients          | [45](45.md) |