feat(rpc): enforce cookie authentication

The JSON-RPC middleware now gates every request: missing, malformed,
or non-matching Authorization: Basic headers return HTTP 401 with
WWW-Authenticate: Basic realm="jsonrpc" per RFC 7235.

generate_cookie returns the cookie line again so Florestad can wrap
it in Arc<Credentials::Cookie> and pass it through to the middleware
state. Credentials::matches compares format!("{user}:{pass}") against
the stored line via a hand-rolled constant_time_eq that runs the full
length regardless of where the first mismatch lies.

floresta-cli reads <datadir>/[<net>/].cookie by default; --rpc-user +
--rpc-password override; --rpc-cookie-file picks a non-default path.
The Python test framework reads the cookie after the RPC socket opens.

Refs: #651

Author: Micah-Shallom

Cargo.lock

@@ -21,6 +21,7 @@ categories = ["cryptography::cryptocurrencies", "command-line-utilities"]
 anyhow = "=1.0.102"
 bitcoin = { workspace = true }
 clap = { workspace = true, features = ["help"] }
+dirs = { version = "=4.0.0", default-features = false }
 serde_json = { workspace = true }
 
 # Local dependencies

bin/floresta-cli/Cargo.toml

@@ -1,16 +1,20 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
 use core::fmt::Debug;
+use std::fs;
+use std::path::Path;
 use std::path::PathBuf;
 mod parsers;
 
+use anyhow::Context;
 use anyhow::Ok;
 use bitcoin::BlockHash;
 use bitcoin::Network;
 use bitcoin::Txid;
 use clap::Parser;
 use clap::Subcommand;
 use floresta_rpc::jsonrpc_client::Client;
+use floresta_rpc::jsonrpc_client::JsonRPCConfig;
 use floresta_rpc::rpc::FlorestaRPC;
 use floresta_rpc::rpc_types::AddNodeCommand;
 use floresta_rpc::rpc_types::RescanConfidence;
@@ -20,8 +24,16 @@ fn main() -> anyhow::Result<()> {
     // Parse command line arguments into a Cli struct
     let cli = Cli::parse();
 
-    // Create a new JSON-RPC client using the host from the CLI arguments
-    let client = Client::new(get_host(&cli));
+    // Resolve basic-auth credentials: explicit flags win, otherwise read the
+    // cookie file written by florestad at startup.
+    let (user, pass) = resolve_credentials(&cli)?;
+
+    // Create a new JSON-RPC client using the host and credentials.
+    let client = Client::new_with_config(JsonRPCConfig {
+        url: get_host(&cli),
+        user: Some(user),
+        pass: Some(pass),
+    });
 
     // Perform the requested RPC call and get the result
     let res = do_request(&cli, client)?;
@@ -33,6 +45,53 @@ fn main() -> anyhow::Result<()> {
     anyhow::Ok(())
 }
 
+// Resolve the basic-auth credentials for the RPC call.
+//
+// Precedence:
+//   1. `--rpc-user` and `--rpc-password` both set: use them.
+//   2. Otherwise read the cookie file at `--rpc-cookie-file` (or the network's
+//      default location) and split on the first `:` into (user, pass).
+fn resolve_credentials(cli: &Cli) -> anyhow::Result<(String, String)> {
+    if let (Some(user), Some(pass)) = (cli.rpc_user.clone(), cli.rpc_password.clone()) {
+        return anyhow::Ok((user, pass));
+    }
+    let cookie_path = cli
+        .rpc_cookie_file
+        .clone()
+        .unwrap_or_else(|| default_cookie_path(cli.network));
+    read_cookie(&cookie_path)
+}
+
+// Read a cookie file and split it into (user, pass) on the first `:`.
+fn read_cookie(path: &Path) -> anyhow::Result<(String, String)> {
+    let contents = fs::read_to_string(path).with_context(|| {
+        format!(
+            "failed to read RPC cookie file at {}; start florestad first or pass --rpc-user/--rpc-password",
+            path.display()
+        )
+    })?;
+    let (user, pass) = contents
+        .split_once(':')
+        .with_context(|| format!("cookie file at {} is malformed", path.display()))?;
+    anyhow::Ok((user.to_string(), pass.to_string()))
+}
+
+// Compute the default cookie file path for the given network. Mirrors
+// florestad's `datadir_path` layout: `~/.floresta/[<net>/].cookie`.
+fn default_cookie_path(network: Network) -> PathBuf {
+    let base = dirs::home_dir()
+        .unwrap_or_else(|| PathBuf::from("."))
+        .join(".floresta");
+    let net_dir = match network {
+        Network::Bitcoin => base,
+        Network::Signet => base.join("signet"),
+        Network::Testnet => base.join("testnet3"),
+        Network::Testnet4 => base.join("testnet4"),
+        Network::Regtest => base.join("regtest"),
+    };
+    net_dir.join(".cookie")
+}
+
 // Function to determine the RPC host based on CLI arguments and network type
 fn get_host(cmd: &Cli) -> String {
     // If a specific RPC host is provided, use it
@@ -164,6 +223,9 @@ pub struct Cli {
     /// The RPC password to use
     #[arg(short = 'P', long, value_name = "PASSWORD")]
     pub rpc_password: Option<String>,
+    /// Path to the RPC cookie file. Defaults to `<datadir>/[<net>/].cookie`.
+    #[arg(long, value_name = "PATH")]
+    pub rpc_cookie_file: Option<PathBuf>,
     /// An actual RPC command to run
     #[command(subcommand)]
     pub methods: Methods,

bin/floresta-cli/src/main.rs

@@ -472,9 +472,10 @@ impl Florestad {
         #[cfg(feature = "json-rpc")]
         {
             let cookie_path = datadir.join(json_rpc::auth::COOKIE_FILE_NAME);
-            json_rpc::auth::generate_cookie(&cookie_path)?;
+            let cookie = json_rpc::auth::generate_cookie(&cookie_path)?;
             let _ = self.cookie_generated.set(());
             info!("RPC cookie file written to {}", cookie_path.display());
+            let credentials = Arc::new(json_rpc::auth::Credentials::Cookie(cookie));
 
             let server = tokio::spawn(json_rpc::server::RpcImpl::create(
                 blockchain_state.clone(),
@@ -491,6 +492,7 @@ impl Florestad {
                 datadir.join("debug.log"),
                 self.config.user_agent.clone(),
                 proxy,
+                credentials,
             ));
 
             if self.json_rpc.set(server).is_err() {

crates/floresta-node/src/florestad.rs

@@ -40,11 +40,12 @@ const COOKIE_TOKEN_BYTES: usize = 32;
 /// Upper bound on the inbound `Authorization` header to cap base64 decode allocation.
 const MAX_AUTH_HEADER_LEN: usize = 16 * 1024;
 
-/// Generate a fresh cookie and write it to `path` with no trailing newline.
+/// Generate a fresh cookie, write it to `path` with no trailing newline, and
+/// return the `__cookie__:<hex>` line for in-process validation.
 ///
 /// Writes go to `<path>.tmp` first with mode `0600` on Unix, then atomically
 /// rename over `path`. A pre-existing cookie file is silently overwritten.
-pub(crate) fn generate_cookie(path: &Path) -> io::Result<()> {
+pub(crate) fn generate_cookie(path: &Path) -> io::Result<String> {
     let mut token = [0u8; COOKIE_TOKEN_BYTES];
     rand::rng().fill(&mut token);
     let auth = format!("{COOKIE_USER}:{}", token.to_lower_hex_string());
@@ -65,7 +66,7 @@ pub(crate) fn generate_cookie(path: &Path) -> io::Result<()> {
 
     fs::rename(&tmp, path)?;
 
-    Ok(())
+    Ok(auth)
 }
 
 /// Errors produced by [`parse_basic_auth_header`].
@@ -100,26 +101,52 @@ impl fmt::Display for BasicAuthHeaderError {
 
 impl std::error::Error for BasicAuthHeaderError {}
 
-/// Axum middleware that parses an inbound `Authorization: Basic` header and
-/// logs the parsed username at debug level. Requests without the header or
-/// with a malformed value are passed through unchanged; this layer does not
-/// reject anything.
+/// Axum middleware that gates each request on the configured [`Credentials`].
+/// Missing, malformed, non-ASCII, or non-matching `Authorization: Basic`
+/// headers all return HTTP 401 with `WWW-Authenticate: Basic realm="jsonrpc"`
+/// per RFC 7235. Matching requests pass through to the handler.
 pub(crate) async fn auth_middleware(
+    axum::extract::State(creds): axum::extract::State<std::sync::Arc<Credentials>>,
     req: axum::extract::Request,
     next: axum::middleware::Next,
 ) -> axum::response::Response {
-    if let Some(header) = req.headers().get(axum::http::header::AUTHORIZATION) {
-        match header.to_str() {
-            Ok(value) => match parse_basic_auth_header(value) {
-                Ok((user, _)) => tracing::debug!("rpc auth header parsed for user {user}"),
-                Err(e) => tracing::debug!("rpc auth header parse failed: {e}"),
-            },
-            Err(_) => tracing::debug!("rpc auth header is not valid ascii"),
+    let Some(header) = req.headers().get(axum::http::header::AUTHORIZATION) else {
+        tracing::debug!("rpc auth header missing; rejecting");
+        return unauthorized();
+    };
+    let value = match header.to_str() {
+        Ok(s) => s,
+        Err(_) => {
+            tracing::debug!("rpc auth header is not valid ascii; rejecting");
+            return unauthorized();
         }
+    };
+    let (user, pass) = match parse_basic_auth_header(value) {
+        Ok(pair) => pair,
+        Err(e) => {
+            tracing::debug!("rpc auth header parse failed: {e}; rejecting");
+            return unauthorized();
+        }
+    };
+    if !creds.matches(&user, &pass) {
+        tracing::debug!("rpc auth credentials mismatched for user {user}; rejecting");
+        return unauthorized();
     }
+    tracing::debug!("rpc auth ok for user {user}");
     next.run(req).await
 }
 
+fn unauthorized() -> axum::response::Response {
+    axum::response::Response::builder()
+        .status(axum::http::StatusCode::UNAUTHORIZED)
+        .header(
+            axum::http::header::WWW_AUTHENTICATE,
+            r#"Basic realm="jsonrpc""#,
+        )
+        .body(axum::body::Body::empty())
+        .expect("static 401 response is always well-formed")
+}
+
 /// Parse an HTTP `Authorization: Basic <b64>` header value into `(user, pass)`.
 ///
 /// Mirrors Bitcoin Core: the `"Basic "` prefix check is case-sensitive, the
@@ -146,6 +173,41 @@ pub(crate) fn parse_basic_auth_header(
     Ok((user.to_string(), pass.to_string()))
 }
 
+/// Configured RPC credentials for this process. The middleware compares each
+/// inbound `Authorization: Basic` request against the stored value via
+/// [`Credentials::matches`].
+pub(crate) enum Credentials {
+    /// Cookie auth. Stores the full `__cookie__:<hex>` line as written to
+    /// disk by [`generate_cookie`].
+    Cookie(String),
+}
+
+impl Credentials {
+    /// True if the supplied basic-auth `user`/`pass` pair authenticates
+    /// against the configured credentials. All comparisons are constant-time.
+    pub(crate) fn matches(&self, user: &str, pass: &str) -> bool {
+        match self {
+            Self::Cookie(expected) => {
+                constant_time_eq(format!("{user}:{pass}").as_bytes(), expected.as_bytes())
+            }
+        }
+    }
+}
+
+/// Constant-time byte slice comparison. Returns `false` immediately on length
+/// mismatch (lengths of both comparands are public), then XORs every byte into
+/// an accumulator before returning.
+pub(crate) fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut acc: u8 = 0;
+    for (x, y) in a.iter().zip(b.iter()) {
+        acc |= x ^ y;
+    }
+    acc == 0
+}
+
 /// Remove the cookie file at `path`. Treats `NotFound` as success so shutdown
 /// is idempotent. Caller must only invoke this after a successful
 /// [`generate_cookie`] in this process.
@@ -181,14 +243,13 @@ mod tests {
     #[test]
     fn generate_cookie_writes_expected_format() {
         let path = tmp_cookie_path("format");
-        generate_cookie(&path).unwrap();
+        let auth = generate_cookie(&path).unwrap();
 
-        let written = fs::read_to_string(&path).unwrap();
         assert!(
-            written.starts_with("__cookie__:"),
-            "cookie file missing prefix: {written}"
+            auth.starts_with("__cookie__:"),
+            "auth string missing prefix: {auth}"
         );
-        let token = written.strip_prefix("__cookie__:").unwrap();
+        let token = auth.strip_prefix("__cookie__:").unwrap();
         assert_eq!(
             token.len(),
             64,
@@ -202,6 +263,12 @@ mod tests {
             "token should be lowercase hex: {token}",
         );
 
+        let written = fs::read_to_string(&path).unwrap();
+        assert_eq!(
+            written, auth,
+            "file content should match returned auth string"
+        );
+
         fs::remove_file(&path).ok();
     }
 
@@ -220,10 +287,8 @@ mod tests {
     fn generate_cookie_produces_distinct_tokens() {
         let path1 = tmp_cookie_path("distinct1");
         let path2 = tmp_cookie_path("distinct2");
-        generate_cookie(&path1).unwrap();
-        generate_cookie(&path2).unwrap();
-        let auth1 = fs::read_to_string(&path1).unwrap();
-        let auth2 = fs::read_to_string(&path2).unwrap();
+        let auth1 = generate_cookie(&path1).unwrap();
+        let auth2 = generate_cookie(&path2).unwrap();
         assert_ne!(
             auth1, auth2,
             "two consecutive calls produced identical tokens"
@@ -237,12 +302,11 @@ mod tests {
     fn generate_cookie_overwrites_existing_file() {
         let path = tmp_cookie_path("overwrite");
         fs::write(&path, "stale-content").unwrap();
-        generate_cookie(&path).unwrap();
+        let auth = generate_cookie(&path).unwrap();
         let written = fs::read_to_string(&path).unwrap();
-        assert_ne!(written, "stale-content", "stale content was not replaced");
-        assert!(
-            written.starts_with("__cookie__:"),
-            "replacement is not a cookie line: {written}"
+        assert_eq!(
+            written, auth,
+            "file content should match returned auth string"
         );
 
         fs::remove_file(&path).ok();
@@ -369,6 +433,39 @@ mod tests {
         );
     }
 
+    #[test]
+    fn constant_time_eq_returns_true_for_equal_bytes() {
+        assert!(constant_time_eq(b"abcdef", b"abcdef"));
+        assert!(constant_time_eq(b"", b""));
+    }
+
+    #[test]
+    fn constant_time_eq_returns_false_for_different_bytes() {
+        assert!(!constant_time_eq(b"abcdef", b"abcdeg"));
+        assert!(!constant_time_eq(b"abcdef", b"xbcdef"));
+    }
+
+    #[test]
+    fn constant_time_eq_returns_false_for_length_mismatch() {
+        assert!(!constant_time_eq(b"abc", b"abcd"));
+        assert!(!constant_time_eq(b"abcd", b"abc"));
+        assert!(!constant_time_eq(b"", b"a"));
+    }
+
+    #[test]
+    fn cookie_credentials_match_their_own_user_and_pass() {
+        let path = tmp_cookie_path("creds_cookie");
+        let auth = generate_cookie(&path).unwrap();
+        let creds = Credentials::Cookie(auth.clone());
+
+        let (user, pass) = auth.split_once(':').unwrap();
+        assert!(creds.matches(user, pass));
+        assert!(!creds.matches(user, "wrong"));
+        assert!(!creds.matches("wronguser", pass));
+
+        fs::remove_file(&path).ok();
+    }
+
     #[cfg(unix)]
     #[test]
     fn generate_cookie_sets_owner_only_mode_on_unix() {

crates/floresta-node/src/json_rpc/auth.rs

@@ -762,6 +762,7 @@ impl<Blockchain: RpcChain> RpcImpl<Blockchain> {
         log_path: impl AsRef<Path>,
         user_agent: String,
         proxy: Option<SocketAddr>,
+        credentials: Arc<super::auth::Credentials>,
     ) {
         let address = address.unwrap_or_else(|| {
             format!("127.0.0.1:{}", Self::get_port(&network))
@@ -792,7 +793,10 @@ impl<Blockchain: RpcChain> RpcImpl<Blockchain> {
                     .allow_private_network(true)
                     .allow_methods([Method::POST, Method::HEAD]),
             )
-            .layer(axum::middleware::from_fn(super::auth::auth_middleware))
+            .layer(axum::middleware::from_fn_with_state(
+                credentials,
+                super::auth::auth_middleware,
+            ))
             .with_state(Arc::new(RpcImpl {
                 chain,
                 wallet,