feat: gRPC authorization for events

closes: https://todo.sr.ht/~gheartsfield/nostr-rs-relay/46
2023-02-11 13:26:08 -06:00
parent e63d179424
commit a16c4e698a
17 changed files with 1522 additions and 8 deletions
@@ -0,0 +1,79 @@
+# gRPC Extensions Design Document
+
+The relay will be extensible through gRPC endpoints, definable in the
+main configuration file.  These will allow external programs to host
+logic for deciding things such as, should this event be persisted,
+should this connection be allowed, and should this subscription
+request be registered.  The primary goal is allow for relay operator
+specific functionality that allows them to serve smaller communities
+and reduce spam and abuse.
+
+This will likely evolve substantially, the first goal is to get a
+basic one-way service that lets an externalized program decide on
+event persistance.  This does not represent the final state of gRPC
+extensibility in `nostr-rs-relay`.
+
+## Considerations
+
+Write event latency must not be significantly affected.  However, the
+primary reason we are implementing this is spam/abuse protection, so
+we are willing to tolerate some increase in latency if that protects
+us against outages!
+
+The interface should provide enough information to make simple
+decisions, without burdening the relay to do extra queries.  The
+decision endpoint will be mostly responsible for maintaining state and
+gathering additional details.
+
+## Design Overview
+
+A gRPC server may be defined in the `config.toml` file.  If it exists,
+the relay will attempt to connect to it and send a message for each
+`EVENT` command submitted by clients.  If a successful response is
+returned indicating the event is permitted, the relay continues
+processing the event as normal.  All existing whitelist, blacklist,
+and `NIP-05` validation checks are still performed and MAY still
+result in the event being rejected.  If a successful response is
+returned indicated the decision is anything other than permit, then
+the relay MUST reject the event, and return a command result to the
+user (using `NIP-20`) indicating the event was blocked (optionally
+providing a message).
+
+In the event there is an error in the gRPC interface, event processing
+proceeds as if gRPC was disabled (fail open).  This allows gRPC
+servers to be deployed with minimal chance of causing a full relay
+outage.
+
+## Design Details
+
+Currently one procedure call is supported, `EventAdmit`, in the
+`Authorization` service.  It accepts the following data in order to
+support authorization decisions:
+
+- The event itself
+- The client IP that submitted the event
+- The client's HTTP origin header, if one exists
+- The client's HTTP user agent header, if one exists
+- The public key of the client, if `NIP-42` authentication was
+  performed (not supported in the relay yet!)
+- The `NIP-05` associated with the event's public key, if it is known
+  to the relay
+
+A server providing authorization decisions will return the following:
+
+- A decision to permit or deny the event
+- An optional message that explains why the event was denied, to be
+  transmitted to the client
+
+## Security Issues
+
+There is little attempt to secure this interface, since it is intended
+for use processes running on the same host.  It is recommended to
+ensure that the gRPC server providing the API is not exposed to the
+public Internet.  Authorization server implementations should have
+their own security reviews performed.
+
+A slow gRPC server could cause availability issues for event
+processing, since this is performed on a single thread.  Avoid any
+expensive or long-running processes that could result from submitted
+events, since any client can initiate a gRPC call to the service.