Add CIRCL GeoIP integration proof

Author: eldryoth

CHANGELOG.md

@@ -15,6 +15,11 @@ behavior when the change improves security or project direction.
   access-decision plugins with separate clock and randomness grants.
 - Add checked-in WASI randomness policy/config examples, standalone real-Wasm
   smoke coverage, and live native HTTP/1 listener coverage.
+- Restore trusted-client GeoIP context lookup in the native HTTP router for
+  HTTP/1 and HTTP/2 access policy.
+- Support CIRCL Geo Open's combined Country and ASN MMDB schema and add an
+  opt-in checksum-pinned real-database smoke covering static, proxy, and
+  load-balanced country/ASN policy.
 
 ### Security
 

Cargo.lock

@@ -73,7 +73,7 @@ load-balancer = [
 stream-proxy = ["proxy", "dep:fluxheim-stream", "fluxheim-config/stream-proxy"]
 udp-proxy = ["proxy", "fluxheim-config/udp-proxy"]
 traffic-mirror = ["proxy", "fluxheim-config/traffic-mirror", "fluxheim-server/traffic-mirror"]
-geoip = ["proxy", "fluxheim-config/geoip", "fluxheim-geoip/runtime"]
+geoip = ["proxy", "fluxheim-config/geoip", "fluxheim-server/geoip"]
 wasm = ["dep:fluxheim-wasm", "fluxheim-config/wasm", "fluxheim-server/wasm", "fluxheim-wasm/runtime"]
 wasm-proxy-abi = ["wasm", "fluxheim-config/wasm-proxy-abi", "fluxheim-server/wasm-proxy-abi", "fluxheim-wasm/proxy-abi"]
 wasm-wasi = ["wasm", "fluxheim-config/wasm-wasi", "fluxheim-server/wasm-wasi", "fluxheim-wasm/wasi"]
@@ -253,7 +253,6 @@ fluxheim-acme = { path = "crates/fluxheim-acme", optional = true }
 fluxheim-compression = { path = "crates/fluxheim-compression" }
 fluxheim-config = { path = "crates/fluxheim-config" }
 fluxheim-cache = { path = "crates/fluxheim-cache" }
-fluxheim-geoip = { path = "crates/fluxheim-geoip" }
 fluxheim-headers = { path = "crates/fluxheim-headers" }
 fluxheim-load-balancer = { path = "crates/fluxheim-load-balancer", optional = true }
 fluxheim-observability = { path = "crates/fluxheim-observability" }

Cargo.toml

@@ -134,7 +134,7 @@ Fluxheim is licensed under the European Union Public Licence 1.2.
 | Config module split | ✅ | `1.4.3`; config loading, shared helpers, domain validation, and large config tests are split into focused `config_*` modules while keeping `crate::config::*` stable. |
 | Load-balancer module split | ✅ | `1.5.0`; health checks, backend state, persistence, selection algorithms, backend policy/status, and file/DNS discovery are split into focused `load_balancer/*` modules while keeping `crate::load_balancer::*` stable. |
 | Apple Silicon macOS dev builds | ✅ | `1.4.4`; Level 1 developer support with Mac-safe runtime paths while some upstream macOS support remains experimental. |
-| GeoIP/Geo-Context policy | ✅ | `1.4.5`; optional bounded local MMDB support with trusted-file enforcement for MaxMind GeoIP2/GeoLite2 and CIRCL Geo Open datasets, plus vhost/route country and ASN ACLs. |
+| GeoIP/Geo-Context policy | ✅ | `1.4.5`; optional bounded local MMDB support with trusted-file enforcement for MaxMind GeoIP2/GeoLite2 and CIRCL Geo Open datasets, plus vhost/route country and ASN ACLs. The [GeoIP guide](docs/geoip.md) includes a pinned real CIRCL database proof for static, proxy, and load-balancer paths. |
 | Pingora-free runtime | ✅ | `1.6.34`; normal Fluxheim builds no longer compile Pingora crates. Server/listener/TLS, HTTP/1, HTTP/2, WebSocket, cache, load-balancer, admin, metrics, stream, and background-service paths run through Fluxheim-owned Rust crates. |
 | HTTP/3/QUIC | ❌ | Planned as a Fluxheim-owned `1.9` protocol milestone using the Rust `quinn`/`h3` stack after the `1.8` macOS/Windows production parity line. |
 | WASM extensibility | 🧪 | Active `1.7.x` line. `1.7.0` added the optional `wasm` feature, strict plugin-file loading, bounded Wasmtime execution, and real-Wasm smoke coverage. `1.7.1` adds config-level plugin registry validation, deterministic attachment ordering, admission limits, metrics, and live native HTTP/1 access-decision hooks. `1.7.2` adds bounded native HTTP/1 request/response header hooks. `1.7.3` starts bounded native HTTP/1 route-decision hooks with configured canary and mirror branch selection, including selected native load-balanced and persistent routes. `1.7.4` starts VCL-like cache-policy hooks with bounded cache-lookup and cache-store decisions for continue/pass/bypass/skip-store/deny around cache lookup and storage. `1.7.5` adds bounded symbolic cache-key component hooks for low-cardinality cache variants plus fixed-ID cache-store TTL/tag/header metadata, symbolic content-type inspection, and a checked-in cache-policy example. `1.7.6` starts mature-runtime hardening with explicit compiled-module identities that isolate module reuse by plugin digest, ABI version, native feature surface, and Fluxheim version. `1.7.7` adds the opt-in `wasm-proxy-abi` compatibility preview boundary. `1.7.8` starts an opt-in WASI Preview 1 boundary with explicit clock/randomness grants and fail-closed import filtering. Direct backend choice, plugin-provided persistence keys, dynamic mirror/shadow target choice, and richer store policy hooks remain staged for later `1.7.x`. |

README.md

@@ -0,0 +1,54 @@
+use std::net::IpAddr;
+use std::path::PathBuf;
+
+use fluxheim_config::{GeoIpConfig, GeoIpDatabaseConfig, GeoIpProvider};
+use fluxheim_geoip::{GeoIpPolicyUsage, GeoIpRuntime};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut arguments = std::env::args().skip(1);
+    let provider = match arguments.next().as_deref() {
+        Some("circl-geo-open") => GeoIpProvider::CirclGeoOpen,
+        Some("maxmind") => GeoIpProvider::Maxmind,
+        _ => return Err("usage: lookup <circl-geo-open|maxmind> <database.mmdb> <ip>...".into()),
+    };
+    let path = arguments
+        .next()
+        .map(PathBuf::from)
+        .ok_or("missing MMDB path")?;
+    let addresses = arguments
+        .map(|value| value.parse::<IpAddr>())
+        .collect::<Result<Vec<_>, _>>()?;
+    if addresses.is_empty() {
+        return Err("at least one IP address is required".into());
+    }
+
+    let config = GeoIpConfig {
+        enabled: true,
+        fallback_enabled: true,
+        databases: vec![GeoIpDatabaseConfig { provider, path }],
+    };
+    let runtime = GeoIpRuntime::from_config(
+        &config,
+        GeoIpPolicyUsage {
+            country: true,
+            asn: true,
+        },
+    )?
+    .ok_or("GeoIP runtime was not enabled")?;
+
+    for address in addresses {
+        match runtime.lookup(address) {
+            Some(context) => println!(
+                "{address}\tcountry={}\tasn={}",
+                context.country_iso().unwrap_or("-"),
+                context
+                    .asn()
+                    .map(|asn| asn.to_string())
+                    .as_deref()
+                    .unwrap_or("-")
+            ),
+            None => println!("{address}\tcountry=-\tasn=-"),
+        }
+    }
+    Ok(())
+}

crates/fluxheim-geoip/examples/lookup.rs

@@ -1,6 +1,6 @@
 use super::{
-    GeoIpLoadLimits, GeoIpPolicyUsage, GeoIpRuntime, admitted_geoip_total, normalized_country,
-    open_verified_mmdb, read_verified_mmdb_with_post_read,
+    GeoIpLoadLimits, GeoIpPolicyUsage, GeoIpRuntime, admitted_geoip_total, normalized_asn,
+    normalized_country, open_verified_mmdb, read_verified_mmdb_with_post_read,
 };
 use fluxheim_config::{GeoIpConfig, GeoIpDatabaseConfig, GeoIpProvider};
 
@@ -27,6 +27,16 @@ fn normalizes_country_codes() {
     assert_eq!(normalized_country(&"A".repeat(4096)), None);
 }
 
+#[test]
+fn normalizes_circl_asn_strings() {
+    assert_eq!(normalized_asn("13335"), Some(13_335));
+    assert_eq!(normalized_asn("0"), None);
+    assert_eq!(normalized_asn("+13335"), None);
+    assert_eq!(normalized_asn("13335 "), None);
+    assert_eq!(normalized_asn("4294967296"), None);
+    assert_eq!(normalized_asn(&"1".repeat(11)), None);
+}
+
 #[test]
 fn aggregate_limit_rejects_before_mmdb_parse() {
     let path = trusted_test_file("geoip-aggregate-limit", b"not-a-valid-mmdb");

crates/fluxheim-geoip/src/geoip_runtime/tests.rs

@@ -1,6 +1,7 @@
 use std::io;
 
 const MAX_RAW_COUNTRY_CODE_BYTES: usize = 8;
+const MAX_RAW_ASN_BYTES: usize = 10;
 
 pub(super) fn normalized_country(value: &str) -> Option<String> {
     if value.len() > MAX_RAW_COUNTRY_CODE_BYTES {
@@ -23,3 +24,13 @@ pub(super) fn admitted_geoip_total(current: u64, next: u64, maximum: u64) -> io:
     }
     Ok(total)
 }
+
+pub(super) fn normalized_asn(value: &str) -> Option<u32> {
+    if value.is_empty()
+        || value.len() > MAX_RAW_ASN_BYTES
+        || !value.bytes().all(|byte| byte.is_ascii_digit())
+    {
+        return None;
+    }
+    value.parse::<u32>().ok().filter(|asn| *asn > 0)
+}

crates/fluxheim-geoip/src/geoip_runtime/value.rs

@@ -78,7 +78,7 @@ mod geoip_runtime {
     mod value;
 
     use file_path::{O_NOFOLLOW, path_contains_symlink};
-    use value::{admitted_geoip_total, normalized_country};
+    use value::{admitted_geoip_total, normalized_asn, normalized_country};
 
     const MAX_GEOIP_DATABASE_BYTES: u64 = 512 * 1024 * 1024;
     const MAX_TOTAL_GEOIP_DATABASE_BYTES: u64 = 1024 * 1024 * 1024;
@@ -187,6 +187,7 @@ mod geoip_runtime {
 
     #[derive(Debug)]
     struct GeoIpDatabase {
+        provider: GeoIpProvider,
         reader: Reader<Vec<u8>>,
         database_type: String,
     }
@@ -205,6 +206,7 @@ mod geoip_runtime {
             })?;
             let database_type = reader.metadata().database_type.clone();
             Ok(Self {
+                provider,
                 reader,
                 database_type,
             })
@@ -228,7 +230,18 @@ mod geoip_runtime {
                 .decode::<geoip2::Asn<'_>>()
                 .ok()
                 .flatten()
-                .and_then(|asn| asn.autonomous_system_number.filter(|asn| *asn > 0));
+                .and_then(|asn| asn.autonomous_system_number.filter(|asn| *asn > 0))
+                .or_else(|| {
+                    (self.provider == GeoIpProvider::CirclGeoOpen)
+                        .then(|| {
+                            lookup
+                                .decode_path::<&str>(&path!["country", "AutonomousSystemNumber"])
+                                .ok()
+                                .flatten()
+                                .and_then(normalized_asn)
+                        })
+                        .flatten()
+                });
             (country.and_then(normalized_country), asn)
         }
 

crates/fluxheim-geoip/src/lib.rs

@@ -17,6 +17,7 @@ compression = ["dep:fluxheim-compression"]
 compression-brotli = ["compression", "fluxheim-compression/brotli"]
 compression-gzip = ["compression", "fluxheim-compression/gzip"]
 compression-zstd = ["compression", "fluxheim-compression/zstd"]
+geoip = ["dep:fluxheim-geoip", "fluxheim-config/geoip", "fluxheim-geoip/runtime"]
 load-balancer = ["dep:fluxheim-load-balancer"]
 otel-tracing = ["dep:fluxheim-observability", "fluxheim-config/otel-tracing"]
 php-fpm = ["dep:fastcgi-client", "dep:fluxheim-php-fpm", "tokio/fs"]
@@ -38,6 +39,7 @@ fluxheim-common = { path = "../fluxheim-common" }
 fluxheim-cache = { path = "../fluxheim-cache" }
 fluxheim-compression = { path = "../fluxheim-compression", optional = true }
 fluxheim-config = { path = "../fluxheim-config" }
+fluxheim-geoip = { path = "../fluxheim-geoip", optional = true }
 fluxheim-headers = { path = "../fluxheim-headers" }
 fluxheim-load-balancer = { path = "../fluxheim-load-balancer", optional = true }
 fluxheim-observability = { path = "../fluxheim-observability", optional = true }

crates/fluxheim-server/Cargo.toml

@@ -7,6 +7,8 @@ use std::time::Duration;
 
 use fluxheim_config::config_net::{normalize_host, normalize_host_pattern};
 use fluxheim_config::{Config, VhostConfig};
+#[cfg(feature = "geoip")]
+use fluxheim_geoip::{GeoIpPolicyUsage, GeoIpRuntime};
 
 #[path = "native_http1_host_router_cache.rs"]
 mod native_http1_host_router_cache;
@@ -42,6 +44,8 @@ pub struct NativeHttp1HostRouter {
     wildcard_hosts: Vec<NativeHttp1WildcardHost>,
     default_proxy: Arc<NativeHttp1RouteProxy>,
     strict: bool,
+    #[cfg(feature = "geoip")]
+    geoip: Option<Arc<GeoIpRuntime>>,
 }
 
 #[derive(Clone, Debug)]
@@ -103,6 +107,10 @@ pub enum NativeHttp1HostRouterConfigError {
         first_scope: String,
         second_scope: String,
     },
+    #[cfg(feature = "geoip")]
+    GeoIp {
+        reason: String,
+    },
 }
 
 impl std::fmt::Display for NativeHttp1HostRouterConfigError {
@@ -142,6 +150,8 @@ impl std::fmt::Display for NativeHttp1HostRouterConfigError {
                 formatter,
                 "storage-bin cache root {path:?} is shared by {first_scope} and {second_scope}; each cache policy requires a unique root"
             ),
+            #[cfg(feature = "geoip")]
+            Self::GeoIp { reason } => write!(formatter, "GeoIP runtime: {reason}"),
         }
     }
 }
@@ -206,6 +216,12 @@ impl NativeHttp1HostRouter {
         NativeHttp1HostRouterConfigError,
     > {
         validate_unique_storage_bin_roots(config)?;
+        #[cfg(feature = "geoip")]
+        let geoip = GeoIpRuntime::from_config(&config.geoip, geoip_policy_usage(config))
+            .map_err(|error| NativeHttp1HostRouterConfigError::GeoIp {
+                reason: error.to_string(),
+            })?
+            .map(Arc::new);
         #[cfg(not(feature = "load-balancer"))]
         let _ = config;
         #[cfg_attr(not(feature = "load-balancer"), allow(unused_mut))]
@@ -221,6 +237,8 @@ impl NativeHttp1HostRouter {
                 collect_load_balancer_services.then_some(&mut load_balancer_services),
                 #[cfg(feature = "load-balancer")]
                 Some(&mut load_balancer_admin_pools),
+                #[cfg(feature = "geoip")]
+                geoip,
             )
             .map(|router| (router, load_balancer_services, load_balancer_admin_pools));
         }
@@ -281,6 +299,8 @@ impl NativeHttp1HostRouter {
                 wildcard_hosts,
                 default_proxy,
                 strict: config.server.host_routing.strict,
+                #[cfg(feature = "geoip")]
+                geoip,
             },
             load_balancer_services,
             load_balancer_admin_pools,
@@ -297,6 +317,7 @@ impl NativeHttp1HostRouter {
         #[cfg(feature = "load-balancer")] load_balancer_admin_pools: Option<
             &mut Vec<crate::NativeLoadBalancerAdminPool>,
         >,
+        #[cfg(feature = "geoip")] geoip: Option<Arc<GeoIpRuntime>>,
     ) -> Result<Self, NativeHttp1HostRouterConfigError> {
         let default_proxy =
             match NativeHttp1RouteProxy::from_root_config_with_load_balancer_services(
@@ -319,6 +340,8 @@ impl NativeHttp1HostRouter {
             wildcard_hosts: Vec::new(),
             default_proxy,
             strict: false,
+            #[cfg(feature = "geoip")]
+            geoip,
         })
     }
 
@@ -386,6 +409,16 @@ impl NativeHttp1Handler for NativeHttp1HostRouter {
     fn prepare_request_context(&self, request: &mut NativeHttp1Request) {
         if let Ok(proxy) = self.select_request(request) {
             proxy.prepare_request_context(request);
+            #[cfg(feature = "geoip")]
+            if let Some(geoip) = &self.geoip {
+                request.geo_context = proxy
+                    .access_client_ip(request)
+                    .and_then(|client_ip| geoip.lookup(client_ip))
+                    .map(|context| crate::NativeHttp1GeoContext {
+                        country_iso: context.country_iso().map(str::to_owned),
+                        asn: context.asn(),
+                    });
+            }
         }
     }
 
@@ -424,6 +457,27 @@ impl NativeHttp1Handler for NativeHttp1HostRouter {
     }
 }
 
+#[cfg(feature = "geoip")]
+fn geoip_policy_usage(config: &Config) -> GeoIpPolicyUsage {
+    let mut usage = GeoIpPolicyUsage::default();
+    for vhost in &config.vhosts {
+        record_geoip_policy_usage(&vhost.access, &mut usage);
+        for route in &vhost.routes {
+            record_geoip_policy_usage(&route.access, &mut usage);
+        }
+    }
+    usage
+}
+
+#[cfg(feature = "geoip")]
+fn record_geoip_policy_usage(
+    access: &fluxheim_config::AccessPolicyConfig,
+    usage: &mut GeoIpPolicyUsage,
+) {
+    usage.country |= !access.allow_countries.is_empty() || !access.deny_countries.is_empty();
+    usage.asn |= !access.allow_asns.is_empty() || !access.deny_asns.is_empty();
+}
+
 fn route_proxy_from_config(
     config: &Config,
     vhost: &VhostConfig,