Prevent relay/gateway self-loop in payjoin-service

OHTTP privacy guarantees rely on the assumption that the relay and
gateway operate independently from each other. The payjoin service runs
both OHTTP relay and the directory gateway in the same process, so we
make a best-effort attempt to detect requests from the same instance via
a sentinel header. This check eliminates a potential footgun for service
operators and payjoin implementers.

Author: spacebear21

Cargo-minimal.lock

@@ -2518,6 +2518,7 @@ dependencies = [
  "http-body-util",
  "hyper",
  "hyper-util",
+ "ohttp-relay",
  "payjoin",
  "prometheus",
  "rand 0.8.5",
@@ -2562,6 +2563,7 @@ dependencies = [
  "config",
  "ohttp-relay",
  "payjoin-directory",
+ "rand 0.8.5",
  "rustls 0.23.31",
  "serde",
  "tokio",

Cargo-recent.lock

@@ -2518,6 +2518,7 @@ dependencies = [
  "http-body-util",
  "hyper",
  "hyper-util",
+ "ohttp-relay",
  "payjoin",
  "prometheus",
  "rand 0.8.5",
@@ -2562,6 +2563,7 @@ dependencies = [
  "config",
  "ohttp-relay",
  "payjoin-directory",
+ "rand 0.8.5",
  "rustls 0.23.31",
  "serde",
  "tokio",

ohttp-relay/Cargo.toml

@@ -23,6 +23,7 @@ _test-util = []
 byteorder = "1.5.0"
 bytes = "1.10.1"
 futures = { version = "0.3.31", optional = true }
+hex = { package = "hex-conservative", version = "0.1.1" }
 http = "1.3.1"
 http-body-util = "0.1.3"
 hyper = { version = "1.6.0", features = ["http1", "server"] }
@@ -48,7 +49,6 @@ tracing = "0.1.41"
 tracing-subscriber = { version = "0.3.20", features = ["env-filter"] }
 
 [dev-dependencies]
-hex = { package = "hex-conservative", version = "0.1.1" }
 mockito = "1.7.0"
 rcgen = "0.12"
 reqwest = { version = "0.12.23", default-features = false, features = [

ohttp-relay/src/lib.rs

@@ -34,6 +34,9 @@ mod gateway_prober;
 #[cfg(feature = "_test-util")]
 pub mod gateway_prober;
 mod gateway_uri;
+pub mod sentinel;
+pub use sentinel::{InvalidHeader, SentinelTag};
+
 use crate::error::{BoxError, Error};
 
 #[cfg(any(feature = "connect-bootstrap", feature = "ws-bootstrap"))]
@@ -52,7 +55,7 @@ pub async fn listen_tcp(
     let addr = SocketAddr::from(([0, 0, 0, 0], port));
     let listener = TcpListener::bind(addr).await?;
     println!("OHTTP relay listening on tcp://{}", addr);
-    ohttp_relay(listener, RelayConfig::new_with_default_client(gateway_origin)).await
+    ohttp_relay(listener, RelayConfig::new_with_default_client(gateway_origin, None)).await
 }
 
 #[instrument]
@@ -62,7 +65,7 @@ pub async fn listen_socket(
 ) -> Result<tokio::task::JoinHandle<Result<(), BoxError>>, BoxError> {
     let listener = UnixListener::bind(socket_path)?;
     info!("OHTTP relay listening on socket: {}", socket_path);
-    ohttp_relay(listener, RelayConfig::new_with_default_client(gateway_origin)).await
+    ohttp_relay(listener, RelayConfig::new_with_default_client(gateway_origin, None)).await
 }
 
 #[cfg(feature = "_test-util")]
@@ -73,7 +76,7 @@ pub async fn listen_tcp_on_free_port(
     let listener = tokio::net::TcpListener::bind("[::]:0").await?;
     let port = listener.local_addr()?.port();
     println!("OHTTP relay binding to port {}", listener.local_addr()?);
-    let config = RelayConfig::new(default_gateway, root_store);
+    let config = RelayConfig::new(default_gateway, root_store, None);
     let handle = ohttp_relay(listener, config).await?;
     Ok((port, handle))
 }
@@ -83,17 +86,25 @@ struct RelayConfig {
     default_gateway: GatewayUri,
     client: HttpClient,
     prober: Prober,
+    sentinel_tag: Option<SentinelTag>,
 }
 
 impl RelayConfig {
-    fn new_with_default_client(default_gateway: GatewayUri) -> Self {
-        Self::new(default_gateway, HttpClient::default())
+    fn new_with_default_client(
+        default_gateway: GatewayUri,
+        sentinel_tag: Option<SentinelTag>,
+    ) -> Self {
+        Self::new(default_gateway, HttpClient::default(), sentinel_tag)
     }
 
-    fn new(default_gateway: GatewayUri, into_client: impl Into<HttpClient>) -> Self {
+    fn new(
+        default_gateway: GatewayUri,
+        into_client: impl Into<HttpClient>,
+        sentinel_tag: Option<SentinelTag>,
+    ) -> Self {
         let client = into_client.into();
         let prober = Prober::new_with_client(client.clone());
-        RelayConfig { default_gateway, client, prober }
+        RelayConfig { default_gateway, client, prober, sentinel_tag }
     }
 }
 
@@ -105,21 +116,24 @@ pub struct Service {
 impl Service {
     fn from_config(config: Arc<RelayConfig>) -> Self { Self { config } }
 
-    pub async fn new() -> Self {
+    pub async fn new(sentinel_tag: SentinelTag) -> Self {
         // The default gateway is hardcoded because it is obsolete and required only for backwards
         // compatibility.
         // The new mechanism for specifying a custom gateway is via RFC 9540 using
         // `/.well-known/ohttp-gateway` request paths.
         let gateway_origin = GatewayUri::from_str(DEFAULT_GATEWAY).expect("valid gateway uri");
-        let config = RelayConfig::new_with_default_client(gateway_origin);
+        let config = RelayConfig::new_with_default_client(gateway_origin, Some(sentinel_tag));
         config.prober.assert_opt_in(&config.default_gateway).await;
         Self { config: Arc::new(config) }
     }
 
     #[cfg(feature = "_test-util")]
-    pub async fn new_with_roots(root_store: rustls::RootCertStore) -> Self {
+    pub async fn new_with_roots(
+        root_store: rustls::RootCertStore,
+        sentinel_tag: SentinelTag,
+    ) -> Self {
         let gateway_origin = GatewayUri::from_str(DEFAULT_GATEWAY).expect("valid gateway uri");
-        let config = RelayConfig::new(gateway_origin, root_store);
+        let config = RelayConfig::new(gateway_origin, root_store, Some(sentinel_tag));
         config.prober.assert_opt_in(&config.default_gateway).await;
         Self { config: Arc::new(config) }
     }
@@ -319,7 +333,8 @@ where
     B: hyper::body::Body<Data = Bytes> + Send + Debug + 'static,
     B::Error: Into<BoxError>,
 {
-    let fwd_req = into_forward_req(req, gateway).await?;
+    let fwd_req = into_forward_req(req, gateway, config.sentinel_tag.as_ref()).await?;
+
     forward_request(fwd_req, config).await.map(|res| {
         let (parts, body) = res.into_parts();
         let boxed_body = BoxBody::new(body);
@@ -332,6 +347,7 @@ where
 async fn into_forward_req<B>(
     req: Request<B>,
     gateway_origin: GatewayUri,
+    sentinel_tag: Option<&SentinelTag>,
 ) -> Result<Request<BoxBody<Bytes, hyper::Error>>, Error>
 where
     B: hyper::body::Body<Data = Bytes> + Send + Debug + 'static,
@@ -359,6 +375,10 @@ where
     let bytes =
         body.collect().await.map_err(|e| Error::BadRequest(e.into().to_string()))?.to_bytes();
 
+    if let Some(tag) = sentinel_tag {
+        builder = builder.header(sentinel::HEADER_NAME, tag.to_header_value());
+    }
+
     builder.body(full(bytes)).map_err(|e| Error::InternalServerError(Box::new(e)))
 }
 

ohttp-relay/src/sentinel.rs

@@ -0,0 +1,75 @@
+use hex::{DisplayHex, FromHex};
+
+/// HTTP header name for the sentinel tag.
+pub const HEADER_NAME: &str = "x-pj-sentinel";
+
+#[derive(Debug)]
+pub struct InvalidHeader;
+
+impl std::fmt::Display for InvalidHeader {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "malformed sentinel header")
+    }
+}
+
+impl std::error::Error for InvalidHeader {}
+
+/// A random 32-byte tag shared between relay and gateway for same-instance detection.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct SentinelTag([u8; 32]);
+
+impl SentinelTag {
+    /// Creates a new sentinel tag from raw bytes.
+    pub fn new(bytes: [u8; 32]) -> Self { Self(bytes) }
+
+    /// Returns the tag as a hex string for use in HTTP headers.
+    pub fn to_header_value(&self) -> String { self.0.to_lower_hex_string() }
+}
+
+/// Verifies a sentinel header value against a tag.
+///
+/// Note that incoming requests should be **rejected** when this function returns `Ok(true)`,
+/// as that would indicate the relay and gateway are the same instance.
+pub fn verify(tag: &SentinelTag, header_value: &str) -> Result<bool, InvalidHeader> {
+    let header_bytes = <[u8; 32]>::from_hex(header_value).map_err(|_| InvalidHeader)?;
+    Ok(tag.0 == header_bytes)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn same_tag_matches() {
+        let tag = SentinelTag::new([0u8; 32]);
+        let header = tag.to_header_value();
+        assert!(verify(&tag, &header).unwrap(), "same tag should match");
+    }
+
+    #[test]
+    fn different_tag_does_not_match() {
+        let tag1 = SentinelTag::new([0u8; 32]);
+        let tag2 = SentinelTag::new([1u8; 32]);
+        let header = tag1.to_header_value();
+        assert!(!verify(&tag2, &header).unwrap(), "different tag should not match");
+    }
+
+    #[test]
+    fn malformed_header_returns_err() {
+        let tag = SentinelTag::new([0u8; 32]);
+        assert!(verify(&tag, "invalid").is_err(), "non-hex should error");
+        assert!(verify(&tag, "abcd").is_err(), "wrong length should error");
+        assert!(verify(&tag, "zz").is_err(), "invalid hex chars should error");
+    }
+
+    #[test]
+    fn header_format() {
+        let tag = SentinelTag::new([0xab; 32]);
+        let header = tag.to_header_value();
+
+        // Should be 64 hex characters (32 bytes)
+        assert_eq!(header.len(), 64, "header should be 64 hex characters");
+        assert!(header.chars().all(|c| c.is_ascii_hexdigit()), "header should be valid hex");
+        assert_eq!(header, "ab".repeat(32), "header should match expected hex");
+    }
+}

payjoin-directory/Cargo.toml

@@ -29,6 +29,7 @@ http-body-util = "0.1.3"
 hyper = { version = "1.6.0", features = ["http1", "server"] }
 hyper-util = { version = "0.1.16", features = ["tokio", "service"] }
 ohttp = { package = "bitcoin-ohttp", version = "0.6.0" }
+ohttp-relay = { path = "../ohttp-relay" }
 payjoin = { version = "1.0.0-rc.1", features = [
   "directory",
 ], default-features = false }

payjoin-directory/src/lib.rs

@@ -24,6 +24,8 @@ use tracing::{debug, error, trace, warn};
 pub use crate::db::files::Db as FilesDb;
 use crate::db::Db;
 pub mod key_config;
+use ohttp_relay::SentinelTag;
+
 pub use crate::key_config::*;
 use crate::metrics::Metrics;
 
@@ -68,6 +70,7 @@ pub struct Service<D: Db> {
     db: D,
     ohttp: ohttp::Server,
     metrics: Metrics,
+    sentinel_tag: Option<SentinelTag>,
 }
 
 impl<D: Db, B> tower::Service<Request<B>> for Service<D>
@@ -91,8 +94,13 @@ where
 }
 
 impl<D: Db> Service<D> {
-    pub fn new(db: D, ohttp: ohttp::Server, metrics: Metrics) -> Self {
-        Self { db, ohttp, metrics }
+    pub fn new(
+        db: D,
+        ohttp: ohttp::Server,
+        metrics: Metrics,
+        sentinel_tag: Option<SentinelTag>,
+    ) -> Self {
+        Self { db, ohttp, metrics, sentinel_tag }
     }
 
     #[cfg(feature = "_manual-tls")]
@@ -194,12 +202,20 @@ impl<D: Db> Service<D> {
 
         let path_segments: Vec<&str> = path.split('/').collect();
         debug!("Service::serve_request: {:?}", &path_segments);
+
+        let sentinel_header = parts
+            .headers
+            .get(ohttp_relay::sentinel::HEADER_NAME)
+            .and_then(|v| v.to_str().ok())
+            .map(String::from);
+
         let mut response = match (parts.method, path_segments.as_slice()) {
             (Method::POST, ["", ".well-known", "ohttp-gateway"]) =>
-                self.handle_ohttp_gateway(body).await,
+                self.handle_ohttp_gateway(body, sentinel_header.as_deref()).await,
             (Method::GET, ["", ".well-known", "ohttp-gateway"]) =>
                 self.handle_ohttp_gateway_get(&query).await,
-            (Method::POST, ["", ""]) => self.handle_ohttp_gateway(body).await,
+            (Method::POST, ["", ""]) =>
+                self.handle_ohttp_gateway(body, sentinel_header.as_deref()).await,
             (Method::GET, ["", "ohttp-keys"]) => self.get_ohttp_keys().await,
             (Method::POST, ["", id]) => self.post_fallback_v1(id, query, body).await,
             (Method::GET, ["", "health"]) => health_check().await,
@@ -217,17 +233,40 @@ impl<D: Db> Service<D> {
     async fn handle_ohttp_gateway<B>(
         &self,
         body: B,
+        sentinel_header: Option<&str>,
     ) -> Result<Response<BoxBody<Bytes, hyper::Error>>, HandlerError>
     where
         B: Body<Data = Bytes> + Send + 'static,
         B::Error: Into<BoxError>,
     {
-        // decapsulate
         let ohttp_body = body
             .collect()
             .await
             .map_err(|e| HandlerError::BadRequest(anyhow::anyhow!(e.into())))?
             .to_bytes();
+
+        // Best-effort validation that the relay and gateway aren't on the same
+        // payjoin-service instance
+        if let Some(tag) = &self.sentinel_tag {
+            if let Some(header_value) = sentinel_header {
+                match ohttp_relay::sentinel::verify(tag, header_value) {
+                    Ok(false) => {} // Allow
+                    Ok(true) => {
+                        warn!("Rejected OHTTP request from same-instance relay");
+                        return Err(HandlerError::Forbidden(anyhow::anyhow!(
+                            "Relay and gateway must be operated by different entities"
+                        )));
+                    }
+                    Err(_) => {
+                        warn!("Rejected OHTTP request with malformed sentinel header");
+                        return Err(HandlerError::BadRequest(anyhow::anyhow!(
+                            "Malformed sentinel header"
+                        )));
+                    }
+                }
+            }
+        }
+
         let (bhttp_req, res_ctx) = self
             .ohttp
             .decapsulate(&ohttp_body)
@@ -577,6 +616,7 @@ enum HandlerError {
     SenderGone(anyhow::Error),
     OhttpKeyRejection(anyhow::Error),
     BadRequest(anyhow::Error),
+    Forbidden(anyhow::Error),
 }
 
 impl HandlerError {
@@ -609,6 +649,10 @@ impl HandlerError {
                 warn!("Bad request: {}", e);
                 *res.status_mut() = StatusCode::BAD_REQUEST
             }
+            HandlerError::Forbidden(e) => {
+                warn!("Forbidden: {}", e);
+                *res.status_mut() = StatusCode::FORBIDDEN
+            }
         };
 
         res

payjoin-directory/src/main.rs

@@ -30,7 +30,7 @@ async fn main() -> Result<(), BoxError> {
         .await
         .expect("Failed to initialize persistent storage");
 
-    let service = Service::new(db, ohttp.into(), metrics);
+    let service = Service::new(db, ohttp.into(), metrics, None);
 
     // Start metrics server in the background
     if let Some(addr) = config.metrics_listen_addr {

payjoin-service/Cargo.toml

@@ -20,6 +20,7 @@ _manual-tls = ["dep:axum-server", "dep:rustls", "ohttp-relay/_test-util"]
 [dependencies]
 anyhow = "1.0"
 axum = "0.8"
+rand = "0.8"
 axum-server = { version = "0.7", features = [
   "tls-rustls-no-provider",
 ], optional = true }