otto 2.11.0 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ci.yml +1 -1
  3. data/.github/workflows/claude-code-review.yml +1 -1
  4. data/.github/workflows/claude.yml +1 -1
  5. data/.github/workflows/code-smells.yml +2 -2
  6. data/.github/workflows/release-gem.yml +1 -1
  7. data/.github/workflows/ruby-lint.yml +1 -1
  8. data/.github/workflows/yardoc.yml +1 -1
  9. data/.rubocop_todo.yml +2 -2
  10. data/AGENTS.md +4 -2
  11. data/CHANGELOG.rst +792 -0
  12. data/Gemfile +3 -2
  13. data/Gemfile.lock +13 -8
  14. data/README.md +6 -0
  15. data/docs/README.md +4 -0
  16. data/docs/audits/2026-09-28-v2.12.0-code-audit.md +732 -0
  17. data/docs/audits/README.md +63 -0
  18. data/docs/guides/authentication.md +329 -0
  19. data/docs/guides/forwarded-authority.md +85 -5
  20. data/docs/guides/mcp.md +40 -4
  21. data/docs/guides/privacy.md +28 -2
  22. data/docs/guides/routing.md +76 -9
  23. data/docs/guides/testing-guide.md +146 -5
  24. data/docs/migrating/v2.3.0.md +13 -7
  25. data/docs/reference/authentication.md +70 -22
  26. data/examples/lambda_handlers/README.md +4 -4
  27. data/examples/lambda_handlers/handlers.rb +4 -5
  28. data/examples/lambda_handlers/routes +2 -2
  29. data/examples/mcp_demo/README.md +65 -27
  30. data/examples/mcp_demo/app.rb +8 -5
  31. data/examples/mcp_demo/config.ru +50 -3
  32. data/examples/mcp_demo/routes +10 -6
  33. data/examples/security_features/README.md +2 -2
  34. data/lib/otto/caddy_tls/localhost_guard.rb +6 -6
  35. data/lib/otto/caddy_tls/server.rb +8 -4
  36. data/lib/otto/core/configuration.rb +5 -3
  37. data/lib/otto/core/option_hash.rb +124 -0
  38. data/lib/otto/core/redacted_inspect.rb +149 -0
  39. data/lib/otto/core/router.rb +57 -34
  40. data/lib/otto/core.rb +2 -0
  41. data/lib/otto/env_keys.rb +30 -6
  42. data/lib/otto/logging_helpers.rb +1 -1
  43. data/lib/otto/mcp/auth/token.rb +12 -1
  44. data/lib/otto/mcp/protocol.rb +3 -3
  45. data/lib/otto/mcp/registry.rb +28 -2
  46. data/lib/otto/mcp/route_parser.rb +20 -8
  47. data/lib/otto/mcp/server.rb +17 -9
  48. data/lib/otto/privacy/config.rb +31 -14
  49. data/lib/otto/privacy/ip_privacy.rb +109 -3
  50. data/lib/otto/privacy/redacted_fingerprint.rb +8 -10
  51. data/lib/otto/request.rb +34 -0
  52. data/lib/otto/response.rb +5 -2
  53. data/lib/otto/route.rb +1 -1
  54. data/lib/otto/route_definition.rb +3 -2
  55. data/lib/otto/route_handlers/base.rb +1 -1
  56. data/lib/otto/route_handlers/logic_class.rb +86 -34
  57. data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
  58. data/lib/otto/security/config.rb +703 -345
  59. data/lib/otto/security/configurator.rb +82 -45
  60. data/lib/otto/security/core.rb +4 -2
  61. data/lib/otto/security/csp/report_middleware.rb +17 -1
  62. data/lib/otto/security/csrf.rb +17 -2
  63. data/lib/otto/security/csrf_validation.rb +13 -7
  64. data/lib/otto/security/middleware/csrf_middleware.rb +203 -37
  65. data/lib/otto/security/middleware/ip_privacy_middleware.rb +129 -42
  66. data/lib/otto/security/rate_limiter.rb +8 -5
  67. data/lib/otto/security/trusted_proxy_config.rb +396 -0
  68. data/lib/otto/static.rb +70 -6
  69. data/lib/otto/testing.rb +148 -0
  70. data/lib/otto/utils.rb +166 -40
  71. data/lib/otto/version.rb +1 -1
  72. data/lib/otto.rb +44 -11
  73. metadata +8 -2
data/CHANGELOG.rst CHANGED
@@ -7,6 +7,798 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
7
7
 
8
8
  <!--scriv-insert-here-->
9
9
 
10
+ .. _changelog-2.13.0:
11
+
12
+ 2.13.0 — 2026-11-01
13
+ ===================
14
+
15
+ Added
16
+ -----
17
+
18
+ - A resource handler declared on an ``MCP`` line can take one argument, the
19
+ Rack env of the MCP request, so it can check permissions per request the
20
+ way a tool handler can. A zero-argument handler is still called with no
21
+ arguments. ``Otto::MCP::Registry#read_resource`` takes the env as an
22
+ optional second argument and passes it to a registered handler that takes
23
+ one argument. A handler that requires more than one argument, or a keyword
24
+ argument, raises ``ArgumentError`` on read, which the endpoint reports as a
25
+ JSON-RPC internal error. Before this, any handler that took an argument
26
+ failed that way. (#296)
27
+
28
+ - ``Otto::Security::Config#existing_session_id(request)`` returns the CSRF
29
+ binding the request already has, from the same sources as
30
+ ``get_or_create_session_id``, or ``nil``. It never mints a binding, writes
31
+ to the session or sets ``env['otto.csrf_binding']``. (#308)
32
+
33
+ Changed
34
+ -------
35
+
36
+ - The generated-secret warning and ``CSRF_SECRET_REQUIRED_MESSAGE`` no longer
37
+ say that a generated secret is not valid across workers in general. Workers
38
+ forked after the secret was generated, as in a preloaded app, share it.
39
+ Workers that load the app themselves (cluster mode without preload),
40
+ processes started separately, other hosts and restarts each generate their
41
+ own secret and reject each other's tokens, and the messages now say so. The
42
+ warning text is in
43
+ ``Otto::Security::Config::CSRF_GENERATED_SECRET_WARNING``. (#297)
44
+
45
+ - Behind a session middleware, a strategy's ``result.session`` no longer
46
+ replaces ``env['rack.session']``. The same holds without one when a plain
47
+ Hash is already there, for example because upstream Rack middleware or an
48
+ Otto handler wrapper called ``Rack::Request#session`` before the route auth
49
+ wrapper ran. A custom strategy that returned its own session, or wrote into
50
+ the default one, is then visible only as
51
+ ``env['otto.strategy_result'].session``. Migration: write to
52
+ ``env['rack.session']``, pass ``session: env['rack.session']`` to
53
+ ``success``, or read the session through ``Otto::Request`` (whose stand-in
54
+ the wrapper replaces) instead of ``Rack::Request`` before authentication.
55
+ (#298)
56
+
57
+ - ``Otto::Request#session`` installs an ``Otto::Request::DefaultSession`` (an
58
+ empty ``Hash`` subclass) instead of a plain ``{}`` when env has no session,
59
+ and app code can see it: ``instance_of?(Hash)`` is false,
60
+ ``YAML.safe_load`` of its YAML dump raises ``Psych::DisallowedClass``, and
61
+ ``Marshal.dump`` records the class name, so loading the dump needs Otto.
62
+ ``to_h`` returns a plain ``Hash``. (#298)
63
+
64
+ - Any other ``key=value`` option on an ``MCP`` or ``TOOL`` line, such as
65
+ ``response=json``, now logs a ``MCP/tool route option not applied`` warning
66
+ when the routes file loads with MCP enabled. The option still loads, but the
67
+ MCP server reads only the resource URI or tool name and the handler, so it
68
+ has no effect. (#296)
69
+
70
+ - On HTTPS requests Otto no longer reads the ``_otto_session``, ``session_id``
71
+ or ``_session_id`` cookies as a CSRF binding. Accepting them as a fallback
72
+ would keep the planting vector, so there is no transition period. After the
73
+ upgrade, a token bound to one of those cookies is rejected once over HTTPS;
74
+ the next token the client fetches is bound to ``__Host-otto_session``. Plain
75
+ HTTP requests keep using ``_otto_session`` as before. The name follows Rack's
76
+ ``request.scheme``: behind a TLS-terminating proxy, Otto must see the request
77
+ as HTTPS (for example ``HTTPS=on``, ``rack.url_scheme``, or a forwarded
78
+ header Rack honors, such as ``X-Forwarded-Proto``) for the hardening to
79
+ apply; once proxy trust is configured, ``IPPrivacyMiddleware`` drops a
80
+ forwarded scheme sent by a peer that fails it. If Otto sees HTTPS while the
81
+ browser uses HTTP, the browser rejects the cookie and CSRF-protected requests
82
+ get ``403``. (#302)
83
+
84
+ - A form rendered over HTTP that posts to HTTPS now gets ``403`` on every
85
+ attempt when its binding lives in the cookie: the HTTP page sets
86
+ ``_otto_session``, which the HTTPS request does not read. Migration: serve
87
+ pages with forms over HTTPS, for example by redirecting HTTP to HTTPS and
88
+ enabling HSTS (``Otto::Security::Config#enable_hsts!``). (#302)
89
+
90
+ - ``CSRFMiddleware`` now also sets the binding cookie on responses that are
91
+ not HTML, when the request used a safe method (``GET``, ``HEAD``,
92
+ ``OPTIONS``, ``TRACE``) and resolved a binding the client does not already
93
+ send. A JSON client that fetches a token from an endpoint calling
94
+ ``Config#get_or_create_session_id`` receives the cookie with the token and
95
+ passes on its next POST. Two such fetches made in parallel before the client
96
+ holds the cookie get different bindings, and only the token whose cookie the
97
+ client kept is accepted. An unsafe request never sets the cookie this way,
98
+ so a cross-site POST, which arrives without the ``SameSite=Lax`` cookie,
99
+ cannot replace the victim's binding with one minted for its ``403``. The
100
+ binding is recorded in ``env['otto.csrf_binding']`` only when it was minted
101
+ or read from ``csrf_session_key``. The session store's own id
102
+ (``session.id``, or ``session['session_id']``), which the store's cookie
103
+ carries when the store sets one, and a binding read from a cookie, which the
104
+ client sends again, are not copied into the binding cookie on these
105
+ responses. (#302)
106
+
107
+ - An HTML response to an unsafe request that has no binding, such as a
108
+ ``csrf=exempt`` callback that another site posts to, now carries no CSRF
109
+ token, and ``CSRFHelpers#csrf_token`` returns ``nil`` there instead of
110
+ minting a binding; ``csrf_meta_tag`` and ``csrf_form_tag`` then render an
111
+ empty ``content`` or ``value``, which the next request's CSRF check rejects
112
+ with ``403``. Behind a session middleware, a handler that writes to the
113
+ session first still gets a token bound to the new session, and the store
114
+ sets its session cookie on that response. Migration: answer the POST with a
115
+ redirect and render the form on the page it redirects to. (#308)
116
+
117
+ - HTML responses no longer set ``_otto_session`` or ``__Host-otto_session``
118
+ to the session's id, ``session['session_id']``, or a binding read from the
119
+ app's ``session_id`` or ``_session_id`` cookie. Behind a session middleware
120
+ the store's cookie carries the binding. A store whose cookie does not come
121
+ back, such as rack-session with ``secure: true`` while Rack sees the request
122
+ as HTTP, kept no session between requests, but the copy kept CSRF tokens
123
+ valid; CSRF-protected requests now get ``403`` too. Fix the store's
124
+ configuration so its cookie is set: make Rack see the forwarded scheme, or
125
+ pass rack-session's ``assume_ssl: true`` (see the authentication guide).
126
+ (#308)
127
+
128
+ - Without a session middleware, a token bound to an auth strategy's session
129
+ that responds to ``id`` or holds a ``'session_id'`` key is now rejected with
130
+ ``403`` on the next request, unless that request also sends the same value
131
+ in a cookie the CSRF check reads (on plain HTTP, the app's ``session_id``
132
+ or ``_session_id`` cookie). The check runs before authentication, so it
133
+ read the copy of that id in the binding cookie, which HTML responses no
134
+ longer set. Migration: run a session middleware, or return a strategy
135
+ session without an id, in which Otto stores its own binding under
136
+ ``csrf_session_key``. (#308)
137
+
138
+ - With CSRF protection enabled, responses on which ``CSRFMiddleware`` sets the
139
+ binding cookie, HTML or not, and HTML pages into which it injects a token
140
+ now carry ``Cache-Control: private, stale-if-error=0`` when the application
141
+ sets neither ``Cache-Control`` nor ``Expires``. An HTML file served from
142
+ ``public:`` or ``mount_static`` gets no token, so it carries the header only
143
+ on a response that sets the binding cookie. A shared cache that honors
144
+ ``private`` no longer stores these responses, including one that stored
145
+ them before under a default TTL. ``Rack::ETag`` mounted outside Otto adds
146
+ its default ``Cache-Control``, ``max-age=0, private, must-revalidate``,
147
+ only when the response has none, so these responses no longer get it. (#309)
148
+
149
+ Fixed
150
+ -----
151
+
152
+ - An MCP endpoint with ``auth_tokens`` (``mcp_auth_tokens``), or with MCP rate
153
+ limiting, raised ``FrozenError`` on every request outside RSpec. The first
154
+ request runs the lazy configuration freeze in ``Otto#call``. Freezing the
155
+ middleware stack reached the already frozen security config a second time,
156
+ through the arguments of ``Otto::MCP::Auth::TokenMiddleware`` and
157
+ ``Otto::MCP::RateLimitMiddleware``, and
158
+ ``Otto::Security::Config#deep_freeze!`` then reran its freeze-time
159
+ validators and raised ``FrozenError: Cannot modify frozen configuration``.
160
+ Because the freeze never completed, every later request retried it and
161
+ raised again; an explicit ``freeze_configuration!`` at boot raised the same
162
+ error. ``Config#deep_freeze!`` now returns ``self`` when ``deep_freeze!``
163
+ already froze the config. On a config frozen with ``Object#freeze``, whose
164
+ nested settings are still mutable, it raises ``FrozenError`` with
165
+ ``Otto::Security::Config::SHALLOW_FREEZE_MESSAGE``, as main raised a
166
+ ``FrozenError`` there too. The test suite did not catch this because
167
+ ``Otto#call`` skips the lazy freeze when RSpec is loaded. (#293)
168
+
169
+ - HEAD requests no longer return 500 once the configuration is frozen. When
170
+ any ``HEAD`` route was declared, the router merged the GET tables into the
171
+ registered HEAD tables (``routes_literal[:HEAD]`` and ``routes[:HEAD]``) on
172
+ every HEAD request. After the first request outside the test suite those
173
+ tables are frozen, so every HEAD request raised ``FrozenError``. The router
174
+ now looks up the HEAD route first and falls back to the GET route without
175
+ changing either table. (#294)
176
+
177
+ - A declared ``HEAD`` literal route now handles HEAD requests for its path.
178
+ The merge let the ``GET`` route for the same path replace it, and it grew
179
+ ``routes[:HEAD]`` on every HEAD request while the configuration was not yet
180
+ frozen. Dynamic HEAD routes are still tried before dynamic GET routes. A
181
+ declared ``HEAD`` route uses its own options and does not inherit ``auth=``
182
+ or ``role=`` from the ``GET`` route for the same path. A HEAD request for a
183
+ path with only a ``GET`` route falls back to that route, including its
184
+ ``auth=``. (#294)
185
+
186
+ - Responses to HEAD requests now have an empty body. A HEAD request that fell
187
+ back to a ``GET`` route returned the GET body, which ``Rack::Lint`` rejects
188
+ with "Response body was given for HEAD request, but should be empty".
189
+ ``Otto#call`` now replaces the body after dispatch and error handling and
190
+ keeps the status and headers, including a ``content-length`` the handler
191
+ set. When the handler's body is a plain Array and the response has no
192
+ ``content-length``, no ``transfer-encoding`` and a status that allows
193
+ content, ``Otto#call`` sets ``content-length`` from that Array, so the HEAD
194
+ response advertises the length a GET would send; Puma and
195
+ ``Rack::ContentLength`` would otherwise compute 0 from the empty body. The
196
+ replacement body has no ``#to_ary`` and closes the original when the server
197
+ closes it, as it would for GET, so an error raised by that close surfaces
198
+ there, not from ``Otto#call`` or from middleware such as ``Rack::ETag``.
199
+ This covers handler, ``/404``, not-found and error responses. Request
200
+ completion hooks receive a plain empty Array as the body. The Caddy TLS
201
+ permission endpoint now writes its body for HEAD as well, so its HEAD
202
+ responses advertise the GET length instead of 0. (#294)
203
+
204
+ - Static mounts and the public directory now answer HEAD requests. They
205
+ answered only GET, so a HEAD request for an asset fell through to the
206
+ dynamic routes and, when none matched, to not found. A HEAD response
207
+ carries the headers a GET would get, including ``content-length``, and an
208
+ empty body. Requests with other methods still skip the static stages.
209
+ (#294)
210
+
211
+ - Apps that enable CSRF protection without ``OTTO_CSRF_SECRET`` or
212
+ ``csrf_secret=`` no longer return 500 for every HTML response outside
213
+ production. ``Otto#call`` freezes the configuration on the first request,
214
+ and the first CSRF token generation then recorded on the frozen
215
+ ``Otto::Security::Config`` that the generated-secret warning had been
216
+ logged, which raised ``FrozenError``. The once-only state now lives in an
217
+ object that stays writable after the freeze. With CSRF enabled, the warning
218
+ is logged when the configuration is frozen. A frozen config with CSRF
219
+ protection disabled logs it the first time ``CSRFHelpers#csrf_token`` or
220
+ ``generate_csrf_token`` signs a token (it raised ``FrozenError`` before).
221
+ The warning is logged once per config, also when several threads generate
222
+ the first tokens at the same time. Specs under RSpec did not hit the error
223
+ because Otto skips the lazy freeze when RSpec is loaded. (#297)
224
+
225
+ - ``RouteAuthWrapper`` no longer replaces an existing ``env['rack.session']``
226
+ with the strategy result's session. ``NoAuthStrategy``, ``RoleStrategy``,
227
+ ``PermissionStrategy``, and ``APIKeyStrategy`` return the empty Hash that
228
+ ``StrategyResult.anonymous`` and ``AuthStrategy#success`` use as a default,
229
+ and that Hash used to overwrite the session installed by the session
230
+ middleware. On ``auth=noauth`` routes, an ``auth=session,noauth``
231
+ fall-through, and role, permission, and API key routes the handler received
232
+ a bare Hash. rack-session then raised ``NoMethodError`` (undefined method
233
+ ``options`` for Hash) while committing the session, and the handler's
234
+ session writes were lost. The handler now receives the session object the
235
+ middleware installed. (#298)
236
+
237
+ - When env has no session, or holds only the stand-in Hash that
238
+ ``Otto::Request#session`` installs when no session middleware ran, the
239
+ wrapper sets ``env['rack.session']`` to the strategy's session (anything
240
+ but ``nil`` or ``false``), as before. Otto's CSRF check reads the session
241
+ that way before authentication, so strategy-owned sessions keep their
242
+ writes on CSRF-checked requests. (#298)
243
+
244
+ - A new visitor's first form POST no longer fails CSRF validation with 403
245
+ when the session store loads lazily, as rack-session does. On the page that
246
+ issued the token the session id was still nil, so Otto bound the token to a
247
+ random value it stored under ``csrf_session_key``. That write made the store
248
+ mint a session id, and on the POST Otto read that id first, so the token was
249
+ checked against a different value.
250
+ ``Otto::Security::Config#get_or_create_session_id`` now reads back the id
251
+ the store minted during the write and binds the token to it. Pages that
252
+ wrote to the session before the token was issued were not affected. (#295)
253
+
254
+ - Session ids are converted with ``to_s`` before they are used as the CSRF
255
+ binding, and ``get_or_create_session_id`` always returns a String.
256
+ rack-session returns a ``Rack::Session::SessionId`` object, which never
257
+ compared equal to the ``_otto_session`` cookie, so ``CSRFMiddleware`` set
258
+ that cookie again on every HTML response it added a token to. (#295)
259
+
260
+ - The binding still follows the session id. A store that renews the id, for
261
+ example rack-session's ``renew`` option at login, invalidates the tokens
262
+ issued before the renewal. (#295)
263
+
264
+ - ``CSRFMiddleware`` now URL-encodes the value of the CSRF binding cookie,
265
+ because Rack URL-decodes cookie values when it reads them. Before, a binding
266
+ that was not a hex token was written as is, and the browser could store a
267
+ different value: an app-set ``session_id`` cookie sent as ``a%3Bb`` (the
268
+ binding ``a;b``) on plain HTTP came back as ``_otto_session=a``, and the
269
+ next CSRF-protected request got ``403``. Hex bindings, including the ones
270
+ Otto generates, are written unchanged. (#302)
271
+
272
+ - A CSRF-protected request now gets ``403`` instead of ``500`` when its token
273
+ is a parameter that Rack parses into an Array or a Hash (``_csrf_token[]=``
274
+ or ``_csrf_token[k]=``), a token with invalid UTF-8 bytes, a signature with
275
+ as many characters as a valid one but more bytes (such as 64 ``é``), or an
276
+ ``ASCII-8BIT`` header token with non-ASCII bytes when the binding has
277
+ non-ASCII characters. The CSRF check raised for each of these, and Otto
278
+ logged an unhandled error. The request was refused either way; only the
279
+ status was wrong. A body that Rack cannot parse, such as
280
+ ``_csrf_token=%ZZ``, still gets ``500``, with or without CSRF
281
+ protection. (#307)
282
+
283
+ - ``Otto::Security::Config#verify_csrf_token`` now returns ``false`` for a
284
+ token that is not a ``String`` or that holds non-ASCII bytes, since a valid
285
+ token is hex. Signatures are compared with ``Rack::Utils.secure_compare``,
286
+ which compares lengths in bytes, in place of a loop that compared lengths in
287
+ characters. ``CSRFEnforcementWrapper`` rejects such a token before it
288
+ resolves the CSRF binding, as it already did for a blank one, so the check
289
+ does not create a session or a binding for it. (#307)
290
+
291
+ - A request that fails the CSRF check no longer creates a binding. Validation
292
+ called ``get_or_create_session_id``, so a request without one had a binding
293
+ minted and written to the session, though no token can verify against a new
294
+ binding. Behind rack-session the rejected POST then committed a new session
295
+ and set its cookie on the ``403``. Validation now reads the binding with
296
+ ``existing_session_id``. (#308)
297
+
298
+ - ``CSRFMiddleware`` no longer changes the application's headers on HTML
299
+ responses; it works on a copy, as it already did on other responses. Before,
300
+ frozen headers raised ``FrozenError``, and an application that returned the
301
+ same headers object for every response had the injected page's
302
+ ``Content-Length`` and each client's binding cookie carried into the
303
+ responses for later clients. (#309)
304
+
305
+ - ``CSRFMiddleware`` no longer adds the binding cookie to a response that
306
+ already sets a cookie of that name, as one does when the middleware runs
307
+ more than once for a request: added again around an Otto with CSRF
308
+ protection, or in nested CSRF-enabled Ottos (for example an Otto whose
309
+ ``not_found=`` is another Otto). The first, innermost, middleware's cookie
310
+ is kept. A shared ``csrf_session_key`` gave identical cookies. Without
311
+ session middleware, Ottos with different ``csrf_session_key`` values mint
312
+ different bindings; the browser kept the outer Otto's, and the inner Otto,
313
+ which checks the requests its routes receive, rejected the tokens it issued
314
+ on that page with ``403``. Those tokens now pass. The outer Otto still
315
+ injects its own ``csrf-token`` meta tag, ahead of the inner Otto's, and its
316
+ token now fails on the page that set the cookie in that case; it passes
317
+ only when the two Ottos share ``csrf_secret`` and resolve the same binding,
318
+ as they do once the client sends the cookie back. (#309)
319
+
320
+ - ``CSRFMiddleware`` now reads an HTML body through ``#to_ary``. The Rack
321
+ specification says "middleware can only process the Body directly if it
322
+ responds to +to_ary+", and that "If the Body responds to both +to_ary+ and
323
+ +close+, its implementation of +to_ary+ must call +close+." Before, the
324
+ middleware read the body with ``join``, or with ``to_s`` when it lacked
325
+ ``join``: a body wrapped by ``Rack::Lint`` got no token, and a
326
+ ``Rack::BodyProxy`` was replaced without being closed, so its close callback
327
+ never ran. A String body, or one that responds to ``join`` but not
328
+ ``to_ary``, now gets no token. Otto's route handlers wrap a String body in
329
+ an Array, so a String page they return still gets one. Other bodies, such as
330
+ files and streams, are still returned unread. (#309)
331
+
332
+ - An HTML page with an invalid byte for its encoding, such as a Latin-1 file
333
+ read as UTF-8, or with body parts in incompatible encodings, no longer gets
334
+ ``500`` when CSRF protection is enabled. ``CSRFMiddleware`` now searches the
335
+ body for ``<head>`` as bytes, injects the token, and leaves the other bytes
336
+ unchanged. The page keeps the encoding its parts have when joined as text,
337
+ and stays binary only when their encodings are incompatible. (#309)
338
+
339
+ Security
340
+ --------
341
+
342
+ - With ``trusted_proxies`` configured, client IP resolution now reads
343
+ ``X-Forwarded-For`` from the right: it skips entries that match a trusted
344
+ proxy and uses the first entry that does not. It previously used the
345
+ leftmost such entry, which the client controls when the proxy appends to
346
+ the header, so a client could choose ``env['otto.client_ip']``, the address
347
+ ``env['otto.ip_match']`` checks, and the ``Otto::Request#client_ipaddress``
348
+ fallback. ``X-Real-IP`` and ``X-Client-IP`` are read only when
349
+ ``X-Forwarded-For`` is absent or blank and are no longer added to its
350
+ chain. ``trusted_proxy_depth`` already counted from the right.
351
+ **Behavior change**: every proxy between the client and the application
352
+ must now be in ``trusted_proxies``, together with any address a proxy
353
+ appends about itself. Google Cloud's external Application Load Balancer,
354
+ for example, appends the client's address and then its forwarding rule's
355
+ address. If one is missing, the unlisted address nearest the application
356
+ becomes the client IP for every request through it: rate-limit keys and
357
+ ``otto.privacy.hashed_ip`` collapse onto it, ``ip_match`` tests it, and a
358
+ private or loopback one exempts the request from masking. 2.12.0 took the
359
+ leftmost untrusted entry, so a missing inner hop went unnoticed. A request
360
+ whose ``X-Forwarded-For`` holds only trusted proxies now resolves to
361
+ ``REMOTE_ADDR`` even when ``X-Real-IP`` names the client.
362
+ **Migration:** list every proxy address, CDN edge ranges and load balancer
363
+ addresses included, in ``trusted_proxies``, and configure each proxy to
364
+ append the address it received the request from to ``X-Forwarded-For``
365
+ (nginx: ``proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;``)
366
+ or to replace a client-supplied value. A proxy that sets only ``X-Real-IP``
367
+ must also append to or replace ``X-Forwarded-For``. See `How enumerated
368
+ proxy trust resolves the client IP
369
+ <docs/guides/forwarded-authority.md#how-enumerated-proxy-trust-resolves-the-client-ip>`__. (#292)
370
+
371
+ - A forwarded entry that is not a valid IP address (such as ``unknown``, or
372
+ an empty entry, including the one a trailing comma leaves) no longer falls
373
+ back to ``REMOTE_ADDR``. In ``trusted_proxies`` mode the walk ends there;
374
+ in ``trusted_proxy_depth`` mode it applies when that entry is the selected
375
+ hop. The request then has no client IP: ``env['otto.ip_match']`` denies
376
+ every range, ``env['otto.client_ip']`` and
377
+ ``Otto::Request#client_ipaddress`` are nil, and with IP privacy enabled
378
+ ``X-Forwarded-For``, ``X-Real-IP`` and ``X-Client-IP`` are deleted and
379
+ ``Forwarded`` loses its ``for=`` pairs but keeps ``proto=``, ``host=`` and
380
+ ``by=`` (it is deleted only if nothing else is left). A request with no
381
+ ``REMOTE_ADDR`` takes the same path; its ``Forwarded`` header used to be
382
+ deleted outright. ``Otto::Request#ip`` and a plain ``Rack::Request#ip``
383
+ still return ``REMOTE_ADDR``, the proxy, on purpose: rate limiters key on
384
+ the request IP, and rack-attack skips a throttle whose discriminator is
385
+ nil. Use ``ip_match``,
386
+ not ``req.ip``, for access decisions. Falling back to the proxy's own
387
+ address made a private or loopback peer the client, which skipped masking,
388
+ left the client's address in ``X-Forwarded-For``, and let ``ip_match``
389
+ test the proxy. **Behavior change** for ``trusted_proxy_depth``, whose
390
+ invalid-target fallback to ``REMOTE_ADDR`` was documented. Depth mode's
391
+ short-chain fallback to ``REMOTE_ADDR`` is unchanged. **Migration:** a
392
+ trusted proxy that writes ``unknown`` where the client address belongs
393
+ now leaves every request through it without a client IP; configure it to
394
+ append the address it received the request from. (#292)
395
+
396
+ - With IP privacy enabled, a request exempt from masking because its resolved
397
+ client IP is private or loopback now has its ``X-Forwarded-For``,
398
+ ``X-Real-IP`` and ``X-Client-IP`` headers and the ``for=`` values in
399
+ ``Forwarded`` rewritten to that client IP. They were left as received, so
400
+ a public address in them stayed in the Rack env: an entry left of an
401
+ unlisted private proxy hop, or a header sent by an untrusted private peer
402
+ or by any client behind a loopback peer with no proxy trust configured.
403
+ ``Rack::Request#ip``, whose default filter trusts private and loopback
404
+ addresses, returned that public address. **Behavior change**: code behind
405
+ a private or loopback peer that read these headers, or called a plain
406
+ ``Rack::Request#ip``, now sees the resolved client IP. Behind a local
407
+ reverse proxy with no trusted proxy configured, that is ``127.0.0.1`` for
408
+ every client, so a rate limiter keyed on ``Rack::Request#ip`` after
409
+ ``IPPrivacyMiddleware`` (rack-attack's request is a ``Rack::Request``) puts
410
+ every client in the loopback bucket. It used to read each client's own,
411
+ unverified ``X-Forwarded-For`` value. **Migration:** to get the client's
412
+ address from a local reverse proxy, list that proxy in ``trusted_proxies``
413
+ so Otto resolves the client (and masks a public one). (#292)
414
+
415
+ - The ``Forwarded`` ``for=`` rewrite (masking, the exemption above, and the
416
+ no-client-IP removal) now finds ``for=`` after every separator Rack 3.2.7
417
+ accepts: whitespace, including a leading tab, and a closing quote, as in
418
+ ``by="x" for=198.51.100.7``. It used to find it only at the start or after
419
+ a comma or semicolon, so a client-chosen ``for=`` could survive and be
420
+ returned by ``Rack::Request#ip``. The result is re-read with
421
+ ``Rack::Utils.forwarded_values``; if another ``for=`` value survives, or
422
+ Rack cannot parse the header (Rack rejects parameters other than ``by``,
423
+ ``for``, ``host`` and ``proto``, so an RFC 7239 extension parameter is
424
+ enough), the header is deleted. The first deletion in a process is logged
425
+ at warn and later ones at debug, since a header like that arrives on every
426
+ request and any client can send one. (#292)
427
+
428
+ - ``Otto::Utils.normalize_ip`` returns nil for a value written as a range,
429
+ such as ``203.0.113.9/0`` or ``10.0.0.0/8``, so a forwarded entry written
430
+ that way is now invalid and the request has no client IP. 2.12.0 took it
431
+ for an address. With ``trusted_proxies: ['10.0.0.0/8']``: a public range
432
+ was returned as the client IP and masked to its network address
433
+ (``203.0.113.9/0`` became ``0.0.0.0``, ``203.0.113.9/32`` became
434
+ ``203.0.113.0``); a loopback or private range outside the trusted list was
435
+ exempted from masking and written to ``REMOTE_ADDR`` and
436
+ ``otto.client_ip`` as the literal string (``127.0.0.1/8``, which
437
+ ``ip_match(['127.0.0.0/8'])`` accepted); and a range inside the trusted
438
+ list (``10.0.0.0/8``) was skipped as a trusted hop.
439
+ ``Otto::Utils.ip_in_cidrs?`` returns false when the client address it is
440
+ given is a range, as a string or as an ``IPAddr`` whose prefix is shorter
441
+ than a host address (``IPAddr.new('203.0.113.0/24')`` used to match
442
+ ``203.0.0.0/16``). (#292)
443
+
444
+ - With IP privacy enabled, vendor headers that carry the client address are
445
+ now masked along with ``REMOTE_ADDR``: ``CF-Connecting-IP``,
446
+ ``CF-Connecting-IPv6``,
447
+ ``True-Client-IP``, ``Fastly-Client-IP``, ``Fly-Client-IP``,
448
+ ``X-Azure-ClientIP``, ``X-Azure-SocketIP``, ``CloudFront-Viewer-Address``,
449
+ ``X-Vercel-Forwarded-For``, ``X-Original-Forwarded-For``,
450
+ ``X-Cluster-Client-IP`` and ``X-AppEngine-User-IP``
451
+ (``Otto::Utils::VENDOR_CLIENT_ADDRESS_HEADERS``). They were left raw while
452
+ ``REMOTE_ADDR`` was masked, so the public client address stayed in the Rack
453
+ env. They are rewritten to the resolved client IP on the private/loopback
454
+ exemption, deleted when no client IP resolves, and masked in the env a
455
+ custom geo resolver sees. Otto still never reads the client IP from them.
456
+ **Behavior change**: code that read one of these headers to get the
457
+ client address now sees the masked (or exempt) address. **Migration:**
458
+ configure ``trusted_proxies`` for the CDN so Otto resolves the client from
459
+ ``X-Forwarded-For``, and read ``req.ip`` or ``env['otto.ip_match']``; use
460
+ the ``:audit`` profile if the raw address is required. (#292)
461
+
462
+ - ``Otto::Security::Config#csrf_secret=`` no longer uses ``nil`` or a blank
463
+ string as the CSRF signing key. Previously ``config.csrf_secret = ''`` (for
464
+ example from ``ENV.fetch('OTTO_CSRF_SECRET', '')``) stored the empty string
465
+ as the HMAC key and marked the secret as configured, so the production guard
466
+ did not fire and a token signed with an empty key verified. ``nil`` was
467
+ stored as well, and every token signing then raised ``TypeError``. For
468
+ ``nil`` and blank strings the setter now uses ``OTTO_CSRF_SECRET`` when that
469
+ is set and not blank, so an assignment from an unset setting no longer
470
+ replaces a secret from the environment. Otherwise it generates a fresh
471
+ random per-process secret marked as generated, the same fallback as an unset
472
+ ``OTTO_CSRF_SECRET``. With CSRF protection enabled and
473
+ ``RACK_ENV=production``, generating a token then raises ``ArgumentError``
474
+ asking for a configured secret, as it does when ``OTTO_CSRF_SECRET`` is
475
+ unset. (#299)
476
+
477
+ - A secret is blank when it holds only Unicode whitespace (``[[:space:]]``),
478
+ characters with the Unicode ``Default_Ignorable_Code_Point`` property (such
479
+ as zero-width spaces and joiners, the soft hyphen U+00AD, the word joiner
480
+ U+2060, the byte order mark U+FEFF, bidirectional marks and the Hangul
481
+ filler U+3164) and NUL. The pattern is
482
+ ``Otto::Security::Config::BLANK_CSRF_SECRET``, matched in UTF-8: the
483
+ string converted from its own encoding, or else its bytes read as UTF-8,
484
+ which is how a non-ASCII ``OTTO_CSRF_SECRET`` arrives under ``LANG=C``
485
+ (tagged ``ASCII-8BIT``). A string that fits neither is blank only if it
486
+ holds nothing but ASCII whitespace and NUL. (#299)
487
+
488
+ - A blank ``OTTO_CSRF_SECRET`` is now treated as unset, like an empty one.
489
+ (#299)
490
+
491
+ - ``csrf_secret=`` raises ``ArgumentError`` for a value that is neither a
492
+ ``String`` nor ``nil``. (#299)
493
+
494
+ - ``csrf_secret=`` logs a warning when the configured secret, from the setter
495
+ or from ``OTTO_CSRF_SECRET``, is shorter than 32 bytes
496
+ (``Otto::Security::Config::CSRF_SECRET_MIN_BYTES``). The warning gives the
497
+ length, not the secret. The secret is still used, and nothing raises, so an
498
+ app that already runs with a short secret keeps booting. (#299)
499
+
500
+ - When ``csrf_secret=`` generates a new secret, the generated-secret warning
501
+ (``Otto::Security::Config::CSRF_GENERATED_SECRET_WARNING``) is logged for
502
+ that secret too, even if it was already logged for an earlier generated
503
+ secret, for example by ``generate_csrf_token`` on a config that was not yet
504
+ frozen. (#299)
505
+
506
+ - ``auth=``, ``role=``, and ``csrf=`` on an ``MCP`` or ``TOOL`` line are now
507
+ rejected. Otto parsed these options but never applied them: the MCP server
508
+ registered the resource or tool without an authentication, role, or CSRF
509
+ check, so any request the MCP endpoint accepted could read the resource or
510
+ call the tool. **Behavior change**: when MCP is enabled as the routes file
511
+ loads (``Otto.new(path, mcp_enabled: true)``, or ``enable_mcp!`` before
512
+ ``load``), a routes file that sets any of these options on an ``MCP`` or
513
+ ``TOOL`` line raises ``Otto::RouteDefinitionError`` and the application
514
+ fails to boot. Remove the options and require a token for the endpoint with
515
+ ``mcp_auth_tokens``. When MCP is not enabled as the file loads, Otto logs
516
+ and skips every ``MCP`` and ``TOOL`` line, as before, without checking its
517
+ options. See the `MCP guide <docs/guides/mcp.md>`__. (#296)
518
+
519
+ - ``#inspect`` no longer prints secrets held by Otto objects. Ruby's
520
+ ``FrozenError`` message embeds the receiver's ``#inspect``, and Otto's error
521
+ handler logs ``error.message``, so a write to a frozen
522
+ ``Otto::Security::Config`` (for example ``config.max_request_size = 1``
523
+ after the configuration froze) logged the CSRF signing key. These values
524
+ now print as ``[REDACTED]``, or ``[REDACTED] (N)`` for a collection of N,
525
+ in ``#inspect`` and in ``pp``:
526
+
527
+ - ``@csrf_secret`` in ``Otto::Security::Config``
528
+ - ``@correlation_secret`` in ``Otto::Privacy::Config`` (``nil`` stays
529
+ ``nil``)
530
+ - ``@tokens`` in ``Otto::MCP::Auth::TokenAuth``
531
+ - ``@auth_tokens`` in ``Otto::MCP::Server``
532
+ - the ``auth_tokens`` and ``mcp_auth_tokens`` entries of ``Otto#option``
533
+
534
+ The output otherwise keeps the ``Object#inspect`` shape. The shared
535
+ implementation is ``Otto::Core::RedactedInspect``. (#300)
536
+
537
+ - ``Otto#option`` is now an ``Otto::Core::OptionHash``, a ``Hash`` subclass.
538
+ It stores MCP bearer tokens as ``Otto::Core::RedactedInspect::SecretList``
539
+ (an ``Array`` subclass) or ``SecretSet`` (a ``Set`` subclass) of frozen
540
+ ``SecretString`` copies (a ``String`` subclass), or as one frozen
541
+ ``SecretString`` for a single token, including tokens stored after
542
+ construction with ``[]=``, ``store``, ``merge!``, ``update``, ``replace``,
543
+ ``transform_values!`` or ``transform_keys!``. The MCP server builds its own
544
+ ``SecretList``, and ``TokenAuth`` a frozen ``SecretSet`` holding the same
545
+ frozen ``SecretString`` objects as the server; ``Otto#option`` holds
546
+ separate copies. Writing to the frozen option Hash, to its token list or
547
+ Set, or to one token (``otto.option[:x] = 1``,
548
+ ``otto.option[:mcp_auth_tokens] << 'y'``) raises a ``FrozenError`` whose
549
+ message shows ``[REDACTED]`` instead of the tokens. The values are still a
550
+ ``Hash``, an ``Array`` or ``Set``, and ``String``\ s: ``==``, ``include?``
551
+ and iteration behave as before. ``to_s`` of the option Hash, of a token
552
+ list and of a token Set now returns the redacted text, for example
553
+ ``[REDACTED] (1)``; ``to_s`` of one token still returns the token.
554
+ ``otto.option[:mcp_auth_tokens]`` is a copy, so the Array or Set passed to
555
+ ``Otto.new`` is no longer frozen with the configuration. (#300)
556
+
557
+ - With ``Otto.debug`` on, ``Otto.new`` logged its raw options, including
558
+ ``mcp_auth_tokens``. It now logs the redacted ``Otto#option``. (#300)
559
+
560
+ - ``Otto::Privacy::Config#correlation_secret`` returns a frozen
561
+ ``SecretString`` copy of the configured value, and
562
+ ``Otto::Security::Config#deep_freeze!`` replaces the CSRF signing key with
563
+ a frozen ``SecretString`` copy before it freezes the config. Neither freezes
564
+ the String the application passed in, so a later write to that String no
565
+ longer raises a ``FrozenError`` that prints it, and a write through
566
+ ``correlation_secret`` raises one that shows ``[REDACTED]``. (#300)
567
+
568
+ - On HTTPS requests, Otto's own CSRF binding cookie is now
569
+ ``__Host-otto_session``, set with ``Secure``, ``Path=/`` and no ``Domain``.
570
+ Browsers that enforce cookie name prefixes accept such a cookie only from a
571
+ secure origin with those attributes, so in those browsers a sibling subdomain
572
+ or a network attacker can no longer plant it. Before, when the session
573
+ provided no binding, a planted ``_otto_session`` (or ``session_id`` or
574
+ ``_session_id``) cookie became the binding, and an attacker holding a token
575
+ for it could forge a login. This covers only Otto's fallback cookie. Behind a
576
+ session middleware the binding is the session's id, so the session cookie can
577
+ still be planted unless it is protected the same way: over HTTPS, configure
578
+ rack-session with a ``__Host-`` key and ``secure: true`` (for example ``use
579
+ Rack::Session::Cookie, key: '__Host-rack.session', secure: true, secrets:
580
+ [...]``). Renewing the session id at login
581
+ (``env['rack.session.options'][:renew] = true``) also keeps a session that
582
+ existed before login from carrying over, though it does not stop a forged
583
+ login. See ``docs/guides/authentication.md``. (#302)
584
+
585
+ - A cross-site POST to a ``csrf=exempt`` route that returns HTML no longer
586
+ replaces the victim's CSRF binding. Such a POST arrives without the
587
+ ``SameSite=Lax`` binding cookie, but the browser keeps a cookie set on the
588
+ response to it. ``CSRFMiddleware`` minted a binding for it, set it as the
589
+ binding cookie and injected a token, so the forms the victim had open got
590
+ ``403``. Behind rack-session, when the browser did not send the session
591
+ cookie either, a new session was committed over the victim's. On an unsafe
592
+ request ``CSRFMiddleware`` now neither creates a binding nor sets the
593
+ binding cookie, and injects a token only when the request already has a
594
+ binding. (#308)
595
+
596
+ - ``CSRFMiddleware`` no longer copies the session's id into the binding
597
+ cookie on HTML responses. It copied ``session.id``,
598
+ ``session['session_id']`` or a binding read from a cookie into the binding
599
+ cookie. A victim whose browser held a planted copy of the attacker's
600
+ session cookie then kept the attacker's session id in the binding cookie,
601
+ which Otto sets without ``Expires``. Once the session cookie was gone, for
602
+ example at the end of its ``expire_after`` lifetime, that id was the
603
+ binding again and a token the attacker held for it was accepted. HTML and
604
+ other responses now share one rule and one code path: the binding cookie is
605
+ set only on responses to safe requests, and only to a binding Otto minted
606
+ or read from ``csrf_session_key``. When
607
+ ``CSRFMiddleware`` mints a binding behind a session store added with
608
+ ``otto.use`` before CSRF protection is enabled, the id that store creates
609
+ is the binding: the store runs inside the middleware, has already
610
+ committed, and never sends that id, so the binding cookie carries it.
611
+ (#308)
612
+
613
+ - ``CSRFMiddleware`` now adds ``Cache-Control: private, stale-if-error=0`` to
614
+ a response on which it sets the CSRF binding cookie or injects a token,
615
+ unless the application set ``Cache-Control`` or ``Expires`` on it. Both are
616
+ meant for one client, and RFC 9111, section 7.3, notes that "the Set-Cookie
617
+ response header field [COOKIE] does not inhibit caching". A shared cache
618
+ that stored such a response could hand one client's binding cookie, with the
619
+ token bound to it, to other clients, or serve a page with a token bound to
620
+ one user's session to everyone. Section 5.2.2.7 says of ``private`` that "a
621
+ shared cache MUST NOT store the response". The browser's own cache may still
622
+ store it. ``stale-if-error=0`` (RFC 5861) is for CloudFront, which stores
623
+ such a response when the cache policy's minimum TTL is above 0, as in the
624
+ managed CachingOptimized policy. For that case the CloudFront developer
625
+ guide says: "If the origin is unreachable and the minimum or maximum TTL
626
+ value is greater than 0, CloudFront will serve the object that it got from
627
+ the origin previously. To avoid this behavior, include the Cache-Control:
628
+ stale-if-error=0 directive with the object returned from the origin." An
629
+ application value, including one that lets shared caches store the response
630
+ such as ``public, max-age=60``, is kept as is. A token the application
631
+ writes into a response itself, which Otto does not change, needs its own
632
+ ``Cache-Control``. Otto does not read fields that some caches give
633
+ precedence over ``Cache-Control``, such as ``CDN-Cache-Control``,
634
+ ``Surrogate-Control`` or ``X-Accel-Expires``. See
635
+ ``docs/guides/authentication.md``. (#309)
636
+
637
+ Documentation
638
+ -------------
639
+
640
+ - The authentication guide and reference describe when the route auth wrapper
641
+ sets ``env['rack.session']`` from ``result.session``. The guide adds that
642
+ Logic classes get no env, so behind a session middleware on ``auth=noauth``,
643
+ role, permission, and API key routes, and on any route without ``auth=``,
644
+ ``@context.session`` is a separate Hash whose writes are not persisted, and
645
+ says what to use instead. (#298)
646
+
647
+ - The authentication reference no longer says the route auth wrapper sets
648
+ ``env['otto.user']`` (nothing sets it; the user is
649
+ ``env['otto.strategy_result'].user``), that ``enable_authentication!`` is a
650
+ no-op (it was removed and raises ``NoMethodError``), or that the
651
+ ``auth=role:admin`` syntax was removed (it resolves to the ``role`` strategy,
652
+ and ``RoleStrategy`` checks the session's roles). A ``LoggingHelpers``
653
+ example comment that read ``env['otto.user']`` now reads the strategy
654
+ result. (#298)
655
+
656
+ - The authentication guide has a section on renewing the session id at login
657
+ with rack-session's ``:renew`` option, as protection against session
658
+ fixation. Otto never changes the session id itself. With CSRF protection
659
+ enabled, tokens issued before the renewal stop validating. (#298)
660
+
661
+ - The authentication reference's multi-strategy flow no longer says the first
662
+ success wins and that 401 is returned only when every strategy fails. It now
663
+ describes the held anonymous fallback, terminal failures, and the 403, 401
664
+ and 302 outcomes. Its role extraction order now includes object-backed users
665
+ (``#roles``, then ``#role``). (#298)
666
+
667
+ - The session-renewal section of the authentication guide says fixation lets
668
+ the attacker in with a server-side store such as ``Rack::Session::Pool``
669
+ but not with ``Rack::Session::Cookie``, recommends redirecting after login
670
+ because a form rendered in the login response carries a token bound to the
671
+ old id, and notes that its CSRF text assumes #295. The reference's
672
+ ``auth=noauth,apikey`` example gives the 302 for non-JSON requests, and the
673
+ multi-strategy notes in ``AGENTS.md`` match the code. (#298)
674
+
675
+ - The MCP guide's multi-step example now calls ``enable_mcp!`` before it
676
+ loads the routes file. It called ``Otto.new('routes')`` first, so Otto
677
+ logged and skipped every ``MCP`` and ``TOOL`` line and the endpoint served
678
+ no resources or tools. (#296)
679
+
680
+ - ``examples/mcp_demo`` now registers its resource and tool. Its routes file
681
+ put ``MCP`` and ``TOOL`` in the verb position, so the route loader
682
+ registered them as ordinary routes for HTTP methods named ``MCP`` and
683
+ ``TOOL`` instead of as a resource and a tool. The lines now use the
684
+ ``VERB /path MCP uri Handler`` and ``VERB /path TOOL name Handler`` forms.
685
+ Its ``config.ru`` also sets a ``Rack::Attack`` cache store, without which
686
+ every request raised ``Rack::Attack::MissingStoreError``. (#296)
687
+
688
+ - The authentication guide now describes a limitation: behind
689
+ ``Rack::Session::Pool``, Otto reads ``session.id`` without loading the
690
+ session, so the CSRF binding is the id the session cookie names even when
691
+ the store holds no session for it, and a planted session cookie does not
692
+ have to name a real session. Otto does not load the session to
693
+ check, since rack-session commits a session that was loaded. The guide
694
+ recommends protecting the session cookie itself (a ``__Host-`` key with
695
+ ``secure: true``), as it already did, and quotes the rack-session 2.1.2
696
+ code it relies on. (#308)
697
+
698
+ - The lambda handlers example no longer says ``csrf=exempt`` is recorded but
699
+ not enforced. It has been enforced at the handler layer since 2.6.0 (#186).
700
+ (#308)
701
+
702
+ .. _changelog-2.12.0:
703
+
704
+ 2.12.0 — 2026-09-26
705
+ ===================
706
+
707
+ Added
708
+ -----
709
+
710
+ - ``referrer_policy`` sets the Referrer-Policy header on routed responses,
711
+ static files, built-in 404 and 500 responses, and authentication failures.
712
+ Pass one W3C policy token to ``Otto.new`` or assign it before the first
713
+ request. A value a route handler sets on its own response is kept. See
714
+ ``docs/guides/testing-guide.md``. (#281)
715
+
716
+ - Logic classes can declare a ``route_params:`` keyword on ``initialize`` to
717
+ receive the router's path captures separately from caller-supplied
718
+ parameters. (#285)
719
+
720
+ - ``Otto::Utils.routing_path(env)`` returns the normalized path the router
721
+ matches, so middleware can judge a request by the same path the router
722
+ dispatches. ``include_mount: true`` includes ``SCRIPT_NAME``. See
723
+ ``docs/guides/routing.md``. (#288)
724
+
725
+ - ``require 'otto/testing'`` adds test support for any test framework.
726
+ ``Otto::Testing.reset!`` clears Otto's process-global forwarding state
727
+ between tests. ``Otto::Testing.env_for`` and ``resolve_client_ip!`` build a
728
+ Rack env whose ``otto.client_ip`` and ``otto.ip_match`` are resolved by
729
+ ``IPPrivacyMiddleware``. See ``docs/guides/testing-guide.md``. (#287)
730
+
731
+ - ``Otto::Security::Config#trusted_proxy_mode`` returns ``:filter``,
732
+ ``:depth``, ``:none``, or nil. (#148)
733
+
734
+ Changed
735
+ -------
736
+
737
+ - A ``referrer-policy`` value set through ``security_headers`` is now
738
+ validated like ``referrer_policy``. An unknown token or a comma-separated
739
+ fallback list raises ``ArgumentError`` at configuration time, and the header
740
+ can no longer be removed from ``security_headers``. (#281)
741
+
742
+ - Trusted-proxy state moved into a private
743
+ ``Otto::Security::TrustedProxyConfig``, and
744
+ ``Security::Configurator#configure`` now takes ``**options``. Public
745
+ methods, accepted keys, and behavior are unchanged. (#148)
746
+
747
+ - The forwarding-family conflict error and the warning for a hand-set
748
+ ``otto.client_ip`` now name the ``Otto::Testing`` helper that addresses
749
+ each. ``Otto::Security::Config.reset_rack_forwarding_family_for_testing!``
750
+ remains for existing RSpec callers. (#287)
751
+
752
+ Fixed
753
+ -----
754
+
755
+ - Requests whose ``PATH_INFO`` contains a malformed percent-escape (``%zz``)
756
+ or a raw invalid byte are now routed instead of answering 500. (#288)
757
+
758
+ - The general rate-limit throttle now skips internal paths by the path the
759
+ router dispatches, so ``/%5Fmcp`` is skipped like ``/_mcp``. (#288)
760
+
761
+ - ``Otto::Privacy::Config#profile=`` now sets both ``disabled`` and
762
+ ``mask_private_ips`` for every profile. Switching to ``:audit`` previously
763
+ left ``mask_private_ips`` unchanged, so a later ``enable!`` could restore
764
+ ``:anonymous`` instead of ``:masked``. (#286)
765
+
766
+ - CSP violation reports now reach the receiver when Otto is mounted under a
767
+ sub-path. The receiver matches ``csp_report_uri`` against ``SCRIPT_NAME`` +
768
+ ``PATH_INFO``, so configure the site-absolute path including the mount
769
+ prefix, such as ``/api/csp-report`` under ``map '/api'``. A mount-relative
770
+ value no longer matches. Trailing-slash and percent-encoded spellings of
771
+ the report path are also matched. (#289)
772
+
773
+ Security
774
+ --------
775
+
776
+ - JSON request bodies can no longer override path captures, query
777
+ parameters, or form fields in Logic class parameters; JSON keys now merge
778
+ below them. JSON bodies are no longer parsed for ``GET`` or ``HEAD``
779
+ requests. Before upgrading, check Logic classes that read a JSON body on
780
+ ``GET`` or expect a JSON key to replace a query or path value. (#285)
781
+
782
+ Documentation
783
+ -------------
784
+
785
+ - ``docs/guides/routing.md`` covers matching request paths in middleware,
786
+ including apps mounted under a sub-path. ``docs/guides/testing-guide.md``
787
+ covers ``Otto::Testing`` and Referrer-Policy configuration. (#281, #287,
788
+ #288)
789
+
790
+ AI Assistance
791
+ -------------
792
+
793
+ - The ``TrustedProxyConfig`` refactor was implemented with AI assistance and
794
+ checked against the previous release by a differential run of 1,620
795
+ trusted-proxy operation sequences and 29 ``configure`` calls, with no
796
+ difference in outcome. (#148)
797
+
798
+ - ``Otto::Testing`` helpers, specs, and guide updates were written with AI
799
+ assistance. The reset was also exercised without RSpec, under Tryouts and
800
+ Minitest. (#287)
801
+
10
802
  .. _changelog-2.11.0:
11
803
 
12
804
  2.11.0 — 2026-09-12