diff --git a/crates/clipsync-core/src/pairing.rs b/crates/clipsync-core/src/pairing.rs index 22f0c6d..5a44088 100644 --- a/crates/clipsync-core/src/pairing.rs +++ b/crates/clipsync-core/src/pairing.rs @@ -170,12 +170,18 @@ pub async fn join_room( )) })?; if !resp.status().is_success() { + let throttled = resp.status() == reqwest::StatusCode::TOO_MANY_REQUESTS; let body = resp.text().await.unwrap_or_default(); if body.contains("code_invalid") || body.contains("code_expired") { return Err(CoreError::Pairing( "unknown or expired pairing code; on the other device run `clipsync room create` again".into(), )); } + if throttled || body.contains("too_many_attempts") { + return Err(CoreError::Pairing( + "the relay is limiting pairing attempts; wait a few minutes, then run `clipsync room create` again on the other device and retry with the new code".into(), + )); + } return Err(CoreError::Pairing(format!("join failed: {body}"))); } let joined: JoinPairingResponse = resp.json().await?; @@ -641,10 +647,14 @@ mod tests { let store = LocalStore::open_from(crate::AppPaths::from_root(directory.path().into())).unwrap(); let identity = DeviceIdentity::from_bytes("http-failure".into(), [31; 32]); - for body in [ - "code_invalid", - "code_expired", - "busy: joiner already connected", + for (status, body) in [ + (StatusCode::CONFLICT, "code_invalid"), + (StatusCode::CONFLICT, "code_expired"), + (StatusCode::CONFLICT, "busy: joiner already connected"), + ( + StatusCode::TOO_MANY_REQUESTS, + r#"{"code":"too_many_attempts","message":"pairing attempt limit reached"}"#, + ), ] { let server = crate::test_relay::Server::http( Router::new() @@ -654,7 +664,7 @@ mod tests { ) .route( "/v1/pairing/join", - post(move || async move { (StatusCode::CONFLICT, body) }), + post(move || async move { (status, body) }), ), ) .await; @@ -669,6 +679,8 @@ mod tests { .unwrap_err(); if body.starts_with("code_") { assert!(join.to_string().contains("unknown or expired pairing code")); + } else if status == StatusCode::TOO_MANY_REQUESTS { + assert!(join.to_string().contains("limiting pairing attempts")); } else { assert!(join.to_string().contains(body)); } diff --git a/crates/clipsync-relay/src/client_ip.rs b/crates/clipsync-relay/src/client_ip.rs new file mode 100644 index 0000000..45342c7 --- /dev/null +++ b/crates/clipsync-relay/src/client_ip.rs @@ -0,0 +1,79 @@ +// Copyright the ClipSync contributors. +// SPDX-License-Identifier: MIT +//! Client address resolution for per-client limits. +//! +//! The TCP peer address is authoritative by default. `X-Forwarded-For` is read +//! only when the peer itself is an operator-configured trusted proxy, and then +//! only up to the rightmost hop that is not a trusted proxy: every entry to the +//! left of that hop was written by the client and can be forged. + +use std::net::{IpAddr, SocketAddr}; + +use axum::http::HeaderMap; +use ipnet::IpNet; + +const X_FORWARDED_FOR: &str = "x-forwarded-for"; + +#[derive(Clone, Debug, Default)] +pub(crate) struct TrustedProxies(Vec); + +impl TrustedProxies { + pub(crate) fn new(proxies: Vec) -> Self { + Self(proxies.into_iter().map(|net| net.trunc()).collect()) + } + + fn contains(&self, ip: IpAddr) -> bool { + self.0.iter().any(|net| net.contains(&ip)) + } + + /// Resolve the client address of a request received from `peer`. + pub(crate) fn client_ip(&self, peer: IpAddr, headers: &HeaderMap) -> IpAddr { + let peer = peer.to_canonical(); + if !self.contains(peer) { + return peer; + } + // Each proxy appends the address it received the request from, so walk + // from the right. A malformed hop ends the walk at the nearest trusted + // proxy: nothing to its left can be attributed reliably. + let hops: Vec> = headers + .get_all(X_FORWARDED_FOR) + .iter() + .flat_map(|value| match value.to_str() { + Ok(list) => list.split(',').map(Some).collect::>(), + Err(_) => vec![None], + }) + .collect(); + let mut client = peer; + for hop in hops.into_iter().rev() { + let Some(ip) = hop.and_then(parse_hop) else { + break; + }; + client = ip.to_canonical(); + if !self.contains(client) { + break; + } + } + client + } +} + +fn parse_hop(hop: &str) -> Option { + let hop = hop.trim(); + hop.parse::() + .ok() + .or_else(|| hop.parse::().ok().map(|addr| addr.ip())) +} + +/// Parse one `CLIPSYNC_RELAY_TRUSTED_PROXIES` entry: a CIDR range or a single address. +pub(crate) fn parse_trusted_proxy(value: &str) -> Result { + let value = value.trim(); + value + .parse::() + .or_else(|_| value.parse::().map(IpNet::from)) + .map_err(|_| format!("`{value}` is not an IP address or CIDR range")) +} + +#[cfg(test)] +#[cfg_attr(coverage_nightly, coverage(off))] +#[path = "client_ip_tests.rs"] +mod tests; diff --git a/crates/clipsync-relay/src/client_ip_tests.rs b/crates/clipsync-relay/src/client_ip_tests.rs new file mode 100644 index 0000000..cd92c77 --- /dev/null +++ b/crates/clipsync-relay/src/client_ip_tests.rs @@ -0,0 +1,99 @@ +// Copyright the ClipSync contributors. +// SPDX-License-Identifier: MIT +use super::*; +use axum::http::HeaderValue; + +fn proxies(entries: &[&str]) -> TrustedProxies { + TrustedProxies::new( + entries + .iter() + .map(|entry| parse_trusted_proxy(entry).unwrap()) + .collect(), + ) +} + +fn forwarded(values: &[&[u8]]) -> HeaderMap { + let mut headers = HeaderMap::new(); + for value in values { + headers.append(X_FORWARDED_FOR, HeaderValue::from_bytes(value).unwrap()); + } + headers +} + +fn ip(value: &str) -> IpAddr { + value.parse().unwrap() +} + +#[test] +fn forwarded_header_is_ignored_without_trusted_proxy_configuration() { + let headers = forwarded(&[b"203.0.113.9"]); + assert_eq!( + TrustedProxies::default().client_ip(ip("127.0.0.1"), &headers), + ip("127.0.0.1") + ); +} + +#[test] +fn forwarded_header_is_ignored_from_an_untrusted_peer() { + let trusted = proxies(&["10.0.0.0/8"]); + let headers = forwarded(&[b"203.0.113.9"]); + assert_eq!( + trusted.client_ip(ip("198.51.100.4"), &headers), + ip("198.51.100.4") + ); +} + +#[test] +fn trusted_proxy_yields_the_rightmost_untrusted_hop_not_client_supplied_entries() { + let trusted = proxies(&["10.0.0.0/8", "127.0.0.1"]); + // The client forged the leftmost entry; the edge proxy (10.0.0.2) appended + // the real client address, and the local proxy appended the edge proxy. + let headers = forwarded(&[b"192.0.2.66, 203.0.113.9", b"10.0.0.2"]); + assert_eq!( + trusted.client_ip(ip("127.0.0.1"), &headers), + ip("203.0.113.9") + ); + let single = forwarded(&[b"203.0.113.9:51234"]); + assert_eq!( + trusted.client_ip(ip("127.0.0.1"), &single), + ip("203.0.113.9") + ); + let v6 = forwarded(&[b"[2001:db8::7]:443"]); + assert_eq!( + trusted.client_ip(ip("::ffff:127.0.0.1"), &v6), + ip("2001:db8::7") + ); +} + +#[test] +fn missing_or_malformed_forwarded_hops_fall_back_to_the_nearest_trusted_proxy() { + let trusted = proxies(&["10.0.0.0/8"]); + assert_eq!( + trusted.client_ip(ip("10.0.0.1"), &HeaderMap::new()), + ip("10.0.0.1") + ); + let garbage = forwarded(&[b"203.0.113.9, not-an-ip, 10.0.0.3"]); + assert_eq!(trusted.client_ip(ip("10.0.0.1"), &garbage), ip("10.0.0.3")); + let opaque = forwarded(&[b"203.0.113.9", b"\xff"]); + assert_eq!(trusted.client_ip(ip("10.0.0.1"), &opaque), ip("10.0.0.1")); + let all_trusted = forwarded(&[b"10.0.0.9, 10.0.0.3"]); + assert_eq!( + trusted.client_ip(ip("10.0.0.1"), &all_trusted), + ip("10.0.0.9") + ); +} + +#[test] +fn trusted_proxy_entries_accept_cidrs_and_single_addresses_only() { + let range = parse_trusted_proxy(" 10.1.2.3/8 ").unwrap(); + assert_eq!(range, "10.1.2.3/8".parse::().unwrap()); + assert_eq!( + parse_trusted_proxy("::1").unwrap(), + "::1/128".parse::().unwrap() + ); + assert!(parse_trusted_proxy("proxy.example").is_err()); + assert!(parse_trusted_proxy("10.0.0.0/33").is_err()); + let trusted = TrustedProxies::new(vec![range]); + assert!(trusted.contains(ip("10.200.0.1"))); + assert!(!trusted.contains(ip("11.0.0.1"))); +} diff --git a/crates/clipsync-relay/src/http_tests.rs b/crates/clipsync-relay/src/http_tests.rs index b8aaf1b..a397b5d 100644 --- a/crates/clipsync-relay/src/http_tests.rs +++ b/crates/clipsync-relay/src/http_tests.rs @@ -45,6 +45,7 @@ async fn pairing_http_errors_preserve_protocol_expiry_busy_and_attempt_statuses( let error = join_pairing( ConnectInfo(address), State(state.clone()), + HeaderMap::new(), Json(request.clone()), ) .await @@ -54,6 +55,7 @@ async fn pairing_http_errors_preserve_protocol_expiry_busy_and_attempt_statuses( let error = join_pairing( ConnectInfo(address), State(state.clone()), + HeaderMap::new(), Json(request.clone()), ) .await @@ -66,6 +68,7 @@ async fn pairing_http_errors_preserve_protocol_expiry_busy_and_attempt_statuses( let error = join_pairing( ConnectInfo(address), State(state.clone()), + HeaderMap::new(), Json(request.clone()), ) .await @@ -77,6 +80,7 @@ async fn pairing_http_errors_preserve_protocol_expiry_busy_and_attempt_statuses( let joined = join_pairing( ConnectInfo(address), State(state.clone()), + HeaderMap::new(), Json(request.clone()), ) .await @@ -85,6 +89,7 @@ async fn pairing_http_errors_preserve_protocol_expiry_busy_and_attempt_statuses( let error = join_pairing( ConnectInfo(address), State(state.clone()), + HeaderMap::new(), Json(request.clone()), ) .await @@ -94,9 +99,14 @@ async fn pairing_http_errors_preserve_protocol_expiry_busy_and_attempt_statuses( for _ in 0..30 { state.record_ip_fail(address.ip()); } - let error = join_pairing(ConnectInfo(address), State(state), Json(request)) - .await - .unwrap_err(); + let error = join_pairing( + ConnectInfo(address), + State(state), + HeaderMap::new(), + Json(request), + ) + .await + .unwrap_err(); assert_eq!(error.0, StatusCode::TOO_MANY_REQUESTS); assert_eq!(error.1 .0.code, "too_many_attempts"); assert!(serde_json::to_string(&error.1 .0) @@ -161,3 +171,229 @@ async fn server_reports_bind_failure_and_serves_health_and_metrics_on_a_local_li task.abort(); assert!(task.await.unwrap_err().is_cancelled()); } + +fn join_test_state() -> Arc { + Arc::new(RelayState::new(RelayConfig { + bind: "127.0.0.1:0".parse().unwrap(), + public_url: "http://127.0.0.1".into(), + token_secret: vec![33; 32], + webhook_url: None, + webhook_secret: None, + })) +} + +async fn create_offer(state: &Arc) -> CreatePairingResponse { + create_pairing( + State(state.clone()), + Json(CreatePairingRequest { + protocol_version: PROTOCOL_VERSION, + pairing_session_id: PairingSessionId::new(), + device_id: DeviceId::new(), + device_name: "owner".into(), + os: "test".into(), + ttl_secs: None, + }), + ) + .await + .unwrap() + .0 +} + +fn join_request(code: &str) -> JoinPairingRequest { + JoinPairingRequest { + protocol_version: PROTOCOL_VERSION, + pairing_code: code.into(), + device_id: DeviceId::new(), + device_name: "joiner".into(), + os: "test".into(), + } +} + +/// Regression for unbounded pairing-code guessing: a single client sweeping +/// wrong codes must be throttled, and must not then be able to join with the +/// correct code. +#[tokio::test] +async fn sweeping_wrong_codes_from_one_ip_is_throttled_and_blocks_the_correct_code() { + const SWEEP: u32 = 20_000; + let state = join_test_state(); + let offer = create_offer(&state).await; + let attacker: SocketAddr = "198.51.100.7:4000".parse().unwrap(); + let (mut not_found, mut throttled) = (0u32, 0u32); + for n in 0..SWEEP { + let code = format!("{n:06}"); + if code == offer.pairing_code { + continue; + } + let error = join_pairing( + ConnectInfo(attacker), + State(state.clone()), + HeaderMap::new(), + Json(join_request(&code)), + ) + .await + .unwrap_err(); + match error.0 { + StatusCode::NOT_FOUND => not_found += 1, + StatusCode::TOO_MANY_REQUESTS => throttled += 1, + other => panic!("unexpected status {other}"), + } + } + assert!(throttled > 0, "wrong-code sweep was never throttled"); + assert!(not_found < 100, "{not_found} guesses were evaluated"); + let error = join_pairing( + ConnectInfo(attacker), + State(state.clone()), + HeaderMap::new(), + Json(join_request(&offer.pairing_code)), + ) + .await + .unwrap_err(); + assert_eq!(error.0, StatusCode::TOO_MANY_REQUESTS); + assert_eq!(error.1 .0.code, "too_many_attempts"); +} + +fn forwarded_for(client: &str) -> HeaderMap { + let mut headers = HeaderMap::new(); + headers.insert("x-forwarded-for", client.parse().unwrap()); + headers +} + +async fn join_status( + state: &Arc, + peer: SocketAddr, + headers: HeaderMap, + code: &str, +) -> StatusCode { + match join_pairing( + ConnectInfo(peer), + State(state.clone()), + headers, + Json(join_request(code)), + ) + .await + { + Ok(_) => StatusCode::OK, + Err(error) => error.0, + } +} + +/// Wrong codes that never collide with `offer`. +fn wrong_codes(offer: &CreatePairingResponse) -> impl Iterator + '_ { + (0..1_000_000u32) + .map(|n| format!("{n:06}")) + .filter(move |code| *code != offer.pairing_code) +} + +#[tokio::test] +async fn forwarded_for_is_honored_only_from_configured_trusted_proxies() { + let proxy: SocketAddr = "127.0.0.1:4000".parse().unwrap(); + // Without configuration the header is ignored: a direct client cannot + // rotate spoofed addresses, and clients behind a proxy share its budget. + // Each run stops at the per-client limit, below the relay-wide budget, so + // a header that was wrongly honored would show up as extra 404s. + let state = join_test_state(); + let offer = create_offer(&state).await; + let mut not_found = 0; + for (n, code) in wrong_codes(&offer).take(50).enumerate() { + let spoofed = forwarded_for(&format!("192.0.2.{n}")); + match join_status(&state, proxy, spoofed, &code).await { + StatusCode::NOT_FOUND => not_found += 1, + StatusCode::TOO_MANY_REQUESTS => break, + other => panic!("unexpected status {other}"), + } + } + assert_eq!(not_found, IP_FAILED_JOIN_LIMIT); + assert_eq!( + join_status( + &state, + proxy, + forwarded_for("203.0.113.5"), + &offer.pairing_code + ) + .await, + StatusCode::TOO_MANY_REQUESTS + ); + + // With the proxy trusted, each forwarded client has its own budget and a + // client-forged entry to the left of the proxy's is ignored. + let state = Arc::new(RelayState::with_trusted_proxies( + RelayConfig { + bind: "127.0.0.1:0".parse().unwrap(), + public_url: "http://127.0.0.1".into(), + token_secret: vec![34; 32], + webhook_url: None, + webhook_secret: None, + }, + vec!["127.0.0.0/8".parse().unwrap()], + )); + let offer = create_offer(&state).await; + let mut not_found = 0; + for (n, code) in wrong_codes(&offer).take(50).enumerate() { + let forged = forwarded_for(&format!("192.0.2.{n}, 198.51.100.9")); + match join_status(&state, proxy, forged, &code).await { + StatusCode::NOT_FOUND => not_found += 1, + StatusCode::TOO_MANY_REQUESTS => break, + other => panic!("unexpected status {other}"), + } + } + assert_eq!( + not_found, IP_FAILED_JOIN_LIMIT, + "forged leftmost entries evaded the client limit" + ); + assert_eq!( + join_status( + &state, + proxy, + forwarded_for("203.0.113.5"), + &offer.pairing_code + ) + .await, + StatusCode::OK + ); + // An untrusted peer cannot use the header even when proxies are configured. + let direct: SocketAddr = "198.51.100.9:4000".parse().unwrap(); + assert_eq!( + join_status(&state, direct, forwarded_for("203.0.113.6"), "000000").await, + StatusCode::TOO_MANY_REQUESTS + ); +} + +#[tokio::test] +async fn exhausted_relay_wide_budget_answers_unknown_and_correct_codes_identically() { + let state = join_test_state(); + let offer = create_offer(&state).await; + let mut refusals = 0; + for (n, code) in wrong_codes(&offer).take(1_000).enumerate() { + let client: SocketAddr = format!("10.{}.{}.1:4000", n / 256, n % 256) + .parse() + .unwrap(); + if join_status(&state, client, HeaderMap::new(), &code).await + == StatusCode::TOO_MANY_REQUESTS + { + refusals += 1; + } + } + assert!(refusals > 0, "distributed guesses were never throttled"); + let fresh: SocketAddr = "192.0.2.250:4000".parse().unwrap(); + let unknown = join_pairing( + ConnectInfo(fresh), + State(state.clone()), + HeaderMap::new(), + Json(join_request("999999")), + ) + .await + .unwrap_err(); + let correct = join_pairing( + ConnectInfo(fresh), + State(state.clone()), + HeaderMap::new(), + Json(join_request(&offer.pairing_code)), + ) + .await + .unwrap_err(); + assert_eq!(unknown.0, StatusCode::TOO_MANY_REQUESTS); + assert_eq!( + serde_json::to_string(&unknown.1 .0).unwrap(), + serde_json::to_string(&correct.1 .0).unwrap() + ); +} diff --git a/crates/clipsync-relay/src/lib.rs b/crates/clipsync-relay/src/lib.rs index f970e91..f3d4952 100644 --- a/crates/clipsync-relay/src/lib.rs +++ b/crates/clipsync-relay/src/lib.rs @@ -4,6 +4,7 @@ //! Zero-knowledge ClipSync relay: pairing rendezvous and encrypted frame routing. mod auth; +mod client_ip; mod state; mod transport; mod webhook; @@ -14,7 +15,7 @@ use std::sync::Arc; use std::time::Duration; use axum::extract::State; -use axum::http::StatusCode; +use axum::http::{HeaderMap, StatusCode}; use axum::routing::{get, post}; use axum::{Json, Router}; use tower_http::limit::RequestBodyLimitLayer; @@ -27,6 +28,8 @@ use clipsync_protocol::{ }; pub use state::RelayState; +#[cfg(test)] +use state::IP_FAILED_JOIN_LIMIT; pub use transport::RelayTransportConfig; #[derive(Clone, Debug)] @@ -106,7 +109,14 @@ pub async fn serve_with_transport( let tls = transport.tls_config(&config.public_url)?; let listener = std::net::TcpListener::bind(config.bind)?; let addr = listener.local_addr()?; - let app = router(config).into_make_service_with_connect_info::(); + if !transport.trusted_proxies.is_empty() { + info!( + ranges = transport.trusted_proxies.len(), + "honoring X-Forwarded-For from trusted proxies for pairing limits" + ); + } + let app = router_with_trusted_proxies(config, transport.trusted_proxies.clone()) + .into_make_service_with_connect_info::(); let server = axum_server::from_tcp(listener)?.first_request_timeout(Duration::from_secs(10)); if let Some(tls) = tls { info!(%addr, "clipsync-relay listening with TLS 1.2/1.3"); @@ -122,7 +132,16 @@ pub async fn serve_with_transport( } pub fn router(config: RelayConfig) -> Router { - let state = Arc::new(RelayState::new(config)); + router_with_trusted_proxies(config, Vec::new()) +} + +/// Like [`router`], also honoring `X-Forwarded-For` from `trusted_proxies` +/// when identifying clients for pairing limits. +pub fn router_with_trusted_proxies( + config: RelayConfig, + trusted_proxies: Vec, +) -> Router { + let state = Arc::new(RelayState::with_trusted_proxies(config, trusted_proxies)); let janitor_state = state.clone(); tokio::spawn(async move { loop { @@ -169,6 +188,7 @@ async fn create_pairing( async fn join_pairing( axum::extract::ConnectInfo(addr): axum::extract::ConnectInfo, State(state): State>, + headers: HeaderMap, Json(req): Json, ) -> Result, (StatusCode, Json)> { if req.protocol_version != clipsync_protocol::PROTOCOL_VERSION { @@ -178,7 +198,8 @@ async fn join_pairing( "unsupported protocol version", )); } - match state.join_pairing(req, addr.ip()) { + let client = state.client_ip(addr.ip(), &headers); + match state.join_pairing(req, client) { Ok(resp) => Ok(Json(resp)), Err(JoinError::NotFound) => Err(err( StatusCode::NOT_FOUND, diff --git a/crates/clipsync-relay/src/state.rs b/crates/clipsync-relay/src/state.rs index f687d25..b3483f1 100644 --- a/crates/clipsync-relay/src/state.rs +++ b/crates/clipsync-relay/src/state.rs @@ -1,8 +1,9 @@ // Copyright the ClipSync contributors. // SPDX-License-Identifier: MIT use std::collections::HashMap; -use std::net::IpAddr; +use std::net::{IpAddr, Ipv6Addr}; use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Mutex, PoisonError}; use std::time::{Duration, Instant}; use chrono::{DateTime, Utc}; @@ -17,8 +18,52 @@ use clipsync_protocol::{ }; use crate::auth::issue_token; +use crate::client_ip::TrustedProxies; use crate::{JoinError, RelayConfig, WsOut}; +// Failed pairing joins are limited per client and relay-wide. The relay-wide +// budget is what bounds guessing: with `PAIRING_TTL_SECS`-long fixed windows, +// a pairing code's lifetime overlaps at most two windows, so at most +// 2 * GLOBAL_FAILED_JOIN_LIMIT = 40 wrong codes are evaluated while any code +// is live, however many addresses the attacker uses. Codes are uniform over +// 10^6 values, so one session is guessed with probability <= 40 / 10^6 = +// 4e-5 (4e-5 * S with S sessions open at once). This is below the 1e-4 +// implied by NIST SP 800-63B's ceiling of 100 failed attempts against a +// 6-digit authenticator. + +/// Failed joins one client may make per window: enough to retype a mistyped +/// code a few times, while one address alone tests at most 10 of 10^6 codes. +pub(crate) const IP_FAILED_JOIN_LIMIT: u32 = 10; +/// Per-client window; longer than a pairing session so a code cannot outlive +/// one client's budget, short enough that a mistyping user is not locked out +/// for long. +const IP_FAILED_JOIN_WINDOW: Duration = Duration::from_secs(15 * 60); +/// Relay-wide failed joins per window; see the bound above. A self-hosted relay +/// rarely sees more than a handful of mistyped codes per pairing window. +const GLOBAL_FAILED_JOIN_LIMIT: u32 = 20; +/// One pairing TTL, so the per-session bound above holds if the TTL changes. +const GLOBAL_FAILED_JOIN_WINDOW: Duration = Duration::from_secs(PAIRING_TTL_SECS); +/// IPv6 sites are normally delegated at least a /64, so one client controls +/// every address in it; count them as one client. +const IPV6_CLIENT_PREFIX_LEN: u32 = 64; +/// Values a pairing code can take: six decimal digits (see `alloc_code`). +const PAIRING_CODE_SPACE: u64 = 1_000_000; +/// Largest acceptable guessing success per session, as 1 in this many (1e-4). +const NEGLIGIBLE_GUESS_ODDS: u64 = 10_000; +/// Fixed windows per pairing lifetime in the worst case (see the bound above). +const WINDOWS_PER_PAIRING_LIFETIME: u64 = 2; + +// Keep the bound above true if any of these values change. +const _: () = { + assert!(GLOBAL_FAILED_JOIN_WINDOW.as_secs() >= PAIRING_TTL_SECS); + assert!(IP_FAILED_JOIN_WINDOW.as_secs() >= PAIRING_TTL_SECS); + assert!(IP_FAILED_JOIN_LIMIT < GLOBAL_FAILED_JOIN_LIMIT); + assert!( + WINDOWS_PER_PAIRING_LIFETIME * GLOBAL_FAILED_JOIN_LIMIT as u64 * NEGLIGIBLE_GUESS_ODDS + <= PAIRING_CODE_SPACE + ); +}; + pub struct RelayState { pub config: RelayConfig, pairing_by_code: DashMap, @@ -26,7 +71,11 @@ pub struct RelayState { rooms: DashMap, pub connections: DashMap>, queue: DashMap)>, + /// Failed joins per client key (see `rate_limit_key`): count and window start. ip_fails: DashMap, + /// Relay-wide failed joins: count and window start. + global_join_fails: Mutex<(u32, Instant)>, + trusted_proxies: TrustedProxies, pub connections_total: AtomicU64, pub frames_forwarded: AtomicU64, pub pairing_ok: AtomicU64, @@ -63,8 +112,31 @@ pub struct DeviceEntry { pub revoked: bool, } +/// Join attempt counted before the code lookup and refunded if the join succeeds. +struct JoinReservation { + key: IpAddr, + ip_window: Instant, + global_window: Instant, +} + +/// Rate-limit key for a client address: IPv4 as is, IPv6 by its /64 prefix. +fn rate_limit_key(ip: IpAddr) -> IpAddr { + match ip.to_canonical() { + IpAddr::V6(v6) => { + let mask = u128::MAX << (u128::BITS - IPV6_CLIENT_PREFIX_LEN); + IpAddr::V6(Ipv6Addr::from(u128::from(v6) & mask)) + } + v4 => v4, + } +} + impl RelayState { pub fn new(config: RelayConfig) -> Self { + Self::with_trusted_proxies(config, Vec::new()) + } + + /// Like [`RelayState::new`], also honoring `X-Forwarded-For` from `trusted_proxies`. + pub fn with_trusted_proxies(config: RelayConfig, trusted_proxies: Vec) -> Self { Self { config, pairing_by_code: DashMap::new(), @@ -73,6 +145,8 @@ impl RelayState { connections: DashMap::new(), queue: DashMap::new(), ip_fails: DashMap::new(), + global_join_fails: Mutex::new((0, Instant::now())), + trusted_proxies: TrustedProxies::new(trusted_proxies), connections_total: AtomicU64::new(0), frames_forwarded: AtomicU64::new(0), pairing_ok: AtomicU64::new(0), @@ -148,12 +222,34 @@ impl RelayState { Err("could not allocate pairing code".into()) } + /// Client address for per-client limits of a request received from `peer`. + pub fn client_ip(&self, peer: IpAddr, headers: &axum::http::HeaderMap) -> IpAddr { + self.trusted_proxies.client_ip(peer, headers) + } + + /// Join a pairing session by code. Every failed join, whatever its cause, + /// counts against the client and the relay-wide budget; once either is + /// exhausted every join is refused with `Attempts`, including one with a + /// correct code, so the response never reveals whether a code exists. pub fn join_pairing( &self, req: JoinPairingRequest, ip: IpAddr, ) -> Result { - self.check_ip(ip)?; + let reservation = self.reserve_join_attempt(rate_limit_key(ip))?; + let result = self.join_pairing_session(req); + if result.is_ok() { + self.release_join_attempt(reservation); + } else { + self.pairing_fail.fetch_add(1, Ordering::Relaxed); + } + result + } + + fn join_pairing_session( + &self, + req: JoinPairingRequest, + ) -> Result { let mut session = self .pairing_by_code .get_mut(&req.pairing_code) @@ -201,22 +297,78 @@ impl RelayState { }) } - fn check_ip(&self, ip: IpAddr) -> Result<(), JoinError> { - let mut entry = self.ip_fails.entry(ip).or_insert((0, Instant::now())); - if entry.1.elapsed() > Duration::from_secs(3600) { - *entry = (0, Instant::now()); + /// Count a join attempt before the code is looked up, so concurrent guesses + /// cannot overshoot either budget. Refused attempts are not counted. + fn reserve_join_attempt(&self, key: IpAddr) -> Result { + let ip_window = { + let mut entry = self + .ip_fails + .entry(key) + .or_insert_with(|| (0, Instant::now())); + // Read the clock while holding the entry so a reset never + // back-dates a window past a concurrent update. + let now = Instant::now(); + if now.duration_since(entry.1) > IP_FAILED_JOIN_WINDOW { + *entry = (0, now); + } + if entry.0 >= IP_FAILED_JOIN_LIMIT { + return Err(JoinError::Attempts); + } + entry.0 += 1; + entry.1 + }; + let mut global = self + .global_join_fails + .lock() + .unwrap_or_else(PoisonError::into_inner); + let now = Instant::now(); + if now.duration_since(global.1) > GLOBAL_FAILED_JOIN_WINDOW { + *global = (0, now); } - if entry.0 >= 30 { + if global.0 >= GLOBAL_FAILED_JOIN_LIMIT { + drop(global); + self.release_ip_attempt(key, ip_window); return Err(JoinError::Attempts); } - Ok(()) + global.0 += 1; + Ok(JoinReservation { + key, + ip_window, + global_window: global.1, + }) } - pub fn record_ip_fail(&self, ip: IpAddr) { - self.ip_fails - .entry(ip) - .and_modify(|e| e.0 += 1) - .or_insert((1, Instant::now())); + /// Refund a successful join; a refund for an already-reset window is void. + fn release_join_attempt(&self, reservation: JoinReservation) { + self.release_ip_attempt(reservation.key, reservation.ip_window); + let mut global = self + .global_join_fails + .lock() + .unwrap_or_else(PoisonError::into_inner); + if global.1 == reservation.global_window { + global.0 = global.0.saturating_sub(1); + } + } + + fn release_ip_attempt(&self, key: IpAddr, window: Instant) { + self.ip_fails.remove_if_mut(&key, |_, entry| { + if entry.1 == window { + entry.0 = entry.0.saturating_sub(1); + } + entry.0 == 0 + }); + } + + /// Test helper: charge failed joins to one client without the relay-wide budget. + #[cfg(test)] + pub(crate) fn record_ip_fail(&self, ip: IpAddr) { + let now = Instant::now(); + let mut entry = self.ip_fails.entry(rate_limit_key(ip)).or_insert((0, now)); + if now.duration_since(entry.1) > IP_FAILED_JOIN_WINDOW { + *entry = (0, now); + } + entry.0 = entry.0.saturating_add(1); + drop(entry); self.pairing_fail.fetch_add(1, Ordering::Relaxed); } @@ -388,6 +540,8 @@ impl RelayState { let now = Utc::now(); self.pairing_by_code .retain(|_, s| s.expires_at > now && !s.completed); + self.ip_fails + .retain(|_, (_, window)| window.elapsed() <= IP_FAILED_JOIN_WINDOW); self.queue.retain(|_, (_, exp)| { if *exp > now { true diff --git a/crates/clipsync-relay/src/state_tests.rs b/crates/clipsync-relay/src/state_tests.rs index 8423c94..30d03ad 100644 --- a/crates/clipsync-relay/src/state_tests.rs +++ b/crates/clipsync-relay/src/state_tests.rs @@ -147,3 +147,143 @@ fn queue_expiry_discards_only_expired_envelopes_and_gc_counts_them() { assert_eq!(state.take_queue("fresh"), Some(envelope)); assert_eq!(state.expired.load(Ordering::Relaxed), 2); } + +#[test] +fn gc_drops_expired_failed_join_entries() { + let (state, _, _, _) = fixture(); + let stale: IpAddr = "192.0.2.10".parse().unwrap(); + let fresh: IpAddr = "192.0.2.11".parse().unwrap(); + state.record_ip_fail(stale); + state.record_ip_fail(fresh); + state.ip_fails.get_mut(&stale).unwrap().1 = + Instant::now() - IP_FAILED_JOIN_WINDOW - Duration::from_secs(1); + state.gc(); + assert!(state.ip_fails.get(&stale).is_none()); + assert!(state.ip_fails.get(&fresh).is_some()); +} + +/// A wrong code for `offer` that differs in its last digit. +fn wrong_code(offer: &CreatePairingResponse, salt: u32) -> String { + let real: u32 = offer.pairing_code.parse().unwrap(); + let digits = offer.pairing_code.len(); + let modulus = 10u32.pow(digits as u32); + let code = (real + 1 + salt % (modulus - 1)) % modulus; + format!("{code:0digits$}") +} + +#[test] +fn wrong_codes_from_one_client_exhaust_its_budget_and_refuse_its_correct_code() { + let (state, offer, _, owner) = fixture(); + let attacker: IpAddr = "198.51.100.1".parse().unwrap(); + // Every failure kind counts, not only unknown codes. + assert!(matches!( + state.join_pairing(join(&offer.pairing_code, owner), attacker), + Err(JoinError::Other(_)) + )); + for salt in 1..IP_FAILED_JOIN_LIMIT { + assert!(matches!( + state.join_pairing(join(&wrong_code(&offer, salt), DeviceId::new()), attacker), + Err(JoinError::NotFound) + )); + } + assert!(matches!( + state.join_pairing(join(&wrong_code(&offer, 0), DeviceId::new()), attacker), + Err(JoinError::Attempts) + )); + assert!(matches!( + state.join_pairing(join(&offer.pairing_code, DeviceId::new()), attacker), + Err(JoinError::Attempts) + )); + assert_eq!( + state.ip_fails.get(&attacker).unwrap().0, + IP_FAILED_JOIN_LIMIT, + "refused attempts must not extend the count" + ); + let other: IpAddr = "198.51.100.2".parse().unwrap(); + state + .join_pairing(join(&offer.pairing_code, DeviceId::new()), other) + .unwrap(); + assert!(state.ip_fails.get(&other).is_none(), "success is refunded"); + assert_eq!( + state.pairing_fail.load(Ordering::Relaxed), + u64::from(IP_FAILED_JOIN_LIMIT) + ); +} + +#[test] +fn successful_joins_do_not_consume_failure_budgets() { + let state = fixture().0; + let client: IpAddr = "198.51.100.3".parse().unwrap(); + for _ in 0..(GLOBAL_FAILED_JOIN_LIMIT + IP_FAILED_JOIN_LIMIT) { + let offer = state + .create_pairing(CreatePairingRequest { + protocol_version: clipsync_protocol::PROTOCOL_VERSION, + pairing_session_id: PairingSessionId::new(), + device_id: DeviceId::new(), + device_name: "owner".into(), + os: "test".into(), + ttl_secs: None, + }) + .unwrap(); + state + .join_pairing(join(&offer.pairing_code, DeviceId::new()), client) + .unwrap(); + } + assert_eq!(state.global_join_fails.lock().unwrap().0, 0); +} + +#[test] +fn distributed_wrong_codes_exhaust_the_relay_wide_budget_without_revealing_codes() { + let (state, offer, _, _) = fixture(); + for n in 0..GLOBAL_FAILED_JOIN_LIMIT { + let ip = IpAddr::from([203, 0, 113, n as u8]); + assert!(matches!( + state.join_pairing(join(&wrong_code(&offer, n), DeviceId::new()), ip), + Err(JoinError::NotFound) + )); + } + let fresh: IpAddr = "192.0.2.200".parse().unwrap(); + // Unknown and correct codes are refused identically once the budget is spent. + assert!(matches!( + state.join_pairing(join(&wrong_code(&offer, 0), DeviceId::new()), fresh), + Err(JoinError::Attempts) + )); + assert!(matches!( + state.join_pairing(join(&offer.pairing_code, DeviceId::new()), fresh), + Err(JoinError::Attempts) + )); + assert!( + state.ip_fails.get(&fresh).is_none(), + "refused attempts must not allocate per-client entries" + ); + state.global_join_fails.lock().unwrap().1 = + Instant::now() - GLOBAL_FAILED_JOIN_WINDOW - Duration::from_secs(1); + state + .join_pairing(join(&offer.pairing_code, DeviceId::new()), fresh) + .unwrap(); +} + +#[test] +fn ipv6_clients_are_limited_per_64_prefix_and_mapped_ipv4_as_ipv4() { + let (state, offer, _, _) = fixture(); + for n in 0..IP_FAILED_JOIN_LIMIT { + let ip = IpAddr::from([0x2001, 0xdb8, 0, 0x7, 0, 0, 0, n as u16 + 1]); + assert!(matches!( + state.join_pairing(join(&wrong_code(&offer, n), DeviceId::new()), ip), + Err(JoinError::NotFound) + )); + } + let same_prefix = IpAddr::from([0x2001, 0xdb8, 0, 0x7, 0xffff, 0, 0, 1]); + assert!(matches!( + state.join_pairing(join(&offer.pairing_code, DeviceId::new()), same_prefix), + Err(JoinError::Attempts) + )); + assert_eq!( + rate_limit_key("::ffff:192.0.2.1".parse().unwrap()), + "192.0.2.1".parse::().unwrap() + ); + let next_prefix = IpAddr::from([0x2001, 0xdb8, 0, 0x8, 0, 0, 0, 1]); + state + .join_pairing(join(&offer.pairing_code, DeviceId::new()), next_prefix) + .unwrap(); +} diff --git a/crates/clipsync-relay/src/transport.rs b/crates/clipsync-relay/src/transport.rs index 4088ba3..7ae91df 100644 --- a/crates/clipsync-relay/src/transport.rs +++ b/crates/clipsync-relay/src/transport.rs @@ -32,6 +32,15 @@ pub struct RelayTransportConfig { /// Explicitly allow plaintext HTTP behind a TLS proxy or for local development #[arg(long, env = "CLIPSYNC_RELAY_ALLOW_HTTP")] pub allow_http: bool, + /// Comma-separated proxy addresses/CIDRs whose X-Forwarded-For identifies + /// clients for pairing limits; unset uses only the TCP peer address + #[arg( + long, + env = "CLIPSYNC_RELAY_TRUSTED_PROXIES", + value_delimiter = ',', + value_parser = crate::client_ip::parse_trusted_proxy + )] + pub trusted_proxies: Vec, } impl RelayTransportConfig { diff --git a/crates/clipsync-relay/src/transport_tests.rs b/crates/clipsync-relay/src/transport_tests.rs index 9656d27..32e2046 100644 --- a/crates/clipsync-relay/src/transport_tests.rs +++ b/crates/clipsync-relay/src/transport_tests.rs @@ -55,3 +55,22 @@ async fn handshakes_reject_capacity_overflow_and_release_cancelled_permits() { drop(pending); assert_eq!(acceptor.permits.available_permits(), MAX_HANDSHAKES); } + +#[test] +fn trusted_proxies_default_to_none_and_parse_comma_separated_ranges() { + #[derive(Parser)] + struct Args { + #[command(flatten)] + transport: RelayTransportConfig, + } + let parse = |args: &[&str]| { + Args::try_parse_from(std::iter::once("clipsync-relay").chain(args.iter().copied())) + .map(|args| args.transport.trusted_proxies) + }; + assert!(RelayTransportConfig::default().trusted_proxies.is_empty()); + assert_eq!( + parse(&["--trusted-proxies", "10.0.0.0/8, 127.0.0.1,::1"]).unwrap(), + ["10.0.0.0/8", "127.0.0.1/32", "::1/128"].map(|net| net.parse::().unwrap()) + ); + assert!(parse(&["--trusted-proxies", "10.0.0.0/8,proxy.example"]).is_err()); +} diff --git a/docs/interfaces.md b/docs/interfaces.md index 2b17621..094bd79 100644 --- a/docs/interfaces.md +++ b/docs/interfaces.md @@ -203,7 +203,7 @@ Handler-generated HTTP failures have the JSON shape | create / 400 | `pairing_create` | Pairing creation failed, for example code allocation failure. | | join / 404 | `code_invalid` | Unknown code, including expired sessions already removed by cleanup. | | join / 410 | `code_expired` | Session exists but has expired. | -| join / 429 | `too_many_attempts` | Pairing attempt limit reached. | +| join / 429 | `too_many_attempts` | Pairing attempt limit reached: the session's attempts, the client's failed joins, or the relay-wide failed-join budget. Returned even for a correct code once a failure budget is spent. | | join / 409 | `busy` | Session already has a joiner or is completed. | | join / 400 | `join_failed` | Other join rejection, including using the creator's device ID. | diff --git a/docs/security.md b/docs/security.md index d56afc2..323470e 100644 --- a/docs/security.md +++ b/docs/security.md @@ -17,6 +17,23 @@ SPAKE2 transcript to the protocol version, pairing session ID, and device IDs, then exchange HMAC confirmations. Wrong code, mutated transcript, or failed confirmation aborts without storing credentials. +The relay limits online guessing of this password. Every failed +`/v1/pairing/join` counts, whether the code was unknown, expired, busy or +otherwise rejected. Each client address (IPv6 by /64 prefix) may fail 10 times +per 15 minutes. The whole relay may fail 20 times per 120-second pairing TTL. +A code's lifetime overlaps at most two of those relay-wide windows, so an +attacker with any number of addresses can test at most 40 of the 10^6 codes +while a session is open. That bounds the chance of guessing one session at +4 × 10^-5. When either budget is spent, the relay refuses every join, including +one with the correct code, with `429 too_many_attempts`. This response does not +reveal whether a code exists. Successful joins are not counted, but they do not +clear earlier failures. Behind a NAT or proxy, a legitimate user who shares an +address with a guesser is refused until the window ends. Anyone who can spend +the relay-wide budget can keep blocking new pairings. This is a deliberate +trade-off: guessing becomes a denial of service instead of a room compromise. +Per-client limits use the TCP peer address unless trusted proxies are configured; +see [self-hosting](self-hosting.md). + The relay generates this password. Pair through a trusted relay: an actively malicious operator who knows the password is outside the honest-but-curious model and may impersonate a pairing participant. HTTPS/WSS authenticates the diff --git a/docs/self-hosting.md b/docs/self-hosting.md index 59a11fa..98b27c5 100644 --- a/docs/self-hosting.md +++ b/docs/self-hosting.md @@ -48,8 +48,21 @@ with a five-second TLS handshake deadline and at most 128 incomplete handshakes. Excess attempts close immediately, without a waiting socket queue. The server also limits the time to its first HTTP request to ten seconds. The HTTP/WebSocket router still receives the actual TCP peer address for rate -limits; proxy deployments see the immediate proxy's address. Forwarded-IP -headers are not promoted to trusted connection metadata. +limits. By default, proxy deployments see the immediate proxy's address, so all +clients behind one proxy share a pairing-join budget, and forwarded-IP headers +are ignored. + +To give clients behind a reverse proxy separate pairing-join budgets, set +`CLIPSYNC_RELAY_TRUSTED_PROXIES` (or `--trusted-proxies`) to a comma-separated +list of the proxy addresses or CIDR ranges, for example `127.0.0.1` for the +nginx example below. The relay then reads `X-Forwarded-For` only on connections +from those addresses, and uses the rightmost entry that is not itself a trusted +proxy. Entries to the left of that entry are ignored because clients can write +them. Configure the proxy to append the connecting address, as nginx's +`$proxy_add_x_forwarded_for` and Caddy's `reverse_proxy` do. List only addresses +that untrusted clients cannot connect from. A process that can connect from a +trusted address can claim any client address. The setting affects pairing-join +limits only. Leave it unset when clients connect to the relay directly. For a container, mount the certificate directory read-only and pass the paths at runtime. Keep private files out of the image and build context. This example @@ -121,6 +134,7 @@ location / { proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 3600; } ``` @@ -134,6 +148,7 @@ location / { | `CLIPSYNC_RELAY_TLS_CERT_FILE` | PEM certificate chain for direct HTTPS/WSS | | `CLIPSYNC_RELAY_TLS_KEY_FILE` | Matching PEM private key; both TLS files are required | | `CLIPSYNC_RELAY_ALLOW_HTTP` | Explicit `true` for a local/TLS-proxy plaintext origin; default `false` | +| `CLIPSYNC_RELAY_TRUSTED_PROXIES` | Optional comma-separated proxy addresses/CIDRs whose `X-Forwarded-For` identifies clients for pairing-join limits; unset uses only the TCP peer address | | `CLIPSYNC_RELAY_TOKEN_SECRET_FILE` | Optional private file of exact HMAC key bytes; at least 32 bytes; cannot be combined with `CLIPSYNC_RELAY_TOKEN_SECRET` | | `CLIPSYNC_RELAY_TOKEN_SECRET` | HMAC token key; at least 32 bytes when explicitly set. Unset, empty, or whitespace-only generates a fresh random 32-byte key. | | `CLIPSYNC_RELAY_WEBHOOK_URL` | Optional metadata webhook |