Bound GeoIP security context loading

Author: eldryoth

CHANGELOG.md

@@ -34,6 +34,8 @@ behavior when the change improves security or project direction.
   `sanitization::SecretVec`, and fix the managed child `PATH`.
 - Bind managed PHP-FPM spawn to a trusted executable descriptor and terminate
   its complete dedicated process group during shutdown and watchdog recovery.
+- Bound GeoIP database reads to an exact admitted-length allocation with a
+  separate growth probe, and validate every publicly constructed `GeoContext`.
 
 ## 1.7.7 - 2026-07-10
 

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

@@ -98,11 +98,45 @@ fn rejects_writable_database_and_parent() {
 fn rejects_database_modified_during_read() {
     let path = trusted_test_file("geoip-read-change", b"first-database");
     let verified = open_verified_mmdb(&path, 64).unwrap();
-    let error = read_verified_mmdb_with_post_read(verified, || {
+    let error = read_verified_mmdb_with_post_read(verified, |_| {
         std::fs::write(&path, b"other-database").unwrap();
     })
     .unwrap_err();
 
     assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
     assert!(error.to_string().contains("changed while reading"));
 }
+
+#[test]
+fn rejects_database_growth_without_growing_admitted_buffer() {
+    use std::io::Write as _;
+
+    let path = trusted_test_file("geoip-read-growth", b"database");
+    let verified = open_verified_mmdb(&path, 64).unwrap();
+    let admitted_len = usize::try_from(verified.byte_len).unwrap();
+    let observed_capacity = std::cell::Cell::new(usize::MAX);
+    let error = read_verified_mmdb_with_post_read(verified, |capacity| {
+        observed_capacity.set(capacity);
+        let mut file = std::fs::OpenOptions::new()
+            .append(true)
+            .open(&path)
+            .unwrap();
+        file.write_all(b"x").unwrap();
+    })
+    .unwrap_err();
+
+    assert_eq!(error.kind(), std::io::ErrorKind::InvalidInput);
+    assert!(error.to_string().contains("grew while reading"));
+    assert_eq!(observed_capacity.get(), admitted_len);
+}
+
+#[test]
+fn rejects_database_that_becomes_shorter_before_exact_read() {
+    let path = trusted_test_file("geoip-read-shorter", b"database");
+    let verified = open_verified_mmdb(&path, 64).unwrap();
+    std::fs::write(&path, b"short").unwrap();
+    let error = read_verified_mmdb_with_post_read(verified, |_| {}).unwrap_err();
+
+    assert_eq!(error.kind(), std::io::ErrorKind::UnexpectedEof);
+    assert!(error.to_string().contains("became shorter while reading"));
+}

crates/fluxheim-geoip/src/lib.rs

@@ -10,9 +10,40 @@ pub struct GeoContext {
     asn: Option<u32>,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum GeoContextError {
+    InvalidCountry,
+    InvalidAsn,
+}
+
+impl std::fmt::Display for GeoContextError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidCountry => {
+                formatter.write_str("country must contain exactly two ASCII letters")
+            }
+            Self::InvalidAsn => formatter.write_str("ASN must be greater than zero"),
+        }
+    }
+}
+
+impl std::error::Error for GeoContextError {}
+
 impl GeoContext {
-    pub fn new(country_iso: Option<String>, asn: Option<u32>) -> Self {
-        Self { country_iso, asn }
+    pub fn try_new(country_iso: Option<String>, asn: Option<u32>) -> Result<Self, GeoContextError> {
+        let country_iso = match country_iso {
+            Some(value)
+                if value.len() == 2 && value.bytes().all(|byte| byte.is_ascii_alphabetic()) =>
+            {
+                Some(value.to_ascii_uppercase())
+            }
+            Some(_) => return Err(GeoContextError::InvalidCountry),
+            None => None,
+        };
+        if asn == Some(0) {
+            return Err(GeoContextError::InvalidAsn);
+        }
+        Ok(Self { country_iso, asn })
     }
 
     pub fn country_iso(&self) -> Option<&str> {
@@ -149,7 +180,7 @@ mod geoip_runtime {
                 }
             }
 
-            let context = GeoContext::new(country, asn);
+            let context = GeoContext::try_new(country, asn).ok()?;
             (!context.is_empty()).then_some(context)
         }
     }
@@ -438,38 +469,44 @@ mod geoip_runtime {
     }
 
     fn read_verified_mmdb(verified: VerifiedMmdbFile) -> io::Result<Vec<u8>> {
-        read_verified_mmdb_with_post_read(verified, || {})
+        read_verified_mmdb_with_post_read(verified, |_| {})
     }
 
     fn read_verified_mmdb_with_post_read(
         mut verified: VerifiedMmdbFile,
-        post_read: impl FnOnce(),
+        post_read: impl FnOnce(usize),
     ) -> io::Result<Vec<u8>> {
-        let capacity = usize::try_from(verified.byte_len).map_err(|_| {
+        let expected = usize::try_from(verified.byte_len).map_err(|_| {
             io::Error::new(
                 io::ErrorKind::InvalidInput,
                 "GeoIP database size cannot be represented on this platform",
             )
         })?;
         let mut contents = Vec::new();
-        contents.try_reserve_exact(capacity).map_err(|error| {
+        contents.try_reserve_exact(expected).map_err(|error| {
             io::Error::other(format!("failed to reserve GeoIP database buffer: {error}"))
         })?;
-        let mut limited = verified
-            .file
-            .by_ref()
-            .take(verified.byte_len.saturating_add(1));
-        limited.read_to_end(&mut contents)?;
-        if contents.len() as u64 != verified.byte_len {
+        contents.resize(expected, 0);
+        verified.file.read_exact(&mut contents).map_err(|error| {
+            io::Error::new(
+                error.kind(),
+                format!(
+                    "GeoIP database became shorter while reading {}: {error}",
+                    verified.path.display()
+                ),
+            )
+        })?;
+        post_read(contents.capacity());
+        let mut extra = [0_u8; 1];
+        if verified.file.read(&mut extra)? != 0 {
             return Err(io::Error::new(
                 io::ErrorKind::InvalidInput,
                 format!(
-                    "GeoIP database size changed while reading: {}",
+                    "GeoIP database grew while reading: {}",
                     verified.path.display()
                 ),
             ));
         }
-        post_read();
         let final_state = MmdbFileState::from_metadata(&verified.file.metadata()?);
         if final_state != verified.state {
             return Err(io::Error::new(
@@ -486,3 +523,32 @@ mod geoip_runtime {
 
 #[cfg(feature = "runtime")]
 pub use geoip_runtime::{GeoIpPolicyUsage, GeoIpRuntime};
+
+#[cfg(test)]
+mod geo_context_tests {
+    use super::{GeoContext, GeoContextError};
+
+    #[test]
+    fn public_constructor_normalizes_valid_security_context() {
+        let context = GeoContext::try_new(Some("se".to_owned()), Some(64_512)).unwrap();
+
+        assert_eq!(context.country_iso(), Some("SE"));
+        assert_eq!(context.asn(), Some(64_512));
+        assert!(!context.is_empty());
+        assert!(GeoContext::try_new(None, None).unwrap().is_empty());
+    }
+
+    #[test]
+    fn public_constructor_rejects_invalid_security_context() {
+        for country in ["", "S", "USA", "S1", "SÉ", " SE"] {
+            assert_eq!(
+                GeoContext::try_new(Some(country.to_owned()), None),
+                Err(GeoContextError::InvalidCountry)
+            );
+        }
+        assert_eq!(
+            GeoContext::try_new(Some("SE".to_owned()), Some(0)),
+            Err(GeoContextError::InvalidAsn)
+        );
+    }
+}

docs/config-reference.md

@@ -3165,13 +3165,16 @@ later databases when possible.
 Fluxheim does not download GeoIP databases in-process. Each MMDB file is capped
 at 512 MiB, each loaded GeoIP runtime is capped at 1 GiB total, and at most
 eight databases are accepted. Aggregate capacity is checked from the verified
-open descriptor before its contents are allocated, read, or parsed. Paths must
-be absolute and symlink-free; the file and every parent directory must be owned
-by root, the effective service user, or the platform root-equivalent owner and
-must not be group- or world-writable. Fluxheim rejects descriptor identity or
-metadata changes during loading. GeoIP update jobs should prepare and verify a
-replacement under a trusted directory, apply safe ownership and modes, then
-atomically rename it into place before reloading Fluxheim.
+open descriptor before its contents are allocated, read, or parsed. The loader
+allocates exactly the admitted length, reads it completely, then probes for one
+extra byte separately so concurrent file growth cannot amplify the heap
+allocation. Paths must be absolute and symlink-free; the file and every parent
+directory must be owned by root, the effective service user, or the platform
+root-equivalent owner and must not be group- or world-writable. Fluxheim rejects
+shortened, grown, descriptor-identity-changed, or metadata-changed databases
+during loading. GeoIP update jobs should prepare and verify a replacement under
+a trusted directory, apply safe ownership and modes, then atomically rename it
+into place before reloading Fluxheim.
 
 Vhost and route access policies can then use:
 
@@ -3184,8 +3187,10 @@ deny_asns = [64512]
 ```
 
 Country values must be uppercase ISO alpha-2 codes. ASN values are numeric and
-must be greater than zero. Geo allow lists fail closed when no Geo-Context is
-available; Geo deny lists deny only on a resolved match. See
+must be greater than zero. The Geo-Context API also validates these invariants
+and canonicalizes valid country values before they can reach policy. Geo allow
+lists fail closed when no Geo-Context is available; Geo deny lists deny only on
+a resolved match. See
 [`docs/geoip.md`](geoip.md) for the feature boundary and operational update
 pattern.
 

docs/geoip.md

@@ -43,15 +43,20 @@ rejected.
 
 Each MMDB file is capped at 512 MiB at both metadata and read time. Fluxheim
 opens and inspects each descriptor, checks its size against the remaining 1 GiB
-aggregate allowance, and only then allocates, reads, and parses it. At most
-eight databases are accepted by both config validation and the runtime crate.
-During hot reload, the old and new runtimes can briefly coexist while in-flight
+aggregate allowance, and only then allocates an exact-length input buffer,
+reads that admitted length, and probes one extra byte without growing the heap
+buffer. Shortened, grown, or metadata-changed files fail loading. At most eight
+databases are accepted by both config validation and the runtime crate. During
+hot reload, the old and new runtimes can briefly coexist while in-flight
 requests finish, so size host/container memory for up to two admitted runtimes
 plus parser overhead.
 
 Country fields are decoded as borrowed MMDB strings. Raw values longer than
 eight bytes are rejected before normalization or owned allocation; accepted
-values must normalize to exactly two ASCII letters.
+values must normalize to exactly two ASCII letters. Public `GeoContext`
+construction enforces the same invariant, canonicalizes accepted countries to
+uppercase, and rejects ASN zero so future policy consumers cannot introduce an
+invalid context through the crate API.
 
 ```toml
 [geoip]

release-notes/RELEASE_NOTES_1.7.8.md

@@ -54,6 +54,12 @@ general-purpose WASI application hosting.
 - Hold PHP memory bodies and bounded spool-read buffers in
   `sanitization::SecretVec`, clear consumed spool buffers immediately, and
   clear full buffer capacity on cancellation, error, or drop.
+- Read each verified GeoIP database into an exact admitted-length buffer and
+  probe growth with a separate stack byte, preventing a one-byte in-place
+  append from triggering large `Vec` capacity growth before rejection.
+- Validate public `GeoContext` construction, canonicalize accepted two-letter
+  ASCII countries to uppercase, and reject ASN zero before policy consumers can
+  observe malformed security state.
 - Replace inherited managed PHP-FPM `PATH` handling with a fixed allowlisted
   search path after clearing the child environment.