otto 2.12.0 → 2.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/ci.yml +1 -1
- data/.github/workflows/claude-code-review.yml +1 -1
- data/.github/workflows/claude.yml +1 -1
- data/.github/workflows/code-smells.yml +2 -2
- data/.github/workflows/release-gem.yml +1 -1
- data/.github/workflows/ruby-lint.yml +1 -1
- data/.github/workflows/yardoc.yml +1 -1
- data/AGENTS.md +4 -2
- data/CHANGELOG.rst +692 -0
- data/Gemfile +1 -0
- data/Gemfile.lock +6 -1
- data/docs/README.md +4 -0
- data/docs/audits/2026-09-28-v2.12.0-code-audit.md +732 -0
- data/docs/audits/README.md +63 -0
- data/docs/guides/authentication.md +329 -0
- data/docs/guides/forwarded-authority.md +80 -4
- data/docs/guides/mcp.md +40 -4
- data/docs/guides/privacy.md +23 -2
- data/docs/guides/routing.md +8 -4
- data/docs/guides/testing-guide.md +31 -3
- data/docs/migrating/v2.3.0.md +13 -7
- data/docs/reference/authentication.md +70 -22
- data/examples/lambda_handlers/README.md +4 -4
- data/examples/lambda_handlers/handlers.rb +4 -5
- data/examples/lambda_handlers/routes +2 -2
- data/examples/mcp_demo/README.md +65 -27
- data/examples/mcp_demo/app.rb +8 -5
- data/examples/mcp_demo/config.ru +50 -3
- data/examples/mcp_demo/routes +10 -6
- data/examples/security_features/README.md +2 -2
- data/lib/otto/caddy_tls/server.rb +8 -4
- data/lib/otto/core/option_hash.rb +124 -0
- data/lib/otto/core/redacted_inspect.rb +149 -0
- data/lib/otto/core/router.rb +41 -14
- data/lib/otto/core.rb +2 -0
- data/lib/otto/env_keys.rb +30 -7
- data/lib/otto/logging_helpers.rb +1 -1
- data/lib/otto/mcp/auth/token.rb +12 -1
- data/lib/otto/mcp/protocol.rb +3 -3
- data/lib/otto/mcp/registry.rb +28 -2
- data/lib/otto/mcp/route_parser.rb +20 -8
- data/lib/otto/mcp/server.rb +17 -9
- data/lib/otto/privacy/config.rb +12 -1
- data/lib/otto/privacy/ip_privacy.rb +109 -3
- data/lib/otto/privacy/redacted_fingerprint.rb +8 -10
- data/lib/otto/request.rb +34 -0
- data/lib/otto/route_definition.rb +3 -2
- data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
- data/lib/otto/security/config.rb +358 -46
- data/lib/otto/security/csrf.rb +17 -2
- data/lib/otto/security/csrf_validation.rb +13 -7
- data/lib/otto/security/middleware/csrf_middleware.rb +203 -37
- data/lib/otto/security/middleware/ip_privacy_middleware.rb +127 -38
- data/lib/otto/static.rb +63 -0
- data/lib/otto/utils.rb +105 -28
- data/lib/otto/version.rb +1 -1
- data/lib/otto.rb +37 -9
- metadata +6 -2
|
@@ -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
|
|
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. |
|
|
@@ -209,9 +283,11 @@ registers the family for the process, even under `trusted_proxies: :none`.
|
|
|
209
283
|
`trusted_proxy_header` accepts `X-Forwarded-For` (the default), `Forwarded`, or
|
|
210
284
|
`Both`. When configuring proxy trust, `Forwarded` and `Both` require depth mode.
|
|
211
285
|
CIDR filter mode resolves client IPs from the `X-Forwarded-For` family only
|
|
212
|
-
(`X-Forwarded-For`,
|
|
213
|
-
|
|
214
|
-
|
|
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:
|
|
215
291
|
|
|
216
292
|
```text
|
|
217
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,
|
|
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
|
|
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
|
|
93
|
-
|
|
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
|
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. |
|