initial version

2025-08-05 23:48:43 +02:00 · 2025-08-05 23:48:43 +02:00 · 9a58dcc097
commit 9a58dcc097
10 changed files with 823 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,128 @@
+# NIP-42 Proxy
+
+This project is a NIP-42 proxy for Nostr relays. It provides an authentication layer in front of a public relay, allowing only authenticated users to connect and interact with it.
+
+## Features
+
+- **NIP-42 Authentication**: Enforces NIP-42 authentication, ensuring that only authorized users can access the relay.
+- **Proxy Layer**: Acts as a proxy, forwarding messages between authenticated clients and the main relay.
+- **Dynamic Whitelist**: Manage allowed public keys and event kinds dynamically through an admin RPC interface.
+- **Admin RPC Interface**: A NIP-98-protected RPC interface for administering the proxy.
+- **Docker Support**: Comes with a `Dockerfile` for easy deployment.
+- **Bun Support**: Can be run directly with `bun`.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) installed on your system.
+- [Docker](https://www.docker.com/) (optional) installed on your system.
+
+## Installation
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://git.arx-ccn.com/Arx/nip42-proxy.git
+   cd nip42-proxy
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   bun install
+   ```
+
+## Configuration
+
+The proxy is configured through environment variables.
+
+- `ALLOW_UNAUTHED_PUBLISH`: (Optional) Set to `true` to allow unauthenticated clients to publish events. Defaults to `false`.
+- `RELAY_URL`: The URL of the relay that the proxy will connect to.
+- `RELAY_OUTSIDE_URL`: (Optional) The URL that clients use to connect to the proxy. Defaults to the `RELAY_URL`.
+- `RELAY_NAME`: (Optional) The name of the relay.
+- `RELAY_DESCRIPTION`: (Optional) A description of the relay.
+- `RELAY_BANNER`: (Optional) A URL to a banner image for the relay.
+- `RELAY_ICON`: (Optional) A URL to an icon for the relay.
+- `RELAY_CONTACT`: (Optional) A contact email or address for the relay.
+- `RELAY_POLICY`: (Optional) A URL to the relay's policy document.
+- `ADMIN_PUBKEY`: (Optional) The public key of the administrator of the relay.
+
+## Usage
+
+### With Bun
+
+To run the proxy directly with Bun:
+
+```bash
+bun run index.ts
+```
+
+You can also set environment variables in the same command:
+
+```bash
+RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts
+```
+
+### With Docker
+
+To run the proxy using Docker, follow these steps:
+
+1. **Build the Docker image**:
+
+   ```bash
+   docker build -t nip42-proxy .
+   ```
+
+2. **Run the Docker container**:
+
+   ```bash
+   docker run -p 3000:3000 --name nip42-proxy nip42-proxy
+   ```
+
+   - This command maps port `3000` on your local machine to port `3000` in the container.
+
+   To run with a custom relay URL and other environment variables, use the `-e` flag:
+
+   ```bash
+   docker run -p 3000:3000 -e RELAY_URL="wss://your-relay-url.com" -e ADMIN_PUBKEY="my-admin-pubkey" --name nip42-proxy nip42-proxy
+   ```
+
+The server will start, and you can connect to it using a Nostr client that supports NIP-42 authentication.
+
+## Admin RPC Interface
+
+The proxy exposes a NIP-98-protected RPC interface for administration. To use it, you need to send a `POST` request to the root URL (`/`) with the `Content-Type` header set to `application/nostr+json+rpc`. The `Authorization` header must contain a NIP-98 token.
+
+**Available Methods:**
+
+- `supportedmethods`: Get a list of supported RPC methods.
+- `getinfo`: Get the relay's information document.
+- `banpubkey`: Ban a public key.
+- `allowpubkey`: Allow a public key.
+- `listallowedpubkeys`: List all allowed public keys.
+- `allowkind`: Allow a specific event kind.
+- `disallowkind`: Disallow a specific event kind.
+- `listallowedkinds`: List all allowed event kinds.
+
+**Example using `curl`:**
+
+```bash
+# First, generate a NIP-98 token. This is usually done with a Nostr library.
+# For this example, let's assume you have a valid token in the $TOKEN variable.
+
+# Get the list of allowed pubkeys
+curl -X POST -H "Content-Type: application/nostr+json+rpc" -H "Authorization: $TOKEN" -d '{"method": "listallowedpubkeys", "params": []}' http://localhost:3000/
+
+# Allow a new pubkey
+curl -X POST -H "Content-Type: application/nostr+json+rpc" -H "Authorization: $TOKEN" -d '{"method": "allowpubkey", "params": ["new-pubkey-to-allow"]}' http://localhost:3000/
+```
+
+## How It Works
+
+1. **Client Connection**: When a client connects to the proxy, it is initially in an unauthenticated state.
+2. **Authentication Request**: The proxy sends an `AUTH` challenge to the client.
+3. **Client Authentication**: The client must respond with a valid `AUTH` event, signed with an allowed public key.
+4. **Authenticated State**: Once authenticated, the client can send and receive messages from the main relay through the proxy.
+5. **Message Forwarding**: All messages from the authenticated client are forwarded to the main relay, and all messages from the main relay are forwarded to the client.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request with your improvements.