128 lines
No EOL
4.8 KiB
Markdown
128 lines
No EOL
4.8 KiB
Markdown
# 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. |