AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
security(console): key the auth rate limiter on the socket peer, not x-forwarded-for (#112)
xerj-orgb2270223d781
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3a7bef85d..cf1d357a9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -48,6 +48,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0Prior to this, the rule was half-enforced: `flat_object`/`flattened`were special-cased into a `400` while every other ES-forbidden typepassed.+### Security++- **`x-forwarded-for` is no longer trusted for client identity** (#76 S5-4).+ The per-IP auth rate limiter and the audit-log source address used to be+ read straight out of `x-forwarded-for` — a header the caller writes. A+ rotating `x-forwarded-for: 1.2.3.$RANDOM` therefore reset the quota on+ every request, so the unauthenticated magic-link redeem and bootstrap-claim+ endpoints could be brute-forced without limit, while honest clients (who+ send no such header) stayed throttled. Client identity now comes from the+ TCP peer: `ConnectInfo<SocketAddr>` is threaded through both the plain and+ the TLS listener, and a handler reads it via the new `ClientIp` extractor.++ Forwarding headers are still honoured behind a real reverse proxy, but only+ from a proxy the operator has declared: the new **`server.trusted_proxies`**+ setting takes IP addresses or CIDR blocks (`["10.0.0.0/8", "::1"]`) and is+ **empty by default — an unconfigured node believes nobody**. When the peer+ is a declared proxy the forwarded chain is read right-to-left (the left end+ is caller-authored) and the right-most address that is not itself a listed+ proxy wins; a malformed element stops the walk rather than being stepped+ over. Malformed entries in the setting fail startup instead of silently+ widening or narrowing trust.++ Operators terminating TLS or load-balancing in front of XERJ must set+ `server.trusted_proxies` to their proxy's address, otherwise every user+ behind it shares one rate-limit bucket.## [1.0.0-rc.9] - 2026-08-01@@ -356,7 +381,7 @@ limitations rather than quietly omitted.which means a caller can spoof the address the per-IP rate limiterkeys on. The fix needs `ConnectInfo` threaded through the sharedserve and TLS path and is deliberately not bundled with the smaller- items above.+ items above. *(Fixed after this release — see Unreleased.)*- **Windows durability is weaker than Unix durability**, as describedunder Fixed. The platform provides no way to make it otherwise.diff --git a/docs/case-studies/xerj-self-audit/FINDINGS-V2.md b/docs/case-studies/xerj-self-audit/FINDINGS-V2.mdindex f3918da75..085c3c658 100644--- a/docs/case-studies/xerj-self-audit/FINDINGS-V2.md+++ b/docs/case-studies/xerj-self-audit/FINDINGS-V2.md@@ -137,7 +137,7 @@ the Raft-auth Phase-2 item. Source-verified, not exploited on a live cluster.----## S5-4 — `x-forwarded-for` trusted as identity for rate-limiting and audit · Medium · open+## S5-4 — `x-forwarded-for` trusted as identity for rate-limiting and audit · Medium · fixed`crates/xerj-console-api/src/auth/magic.rs:360`, `rate_limit.rs:58`.@@ -155,6 +155,18 @@ the audit log. Confirmed unauthenticated (the endpoint is registeredand consult `x-forwarded-for` only when the socket peer is a trusted proxy in anoperator-configured CIDR.+**Status.** Fixed. `ConnectInfo<SocketAddr>` is installed on both the plain and+the TLS listener (`into_make_service_with_connect_info`), and handlers read the+caller address through a `ClientIp` extractor+(`crates/xerj-console-api/src/client_ip.rs`). Forwarding headers are consulted+only when the socket peer matches `server.trusted_proxies` — a new setting that+takes addresses/CIDRs and is **empty by default**, so an unconfigured node+believes nobody. The chain is read right-to-left past our own proxies; the+caller-authored left end is never used, and a malformed element stops the walk.+Covered by `tests/trusted_proxy_client_identity.rs` (spoof from an untrusted+peer changes nothing; a declared proxy's forwarded address is honoured) plus+listener-level tests that the real peer reaches handlers over HTTP and HTTPS.+---## S5-3 — Magic-link single-use / bootstrap-claim is TOCTOU · Medium · opendiff --git a/docs/recipes/production-deployment.md b/docs/recipes/production-deployment.mdindex ce368a7cb..0d5e9d19c 100644--- a/docs/recipes/production-deployment.md+++ b/docs/recipes/production-deployment.md@@ -190,6 +190,41 @@ Because the gRPC port carries cleartext frames, **terminate TLS in front ofclients reach it over an untrusted link. If you don't use gRPC, don't exposethe port.+### Behind a reverse proxy: `server.trusted_proxies`++XERJ derives client identity — the per-IP auth rate-limit bucket on the+console's login / magic-link endpoints, and the audit-log source address —+from the **TCP peer address**, which a caller cannot forge. `X-Forwarded-For`+is written by the caller and is **ignored by default**.++That default is safe but it is not what you want behind a proxy: the peer is+then always the proxy, so every user collapses into one bucket (ten login+attempts a minute for the whole company). Declare the proxy:++```toml+[server]+# Addresses or CIDR blocks. Empty by default — believe nobody.+trusted_proxies = ["10.0.0.7"] # or ["10.0.0.0/8", "::1"]+```++Rules worth knowing before you set it:++- **List only proxies you operate.** Anything named here can claim to be any+ client, and so can side-step per-IP throttling. `0.0.0.0/0` re-opens the+ exact hole this setting exists to close.+- **The chain is read right-to-left.** `X-Forwarded-For` is appended+ left-to-right, so the left end is whatever the original caller sent. XERJ+ takes the right-most entry that is not itself a listed proxy — the one your+ own outermost proxy just wrote. A caller who pre-seeds the header cannot+ pick their own bucket.+- **`X-Real-IP` is honoured only when there is no `X-Forwarded-For`**, and+ only from a listed peer.+- **A bad entry fails startup.** `trusted_proxies = ["10.0.0.0/99"]` refuses+ to boot rather than quietly trusting nothing (or everything).+- Make sure the proxy actually **overwrites** rather than appends blindly —+ nginx `proxy_set_header X-Forwarded-For $proxy_add_forwarded_for` is+ correct; passing the client's header through verbatim is not.+---## 2. What XERJ does and does not secure itself@@ -208,6 +243,7 @@ transport encryption; your platform provides the rest.| Memtable + RSS + disk-flood circuit breakers (429 before OOM/ENOSPC) | ✅ (`[limits]`) || Restrictive CORS by default (no cross-origin reads unless allow-listed) | ✅ (`[cors]`) || Secrets written `0600` (admin key, auto-generated TLS key) | ✅ |+| Client identity from the TCP peer, not `X-Forwarded-For` | ✅ (`server.trusted_proxies`, empty by default) |### Bound retained segment hydrationdiff --git a/engine/crates/xerj-common/src/config.rs b/engine/crates/xerj-common/src/config.rsindex f8f925147..e076debb8 100644--- a/engine/crates/xerj-common/src/config.rs+++ b/engine/crates/xerj-common/src/config.rs@@ -46,7 +46,7 @@ use crate::error::XerjError;#[derive(Debug, Clone, Default, Serialize, Deserialize)]#[serde(default, deny_unknown_fields)]pub struct Config {- /// Network and data directory settings — 5 settings.+ /// Network and data directory settings — 6 settings.pub server: ServerConfig,/// Authentication — 2 settings.pub auth: AuthConfig,@@ -136,6 +136,13 @@ impl Config {));}+ // Trusted proxies: a typo in a trust boundary must fail startup, not+ // silently degrade. (A rejected entry that we merely skipped would+ // leave the operator believing forwarding headers are honoured when+ // they are not — or, worse, the reverse.)+ crate::net::TrustedProxies::parse(&self.server.trusted_proxies)+ .map_err(|why| XerjError::config(format!("server.trusted_proxies: {why}")))?;+// TLS: if enabled, paths must be suppliedif self.tls.enabled {if self.tls.cert_path.is_empty() {@@ -266,7 +273,7 @@ impl Config {/// Network and data-directory settings.///-/// **5 settings.**+/// **6 settings.**#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(default, deny_unknown_fields)]pub struct ServerConfig {@@ -280,6 +287,24 @@ pub struct ServerConfig {pub data_dir: String,/// Address to bind all listeners (default: `"0.0.0.0"`).pub bind_address: String,+ /// Reverse proxies whose `X-Forwarded-For` / `X-Real-IP` headers may be+ /// believed (default: `[]` — **believe nobody**).+ ///+ /// Client identity (the per-IP auth rate-limit bucket and the audit-log+ /// source address) is normally taken from the TCP peer address, which a+ /// caller cannot forge. `X-Forwarded-For` is attacker-controlled and is+ /// therefore ignored unless the *socket peer* matches an entry here.+ ///+ /// Entries are single addresses (`"10.0.0.7"`, `"::1"`) or CIDR blocks+ /// (`"10.0.0.0/8"`, `"fd00::/8"`); invalid entries are rejected at+ /// startup rather than silently ignored. Set this **only** to the+ /// addresses of proxies you operate: anything listed here can claim to+ /// be any client and so bypass per-IP throttling.+ ///+ /// With this set, the forwarded chain is read right-to-left and the+ /// right-most address that is *not* itself a listed proxy is used — the+ /// left end of the chain is written by the caller and cannot be trusted.+ pub trusted_proxies: Vec<String>,}impl Default for ServerConfig {@@ -290,6 +315,7 @@ impl Default for ServerConfig {es_compat_port: 9200,data_dir: "./data".into(),bind_address: "0.0.0.0".into(),+ trusted_proxies: Vec::new(),}}}@@ -1428,10 +1454,48 @@ mod tests {}}+ /// The safe default: no proxy is trusted, so `X-Forwarded-For` carries no+ /// authority anywhere until an operator says otherwise (#76 S5-4).+ #[test]+ fn trusted_proxies_default_to_empty() {+ assert!(Config::default().server.trusted_proxies.is_empty());+ let cfg = Config::from_toml_str("[server]\nrest_port = 9000\n").unwrap();+ assert!(cfg.server.trusted_proxies.is_empty());+ assert!(+ crate::net::TrustedProxies::parse(&cfg.server.trusted_proxies)+ .unwrap()+ .is_empty()+ );+ }++ #[test]+ fn trusted_proxies_parse_from_toml() {+ let cfg = Config::from_toml_str("[server]\ntrusted_proxies = [\"10.0.0.0/8\", \"::1\"]\n")+ .unwrap();+ cfg.validate().unwrap();+ let t = crate::net::TrustedProxies::parse(&cfg.server.trusted_proxies).unwrap();+ assert!(t.contains(&"10.4.5.6".parse().unwrap()));+ assert!(!t.contains(&"11.4.5.6".parse().unwrap()));+ }++ /// A typo in a trust boundary fails startup rather than silently+ /// producing a set that trusts nothing (or everything).+ #[test]+ fn malformed_trusted_proxy_fails_validation() {+ let err = Config::from_toml_str("[server]\ntrusted_proxies = [\"10.0.0.0/99\"]\n")+ .unwrap_err()+ .to_string();+ assert!(+ err.contains("trusted_proxies"),+ "error should name the setting, got: {err}"+ );+ }+#[test]fn count_user_facing_settings() {// 50 user-facing settings:- // server: 5 (rest_port, grpc_port, es_compat_port, data_dir, bind_address)+ // server: 6 (rest_port, grpc_port, es_compat_port, data_dir,+ // bind_address, trusted_proxies)// auth: 3 (enabled, admin_api_key, metrics_token) ← RC4-W4 item 4// tls: 3 (enabled, cert_path, key_path)// storage: 10 (wal_sync, wal_batch_ms, wal_max_size_mb, flush_size_mb,@@ -1450,8 +1514,8 @@ mod tests {// indexing: 3 (turbo_batch_size, turbo_parallel, turbo_fast_analyzer)// logging: 2 (format, access_log) ← RC4-W4 item 6// ─────────- // total: 59 fields, minus 1 auto-generated (admin_api_key) = 58 meaningful user settings- let total: usize = 5 + 3 + 3 + 10 + 5 + 3 + 1 + 6 + 2 + 4 + 12 + 3 + 2;- assert_eq!(total, 59);+ // total: 60 fields, minus 1 auto-generated (admin_api_key) = 59 meaningful user settings+ let total: usize = 6 + 3 + 3 + 10 + 5 + 3 + 1 + 6 + 2 + 4 + 12 + 3 + 2;+ assert_eq!(total, 60);}}diff --git a/engine/crates/xerj-common/src/lib.rs b/engine/crates/xerj-common/src/lib.rsindex 80aebf936..7a94e6a1e 100644--- a/engine/crates/xerj-common/src/lib.rs+++ b/engine/crates/xerj-common/src/lib.rs@@ -18,11 +18,13 @@//! - [`types`] — Core domain types (documents, fields, IDs)//! - [`schema`] — Index schema management and mapping evolution//! - [`metrics`] — Prometheus counters, histograms, and gauges+//! - [`net`] — Network trust primitives (trusted-proxy CIDR matching)pub mod config;pub mod error;pub mod fsio;pub mod metrics;+pub mod net;pub mod schema;pub mod types;diff --git a/engine/crates/xerj-common/src/net.rs b/engine/crates/xerj-common/src/net.rsnew file mode 100644index 000000000..ec666ce4b--- /dev/null+++ b/engine/crates/xerj-common/src/net.rs@@ -0,0 +1,296 @@+//! Network trust primitives — who is allowed to tell us who the client is.+//!+//! Xerj derives the caller's identity (per-IP auth rate-limit bucket,+//! audit-log source address) from the TCP peer address, which a caller+//! cannot forge. Behind a legitimate reverse proxy the peer *is* the proxy,+//! which would collapse every user into one bucket, so the proxy's+//! `X-Forwarded-For` header has to be honoured — but only when the socket+//! peer is a proxy the operator has actually declared.+//!+//! [`TrustedProxies`] is that declaration: a parsed set of addresses / CIDR+//! blocks. It is **empty by default**, and an empty set trusts nothing, so a+//! node that has not been configured for a proxy ignores forwarding headers+//! entirely.++use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};++/// One entry of the trusted-proxy list: a base address plus a prefix length.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+struct Cidr {+ base: IpAddr,+ prefix_len: u8,+}++impl Cidr {+ /// Parse `"10.0.0.7"`, `"10.0.0.0/8"`, `"::1"`, `"fd00::/8"`.+ ///+ /// A bare address is treated as a host route (`/32` for v4, `/128` for+ /// v6). The prefix length must fit the address family.+ fn parse(s: &str) -> Result<Self, String> {+ let s = s.trim();+ if s.is_empty() {+ return Err("empty entry".to_string());+ }+ let (addr_str, prefix_str) = match s.split_once('/') {+ Some((a, p)) => (a, Some(p)),+ None => (s, None),+ };+ let base: IpAddr = addr_str+ .parse()+ .map_err(|_| format!("`{addr_str}` is not an IP address"))?;+ let max_len: u8 = match base {+ IpAddr::V4(_) => 32,+ IpAddr::V6(_) => 128,+ };+ let prefix_len = match prefix_str {+ None => max_len,+ Some(p) => {+ let n: u8 = p+ .parse()+ .map_err(|_| format!("`{p}` is not a prefix length"))?;+ if n > max_len {+ return Err(format!("prefix /{n} exceeds /{max_len} for `{addr_str}`"));+ }+ n+ }+ };+ Ok(Self { base, prefix_len })+ }++ fn contains(&self, ip: &IpAddr) -> bool {+ match (self.base, ip) {+ (IpAddr::V4(base), IpAddr::V4(ip)) => {+ prefix_eq(&base.octets(), &ip.octets(), self.prefix_len)+ }+ (IpAddr::V6(base), IpAddr::V6(ip)) => {+ prefix_eq(&base.octets(), &ip.octets(), self.prefix_len)+ }+ // Families never cross: peers are canonicalised (v4-mapped v6+ // folded down to v4) before they get here, so a v4 peer is only+ // ever matched against v4 entries.+ _ => false,+ }+ }+}++/// Do `a` and `b` agree on their first `bits` bits?+fn prefix_eq(a: &[u8], b: &[u8], bits: u8) -> bool {+ let whole = (bits / 8) as usize;+ if a[..whole] != b[..whole] {+ return false;+ }+ let rem = bits % 8;+ if rem == 0 {+ return true;+ }+ let mask = 0xffu8 << (8 - rem);+ a[whole] & mask == b[whole] & mask+}++/// Fold an IPv4-mapped IPv6 address (`::ffff:1.2.3.4`) down to plain IPv4.+///+/// A dual-stack listener reports IPv4 peers in mapped form, so without this+/// a `10.0.0.0/8` entry would never match a real 10.x proxy.+pub fn canonical_ip(ip: IpAddr) -> IpAddr {+ match ip {+ IpAddr::V6(v6) => match v6.to_ipv4_mapped() {+ Some(v4) => IpAddr::V4(v4),+ None => IpAddr::V6(v6),+ },+ v4 => v4,+ }+}++/// The operator-declared set of reverse proxies whose forwarding headers may+/// be believed. Empty means "trust nothing" — the safe default.+#[derive(Debug, Clone, Default, PartialEq, Eq)]+pub struct TrustedProxies {+ entries: Vec<Cidr>,+}++impl TrustedProxies {+ /// A set that trusts nothing.+ pub fn none() -> Self {+ Self::default()+ }++ /// Parse a config list. Fails on the first malformed entry — a typo in a+ /// trust boundary must be loud, never silently "trusts nothing" (which+ /// would look like it worked) nor silently "trusts everything".+ pub fn parse(entries: &[String]) -> Result<Self, String> {+ let mut parsed = Vec::with_capacity(entries.len());+ for e in entries {+ parsed.push(Cidr::parse(e).map_err(|why| format!("`{e}`: {why}"))?);+ }+ Ok(Self { entries: parsed })+ }++ /// True when nothing is trusted (the default).+ pub fn is_empty(&self) -> bool {+ self.entries.is_empty()+ }++ /// Is `ip` one of the declared proxies?+ pub fn contains(&self, ip: &IpAddr) -> bool {+ if self.entries.is_empty() {+ return false;+ }+ let ip = canonical_ip(*ip);+ self.entries.iter().any(|e| e.contains(&ip))+ }+}++/// Parse one element of an `X-Forwarded-For` chain into an address.+///+/// Handles the shapes proxies actually emit: a bare address, a bracketed+/// IPv6 literal with a port (`[2001:db8::1]:443`), and an IPv4 address with+/// a port (`1.2.3.4:5678`). Returns `None` for anything else — including+/// RFC 7239 obfuscated identifiers (`_hidden`) and `unknown`, which carry no+/// address and must not be silently skipped over.+pub fn parse_forwarded_element(raw: &str) -> Option<IpAddr> {+ let s = raw.trim();+ if s.is_empty() {+ return None;+ }+ // `[v6]:port` or `[v6]`+ if let Some(rest) = s.strip_prefix('[') {+ let (inner, _) = rest.split_once(']')?;+ return inner.parse::<Ipv6Addr>().ok().map(IpAddr::V6);+ }+ if let Ok(ip) = s.parse::<IpAddr>() {+ return Some(ip);+ }+ // `1.2.3.4:5678` — only valid for v4; a bare v6 with a colon-port is+ // ambiguous and proxies are required to bracket it.+ if let Some((host, port)) = s.rsplit_once(':') {+ if !port.is_empty() && port.bytes().all(|b| b.is_ascii_digit()) {+ if let Ok(v4) = host.parse::<Ipv4Addr>() {+ return Some(IpAddr::V4(v4));+ }+ }+ }+ None+}++#[cfg(test)]+mod tests {+ use super::*;++ fn ip(s: &str) -> IpAddr {+ s.parse().unwrap()+ }++ #[test]+ fn empty_set_trusts_nothing() {+ let t = TrustedProxies::none();+ assert!(t.is_empty());+ for candidate in ["127.0.0.1", "10.0.0.1", "::1", "8.8.8.8"] {+ assert!(+ !t.contains(&ip(candidate)),+ "{candidate} must not be trusted"+ );+ }+ }++ #[test]+ fn host_entry_matches_exactly_one_address() {+ let t = TrustedProxies::parse(&["10.0.0.7".to_string()]).unwrap();+ assert!(t.contains(&ip("10.0.0.7")));+ assert!(!t.contains(&ip("10.0.0.8")));+ assert!(!t.contains(&ip("10.0.0.6")));+ }++ #[test]+ fn cidr_entry_matches_the_block_and_nothing_else() {+ let t = TrustedProxies::parse(&["10.1.2.0/24".to_string()]).unwrap();+ assert!(t.contains(&ip("10.1.2.0")));+ assert!(t.contains(&ip("10.1.2.255")));+ assert!(!t.contains(&ip("10.1.3.0")));+ assert!(!t.contains(&ip("10.1.1.255")));+ }++ #[test]+ fn non_byte_aligned_prefix_masks_correctly() {+ let t = TrustedProxies::parse(&["192.168.4.0/22".to_string()]).unwrap();+ assert!(t.contains(&ip("192.168.4.1")));+ assert!(t.contains(&ip("192.168.7.254")));+ assert!(!t.contains(&ip("192.168.8.1")));+ assert!(!t.contains(&ip("192.168.3.255")));+ }++ #[test]+ fn ipv6_entries_work() {+ let t = TrustedProxies::parse(&["fd00::/8".to_string(), "::1".to_string()]).unwrap();+ assert!(t.contains(&ip("fd12::9")));+ assert!(t.contains(&ip("::1")));+ assert!(!t.contains(&ip("2001:db8::1")));+ }++ #[test]+ fn families_do_not_cross() {+ let v4_only = TrustedProxies::parse(&["0.0.0.0/0".to_string()]).unwrap();+ assert!(v4_only.contains(&ip("8.8.8.8")));+ assert!(!v4_only.contains(&ip("2001:db8::1")));++ let v6_only = TrustedProxies::parse(&["::/0".to_string()]).unwrap();+ assert!(v6_only.contains(&ip("2001:db8::1")));+ assert!(!v6_only.contains(&ip("8.8.8.8")));+ }++ #[test]+ fn v4_mapped_v6_peer_matches_a_v4_entry() {+ let t = TrustedProxies::parse(&["10.0.0.0/8".to_string()]).unwrap();+ assert!(t.contains(&ip("::ffff:10.4.5.6")));+ assert!(!t.contains(&ip("::ffff:11.4.5.6")));+ }++ #[test]+ fn malformed_entries_are_rejected_loudly() {+ for bad in [+ "not-an-ip",+ "10.0.0.0/33",+ "::1/129",+ "10.0.0.0/abc",+ "",+ "example.com",+ ] {+ assert!(+ TrustedProxies::parse(&[bad.to_string()]).is_err(),+ "`{bad}` must be rejected"+ );+ }+ }++ #[test]+ fn forwarded_elements_parse_the_shapes_proxies_emit() {+ assert_eq!(parse_forwarded_element(" 1.2.3.4 "), Some(ip("1.2.3.4")));+ assert_eq!(parse_forwarded_element("1.2.3.4:5678"), Some(ip("1.2.3.4")));+ assert_eq!(+ parse_forwarded_element("2001:db8::1"),+ Some(ip("2001:db8::1"))+ );+ assert_eq!(+ parse_forwarded_element("[2001:db8::1]:443"),+ Some(ip("2001:db8::1"))+ );+ assert_eq!(+ parse_forwarded_element("[2001:db8::1]"),+ Some(ip("2001:db8::1"))+ );+ }++ #[test]+ fn forwarded_elements_that_carry_no_address_are_none() {+ for bad in [+ "",+ " ",+ "unknown",+ "_hidden",+ "1.2.3.4.5",+ "[bogus]",+ "evil",+ ] {+ assert_eq!(parse_forwarded_element(bad), None, "`{bad}` must not parse");+ }+ }+}diff --git a/engine/crates/xerj-console-api/src/auth/login.rs b/engine/crates/xerj-console-api/src/auth/login.rsindex 51901094f..4c115dcf3 100644--- a/engine/crates/xerj-console-api/src/auth/login.rs+++ b/engine/crates/xerj-console-api/src/auth/login.rs@@ -22,6 +22,7 @@ use serde_json::json;use webauthn_rs::prelude::*;use crate::auth::{audit, rate_limit, sessions, store, webauthn_setup};+use crate::client_ip::ClientIp;use crate::error::{ConsoleApiError, ConsoleResult};use crate::indices;use crate::response::ok;@@ -47,10 +48,9 @@ pub struct BeginResponse {pub async fn begin(State(state): State<ConsoleState>,- headers: HeaderMap,+ ClientIp(ip): ClientIp,Json(body): Json<BeginBody>,) -> ConsoleResult<Response> {- let ip = ip_from_headers(&headers);rate_limit::charge(&state, &ip, "login-begin")?;if body.email.is_empty() {@@ -119,10 +119,10 @@ pub struct FinishBody {pub async fn finish(State(state): State<ConsoleState>,+ ClientIp(ip): ClientIp,headers: HeaderMap,Json(body): Json<FinishBody>,) -> ConsoleResult<Response> {- let ip = ip_from_headers(&headers);rate_limit::charge(&state, &ip, "login-finish")?;let pending = state@@ -272,19 +272,4 @@ fn prune_pending(state: &ConsoleState) {.retain(|_k, v| v.created_at_ms > cutoff);}-fn ip_from_headers(headers: &HeaderMap) -> String {- if let Some(v) = headers.get("x-forwarded-for").and_then(|h| h.to_str().ok()) {- if let Some(first) = v.split(',').next() {- let t = first.trim();- if !t.is_empty() {- return t.to_string();- }- }- }- if let Some(v) = headers.get("x-real-ip").and_then(|h| h.to_str().ok()) {- return v.trim().to_string();- }- "unknown".to_string()-}-use base64::Engine as _;diff --git a/engine/crates/xerj-console-api/src/auth/magic.rs b/engine/crates/xerj-console-api/src/auth/magic.rsindex 14cbfd9d7..accde5d67 100644--- a/engine/crates/xerj-console-api/src/auth/magic.rs+++ b/engine/crates/xerj-console-api/src/auth/magic.rs@@ -16,13 +16,14 @@//! Enrollment session lives only in RAM (not persisted) for 30 minutes//! and is consumed exactly once by `passkey/finish`.-use axum::{extract::State, http::HeaderMap, response::Response, Json};+use axum::{extract::State, response::Response, Json};use rand::RngCore;use serde::{Deserialize, Serialize};use serde_json::json;use crate::auth::{audit, rate_limit, store, AuthSession};use crate::bootstrap::sha256_hex;+use crate::client_ip::ClientIp;use crate::error::{ConsoleApiError, ConsoleResult};use crate::indices;use crate::response::ok;@@ -72,7 +73,7 @@ pub struct IssueResponse {pub async fn issue(State(state): State<ConsoleState>,session: AuthSession,- headers: HeaderMap,+ ClientIp(ip): ClientIp,Json(body): Json<IssueBody>,) -> ConsoleResult<Response> {// Only owners and admins may invite.@@ -147,7 +148,6 @@ pub async fn issue(};store::put_magic_link(&state.engine, &link).await?;- let ip = ip_from_headers(&headers);audit::record(&state.engine,&session.user.id,@@ -193,13 +193,13 @@ pub struct RedeemResponse {pub async fn redeem(State(state): State<ConsoleState>,- headers: HeaderMap,+ ClientIp(ip): ClientIp,Json(body): Json<RedeemBody>,) -> ConsoleResult<Response> {- // Rate-limit by source IP. We pull headers manually here because- // FromRequestParts wiring would force every endpoint into the same- // typed extractor.- let ip = ip_from_headers(&headers);+ // Rate-limit by source IP. `ClientIp` resolves that from the TCP peer,+ // consulting `x-forwarded-for` only when the peer is a configured+ // trusted proxy (#76 S5-4) — this endpoint is unauthenticated, so a+ // header-derived key would let anyone mint a fresh quota per request.rate_limit::charge(&state, &ip, "magic-redeem")?;if body.token.is_empty() {@@ -365,26 +365,10 @@ fn audit_redeem_failed(state: &ConsoleState, why: &str, ip: &str) {use base64::Engine as _;-fn ip_from_headers(headers: &HeaderMap) -> String {- if let Some(v) = headers.get("x-forwarded-for").and_then(|h| h.to_str().ok()) {- if let Some(first) = v.split(',').next() {- let t = first.trim();- if !t.is_empty() {- return t.to_string();- }- }- }- if let Some(v) = headers.get("x-real-ip").and_then(|h| h.to_str().ok()) {- return v.trim().to_string();- }- "unknown".to_string()-}-#[cfg(test)]mod tests {use std::sync::Arc;- use axum::http::HeaderValue;use tempfile::TempDir;use tokio::sync::Barrier;@@ -436,15 +420,14 @@ mod tests {}/// Drive the handler exactly as axum would. Every call declares its own- /// source IP so the per-IP limiter (10/min) never fires — a 429 would- /// silently stand in for a rejected redemption and hide the invariant- /// under test.+ /// resolved source IP so the per-IP limiter (10/min) never fires — a 429+ /// would silently stand in for a rejected redemption and hide the+ /// invariant under test. Note this is the *resolved* address (post trust+ /// check), not a header a caller could set: see `client_ip`.async fn redeem_as(state: &ConsoleState, token: &str, ip: &str) -> ConsoleResult<Response> {- let mut headers = HeaderMap::new();- headers.insert("x-forwarded-for", HeaderValue::from_str(ip).unwrap());redeem(State(state.clone()),- headers,+ ClientIp(ip.to_string()),Json(RedeemBody {token: token.to_string(),}),diff --git a/engine/crates/xerj-console-api/src/auth/passkey.rs b/engine/crates/xerj-console-api/src/auth/passkey.rsindex 23f28a26b..4db68eee6 100644--- a/engine/crates/xerj-console-api/src/auth/passkey.rs+++ b/engine/crates/xerj-console-api/src/auth/passkey.rs@@ -25,6 +25,7 @@ use serde_json::json;use webauthn_rs::prelude::*;use crate::auth::{audit, sessions, store, webauthn_setup};+use crate::client_ip::ClientIp;use crate::error::{ConsoleApiError, ConsoleResult};use crate::indices;use crate::response::ok;@@ -164,6 +165,7 @@ pub struct FinishBody {pub async fn finish(State(state): State<ConsoleState>,+ ClientIp(ip): ClientIp,headers: HeaderMap,Json(body): Json<FinishBody>,) -> ConsoleResult<Response> {@@ -245,7 +247,6 @@ pub async fn finish(store::upsert_user(&state.engine, &user).await?;// Audit + session cookie.- let ip = sessions_request_ip(&headers);let ua = headers.get("user-agent").and_then(|h| h.to_str().ok())@@ -315,19 +316,4 @@ fn prune_pending(state: &ConsoleState) {.retain(|_k, v| v.created_at_ms > cutoff);}-fn sessions_request_ip(headers: &HeaderMap) -> String {- if let Some(v) = headers.get("x-forwarded-for").and_then(|h| h.to_str().ok()) {- if let Some(first) = v.split(',').next() {- let t = first.trim();- if !t.is_empty() {- return t.to_string();- }- }- }- if let Some(v) = headers.get("x-real-ip").and_then(|h| h.to_str().ok()) {- return v.trim().to_string();- }- "unknown".to_string()-}-use base64::Engine as _;diff --git a/engine/crates/xerj-console-api/src/auth/rate_limit.rs b/engine/crates/xerj-console-api/src/auth/rate_limit.rsindex 137c40dbc..179787a7d 100644--- a/engine/crates/xerj-console-api/src/auth/rate_limit.rs+++ b/engine/crates/xerj-console-api/src/auth/rate_limit.rs@@ -7,11 +7,14 @@//!//! On limit exceeded we return 429 with no body — leaking whether the//! email/token was valid would defeat the purpose of rate limiting.+//!+//! The `ip` this keys on must come from [`crate::ClientIp`] — the TCP peer,+//! consulting `x-forwarded-for` only from a declared trusted proxy. Deriving+//! it from headers is what made the limiter bypassable (#76 S5-4); there is+//! deliberately no header-reading helper in this module to reach for.use std::sync::atomic::{AtomicU64, Ordering};-use axum::http::request::Parts;-use crate::error::{ConsoleApiError, ConsoleResult};use crate::state::{ConsoleState, RateWindow};use crate::time::now_epoch_ms;@@ -21,29 +24,6 @@ const PER_HOUR: u32 = 100;const WINDOW_MIN_MS: i64 = 60_000;const WINDOW_HOUR_MS: i64 = 3_600_000;-/// Pull the caller's IP out of the request — `x-forwarded-for` (first-/// element) when present, else falling through to `x-real-ip`, else-/// "unknown" (so a misconfigured deployment still rate-limits, though-/// per-host instead of per-IP).-pub fn caller_ip(parts: &Parts) -> String {- if let Some(v) = parts- .headers- .get("x-forwarded-for")- .and_then(|h| h.to_str().ok())- {- if let Some(first) = v.split(',').next() {- let trimmed = first.trim();- if !trimmed.is_empty() {- return trimmed.to_string();- }- }- }- if let Some(v) = parts.headers.get("x-real-ip").and_then(|h| h.to_str().ok()) {- return v.trim().to_string();- }- "unknown".to_string()-}-/// Counter of insertions, used to drive periodic pruning so we never/// pay for a full sweep. (DashMap iter is per-shard locking, so a/// 1-in-50 prune keeps tail latency unaffected.)diff --git a/engine/crates/xerj-console-api/src/client_ip.rs b/engine/crates/xerj-console-api/src/client_ip.rsnew file mode 100644index 000000000..69df7e051--- /dev/null+++ b/engine/crates/xerj-console-api/src/client_ip.rs@@ -0,0 +1,407 @@+//! Who the caller *is*, as opposed to who they claim to be (#76 S5-4).+//!+//! Every auth endpoint charges a per-IP rate-limit bucket and stamps a source+//! address into the audit log. Both used to be derived from `X-Forwarded-For`+//! — a header the caller writes. A rotating `x-forwarded-for: 1.2.3.$RANDOM`+//! therefore got a fresh quota on every request (unthrottled brute force of+//! magic links and the bootstrap claim) while honest clients, who send no such+//! header, stayed throttled. Exactly backwards.+//!+//! The address now comes from the transport: [`axum::extract::ConnectInfo`],+//! i.e. the TCP peer, which the caller cannot forge.+//!+//! ## Reverse proxies+//!+//! Behind a legitimate proxy the peer *is* the proxy, and keying purely on the+//! socket would collapse every user into one bucket — a self-inflicted DoS. So+//! forwarding headers are honoured, but only when the socket peer is a proxy+//! the operator declared in `server.trusted_proxies`. The list is empty by+//! default: **an unconfigured node believes nobody**.+//!+//! ## Reading the chain+//!+//! `X-Forwarded-For` is a comma-separated chain, appended to left-to-right.+//! The left end is whatever the original caller sent — attacker-controlled.+//! The *right-most* entry is the one your own outermost proxy just wrote, so+//! the chain is walked right-to-left, skipping entries that are themselves+//! declared proxies, and the first non-proxy address wins. A malformed+//! element stops the walk (we do not step over it into attacker-authored+//! text) and we fall back to the peer.++use std::net::{IpAddr, SocketAddr};++use axum::{+ async_trait,+ extract::{ConnectInfo, FromRequestParts},+ http::{request::Parts, HeaderMap},+};+use xerj_common::net::{canonical_ip, parse_forwarded_element, TrustedProxies};++/// The bucket key used when we cannot establish any address at all (no+/// `ConnectInfo` in the request extensions — e.g. a router driven directly by+/// `tower::ServiceExt::oneshot` in a test, or a future transport that does not+/// carry a peer). Failing to one shared bucket throttles rather than+/// exempts: strictly safer than believing a header.+pub const UNKNOWN_IP: &str = "unknown";++/// Resolve the caller's address.+///+/// `peer` is the real socket peer. Returns the address as a string because+/// that is what the rate-limit key and the audit record want; the value is+/// always either a canonical IP literal or [`UNKNOWN_IP`], never+/// caller-authored text.+pub fn resolve(peer: Option<IpAddr>, headers: &HeaderMap, trusted: &TrustedProxies) -> String {+ let Some(peer) = peer.map(canonical_ip) else {+ // No transport identity. Header data cannot rescue this — it would+ // reintroduce the very spoof we are closing.+ return UNKNOWN_IP.to_string();+ };++ // The common case, and the whole point: an ordinary client's headers are+ // never consulted.+ if !trusted.contains(&peer) {+ return peer.to_string();+ }++ // Peer is a declared proxy — its forwarding headers may be believed.+ // Multiple `X-Forwarded-For` headers are equivalent to one comma-joined+ // header (RFC 7230 §3.2.2), so walk every value, right-to-left.+ let elements: Vec<&str> = headers+ .get_all("x-forwarded-for")+ .iter()+ .filter_map(|v| v.to_str().ok())+ .flat_map(|v| v.split(','))+ .collect();++ if !elements.is_empty() {+ for element in elements.iter().rev() {+ match parse_forwarded_element(element) {+ Some(ip) => {+ let ip = canonical_ip(ip);+ if !trusted.contains(&ip) {+ return ip.to_string();+ }+ // Another of our own proxies — keep walking left.+ }+ // Garbage or an obfuscated identifier. Stop: anything further+ // left is behind text we could not validate.+ None => return peer.to_string(),+ }+ }+ // Every hop in the chain was one of our own proxies; the original+ // client was never recorded.+ return peer.to_string();+ }++ // No forwarded chain — honour the single-valued `X-Real-IP` that nginx+ // and friends set. Same trust gate: only because the peer is declared.+ if let Some(ip) = headers+ .get("x-real-ip")+ .and_then(|v| v.to_str().ok())+ .and_then(parse_forwarded_element)+ {+ return canonical_ip(ip).to_string();+ }++ peer.to_string()+}++/// Extractor form: the caller's address, already trust-resolved.+///+/// Use this in handlers instead of reading headers. It needs `ConnectInfo` in+/// the request extensions, which the server installs via+/// `into_make_service_with_connect_info::<SocketAddr>()` on both the plain and+/// the TLS listener.+#[derive(Debug, Clone)]+pub struct ClientIp(pub String);++impl ClientIp {+ pub fn as_str(&self) -> &str {+ &self.0+ }+}++#[async_trait]+impl<S> FromRequestParts<S> for ClientIp+where+ S: TrustedProxySource + Send + Sync,+{+ type Rejection = std::convert::Infallible;++ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {+ let peer = parts+ .extensions+ .get::<ConnectInfo<SocketAddr>>()+ .map(|ci| ci.0.ip());+ Ok(ClientIp(resolve(+ peer,+ &parts.headers,+ state.trusted_proxies(),+ )))+ }+}++/// State that can say which proxies are trusted. Implemented by+/// `ConsoleState`; a trait so the extractor stays testable without one.+pub trait TrustedProxySource {+ fn trusted_proxies(&self) -> &TrustedProxies;+}++#[cfg(test)]+mod tests {+ use super::*;++ fn headers(pairs: &[(&str, &str)]) -> HeaderMap {+ let mut h = HeaderMap::new();+ for (k, v) in pairs {+ h.append(+ axum::http::HeaderName::from_bytes(k.as_bytes()).unwrap(),+ axum::http::HeaderValue::from_str(v).unwrap(),+ );+ }+ h+ }++ fn ip(s: &str) -> IpAddr {+ s.parse().unwrap()+ }++ fn trust(entries: &[&str]) -> TrustedProxies {+ TrustedProxies::parse(&entries.iter().map(|s| s.to_string()).collect::<Vec<_>>()).unwrap()+ }++ // ── The defect itself ────────────────────────────────────────────────++ /// #76 S5-4: an untrusted caller cannot move its own rate-limit bucket.+ #[test]+ fn spoofed_header_from_untrusted_peer_is_ignored() {+ let t = TrustedProxies::none();+ let peer = Some(ip("203.0.113.9"));+ let baseline = resolve(peer, &HeaderMap::new(), &t);+ assert_eq!(baseline, "203.0.113.9");++ for spoof in ["1.2.3.4", "1.2.3.5, 9.9.9.9", " 8.8.8.8 ", "2001:db8::1"] {+ assert_eq!(+ resolve(peer, &headers(&[("x-forwarded-for", spoof)]), &t),+ baseline,+ "x-forwarded-for: {spoof} must not change the key"+ );+ }+ assert_eq!(+ resolve(peer, &headers(&[("x-real-ip", "1.2.3.4")]), &t),+ baseline+ );+ }++ /// The brute-force shape from the finding: a rotating header used to mint+ /// a new bucket per request. Every rotation must now collapse to one key.+ #[test]+ fn rotating_spoof_yields_one_key() {+ let t = TrustedProxies::none();+ let peer = Some(ip("203.0.113.9"));+ let keys: std::collections::HashSet<String> = (0..64)+ .map(|n| {+ resolve(+ peer,+ &headers(&[("x-forwarded-for", &format!("1.2.3.{n}"))]),+ &t,+ )+ })+ .collect();+ assert_eq!(keys.len(), 1, "rotating spoof produced {keys:?}");+ }++ /// Configuring a proxy does not make *other* peers trustworthy.+ #[test]+ fn peer_outside_the_trusted_set_is_still_ignored() {+ let t = trust(&["10.0.0.0/8"]);+ assert_eq!(+ resolve(+ Some(ip("203.0.113.9")),+ &headers(&[("x-forwarded-for", "1.2.3.4")]),+ &t+ ),+ "203.0.113.9"+ );+ }++ // ── The proxy case ───────────────────────────────────────────────────++ #[test]+ fn trusted_peer_has_its_forwarded_address_honoured() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "198.51.100.23")]),+ &t+ ),+ "198.51.100.23"+ );+ }++ /// The attacker owns the left end of the chain; only the right-most entry+ /// was written by our own proxy.+ #[test]+ fn rightmost_entry_wins_over_attacker_prefix() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "1.1.1.1, 2.2.2.2, 198.51.100.23")]),+ &t+ ),+ "198.51.100.23",+ "must not take the caller-authored left end"+ );+ }++ /// Two proxy hops: skip our own, take the first address neither of them.+ #[test]+ fn walks_left_past_our_own_proxies() {+ let t = trust(&["10.0.0.0/8"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "198.51.100.23, 10.0.0.9")]),+ &t+ ),+ "198.51.100.23"+ );+ }++ /// Split across repeated header lines — same chain semantics.+ #[test]+ fn repeated_headers_are_one_chain() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[+ ("x-forwarded-for", "1.1.1.1"),+ ("x-forwarded-for", "198.51.100.23"),+ ]),+ &t+ ),+ "198.51.100.23"+ );+ }++ /// An attacker behind our proxy can send garbage as the element to the+ /// left of the real one; we must not step over it and adopt their text.+ #[test]+ fn malformed_element_falls_back_to_the_peer() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "198.51.100.23, unknown")]),+ &t+ ),+ "10.0.0.7"+ );+ }++ #[test]+ fn all_hops_trusted_falls_back_to_the_peer() {+ let t = trust(&["10.0.0.0/8"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "10.0.0.4, 10.0.0.9")]),+ &t+ ),+ "10.0.0.7"+ );+ }++ #[test]+ fn trusted_peer_honours_x_real_ip_when_no_chain() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-real-ip", "198.51.100.23")]),+ &t+ ),+ "198.51.100.23"+ );+ }++ #[test]+ fn trusted_peer_with_no_headers_is_the_peer() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(Some(ip("10.0.0.7")), &HeaderMap::new(), &t),+ "10.0.0.7"+ );+ }++ // ── Edges ────────────────────────────────────────────────────────────++ /// No transport identity: one shared bucket, never a header-derived one.+ #[test]+ fn missing_connect_info_never_falls_back_to_headers() {+ for t in [TrustedProxies::none(), trust(&["0.0.0.0/0"])] {+ assert_eq!(+ resolve(None, &headers(&[("x-forwarded-for", "1.2.3.4")]), &t),+ UNKNOWN_IP+ );+ }+ }++ /// A dual-stack listener reports IPv4 peers as `::ffff:a.b.c.d`; the+ /// trusted-proxy entry is written in plain v4 form.+ #[test]+ fn v4_mapped_peer_matches_v4_trust_entry() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("::ffff:10.0.0.7")),+ &headers(&[("x-forwarded-for", "198.51.100.23")]),+ &t+ ),+ "198.51.100.23"+ );+ // …and the key for an ordinary v4-mapped client is the plain v4 form,+ // so one client never occupies two buckets.+ assert_eq!(+ resolve(Some(ip("::ffff:203.0.113.9")), &HeaderMap::new(), &t),+ "203.0.113.9"+ );+ }++ #[test]+ fn forwarded_entries_with_ports_are_accepted() {+ let t = trust(&["10.0.0.7"]);+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "198.51.100.23:44321")]),+ &t+ ),+ "198.51.100.23"+ );+ assert_eq!(+ resolve(+ Some(ip("10.0.0.7")),+ &headers(&[("x-forwarded-for", "[2001:db8::5]:443")]),+ &t+ ),+ "2001:db8::5"+ );+ }++ /// The socket port is not part of identity — otherwise every connection+ /// from one host would get its own quota.+ #[test]+ fn peer_port_is_not_part_of_the_key() {+ let t = TrustedProxies::none();+ let a: SocketAddr = "203.0.113.9:1111".parse().unwrap();+ let b: SocketAddr = "203.0.113.9:2222".parse().unwrap();+ assert_eq!(+ resolve(Some(a.ip()), &HeaderMap::new(), &t),+ resolve(Some(b.ip()), &HeaderMap::new(), &t)+ );+ }+}diff --git a/engine/crates/xerj-console-api/src/lib.rs b/engine/crates/xerj-console-api/src/lib.rsindex 4cb9cd234..77d71c556 100644--- a/engine/crates/xerj-console-api/src/lib.rs+++ b/engine/crates/xerj-console-api/src/lib.rs@@ -43,6 +43,7 @@pub mod auth;pub mod bootstrap;+pub mod client_ip;pub mod cluster;pub mod dashboards;pub mod data_sources;@@ -57,6 +58,7 @@ pub mod state;pub mod time;pub mod views;+pub use client_ip::ClientIp;pub use error::{ConsoleApiError, ConsoleResult};pub use router::xerj_console_router;pub use state::ConsoleState;diff --git a/engine/crates/xerj-console-api/src/state.rs b/engine/crates/xerj-console-api/src/state.rsindex 932f1a3f3..3d58cd645 100644--- a/engine/crates/xerj-console-api/src/state.rs+++ b/engine/crates/xerj-console-api/src/state.rs@@ -8,8 +8,10 @@use std::sync::Arc;use dashmap::DashMap;+use xerj_common::net::TrustedProxies;use xerj_engine::Engine;+use crate::client_ip::TrustedProxySource;use crate::time::now_epoch_ms;/// Server start time, in epoch ms. Used by `/cluster/info` so the SPA can@@ -127,6 +129,13 @@ pub struct ConsoleState {/// transition atomic. Redemptions are rare (enrollment/recovery), so a/// single gate is cheaper than a per-token map and needs no cleanup.pub redeem_gate: Arc<tokio::sync::Mutex<()>>,++ /// Reverse proxies whose `X-Forwarded-For` / `X-Real-IP` we believe+ /// (#76 S5-4). Empty by default — an unconfigured node derives client+ /// identity from the socket peer only, so the auth rate limiter cannot be+ /// side-stepped with a forged header. Populated from+ /// `server.trusted_proxies` by `xerj-server` at startup.+ pub trusted_proxies: Arc<TrustedProxies>,}#[derive(Debug, Clone, Copy)]@@ -169,8 +178,24 @@ impl ConsoleState {auth_rate_counters: Arc::new(DashMap::new()),master_key: Arc::new(master_key),redeem_gate: Arc::new(tokio::sync::Mutex::new(())),+ trusted_proxies: Arc::new(TrustedProxies::none()),}}++ /// Declare the reverse proxies whose forwarding headers may be believed.+ ///+ /// Builder-style so the safe default (trust nothing) is what you get+ /// unless a caller opts in explicitly.+ pub fn with_trusted_proxies(mut self, trusted: TrustedProxies) -> Self {+ self.trusted_proxies = Arc::new(trusted);+ self+ }+}++impl TrustedProxySource for ConsoleState {+ fn trusted_proxies(&self) -> &TrustedProxies {+ &self.trusted_proxies+ }}impl std::fmt::Debug for ConsoleState {diff --git a/engine/crates/xerj-console-api/tests/trusted_proxy_client_identity.rs b/engine/crates/xerj-console-api/tests/trusted_proxy_client_identity.rsnew file mode 100644index 000000000..62340e000--- /dev/null+++ b/engine/crates/xerj-console-api/tests/trusted_proxy_client_identity.rs@@ -0,0 +1,204 @@+//! #76 S5-4 — `x-forwarded-for` must not be trusted for client identity.+//!+//! The per-IP auth rate limiter used to key on `x-forwarded-for`, a header the+//! caller writes. A rotating `x-forwarded-for: 1.2.3.$RANDOM` therefore reset+//! the quota on every request (unthrottled brute force of the magic-link /+//! bootstrap-claim endpoints) while honest clients, who send no such header,+//! stayed throttled.+//!+//! These drive the *real* router — `ConnectInfo` supplied exactly as the axum+//! listener supplies it — and assert both halves of the fix:+//!+//! - an untrusted peer's forwarded header changes nothing;+//! - a peer the operator declared in `server.trusted_proxies` has its+//! forwarded address honoured, so real users behind a proxy still get one+//! bucket each.++use std::net::SocketAddr;++use axum::{body::Body, extract::ConnectInfo, http::Request, Router};+use serde_json::json;+use tempfile::TempDir;+use tower::ServiceExt;+use xerj_common::{config::Config, net::TrustedProxies};+use xerj_console_api::{state::ClusterMode, xerj_console_router, ConsoleState};+use xerj_engine::Engine;++/// PER_MINUTE in `auth/rate_limit.rs`.+const PER_MINUTE: usize = 10;++const LOGIN_BEGIN: &str = "/_xerj-console/api/v1/auth/login/begin";++async fn boot(trusted: &[&str]) -> (Router, TempDir) {+ let dir = TempDir::new().unwrap();+ let mut cfg = Config::default();+ cfg.server.data_dir = dir.path().to_str().unwrap().to_string();+ let engine = Engine::new(cfg).expect("engine");+ let outcome = xerj_console_api::bootstrap::run(&engine, dir.path(), "http://localhost:9200")+ .await+ .expect("bootstrap");+ let trusted =+ TrustedProxies::parse(&trusted.iter().map(|s| s.to_string()).collect::<Vec<_>>()).unwrap();+ let state = ConsoleState::new(+ engine,+ "local".into(),+ outcome.master_key,+ ClusterMode::Standalone,+ )+ .with_trusted_proxies(trusted);+ (xerj_console_router(state), dir)+}++/// One `POST /auth/login/begin` from `peer`, optionally carrying `xff`.+/// `ConnectInfo` is inserted the same way axum's+/// `into_make_service_with_connect_info` inserts it.+async fn login_begin(router: &Router, peer: &str, xff: Option<&str>) -> u16 {+ let peer: SocketAddr = peer.parse().expect("peer must be addr:port");+ let mut req = Request::builder()+ .method("POST")+ .uri(LOGIN_BEGIN)+ .header("content-type", "application/json");+ if let Some(xff) = xff {+ req = req.header("x-forwarded-for", xff);+ }+ let mut req = req+ .body(Body::from(json!({ "email": "x@y" }).to_string()))+ .unwrap();+ req.extensions_mut().insert(ConnectInfo(peer));++ router.clone().oneshot(req).await.unwrap().status().as_u16()+}++/// The exploit, verbatim: a rotating forwarded header from one untrusted+/// caller. Every request must land in the *same* bucket, so the limiter fires+/// on schedule instead of never.+#[tokio::test]+async fn rotating_forwarded_header_cannot_refresh_the_quota() {+ let (router, _dir) = boot(&[]).await;++ let mut statuses = Vec::new();+ for n in 0..PER_MINUTE + 5 {+ statuses.push(login_begin(&router, "203.0.113.9:44321", Some(&format!("1.2.3.{n}"))).await);+ }++ assert!(+ statuses[..PER_MINUTE].iter().all(|s| *s == 200),+ "first {PER_MINUTE} should pass: {statuses:?}"+ );+ assert!(+ statuses[PER_MINUTE..].iter().all(|s| *s == 429),+ "a rotating x-forwarded-for must NOT mint a fresh quota: {statuses:?}"+ );+}++/// …and the header cannot be used to frame someone else either: an exhausted+/// attacker cannot spend a victim's quota, and a victim's socket is unaffected+/// by whatever the attacker claimed to be.+#[tokio::test]+async fn untrusted_peer_cannot_move_its_bucket_onto_another_address() {+ let (router, _dir) = boot(&[]).await;++ for _ in 0..PER_MINUTE {+ assert_eq!(login_begin(&router, "203.0.113.9:1000", None).await, 200);+ }+ assert_eq!(+ login_begin(&router, "203.0.113.9:1000", Some("198.51.100.23")).await,+ 429,+ "spoofing another address must not buy a fresh quota"+ );+ assert_eq!(+ login_begin(&router, "198.51.100.23:1000", None).await,+ 200,+ "the spoofed victim's own bucket must be untouched"+ );+}++/// A different socket peer is a different bucket — the limiter still does its+/// job for distinct clients rather than collapsing everyone together.+#[tokio::test]+async fn distinct_peers_have_distinct_buckets() {+ let (router, _dir) = boot(&[]).await;++ for _ in 0..PER_MINUTE {+ assert_eq!(login_begin(&router, "203.0.113.9:1000", None).await, 200);+ }+ assert_eq!(login_begin(&router, "203.0.113.9:1000", None).await, 429);+ assert_eq!(+ login_begin(&router, "203.0.113.10:1000", None).await,+ 200,+ "a different peer must not inherit the exhausted bucket"+ );+ // Ports are not identity: the same host on a new connection is the same+ // bucket, or one client could just reconnect for a fresh quota.+ assert_eq!(login_begin(&router, "203.0.113.9:2000", None).await, 429);+}++/// Behind a declared proxy the peer is always the proxy, so the forwarded+/// address must be honoured — otherwise every user collapses into one bucket+/// and ten logins company-wide per minute locks everybody out.+#[tokio::test]+async fn trusted_peer_has_its_forwarded_address_honoured() {+ let (router, _dir) = boot(&["10.0.0.7"]).await;++ for _ in 0..PER_MINUTE {+ assert_eq!(+ login_begin(&router, "10.0.0.7:1000", Some("198.51.100.23")).await,+ 200+ );+ }+ assert_eq!(+ login_begin(&router, "10.0.0.7:1000", Some("198.51.100.23")).await,+ 429,+ "the forwarded client must be throttled on its own bucket"+ );+ assert_eq!(+ login_begin(&router, "10.0.0.7:1000", Some("198.51.100.24")).await,+ 200,+ "a different forwarded client must have its own bucket"+ );+}++/// The chain is appended left-to-right, so the left end is whatever the caller+/// sent. Only the right-most entry was written by our own proxy. A client that+/// pre-seeds `x-forwarded-for` must not be able to pick its own bucket.+#[tokio::test]+async fn attacker_prefix_in_the_chain_is_ignored() {+ let (router, _dir) = boot(&["10.0.0.7"]).await;++ for n in 0..PER_MINUTE {+ // Attacker rotates the part *they* control; the proxy appends the+ // truth on the right.+ assert_eq!(+ login_begin(+ &router,+ "10.0.0.7:1000",+ Some(&format!("9.9.9.{n}, 198.51.100.23"))+ )+ .await,+ 200+ );+ }+ assert_eq!(+ login_begin(&router, "10.0.0.7:1000", Some("9.9.9.250, 198.51.100.23")).await,+ 429,+ "the caller-authored left end must not select the bucket"+ );+}++/// Trusting one proxy does not make every peer trustworthy.+#[tokio::test]+async fn configuring_a_proxy_does_not_trust_other_peers() {+ let (router, _dir) = boot(&["10.0.0.7"]).await;++ for n in 0..PER_MINUTE {+ assert_eq!(+ login_begin(&router, "203.0.113.9:1000", Some(&format!("1.2.3.{n}"))).await,+ 200+ );+ }+ assert_eq!(+ login_begin(&router, "203.0.113.9:1000", Some("1.2.3.99")).await,+ 429,+ "a peer outside trusted_proxies is still keyed on its socket"+ );+}diff --git a/engine/crates/xerj-server/src/main.rs b/engine/crates/xerj-server/src/main.rsindex ae2f5eb84..d469d8fdb 100644--- a/engine/crates/xerj-server/src/main.rs+++ b/engine/crates/xerj-server/src/main.rs@@ -770,6 +770,15 @@ fn spawn_periodic_flusher(// Server runners// ─────────────────────────────────────────────────────────────────────────────+/// Serve `router` on `addr`, plain or TLS.+///+/// Both paths install `ConnectInfo<SocketAddr>` via+/// `into_make_service_with_connect_info`, so handlers can reach the real TCP+/// peer. That is what the console's per-IP auth rate limiter keys on — it used+/// to key on `x-forwarded-for`, which the caller writes, so a rotating header+/// bought an unlimited quota (#76 S5-4). Forwarding headers are believed only+/// when the peer is listed in `server.trusted_proxies`; without connect-info on+/// *both* listeners the limiter would fall back to a single shared bucket.async fn serve(router: Router,addr: SocketAddr,@@ -800,7 +809,7 @@ async fn serve(axum_server::bind_rustls(addr, tls).handle(handle)- .serve(router.into_make_service())+ .serve(router.into_make_service_with_connect_info::<SocketAddr>()).await.with_context(|| format!("{name} serve error (TLS)"))?;@@ -819,11 +828,14 @@ async fn serve(// (Netty) sets this by default; without it small request/response// round-trips can stall on the delayed-ACK/Nagle interaction, which// shows up as a fixed per-request latency tax on trivial reads.- axum::serve(listener, router)- .tcp_nodelay(true)- .with_graceful_shutdown(shutdown_signal())- .await- .with_context(|| format!("{name} serve error"))?;+ axum::serve(+ listener,+ router.into_make_service_with_connect_info::<SocketAddr>(),+ )+ .tcp_nodelay(true)+ .with_graceful_shutdown(shutdown_signal())+ .await+ .with_context(|| format!("{name} serve error"))?;info!("{name} shut down cleanly");Ok(())@@ -1594,12 +1606,31 @@ async fn async_main() -> Result<()> {} else {ClusterMode::Standalone};+ // #76 S5-4: which reverse proxies (if any) may tell us who the client is.+ // Empty by default — an unconfigured node ignores `x-forwarded-for`+ // entirely and keys the auth rate limiter on the TCP peer. `validate()`+ // already rejected malformed entries, so this parse cannot fail; treat a+ // surprise as fatal rather than silently widening or narrowing trust.+ let trusted_proxies = xerj_common::net::TrustedProxies::parse(&cfg.server.trusted_proxies)+ .map_err(|why| anyhow::anyhow!("server.trusted_proxies: {why}"))?;+ if !trusted_proxies.is_empty() {+ info!(+ "trusting x-forwarded-for from {} configured proxy entr{}",+ cfg.server.trusted_proxies.len(),+ if cfg.server.trusted_proxies.len() == 1 {+ "y"+ } else {+ "ies"+ }+ );+ }let xerj_console_state = ConsoleState::new(engine.clone(),xerj_console_node_id,xerj_console_outcome.master_key,xerj_console_cluster_mode,- );+ )+ .with_trusted_proxies(trusted_proxies);// 9b. Application statelet state = AppState::new(cfg.clone(), engine, metrics);@@ -1743,7 +1774,20 @@ mod tls_tests {}fn test_router() -> Router {- Router::new().route("/", get(|| async { "ok" }))+ Router::new()+ .route("/", get(|| async { "ok" }))+ // Echoes the transport peer so a test can prove `serve` installed+ // `ConnectInfo` — the identity the auth rate limiter keys on+ // (#76 S5-4). Without connect-info wiring this handler would 500+ // (missing extension), which is exactly the regression to catch.+ .route(+ "/peer",+ get(+ |axum::extract::ConnectInfo(peer): axum::extract::ConnectInfo<SocketAddr>| async move {+ peer.ip().to_string()+ },+ ),+ )}/// Poll until the just-spawned listener answers (spawn races the client).@@ -1813,6 +1857,84 @@ mod tls_tests {server.abort();}+ /// #76 S5-4: the plain listener must hand handlers the real TCP peer.+ /// The console rate limiter keys on it; if `ConnectInfo` is missing the+ /// limiter degrades to one shared bucket and, worse, the only remaining+ /// signal would be the caller-supplied header we are refusing to trust.+ /// A spoofed `x-forwarded-for` must not perturb what the transport says.+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn plain_listener_exposes_the_real_peer_not_the_header() {+ let port = free_port();+ let addr: SocketAddr = ([127, 0, 0, 1], port).into();+ let server = tokio::spawn(serve(test_router(), addr, "test-peer-plain", None));++ let client = reqwest::Client::new();+ assert_eq!(+ poll_status(&client, &format!("http://127.0.0.1:{port}/")).await,+ 200+ );++ let body = client+ .get(format!("http://127.0.0.1:{port}/peer"))+ .header("x-forwarded-for", "1.2.3.4")+ .send()+ .await+ .unwrap()+ .text()+ .await+ .unwrap();+ assert_eq!(+ body, "127.0.0.1",+ "handler must see the socket peer, not the spoofed header"+ );++ server.abort();+ }++ /// Same guarantee on the TLS path — it uses a different accept loop+ /// (`axum_server`), so connect-info has to be wired there independently.+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn tls_listener_exposes_the_real_peer_not_the_header() {+ let dir = tempfile::tempdir().unwrap();+ let mut cfg = Config::default();+ cfg.server.data_dir = dir.path().to_string_lossy().into_owned();+ cfg.tls.enabled = true;+ ensure_tls_cert(&mut cfg).expect("generate self-signed cert");+ let tls = build_tls_config(&cfg)+ .await+ .expect("build tls config")+ .expect("tls enabled must yield Some");++ let port = free_port();+ let addr: SocketAddr = ([127, 0, 0, 1], port).into();+ let server = tokio::spawn(serve(test_router(), addr, "test-peer-tls", Some(tls)));++ let client = reqwest::Client::builder()+ .danger_accept_invalid_certs(true)+ .build()+ .unwrap();+ assert_eq!(+ poll_status(&client, &format!("https://127.0.0.1:{port}/")).await,+ 200+ );++ let body = client+ .get(format!("https://127.0.0.1:{port}/peer"))+ .header("x-forwarded-for", "1.2.3.4")+ .send()+ .await+ .unwrap()+ .text()+ .await+ .unwrap();+ assert_eq!(+ body, "127.0.0.1",+ "TLS handler must see the socket peer, not the spoofed header"+ );++ server.abort();+ }+/// TLS enabled but the cert path is missing → `build_tls_config` fails/// loud rather than silently downgrading to cleartext.#[tokio::test]diff --git a/engine/xerj.default.toml b/engine/xerj.default.tomlindex 1b388f82c..2d36ab445 100644--- a/engine/xerj.default.toml+++ b/engine/xerj.default.toml@@ -11,7 +11,7 @@# every default below.# ============================================================-# ── Network & Data Directory (5 settings) ─────────────────────────────────────+# ── Network & Data Directory (6 settings) ─────────────────────────────────────[server]@@ -35,6 +35,21 @@ data_dir = "./data"# "0.0.0.0" listens on all interfaces; use "127.0.0.1" for localhost only.bind_address = "0.0.0.0"+# Reverse proxies whose X-Forwarded-For / X-Real-IP headers may be believed.+#+# Client identity — the per-IP auth rate-limit bucket and the audit-log source+# address — is taken from the TCP peer, which a caller cannot forge.+# X-Forwarded-For is attacker-controlled and is IGNORED unless the socket peer+# matches an entry here. Default is empty: believe nobody.+#+# If you terminate TLS or load-balance in front of xerj, list that proxy here+# or every user behind it shares one rate-limit bucket. List ONLY proxies you+# operate: anything named here can claim to be any client.+#+# Entries are addresses or CIDR blocks; a bad entry fails startup.+# trusted_proxies = ["10.0.0.7", "10.1.0.0/16", "::1"]+trusted_proxies = []+# ── Authentication (2 settings) ───────────────────────────────────────────────[auth]