improve readme and add license
This commit is contained in:
parent
9a58dcc097
commit
95540fff69
GPG key ID:
7CC8056A5A04557E
2 changed files with 736 additions and 84 deletions
159
README.md
159
README.md
|
|
@ -1,95 +1,94 @@
|
|||
# NIP-42 Proxy
|
||||
<div align="center">
|
||||
<img src="images/logo.webp" alt="NIP-42 Proxy Logo" width="200"/>
|
||||
<h1>NIP-42 Proxy</h1>
|
||||
<p>A NIP-42 authentication proxy for Nostr relays.</p>
|
||||
<p>
|
||||
<a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL_v3-blue.svg" alt="License: AGPL v3"></a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
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
|
||||
This project provides a robust NIP-42 proxy for Nostr relays, creating an authentication layer to ensure only authorized users can connect and interact with a public relay.
|
||||
|
||||
- **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`.
|
||||
## ✨ Features
|
||||
|
||||
## Prerequisites
|
||||
- **NIP-42 Authentication**: Enforces NIP-42 authentication, securing your relay from unauthorized access.
|
||||
- **Proxy Layer**: Seamlessly forwards messages between authenticated clients and the main relay.
|
||||
- **Dynamic Whitelist**: Manage allowed public keys and event kinds on-the-fly via an admin RPC interface.
|
||||
- **Admin RPC Interface**: A NIP-98-protected RPC interface for easy administration.
|
||||
- **Containerized**: Comes with a `Dockerfile` for easy and consistent deployment.
|
||||
- **Fast & Modern**: Built with Bun for optimal performance.
|
||||
|
||||
- [Bun](https://bun.sh/) installed on your system.
|
||||
- [Docker](https://www.docker.com/) (optional) installed on your system.
|
||||
## 🚀 Getting Started
|
||||
|
||||
## Installation
|
||||
### Prerequisites
|
||||
|
||||
1. **Clone the repository**:
|
||||
- [Bun](https://bun.sh/)
|
||||
- [Docker](https://www.docker.com/) (Optional)
|
||||
|
||||
### Installation & Running
|
||||
|
||||
1. **Clone the repository:**
|
||||
|
||||
```bash
|
||||
git clone https://git.arx-ccn.com/Arx/nip42-proxy.git
|
||||
cd nip42-proxy
|
||||
```
|
||||
|
||||
2. **Install dependencies**:
|
||||
2. **Install dependencies:**
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
## Configuration
|
||||
3. **Run the proxy:**
|
||||
- **With Bun:**
|
||||
|
||||
The proxy is configured through environment variables.
|
||||
```bash
|
||||
RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts
|
||||
```
|
||||
|
||||
- `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.
|
||||
- **With Docker:**
|
||||
1. Build the image:
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
docker build -t nip42-proxy .
|
||||
```
|
||||
|
||||
### With Bun
|
||||
2. Run the container:
|
||||
|
||||
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
|
||||
```
|
||||
```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
|
||||
## ⚙️ Configuration
|
||||
|
||||
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.
|
||||
The proxy is configured through environment variables.
|
||||
|
||||
<details>
|
||||
<summary>Click to view all configuration options</summary>
|
||||
|
||||
| Variable | Description | Default |
|
||||
| ------------------------ | ----------------------------------------------------------------- | ----------- |
|
||||
| `ALLOW_UNAUTHED_PUBLISH` | Set to `true` to allow unauthenticated clients to publish events. | `false` |
|
||||
| `RELAY_URL` | The URL of the relay that the proxy will connect to. | |
|
||||
| `RELAY_OUTSIDE_URL` | The URL that clients use to connect to the proxy. | `RELAY_URL` |
|
||||
| `RELAY_NAME` | The name of the relay. | |
|
||||
| `RELAY_DESCRIPTION` | A description of the relay. | |
|
||||
| `RELAY_BANNER` | A URL to a banner image for the relay. | |
|
||||
| `RELAY_ICON` | A URL to an icon for the relay. | |
|
||||
| `RELAY_CONTACT` | A contact email or address for the relay. | |
|
||||
| `RELAY_POLICY` | A URL to the relay's policy document. | |
|
||||
| `ADMIN_PUBKEY` | The public key of the administrator of the relay. | |
|
||||
|
||||
</details>
|
||||
|
||||
## 🔧 Admin RPC Interface
|
||||
|
||||
The proxy exposes a NIP-98-protected RPC interface for administration. Send a `POST` request to the root URL (`/`) with `Content-Type: application/nostr+json+rpc` and a NIP-98 token in the `Authorization` header.
|
||||
|
||||
**Available Methods:**
|
||||
|
||||
|
|
@ -102,27 +101,19 @@ The proxy exposes a NIP-98-protected RPC interface for administration. To use it
|
|||
- `disallowkind`: Disallow a specific event kind.
|
||||
- `listallowedkinds`: List all allowed event kinds.
|
||||
|
||||
**Example using `curl`:**
|
||||
## 🤔 How It Works
|
||||
|
||||
```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.
|
||||
1. **Client Connection**: A client connects to the proxy and is initially unauthenticated.
|
||||
2. **Authentication Request**: The proxy sends an `AUTH` challenge.
|
||||
3. **Client Authentication**: The client responds with a valid `AUTH` event, signed with an allowed public key.
|
||||
4. **Authenticated State**: The client is now authenticated and can interact with the relay.
|
||||
5. **Message Forwarding**: Messages are forwarded between the client and the main relay.
|
||||
|
||||
# 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/
|
||||
## 🤝 Contributing
|
||||
|
||||
# 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/
|
||||
```
|
||||
Contributions are welcome! Please open an issue or submit a pull request with your improvements.
|
||||
|
||||
## How It Works
|
||||
## 📄 License
|
||||
|
||||
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.
|
||||
This project is licensed under the AGPLv3. See the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please open an issue or submit a pull request with your improvements.
|
||||
Loading…
Add table
Add a link
Reference in a new issue