otto 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8303453d265fcf2d5b0fa0754aafdbdb3e24eb89be9dc5a7b5611b4f2bcc699
-  data.tar.gz: 2081706f65a3475f95555d96547841691f906b015f8b012739abc7804923fc76
+  metadata.gz: d60f9cd87b0c935f8c79ecc1aae11f4b9880794d57b0ee5309c53baafcb84dcf
+  data.tar.gz: d92225f2ab02c1fbbd9c6ab745c27373aa6f11608f27067ec4485ca4f81878b2
 SHA512:
-  metadata.gz: 75c496ee29c9c4ec0b05a8effda77e4e1dafc02080fb341a2320313011437f2b0bc0511ad6ca7d1b53928d6f75130693c974c72ed053aa35e5c6d16f60af0a5e
-  data.tar.gz: 9d9615efa73c7ebafafe7f7e1eb3e098f8c07f3200ac62882c52c39954087c73053fc9574beda1b1e11ecc836e0b9bacb70fe267c90fa92600531ef14fca1b63
+  metadata.gz: cf10b7fdf1245e1dd64140ef3a57fc69f2a42197ede66812f02a89f80f291ff3759a7b5245487fd0e7948e4da6534534dbe9d753e0d15cf0ea57366da2c928da
+  data.tar.gz: cba8ac893ef636d0e978061304704018907bba315160405561f41592613a250a762ac1a0ebad7de675984101f711f44aabec8693ac3445e4e1e6d9b8f7ffd788

data/.github/workflows/ci.yml

@@ -74,7 +74,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         continue-on-error: ${{ matrix.experimental }}
         with:
           ruby-version: ${{ matrix.ruby }}

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

@@ -61,7 +61,7 @@ jobs:
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@19dda84776b3518d98b8798e591daee763049ed3 # v1.0.220
+        uses: anthropics/claude-code-action@7b0b255830a1fab6e602658672acad11c12d841d # v1.0.226
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

data/.github/workflows/claude.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@19dda84776b3518d98b8798e591daee763049ed3 # v1.0.220
+        uses: anthropics/claude-code-action@7b0b255830a1fab6e602658672acad11c12d841d # v1.0.226
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

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

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: 3.4
 
@@ -91,7 +91,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: 3.4
           bundler-cache: true

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

@@ -139,7 +139,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           bundler-cache: true
           # Pinned to 3.3 (oldest non-experimental Ruby in the CI matrix).

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

@@ -46,7 +46,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+      - uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true

data/.github/workflows/yardoc.yml

@@ -47,7 +47,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Ruby environment
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: '3.4'
           bundler-cache: true

data/.rubocop_todo.yml

@@ -412,10 +412,10 @@ Metrics/ModuleLength:
   Exclude:
     - 'lib/otto/design_system.rb'
 
-# Offense count: 4
+# Offense count: 6
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 11
+  Max: 7
 
 # Offense count: 46
 # Configuration parameters: AllowedMethods, AllowedPatterns.

data/CHANGELOG.rst

@@ -7,6 +7,106 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.12.0:
+
+2.12.0 — 2026-09-26
+===================
+
+Added
+-----
+
+- ``referrer_policy`` sets the Referrer-Policy header on routed responses,
+  static files, built-in 404 and 500 responses, and authentication failures.
+  Pass one W3C policy token to ``Otto.new`` or assign it before the first
+  request. A value a route handler sets on its own response is kept. See
+  ``docs/guides/testing-guide.md``. (#281)
+
+- Logic classes can declare a ``route_params:`` keyword on ``initialize`` to
+  receive the router's path captures separately from caller-supplied
+  parameters. (#285)
+
+- ``Otto::Utils.routing_path(env)`` returns the normalized path the router
+  matches, so middleware can judge a request by the same path the router
+  dispatches. ``include_mount: true`` includes ``SCRIPT_NAME``. See
+  ``docs/guides/routing.md``. (#288)
+
+- ``require 'otto/testing'`` adds test support for any test framework.
+  ``Otto::Testing.reset!`` clears Otto's process-global forwarding state
+  between tests. ``Otto::Testing.env_for`` and ``resolve_client_ip!`` build a
+  Rack env whose ``otto.client_ip`` and ``otto.ip_match`` are resolved by
+  ``IPPrivacyMiddleware``. See ``docs/guides/testing-guide.md``. (#287)
+
+- ``Otto::Security::Config#trusted_proxy_mode`` returns ``:filter``,
+  ``:depth``, ``:none``, or nil. (#148)
+
+Changed
+-------
+
+- A ``referrer-policy`` value set through ``security_headers`` is now
+  validated like ``referrer_policy``. An unknown token or a comma-separated
+  fallback list raises ``ArgumentError`` at configuration time, and the header
+  can no longer be removed from ``security_headers``. (#281)
+
+- Trusted-proxy state moved into a private
+  ``Otto::Security::TrustedProxyConfig``, and
+  ``Security::Configurator#configure`` now takes ``**options``. Public
+  methods, accepted keys, and behavior are unchanged. (#148)
+
+- The forwarding-family conflict error and the warning for a hand-set
+  ``otto.client_ip`` now name the ``Otto::Testing`` helper that addresses
+  each. ``Otto::Security::Config.reset_rack_forwarding_family_for_testing!``
+  remains for existing RSpec callers. (#287)
+
+Fixed
+-----
+
+- Requests whose ``PATH_INFO`` contains a malformed percent-escape (``%zz``)
+  or a raw invalid byte are now routed instead of answering 500. (#288)
+
+- The general rate-limit throttle now skips internal paths by the path the
+  router dispatches, so ``/%5Fmcp`` is skipped like ``/_mcp``. (#288)
+
+- ``Otto::Privacy::Config#profile=`` now sets both ``disabled`` and
+  ``mask_private_ips`` for every profile. Switching to ``:audit`` previously
+  left ``mask_private_ips`` unchanged, so a later ``enable!`` could restore
+  ``:anonymous`` instead of ``:masked``. (#286)
+
+- CSP violation reports now reach the receiver when Otto is mounted under a
+  sub-path. The receiver matches ``csp_report_uri`` against ``SCRIPT_NAME`` +
+  ``PATH_INFO``, so configure the site-absolute path including the mount
+  prefix, such as ``/api/csp-report`` under ``map '/api'``. A mount-relative
+  value no longer matches. Trailing-slash and percent-encoded spellings of
+  the report path are also matched. (#289)
+
+Security
+--------
+
+- JSON request bodies can no longer override path captures, query
+  parameters, or form fields in Logic class parameters; JSON keys now merge
+  below them. JSON bodies are no longer parsed for ``GET`` or ``HEAD``
+  requests. Before upgrading, check Logic classes that read a JSON body on
+  ``GET`` or expect a JSON key to replace a query or path value. (#285)
+
+Documentation
+-------------
+
+- ``docs/guides/routing.md`` covers matching request paths in middleware,
+  including apps mounted under a sub-path. ``docs/guides/testing-guide.md``
+  covers ``Otto::Testing`` and Referrer-Policy configuration. (#281, #287,
+  #288)
+
+AI Assistance
+-------------
+
+- The ``TrustedProxyConfig`` refactor was implemented with AI assistance and
+  checked against the previous release by a differential run of 1,620
+  trusted-proxy operation sequences and 29 ``configure`` calls, with no
+  difference in outcome. (#148)
+
+- ``Otto::Testing`` helpers, specs, and guide updates were written with AI
+  assistance. The reset was also exercised without RSpec, under Tryouts and
+  Minitest. (#287)
+
 .. _changelog-2.11.0:
 
 2.11.0 — 2026-09-12

data/Gemfile

@@ -19,7 +19,7 @@ end
 group :development, :test, optional: true do
   # Keep gems that need to be in both environments
   gem 'json_schemer', '~> 2.0'
-  gem 'maxmind-db', '~> 1.2' # Optional geo DB reader; exercised by geo specs
+  gem 'maxmind-db', '~> 1.5' # Optional geo DB reader; exercised by geo specs
   gem 'rack-attack', '~> 6.7'
   gem 'reek', '~> 6.5'
 end
@@ -29,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.90.0', require: false
+  gem 'rubocop', '~> 1.91.0', 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.11.0)
+    otto (2.12.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -57,7 +57,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.21.2)
+    json (3.0.2)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
@@ -71,7 +71,7 @@ GEM
     loofah (2.25.2)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    maxmind-db (1.4.0)
+    maxmind-db (1.5.0)
     minitest (5.26.0)
     nokogiri (1.19.4-aarch64-linux-gnu)
       racc (~> 1.4)
@@ -144,7 +144,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.90.0)
+    rubocop (1.91.0)
       json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -166,9 +166,9 @@ GEM
       lint_roller (~> 1.1)
       regexp_parser (>= 2.0)
       rubocop (~> 1.86, >= 1.86.2)
-    rubocop-thread_safety (0.7.3)
+    rubocop-thread_safety (0.8.0)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      rubocop (~> 1.89)
       rubocop-ast (>= 1.44.0, < 2.0)
     ruby-lsp (0.26.11)
       language_server-protocol (~> 3.17.0)
@@ -215,7 +215,7 @@ DEPENDENCIES
   debug
   json_schemer (~> 2.0)
   kramdown
-  maxmind-db (~> 1.2)
+  maxmind-db (~> 1.5)
   otto!
   rack-attack (~> 6.7)
   rack-test
@@ -223,7 +223,7 @@ DEPENDENCIES
   rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.90.0)
+  rubocop (~> 1.91.0)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/README.md

@@ -278,6 +278,12 @@ middleware, so browsers can POST reports without a CSRF token — regardless of
 order you enable security features in. A throwing callback can never break the
 receiver; it still answers `204`.
 
+The report path is the site-absolute path the browser POSTs to. When Otto is
+mounted under a sub-path (`map '/api' { run otto }`), include the prefix:
+`enable_csp_reporting!("/api/_/csp-report")`. The receiver matches it against
+`SCRIPT_NAME` + `PATH_INFO`, so the same value works in the header and in the
+receiver.
+
 Modern browsers (Chrome) have deprecated `report-uri` in favour of the Reporting
 API. Pass `endpoint_url:` — an **absolute** URL whose path is the report path —
 to also emit a `report-to` directive and a `Reporting-Endpoints` response header,

data/docs/guides/forwarded-authority.md

@@ -190,10 +190,14 @@ process that both resolve proxied requests must agree. The later one raises:
 Cannot use forwarding family %s (trusted_proxy_header) because another Otto
 application in this process already uses %s. Rack's forwarded host, port,
 scheme, and IP policy is process-global, so every Otto application in one
-process that resolves proxied requests must use the same forwarding family.
+process that resolves proxied requests must use the same forwarding family. A
+test suite that builds applications with different families must clear this
+between tests: require 'otto/testing' and call Otto::Testing.reset!.
 ```
 
 The two placeholders are the requested family and the already committed one.
+See [Testing Otto applications](testing-guide.md#reset-ottos-process-global-state-between-tests)
+for the reset.
 
 An application that configures no proxy trust, and one that asserts
 `trusted_proxies: :none`, read no forwarded chain and therefore stake no claim

data/docs/guides/privacy.md

@@ -154,6 +154,11 @@ the closure.
 allowed = req.env.fetch('otto.ip_match').call(['192.0.2.0/24', '2001:db8::/32'])
 ```
 
+In tests, build the env with `Otto::Testing.env_for` rather than writing
+`otto.client_ip` by hand; a hand-written value leaves `otto.ip_match` denying
+every range. See
+[Testing Otto applications](testing-guide.md#hand-a-harness-a-resolved-client-ip).
+
 ## Middleware placement
 
 When building a larger Rack stack, put privacy before components that log or

data/docs/guides/routing.md

@@ -142,11 +142,31 @@ GET /products/:id  Products::Show
 
 A handler can read `req.params[:id]` or a Logic class can read `params[:id]`.
 Request query and body parameters are merged according to the handler's request
-contract. JSON bodies are parsed for Logic-class parameters when the content
-type is JSON and the body is a JSON object. A valid non-object JSON body is
-ignored. Malformed JSON is logged and the Logic class still runs with its other
-parameters; perform application validation when malformed JSON must return a
-client error.
+contract. Path captures are merged on top, so a caller cannot replace the value
+the router matched by repeating the key in the query string or body. Between
+the query string and a form body, Rack's own order applies (the form body
+wins). For Logic classes a JSON body sits below all of those.
+
+A Logic class that must not confuse a path value with a caller-supplied one
+can take the captures separately by declaring a `route_params:` keyword:
+
+```ruby
+class Receipts::Show
+  def initialize(strategy_result, params, locale, route_params: {})
+    @identifier = route_params[:identifier] # only ever the path value
+    @params = params
+  end
+end
+```
+
+The keyword is optional; the three-argument constructor keeps working. The same
+values remain in `params` for classes that do not declare it.
+
+JSON bodies are parsed for Logic-class parameters when the request method
+carries a body (never `GET` or `HEAD`), the content type is JSON, and the body
+is a JSON object. A valid non-object JSON body is ignored. Malformed JSON is
+logged and the Logic class still runs with its other parameters; perform
+application validation when malformed JSON must return a client error.
 
 ## Security options in routes
 
@@ -245,6 +265,49 @@ files outside the public directory should replace it with `mount_static` and
 an explicit root. There is no compatibility shim: calling the removed method
 raises `NoMethodError` at boot.
 
+## Matching request paths before the router
+
+The router does not match raw `PATH_INFO`. It percent-decodes it, scrubs
+invalid UTF-8, and strips one trailing slash, so `GET /%63olonel/` reaches the
+`/colonel` route. Middleware that decides on a request by its path (an access
+guard, a throttle, a session skip) must compare the same value. Otherwise a
+request can match a route without matching the guard in front of it, which
+on an access guard is a bypass.
+
+`Otto::Utils.routing_path(env)` returns that value. The router gets its path
+from the same method, so the two cannot drift:
+
+```ruby
+class AdminGuard
+  ADMIN = Otto::Utils.normalize_path('/colonel')
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    path = Otto::Utils.routing_path(env)
+    admin_path = path == ADMIN || path.start_with?("#{ADMIN}/")
+    return [404, {}, []] if admin_path && !allowed?(env) # allowed? is yours
+
+    @app.call(env)
+  end
+end
+```
+
+The result is mount-relative. When the app is mounted under a sub-path
+(`map '/api' { run otto }`), Rack moves the prefix into `SCRIPT_NAME` and the
+router sees only the rest. Compare that form against paths as written in the
+routes file. For middleware shared by several mounted apps and configured
+with external URLs, pass `include_mount: true` to get `SCRIPT_NAME` and
+`PATH_INFO` joined and normalized as one path: inside an app mounted at
+`/api/v2`, the router's `/status` is `/api/v2/status`, and matching the
+mount-relative form would also match every other app's `/status`.
+
+The value uses `normalize_path` conventions: root is `''`, and a configured
+path must go through `Otto::Utils.normalize_path` before an exact comparison.
+A malformed escape such as `%zz` is kept as written; the method never raises.
+
 ## Fallback 404 and 500 responses
 
 A `GET /404` or `GET /500` route in the routes file handles misses and

data/docs/guides/testing-guide.md

@@ -41,6 +41,7 @@ require 'rack/mock'
 require 'rspec'
 require 'tempfile'
 require 'otto'
+require 'otto/testing'
 
 module OttoAppSpecHelpers
   def rack_env(path = '/', method: 'GET', headers: {}, params: {})
@@ -69,6 +70,10 @@ end
 RSpec.configure do |config|
   config.include OttoAppSpecHelpers
 
+  config.before do
+    Otto::Testing.reset!
+  end
+
   config.after do
     Array(@route_files).each(&:unlink)
   end
@@ -79,6 +84,46 @@ Within Otto itself, use the existing helpers in
 [`spec/support/test_helpers.rb`](../../spec/support/test_helpers.rb) instead of
 copying this application-level helper.
 
+## Reset Otto's process-global state between tests
+
+`require 'otto'` does not load `otto/testing`. Require it from the test helper;
+it does not depend on RSpec.
+
+`Otto.new` pins `Rack::Request.forwarded_priority` from `trusted_proxy_header`
+whenever an application configures proxy trust or names a header. Rack keeps one
+priority per process, so Otto records the family and raises `ArgumentError`
+when a later application in the same process chooses a different one. A suite
+that builds one application with `trusted_proxy_header: 'Forwarded'` and
+another with `trusted_proxies:` fails or passes depending on test order unless
+the record is cleared between tests. `Otto::Testing.reset!` clears it and
+restores Rack's priority to the value Otto saw at load time.
+
+Call it before every test:
+
+```ruby
+# RSpec
+RSpec.configure { |config| config.before { Otto::Testing.reset! } }
+
+# Minitest
+class Minitest::Test
+  def before_setup
+    super
+    Otto::Testing.reset!
+  end
+end
+
+# Tryouts: at the start of each test case that builds an Otto app
+## a depth-mode app reading Forwarded
+Otto::Testing.reset!
+Otto.new(nil, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
+```
+
+Tryouts runs a file's setup section once, before all of its test cases, so a
+reset placed there does not separate the cases from each other.
+
+`Otto::Security::Config.reset_rack_forwarding_family_for_testing!` does the
+same but raises unless RSpec is loaded. It remains for existing callers.
+
 ## Test Logic classes as plain Ruby objects
 
 Logic classes receive an authentication result, merged parameters, and a locale.
@@ -260,7 +305,9 @@ Otto's parser. Send an `application/json` body through a real Otto instance or
 
 Current behavior to cover explicitly:
 
-- a JSON object is merged into the Logic parameters;
+- a JSON object is merged into the Logic parameters below path captures, the
+  query string and any form body, which all win over it;
+- a JSON body on `GET` or `HEAD` is ignored;
 - a valid non-object JSON value is ignored;
 - malformed JSON is logged and the Logic class continues with other parameters;
 - non-JSON bodies are not parsed by the Logic handler.
@@ -343,6 +390,52 @@ octets, or set `mask_private_ips = true` to include private and localhost
 addresses. For application-facing tests, prefer a real Otto instance configured
 through `configure_ip_privacy`.
 
+### Hand a harness a resolved client IP
+
+Code that runs behind `IPPrivacyMiddleware` reads `env['otto.client_ip']` and,
+for access decisions, `env['otto.ip_match']`. Do not write `otto.client_ip` by
+hand. The middleware treats its presence as a sign that it already ran, so it
+never builds `otto.ip_match` from the full address. Instead it installs a check
+that returns `false` for every range and logs a warning. Allowlist tests then
+deny, and when the application uses CIDR proxy trust it also treats the peer as
+untrusted.
+
+`Otto::Testing.env_for` runs the middleware over a Rack env for a request
+arriving directly from `client_ip`, so both keys come from one resolution:
+
+```ruby
+env = Otto::Testing.env_for('/admin', client_ip: '203.0.113.9',
+                                      security_config: otto.security_config)
+
+env['otto.client_ip']                          # => "203.0.113.0" (masked)
+env['otto.ip_match'].call(['203.0.113.9/32'])  # => true
+```
+
+`security_config:` is required. The application's own middleware keeps what
+this resolution produced, so pass `otto.security_config` to get the masking and
+proxy trust of the application under test; `nil` means an unconfigured
+middleware (public addresses masked, no proxy trust). `client_ip: nil` builds a
+request with no resolvable client IP: `env['otto.client_ip']` is `nil` and
+`otto.ip_match` denies every range. Other keywords and String env keys go to
+`Rack::MockRequest.env_for`.
+
+`env_for` models a direct request, so it raises `ArgumentError` when given
+`X-Forwarded-For`, `X-Real-IP`, `X-Client-IP` or `Forwarded`: under a
+configuration that trusts the peer, those would resolve an address other than
+`client_ip`. For a request relayed by a proxy, build the env with `REMOTE_ADDR`
+and the forwarded headers, then resolve it under the application's
+configuration:
+
+```ruby
+env = Rack::MockRequest.env_for('/admin', 'REMOTE_ADDR' => '10.0.0.5',
+                                          'HTTP_X_FORWARDED_FOR' => '203.0.113.9')
+Otto::Testing.resolve_client_ip!(env, otto.security_config)
+```
+
+Resolved under a different configuration, the proxy can become the client and
+the application keeps that answer. `resolve_client_ip!` raises on an env that
+already carries `otto.client_ip` or `otto.ip_match` for the same reason.
+
 See the [privacy guide](privacy.md) and the maintained privacy specs:
 
 - [`spec/otto/ip_privacy_spec.rb`](../../spec/otto/ip_privacy_spec.rb)
@@ -369,13 +462,33 @@ Otto's default route responses include:
 - `x-xss-protection: 1; mode=block`
 - `referrer-policy: strict-origin-when-cross-origin`
 
+Configure exactly one W3C policy token when constructing the application; Otto
+applies it to routed responses, static files, and authentication failures:
+
+```ruby
+otto = Otto.new('routes.txt', referrer_policy: 'no-referrer')
+```
+
+The same setting is available as
+`otto.security_config.referrer_policy = 'no-referrer'` and
+`otto.security.referrer_policy = 'no-referrer'` during boot, before the first
+request freezes configuration. An unknown policy token raises `ArgumentError`
+at configuration time. Comma-separated policy fallback lists are not accepted.
+Existing applications that pass `referrer-policy`
+through `security_headers` remain supported and receive the same validation.
+A route handler that explicitly sets `res['referrer-policy']` keeps its
+response-specific value.
+
 `x-frame-options` is not a default header. Call
 `otto.enable_frame_protection!` before the first request if a test should expect
 `x-frame-options: SAMEORIGIN`.
 
 Test security behavior at the narrowest useful level, but do not require every
 unrelated unit test to repeat header and privacy assertions. Keep those checks in
-focused middleware or request specs.
+focused middleware or request specs. When testing a custom referrer policy,
+exercise a complete response from each response family the application uses
+(for example, routed HTML, `Rack::Files`, and an authentication failure), rather
+than asserting only against `security_config.security_headers`.
 
 ## Maintained examples by task
 

data/lib/otto/caddy_tls/localhost_guard.rb

@@ -120,16 +120,16 @@ class Otto
         Otto::Utils.relayed_request?(env)
       end
 
-      # Whether this request is for the protected endpoint. Normalizes
-      # +PATH_INFO+ through the same +Otto::Utils.normalize_path+ the router
-      # uses for literal matching, so a percent-encoded, invalid-byte, or
-      # trailing-slash variant the router would still route cannot slip past the
-      # guard by normalizing differently here than at dispatch.
+      # Whether this request is for the protected endpoint. Compares the path
+      # the router itself dispatches on (+Otto::Utils.routing_path+), so a
+      # percent-encoded, invalid-byte, or trailing-slash variant the router
+      # would still route cannot slip past the guard by normalizing differently
+      # here than at dispatch.
       #
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def targets_endpoint?(env)
-        normalize_path(env['PATH_INFO']) == @endpoint
+        Otto::Utils.routing_path(env) == @endpoint
       end
 
       # Router-equivalent path normalization. Delegates to the single shared

data/lib/otto/core/configuration.rb

@@ -85,10 +85,12 @@ class Otto
           @security_config.trusted_proxy_header = opts[:trusted_proxy_header]
         end
 
-        # Set custom security headers
-        return unless opts[:security_headers]
+        # Keep the generic security_headers option compatible while routing a
+        # Referrer-Policy entry through the same validated collection as the
+        # dedicated setting. When both are present, the dedicated option wins.
+        set_security_headers(opts[:security_headers]) if opts[:security_headers]
 
-        set_security_headers(opts[:security_headers])
+        @security_config.referrer_policy = opts[:referrer_policy] if opts.key?(:referrer_policy)
       end
 
       def configure_authentication(opts)