feat(router): HMAC based Subgraph Auth

ardatan · ardatan · commit f42ad50716d9 · 2025-10-31T15:24:02.000+03:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/lib/executor/Cargo.toml b/lib/executor/Cargo.toml
@@ -49,6 +49,9 @@ itoa = "1.0.15"
 ryu = "1.0.20"
 indexmap = "2.10.0"
 bumpalo = "3.19.0"
+hmac = "0.12.1"
+sha2 = "0.10.9"
+hex = "0.4.3"
 
 [dev-dependencies]
 subgraphs = { path = "../../bench/subgraphs" }
diff --git a/lib/executor/src/execution/plan.rs b/lib/executor/src/execution/plan.rs
@@ -708,6 +708,7 @@ impl<'exec, 'req> Executor<'exec, 'req> {
             representations,
             headers: headers_map,
             extensions: None,
+            client_request: self.client_request,
         };
 
         if let Some(jwt_forwarding_plan) = &self.jwt_forwarding_plan {
@@ -722,7 +723,7 @@ impl<'exec, 'req> Executor<'exec, 'req> {
             subgraph_name: node.service_name.clone(),
             response: self
                 .executors
-                .execute(&node.service_name, subgraph_request, self.client_request)
+                .execute(&node.service_name, subgraph_request)
                 .await
                 .into(),
         }))
diff --git a/lib/executor/src/executors/common.rs b/lib/executor/src/executors/common.rs
@@ -5,11 +5,13 @@ use bytes::Bytes;
 use http::HeaderMap;
 use sonic_rs::Value;
 
+use crate::execution::client_request_details::ClientRequestDetails;
+
 #[async_trait]
 pub trait SubgraphExecutor {
-    async fn execute<'a>(
+    async fn execute<'exec, 'req>(
         &self,
-        execution_request: HttpExecutionRequest<'a>,
+        execution_request: HttpExecutionRequest<'exec, 'req>,
     ) -> HttpExecutionResponse;
 
     fn to_boxed_arc<'a>(self) -> Arc<Box<dyn SubgraphExecutor + Send + Sync + 'a>>
@@ -26,18 +28,19 @@ pub type SubgraphExecutorBoxedArc = Arc<Box<SubgraphExecutorType>>;
 
 pub type SubgraphRequestExtensions = HashMap<String, Value>;
 
-pub struct HttpExecutionRequest<'a> {
-    pub query: &'a str,
+pub struct HttpExecutionRequest<'exec, 'req> {
+    pub query: &'exec str,
     pub dedupe: bool,
-    pub operation_name: Option<&'a str>,
+    pub operation_name: Option<&'exec str>,
     // TODO: variables could be stringified before even executing the request
-    pub variables: Option<HashMap<&'a str, &'a sonic_rs::Value>>,
+    pub variables: Option<HashMap<&'exec str, &'exec sonic_rs::Value>>,
     pub headers: HeaderMap,
     pub representations: Option<Vec<u8>>,
     pub extensions: Option<SubgraphRequestExtensions>,
+    pub client_request: &'exec ClientRequestDetails<'exec, 'req>,
 }
 
-impl HttpExecutionRequest<'_> {
+impl HttpExecutionRequest<'_, '_> {
     pub fn add_request_extensions_field(&mut self, key: String, value: Value) {
         self.extensions
             .get_or_insert_with(HashMap::new)
diff --git a/lib/executor/src/executors/error.rs b/lib/executor/src/executors/error.rs
@@ -20,6 +20,10 @@ pub enum SubgraphExecutorError {
     RequestFailure(String, String),
     #[error("Failed to serialize variable \"{0}\": {1}")]
     VariablesSerializationFailure(String, String),
+    #[error("HMAC signature error: {0}")]
+    HMACSignatureError(String),
+    #[error("Failed to serialize extension \"{0}\": {1}")]
+    ExtensionSerializationFailure(String, String),
 }
 
 impl From<SubgraphExecutorError> for GraphQLError {
@@ -61,6 +65,10 @@ impl SubgraphExecutorError {
             SubgraphExecutorError::VariablesSerializationFailure(_, _) => {
                 "SUBGRAPH_VARIABLES_SERIALIZATION_FAILURE"
             }
+            SubgraphExecutorError::ExtensionSerializationFailure(_, _) => {
+                "SUBGRAPH_EXTENSION_SERIALIZATION_FAILURE"
+            }
+            SubgraphExecutorError::HMACSignatureError(_) => "SUBGRAPH_HMAC_SIGNATURE_ERROR",
         }
     }
 }
diff --git a/lib/executor/src/executors/http.rs b/lib/executor/src/executors/http.rs
@@ -1,21 +1,25 @@
+use std::collections::BTreeMap;
 use std::sync::Arc;
 
 use crate::executors::common::HttpExecutionResponse;
 use crate::executors::dedupe::{request_fingerprint, ABuildHasher, SharedResponse};
 use dashmap::DashMap;
+use hive_router_config::hmac_signature::BooleanOrExpression;
 use hive_router_config::HiveRouterConfig;
 use tokio::sync::OnceCell;
 
 use async_trait::async_trait;
 
 use bytes::{BufMut, Bytes, BytesMut};
+use hmac::{Hmac, Mac};
 use http::HeaderMap;
 use http::HeaderValue;
 use http_body_util::BodyExt;
 use http_body_util::Full;
 use hyper::Version;
 use hyper_tls::HttpsConnector;
 use hyper_util::client::legacy::{connect::HttpConnector, Client};
+use sha2::Sha256;
 use tokio::sync::Semaphore;
 use tracing::debug;
 
@@ -27,6 +31,7 @@ use crate::utils::consts::COLON;
 use crate::utils::consts::COMMA;
 use crate::utils::consts::QUOTE;
 use crate::{executors::common::SubgraphExecutor, json_writer::write_and_escape_string};
+use vrl::core::Value as VrlValue;
 
 #[derive(Debug)]
 pub struct HTTPSubgraphExecutor {
@@ -41,9 +46,12 @@ pub struct HTTPSubgraphExecutor {
 
 const FIRST_VARIABLE_STR: &[u8] = b",\"variables\":{";
 const FIRST_QUOTE_STR: &[u8] = b"{\"query\":";
+const FIRST_EXTENSION_STR: &[u8] = b",\"extensions\":{";
 
 pub type HttpClient = Client<HttpsConnector<HttpConnector>, Full<Bytes>>;
 
+type HmacSha256 = Hmac<Sha256>;
+
 impl HTTPSubgraphExecutor {
     pub fn new(
         subgraph_name: String,
@@ -74,9 +82,9 @@ impl HTTPSubgraphExecutor {
         }
     }
 
-    fn build_request_body<'a>(
+    fn build_request_body<'exec, 'req>(
         &self,
-        execution_request: &HttpExecutionRequest<'a>,
+        execution_request: &HttpExecutionRequest<'exec, 'req>,
     ) -> Result<Vec<u8>, SubgraphExecutorError> {
         let mut body = Vec::with_capacity(4096);
         body.put(FIRST_QUOTE_STR);
@@ -118,13 +126,90 @@ impl HTTPSubgraphExecutor {
             body.put(CLOSE_BRACE);
         }
 
-        if let Some(extensions) = &execution_request.extensions {
-            if !extensions.is_empty() {
-                let as_value = sonic_rs::to_value(extensions).unwrap();
+        let should_sign_hmac = match &self.config.hmac_signature.enabled {
+            BooleanOrExpression::Boolean(b) => *b,
+            BooleanOrExpression::Expression(expr) => {
+                // .subgraph
+                let subgraph_value = VrlValue::Object(BTreeMap::from([(
+                    "name".into(),
+                    VrlValue::Bytes(Bytes::from(self.subgraph_name.to_owned())),
+                )]));
+                // .request
+                let request_value: VrlValue = execution_request.client_request.into();
+                let target_value = VrlValue::Object(BTreeMap::from([
+                    ("subgraph".into(), subgraph_value),
+                    ("request".into(), request_value),
+                ]));
+                let result = expr.execute_with_value(target_value);
+                match result {
+                    Ok(VrlValue::Boolean(b)) => b,
+                    Ok(_) => {
+                        return Err(SubgraphExecutorError::HMACSignatureError(
+                            "HMAC signature expression did not evaluate to a boolean".to_string(),
+                        ));
+                    }
+                    Err(e) => {
+                        return Err(SubgraphExecutorError::HMACSignatureError(format!(
+                            "HMAC signature expression evaluation error: {}",
+                            e
+                        )));
+                    }
+                }
+            }
+        };
 
-                body.put(COMMA);
-                body.put("\"extensions\":".as_bytes());
-                body.extend_from_slice(as_value.to_string().as_bytes());
+        let hmac_signature_ext = if should_sign_hmac {
+            let mut mac = HmacSha256::new_from_slice(self.config.hmac_signature.secret.as_bytes())
+                .map_err(|e| {
+                    SubgraphExecutorError::HMACSignatureError(format!(
+                        "Failed to create HMAC instance: {}",
+                        e
+                    ))
+                })?;
+            let mut body_without_extensions = body.clone();
+            body_without_extensions.put(CLOSE_BRACE);
+            mac.update(&body_without_extensions);
+            let result = mac.finalize();
+            let result_bytes = result.into_bytes();
+            Some(result_bytes)
+        } else {
+            None
+        };
+
+        if let Some(extensions) = &execution_request.extensions {
+            let mut first = true;
+            for (extension_name, extension_value) in extensions {
+                if first {
+                    body.put(COMMA);
+                    body.put(FIRST_EXTENSION_STR);
+                    first = false;
+                } else {
+                    body.put(COMMA);
+                }
+                body.put(QUOTE);
+                body.put(extension_name.as_bytes());
+                body.put(QUOTE);
+                body.put(COLON);
+                let value_str = sonic_rs::to_string(extension_value).map_err(|err| {
+                    SubgraphExecutorError::ExtensionSerializationFailure(
+                        extension_name.to_string(),
+                        err.to_string(),
+                    )
+                })?;
+                body.put(value_str.as_bytes());
+            }
+            if let Some(hmac_bytes) = hmac_signature_ext {
+                if first {
+                    body.put(COMMA);
+                    body.put(FIRST_EXTENSION_STR);
+                } else {
+                    body.put(COMMA);
+                }
+                body.put(self.config.hmac_signature.extension_name.as_bytes());
+                let hmac_hex = hex::encode(hmac_bytes);
+                body.put(QUOTE);
+                body.put(hmac_hex.as_bytes());
+                body.put(QUOTE);
             }
         }
 
@@ -210,9 +295,9 @@ impl HTTPSubgraphExecutor {
 #[async_trait]
 impl SubgraphExecutor for HTTPSubgraphExecutor {
     #[tracing::instrument(skip_all, fields(subgraph_name = self.subgraph_name))]
-    async fn execute<'a>(
+    async fn execute<'exec, 'req>(
         &self,
-        execution_request: HttpExecutionRequest<'a>,
+        execution_request: HttpExecutionRequest<'exec, 'req>,
     ) -> HttpExecutionResponse {
         let body = match self.build_request_body(&execution_request) {
             Ok(body) => body,
diff --git a/lib/executor/src/executors/map.rs b/lib/executor/src/executors/map.rs
@@ -105,13 +105,12 @@ impl SubgraphExecutorMap {
         Ok(subgraph_executor_map)
     }
 
-    pub async fn execute<'a, 'req>(
+    pub async fn execute<'exec, 'req>(
         &self,
         subgraph_name: &str,
-        execution_request: HttpExecutionRequest<'a>,
-        client_request: &ClientRequestDetails<'a, 'req>,
+        execution_request: HttpExecutionRequest<'exec, 'req>,
     ) -> HttpExecutionResponse {
-        match self.get_or_create_executor(subgraph_name, client_request) {
+        match self.get_or_create_executor(subgraph_name, execution_request.client_request) {
             Ok(Some(executor)) => executor.execute(execution_request).await,
             Err(err) => {
                 error!(
diff --git a/lib/router-config/src/hmac_signature.rs b/lib/router-config/src/hmac_signature.rs
@@ -0,0 +1,58 @@
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::primitives::expression::Expression;
+
+#[derive(Debug, Clone, Deserialize, Serialize, Default, JsonSchema)]
+pub struct HMACSignatureConfig {
+    // Whether to sign outgoing requests with HMAC signatures.
+    // Can be a boolean or a VRL expression that evaluates to a boolean.
+    // Example:
+    // hmac_signature:
+    //  enabled: true
+    // or enable it conditionally based on the subgraph name:
+    // hmac_signature:
+    //  enabled: |
+    //    if .subgraph.name == "users" {
+    //      true
+    //    } else {
+    //      false
+    //    }
+    pub enabled: BooleanOrExpression,
+
+    // The secret key used for HMAC signing and verification.
+    // It should be a random, opaque string shared between the Hive Router and the subgraph services.
+    pub secret: String,
+
+    // The key name used in the extensions field of the outgoing requests to store the HMAC signature.
+    #[serde(default = "default_extension_name")]
+    pub extension_name: String,
+}
+
+fn default_extension_name() -> String {
+    "hmac_signature".to_string()
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
+pub enum BooleanOrExpression {
+    Boolean(bool),
+    Expression(Expression),
+}
+
+impl Default for BooleanOrExpression {
+    fn default() -> Self {
+        BooleanOrExpression::Boolean(false)
+    }
+}
+
+impl HMACSignatureConfig {
+    pub fn is_disabled(&self) -> bool {
+        match &self.enabled {
+            BooleanOrExpression::Boolean(b) => !*b,
+            BooleanOrExpression::Expression(_) => {
+                // If it's an expression, we consider it enabled for the purpose of this check.
+                false
+            }
+        }
+    }
+}
diff --git a/lib/router-config/src/lib.rs b/lib/router-config/src/lib.rs
@@ -3,6 +3,7 @@ pub mod csrf;
 mod env_overrides;
 pub mod graphiql;
 pub mod headers;
+pub mod hmac_signature;
 pub mod http_server;
 pub mod jwt_auth;
 pub mod log;
@@ -92,6 +93,12 @@ pub struct HiveRouterConfig {
     /// Configuration for overriding labels.
     #[serde(default, skip_serializing_if = "HashMap::is_empty")]
     pub override_labels: OverrideLabelsConfig,
+
+    #[serde(
+        default,
+        skip_serializing_if = "hmac_signature::HMACSignatureConfig::is_disabled"
+    )]
+    pub hmac_signature: hmac_signature::HMACSignatureConfig,
 }
 
 #[derive(Debug, thiserror::Error)]

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,10 @@ pub enum SubgraphExecutorError {`
`20`	`20`	`RequestFailure(String, String),`
`21`	`21`	`#[error("Failed to serialize variable \"{0}\": {1}")]`
`22`	`22`	`VariablesSerializationFailure(String, String),`
	`23`	`+ #[error("HMAC signature error: {0}")]`
	`24`	`+ HMACSignatureError(String),`
	`25`	`+ #[error("Failed to serialize extension \"{0}\": {1}")]`
	`26`	`+ ExtensionSerializationFailure(String, String),`
`23`	`27`	`}`
`24`	`28`
`25`	`29`	`impl From<SubgraphExecutorError> for GraphQLError {`
`@@ -61,6 +65,10 @@ impl SubgraphExecutorError {`
`61`	`65`	`SubgraphExecutorError::VariablesSerializationFailure(_, _) => {`
`62`	`66`	`"SUBGRAPH_VARIABLES_SERIALIZATION_FAILURE"`
`63`	`67`	`}`
	`68`	`+ SubgraphExecutorError::ExtensionSerializationFailure(_, _) => {`
	`69`	`+ "SUBGRAPH_EXTENSION_SERIALIZATION_FAILURE"`
	`70`	`+ }`
	`71`	`+ SubgraphExecutorError::HMACSignatureError(_) => "SUBGRAPH_HMAC_SIGNATURE_ERROR",`
`64`	`72`	`}`
`65`	`73`	`}`
`66`	`74`	`}`