Skip to content

armgit / xerj

Public Imported from GitHub
0

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.

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.md
index 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.0
Prior to this, the rule was half-enforced: `flat_object`/`flattened`
were special-cased into a `400` while every other ES-forbidden type
passed.
+### 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 limiter
keys on. The fix needs `ConnectInfo` threaded through the shared
serve 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 described
under 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.md
index 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 registered
and consult `x-forwarded-for` only when the socket peer is a trusted proxy in an
operator-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 · open
diff --git a/docs/recipes/production-deployment.md b/docs/recipes/production-deployment.md
index 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 of
clients reach it over an untrusted link. If you don't use gRPC, don't expose
the 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 hydration
diff --git a/engine/crates/xerj-common/src/config.rs b/engine/crates/xerj-common/src/config.rs
index 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 supplied
if 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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 state
let 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.toml
index 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]