add API authentication via Biscuit tokens

Author: zoedberg

Cargo.lock

@@ -15,6 +15,7 @@ axum-extra = "0.9.4"
 # axum-macros = "0.4.2"  # uncomment to use debug_handler
 baid58 = "0.4.4"
 base64 = "0.22.1"
+biscuit-auth = "6.0.0"
 bitcoin = "0.32"
 bitcoin-bech32 = "0.13"
 chacha20poly1305 = { version = "0.10.1", features = ["stream"] }

Cargo.toml

@@ -197,6 +197,7 @@ The node currently exposes the following APIs:
 - `/postassetmedia` (POST)
 - `/refreshtransfers` (POST)
 - `/restore` (POST)
+- `/revoketoken` (POST)
 - `/rgbinvoice` (POST)
 - `/sendasset` (POST)
 - `/sendbtc` (POST)
@@ -223,6 +224,95 @@ given above, you can even call the APIs directly from the Swagger UI.
 
 To stop the daemon, exit with the `/shutdown` API (or press `Ctrl+C`).
 
+### Authentication
+
+RLN provides API authentication via [Biscuit tokens].
+
+#### One-time setup
+
+First, generate a root keypair. This keypair is your issuer key: the private
+half signs new tokens, and the public half is shared with your node so it can
+verify them.
+
+```sh
+# install the biscuit CLI (or download a prebuilt binary from the Biscuit releases page
+cargo install biscuit-cli
+
+# generate a root keypair (prints both keys)
+biscuit keypair
+
+# alternatively, you can export just the private key
+biscuit keypair --only-private-key > private-key-file
+# and later derive the public key from it
+biscuit keypair --from-private-key-file private-key-file --only-public-key
+```
+
+Save the private key in a secure way (e.g. in a secret manager).
+
+When starting the node, pass the public key with:
+```sh
+--root-public-key <public_key>
+```
+To **disable** authentication provide the explicit `--disable-authentication`
+arg and do not provide any key.
+
+#### Minting tokens
+
+You can now create Biscuit tokens that will allow calling the authenticated
+APIs.
+
+Tokens must carry a **role**, these are the available roles:
+
+- **admin** token (full access):
+    ```sh
+    echo 'role("admin");' \
+      | biscuit generate --private-key-file private-key-file -
+    ```
+
+- **read-only** token (allows access only to endpoints that do not make any
+  write operations):
+    ```sh
+    echo 'role("read-only");' \
+      | biscuit generate --private-key-file private-key-file -
+    ```
+- **custom** token (allows access only to the specified API paths), for
+  example:
+    ```sh
+    echo 'role("custom");
+          right("api", "/nodeinfo");
+          right("api", "/networkinfo");' \
+      | biscuit generate --private-key-file private-key-file -
+    ```
+
+Tokens can also carry an **expiry** date. Add a `check` clause to enforce
+expiration, for example:
+```sh
+echo 'role("admin");
+      check if time($t), $t <= 2025-08-30T00:00:00Z;' \
+  | biscuit generate --private-key-file private-key-file -
+```
+
+#### Using tokens
+
+All authenticated requests must include the Biscuit token in the
+`Authorization` header:
+
+```sh
+curl -H "Authorization: Bearer <token>" [...] http://<node-address>/networkinfo
+```
+
+In the Swagger UI you can add the token by clicking the Authorize button (lock
+icon) at the top right, pasting the token and clicking Authorize.
+
+#### Revoking tokens
+
+A token can be revoked before its expiration.
+When you revoke a token, the node will reject any future request carrying that
+token.
+The node exposes a `/revoketoken` endpoint for this purpose.
+Internally, the node extracts the token’s revocation identifiers and adds them
+to its revocation list. Every request checks this list before authenticating.
+
 ## Test
 
 Tests for a few scenarios using the regtest network are included. The same
@@ -244,6 +334,7 @@ Here is a list of projects using RLN, in alphabetical order:
 - [Thunderstack]
 
 
+[Biscuit tokens]: https://www.biscuitsec.org/
 [RGB proxy server]: https://github.com/RGB-Tools/rgb-proxy-server
 [ldk-sample]: https://github.com/lightningdevkit/ldk-sample
 [OpenAPI specification]: /openapi.yaml

README.md

@@ -784,6 +784,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/EmptyResponse'
+  /revoketoken:
+    post:
+      tags:
+        - Other
+      summary: Revoke a token
+      description: Revoke an authentication token
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RevokeTokenRequest'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptyResponse'
   /rgbinvoice:
     post:
       tags:
@@ -1994,6 +2012,12 @@ components:
         password:
           type: string
           example: nodepassword
+    RevokeTokenRequest:
+      type: object
+      properties:
+        token:
+          type: string
+          example: EnYKDBgDIggKBggGEgIYDRIkCAASICqCgqtFMIJ1eLCM3raDzqg9UqV-6nJWzGjjJG0S5IIUGkBpF-itmppHcdcSrSCiKklz9VZT4UmIND_0RFc32Imq3bLR_Y7GYaSpJo5lJfU1cA2BG_hy7P1UN4g5jKTKS88GIiIKIAUKXrrx0Ca-rMZa537VOFw2X8q_KVQ6OC4Z0ztro0sQ
     RgbAllocation:
       type: object
       properties:
@@ -2387,3 +2411,10 @@ components:
         colorable:
           type: boolean
           example: true
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: Biscuit
+security:
+  - bearerAuth: []

openapi.yaml

@@ -2,6 +2,7 @@ use clap::{value_parser, Parser};
 use rgb_lib::BitcoinNetwork;
 use std::path::PathBuf;
 
+use crate::auth::check_auth_args;
 use crate::error::AppError;
 use crate::utils::check_port_is_available;
 
@@ -26,6 +27,14 @@ struct Args {
     /// Max allowed media size for upload (in MB)
     #[arg(long, default_value_t = 5)]
     max_media_upload_size_mb: u16,
+
+    /// Root public key for biscuit token authentication (hex-encoded)
+    #[arg(long)]
+    root_public_key: Option<String>,
+
+    /// Disable authentication
+    #[arg(long, default_value_t = false)]
+    disable_authentication: bool,
 }
 
 pub(crate) struct UserArgs {
@@ -34,6 +43,7 @@ pub(crate) struct UserArgs {
     pub(crate) ldk_peer_listening_port: u16,
     pub(crate) network: BitcoinNetwork,
     pub(crate) max_media_upload_size_mb: u16,
+    pub(crate) root_public_key: Option<biscuit_auth::PublicKey>,
 }
 
 pub(crate) fn parse_startup_args() -> Result<UserArgs, AppError> {
@@ -46,11 +56,14 @@ pub(crate) fn parse_startup_args() -> Result<UserArgs, AppError> {
     let ldk_peer_listening_port = args.ldk_peer_listening_port;
     check_port_is_available(ldk_peer_listening_port)?;
 
+    let root_public_key = check_auth_args(args.disable_authentication, args.root_public_key)?;
+
     Ok(UserArgs {
         storage_dir_path: args.storage_directory_path,
         daemon_listening_port,
         ldk_peer_listening_port,
         network,
         max_media_upload_size_mb: args.max_media_upload_size_mb,
+        root_public_key,
     })
 }