src | ||
.gitignore | ||
biome.json | ||
bun.lock | ||
Dockerfile | ||
index.ts | ||
package.json | ||
README.md | ||
tsconfig.json |
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
Installation
-
Clone the repository:
git clone https://git.arx-ccn.com/Arx/nip42-proxy.git cd nip42-proxy
-
Install dependencies:
bun install
Configuration
The proxy is configured through environment variables.
ALLOW_UNAUTHED_PUBLISH
: (Optional) Set totrue
to allow unauthenticated clients to publish events. Defaults tofalse
.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 theRELAY_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:
bun run index.ts
You can also set environment variables in the same command:
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:
-
Build the Docker image:
docker build -t nip42-proxy .
-
Run the Docker container:
docker run -p 3000:3000 --name nip42-proxy nip42-proxy
- This command maps port
3000
on your local machine to port3000
in the container.
To run with a custom relay URL and other environment variables, use the
-e
flag:docker run -p 3000:3000 -e RELAY_URL="wss://your-relay-url.com" -e ADMIN_PUBKEY="my-admin-pubkey" --name nip42-proxy nip42-proxy
- This command maps port
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
:
# 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
- Client Connection: When a client connects to the proxy, it is initially in an unauthenticated state.
- Authentication Request: The proxy sends an
AUTH
challenge to the client. - Client Authentication: The client must respond with a valid
AUTH
event, signed with an allowed public key. - Authenticated State: Once authenticated, the client can send and receive messages from the main relay through the proxy.
- 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.