Arx/nip42-proxy
Arx/nip42-proxy
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

improve readme and add license

Browse source
This commit is contained in:
Danny Morabito 2025-08-10 21:27:02 +02:00
parent 9a58dcc097
commit 4ec7208a27
Signed by: dannym
GPG key ID: 7CC8056A5A04557E
3 changed files with 749 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

181
README.md
View file

@ -1,128 +1,123 @@
# NIP-42 Proxy
<table>
<tr>
<td><img src="images/logo.webp" alt="NIP-42 Proxy Logo" width="200"/></td>
<td>
<h1>NIP-42 Proxy</h1>
<p>A simple, no-fuss NIP-42 authentication proxy for your Nostr relay.</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>
</td>
</tr>
</table>
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
Ever wanted to run a private Nostr relay without all the hassle? This NIP-42 proxy is your answer. It sits in front of your relay and makes sure only the right people can get in. Simple as that.
- **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`.
## ✨ What's Inside?
## Prerequisites
- **NIP-42 Auth:** Keep your relay safe and sound with NIP-42 authentication.
- **Proxy Power:** It's a straightforward proxy that forwards messages between your users and the relay.
- **Whitelist Control:** Easily manage who gets in and what they can do with a dynamic whitelist.
- **Admin Interface:** A handy RPC interface (protected by NIP-98) to manage your proxy.
- **Docker-Ready:** Comes with a `Dockerfile`, so you can get it up and running in a flash.
- **Bun-Powered:** Built with Bun for a fast and modern experience.
- [Bun](https://bun.sh/) installed on your system.
- [Docker](https://www.docker.com/) (optional) installed on your system.
## 🚀 Get Going
## Installation
### What You'll Need
1. **Clone the repository**:
- [Bun](https://bun.sh/)
- [Docker](https://www.docker.com/) (if you're into that)
```bash
git clone https://git.arx-ccn.com/Arx/nip42-proxy.git
cd nip42-proxy
```
### Let's Do This
2. **Install dependencies**:
```bash
bun install
```
1. **Clone the code:**
## Configuration
```bash
git clone https://git.arx-ccn.com/Arx/nip42-proxy.git
cd nip42-proxy
```
The proxy is configured through environment variables.
2. **Install the things:**
- `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.
```bash
bun install
```
## Usage
3. **Fire it up:**
- **With Bun:**
### With Bun
```bash
RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts
```
To run the proxy directly with Bun:
- **With Docker:**
1. Build it:
```bash
bun run index.ts
```
```bash
docker build -t nip42-proxy .
```
You can also set environment variables in the same command:
2. Run it:
```bash
RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts
```
```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
```
### With Docker
Now you can connect to your proxy with any Nostr client that gets NIP-42.
To run the proxy using Docker, follow these steps:
## ⚙️ Tweaks and Knobs
1. **Build the Docker image**:
This proxy is configured with environment variables. Here's the rundown:
```bash
docker build -t nip42-proxy .
```
<details>
<summary>Click to see all the options</summary>
2. **Run the Docker container**:
| Variable | What it does | Default |
| ------------------------ | ----------------------------------------- | ----------- |
| `ALLOW_UNAUTHED_PUBLISH` | Let unauthenticated users publish events. | `false` |
| `RELAY_URL` | The URL of the relay you're proxying. | |
| `RELAY_OUTSIDE_URL` | The URL your users will connect to. | `RELAY_URL` |
| `RELAY_NAME` | The name of your relay. | |
| `RELAY_DESCRIPTION` | A little something about your relay. | |
| `RELAY_BANNER` | A URL for a banner image. | |
| `RELAY_ICON` | A URL for an icon. | |
| `RELAY_CONTACT` | How people can get in touch. | |
| `RELAY_POLICY` | A URL to your relay's policy. | |
| `ADMIN_PUBKEY` | The public key of the relay's admin. | |
```bash
docker run -p 3000:3000 --name nip42-proxy nip42-proxy
```
</details>
- This command maps port `3000` on your local machine to port `3000` in the container.
## 🔧 The Admin Zone
To run with a custom relay URL and other environment variables, use the `-e` flag:
The proxy has a special RPC interface for admins, protected by NIP-98. Just send a `POST` request to the root URL (`/`) with the right headers (`Content-Type: application/nostr+json+rpc` and a NIP-98 `Authorization` token).
```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
```
**What you can do:**
The server will start, and you can connect to it using a Nostr client that supports NIP-42 authentication.
- `supportedmethods`: See what commands are available.
- `getinfo`: Get the relay's info doc.
- `banpubkey`: Kick someone out.
- `allowpubkey`: Let someone in.
- `listallowedpubkeys`: See who's on the list.
- `allowkind`: Allow a certain kind of event.
- `disallowkind`: Block a certain kind of event.
- `listallowedkinds`: See what kinds are allowed.
## Admin RPC Interface
## 🤔 How's It Work?
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.
1. **Knock Knock:** A client connects, but they're just a guest for now.
2. **Who's There?:** The proxy asks for their credentials with an `AUTH` challenge.
3. **The Password:** The client sends back a valid `AUTH` event, signed with a key that's on the list.
4. **You're In:** The client is now authenticated and can chat with the relay.
5. **The Conversation:** Messages flow freely between the client and the relay.
**Available Methods:**
## 🤝 Wanna Help?
- `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.
Got ideas? Found a bug? Pull requests and issues are always welcome.
**Example using `curl`:**
## 📄 The Fine Print
```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.
This project is licensed under the AGPLv3. Check out the [LICENSE](LICENSE) file for the full text.
# 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.