L402 Nginx Module

An L402 authentication module/plugin for Nginx that integrates seamlessly into your web server, enabling Lightning Network-based monetization for your REST APIs (HTTP/1 and HTTP/2). It supports Lightning Network Daemon (LND), Lightning Network URL (LNURL), and Nostr Wallet Connect (NWC) for invoice generation. The module can be configured to charge per unique API call, allowing you to monetize your endpoints based on specific request paths.

graph TD;
    A[Request Received] --> B{Endpoint L402 Enabled?}
    B -->|No| C[Return 200 OK]
    B -->|Yes| D{Authorization Header present in request?}
    D -->|No| F[Generate L402 Header macaroon & invoice]
    F --> G{Header Generation Success?}
    G -->|Yes| H[Add WWW-Authenticate Header]
    G -->|No| I[Return 500 Internal Server Error]
    H --> J[Return 402 Payment Required]
    D -->|Yes| K[Parse L402 Header macaroon & preimage]
    K --> L{Parse Success?}
    L -->|No| M[Return 500 Internal Server Error]
    L -->|Yes| N[Verify L402]
    N --> O{Verification Success?}
    O -->|Yes| P[Return 200 OK]
    O -->|No| Q[Return 401 Unauthorized]

Loading

Installation & Usage

1. Download the module file libngx_l402_lib.so from the latest release and copy it to your Nginx modules directory (typically /etc/nginx/modules/)

2. Enable the module in your nginx.conf:

load_module /etc/nginx/modules/libngx_l402_lib.so;

3. Enable L402 for specific locations:

location /protected {
    root   /usr/share/nginx/html;
    index  index.html index.htm;
    
    # l402 module directive:   
    l402 on;
    l402_amount_msat    10000;
}

4. Set the following environment variables in nginx.service (typically in /lib/systemd/system/nginx.service):

[Service]
...
# Use one of the following:
# if using LNURL:
Environment=LN_CLIENT_TYPE=LNURL
Environment=LNURL_ADDRESS=https://your-lnurl-server.com
Environment=ROOT_KEY=your-root-key
# if using LND:
Environment=LN_CLIENT_TYPE=LND
Environment=LND_ADDRESS=https://your-lnd-server.com
Environment=MACAROON_FILE_PATH=/path/to/macaroon
Environment=CERT_FILE_PATH=/path/to/cert
Environment=ROOT_KEY=your-root-key
# if using NWC:
Environment=LN_CLIENT_TYPE=NWC
Environment=NWC_URI=https://your-nostr-wallet.com
Environment=ROOT_KEY=your-root-key

# To accept Cashu tokens as Ecash for L402:
Environment=CASHU_ECASH_SUPPORT=true
Environment=CASHU_DB_PATH=/var/lib/nginx/cashu_wallet.db
...

5. Restart Nginx:

sudo systemctl restart nginx

6. (Only if accepting Cashu tokens) Provide permission to the Nginx user to access the Cashu database:

sudo chown nginx:nginx /var/lib/nginx/cashu_wallet.db
sudo chmod 666 /var/lib/nginx/cashu_wallet.db

Building from Source

To build the module from source:

1. Install Rust and Cargo if not already installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Clone the repository:

git clone https://github.com/DhananjayPurohit/ngx_l402.git
cd ngx_l402

3. Build the module:

cargo build --release --features export-modules

The compiled module will be created at /target/release/libngx_l402_lib.so.