Add HMAC-based authentication for RPC/CLI

Implements time-based HMAC-SHA256 authentication using a shared API key.
Each request includes a timestamp and HMAC in the X-Auth header, preventing
replay attacks with a 60-second tolerance window.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: benthecarman

Cargo.lock

@@ -51,6 +51,6 @@ cargo run --bin ldk-server ./ldk-server/ldk-server-config.toml
 
 Interact with the node using CLI:
 ```
-./target/debug/ldk-server-cli -b localhost:3002 onchain-receive # To generate onchain-receive address.
-./target/debug/ldk-server-cli -b localhost:3002 help # To print help/available commands.
+./target/debug/ldk-server-cli -b localhost:3002 --api-key your-secret-api-key onchain-receive # To generate onchain-receive address.
+./target/debug/ldk-server-cli -b localhost:3002 --api-key your-secret-api-key help # To print help/available commands.
 ```

README.md

@@ -46,6 +46,9 @@ struct Cli {
 	#[arg(short, long, default_value = "localhost:3000")]
 	base_url: String,
 
+	#[arg(short, long, required(true))]
+	api_key: String,
+
 	#[command(subcommand)]
 	command: Commands,
 }
@@ -214,7 +217,7 @@ enum Commands {
 #[tokio::main]
 async fn main() {
 	let cli = Cli::parse();
-	let client = LdkServerClient::new(cli.base_url);
+	let client = LdkServerClient::new(cli.base_url, cli.api_key);
 
 	match cli.command {
 		Commands::GetNodeInfo => {

ldk-server-cli/src/main.rs

@@ -11,3 +11,4 @@ serde = ["ldk-server-protos/serde"]
 ldk-server-protos = { path = "../ldk-server-protos" }
 reqwest = { version = "0.11.13", default-features = false, features = ["rustls-tls"] }
 prost = { version = "0.11.6", default-features = false, features = ["std", "prost-derive"] }
+bitcoin_hashes = "0.14"

ldk-server-client/Cargo.toml

@@ -13,6 +13,8 @@ use crate::error::LdkServerError;
 use crate::error::LdkServerErrorCode::{
 	AuthError, InternalError, InternalServerError, InvalidRequestError, LightningError,
 };
+use bitcoin_hashes::hmac::{Hmac, HmacEngine};
+use bitcoin_hashes::{sha256, Hash, HashEngine};
 use ldk_server_protos::api::{
 	Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
@@ -32,6 +34,7 @@ use ldk_server_protos::endpoints::{
 use ldk_server_protos::error::{ErrorCode, ErrorResponse};
 use reqwest::header::CONTENT_TYPE;
 use reqwest::Client;
+use std::time::{SystemTime, UNIX_EPOCH};
 
 const APPLICATION_OCTET_STREAM: &str = "application/octet-stream";
 
@@ -40,12 +43,31 @@ const APPLICATION_OCTET_STREAM: &str = "application/octet-stream";
 pub struct LdkServerClient {
 	base_url: String,
 	client: Client,
+	api_key: String,
 }
 
 impl LdkServerClient {
 	/// Constructs a [`LdkServerClient`] using `base_url` as the ldk-server endpoint.
-	pub fn new(base_url: String) -> Self {
-		Self { base_url, client: Client::new() }
+	/// `api_key` is used for HMAC-based authentication.
+	pub fn new(base_url: String, api_key: String) -> Self {
+		Self { base_url, client: Client::new(), api_key }
+	}
+
+	/// Computes the HMAC-SHA256 authentication header value.
+	/// Format: "HMAC <timestamp>:<hmac_hex>"
+	fn compute_auth_header(&self, body: &[u8]) -> String {
+		let timestamp = SystemTime::now()
+			.duration_since(UNIX_EPOCH)
+			.expect("System time should be after Unix epoch")
+			.as_secs();
+
+		// Compute HMAC-SHA256(api_key, timestamp_bytes || body)
+		let mut hmac_engine: HmacEngine<sha256::Hash> = HmacEngine::new(self.api_key.as_bytes());
+		hmac_engine.input(&timestamp.to_be_bytes());
+		hmac_engine.input(body);
+		let hmac_result = Hmac::<sha256::Hash>::from_engine(hmac_engine);
+
+		format!("HMAC {}:{}", timestamp, hmac_result)
 	}
 
 	/// Retrieve the latest node info like `node_id`, `current_best_block` etc.
@@ -196,10 +218,12 @@ impl LdkServerClient {
 		&self, request: &Rq, url: &str,
 	) -> Result<Rs, LdkServerError> {
 		let request_body = request.encode_to_vec();
+		let auth_header = self.compute_auth_header(&request_body);
 		let response_raw = self
 			.client
 			.post(url)
 			.header(CONTENT_TYPE, APPLICATION_OCTET_STREAM)
+			.header("X-Auth", auth_header)
 			.body(request_body)
 			.send()
 			.await

ldk-server-client/src/client.rs

@@ -20,6 +20,7 @@ async-trait = { version = "0.1.85", default-features = false }
 toml = { version = "0.8.9", default-features = false, features = ["parse"] }
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
 log = "0.4.28"
+base64 = { version = "0.21", default-features = false, features = ["std"] }
 
 # Required for RabittMQ based EventPublisher. Only enabled for `events-rabbitmq` feature.
 lapin = { version = "2.4.0", features = ["rustls"], default-features = false, optional = true }

ldk-server/Cargo.toml

@@ -3,6 +3,7 @@
 network = "regtest"                           # Bitcoin network to use
 listening_address = "localhost:3001"          # Lightning node listening address
 rest_service_address = "127.0.0.1:3002"       # LDK Server REST address
+api_key = "your-secret-api-key"               # API key for authenticating REST requests
 
 # Storage settings
 [storage.disk]

ldk-server/ldk-server-config.toml

@@ -43,6 +43,9 @@ pub(crate) enum LdkServerErrorCode {
 	/// Please refer to [`protos::error::ErrorCode::InvalidRequestError`].
 	InvalidRequestError,
 
+	/// Please refer to [`protos::error::ErrorCode::AuthError`].
+	AuthError,
+
 	/// Please refer to [`protos::error::ErrorCode::LightningError`].
 	LightningError,
 
@@ -54,6 +57,7 @@ impl fmt::Display for LdkServerErrorCode {
 	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 		match self {
 			LdkServerErrorCode::InvalidRequestError => write!(f, "InvalidRequestError"),
+			LdkServerErrorCode::AuthError => write!(f, "AuthError"),
 			LdkServerErrorCode::LightningError => write!(f, "LightningError"),
 			LdkServerErrorCode::InternalServerError => write!(f, "InternalServerError"),
 		}

ldk-server/src/api/error.rs

@@ -356,7 +356,7 @@ fn main() {
 					match res {
 						Ok((stream, _)) => {
 							let io_stream = TokioIo::new(stream);
-							let node_service = NodeService::new(Arc::clone(&node), Arc::clone(&paginated_store));
+							let node_service = NodeService::new(Arc::clone(&node), Arc::clone(&paginated_store), config_file.api_key.clone());
 							runtime.spawn(async move {
 								if let Err(err) = http1::Builder::new().serve_connection(io_stream, node_service).await {
 									error!("Failed to serve connection: {}", err);