Axum: add protected CloudFront Geo metadata provider #432

Goal

Add an optional native Geo provider for Axum applications that consumes trusted CloudFront country and country-region metadata through a checked ingress boundary. Provider selection is explicit and optional. Geo remains separate from config, secret and KV stores.

This is the CloudFront portion of the original Geo follow-up under #391. Local GeoIP database support is tracked separately in #438. Do not expand the AWS store-provider PR #414 to include geography.

Why this is needed

The checked native ingress work in #409 provides client-IP facts and their provenance, but not visitor country or subdivision. Trusted Server's native PlatformGeo currently returns no geography, leaving jurisdiction unknown. Its intentional fail-closed auction/identity behavior is documented in IABTechLab/trusted-server#1134.

An AWS deployment region is not visitor geography. A browser language, timezone, arbitrary country header or missing TCF string is not a substitute either.

Provider contract and ownership

• Expose typed geographic facts through the existing request/runtime composition model: at least optional country and subdivision, with provider provenance and explicit unavailable/partial/error behavior. Do not invent a country, region, city or coordinates to fill missing fields.
• EdgeZero owns provider mechanics and checked metadata. Applications own jurisdiction classification, regulatory lists, CMP interpretation, consent and auction/identity decisions. Geography is an estimate, not proof of residency or consent.
• Provider selection is explicit and optional. Absence remains unavailable; a configured provider must not silently switch to another source. Keep native provider dependencies default-off and preserve portable/WASM contracts.
• Reuse existing native startup/initializer ownership and explicit runtime options or bindings patterns. No new general plugin framework is required.

Trusted CloudFront metadata

• Optionally consume CloudFront country and country-region headers through a checked ingress boundary, with strict parsing and explicit missing/partial behavior.
• Require a deployment-owned, protected CloudFront-to-origin path and header provenance. Reaching the application through a trusted ALB subnet alone does not prove that a geographic header originated at CloudFront.
• Reject or ignore spoofed, duplicate, malformed or untrusted assertions. Never trust raw geographic headers supplied directly by a client.
• Keep CloudFront provisioning and origin access configuration in deployment guidance, not automatic SDK infrastructure mutation. Header consumption must not require AWS store providers or AWS SDK calls.

Acceptance

• Explicit CloudFront provider selection, default-off dependencies and provider availability have focused tests; invalid selected configuration fails before listen without provider fallback.
• Ingress fixtures cover a verified source, direct-client spoofing, an ALB forwarding unverified headers, malformed/duplicate assertions and missing subdivision.
• Consumers can distinguish unavailable or partial geography from a known result. In particular, US country with no state retains an unknown subdivision; the provider makes no claim about which privacy regime applies.
• Documentation shows protected CloudFront deployment guidance, privacy-safe diagnostics, capability limitations and the difference between geographic facts and application policy.
• Existing adapters, native lifecycle behavior and WASM/default dependency checks remain intact. Record fixture evidence separately from any real CloudFront deployment acceptance.

Geo remains optional for general Axum hosting. A downstream profile that depends on geography must demonstrate its configured provider or retain its existing fail-closed behavior. This issue does not authorize changing Trusted Server's consent rules, adding an assumed jurisdiction, or implementing an identity database.

Related

• Parent epic: Make the Axum adapter production-ready for self-hosted deployments #391
• Checked native ingress: feat(axum): add safe diagnostics and trusted proxy metadata #409
• Local GeoIP database provider: Axum: follow up with an explicit local GeoIP provider #438
• Related client metadata work: Axum ClientInfo #92
• Native provider composition reference, separate scope: Add native AWS store providers #414
• Downstream adoption and policy: An adapter with no geo module fails closed on Edge Cookie creation and on the auction trusted-server#1134
• CloudFront header reference: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html