otto 2.12.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.
- checksums.yaml +4 -4
- data/.github/workflows/ci.yml +1 -1
- data/.github/workflows/claude-code-review.yml +1 -1
- data/.github/workflows/claude.yml +1 -1
- data/.github/workflows/code-smells.yml +2 -2
- data/.github/workflows/release-gem.yml +1 -1
- data/.github/workflows/ruby-lint.yml +1 -1
- data/.github/workflows/yardoc.yml +1 -1
- data/AGENTS.md +4 -2
- data/CHANGELOG.rst +692 -0
- data/Gemfile +1 -0
- data/Gemfile.lock +6 -1
- data/docs/README.md +4 -0
- data/docs/audits/2026-09-28-v2.12.0-code-audit.md +732 -0
- data/docs/audits/README.md +63 -0
- data/docs/guides/authentication.md +329 -0
- data/docs/guides/forwarded-authority.md +80 -4
- data/docs/guides/mcp.md +40 -4
- data/docs/guides/privacy.md +23 -2
- data/docs/guides/routing.md +8 -4
- data/docs/guides/testing-guide.md +31 -3
- data/docs/migrating/v2.3.0.md +13 -7
- data/docs/reference/authentication.md +70 -22
- data/examples/lambda_handlers/README.md +4 -4
- data/examples/lambda_handlers/handlers.rb +4 -5
- data/examples/lambda_handlers/routes +2 -2
- data/examples/mcp_demo/README.md +65 -27
- data/examples/mcp_demo/app.rb +8 -5
- data/examples/mcp_demo/config.ru +50 -3
- data/examples/mcp_demo/routes +10 -6
- data/examples/security_features/README.md +2 -2
- data/lib/otto/caddy_tls/server.rb +8 -4
- data/lib/otto/core/option_hash.rb +124 -0
- data/lib/otto/core/redacted_inspect.rb +149 -0
- data/lib/otto/core/router.rb +41 -14
- data/lib/otto/core.rb +2 -0
- data/lib/otto/env_keys.rb +30 -7
- data/lib/otto/logging_helpers.rb +1 -1
- data/lib/otto/mcp/auth/token.rb +12 -1
- data/lib/otto/mcp/protocol.rb +3 -3
- data/lib/otto/mcp/registry.rb +28 -2
- data/lib/otto/mcp/route_parser.rb +20 -8
- data/lib/otto/mcp/server.rb +17 -9
- data/lib/otto/privacy/config.rb +12 -1
- data/lib/otto/privacy/ip_privacy.rb +109 -3
- data/lib/otto/privacy/redacted_fingerprint.rb +8 -10
- data/lib/otto/request.rb +34 -0
- data/lib/otto/route_definition.rb +3 -2
- data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
- data/lib/otto/security/config.rb +358 -46
- data/lib/otto/security/csrf.rb +17 -2
- data/lib/otto/security/csrf_validation.rb +13 -7
- data/lib/otto/security/middleware/csrf_middleware.rb +203 -37
- data/lib/otto/security/middleware/ip_privacy_middleware.rb +127 -38
- data/lib/otto/static.rb +63 -0
- data/lib/otto/utils.rb +105 -28
- data/lib/otto/version.rb +1 -1
- data/lib/otto.rb +37 -9
- metadata +6 -2
data/CHANGELOG.rst
CHANGED
|
@@ -7,6 +7,698 @@ 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
|
+
|
|
10
702
|
.. _changelog-2.12.0:
|
|
11
703
|
|
|
12
704
|
2.12.0 — 2026-09-26
|