feat(security): add API key authentication for gRPC server

Author: kwsantiago

ddk-node/README.md

@@ -22,13 +22,16 @@ Options:
   -n, --network <NETWORK>          Set the Bitcoin network for DDK [default: regtest]
   -s, --storage-dir <STORAGE_DIR>  The path where DlcDevKit will store data.
   -p, --port <LISTENING_PORT>      Listening port for network transport. [default: 1776]
-      --grpc <GRPC_HOST>           Host and port the gRPC server will run on. [default: 0.0.0.0:3030]
+      --grpc <GRPC_HOST>           Host and port the gRPC server will run on. [default: 127.0.0.1:3030]
+      --api-key <API_KEY>          API key for gRPC authentication. Required for non-localhost bindings.
       --esplora <ESPLORA_HOST>     Host to connect to an esplora server. [default: http://127.0.0.1:30000]
       --oracle <ORACLE_HOST>       Host to connect to an oracle server. [default: http://127.0.0.1:8082]
       --seed <SEED>                Seed config strategy ('bytes' OR 'file') [default: file]
   -h, --help                       Print help
 ```
 
+When binding to non-localhost addresses (e.g., `--grpc 0.0.0.0:3030`), an API key is required via `--api-key`.
+
 ```
 $ ddk-cli --help
 

ddk-node/src/bin/cli.rs

@@ -1,6 +1,8 @@
 use clap::Parser;
 use ddk_node::cli_opts::CliCommand;
 use ddk_node::ddkrpc::ddk_rpc_client::DdkRpcClient;
+use tonic::metadata::MetadataValue;
+use tonic::transport::Channel;
 
 #[derive(Debug, Clone, Parser)]
 #[clap(name = "ddk-cli")]
@@ -14,6 +16,9 @@ struct DdkCliArgs {
     #[arg(help = "ddk-node gRPC server to connect to.")]
     #[arg(default_value = "http://127.0.0.1:3030")]
     pub server: String,
+    #[arg(long)]
+    #[arg(help = "API key for authentication")]
+    pub api_key: Option<String>,
     #[clap(subcommand)]
     pub command: CliCommand,
 }
@@ -22,9 +27,21 @@ struct DdkCliArgs {
 async fn main() -> anyhow::Result<()> {
     let opts = DdkCliArgs::parse();
 
-    let mut client = DdkRpcClient::connect(opts.server).await?;
+    if let Some(api_key) = opts.api_key {
+        let channel = Channel::from_shared(opts.server)?.connect().await?;
 
-    ddk_node::command::cli_command(opts.command, &mut client).await?;
+        let token: MetadataValue<_> = api_key.parse()?;
+        let mut client =
+            DdkRpcClient::with_interceptor(channel, move |mut req: tonic::Request<()>| {
+                req.metadata_mut().insert("x-api-key", token.clone());
+                Ok(req)
+            });
+
+        ddk_node::command::cli_command(opts.command, &mut client).await?;
+    } else {
+        let mut client = DdkRpcClient::connect(opts.server).await?;
+        ddk_node::command::cli_command(opts.command, &mut client).await?;
+    }
 
     Ok(())
 }

ddk-node/src/command.rs

@@ -27,12 +27,15 @@ use ddk_messages::oracle_msgs::{EventDescriptor, OracleAnnouncement};
 use ddk_messages::{AcceptDlc, OfferDlc};
 use inquire::{Select, Text};
 use serde_json::Value;
-use tonic::transport::Channel;
 
-pub async fn cli_command(
-    arg: CliCommand,
-    client: &mut DdkRpcClient<Channel>,
-) -> anyhow::Result<()> {
+pub async fn cli_command<T>(arg: CliCommand, client: &mut DdkRpcClient<T>) -> anyhow::Result<()>
+where
+    T: tonic::client::GrpcService<tonic::body::BoxBody> + Send + 'static,
+    T::Error: Into<Box<dyn std::error::Error + Send + Sync>>,
+    T::ResponseBody: tonic::codegen::Body<Data = tonic::codegen::Bytes> + Send + 'static,
+    <T::ResponseBody as tonic::codegen::Body>::Error:
+        Into<Box<dyn std::error::Error + Send + Sync>> + Send,
+{
     match arg {
         CliCommand::Info => {
             let info = client.info(InfoRequest::default()).await?.into_inner();
@@ -306,9 +309,16 @@ async fn generate_contract_input() -> anyhow::Result<ContractInput> {
     })
 }
 
-async fn interactive_contract_input(
-    client: &mut DdkRpcClient<Channel>,
-) -> anyhow::Result<ContractInput> {
+async fn interactive_contract_input<T>(
+    client: &mut DdkRpcClient<T>,
+) -> anyhow::Result<ContractInput>
+where
+    T: tonic::client::GrpcService<tonic::body::BoxBody> + Send + 'static,
+    T::Error: Into<Box<dyn std::error::Error + Send + Sync>>,
+    T::ResponseBody: tonic::codegen::Body<Data = tonic::codegen::Bytes> + Send + 'static,
+    <T::ResponseBody as tonic::codegen::Body>::Error:
+        Into<Box<dyn std::error::Error + Send + Sync>> + Send,
+{
     let contract_type =
         Select::new("Select type of contract.", vec!["enum", "numerical"]).prompt()?;
 

ddk-node/src/ddkrpc.rs

@@ -255,6 +255,7 @@ pub struct SignRequest {
     #[prost(oneof = "sign_request::Outcome", tags = "2, 3")]
     pub outcome: ::core::option::Option<sign_request::Outcome>,
 }
+/// Nested message and enum types in `SignRequest`.
 pub mod sign_request {
     #[derive(serde::Serialize, serde::Deserialize)]
     #[allow(clippy::derive_partial_eq_without_eq)]

ddk-node/src/lib.rs

@@ -32,6 +32,7 @@ use ddkrpc::{InfoRequest, InfoResponse};
 use opts::NodeOpts;
 use std::str::FromStr;
 use std::sync::Arc;
+use tonic::service::Interceptor;
 use tonic::transport::Server;
 use tonic::Request;
 use tonic::Response;
@@ -40,6 +41,44 @@ use tonic::{async_trait, Code};
 
 type Ddk = DlcDevKit<NostrDlc, PostgresStore, KormirOracleClient>;
 
+/// API key authentication interceptor for gRPC requests.
+///
+/// This interceptor checks for an API key in the `x-api-key` metadata header.
+/// If an API key is configured, all requests must include a matching key.
+/// If no API key is configured, all requests are allowed (for localhost-only deployments).
+#[derive(Clone)]
+pub struct ApiKeyInterceptor {
+    api_key: Option<String>,
+}
+
+impl ApiKeyInterceptor {
+    pub fn new(api_key: Option<String>) -> Self {
+        Self { api_key }
+    }
+}
+
+impl Interceptor for ApiKeyInterceptor {
+    fn call(&mut self, req: Request<()>) -> Result<Request<()>, Status> {
+        // If no API key is configured, allow all requests
+        let Some(expected_key) = &self.api_key else {
+            return Ok(req);
+        };
+
+        // Check for API key in metadata
+        let metadata = req.metadata();
+        match metadata.get("x-api-key") {
+            Some(key) => {
+                if key.to_str().unwrap_or("") == expected_key {
+                    Ok(req)
+                } else {
+                    Err(Status::unauthenticated("Invalid API key"))
+                }
+            }
+            None => Err(Status::unauthenticated("Missing API key")),
+        }
+    }
+}
+
 #[derive(Clone)]
 pub struct DdkNode {
     pub node: Arc<Ddk>,
@@ -53,6 +92,18 @@ impl DdkNode {
     }
 
     pub async fn serve(opts: NodeOpts) -> anyhow::Result<()> {
+        // Validate security configuration
+        let is_localhost =
+            opts.grpc_host.starts_with("127.0.0.1") || opts.grpc_host.starts_with("localhost");
+
+        if !is_localhost && opts.api_key.is_none() {
+            anyhow::bail!(
+                "API key is required when binding to non-localhost address ({}). \
+                Use --api-key to set an API key or bind to 127.0.0.1 for local-only access.",
+                opts.grpc_host
+            );
+        }
+
         let logger = Arc::new(Logger::console(
             "console_logger".to_string(),
             LogLevel::Info,
@@ -102,15 +153,25 @@ impl DdkNode {
         ddk.start()?;
         let node = DdkNode::new(ddk);
         let node_stop = node.node.clone();
+
+        // Create API key interceptor
+        let interceptor = ApiKeyInterceptor::new(opts.api_key.clone());
+
         let server = Server::builder()
-            .add_service(DdkRpcServer::new(node))
+            .add_service(DdkRpcServer::with_interceptor(node, interceptor))
             .serve_with_shutdown(opts.grpc_host.parse()?, async {
                 tokio::signal::ctrl_c()
                     .await
                     .expect("Failed to install Ctrl+C signal handler");
                 let _ = node_stop.stop();
             });
 
+        if opts.api_key.is_some() {
+            tracing::info!("gRPC server starting with API key authentication enabled");
+        } else {
+            tracing::info!("gRPC server starting without authentication (localhost only)");
+        }
+
         server.await?;
 
         Ok(())

ddk-node/src/opts.rs

@@ -30,9 +30,12 @@ pub struct NodeOpts {
     #[arg(help = "Listening port for the lightning network transport.")]
     pub listening_port: u16,
     #[arg(long = "grpc")]
-    #[arg(default_value = "0.0.0.0:3030")]
+    #[arg(default_value = "127.0.0.1:3030")]
     #[arg(help = "Host and port the gRPC server will run on.")]
     pub grpc_host: String,
+    #[arg(long = "api-key")]
+    #[arg(help = "API key for gRPC authentication. Required for non-localhost bindings.")]
+    pub api_key: Option<String>,
     #[arg(long = "esplora")]
     #[arg(default_value = "https://mutinynet.com/api")]
     #[arg(help = "Esplora server to connect to.")]