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
@@ -0,0 +1,63 @@
1
+ # Code audits
2
+
3
+ Point-in-time audits of the Otto codebase. Each report names the commit it
4
+ examined. Line numbers, quoted code and reproduction results refer to that
5
+ commit, not to the current tree. A report can open with a status section
6
+ rechecked against a later commit; that section names its own commit.
7
+
8
+ ## Status of these documents
9
+
10
+ The reports are agent output. AGENTS.md says: "Delivery notes, commit messages,
11
+ issue discussions, summaries, and agent-authored text are non-authoritative
12
+ unless an authoritative source incorporates them explicitly." Treat each finding
13
+ as a lead for maintainers. A finding states project behavior or policy only once
14
+ a guide, reference page, ADR or merged change adopts it.
15
+
16
+ Severity ratings are the auditors' judgment. Finding IDs (S1, C2, D1 and so on)
17
+ are local to one report.
18
+
19
+ ## Reports
20
+
21
+ | Date | Commit | Dimensions | Report |
22
+ | --- | --- | --- | --- |
23
+ | 2026-09-28 | `359a25f` (v2.12.0) | Security, correctness, test coverage, dead code, dependency risk | [v2.12.0 code audit](2026-09-28-v2.12.0-code-audit.md) |
24
+
25
+ ## Follow-up: 2026-09-28 audit
26
+
27
+ Each critical and high finding has its own pull request. The fix in each PR was
28
+ reproduced with a failing spec before it was written; the PR description holds
29
+ that evidence. States were last checked on 2026-11-01, with main at `776b99d`.
30
+
31
+ | Finding | Severity | Pull request | State |
32
+ | --- | --- | --- | --- |
33
+ | S1, C1: client IP resolved from the leftmost X-Forwarded-For entry | Critical | [#292](https://github.com/delano/otto/pull/292) | Merged 2026-10-06 |
34
+ | S2: `Config#deep_freeze!` not idempotent with MCP middleware | High | [#293](https://github.com/delano/otto/pull/293) | Merged 2026-10-06 |
35
+ | C2: HEAD dispatch mutates the route tables | High | [#294](https://github.com/delano/otto/pull/294) | Merged 2026-10-06 |
36
+ | C3: generated CSRF secret warning writes to the frozen config | High | [#297](https://github.com/delano/otto/pull/297) | Merged 2026-10-06 |
37
+ | C4: auth success replaces `rack.session` with `{}` | High | [#298](https://github.com/delano/otto/pull/298) | Merged 2026-10-06 |
38
+ | C5: CSRF session binding changes between GET and POST | High | [#295](https://github.com/delano/otto/pull/295) | Merged 2026-10-06 |
39
+ | C6, T1: `csrf_secret=` accepts `''` and `nil` | High | [#299](https://github.com/delano/otto/pull/299) | Merged 2026-10-06 |
40
+ | D1: `auth=` and `role=` on MCP and TOOL routes not enforced | High | [#296](https://github.com/delano/otto/pull/296) | Merged 2026-10-06 |
41
+
42
+ These related pull requests are not findings from the report:
43
+
44
+ | Change | Origin | Pull request | State |
45
+ | --- | --- | --- | --- |
46
+ | Redact secrets from `#inspect` | The CSRF secret showed in `Security::Config#inspect` and `FrozenError` messages; found while preparing #297 | [#300](https://github.com/delano/otto/pull/300) | Merged 2026-10-06 |
47
+ | Bind the CSRF fallback cookie to a `__Host-` name on HTTPS | Changes the cookie fallback in the same CSRF binding lookup that #295 changes | [#302](https://github.com/delano/otto/pull/302) | Merged 2026-10-12 |
48
+ | Resolve the CSRF binding without minting on failures or copying store ids | Left after #302: a failed CSRF check created a binding, and HTML responses copied the session store's id into the binding cookie | [#308](https://github.com/delano/otto/pull/308) | Merged 2026-11-01 |
49
+ | Keep CSRF responses out of shared caches and set the binding cookie once | Left after #302: no `Cache-Control` on responses that set the binding cookie, and a duplicate `Set-Cookie` when the middleware runs twice; also fixes C8 | [#309](https://github.com/delano/otto/pull/309) | Merged 2026-11-01 |
50
+
51
+ Three medium and low findings have a pull request:
52
+
53
+ | Finding | Severity | Pull request | State |
54
+ | --- | --- | --- | --- |
55
+ | S3, C11: a non-String `_csrf_token` parameter returns 500 instead of 403 | Low | [#307](https://github.com/delano/otto/pull/307) | Merged 2026-11-01 |
56
+ | C8: CSRF token injection replaces the response body without closing the original | Medium | [#309](https://github.com/delano/otto/pull/309) | Merged 2026-11-01 |
57
+
58
+ The other medium and low findings have no pull request yet. All 23 were
59
+ present at `4e2758c`; the report's
60
+ [status section](2026-09-28-v2.12.0-code-audit.md#status-on-main) gives each
61
+ one's location on main and a second raise site for C9.
62
+
63
+ When one of these pull requests merges or closes, update its State cell.
@@ -329,11 +329,123 @@ result.metadata
329
329
  result.strategy_name
330
330
  ```
331
331
 
332
+ `result.session` is the session the strategy passed to the result. When a
333
+ strategy passes no `session:`, `StrategyResult.anonymous` and
334
+ `AuthStrategy#success` use a new, empty Hash.
335
+
336
+ After a strategy succeeds, the route auth wrapper sets `env['rack.session']` to
337
+ `result.session`, unless that value is `nil` or `false`, when env holds no
338
+ session that a middleware installed: the key is absent, or it holds the
339
+ `Otto::Request::DefaultSession` that `Otto::Request#session` installs when no
340
+ session middleware ran. (Otto's CSRF check reads the session that way before
341
+ authentication runs.) A session that a middleware installed is never replaced,
342
+ so the handler receives that object. Any other value already in
343
+ `env['rack.session']` counts as installed too, including the plain Hash that
344
+ `Rack::Request#session` creates when upstream Rack middleware or a handler
345
+ wrapper calls it before the route auth wrapper runs; the strategy's session is
346
+ then not placed in env.
347
+
348
+ The built-in `SessionStrategy` passes the object from env. `NoAuthStrategy` and
349
+ `APIKeyStrategy` pass no session. Without a session middleware, their empty
350
+ Hash becomes `env['rack.session']`, so `result.session` and
351
+ `env['rack.session']` are the same object. Behind a session middleware,
352
+ `result.session` on those routes is a separate Hash, and a controller handler
353
+ reads and writes the session through `req.session` (or `env['rack.session']`).
354
+ `RoleStrategy` and `PermissionStrategy` also pass no session, but they read
355
+ roles and permissions from `env['rack.session']` and fail with
356
+ `No session available` when env has none, so their routes need a session
357
+ middleware. On a route without `auth=`, the anonymous result's session is never
358
+ placed in env.
359
+
360
+ Logic classes receive the result as `@context` and get no env. Behind a session
361
+ middleware on those routes, and on any route without `auth=`, `@context.session`
362
+ is therefore a separate Hash, and nothing written to it is persisted. For a
363
+ Logic class to see the middleware's session, the route's strategy has to pass
364
+ `session: env['rack.session']` to `success`, as `SessionStrategy` does.
365
+ Otherwise, make the endpoint a controller handler.
366
+
367
+ With CSRF protection enabled and no session middleware, a strategy session that
368
+ responds to `id` or holds a `'session_id'` key becomes the CSRF binding for code
369
+ that runs after authentication: a token the handler generates, and the token
370
+ `CSRFMiddleware` injects into an HTML response. The next request's CSRF check
371
+ runs before authentication, so it does not see that session; it reads the
372
+ binding cookie instead. `CSRFMiddleware` does not copy a session's id into the
373
+ binding cookie, so the check rejects those tokens with `403` unless the request
374
+ also carries the same value in a cookie the check reads: on plain HTTP, the
375
+ app's `session_id` or `_session_id` cookie. To keep such tokens valid, run a
376
+ session middleware, whose session the check reads, or return a strategy session
377
+ that neither responds to `id` nor holds a `'session_id'` key: Otto then stores
378
+ its own binding in that session under `csrf_session_key` and sets the binding
379
+ cookie to it on responses to safe requests.
380
+
332
381
  Application code should read the result created by Otto rather than constructing
333
382
  its own `StrategyResult`. The `Data` record does not allow member reassignment,
334
383
  but contained `session`, `user`, and `metadata` objects are not deep-frozen;
335
384
  their mutability remains the application's responsibility.
336
385
 
386
+ ## Renew the session id at login
387
+
388
+ Otto never changes the session id. `SessionStrategy` authenticates any request
389
+ whose session holds the configured key, whatever the session's id. If the login
390
+ handler writes the user id into the session without renewing the id, the
391
+ session keeps the id it had before login. That is session fixation. Its effect
392
+ depends on the session store:
393
+
394
+ - With a server-side store such as rack-session's `Rack::Session::Pool`, an
395
+ attacker who obtained the session id before the victim logged in, for
396
+ example by planting the session cookie in the victim's browser, is
397
+ authenticated as the victim once the victim logs in.
398
+ - With `Rack::Session::Cookie`, the session data travels in the cookie, so the
399
+ attacker's copy of the cookie stays anonymous. The session id inside it does
400
+ not change, though, so with CSRF protection enabled a token issued for the
401
+ attacker's copy still validates on the victim's requests (see below).
402
+
403
+ Renew the id in the handler that completes the login. With rack-session, set
404
+ the `:renew` option for the request:
405
+
406
+ ```ruby
407
+ class Session
408
+ def self.create(req, res)
409
+ account = Account.authenticate(req.params['email'], req.params['password'])
410
+ return res.redirect('/signin') unless account
411
+
412
+ req.env['rack.session.options'][:renew] = true
413
+ req.session['user_id'] = account.id
414
+ res.redirect('/dashboard')
415
+ end
416
+ end
417
+ ```
418
+
419
+ rack-session 2.1.2 documents the option in the comment above
420
+ `Rack::Session::Abstract::Persisted`, an ancestor of its `Pool` and `Cookie`
421
+ stores ([lib/rack/session/abstract/id.rb, lines 223-225](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L223-L225)):
422
+
423
+ > :renew (implementation dependent) will prompt the generation of a new
424
+ > session id, and migration of data to be referenced at the new id. If
425
+ > :defer is set, it will be overridden and the cookie will be set.
426
+
427
+ The same comment
428
+ ([lines 229-230](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L229-L230))
429
+ says where to set it: "These options can be set on a per request basis, at the
430
+ location of <tt>env['rack.session.options']</tt>." rack-session sets that key
431
+ on each request it handles, so the handler must run behind a rack-session
432
+ middleware. For another session store, see its documentation on renewing the
433
+ id.
434
+
435
+ With CSRF protection enabled, Otto binds CSRF tokens to `session.id` when the
436
+ session has one (see `Otto::Security::Config#get_or_create_session_id`). After
437
+ the id is renewed, a token issued before login no longer validates and the
438
+ request gets `403`. rack-session renews the id when it commits the session,
439
+ after the response is built, so a form rendered in the login response itself
440
+ also carries a token bound to the old id. Respond to the login with a redirect
441
+ and render forms on the page it redirects to (post/redirect/get); those carry a
442
+ token that validates.
443
+
444
+ This CSRF behavior assumes the session-binding change in delano/otto#295.
445
+ Without it, a new visitor's first token is bound to a random value rather than
446
+ to `session.id`, and that visitor's first CSRF-protected POST, such as the
447
+ login form itself, gets `403` whether or not the id is renewed.
448
+
337
449
  ## Failure and response behavior
338
450
 
339
451
  - Unknown strategy names fail before any strategy in the route runs.
@@ -368,6 +480,223 @@ and revocation policy in the application. Otto supplies the route boundary and
368
480
  result contract; it does not provide a user database or a universal session
369
481
  store.
370
482
 
483
+ ## Protect the cookie that carries the CSRF binding
484
+
485
+ With CSRF protection enabled, Otto binds each token to a value it reads from the
486
+ session first (`session.id`, a binding it stored in the session, or
487
+ `session['session_id']`) and, only when the session provides none, from its
488
+ own binding cookie. On HTTPS requests
489
+ that cookie is `__Host-otto_session`, set with `Secure`, `Path=/` and no
490
+ `Domain`, so in browsers that enforce cookie name prefixes a sibling subdomain
491
+ or a network attacker cannot plant it; on HTTP it is `_otto_session`.
492
+ `CSRFMiddleware` sets it only on responses to safe requests (`GET`, `HEAD`,
493
+ `OPTIONS`, `TRACE`), HTML or not, and only to a binding the client does not
494
+ already send: one Otto minted, one stored in the session under
495
+ `csrf_session_key`, or (see below) the id a store inside `CSRFMiddleware`
496
+ created for Otto's write. It never copies a session id the request already had,
497
+ or a binding read from a cookie, into it; the client sends those again with its
498
+ next request, and a session id copied from a planted session cookie would
499
+ outlive that cookie in `__Host-otto_session`. A session store added with
500
+ `otto.use` before CSRF protection is enabled runs inside `CSRFMiddleware` and
501
+ has committed the session by the time the middleware injects a token. When the
502
+ middleware mints the binding there, the store never sends the id it creates
503
+ for Otto's write, so the binding cookie carries that id instead. On an unsafe
504
+ request neither the CSRF check nor `CSRFMiddleware` creates a binding: a request
505
+ that fails the CSRF check gets its `403` without one, and an HTML response to an
506
+ unsafe request (for example a `csrf=exempt` route that another site posts to)
507
+ carries a token only when the request already has a binding. On plain HTTP,
508
+ and wherever Otto sees an HTTPS request as HTTP (for example behind a
509
+ TLS-terminating proxy that does not send `X-Forwarded-Proto`), the cookie is
510
+ `_otto_session` and can still be planted.
511
+ Cookies are not isolated by port, so a service on another port of the same host
512
+ can also set `__Host-otto_session`.
513
+
514
+ Behind a session middleware the session's id is the binding, so the session
515
+ cookie is the one an attacker would plant: an attacker who can set cookies for
516
+ the victim's browser plants their own session cookie, requests a form with it,
517
+ and uses the token to forge a login. Otto's `__Host-` cookie does not cover
518
+ that. Over HTTPS, give the session cookie the same protection:
519
+
520
+ ```ruby
521
+ use Rack::Session::Cookie,
522
+ key: '__Host-rack.session',
523
+ secure: true,
524
+ secrets: [ENV.fetch('SESSION_SECRET')] # at least 64 bytes
525
+ ```
526
+
527
+ rack-session sets `Path=/` and no `Domain` unless told otherwise, so with
528
+ `secure: true` the cookie meets the `__Host-` requirements; `Rack::Session::Pool`
529
+ takes the same `key:` and `secure:` options. With `secure: true`, rack-session
530
+ sets the cookie only when Rack sees the request as HTTPS (`request.ssl?`), so
531
+ behind a TLS-terminating proxy Rack must see the forwarded scheme, or no
532
+ session survives between requests; rack-session 2.1.2 also takes
533
+ `assume_ssl: true`, which its `security_matches?` treats as HTTPS
534
+ ([lines 371-374](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L371-L374)):
535
+ `request.ssl? || @assume_ssl == true`. Otto's binding cookie does not stand in
536
+ for the missing session cookie, so CSRF-protected requests then get `403` as
537
+ well. The same holds for a request whose `rack.session.options` set `skip` or
538
+ `defer`: the store sets no cookie, and unless the application sets one the
539
+ binding read from `session.id` never reaches the client.
540
+ `Rack::Session::Cookie` raises `ArgumentError` when it is built with a secret
541
+ shorter than 64 bytes. Also renew the session id in the login handler
542
+ (`req.env['rack.session.options'][:renew] = true`), so a session that existed
543
+ before login does not carry over.
544
+
545
+ The planted session cookie does not have to name a session the store holds.
546
+ Otto reads `session.id` without loading the session, and in rack-session 2.1.2
547
+ an unloaded session's id is whatever the store extracts from the request
548
+ ([lib/rack/session/abstract/id.rb, lines 74-77](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L74-L77)):
549
+
550
+ ```ruby
551
+ def id
552
+ return @id if @loaded or instance_variable_defined?(:@id)
553
+ @id = @store.send(:extract_session_id, @req)
554
+ end
555
+ ```
556
+
557
+ For `Rack::Session::Pool` that is the value of the session cookie. `Persisted`
558
+ reads it
559
+ ([lines 328-332](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L328-L332)):
560
+
561
+ ```ruby
562
+ def extract_session_id(request)
563
+ sid = request.cookies[@key]
564
+ sid ||= request.params[@key] unless @cookie_only
565
+ sid
566
+ end
567
+ ```
568
+
569
+ and `PersistedSecure`, the class `Pool` inherits from, wraps it in a
570
+ `SessionId`
571
+ ([lines 483-486](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L483-L486)):
572
+
573
+ ```ruby
574
+ def extract_session_id(*)
575
+ public_id = super
576
+ public_id && SessionId.new(public_id)
577
+ end
578
+ ```
579
+
580
+ `Pool` replaces an id it holds no session for only when the session loads
581
+ ([lib/rack/session/pool.rb, lines 44-52](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/pool.rb#L44-L52)):
582
+
583
+ ```ruby
584
+ def find_session(req, sid)
585
+ @mutex.synchronize do
586
+ unless sid and session = get_session_with_fallback(sid)
587
+ sid, session = generate_sid(use_mutex: false), {}
588
+ @pool.store sid.private_id, session
589
+ end
590
+ [sid, session]
591
+ end
592
+ end
593
+ ```
594
+
595
+ So behind `Pool`, until something loads the session, the binding is the id the
596
+ session cookie names, and an attacker can plant a value they made up instead of
597
+ a copy of their own session cookie. This is a known limitation. Otto does not
598
+ load the session to check the id. rack-session commits a session that was
599
+ loaded
600
+ ([lines 350-357](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/abstract/id.rb#L350-L357)):
601
+
602
+ ```ruby
603
+ def commit_session?(req, session, options)
604
+ if options[:skip]
605
+ false
606
+ else
607
+ has_session = loaded_session?(session) || forced_session_update?(session, options)
608
+ has_session && security_matches?(req, options)
609
+ end
610
+ end
611
+ ```
612
+
613
+ Our reading of `commit_session?` is that loading on every CSRF-checked request
614
+ would make each such request commit the copy it loaded before the handler ran,
615
+ over any session write an overlapping request made in the meantime. Loading
616
+ would also not stop the attack: an attacker who can plant a cookie can as easily
617
+ plant the id of a real session they started, which a load accepts. In both
618
+ cases, protect the session cookie itself as described above.
619
+
620
+ `Rack::Session::Cookie` differs: its `extract_session_id` reads `session_id`
621
+ from the decrypted cookie
622
+ ([lib/rack/session/cookie.rb, lines 209-211](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/cookie.rb#L209-L211)),
623
+ so with `secrets:` configured a value that does not decrypt yields no id.
624
+ Without `secrets:` the cookie is decoded with the `coder` instead
625
+ ([lines 240-244](https://github.com/rack/rack-session/blob/v2.1.2/lib/rack/session/cookie.rb#L240-L244),
626
+ "Use the coder option, which has the potential to be very unsafe."), and a
627
+ planted cookie can carry any `session_id`.
628
+
629
+ ## Keep CSRF responses out of shared caches
630
+
631
+ A response on which `CSRFMiddleware` sets the binding cookie or injects a token
632
+ is meant for one client. RFC 9111, section 7.3: "Note that the Set-Cookie
633
+ response header field [COOKIE] does not inhibit caching; a cacheable response
634
+ with a Set-Cookie header field can be (and often is) used to satisfy subsequent
635
+ requests to caches." A shared cache that stored such a response would hand one
636
+ client's binding cookie, or a token bound to one client's session, to other
637
+ clients. The middleware therefore adds
638
+ `Cache-Control: private, stale-if-error=0` to these responses. RFC 9111,
639
+ section 5.2.2.7: "The unqualified private response directive indicates that a
640
+ shared cache MUST NOT store the response (i.e., the response is intended for a
641
+ single user)." The browser's own cache may still store it.
642
+
643
+ `stale-if-error=0` (RFC 5861) is for a cache that stores the response despite
644
+ `private`. CloudFront does when the cache policy's minimum TTL is above 0, as
645
+ in the managed CachingOptimized policy (1 second). The CloudFront developer
646
+ guide: "If your minimum TTL is greater than 0, CloudFront uses the cache
647
+ policy’s minimum TTL, even if the Cache-Control: no-cache, no-store, and/or
648
+ private directives are present in the origin headers. If the origin is
649
+ reachable, CloudFront gets the object from the origin and returns it to the
650
+ viewer. If the origin is unreachable and the minimum or maximum TTL value is
651
+ greater than 0, CloudFront will serve the object that it got from the origin
652
+ previously. To avoid this behavior, include the Cache-Control:
653
+ stale-if-error=0 directive with the object returned from the origin."
654
+
655
+ When the application sets `Cache-Control` or `Expires` on the response, Otto
656
+ adds nothing, even when the application's value lets shared caches store the
657
+ response (for example `public, max-age=60`); a page that carries a token then
658
+ needs `private` or `no-store` from the application, and `stale-if-error=0` for
659
+ the CloudFront case above. Otto also adds nothing to a response it did not
660
+ change: a token the application writes itself, for example from a JSON token
661
+ endpoint behind a session middleware, needs its own header, such as
662
+ `res['cache-control'] = 'private, stale-if-error=0'`.
663
+
664
+ Otto reads only `Cache-Control` and `Expires`. Some caches give their own
665
+ fields precedence, and Otto does not inspect those: a cache that implements
666
+ `CDN-Cache-Control` (RFC 9213, section 2.2) "MUST ignore the Cache-Control and
667
+ Expires header fields in that response" when one of its targeted fields has a
668
+ valid, non-empty value; the
669
+ [nginx proxy module documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid)
670
+ says "If the header does not include the “X-Accel-Expires” field, parameters
671
+ of caching may be set in the header fields “Expires” or “Cache-Control”"; and
672
+ Varnish's built-in VCL checks `Cache-Control` for `private` only when the
673
+ response has no `Surrogate-Control`
674
+ ([bin/varnishd/builtin.vcl in Varnish 7.6](https://github.com/varnishcache/varnish-cache/blob/7.6/bin/varnishd/builtin.vcl#L235-L241)):
675
+
676
+ ```vcl
677
+ sub vcl_beresp_control {
678
+ if (beresp.http.Surrogate-control ~ "(?i)no-store" ||
679
+ (!beresp.http.Surrogate-Control &&
680
+ beresp.http.Cache-Control ~ "(?i:no-cache|no-store|private)")) {
681
+ call vcl_beresp_hitmiss;
682
+ }
683
+ }
684
+ ```
685
+
686
+ Both keep a response that carries `Set-Cookie` out of the cache on their own
687
+ by default: the same nginx page says "If the header includes the “Set-Cookie”
688
+ field, such a response will not be cached", and the built-in VCL's
689
+ `vcl_beresp_cookie` calls `vcl_beresp_hitmiss` when `beresp.http.Set-Cookie`
690
+ is set. nginx's `proxy_ignore_headers` turns this off when it lists
691
+ `Set-Cookie`; that page says the directive "Disables processing of certain
692
+ response header fields from the proxied server". A response
693
+ that carries only an injected token has no such cookie and depends on
694
+ `Cache-Control`. An application that sends one of these fields on a page that
695
+ carries a token needs to keep shared caches out in that field as well. A cache
696
+ that is configured to ignore `Cache-Control`, such as a Cloudflare rule that
697
+ sets an edge TTL and ignores cache headers, stores these responses anyway, so
698
+ keep pages that carry tokens out of such rules.
699
+
371
700
  ## Related contracts
372
701
 
373
702
  - [Route syntax](../reference/route-syntax.md) — `auth=`, `role=`, and route
@@ -66,6 +66,80 @@ forwarded host, scheme, port, and IP values directly.
66
66
  Configure these options before the first request, when Otto freezes its
67
67
  configuration.
68
68
 
69
+ ## How enumerated proxy trust resolves the client IP
70
+
71
+ With `trusted_proxies: [...]`, Otto reads `X-Forwarded-For` only when
72
+ `REMOTE_ADDR` matches a configured proxy. It then reads the header from the
73
+ right: starting with the entry nearest the application, it skips entries that
74
+ match a configured proxy and takes the first entry that does not as the client
75
+ IP. Entries to the left of that one are never used. If every entry matches a
76
+ configured proxy, Otto uses `REMOTE_ADDR`.
77
+
78
+ For example, with `trusted_proxies: ['10.0.0.0/8']` and a request from
79
+ `10.0.0.5` carrying `X-Forwarded-For: 198.51.100.7, 203.0.113.9, 10.0.0.9`,
80
+ the client IP is `203.0.113.9`. The `198.51.100.7` entry is whatever the client
81
+ sent.
82
+
83
+ If the walk reaches an entry that is not a valid IP address (such as `unknown`,
84
+ an empty entry, including the one a trailing comma leaves, or a range such as
85
+ `203.0.113.9/0`) before it finds one that does not match, the request has no
86
+ client IP. A proxy wrote that entry where the client belongs, and the proxy
87
+ itself is not the client. `env['otto.ip_match']` returns false for every range,
88
+ `env['otto.client_ip']` and `Otto::Request#client_ipaddress` are nil, and when
89
+ IP privacy is enabled (the `:masked` and `:anonymous` profiles) Otto deletes
90
+ `X-Forwarded-For`, `X-Real-IP`, `X-Client-IP` and the vendor headers in
91
+ `Otto::Utils::VENDOR_CLIENT_ADDRESS_HEADERS` and removes every `for=` pair
92
+ from `Forwarded`, keeping its `proto=`, `host=` and `by=` fields (an element
93
+ left empty is dropped, and a header left empty is deleted). `REMOTE_ADDR` keeps
94
+ the proxy's address, and both `req.ip` and a plain `Rack::Request#ip` return
95
+ it, so rate limiters still have a key; see
96
+ [the privacy guide](privacy.md#default-behavior) for why.
97
+
98
+ A proxy can write `unknown` on purpose. RFC 7239 (section 6.2) defines it for
99
+ `Forwarded`, for a proxy that does not know the identity of the preceding hop
100
+ but still signals that it forwarded the request, and a proxy can write the same
101
+ token into `X-Forwarded-For` for that reason or because it is set to withhold
102
+ the client address. When a trusted proxy does this, every request through it
103
+ has no client IP, so `ip_match` denies all of them. To resolve a client IP,
104
+ configure that proxy to append the address it received the request from.
105
+
106
+ The walk gives the right answer only when two things hold:
107
+
108
+ - **Every proxy between the client and the application is listed** in
109
+ `trusted_proxies`, together with any address a proxy appends about itself.
110
+ Google Cloud's external Application Load Balancer, for example, appends the
111
+ client's address and then its forwarding rule's address, so the forwarding
112
+ rule's address has to be listed as well as the load balancer's own ranges.
113
+ An unlisted address is an untrusted entry: the one nearest the application
114
+ becomes the client IP for every request through it. Rate-limit keys and
115
+ `otto.privacy.hashed_ip` then collapse onto that address, `ip_match` tests
116
+ it, and if it is private or loopback the request is exempt from masking.
117
+ A CDN in front of a listed load balancer is the common case: list the CDN's
118
+ edge ranges too.
119
+ - **Every listed proxy appends** the address it received the request from to
120
+ `X-Forwarded-For`. nginx does this with
121
+ `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`. A trusted
122
+ proxy that passes the client's `X-Forwarded-For` through unchanged lets the
123
+ client choose the rightmost entry, and with it the resolved client IP, the
124
+ value `env['otto.ip_match']` checks, and every key derived from it.
125
+ Configure each trusted proxy to append to the header, or to replace a
126
+ client-supplied value with the address it observed.
127
+
128
+ Releases through 2.12.0 took the leftmost untrusted entry instead, which the
129
+ client controls behind an appending proxy. Under that walk a missing inner
130
+ proxy did not change the result for a client that sent no `X-Forwarded-For`,
131
+ so a deployment that worked on 2.12.0 can need more `trusted_proxies` entries
132
+ after upgrading.
133
+
134
+ `X-Real-IP` and `X-Client-IP` each carry one address. Otto reads them only when
135
+ `X-Forwarded-For` is absent or blank, `X-Real-IP` first and then `X-Client-IP`,
136
+ and never adds them to the `X-Forwarded-For` chain. A proxy that sets
137
+ `X-Real-IP` but passes a client's `X-Forwarded-For` through still lets that
138
+ header decide the client IP. When `X-Forwarded-For` is present and every entry
139
+ in it is a trusted proxy, Otto uses `REMOTE_ADDR`, not `X-Real-IP`. A proxy
140
+ that sets only `X-Real-IP` should also append to or replace
141
+ `X-Forwarded-For`.
142
+
69
143
  ## How Otto handles each trust state
70
144
 
71
145
  The decision is made by `IPPrivacyMiddleware` from the connecting peer
@@ -74,7 +148,7 @@ The decision is made by `IPPrivacyMiddleware` from the connecting peer
74
148
 
75
149
  | Trust state | `otto.via_trusted_proxy` | Forwarded host, scheme, and port carriers |
76
150
  | --- | --- | --- |
77
- | `REMOTE_ADDR` matches a configured trusted-proxy CIDR | `true` | Kept. When privacy masking applies, `Forwarded` keeps its `proto=`, `host=`, and `by=` fields while its `for=` value is replaced with the masked IP. |
151
+ | `REMOTE_ADDR` matches a configured trusted-proxy CIDR | `true` | Kept. When IP privacy is enabled, `Forwarded` keeps its `proto=`, `host=`, and `by=` fields while its `for=` value is replaced with the masked IP, or with the resolved client IP when that IP is private or loopback and exempt from masking. When no client IP resolves, the `for=` pairs are removed instead. Otto re-reads the result with Rack's parser; if any other `for=` value survives, or Rack cannot parse the header (an RFC 7239 extension parameter is enough), Otto deletes the header. The first deletion in a process is logged at warn, later ones at debug. |
78
152
  | Depth mode is enabled | `true` for every peer | Kept, subject to the same privacy masking. |
79
153
  | Proxy trust is configured, but the peer does not match a configured CIDR | `false` | Deleted. |
80
154
  | `trusted_proxies: :none` is configured | `false` for every peer | Deleted. |
@@ -190,10 +264,14 @@ process that both resolve proxied requests must agree. The later one raises:
190
264
  Cannot use forwarding family %s (trusted_proxy_header) because another Otto
191
265
  application in this process already uses %s. Rack's forwarded host, port,
192
266
  scheme, and IP policy is process-global, so every Otto application in one
193
- process that resolves proxied requests must use the same forwarding family.
267
+ process that resolves proxied requests must use the same forwarding family. A
268
+ test suite that builds applications with different families must clear this
269
+ between tests: require 'otto/testing' and call Otto::Testing.reset!.
194
270
  ```
195
271
 
196
272
  The two placeholders are the requested family and the already committed one.
273
+ See [Testing Otto applications](testing-guide.md#reset-ottos-process-global-state-between-tests)
274
+ for the reset.
197
275
 
198
276
  An application that configures no proxy trust, and one that asserts
199
277
  `trusted_proxies: :none`, read no forwarded chain and therefore stake no claim
@@ -205,9 +283,11 @@ registers the family for the process, even under `trusted_proxies: :none`.
205
283
  `trusted_proxy_header` accepts `X-Forwarded-For` (the default), `Forwarded`, or
206
284
  `Both`. When configuring proxy trust, `Forwarded` and `Both` require depth mode.
207
285
  CIDR filter mode resolves client IPs from the `X-Forwarded-For` family only
208
- (`X-Forwarded-For`, then `X-Real-IP`, then `X-Client-IP`) and never from RFC
209
- 7239 `Forwarded`, so a non-default family would make Rack read a header that
210
- Otto ignores:
286
+ (`X-Forwarded-For`, or `X-Real-IP` then `X-Client-IP` when it is absent or
287
+ blank; see
288
+ [How enumerated proxy trust resolves the client IP](#how-enumerated-proxy-trust-resolves-the-client-ip))
289
+ and never from RFC 7239 `Forwarded`, so a non-default family would make Rack
290
+ read a header that Otto ignores:
211
291
 
212
292
  ```text
213
293
  Cannot configure trusted_proxy_header 'Forwarded' or 'Both' together with
data/docs/guides/mcp.md CHANGED
@@ -62,16 +62,23 @@ The endpoint is `POST /_mcp` unless `mcp_endpoint:` (or `http_endpoint:`) sets
62
62
  another slash-prefixed path. `mcp_enabled?` returns `true` after MCP has been
63
63
  enabled.
64
64
 
65
- For multi-step boot configuration, call `enable_mcp!` instead:
65
+ For multi-step boot configuration, construct Otto without a routes file, call
66
+ `enable_mcp!`, then load the routes file:
66
67
 
67
68
  ```ruby
68
- otto = Otto.new('routes')
69
+ otto = Otto.new
69
70
  otto.enable_mcp!(
70
71
  http_endpoint: '/api/mcp',
71
72
  auth_tokens: [ENV.fetch('MCP_TOKEN')],
72
73
  )
74
+ otto.load('routes')
73
75
  ```
74
76
 
77
+ Otto registers `MCP` and `TOOL` lines only while a routes file loads, and only
78
+ if MCP is already enabled. `Otto.new('routes')` followed by `enable_mcp!` loads
79
+ the file first: Otto logs an error for each `MCP` and `TOOL` line, skips it,
80
+ and the endpoint serves no resources or tools.
81
+
75
82
  Enable MCP only once per `Otto` instance. A second call raises `ArgumentError`;
76
83
  provide all MCP settings in the first call.
77
84
 
@@ -89,8 +96,11 @@ POST /mcp/create-user TOOL create_user AppMCP.create_user
89
96
  ```
90
97
 
91
98
  `MCP` registers a resource. Its resource URI is `users`: Otto removes one
92
- leading slash from the declaration. The handler must be a zero-argument class
93
- method. Otto returns its value as text with the `text/plain` MIME type.
99
+ leading slash from the declaration. The handler is a class method that takes
100
+ no arguments, or one argument: the Rack `env` of the MCP request. A handler
101
+ that requires more than one argument, or a keyword argument, fails the read
102
+ with a JSON-RPC internal error. Otto returns the handler's value as text with
103
+ the `text/plain` MIME type.
94
104
 
95
105
  `TOOL` registers a tool. Its handler is a class method that receives
96
106
  `arguments` and the Rack `env`:
@@ -117,6 +127,32 @@ currently advertise an empty input schema. A tool still receives the
117
127
  `params.arguments` object supplied by the client, so validate its fields in the
118
128
  handler before using them.
119
129
 
130
+ `MCP` and `TOOL` declarations cannot use the `auth=`, `role=`, or `csrf=` route
131
+ options. Otto does not run route-level authentication, role, or CSRF checks
132
+ for resources and tools. When MCP is enabled as the routes file loads, a line
133
+ that sets any of these options raises `Otto::RouteDefinitionError` and the
134
+ application fails to boot:
135
+
136
+ ```text
137
+ # Rejected when the routes file loads with MCP enabled:
138
+ POST /mcp/delete-user TOOL delete_user AppMCP.delete_user auth=session role=admin
139
+ ```
140
+
141
+ When MCP is not enabled as the file loads, Otto logs and skips every `MCP` and
142
+ `TOOL` line, as described above, without checking its options.
143
+
144
+ Any other `key=value` option on an `MCP` or `TOOL` line, such as
145
+ `response=json`, still loads, but Otto logs a `MCP/tool route option not
146
+ applied` warning for it. The MCP server reads only the resource URI or tool
147
+ name and the handler, so these options have no effect.
148
+
149
+ Use `mcp_auth_tokens` to require a token for the MCP endpoint (see
150
+ [Authentication](#authentication)). A request that passes the token check can
151
+ list, read, and call every registered resource and tool, so check permissions
152
+ inside the handler of any resource or tool that needs them. Both receive the
153
+ Rack `env` of the MCP request: a tool handler always, a resource handler when
154
+ it takes one argument.
155
+
120
156
  ## Call the endpoint
121
157
 
122
158
  Every request must be a JSON-RPC 2.0 `POST` with