diff --git a/README.md b/README.md index 7248416..317d088 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,10 @@ NIP-42 Proxy Logo

NIP-42 Proxy

-

A NIP-42 authentication proxy for Nostr relays.

+

A simple, no-fuss NIP-42 authentication proxy for your Nostr relay.

+ Docker Pulls + Bun License: AGPL v3

@@ -13,111 +15,105 @@ --- -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. +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. -## ✨ Features +## ✨ What's Inside? -- **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. +- **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. -## 🚀 Getting Started +## 🚀 Get Going -### Prerequisites +### What You'll Need - [Bun](https://bun.sh/) -- [Docker](https://www.docker.com/) (Optional) +- [Docker](https://www.docker.com/) (if you're into that) -### Installation & Running +### Let's Do This -1. **Clone the repository:** +1. **Clone the code:** + ```bash + git clone https://git.arx-ccn.com/Arx/nip42-proxy.git + cd nip42-proxy + ``` - ```bash - git clone https://git.arx-ccn.com/Arx/nip42-proxy.git - cd nip42-proxy - ``` +2. **Install the things:** + ```bash + bun install + ``` -2. **Install dependencies:** - - ```bash - bun install - ``` - -3. **Run the proxy:** - - **With Bun:** - - ```bash - RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts - ``` - - - **With Docker:** - 1. Build the image: +3. **Fire it up:** + * **With Bun:** ```bash - docker build -t nip42-proxy . + RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts ``` - 2. Run the container: + * **With Docker:** + 1. Build it: + ```bash + docker build -t nip42-proxy . + ``` + 2. Run it: + ```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 - ``` +Now you can connect to your proxy with any Nostr client that gets NIP-42. -The server will start, and you can connect to it using a Nostr client that supports NIP-42 authentication. +## ⚙️ Tweaks and Knobs -## ⚙️ Configuration - -The proxy is configured through environment variables. +This proxy is configured with environment variables. Here's the rundown:
- Click to view all configuration options + Click to see all the options -| 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. | | + | 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. | |
-## 🔧 Admin RPC Interface +## 🔧 The Admin Zone -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. +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). -**Available Methods:** +**What you can do:** -- `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. +- `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. -## 🤔 How It Works +## 🤔 How's It Work? -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. +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. -## 🤝 Contributing +## 🤝 Wanna Help? -Contributions are welcome! Please open an issue or submit a pull request with your improvements. +Got ideas? Found a bug? Pull requests and issues are always welcome. -## 📄 License - -This project is licensed under the AGPLv3. See the [LICENSE](LICENSE) file for details. +## 📄 The Fine Print +This project is licensed under the AGPLv3. Check out the [LICENSE](LICENSE) file for the full text. \ No newline at end of file