initial version

README.md

@@ -0,0 +1,97 @@
+# 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.
+- **Whitelist**: Filters access based on a whitelist of public keys defined in `allowed-pubkeys.json`.
+
+## Prerequisites
+
+- [Docker](https://www.docker.com/) installed on your system.
+
+## Installation
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://git.arx-ccn.com/Arx/nip42-proxy.git
+   cd nip42-proxy
+   ```
+
+## Configuration
+
+1. **Whitelist (Optional)**:
+   - Create a file named `allowed-pubkeys.json` in the root directory.
+   - Add an array of whitelisted public keys in the following format:
+
+     ```json
+     ["pubkey1", "pubkey2"]
+     ```
+
+   - If this file does not exist, the proxy will allow any user to authenticate.
+
+2. **Relay URL**:
+   - The proxy can be configured to connect to a specific relay using one of the following methods (in order of priority):
+     1. **Environment Variable**: Set the `RELAY_URL` environment variable when running the Docker container:
+
+        ```bash
+        docker run -e RELAY_URL="wss://your-relay-url.com" ...
+        ```
+
+     2. **Default**: If no URL is provided, the proxy will connect to the default relay: `wss://relay.arx-ccn.com`.
+
+## 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
+
+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 -v $(pwd)/allowed-pubkeys.json:/app/allowed-pubkeys.json --name nip42-proxy nip42-proxy
+   ```
+
+   - This command maps port `3000` on your local machine to port `3000` in the container.
+   - It also mounts the `allowed-pubkeys.json` file from your local directory into the container.
+
+   To run with a custom relay URL, use the `-e` flag:
+
+   ```bash
+   docker run -p 3000:3000 -e RELAY_URL="wss://your-relay-url.com" -v $(pwd)/allowed-pubkeys.json:/app/allowed-pubkeys.json --name nip42-proxy nip42-proxy
+   ```
+
+The server will start, and you can connect to it using a Nostr client that supports NIP-42 authentication.
+
+## 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 a whitelisted 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.
+