otto 2.11.0 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ci.yml +1 -1
  3. data/.github/workflows/claude-code-review.yml +1 -1
  4. data/.github/workflows/claude.yml +1 -1
  5. data/.github/workflows/code-smells.yml +2 -2
  6. data/.github/workflows/release-gem.yml +1 -1
  7. data/.github/workflows/ruby-lint.yml +1 -1
  8. data/.github/workflows/yardoc.yml +1 -1
  9. data/.rubocop_todo.yml +2 -2
  10. data/AGENTS.md +4 -2
  11. data/CHANGELOG.rst +792 -0
  12. data/Gemfile +3 -2
  13. data/Gemfile.lock +13 -8
  14. data/README.md +6 -0
  15. data/docs/README.md +4 -0
  16. data/docs/audits/2026-09-28-v2.12.0-code-audit.md +732 -0
  17. data/docs/audits/README.md +63 -0
  18. data/docs/guides/authentication.md +329 -0
  19. data/docs/guides/forwarded-authority.md +85 -5
  20. data/docs/guides/mcp.md +40 -4
  21. data/docs/guides/privacy.md +28 -2
  22. data/docs/guides/routing.md +76 -9
  23. data/docs/guides/testing-guide.md +146 -5
  24. data/docs/migrating/v2.3.0.md +13 -7
  25. data/docs/reference/authentication.md +70 -22
  26. data/examples/lambda_handlers/README.md +4 -4
  27. data/examples/lambda_handlers/handlers.rb +4 -5
  28. data/examples/lambda_handlers/routes +2 -2
  29. data/examples/mcp_demo/README.md +65 -27
  30. data/examples/mcp_demo/app.rb +8 -5
  31. data/examples/mcp_demo/config.ru +50 -3
  32. data/examples/mcp_demo/routes +10 -6
  33. data/examples/security_features/README.md +2 -2
  34. data/lib/otto/caddy_tls/localhost_guard.rb +6 -6
  35. data/lib/otto/caddy_tls/server.rb +8 -4
  36. data/lib/otto/core/configuration.rb +5 -3
  37. data/lib/otto/core/option_hash.rb +124 -0
  38. data/lib/otto/core/redacted_inspect.rb +149 -0
  39. data/lib/otto/core/router.rb +57 -34
  40. data/lib/otto/core.rb +2 -0
  41. data/lib/otto/env_keys.rb +30 -6
  42. data/lib/otto/logging_helpers.rb +1 -1
  43. data/lib/otto/mcp/auth/token.rb +12 -1
  44. data/lib/otto/mcp/protocol.rb +3 -3
  45. data/lib/otto/mcp/registry.rb +28 -2
  46. data/lib/otto/mcp/route_parser.rb +20 -8
  47. data/lib/otto/mcp/server.rb +17 -9
  48. data/lib/otto/privacy/config.rb +31 -14
  49. data/lib/otto/privacy/ip_privacy.rb +109 -3
  50. data/lib/otto/privacy/redacted_fingerprint.rb +8 -10
  51. data/lib/otto/request.rb +34 -0
  52. data/lib/otto/response.rb +5 -2
  53. data/lib/otto/route.rb +1 -1
  54. data/lib/otto/route_definition.rb +3 -2
  55. data/lib/otto/route_handlers/base.rb +1 -1
  56. data/lib/otto/route_handlers/logic_class.rb +86 -34
  57. data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
  58. data/lib/otto/security/config.rb +703 -345
  59. data/lib/otto/security/configurator.rb +82 -45
  60. data/lib/otto/security/core.rb +4 -2
  61. data/lib/otto/security/csp/report_middleware.rb +17 -1
  62. data/lib/otto/security/csrf.rb +17 -2
  63. data/lib/otto/security/csrf_validation.rb +13 -7
  64. data/lib/otto/security/middleware/csrf_middleware.rb +203 -37
  65. data/lib/otto/security/middleware/ip_privacy_middleware.rb +129 -42
  66. data/lib/otto/security/rate_limiter.rb +8 -5
  67. data/lib/otto/security/trusted_proxy_config.rb +396 -0
  68. data/lib/otto/static.rb +70 -6
  69. data/lib/otto/testing.rb +148 -0
  70. data/lib/otto/utils.rb +166 -40
  71. data/lib/otto/version.rb +1 -1
  72. data/lib/otto.rb +44 -11
  73. metadata +8 -2
@@ -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
@@ -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. JSON bodies are parsed for Logic-class parameters when the content
146
- type is JSON and the body is a JSON object. A valid non-object JSON body is
147
- ignored. Malformed JSON is logged and the Logic class still runs with its other
148
- parameters; perform application validation when malformed JSON must return a
149
- client error.
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` is served, the
216
- prefix itself is not (mounts serve files, not directory listings), and a
217
- request for a file the root does not contain falls through to the next
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) — response injection.
316
- - [`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`.
317
- - [`spec/otto/security/csrf_validation_spec.rb`](../../spec/otto/security/csrf_validation_spec.rb) — token and session extraction.
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
 
@@ -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. The client is the first address in the forwarded chain that is not itself a trusted proxy. |
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), or the selected
188
- entry is not a valid IP, the resolver returns `REMOTE_ADDR` rather than a
189
- spoofable forwarded value. This is intentionally **stricter than Express**, which
190
- returns the leftmost (most spoofable) forwarded entry in that case.
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 resolver falls back to
250
- `REMOTE_ADDR`. Multiple `Forwarded` headers (joined by Rack into one
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. Strategies execute left-to-right in order
32
- 2. **First success wins** - remaining strategies are not executed
33
- 3. Returns 401 only if **all** strategies fail
34
- 4. Unknown strategies cause immediate 401 (strict mode)
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 succeeds → call handler (apikey/oauth not executed)
56
+ # 2. If session authenticates → call handler (apikey/oauth not executed)
43
57
  # 3. If session fails → try 'apikey' strategy
44
- # 4. If apikey succeeds → call handler (oauth not executed)
58
+ # 4. If apikey authenticates → call handler (oauth not executed)
45
59
  # 5. If apikey fails → try 'oauth' strategy
46
- # 6. If oauth succeeds → call handler
47
- # 7. If all fail → return 401
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
- 1. `result.user_roles` (direct accessor)
80
- 2. `result.user[:roles]` (user hash with symbol key)
81
- 3. `result.user['roles']` (user hash with string key)
82
- 4. `result.metadata[:user_roles]` (metadata)
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
- 3. On first success:
269
- - Sets `env['rack.session']` (if provided)
270
- - Sets `env['otto.strategy_result']`
271
- - Sets `env['otto.user']` (extracted from result)
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 all strategies fail: Returns 401/302
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!` is a no-op kept for API compatibility
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
- - `auth=role:admin` syntax removed in favor of separate `role=admin` option
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` — parsed and exposed on the route definition (intended to mark
77
- the webhook, which external callers reach without a browser token). Note:
78
- `CSRFMiddleware` does not yet consult per-route options, so this option is
79
- currently recorded but not enforced — see issue #186.
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
- # intended to let external callers (which cannot present a CSRF token) reach
53
- # it. Note: CSRFMiddleware does not yet honor per-route csrf=exempt (issue
54
- # #186), so the option is currently advisory. When enforcement lands, exempt
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: marked csrf=exempt (option is parsed/exposed but not yet
27
- # enforced by CSRFMiddleware -- see issue #186).
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