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.
- 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/.rubocop_todo.yml +2 -2
- data/AGENTS.md +4 -2
- data/CHANGELOG.rst +792 -0
- data/Gemfile +3 -2
- data/Gemfile.lock +13 -8
- data/README.md +6 -0
- 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 +85 -5
- data/docs/guides/mcp.md +40 -4
- data/docs/guides/privacy.md +28 -2
- data/docs/guides/routing.md +76 -9
- data/docs/guides/testing-guide.md +146 -5
- 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/localhost_guard.rb +6 -6
- data/lib/otto/caddy_tls/server.rb +8 -4
- data/lib/otto/core/configuration.rb +5 -3
- data/lib/otto/core/option_hash.rb +124 -0
- data/lib/otto/core/redacted_inspect.rb +149 -0
- data/lib/otto/core/router.rb +57 -34
- data/lib/otto/core.rb +2 -0
- data/lib/otto/env_keys.rb +30 -6
- 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 +31 -14
- 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/response.rb +5 -2
- data/lib/otto/route.rb +1 -1
- data/lib/otto/route_definition.rb +3 -2
- data/lib/otto/route_handlers/base.rb +1 -1
- data/lib/otto/route_handlers/logic_class.rb +86 -34
- data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
- data/lib/otto/security/config.rb +703 -345
- data/lib/otto/security/configurator.rb +82 -45
- data/lib/otto/security/core.rb +4 -2
- data/lib/otto/security/csp/report_middleware.rb +17 -1
- 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 +129 -42
- data/lib/otto/security/rate_limiter.rb +8 -5
- data/lib/otto/security/trusted_proxy_config.rb +396 -0
- data/lib/otto/static.rb +70 -6
- data/lib/otto/testing.rb +148 -0
- data/lib/otto/utils.rb +166 -40
- data/lib/otto/version.rb +1 -1
- data/lib/otto.rb +44 -11
- metadata +8 -2
data/docs/guides/privacy.md
CHANGED
|
@@ -11,9 +11,18 @@ place the privacy middleware in the common stack first.
|
|
|
11
11
|
With the default `:masked` profile:
|
|
12
12
|
|
|
13
13
|
- public IP addresses are masked by the configured octet precision (one octet
|
|
14
|
-
by default: `203.0.113.9` becomes `203.0.113.0`)
|
|
14
|
+
by default: `203.0.113.9` becomes `203.0.113.0`), in `REMOTE_ADDR` and in
|
|
15
|
+
every header that carries the client address: `X-Forwarded-For`,
|
|
16
|
+
`X-Real-IP`, `X-Client-IP`, the `for=` values in `Forwarded`, and the vendor
|
|
17
|
+
headers in `Otto::Utils::VENDOR_CLIENT_ADDRESS_HEADERS` (such as
|
|
18
|
+
`CF-Connecting-IP`, `True-Client-IP`, `Fastly-Client-IP` and
|
|
19
|
+
`X-Original-Forwarded-For`), which Otto never reads the client IP from;
|
|
15
20
|
- requests from private and loopback addresses are exempt from the privacy
|
|
16
21
|
fingerprint by default, so their IP, user agent, and referer remain unchanged;
|
|
22
|
+
their client-address headers (the same list) are rewritten to the resolved
|
|
23
|
+
client IP, because those headers can still carry a public address (a
|
|
24
|
+
`Forwarded` header whose rewrite Otto cannot verify with Rack's parser is
|
|
25
|
+
deleted);
|
|
17
26
|
- for requests that are masked, user-agent version details are anonymized and
|
|
18
27
|
referer query parameters are removed;
|
|
19
28
|
- original public values are not retained in the Rack environment; and
|
|
@@ -23,6 +32,18 @@ With the default `:masked` profile:
|
|
|
23
32
|
Downstream code should read `req.ip`, `req.masked_ip`, and the documented privacy
|
|
24
33
|
environment keys rather than re-resolving an address from forwarded headers.
|
|
25
34
|
|
|
35
|
+
A request can have no client IP when a trusted proxy wrote a value that is not
|
|
36
|
+
an address (such as `unknown`) where the client belongs. For that request,
|
|
37
|
+
`env['otto.client_ip']` and `req.client_ipaddress` are nil and
|
|
38
|
+
`env['otto.ip_match']` returns false for every range, but `req.ip` still
|
|
39
|
+
returns the connecting peer (`REMOTE_ADDR`, which is the proxy). That is
|
|
40
|
+
deliberate: rate limiters key on `req.ip`, and rack-attack skips a throttle
|
|
41
|
+
whose discriminator is nil, so a nil `req.ip` would exempt those requests from
|
|
42
|
+
rate limiting. Do not use `req.ip` for access decisions; use
|
|
43
|
+
`env['otto.ip_match']`. See
|
|
44
|
+
[Forwarded host authority](forwarded-authority.md#how-enumerated-proxy-trust-resolves-the-client-ip)
|
|
45
|
+
for when a request has no client IP.
|
|
46
|
+
|
|
26
47
|
These profiles are technical data-minimization controls, not a compliance
|
|
27
48
|
certification. Whether a deployment meets GDPR, CCPA, or another legal regime
|
|
28
49
|
also depends on its purposes, notices, retention, access controls, vendors, and
|
|
@@ -81,7 +102,7 @@ Common values are also available in the Rack environment:
|
|
|
81
102
|
|
|
82
103
|
| Value | Environment key | Contract |
|
|
83
104
|
| --- | --- | --- |
|
|
84
|
-
| Canonical client IP | `otto.client_ip` | Masked IP when masking applies; resolved full IP under `:audit` or for an exempt private/loopback request. |
|
|
105
|
+
| Canonical client IP | `otto.client_ip` | Masked IP when masking applies; resolved full IP under `:audit` or for an exempt private/loopback request; nil when no client IP resolves. |
|
|
85
106
|
| Precise CIDR verdict | `otto.ip_match` | Callable that checks the resolved full IP against CIDRs and returns only `true` or `false`. |
|
|
86
107
|
| Masked IP | `otto.privacy.masked_ip` | Set when the request runs through the privacy fingerprint; absent for exempt or `:audit` requests. |
|
|
87
108
|
| Rotating IP hash | `otto.privacy.hashed_ip` | Correlation value computed with Otto's rotating key; absent for exempt or `:audit` requests. |
|
|
@@ -154,6 +175,11 @@ the closure.
|
|
|
154
175
|
allowed = req.env.fetch('otto.ip_match').call(['192.0.2.0/24', '2001:db8::/32'])
|
|
155
176
|
```
|
|
156
177
|
|
|
178
|
+
In tests, build the env with `Otto::Testing.env_for` rather than writing
|
|
179
|
+
`otto.client_ip` by hand; a hand-written value leaves `otto.ip_match` denying
|
|
180
|
+
every range. See
|
|
181
|
+
[Testing Otto applications](testing-guide.md#hand-a-harness-a-resolved-client-ip).
|
|
182
|
+
|
|
157
183
|
## Middleware placement
|
|
158
184
|
|
|
159
185
|
When building a larger Rack stack, put privacy before components that log or
|
data/docs/guides/routing.md
CHANGED
|
@@ -142,11 +142,31 @@ GET /products/:id Products::Show
|
|
|
142
142
|
|
|
143
143
|
A handler can read `req.params[:id]` or a Logic class can read `params[:id]`.
|
|
144
144
|
Request query and body parameters are merged according to the handler's request
|
|
145
|
-
contract.
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
145
|
+
contract. Path captures are merged on top, so a caller cannot replace the value
|
|
146
|
+
the router matched by repeating the key in the query string or body. Between
|
|
147
|
+
the query string and a form body, Rack's own order applies (the form body
|
|
148
|
+
wins). For Logic classes a JSON body sits below all of those.
|
|
149
|
+
|
|
150
|
+
A Logic class that must not confuse a path value with a caller-supplied one
|
|
151
|
+
can take the captures separately by declaring a `route_params:` keyword:
|
|
152
|
+
|
|
153
|
+
```ruby
|
|
154
|
+
class Receipts::Show
|
|
155
|
+
def initialize(strategy_result, params, locale, route_params: {})
|
|
156
|
+
@identifier = route_params[:identifier] # only ever the path value
|
|
157
|
+
@params = params
|
|
158
|
+
end
|
|
159
|
+
end
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The keyword is optional; the three-argument constructor keeps working. The same
|
|
163
|
+
values remain in `params` for classes that do not declare it.
|
|
164
|
+
|
|
165
|
+
JSON bodies are parsed for Logic-class parameters when the request method
|
|
166
|
+
carries a body (never `GET` or `HEAD`), the content type is JSON, and the body
|
|
167
|
+
is a JSON object. A valid non-object JSON body is ignored. Malformed JSON is
|
|
168
|
+
logged and the Logic class still runs with its other parameters; perform
|
|
169
|
+
application validation when malformed JSON must return a client error.
|
|
150
170
|
|
|
151
171
|
## Security options in routes
|
|
152
172
|
|
|
@@ -172,6 +192,10 @@ the result is still inside that root and is a regular, readable file owned by
|
|
|
172
192
|
the process user or group. Anything else, including a symlink that points
|
|
173
193
|
outside the root, is treated as not found.
|
|
174
194
|
|
|
195
|
+
Both answer `GET` and `HEAD` requests. A `HEAD` response carries the headers a
|
|
196
|
+
`GET` would get, including `content-length`, and an empty body. Requests with
|
|
197
|
+
any other method skip the static stages.
|
|
198
|
+
|
|
175
199
|
### Implicit public directory
|
|
176
200
|
|
|
177
201
|
Passing `public:` serves every file under that directory at its relative path.
|
|
@@ -212,10 +236,10 @@ otto.mount_static('/', root: 'public/root-files') # favicon.ico, robots.txt
|
|
|
212
236
|
directory. Registering the same prefix twice on one instance raises
|
|
213
237
|
`ArgumentError`; different Otto instances are fully independent.
|
|
214
238
|
- Requests are matched on the decoded, trailing-slash-stripped path, the same
|
|
215
|
-
normalization every other dispatch stage uses. Only `GET`
|
|
216
|
-
prefix itself is not (mounts serve files, not directory
|
|
217
|
-
request for a file the root does not contain falls through
|
|
218
|
-
dispatch stage.
|
|
239
|
+
normalization every other dispatch stage uses. Only `GET` and `HEAD` are
|
|
240
|
+
served, the prefix itself is not (mounts serve files, not directory
|
|
241
|
+
listings), and a request for a file the root does not contain falls through
|
|
242
|
+
to the next dispatch stage.
|
|
219
243
|
- `mount_static` must be called before the first request. After configuration
|
|
220
244
|
freezing it raises `FrozenError`, and `otto.static_mounts` is a frozen,
|
|
221
245
|
read-only table.
|
|
@@ -245,6 +269,49 @@ files outside the public directory should replace it with `mount_static` and
|
|
|
245
269
|
an explicit root. There is no compatibility shim: calling the removed method
|
|
246
270
|
raises `NoMethodError` at boot.
|
|
247
271
|
|
|
272
|
+
## Matching request paths before the router
|
|
273
|
+
|
|
274
|
+
The router does not match raw `PATH_INFO`. It percent-decodes it, scrubs
|
|
275
|
+
invalid UTF-8, and strips one trailing slash, so `GET /%63olonel/` reaches the
|
|
276
|
+
`/colonel` route. Middleware that decides on a request by its path (an access
|
|
277
|
+
guard, a throttle, a session skip) must compare the same value. Otherwise a
|
|
278
|
+
request can match a route without matching the guard in front of it, which
|
|
279
|
+
on an access guard is a bypass.
|
|
280
|
+
|
|
281
|
+
`Otto::Utils.routing_path(env)` returns that value. The router gets its path
|
|
282
|
+
from the same method, so the two cannot drift:
|
|
283
|
+
|
|
284
|
+
```ruby
|
|
285
|
+
class AdminGuard
|
|
286
|
+
ADMIN = Otto::Utils.normalize_path('/colonel')
|
|
287
|
+
|
|
288
|
+
def initialize(app)
|
|
289
|
+
@app = app
|
|
290
|
+
end
|
|
291
|
+
|
|
292
|
+
def call(env)
|
|
293
|
+
path = Otto::Utils.routing_path(env)
|
|
294
|
+
admin_path = path == ADMIN || path.start_with?("#{ADMIN}/")
|
|
295
|
+
return [404, {}, []] if admin_path && !allowed?(env) # allowed? is yours
|
|
296
|
+
|
|
297
|
+
@app.call(env)
|
|
298
|
+
end
|
|
299
|
+
end
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
The result is mount-relative. When the app is mounted under a sub-path
|
|
303
|
+
(`map '/api' { run otto }`), Rack moves the prefix into `SCRIPT_NAME` and the
|
|
304
|
+
router sees only the rest. Compare that form against paths as written in the
|
|
305
|
+
routes file. For middleware shared by several mounted apps and configured
|
|
306
|
+
with external URLs, pass `include_mount: true` to get `SCRIPT_NAME` and
|
|
307
|
+
`PATH_INFO` joined and normalized as one path: inside an app mounted at
|
|
308
|
+
`/api/v2`, the router's `/status` is `/api/v2/status`, and matching the
|
|
309
|
+
mount-relative form would also match every other app's `/status`.
|
|
310
|
+
|
|
311
|
+
The value uses `normalize_path` conventions: root is `''`, and a configured
|
|
312
|
+
path must go through `Otto::Utils.normalize_path` before an exact comparison.
|
|
313
|
+
A malformed escape such as `%zz` is kept as written; the method never raises.
|
|
314
|
+
|
|
248
315
|
## Fallback 404 and 500 responses
|
|
249
316
|
|
|
250
317
|
A `GET /404` or `GET /500` route in the routes file handles misses and
|
|
@@ -41,6 +41,7 @@ require 'rack/mock'
|
|
|
41
41
|
require 'rspec'
|
|
42
42
|
require 'tempfile'
|
|
43
43
|
require 'otto'
|
|
44
|
+
require 'otto/testing'
|
|
44
45
|
|
|
45
46
|
module OttoAppSpecHelpers
|
|
46
47
|
def rack_env(path = '/', method: 'GET', headers: {}, params: {})
|
|
@@ -69,6 +70,10 @@ end
|
|
|
69
70
|
RSpec.configure do |config|
|
|
70
71
|
config.include OttoAppSpecHelpers
|
|
71
72
|
|
|
73
|
+
config.before do
|
|
74
|
+
Otto::Testing.reset!
|
|
75
|
+
end
|
|
76
|
+
|
|
72
77
|
config.after do
|
|
73
78
|
Array(@route_files).each(&:unlink)
|
|
74
79
|
end
|
|
@@ -79,6 +84,46 @@ Within Otto itself, use the existing helpers in
|
|
|
79
84
|
[`spec/support/test_helpers.rb`](../../spec/support/test_helpers.rb) instead of
|
|
80
85
|
copying this application-level helper.
|
|
81
86
|
|
|
87
|
+
## Reset Otto's process-global state between tests
|
|
88
|
+
|
|
89
|
+
`require 'otto'` does not load `otto/testing`. Require it from the test helper;
|
|
90
|
+
it does not depend on RSpec.
|
|
91
|
+
|
|
92
|
+
`Otto.new` pins `Rack::Request.forwarded_priority` from `trusted_proxy_header`
|
|
93
|
+
whenever an application configures proxy trust or names a header. Rack keeps one
|
|
94
|
+
priority per process, so Otto records the family and raises `ArgumentError`
|
|
95
|
+
when a later application in the same process chooses a different one. A suite
|
|
96
|
+
that builds one application with `trusted_proxy_header: 'Forwarded'` and
|
|
97
|
+
another with `trusted_proxies:` fails or passes depending on test order unless
|
|
98
|
+
the record is cleared between tests. `Otto::Testing.reset!` clears it and
|
|
99
|
+
restores Rack's priority to the value Otto saw at load time.
|
|
100
|
+
|
|
101
|
+
Call it before every test:
|
|
102
|
+
|
|
103
|
+
```ruby
|
|
104
|
+
# RSpec
|
|
105
|
+
RSpec.configure { |config| config.before { Otto::Testing.reset! } }
|
|
106
|
+
|
|
107
|
+
# Minitest
|
|
108
|
+
class Minitest::Test
|
|
109
|
+
def before_setup
|
|
110
|
+
super
|
|
111
|
+
Otto::Testing.reset!
|
|
112
|
+
end
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
# Tryouts: at the start of each test case that builds an Otto app
|
|
116
|
+
## a depth-mode app reading Forwarded
|
|
117
|
+
Otto::Testing.reset!
|
|
118
|
+
Otto.new(nil, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Tryouts runs a file's setup section once, before all of its test cases, so a
|
|
122
|
+
reset placed there does not separate the cases from each other.
|
|
123
|
+
|
|
124
|
+
`Otto::Security::Config.reset_rack_forwarding_family_for_testing!` does the
|
|
125
|
+
same but raises unless RSpec is loaded. It remains for existing callers.
|
|
126
|
+
|
|
82
127
|
## Test Logic classes as plain Ruby objects
|
|
83
128
|
|
|
84
129
|
Logic classes receive an authentication result, merged parameters, and a locale.
|
|
@@ -260,7 +305,9 @@ Otto's parser. Send an `application/json` body through a real Otto instance or
|
|
|
260
305
|
|
|
261
306
|
Current behavior to cover explicitly:
|
|
262
307
|
|
|
263
|
-
- a JSON object is merged into the Logic parameters
|
|
308
|
+
- a JSON object is merged into the Logic parameters below path captures, the
|
|
309
|
+
query string and any form body, which all win over it;
|
|
310
|
+
- a JSON body on `GET` or `HEAD` is ignored;
|
|
264
311
|
- a valid non-object JSON value is ignored;
|
|
265
312
|
- malformed JSON is logged and the Logic class continues with other parameters;
|
|
266
313
|
- non-JSON bodies are not parsed by the Logic handler.
|
|
@@ -310,11 +357,39 @@ Valid request tokens must come from `config.generate_csrf_token(session_id)` and
|
|
|
310
357
|
must use the matching session ID; an arbitrary value copied into the session and
|
|
311
358
|
header is not a valid token.
|
|
312
359
|
|
|
360
|
+
When the session provides no binding (no session middleware, or a session with
|
|
361
|
+
no id and no stored binding), the binding lives in a cookie that
|
|
362
|
+
`CSRFMiddleware` sets only on responses to safe requests, HTML or not, whose
|
|
363
|
+
binding the client does not already send: one Otto minted, or one stored under
|
|
364
|
+
`csrf_session_key`. A session id the request already had, or a binding read
|
|
365
|
+
from a cookie, is never copied into it, so a test behind a session middleware
|
|
366
|
+
that wraps `CSRFMiddleware` carries the store's cookie, not `_otto_session`. A
|
|
367
|
+
store added with `otto.use` before CSRF protection is enabled runs inside
|
|
368
|
+
`CSRFMiddleware`; there the binding cookie carries the id the store creates
|
|
369
|
+
when the middleware mints a binding. An unsafe request never creates a
|
|
370
|
+
binding, so a test that posts without one gets `403` and no cookie, and an
|
|
371
|
+
HTML response to it carries no token.
|
|
372
|
+
`spec/otto/security/csrf_rack_session_spec.rb` runs these flows behind
|
|
373
|
+
rack-session's `Pool` and `Cookie` stores.
|
|
374
|
+
`Otto::Security::Config#csrf_binding_cookie_name`
|
|
375
|
+
returns its name: `__Host-otto_session` when Rack reports the request as HTTPS
|
|
376
|
+
(`request.scheme == 'https'`), set with `Secure`, `Path=/` and no `Domain`, and
|
|
377
|
+
`_otto_session` otherwise. On HTTPS requests Otto reads only the `__Host-`
|
|
378
|
+
cookie; `_otto_session`, `session_id` and `_session_id` cookies are ignored
|
|
379
|
+
there, because a sibling subdomain or a network attacker could plant them and
|
|
380
|
+
choose the binding. A test that drives a form over HTTPS must carry
|
|
381
|
+
`__Host-otto_session` from the response to the next request.
|
|
382
|
+
|
|
313
383
|
Use these maintained specs as executable examples:
|
|
314
384
|
|
|
315
|
-
- [`spec/security_csrf_spec.rb`](../../spec/security_csrf_spec.rb)
|
|
316
|
-
- [`spec/otto/security/csrf_enforcement_wrapper_spec.rb`](../../spec/otto/security/csrf_enforcement_wrapper_spec.rb)
|
|
317
|
-
- [`spec/otto/security/csrf_validation_spec.rb`](../../spec/otto/security/csrf_validation_spec.rb)
|
|
385
|
+
- [`spec/security_csrf_spec.rb`](../../spec/security_csrf_spec.rb): response injection.
|
|
386
|
+
- [`spec/otto/security/csrf_enforcement_wrapper_spec.rb`](../../spec/otto/security/csrf_enforcement_wrapper_spec.rb): safe methods, unsafe methods, valid tokens, and `csrf=exempt`.
|
|
387
|
+
- [`spec/otto/security/csrf_validation_spec.rb`](../../spec/otto/security/csrf_validation_spec.rb): token and session extraction.
|
|
388
|
+
- [`spec/otto/security/csrf_binding_cookie_spec.rb`](../../spec/otto/security/csrf_binding_cookie_spec.rb): the binding cookie on HTTP and HTTPS.
|
|
389
|
+
- [`spec/otto/security/csrf_rack_session_spec.rb`](../../spec/otto/security/csrf_rack_session_spec.rb): the binding behind rack-session's `Pool` and `Cookie` stores.
|
|
390
|
+
- [`spec/otto/security/csrf_cache_control_spec.rb`](../../spec/otto/security/csrf_cache_control_spec.rb): `Cache-Control: private, stale-if-error=0` on responses that carry the binding cookie or an injected token.
|
|
391
|
+
- [`spec/otto/security/csrf_nested_middleware_spec.rb`](../../spec/otto/security/csrf_nested_middleware_spec.rb): one binding cookie when `CSRFMiddleware` runs more than once, including nested Ottos.
|
|
392
|
+
- [`spec/otto/security/csrf_middleware_rack_spec.rb`](../../spec/otto/security/csrf_middleware_rack_spec.rb): `CSRFMiddleware` under `Rack::Lint`, including bodies it may not read (files from `public:` and streams), 204, 304 and HEAD responses, and a binding that is not a hex token.
|
|
318
393
|
|
|
319
394
|
## Test IP privacy with the application configuration
|
|
320
395
|
|
|
@@ -343,6 +418,52 @@ octets, or set `mask_private_ips = true` to include private and localhost
|
|
|
343
418
|
addresses. For application-facing tests, prefer a real Otto instance configured
|
|
344
419
|
through `configure_ip_privacy`.
|
|
345
420
|
|
|
421
|
+
### Hand a harness a resolved client IP
|
|
422
|
+
|
|
423
|
+
Code that runs behind `IPPrivacyMiddleware` reads `env['otto.client_ip']` and,
|
|
424
|
+
for access decisions, `env['otto.ip_match']`. Do not write `otto.client_ip` by
|
|
425
|
+
hand. The middleware treats its presence as a sign that it already ran, so it
|
|
426
|
+
never builds `otto.ip_match` from the full address. Instead it installs a check
|
|
427
|
+
that returns `false` for every range and logs a warning. Allowlist tests then
|
|
428
|
+
deny, and when the application uses CIDR proxy trust it also treats the peer as
|
|
429
|
+
untrusted.
|
|
430
|
+
|
|
431
|
+
`Otto::Testing.env_for` runs the middleware over a Rack env for a request
|
|
432
|
+
arriving directly from `client_ip`, so both keys come from one resolution:
|
|
433
|
+
|
|
434
|
+
```ruby
|
|
435
|
+
env = Otto::Testing.env_for('/admin', client_ip: '203.0.113.9',
|
|
436
|
+
security_config: otto.security_config)
|
|
437
|
+
|
|
438
|
+
env['otto.client_ip'] # => "203.0.113.0" (masked)
|
|
439
|
+
env['otto.ip_match'].call(['203.0.113.9/32']) # => true
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
`security_config:` is required. The application's own middleware keeps what
|
|
443
|
+
this resolution produced, so pass `otto.security_config` to get the masking and
|
|
444
|
+
proxy trust of the application under test; `nil` means an unconfigured
|
|
445
|
+
middleware (public addresses masked, no proxy trust). `client_ip: nil` builds a
|
|
446
|
+
request with no resolvable client IP: `env['otto.client_ip']` is `nil` and
|
|
447
|
+
`otto.ip_match` denies every range. Other keywords and String env keys go to
|
|
448
|
+
`Rack::MockRequest.env_for`.
|
|
449
|
+
|
|
450
|
+
`env_for` models a direct request, so it raises `ArgumentError` when given
|
|
451
|
+
`X-Forwarded-For`, `X-Real-IP`, `X-Client-IP` or `Forwarded`: under a
|
|
452
|
+
configuration that trusts the peer, those would resolve an address other than
|
|
453
|
+
`client_ip`. For a request relayed by a proxy, build the env with `REMOTE_ADDR`
|
|
454
|
+
and the forwarded headers, then resolve it under the application's
|
|
455
|
+
configuration:
|
|
456
|
+
|
|
457
|
+
```ruby
|
|
458
|
+
env = Rack::MockRequest.env_for('/admin', 'REMOTE_ADDR' => '10.0.0.5',
|
|
459
|
+
'HTTP_X_FORWARDED_FOR' => '203.0.113.9')
|
|
460
|
+
Otto::Testing.resolve_client_ip!(env, otto.security_config)
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
Resolved under a different configuration, the proxy can become the client and
|
|
464
|
+
the application keeps that answer. `resolve_client_ip!` raises on an env that
|
|
465
|
+
already carries `otto.client_ip` or `otto.ip_match` for the same reason.
|
|
466
|
+
|
|
346
467
|
See the [privacy guide](privacy.md) and the maintained privacy specs:
|
|
347
468
|
|
|
348
469
|
- [`spec/otto/ip_privacy_spec.rb`](../../spec/otto/ip_privacy_spec.rb)
|
|
@@ -369,13 +490,33 @@ Otto's default route responses include:
|
|
|
369
490
|
- `x-xss-protection: 1; mode=block`
|
|
370
491
|
- `referrer-policy: strict-origin-when-cross-origin`
|
|
371
492
|
|
|
493
|
+
Configure exactly one W3C policy token when constructing the application; Otto
|
|
494
|
+
applies it to routed responses, static files, and authentication failures:
|
|
495
|
+
|
|
496
|
+
```ruby
|
|
497
|
+
otto = Otto.new('routes.txt', referrer_policy: 'no-referrer')
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
The same setting is available as
|
|
501
|
+
`otto.security_config.referrer_policy = 'no-referrer'` and
|
|
502
|
+
`otto.security.referrer_policy = 'no-referrer'` during boot, before the first
|
|
503
|
+
request freezes configuration. An unknown policy token raises `ArgumentError`
|
|
504
|
+
at configuration time. Comma-separated policy fallback lists are not accepted.
|
|
505
|
+
Existing applications that pass `referrer-policy`
|
|
506
|
+
through `security_headers` remain supported and receive the same validation.
|
|
507
|
+
A route handler that explicitly sets `res['referrer-policy']` keeps its
|
|
508
|
+
response-specific value.
|
|
509
|
+
|
|
372
510
|
`x-frame-options` is not a default header. Call
|
|
373
511
|
`otto.enable_frame_protection!` before the first request if a test should expect
|
|
374
512
|
`x-frame-options: SAMEORIGIN`.
|
|
375
513
|
|
|
376
514
|
Test security behavior at the narrowest useful level, but do not require every
|
|
377
515
|
unrelated unit test to repeat header and privacy assertions. Keep those checks in
|
|
378
|
-
focused middleware or request specs.
|
|
516
|
+
focused middleware or request specs. When testing a custom referrer policy,
|
|
517
|
+
exercise a complete response from each response family the application uses
|
|
518
|
+
(for example, routed HTML, `Rack::Files`, and an authentication failure), rather
|
|
519
|
+
than asserting only against `security_config.security_headers`.
|
|
379
520
|
|
|
380
521
|
## Maintained examples by task
|
|
381
522
|
|
data/docs/migrating/v2.3.0.md
CHANGED
|
@@ -128,7 +128,7 @@ and the `ConfigureTrustedProxy` monkeypatch
|
|
|
128
128
|
|
|
129
129
|
| Use… | When… |
|
|
130
130
|
|------|-------|
|
|
131
|
-
| **CIDR-walk** (`add_trusted_proxy`, the default) | Your proxy IPs are **enumerable** — a fixed set of load balancers / reverse proxies you can list as IPs or CIDR ranges.
|
|
131
|
+
| **CIDR-walk** (`add_trusted_proxy`, the default) | Your proxy IPs are **enumerable** — a fixed set of load balancers / reverse proxies you can list as IPs or CIDR ranges. Which forwarded entry becomes the client changed in the first release after 2.12.0; see [How enumerated proxy trust resolves the client IP](../guides/forwarded-authority.md#how-enumerated-proxy-trust-resolves-the-client-ip). |
|
|
132
132
|
| **Depth** (`trusted_proxy_depth = N`) | Your proxy tier is **non-enumerable** — Fly, cloud load balancers, dynamic/autoscaling reverse proxies whose addresses you cannot pin down. You instead know the **fixed number of hops** between the client and your app. |
|
|
133
133
|
|
|
134
134
|
The two modes are **mutually exclusive**. Configuring both `trusted_proxies` and
|
|
@@ -184,10 +184,15 @@ counting, so an attacker cannot pad the header with junk/invalid entries to shif
|
|
|
184
184
|
the index. Only the single selected entry is validated.
|
|
185
185
|
|
|
186
186
|
**Short-chain and invalid-target fallback.** If the chain is shorter than
|
|
187
|
-
`N + 1` (a request that may have **bypassed** the proxy tier),
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
187
|
+
`N + 1` (a request that may have **bypassed** the proxy tier), the resolver
|
|
188
|
+
returns `REMOTE_ADDR` rather than a spoofable forwarded value. This is
|
|
189
|
+
intentionally **stricter than Express**, which returns the leftmost (most
|
|
190
|
+
spoofable) forwarded entry in that case. If the selected entry is not a valid
|
|
191
|
+
IP, releases through 2.12.0 also returned `REMOTE_ADDR`; starting with the first
|
|
192
|
+
release after 2.12.0 the request has no client IP instead (`otto.ip_match`
|
|
193
|
+
denies every range; see
|
|
194
|
+
[How enumerated proxy trust resolves the client IP](../guides/forwarded-authority.md#how-enumerated-proxy-trust-resolves-the-client-ip)
|
|
195
|
+
for the rest of that state).
|
|
191
196
|
|
|
192
197
|
**Single-value headers are never consulted.** `X-Real-IP` and `X-Client-IP`
|
|
193
198
|
cannot express a hop chain, so depth mode ignores them (CIDR-walk still consults
|
|
@@ -246,8 +251,9 @@ Otto.new(routes, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
|
|
|
246
251
|
`for=` parameter is read case-insensitively and unquoted. Quoted IPv6 with a
|
|
247
252
|
port (`for="[2001:db8::1]:443"`) resolves to `2001:db8::1`. Obfuscated
|
|
248
253
|
(`for=_hidden`) and `for=unknown` identifiers still occupy a hop position but
|
|
249
|
-
are not valid IPs, so if one is the selected hop the
|
|
250
|
-
|
|
254
|
+
are not valid IPs, so if one is the selected hop the request has no client
|
|
255
|
+
IP (first release after 2.12.0; 2.12.0 and earlier fell back to
|
|
256
|
+
`REMOTE_ADDR`). Multiple `Forwarded` headers (joined by Rack into one
|
|
251
257
|
comma-separated value) are handled.
|
|
252
258
|
- **Raw position counting is preserved** in all three modes: elements are never
|
|
253
259
|
dropped before counting (an element without a `for=` still counts as a hop),
|
|
@@ -28,10 +28,24 @@ GET /api/data DataLogic#show auth=session,apikey,oauth
|
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
**Execution Flow:**
|
|
31
|
-
1.
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
31
|
+
1. Unknown strategy names fail the request with 401 before any strategy runs
|
|
32
|
+
(strict mode)
|
|
33
|
+
2. Strategies execute left-to-right in order
|
|
34
|
+
3. The first **authenticated** success (a result with a user) wins; the
|
|
35
|
+
remaining strategies are not executed
|
|
36
|
+
4. An **anonymous** success (a result without a user, e.g. from `noauth`)
|
|
37
|
+
does not win yet. It is held as a fallback and the chain continues; only
|
|
38
|
+
the first anonymous success is held
|
|
39
|
+
5. A plain failure is recorded and the next strategy runs
|
|
40
|
+
6. A terminal failure (`AuthFailure` with `terminal: true`, e.g. an API key
|
|
41
|
+
that was presented and rejected) halts the chain, and a held anonymous
|
|
42
|
+
fallback does not rescue the request
|
|
43
|
+
7. If the chain completes without an authenticated success or a terminal
|
|
44
|
+
failure, the held anonymous fallback wins
|
|
45
|
+
8. Otherwise the request fails: 403 if any strategy returned an
|
|
46
|
+
`AuthorizationFailure`, else 401 when the route is `response=json` or the
|
|
47
|
+
request accepts `application/json`, and a 302 redirect to the login path
|
|
48
|
+
for other requests
|
|
35
49
|
|
|
36
50
|
**Performance Tip:** Put fastest/most-common strategies first (e.g., `auth=session,apikey`)
|
|
37
51
|
|
|
@@ -39,14 +53,22 @@ GET /api/data DataLogic#show auth=session,apikey,oauth
|
|
|
39
53
|
```ruby
|
|
40
54
|
# Route: auth=session,apikey,oauth
|
|
41
55
|
# 1. Tries 'session' strategy
|
|
42
|
-
# 2. If session
|
|
56
|
+
# 2. If session authenticates → call handler (apikey/oauth not executed)
|
|
43
57
|
# 3. If session fails → try 'apikey' strategy
|
|
44
|
-
# 4. If apikey
|
|
58
|
+
# 4. If apikey authenticates → call handler (oauth not executed)
|
|
45
59
|
# 5. If apikey fails → try 'oauth' strategy
|
|
46
|
-
# 6. If oauth
|
|
47
|
-
# 7. If all fail →
|
|
60
|
+
# 6. If oauth authenticates → call handler
|
|
61
|
+
# 7. If all fail → 401, 403 or 302 (Execution Flow, step 8)
|
|
48
62
|
```
|
|
49
63
|
|
|
64
|
+
Declaration order does not let an anonymous strategy win early. On
|
|
65
|
+
`auth=noauth,session`, a request whose session holds a user is
|
|
66
|
+
authenticated by `session`, and `noauth` wins only when `session` fails. On
|
|
67
|
+
`auth=noauth,apikey`, a request that presents an invalid API key is refused:
|
|
68
|
+
the key's terminal failure halts the chain, and the response follows step 8
|
|
69
|
+
(401 when the route is `response=json` or the request accepts
|
|
70
|
+
`application/json`, otherwise a 302 redirect to the login path).
|
|
71
|
+
|
|
50
72
|
## Strategy Pattern Matching
|
|
51
73
|
|
|
52
74
|
- **Exact match**: `'authenticated'` → looks up `auth_config[:auth_strategies]['authenticated']`
|
|
@@ -72,14 +94,25 @@ GET /profile ProfileLogic auth=session
|
|
|
72
94
|
- Use `auth=` for authentication strategies
|
|
73
95
|
- Use `role=` for role-based route access (OR logic for multiple roles)
|
|
74
96
|
- Fast execution (no database queries)
|
|
75
|
-
- Returns 401 (Unauthorized) for authentication failures
|
|
97
|
+
- Returns 401 (Unauthorized) for authentication failures, or a 302 redirect to
|
|
98
|
+
the login path for requests that do not want JSON
|
|
76
99
|
- Returns 403 (Forbidden) for authorization failures
|
|
77
100
|
|
|
78
|
-
**Role Extraction Order
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
101
|
+
**Role Extraction Order** (checked in order; the first source that is set is
|
|
102
|
+
used):
|
|
103
|
+
1. `result.user_roles`, if the result responds to it (`StrategyResult` does
|
|
104
|
+
not define it)
|
|
105
|
+
2. For a Hash user: `result.user[:roles]`, then `result.user['roles']`. A set
|
|
106
|
+
value is used even when it is empty
|
|
107
|
+
3. For any other user object (ORM model, PORO, `Data`/`Struct`):
|
|
108
|
+
`result.user.roles`, stringified; if the user does not respond to `#roles`
|
|
109
|
+
or it yields no roles, `result.user.role`
|
|
110
|
+
4. `result.metadata[:user_roles]` (metadata; `RoleStrategy` puts the session's
|
|
111
|
+
roles here)
|
|
112
|
+
|
|
113
|
+
A user object that is not a Hash and responds to neither `#roles` nor `#role`
|
|
114
|
+
contributes no roles instead of raising `NoMethodError`; the metadata source
|
|
115
|
+
is still checked.
|
|
83
116
|
|
|
84
117
|
### Layer 2: Resource-Level Authorization
|
|
85
118
|
|
|
@@ -264,21 +297,36 @@ end
|
|
|
264
297
|
When a route has authentication requirements:
|
|
265
298
|
|
|
266
299
|
1. Looks up strategies from `auth_config[:auth_strategies]`
|
|
267
|
-
2. Executes `strategy.authenticate(env, requirement)` for each strategy
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
- Sets `env['
|
|
300
|
+
2. Executes `strategy.authenticate(env, requirement)` for each strategy in
|
|
301
|
+
order, until one authenticates or a terminal failure halts the chain
|
|
302
|
+
3. On the winning success (the first authenticated success, or the held
|
|
303
|
+
anonymous fallback once the chain completes; see Execution Flow above):
|
|
304
|
+
- Sets `env['rack.session']` to `result.session` (unless that is `nil` or
|
|
305
|
+
`false`) when env holds no session a middleware installed: the key is
|
|
306
|
+
absent, or it holds the `Otto::Request::DefaultSession` that
|
|
307
|
+
`Otto::Request#session` installs when no session middleware ran. A
|
|
308
|
+
session a middleware installed is never replaced
|
|
309
|
+
- Sets `env['otto.strategy_result']`; the user is
|
|
310
|
+
`env['otto.strategy_result'].user`
|
|
272
311
|
- Checks role requirements (if `role=` specified)
|
|
273
312
|
- Calls wrapped handler
|
|
274
|
-
4. If
|
|
313
|
+
4. If the chain fails (every strategy failed, or a terminal failure halted
|
|
314
|
+
it): Returns 403, 401 or 302, as in Execution Flow step 8
|
|
275
315
|
5. If role check fails: Returns 403
|
|
276
316
|
|
|
277
317
|
## Compatibility Notes
|
|
278
318
|
|
|
279
|
-
- `enable_authentication!`
|
|
319
|
+
- `enable_authentication!` was removed; calling it raises `NoMethodError`.
|
|
320
|
+
`RouteAuthWrapper` wraps every route handler without it
|
|
280
321
|
- AuthenticationMiddleware was removed (architecturally broken - ran before routing)
|
|
281
|
-
- `
|
|
322
|
+
- `env['otto.user']` is not set; read the user from
|
|
323
|
+
`env['otto.strategy_result'].user`
|
|
324
|
+
- `auth=role:admin` is a strategy requirement, not the route-level role check.
|
|
325
|
+
It resolves to a strategy registered under the exact name `role:admin`, or
|
|
326
|
+
else to the one registered as `role` (prefix match). A `RoleStrategy`
|
|
327
|
+
checks `admin` against the session's roles (`user_roles` by default).
|
|
328
|
+
`role=admin` is the separate route-level check (Layer 1) against the
|
|
329
|
+
successful strategy result
|
|
282
330
|
|
|
283
331
|
## Best Practices
|
|
284
332
|
|
|
@@ -73,10 +73,10 @@ class/instance/logic handler does:
|
|
|
73
73
|
Route options apply to lambdas just like any other handler:
|
|
74
74
|
|
|
75
75
|
- `response=json` — serialize the returned Hash as JSON.
|
|
76
|
-
- `csrf=exempt` —
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
76
|
+
- `csrf=exempt` — skip CSRF token validation for the route (the webhook,
|
|
77
|
+
which external callers reach without a browser token). Otto enforces it at
|
|
78
|
+
the handler layer (issue #186), so exempt only routes that are authenticated
|
|
79
|
+
another way.
|
|
80
80
|
- `auth=` / `role=` — authentication and authorization (when `auth_config`
|
|
81
81
|
is configured on the Otto instance).
|
|
82
82
|
|
|
@@ -48,11 +48,10 @@ module LambdaHandlers
|
|
|
48
48
|
{ greeting: "Hello, #{name}!" }
|
|
49
49
|
end
|
|
50
50
|
|
|
51
|
-
# A webhook-style POST handler. The matching route declares `csrf=exempt
|
|
52
|
-
#
|
|
53
|
-
#
|
|
54
|
-
#
|
|
55
|
-
# CSRF only for endpoints authenticated another way (signature header, shared
|
|
51
|
+
# A webhook-style POST handler. The matching route declares `csrf=exempt`
|
|
52
|
+
# so external callers, which cannot present a CSRF token, can reach it.
|
|
53
|
+
# Otto enforces the option at the handler layer (issue #186), so exempt CSRF
|
|
54
|
+
# only for endpoints authenticated another way (signature header, shared
|
|
56
55
|
# secret, etc.).
|
|
57
56
|
WEBHOOK = lambda do |req, _res, _extra|
|
|
58
57
|
# Rewind first: upstream middleware may already have read the input stream.
|
|
@@ -23,6 +23,6 @@ GET /status &status response=json
|
|
|
23
23
|
# Reads a path param, returned as JSON.
|
|
24
24
|
GET /greet/:name &greet response=json
|
|
25
25
|
|
|
26
|
-
# Webhook receiver:
|
|
27
|
-
#
|
|
26
|
+
# Webhook receiver: csrf=exempt skips the CSRF check for this route (enforced
|
|
27
|
+
# since 2.6.0, #186), so authenticate it another way, such as a signature header.
|
|
28
28
|
POST /webhook &webhook csrf=exempt response=json
|