No description
Find a file
2025-08-10 21:28:08 +02:00
images forgot 2025-08-10 21:28:08 +02:00
src initial version 2025-08-10 21:20:19 +02:00
.gitignore initial version 2025-08-10 21:20:19 +02:00
biome.json initial version 2025-08-10 21:20:19 +02:00
bun.lock initial version 2025-08-10 21:20:19 +02:00
Dockerfile initial version 2025-08-10 21:20:19 +02:00
index.ts initial version 2025-08-10 21:20:19 +02:00
LICENSE improve readme and add license 2025-08-10 21:27:02 +02:00
package.json initial version 2025-08-10 21:20:19 +02:00
README.md p 2025-08-10 21:27:27 +02:00
tsconfig.json initial version 2025-08-10 21:20:19 +02:00

NIP-42 Proxy Logo

NIP-42 Proxy

A NIP-42 authentication proxy for Nostr relays.

License: AGPL v3


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.

Features

  • 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.

🚀 Getting Started

Prerequisites

Installation & Running

  1. Clone the repository:

    git clone https://git.arx-ccn.com/Arx/nip42-proxy.git
    cd nip42-proxy
    
  2. Install dependencies:

    bun install
    
  3. Run the proxy:

    • With Bun:

      RELAY_URL="wss://my-relay.com" ADMIN_PUBKEY="my-admin-pubkey" bun run index.ts
      
    • With Docker:

      1. Build the image:

        docker build -t nip42-proxy .
        
      2. Run the container:

        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.

⚙️ Configuration

The proxy is configured through environment variables.

Click to view all configuration 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.

🔧 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:

  • 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.

🤔 How It Works

  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.

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request with your improvements.

📄 License

This project is licensed under the AGPLv3. See the LICENSE file for details.