feat(rpc): require bearer-token auth on admin gRPC service

Cargo.toml

@@ -91,6 +91,7 @@ cdk = { version = "0.17.2", default-features = false, features = ["wallet"] }
 secp256k1 = { version = "0.30", features = ["serde"] }
 secrecy = { version = "0.10", features = ["serde"] }
 zeroize = "1.8"
+subtle = "2.6"
 
 [dev-dependencies]
 tokio = { version = "1.47.1", features = ["full", "test-util", "macros"] }

README.md

@@ -794,17 +794,19 @@ For client documentation, see the respective client repositories.
 
 ### Admin Operations (RPC Interface)
 
-If RPC is enabled, use admin tools for dispute resolution:
+If RPC is enabled, use admin tools for dispute resolution. Every call requires the `authorization: Bearer <token>` header set to your `[rpc].auth_token` / `MOSTRO_RPC_AUTH_TOKEN` value:
 
 ```bash
+export MOSTRO_RPC_AUTH_TOKEN="your-configured-token"
+
 # Cancel an order (admin override)
-grpcurl -plaintext -d '{"order_id": "abc123"}' localhost:50051 mostro.admin.v1.AdminService/CancelOrder
+grpcurl -plaintext -H "authorization: Bearer $MOSTRO_RPC_AUTH_TOKEN" -d '{"order_id": "abc123"}' localhost:50051 mostro.admin.v1.AdminService/CancelOrder
 
 # Settle disputed order
-grpcurl -plaintext -d '{"order_id": "abc123"}' localhost:50051 mostro.admin.v1.AdminService/SettleOrder
+grpcurl -plaintext -H "authorization: Bearer $MOSTRO_RPC_AUTH_TOKEN" -d '{"order_id": "abc123"}' localhost:50051 mostro.admin.v1.AdminService/SettleOrder
 
 # Add dispute solver
-grpcurl -plaintext -d '{"solver_pubkey": "npub1..."}' localhost:50051 mostro.admin.v1.AdminService/AddSolver
+grpcurl -plaintext -H "authorization: Bearer $MOSTRO_RPC_AUTH_TOKEN" -d '{"solver_pubkey": "npub1..."}' localhost:50051 mostro.admin.v1.AdminService/AddSolver
 ```
 
 ---

docs/ADMIN_RPC_AND_DISPUTES.md

@@ -41,7 +41,7 @@ sequenceDiagram
 ```
 
 ## Audit and Safety
-- Require admin authentication/authorization at message level.
+- Admin RPC transport requires a bearer token (`[rpc].auth_token` / `MOSTRO_RPC_AUTH_TOKEN`), validated by `TokenAuthInterceptor` (`src/rpc/auth.rs`) before any request reaches a handler — see `docs/RPC.md#security-considerations`. The daemon refuses to start if `[rpc].enabled = true` without a token configured.
 - Enforce solver permission levels in the daemon: `read` solvers can assist but cannot execute `admin-settle` or `admin-cancel`.
 - Record solver, timestamps, and decisions in DB for traceability.
 - Avoid leaking sensitive data in logs; scrub invoices and keys.

docs/RPC.md

@@ -22,6 +22,10 @@ enabled = true
 listen_address = "127.0.0.1"
 # RPC server port (required key; default=50051)
 port = 50051
+# Bearer token required on every admin RPC call. Required when enabled = true
+# (the daemon refuses to start otherwise). Prefer the MOSTRO_RPC_AUTH_TOKEN
+# environment variable over storing this in plaintext TOML.
+auth_token = "change-me-to-a-long-random-value"
 ```
 
 ## Available Admin Operations
@@ -86,7 +90,7 @@ Take a dispute for resolution.
 
 ### 5. Validate Database Password
 
-Kept for backward compatibility with older clients. The SQLite database is **not** encrypted and this RPC does **not** validate any password; it always succeeds.
+Kept for backward compatibility with older clients. The SQLite database is **not** encrypted and this RPC does **not** validate any password; it always succeeds. Like every other admin RPC, it is only reached after the bearer-token check below passes.
 
 **Request:**
 
@@ -140,10 +144,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     let mut client = AdminServiceClient::new(channel);
 
-    let request = tonic::Request::new(CancelOrderRequest {
+    let mut request = tonic::Request::new(CancelOrderRequest {
         order_id: "550e8400-e29b-41d4-a716-446655440000".to_string(),
         request_id: Some("12345".to_string()),
     });
+    request.metadata_mut().insert(
+        "authorization",
+        "Bearer <your auth_token>".parse().unwrap(),
+    );
 
     let response = client.cancel_order(request).await?;
 
@@ -159,10 +167,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 ## Security Considerations
 
+- Every admin RPC call requires a bearer token: `authorization: Bearer <token>` metadata, checked by `TokenAuthInterceptor` (`src/rpc/auth.rs`) before the request reaches any handler. The comparison is constant-time (`subtle::ConstantTimeEq`) so a timing side channel can't be used to guess the token.
+- The token is set via `[rpc].auth_token` in `settings.toml`, or the `MOSTRO_RPC_AUTH_TOKEN` environment variable (or `<settings_dir>/.env`) — the environment variable takes precedence, following the same pattern as `MOSTRO_NSEC_PRIVKEY`.
+- **Fail-closed at startup**: if `[rpc].enabled = true` and no token is configured (TOML or environment), the daemon refuses to start rather than silently running an authless admin surface.
 - The RPC server listens on localhost by default for security
-- Consider implementing authentication/authorization for production use
 - The RPC interface provides the same admin capabilities as Nostr-based commands
-- Only enable the RPC server in trusted environments
+- Only enable the RPC server in trusted environments, and treat the token like any other credential (rotate it, don't commit it, prefer the environment variable over plaintext TOML)
 
 ## Debugging
 

docs/RPC_RATE_LIMITING.md

@@ -69,7 +69,7 @@ How the original issue’s ideas map to the codebase today:
 | Exponential backoff / lockout | Implemented inside **`RateLimiter`**; **not** triggered by **`ValidateDbPassword`** (no **`record_failure`**). |
 | Audit logging | **tracing** in service + limiter. |
 | Localhost-only | Default RPC bind **`127.0.0.1`** (see `settings.toml` / `docs/RPC.md`). |
-| Strong auth | Out of scope for this stub; would need API keys or similar. |
+| Strong auth | Implemented (issue #807): a bearer token (`[rpc].auth_token` / `MOSTRO_RPC_AUTH_TOKEN`) is required on every admin RPC call, enforced transport-wide by **`TokenAuthInterceptor`** (`src/rpc/auth.rs`) before any request — including `ValidateDbPassword` — reaches a handler. See `docs/RPC.md#security-considerations`. This module's `RateLimiter` remains in place as defense-in-depth specifically on `ValidateDbPassword`, since token auth already blocks unauthenticated callers entirely and the limiter is cheap, already-reviewed code that adds a second layer against a leaked/brute-forced token. |
 
 ## Testing
 

settings.tpl.toml

@@ -138,6 +138,11 @@ listen_address = "127.0.0.1"
 port = 50051
 # Duration in seconds after which inactive rate-limiter entries are evicted
 # rate_limiter_stale_duration = 3600
+# Bearer token required on every admin RPC call (authorization: Bearer <token>).
+# Required when enabled = true - the daemon refuses to start otherwise.
+# Prefer the MOSTRO_RPC_AUTH_TOKEN environment variable (or <settings_dir>/.env)
+# over storing this in plaintext TOML.
+# auth_token = "change-me-to-a-long-random-value"
 
 # Multi-source price providers (see docs/PRICE_PROVIDERS.md).
 # Absent section ≡ legacy single-source behaviour synthesised from

src/config/constants.rs

@@ -30,3 +30,7 @@ pub const ENV_FILENAME: &str = ".env";
 /// Environment variable name used to override the Nostr private key from the
 /// process environment. Shared between the wizard and the loader.
 pub const NSEC_ENV_VAR: &str = "MOSTRO_NSEC_PRIVKEY";
+
+/// Environment variable name used to override the admin RPC bearer token
+/// from the process environment. Shared between the wizard and the loader.
+pub const RPC_TOKEN_ENV_VAR: &str = "MOSTRO_RPC_AUTH_TOKEN";

src/config/secret.rs

@@ -1,7 +1,7 @@
 //! Helpers for loading and parsing the Mostro Nostr private key with
 //! zeroization of transient buffers.
 
-use crate::config::constants::NSEC_ENV_VAR;
+use crate::config::constants::{NSEC_ENV_VAR, RPC_TOKEN_ENV_VAR};
 use crate::config::types::NostrSettings;
 use mostro_core::error::MostroError::{self, *};
 use mostro_core::error::ServiceError;
@@ -11,7 +11,8 @@ use serde::Serializer;
 use zeroize::Zeroize;
 
 /// Serialize a [`SecretString`] for config files (wizard / TOML export only).
-pub fn serialize_nsec<S>(secret: &SecretString, serializer: S) -> Result<S::Ok, S::Error>
+/// Shared by every `SecretString`-typed setting (`nsec_privkey`, `auth_token`).
+pub fn serialize_secret<S>(secret: &SecretString, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: Serializer,
 {
@@ -32,6 +33,21 @@ pub fn read_nsec_env_var() -> Option<SecretString> {
     Some(secret)
 }
 
+/// Read `MOSTRO_RPC_AUTH_TOKEN` from the process environment, trim
+/// whitespace, and wrap in a [`SecretString`]. Returns `None` when unset or
+/// blank.
+pub fn read_rpc_token_env_var() -> Option<SecretString> {
+    let mut token_from_env = std::env::var(RPC_TOKEN_ENV_VAR).ok()?;
+    let trimmed = token_from_env.trim();
+    if trimmed.is_empty() {
+        token_from_env.zeroize();
+        return None;
+    }
+    let secret = SecretString::from(trimmed.to_owned());
+    token_from_env.zeroize();
+    Some(secret)
+}
+
 /// Parse a bech32 nsec into [`Keys`], exposing the secret only in this scope.
 pub fn parse_mostro_keys(secret: &SecretString) -> Result<Keys, MostroError> {
     let nsec = secret.expose_secret();

src/config/types.rs

@@ -505,7 +505,7 @@ impl Default for LightningSettings {
 pub struct NostrSettings {
     /// Nostr private key. Optional when `MOSTRO_NSEC_PRIVKEY` is provided via
     /// environment variable or `<settings_dir>/.env`.
-    #[serde(default, serialize_with = "crate::config::secret::serialize_nsec")]
+    #[serde(default, serialize_with = "crate::config::secret::serialize_secret")]
     pub nsec_privkey: secrecy::SecretString,
     /// Nostr relays list
     pub relays: Vec<String>,
@@ -522,6 +522,14 @@ pub struct RpcSettings {
     /// Duration in seconds after which inactive rate-limiter entries are evicted
     #[serde(default = "default_rate_limiter_stale_duration")]
     pub rate_limiter_stale_duration: u64,
+    /// Bearer token required on every admin gRPC call (`authorization: Bearer
+    /// <token>` metadata). Optional in TOML when `MOSTRO_RPC_AUTH_TOKEN` is
+    /// provided via environment variable or `<settings_dir>/.env` — mirrors
+    /// `NostrSettings::nsec_privkey`. Unlike the Nostr key, this stays live
+    /// in `MOSTRO_CONFIG` for the process lifetime (the auth interceptor
+    /// reads it on every request) rather than being cleared after startup.
+    #[serde(default, serialize_with = "crate::config::secret::serialize_secret")]
+    pub auth_token: secrecy::SecretString,
 }
 
 fn default_rate_limiter_stale_duration() -> u64 {
@@ -535,6 +543,7 @@ impl Default for RpcSettings {
             listen_address: "127.0.0.1".to_string(),
             port: 50051,
             rate_limiter_stale_duration: default_rate_limiter_stale_duration(),
+            auth_token: secrecy::SecretString::default(),
         }
     }
 }

src/config/util.rs

@@ -3,11 +3,12 @@
 /// It includes functions to initialize the default settings directory and create a settings file from the template if it doesn't exist.
 /// It also includes functions to add a trailing slash to a path if it doesn't already have one.
 use crate::config::constants::{ENV_FILENAME, MAX_DEV_FEE_PERCENTAGE, MIN_DEV_FEE_PERCENTAGE};
-use crate::config::secret::read_nsec_env_var;
+use crate::config::secret::{read_nsec_env_var, read_rpc_token_env_var};
 use crate::config::wizard;
 use crate::config::{init_mostro_settings, Settings};
 use mostro_core::error::MostroError::{self, *};
 use mostro_core::error::ServiceError;
+use secrecy::ExposeSecret;
 use std::fs;
 use std::io::IsTerminal;
 use std::path::PathBuf;
@@ -46,6 +47,16 @@ fn apply_nsec_env_override(settings: &mut Settings) {
     }
 }
 
+/// If the `MOSTRO_RPC_AUTH_TOKEN` environment variable is set to a non-empty
+/// value, override the RPC auth token loaded from `settings.toml`.
+/// Whitespace is trimmed; blank values are ignored so the TOML stays the
+/// fallback.
+fn apply_rpc_token_env_override(settings: &mut Settings) {
+    if let Some(token) = read_rpc_token_env_var() {
+        settings.rpc.auth_token = token;
+    }
+}
+
 /// Validates Mostro settings on startup
 fn validate_mostro_settings(settings: &Settings) -> Result<(), MostroError> {
     let dev_fee = settings.mostro.dev_fee_percentage;
@@ -65,6 +76,16 @@ fn validate_mostro_settings(settings: &Settings) -> Result<(), MostroError> {
         ))));
     }
 
+    // An admin RPC surface with no credential is the exact vulnerability
+    // issue #807 fixes — refuse to boot rather than silently run it open.
+    if settings.rpc.enabled && settings.rpc.auth_token.expose_secret().is_empty() {
+        return Err(MostroInternalErr(ServiceError::IOError(
+            "[rpc].enabled = true requires an auth token: set [rpc].auth_token in \
+             settings.toml or the MOSTRO_RPC_AUTH_TOKEN environment variable."
+                .to_string(),
+        )));
+    }
+
     validate_cashu_settings(
         settings.cashu.as_ref(),
         settings
@@ -173,6 +194,7 @@ pub fn init_configuration_file(config_path: Option<String>) -> Result<(), Mostro
         };
 
         apply_nsec_env_override(&mut settings);
+        apply_rpc_token_env_override(&mut settings);
         validate_mostro_settings(&settings)?;
         init_mostro_settings(settings)?;
         tracing::info!("Settings correctly loaded!");
@@ -190,9 +212,10 @@ pub fn init_configuration_file(config_path: Option<String>) -> Result<(), Mostro
     let mut settings: Settings = toml::from_str(&contents)
         .map_err(|e| MostroInternalErr(ServiceError::IOError(e.to_string())))?;
 
-    // Apply MOSTRO_NSEC_PRIVKEY override before validation so an empty TOML
-    // value is fine when the env var is set.
+    // Apply MOSTRO_NSEC_PRIVKEY / MOSTRO_RPC_AUTH_TOKEN overrides before
+    // validation so an empty TOML value is fine when the env var is set.
     apply_nsec_env_override(&mut settings);
+    apply_rpc_token_env_override(&mut settings);
 
     // Validate settings before initializing
     validate_mostro_settings(&settings)?;
@@ -368,6 +391,90 @@ mod tests {
         assert!(nostr.nsec_privkey.expose_secret().is_empty());
         assert_eq!(nostr.relays, vec!["wss://relay.test"]);
     }
+
+    // ── RPC auth token env override (issue #807) ───────────────────────────
+    // Mirrors the MOSTRO_NSEC_PRIVKEY suite above, sharing the same
+    // EnvVarGuard/ENV_LOCK machinery (ENV_LOCK guards the whole module's env
+    // access, not just NSEC_ENV_VAR, so these are safe to run concurrently
+    // with the nsec tests).
+
+    use crate::config::constants::RPC_TOKEN_ENV_VAR;
+
+    #[test]
+    fn env_var_overrides_toml_rpc_token() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let guard = EnvVarGuard::new(RPC_TOKEN_ENV_VAR);
+        guard.set("token_from_env");
+
+        let mut settings = make_settings("nsec_from_toml");
+        settings.rpc.auth_token = SecretString::from("token_from_toml".to_string());
+        apply_rpc_token_env_override(&mut settings);
+
+        assert_eq!(settings.rpc.auth_token.expose_secret(), "token_from_env");
+    }
+
+    #[test]
+    fn empty_env_var_falls_back_to_toml_rpc_token() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let guard = EnvVarGuard::new(RPC_TOKEN_ENV_VAR);
+        guard.set("");
+
+        let mut settings = make_settings("nsec_from_toml");
+        settings.rpc.auth_token = SecretString::from("token_from_toml".to_string());
+        apply_rpc_token_env_override(&mut settings);
+
+        assert_eq!(settings.rpc.auth_token.expose_secret(), "token_from_toml");
+    }
+
+    #[test]
+    fn no_env_var_keeps_toml_rpc_token() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let _guard = EnvVarGuard::new(RPC_TOKEN_ENV_VAR);
+
+        let mut settings = make_settings("nsec_from_toml");
+        settings.rpc.auth_token = SecretString::from("token_from_toml".to_string());
+        apply_rpc_token_env_override(&mut settings);
+
+        assert_eq!(settings.rpc.auth_token.expose_secret(), "token_from_toml");
+    }
+
+    #[test]
+    fn whitespace_only_env_is_ignored_rpc_token() {
+        let _lock = ENV_LOCK.lock().unwrap();
+        let guard = EnvVarGuard::new(RPC_TOKEN_ENV_VAR);
+        guard.set("   \t  ");
+
+        let mut settings = make_settings("nsec_from_toml");
+        settings.rpc.auth_token = SecretString::from("token_from_toml".to_string());
+        apply_rpc_token_env_override(&mut settings);
+
+        assert_eq!(settings.rpc.auth_token.expose_secret(), "token_from_toml");
+    }
+
+    // ── fail-closed validation (issue #807) ────────────────────────────────
+
+    #[test]
+    fn validate_mostro_settings_rejects_enabled_rpc_without_token() {
+        let mut settings = make_settings("nsec_from_toml");
+        settings.rpc.enabled = true;
+        assert!(validate_mostro_settings(&settings).is_err());
+    }
+
+    #[test]
+    fn validate_mostro_settings_accepts_enabled_rpc_with_token() {
+        let mut settings = make_settings("nsec_from_toml");
+        settings.rpc.enabled = true;
+        settings.rpc.auth_token = SecretString::from("a-real-token".to_string());
+        assert!(validate_mostro_settings(&settings).is_ok());
+    }
+
+    #[test]
+    fn validate_mostro_settings_accepts_disabled_rpc_without_token() {
+        // Default RpcSettings (enabled = false) must stay valid — untouched
+        // deployments that never opted into [rpc] are unaffected.
+        let settings = make_settings("nsec_from_toml");
+        assert!(validate_mostro_settings(&settings).is_ok());
+    }
 }
 
 #[cfg(test)]