feat(visitor-analytics): add trusted online geolocation enrichment #623

Context

The Visitor Analytics module must work in offline/LAN mode without internet, while online deployments may optionally enrich visitor data with trusted proxy or Cloudflare headers.

AWCMS-Mini must not trust spoofable proxy headers by default. Online geolocation must be gated explicitly and must never become required for local/offline/LAN operation.

Objective

Add optional trusted online IP/geolocation enrichment for visitor analytics, using only trusted request headers or local data and never calling external geolocation APIs in the request path.

Scope

Add infrastructure helpers under:

src/modules/visitor-analytics/infrastructure/

Suggested files:

• client-ip.ts
• geo-enrichment.ts

Supported sources:

• Direct client address from the runtime.
• Trusted reverse proxy headers only when VISITOR_ANALYTICS_TRUST_PROXY=true.
• Trusted Cloudflare headers only when VISITOR_ANALYTICS_TRUST_CLOUDFLARE=true.
• Country code from Cloudflare-style headers where available.
• Region/city/timezone only if provided by a trusted source or a local/offline database configured later.
• CF-Ray or equivalent request diagnostic may be stored only as non-secret operational metadata if useful.

Configuration:

VISITOR_ANALYTICS_GEO_ENABLED=false
VISITOR_ANALYTICS_TRUST_PROXY=false
VISITOR_ANALYTICS_TRUST_CLOUDFLARE=false

Runtime behavior:

• If all geo/trust flags are false, enrichment returns empty geo data.
• If Cloudflare trust is enabled, prefer Cloudflare client IP/country headers according to configured trust rules.
• If trusted proxy is enabled, parse proxy headers conservatively.
• If multiple conflicting forwarded values exist, prefer fail-safe behavior and log a warning without trusting ambiguous data.
• Never equate APP_ENV=production with trusted proxy or trusted Cloudflare.

Out of scope

• External network calls to geolocation providers.
• Paid GeoIP integration.
• Cloudflare Worker-specific analytics.
• Bot score integration unless explicitly added in a later issue.
• Blocking requests based on country or IP.

Acceptance criteria

• Default offline/LAN behavior does not trust X-Forwarded-For or any provider header.
• Spoofed X-Forwarded-For is ignored when trust proxy is false.
• Cloudflare headers are ignored unless VISITOR_ANALYTICS_TRUST_CLOUDFLARE=true.
• Geolocation fields remain null/empty when VISITOR_ANALYTICS_GEO_ENABLED=false.
• No external network call is made during request collection.
• Ambiguous forwarded headers fail safe and do not produce a trusted client IP.
• Tests cover direct connection, spoofed XFF, trusted proxy, trusted Cloudflare, geo disabled, and ambiguous header chains.
• Docs explain online vs offline behavior and required reverse proxy/Cloudflare trust boundary.
• bun test passes.
• bun run check passes.

Security and privacy notes

• IP and geolocation are personal/sensitive operational data. Do not collect them by default beyond hashed/minimized fields.
• Do not trust client-controlled headers.
• Do not use geolocation enrichment for authorization or tenant resolution.
• Do not call third-party geolocation APIs from middleware or request transactions.
• Online enrichment should be optional and privacy-first.

Dependencies

Depends on #617, #619, and #620. It can be implemented after the MVP offline/LAN collector is working.