otto 2.6.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de513e2f41fa9d2400937ac2ed577878bd124d5f760558bd12635bf8ad6f296a
-  data.tar.gz: 4a69f3741d3a6dbbe5a7387e2504446ce690927be12ccf90fa814db1a893d13d
+  metadata.gz: 2d4e92c540f41f9cad40b495f8a7106f49a11d8eb9b5011981c97bf585026065
+  data.tar.gz: 10c592de40e1b0b35f57379b5dfca20a51b76967898e0cccce33d903fbfcb75d
 SHA512:
-  metadata.gz: 77ee1dda2b8b84e3848fb72fd737b88b6d6efca57cd0d4effe909451a310aee51ac207a3152848ebc838df52bd02c3153cb818e1bafdc1000282a374be965375
-  data.tar.gz: 8622e8974f115eee90940a157ea93180f2e4aaa05295f5362ca24f068b359b7d2a1396c42483e4d4fa37b9e8fbee7056460230eb68227033134eda09e5e4d8cc
+  metadata.gz: 21268aaf0ec8b815f8981691ef76fe9a41347eeb184b8bb04b7403d5c1aefda9339acd97bee280e53845f3acf17a17cd68175cb272153acfd176ff16183cb0c6
+  data.tar.gz: 0d30534c168a390f3dec1cf8e35388e0cec48c7285a0c10e1358af71b03032a52043cb0fbad09d9578ccea34c8ee27ac49eb90eefc09d4b5cbe740f530a6b5f2

data/.github/workflows/ci.yml

@@ -69,7 +69,7 @@ jobs:
             lockfile: "unlocked"
 
     steps:
-      - uses: actions/checkout@v7.0.0
+      - uses: actions/checkout@v7.0.1
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         continue-on-error: ${{ matrix.experimental }}

data/.github/workflows/claude-code-review.yml

@@ -48,7 +48,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7.0.0
+        uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 1
 

data/.github/workflows/claude.yml

@@ -26,7 +26,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7.0.0
+        uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 1
 

data/.github/workflows/code-smells.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7.0.0
+        uses: actions/checkout@v7.0.1
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -88,7 +88,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7.0.0
+        uses: actions/checkout@v7.0.1
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.github/workflows/release-gem.yml

@@ -134,7 +134,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 

data/.github/workflows/ruby-lint.yml

@@ -41,7 +41,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7.0.0
+        uses: actions/checkout@v7.0.1
 
       - uses: ruby/setup-ruby@v1
         with:

data/.github/workflows/yardoc.yml

@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7.0.0
+        uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0
 

data/.pre-commit-config.yaml

@@ -95,13 +95,30 @@ repos:
   #         - rubocop-rspec
 
   # Commit message issue tracking integration
-  - repo: https://github.com/avilaton/add-msg-issue-prefix-hook
-    rev: v0.0.13
+  - repo: https://github.com/delano/add-msg-issue-prefix-hook
+    rev: v0.1.1-fork
     hooks:
       - id: add-msg-issue-prefix
         stages: [prepare-commit-msg]
         description: Automatically prefix commits with issue numbers
         args:
-          - "--default="
-          - "--pattern=(i18n(?=/)|([a-zA-Z0-9]{0,10}-?[0-9]{1,5}))"
-          - "--template=[#{}]"
+          - '--default='
+          - '--exclude-pattern=^(dependabot|renovate)/'
+          # Extract the issue ID from the branch name, anchored at the start or a
+          # `/` boundary, so version/encoding tokens like v4, utf8, sha256 and
+          # 0.26.2 never match. Two shapes yield an ID: a bare number
+          # (feature/3840-x) or an explicit word prefix (claude/fix-3499-x,
+          # fix/issue-1234), where `(?P<id>...)` emits the bare number.
+          # `i18n(?=/)` emits the whole match as [#I18N].
+          #
+          # NOT JIRA-compatible: there is deliberately no generic `WORD-NNN` arm,
+          # so `feature/ENG-123` yields no prefix. GitHub issue numbers are the
+          # only ticket scheme here, and a generic arm matched dependency and
+          # date tokens instead (deps/postgres-17, security/audit-2026-07-06).
+          # Re-add that arm if this repo ever adopts JIRA-style keys. (#3891)
+          - '--pattern=(?:^|(?<=/))(?:i18n(?=/)|(?:issue|fix|bug|feat|feature)-(?P<id>[0-9]{1,5})|[0-9]{2,5})(?![0-9])'
+          # Separate pattern for has_tag(): detects an already-present [#TAG] in
+          # the subject on reword so the hook does not double-prefix. Matches the
+          # upcased emitted form, incl. [#I18N] which the branch pattern cannot.
+          - '--tag-pattern=[A-Za-z0-9][A-Za-z0-9._-]*'
+          - '--template=[#{}]'

data/CHANGELOG.rst

@@ -7,6 +7,260 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.8.0:
+
+2.8.0 — 2026-08-07
+==================
+
+Changed
+-------
+
+- ``env['otto.via_trusted_proxy']`` is now tri-state: written only when proxy
+  trust is configured (CIDR matchers or ``trusted_proxy_depth``). A present
+  key is authoritative in both directions; an absent key means
+  "unconfigured". Consumers reading the raw env key should presence-check
+  (``env.key?``) rather than compare ``== true``. (#228)
+
+- Configuring an ip-privacy ``geo_header`` together with
+  ``trusted_proxy_depth`` now raises ``ArgumentError`` at configuration time:
+  geo headers are only honored for CIDR-verified proxies, so under depth mode
+  the header could never be consulted. Database-backed geo (``geo_db_path`` /
+  ``geo_db_reader``) remains fully supported under depth. (#228)
+
+Fixed
+-----
+
+- Depth mode now records a peer-trust verdict in
+  ``env['otto.via_trusted_proxy']`` (previously always ``false``, leaving
+  downstream middleware with no trust signal);
+  ``Otto::Request#forwarded_by_trusted_proxy?`` mirrors the grant on its
+  no-middleware fallback path. (#226)
+
+Documentation
+-------------
+
+- Corrected the v2.3.0 migration guide's depth-porting guidance: map depth
+  values directly, not ``+1`` — otto's chain index already accounts for the
+  appended ``REMOTE_ADDR``. (#227, #228)
+
+.. _changelog-2.7.0:
+
+2.7.0 — 2026-08-03
+==================
+
+Added
+-----
+
+- Configurable geo-country resolution. ``configure_ip_privacy`` now accepts
+  ``geo_header:`` — a trusted, app-configured request header checked *before*
+  the built-in CDN headers (e.g. ``geo_header: 'X-Client-Country'``);
+  ``geo_db_path:`` — a MaxMind-format ``.mmdb`` country database giving an
+  offline IP->country fallback (needs the optional ``maxmind-db`` gem); and
+  ``geo_db_reader:`` — bring your own reader (any object responding to
+  ``#get``). A bad ``geo_db_path`` fails at boot, not per-request. (#206)
+
+- ``X-Vercel-IP-Country`` is now recognized among the built-in CDN/provider
+  geo headers. (#206)
+
+- Named privacy profiles: ``configure_ip_privacy(profile: :anonymous | :masked
+  | :audit)`` (also accepted by ``Otto::Privacy::Config.new``) — a validated
+  preset over the existing knobs. ``:masked`` is the default posture (public
+  IPs masked, private exempt), ``:anonymous`` masks every IP including
+  private/localhost, and ``:audit`` disables IP privacy for
+  private/compliance environments (retention responsibility transfers to the
+  operator). ``Config#profile`` derives the label from live knob state, so it
+  cannot go stale. Unknown names raise ``ArgumentError``. (#218)
+
+- ``env['otto.ip_match']``: a verdict-only CIDR membership check over the
+  resolved, UNMASKED client IP, installed by ``IPPrivacyMiddleware`` under
+  every profile. Call it with an array of CIDR strings (or ``IPAddr``
+  objects) and get ``true``/``false`` back, so downstream access control
+  (e.g. a per-tenant allowlist) can match at full /32–/128 precision while
+  ``otto.client_ip``, ``REMOTE_ADDR``, logs, and fingerprints stay masked —
+  only the closure lands in env, never the address. Returns ``false`` when no
+  client IP resolves (fail-closed); invalid CIDR entries raise
+  ``IPAddr::InvalidAddressError``. (#218)
+
+- ``Otto::Utils.ip_in_cidrs?(ip, cidrs)``: the general-purpose CIDR-set
+  matcher behind ``otto.ip_match``, sharing the trusted-proxy matcher's
+  semantics (port stripping, ``IPAddr#native`` folding, family-aware
+  skipping). Runtime ``ip`` fails closed; invalid ``cidrs`` entries raise.
+  Accepts pre-parsed ``IPAddr`` entries for hot paths. (#218)
+
+- ``MiddlewareStack#execution_order`` returns middleware classes in the order
+  they actually run (outermost first), resolving pin tiers — unlike
+  ``#middleware_list``, which reports registration order. (#219)
+
+- ``add_with_position`` accepts ``position: :innermost`` as a clearer synonym
+  for ``:first``, and a new ``position: :entrypoint`` tier that pins middleware
+  outside even ``:outermost`` entries. (#219)
+
+- ``AuthFailure`` now carries a ``terminal`` flag (``terminal?`` predicate),
+  and ``AuthStrategy#failure`` accepts ``terminal: true`` — meaning "credentials
+  were presented, examined, and rejected; do not consult further strategies."
+  ``RouteAuthWrapper`` halts the chain and renders that failure's 401
+  regardless of strategy order, so mixed chains (``auth=basicauth,noauth``)
+  fail closed on invalid credentials instead of proceeding as anonymous. Plain
+  failures keep the existing OR fallthrough. (#220)
+
+Changed
+-------
+
+- Geo resolution now runs against a privacy-masked view — the masked IP and an
+  env with the IP-bearing headers masked — so the unmasked address never
+  reaches a custom resolver or the database. Country networks are >= /24, so
+  /24-masked results are identical at the default masking level. A custom
+  resolver invoked through the middleware now receives the masked IP and env;
+  direct ``GeoResolver.resolve`` callers are unchanged. (#206)
+
+- Middleware pins are now recorded per *entry* rather than per class. An
+  ``:outermost`` pin previously reordered every registration of that class,
+  including ones registered separately with different arguments. (#219)
+
+- ``Otto::LoggingHelpers.request_context`` masks its ``:ip`` field when the
+  request never passed through ``IPPrivacyMiddleware`` (previously it fell back
+  to the raw ``REMOTE_ADDR``). New ``LoggingHelpers.privacy_safe_ip`` exposes
+  that behavior for callers outside Otto's stack. (#219)
+
+- ``Otto::CaddyTLS::LocalhostGuard`` reads the new leak-free boolean
+  ``env['otto.peer_loopback']`` — the loopback verdict ``IPPrivacyMiddleware``
+  records on the untouched socket peer before masking — falling back to
+  ``REMOTE_ADDR`` when absent. The guard still authenticates the raw peer,
+  which it can no longer read directly now that IP masking runs first. (#219)
+
+- ``RouteAuthWrapper`` multi-strategy chains now treat an anonymous success
+  (a ``StrategyResult`` with no user, e.g. from ``noauth``) as a held fallback
+  rather than an immediate win: the rest of the chain still runs so a later
+  credentialed strategy can reject presented credentials terminally. The
+  fallback wins once the chain completes without an authenticated success or
+  terminal failure, preserving OR semantics for credential-less requests.
+  Consequently, in ``auth=noauth,apikey`` a later authenticated success now
+  wins over an earlier anonymous one. (#220)
+
+Removed
+-------
+
+- The built-in ``KNOWN_RANGES`` IP-range guess table (and ``detect_by_range``).
+  When no header, custom resolver, or database resolves a country, the result
+  is now ``'**'`` (unknown) rather than a guess from a hardcoded ~14-entry
+  table that mislabeled whole cloud regions. Callers that relied on the table
+  (e.g. ``8.8.8.8`` -> ``US``) now get ``'**'``; configure a database or an
+  edge header for real geo-location. (#206)
+
+Fixed
+-----
+
+- IP privacy now redacts the RFC 7239 ``Forwarded`` header
+  (``HTTP_FORWARDED``), which Otto reads as an authoritative client-IP source
+  in count-based depth mode. Previously it was left intact while
+  ``X-Forwarded-For`` and friends were masked, so downstream code could read
+  the real client IP from its ``for=`` token. Only the ``for=`` value is
+  replaced; ``proto=``/``host=``/``by=`` and the header structure are
+  preserved. When no client IP resolves, the forwarded headers are dropped
+  rather than left to leak a raw address. (#206)
+
+- IPv4-mapped IPv6 CIDR *ranges* are now folded through ``IPAddr#native``, so
+  the fold is symmetric with the client address. Previously only the client
+  was folded, so a mapped range (``::ffff:10.0.0.0/104``) failed the
+  address-family check and was silently skipped — a wrong verdict rather than
+  an error. Affects ``Otto::Utils.ip_in_cidrs?`` / ``otto.ip_match`` and
+  trusted-proxy entries, where an unmatched proxy silently withheld
+  ``otto.via_trusted_proxy`` and with it ``Request#secure?`` and geo-header
+  trust. **Behavior change** for anyone who configured a mapped-IPv6 range: it
+  now matches the IPv4 clients it names — including ``::ffff:0:0/96``, the
+  whole mapped space, which matches every IPv4 address. The prefix must cover
+  the mapped marker (``/96`` or longer); ``::ffff:10.0.0.0/64`` masks the
+  marker away and still matches neither form. Plain IPv4/IPv6 ranges are
+  unaffected, and pre-parsed ``IPAddr`` entries are not mutated. (#218)
+
+- ``IPPrivacyMiddleware`` reads the privacy setting per request instead of
+  caching it at construction. Otto builds its middleware stack at the end of
+  ``Otto.new`` while ``configure_ip_privacy`` stays legal until the first
+  request, so a post-construction ``configure_ip_privacy(profile: :audit)``
+  was silently ignored and the middleware kept masking. (#218)
+
+- ``IPPrivacyMiddleware`` no longer interpolates the unmasked client IP into
+  its debug log. Under ``Otto.debug``, the pre-mask resolution line
+  (``:masked``, ``:anonymous``) and the private/localhost exemption line
+  (``:masked``) logged the raw address — handing back through the log exactly
+  what the profile withholds from env. The resolution line is gone; the
+  masking path logs the masked IP, and the exemption line now records only
+  that the exemption fired. ``:audit`` is unaffected. (#218)
+
+- ``configure_ip_privacy`` is now all-or-nothing: assignments are dry-run
+  against a copy and validated there before the live config is touched, so a
+  rejected value (e.g. ``octet_precision: 7`` alongside a ``profile:`` preset)
+  can no longer leave the preset half-applied. (#218)
+
+- ``configure_ip_privacy`` fails loudly on falsy knobs. ``octet_precision``,
+  ``hash_rotation`` and ``redis`` were truthiness-guarded, so an explicit
+  ``false`` was silently dropped instead of assigned or rejected; every kwarg
+  now follows the same nil guard — ``nil`` means "leave unchanged", anything
+  else must take effect or raise. A non-Numeric ``hash_rotation`` raises
+  ``ArgumentError`` naming the value rather than ``NoMethodError``. (#218)
+
+- ``Otto::Privacy::Config#profile=`` raises ``ArgumentError`` for a value that
+  cannot name a profile; ``config.profile = 123`` and ``config.profile = nil``
+  previously raised ``NoMethodError`` on ``#to_sym``. The ``profile:`` option
+  form still treats ``nil`` as "leave unchanged", but a non-nameable value now
+  raises before any other option in the same call is applied. (#218)
+
+- ``IPPrivacyMiddleware``'s idempotency guard installs a fail-closed
+  ``otto.ip_match`` when ``otto.client_ip`` was set outside the middleware
+  (out of contract, but previously left the advertised capability ``nil`` and
+  raised ``NoMethodError`` downstream). It deliberately does not rebuild the
+  check from ``otto.client_ip``, which may be masked — matching a masked
+  address against a narrow CIDR yields false allows. The deny is logged.
+  (#218)
+
+- ``Otto::Request#secure?`` now honors ``env['rack.url_scheme']`` — the
+  canonical Rack scheme key that ``Rack::Request#scheme``/``#ssl?`` (and
+  therefore the session Secure-cookie gate, ``Rack::Protection``, and Otto's
+  own CSRF middleware) read. An upstream middleware that normalizes the scheme
+  the idiomatic Rack way is now visible to ``secure?`` instead of producing a
+  second, divergent scheme-truth. The trusted-proxy gate on the raw
+  ``X-Forwarded-Proto`` / ``X-Scheme`` headers is unchanged. (#214)
+
+Security
+--------
+
+- Geo headers (``CF-IPCountry`` and friends, plus any configured
+  ``geo_header``) are now trusted ONLY for a request that demonstrably arrived
+  via a configured CIDR trusted proxy. Previously any client could pick its own
+  country by sending ``CF-IPCountry``/``X-Client-Country``. An unverifiable
+  origin is no longer trusted: count-based depth mode, and — a behavior change
+  — deployments with **no** trusted-proxy configuration. **Migration:** to keep
+  header-based geo, configure ``trusted_proxies`` (CIDR matchers) so Otto can
+  verify the proxy origin. Count-based ``trusted_proxy_depth`` does NOT enable
+  header trust, so depth-mode and header-only setups should set ``geo_db_path``
+  for a local database instead. Otherwise resolution returns ``'**'``. (#206)
+
+- IP masking now applies to the whole middleware stack, not just the
+  application. ``IPPrivacyMiddleware`` was registered ``position: :first``,
+  which is first-in-*array* and therefore **innermost**, so every other
+  middleware Otto mounts — plus anything added via ``Otto#use`` — received the
+  raw ``REMOTE_ADDR``, an un-anonymized User-Agent, and a nil
+  ``env['otto.client_ip']``. It is now pinned outermost. (#219)
+
+- Rate-limit logging no longer writes raw client IPs. The ``rack.attack``
+  subscribers in ``Otto::Security::RateLimiting`` and ``Otto::MCP::RateLimiter``
+  interpolated ``req.ip`` into a ``warn``-level line on every blocked request,
+  so deployments on the default masked profile leaked public IPs to their logs.
+  Both now log a masked address. (#219)
+
+AI Assistance
+-------------
+
+- Geo-header source and local IP->country database fallback designed and
+  implemented with AI assistance, including adversarial review and coverage
+  for header precedence, spoofing, depth-mode trust, IPv6, custom-resolver
+  sealing, boot-time validation, and the real ``maxmind-db`` reader against a
+  generated fixture. (#206)
+
+- IP precision capability, privacy profiles, middleware ordering audit, and
+  terminal auth failures: design, implementation, adversarial review, and
+  regression coverage developed with AI assistance. (#214, #218, #219, #220)
+
 .. _changelog-2.6.0:
 
 2.6.0 — 2026-07-10

data/Gemfile

@@ -19,6 +19,7 @@ end
 group :development, :test, optional: true do
   # Keep gems that need to be in both environments
   gem 'json_schemer'
+  gem 'maxmind-db', '~> 1.2' # Optional geo DB reader; exercised by geo specs
   gem 'rack-attack'
   gem 'reek', '~> 6.5'
 end
@@ -28,7 +29,7 @@ group :development do
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
   gem 'rake', '~> 13.4', require: false # Provides `rake release` for release-gem.yml
-  gem 'rubocop', '~> 1.88.1', require: false
+  gem 'rubocop', '~> 1.88.2', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.6.0)
+    otto (2.8.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -15,8 +15,8 @@ GEM
     ast (2.4.3)
     benchmark (0.5.0)
     bigdecimal (4.1.1)
-    concurrent-ruby (1.3.7)
-    crass (1.0.6)
+    concurrent-ruby (1.3.8)
+    crass (1.0.7)
     date (3.5.1)
     debug (1.11.1)
       irb (~> 1.10)
@@ -59,7 +59,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.20.0)
+    json (2.21.2)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
@@ -70,9 +70,10 @@ GEM
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    loofah (2.25.1)
+    loofah (2.25.2)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
+    maxmind-db (1.4.0)
     minitest (5.26.0)
     nokogiri (1.19.4-aarch64-linux-gnu)
       racc (~> 1.4)
@@ -116,7 +117,7 @@ GEM
       rack (>= 3)
     rainbow (3.1.1)
     rake (13.4.2)
-    rbs (4.0.2)
+    rbs (4.0.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -147,7 +148,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.88.1)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -158,7 +159,7 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-performance (1.26.1)
@@ -173,7 +174,7 @@ GEM
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.9)
+    ruby-lsp (0.26.10)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -200,7 +201,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     user_agent_parser (2.21.0)
-    yard (0.9.44)
+    yard (0.9.45)
     zeitwerk (2.7.3)
 
 PLATFORMS
@@ -218,6 +219,7 @@ DEPENDENCIES
   debug
   json_schemer
   kramdown
+  maxmind-db (~> 1.2)
   otto!
   rack-attack
   rack-test
@@ -225,7 +227,7 @@ DEPENDENCIES
   rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.88.1)
+  rubocop (~> 1.88.2)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/README.md

@@ -165,7 +165,8 @@ end
 2. Registers your callback, invoked once per violation with an
    `Otto::Security::CSP::Report`.
 3. Injects `Otto::Security::CSP::ReportMiddleware`, pinned **outermost** in the
-   stack, which intercepts `POST`s to the report path, parses both the legacy
+   stack (only IP masking runs ahead of it), which intercepts `POST`s to the
+   report path, parses both the legacy
    `application/csp-report` and the Reporting API `application/reports+json`
    formats, enforces a 64 KiB body cap, and always answers `204 No Content` —
    without touching your routes.
@@ -231,7 +232,16 @@ app = Otto.new("./routes")
 # IP hashing: daily-rotating hashes enable analytics without tracking
 ```
 
-Private and localhost IPs are exempted by default for development convenience, but this behavior can be customized via `configure_ip_privacy()` method. Geolocation uses CDN headers (Cloudflare, AWS, etc.) with fallback to IP ranges—no external services required. See [CLAUDE.md](CLAUDE.md) for detailed configuration options.
+Private and localhost IPs are exempted by default for development convenience, but this behavior can be customized via `configure_ip_privacy()` method. Geolocation checks CDN headers (Cloudflare, AWS, Vercel, etc.) first, then an optional local country database—no external services required. You can name a trusted header to check first, plug in a MaxMind-format `.mmdb` file for an offline fallback, or bring your own reader:
+
+```ruby
+otto.configure_ip_privacy(
+  geo_header: 'X-Client-Country',        # trusted app header, checked first
+  geo_db_path: 'data/country.mmdb'       # offline fallback (needs the maxmind-db gem)
+)
+```
+
+Geo headers are only trusted for requests that arrive via a configured trusted proxy (they are client-spoofable otherwise), the database is looked up on the already-masked IP, and `configure_ip_privacy(geo: false)` disables geo entirely. See [AGENTS.md](AGENTS.md) for detailed configuration options.
 
 ## Internationalization Support
 
@@ -357,7 +367,7 @@ gem install otto
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)** - Comprehensive developer guidance covering authentication architecture, configuration freezing, IP privacy, structured logging, and multi-app patterns
+- **[AGENTS.md](AGENTS.md)** - Comprehensive developer guidance covering authentication architecture, configuration freezing, IP privacy, structured logging, and multi-app patterns
 - **[docs/](docs/)** - Technical guides and migration guides
 - **[CHANGELOG.rst](CHANGELOG.rst)** - Version history, breaking changes, and upgrade notes
 

data/docs/.gitignore

@@ -3,6 +3,7 @@
 !migrating/
 !migrating/*.md
 !ipaddr-encoding-quirk.md
+!geo-country.md
 !modern-authentication-authorization-landscape.md
 !multi-strategy-authentication-design.md
 !reverse-proxy-network-services.md