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.
Files changed (59) 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/AGENTS.md +4 -2
  10. data/CHANGELOG.rst +692 -0
  11. data/Gemfile +1 -0
  12. data/Gemfile.lock +6 -1
  13. data/docs/README.md +4 -0
  14. data/docs/audits/2026-09-28-v2.12.0-code-audit.md +732 -0
  15. data/docs/audits/README.md +63 -0
  16. data/docs/guides/authentication.md +329 -0
  17. data/docs/guides/forwarded-authority.md +80 -4
  18. data/docs/guides/mcp.md +40 -4
  19. data/docs/guides/privacy.md +23 -2
  20. data/docs/guides/routing.md +8 -4
  21. data/docs/guides/testing-guide.md +31 -3
  22. data/docs/migrating/v2.3.0.md +13 -7
  23. data/docs/reference/authentication.md +70 -22
  24. data/examples/lambda_handlers/README.md +4 -4
  25. data/examples/lambda_handlers/handlers.rb +4 -5
  26. data/examples/lambda_handlers/routes +2 -2
  27. data/examples/mcp_demo/README.md +65 -27
  28. data/examples/mcp_demo/app.rb +8 -5
  29. data/examples/mcp_demo/config.ru +50 -3
  30. data/examples/mcp_demo/routes +10 -6
  31. data/examples/security_features/README.md +2 -2
  32. data/lib/otto/caddy_tls/server.rb +8 -4
  33. data/lib/otto/core/option_hash.rb +124 -0
  34. data/lib/otto/core/redacted_inspect.rb +149 -0
  35. data/lib/otto/core/router.rb +41 -14
  36. data/lib/otto/core.rb +2 -0
  37. data/lib/otto/env_keys.rb +30 -7
  38. data/lib/otto/logging_helpers.rb +1 -1
  39. data/lib/otto/mcp/auth/token.rb +12 -1
  40. data/lib/otto/mcp/protocol.rb +3 -3
  41. data/lib/otto/mcp/registry.rb +28 -2
  42. data/lib/otto/mcp/route_parser.rb +20 -8
  43. data/lib/otto/mcp/server.rb +17 -9
  44. data/lib/otto/privacy/config.rb +12 -1
  45. data/lib/otto/privacy/ip_privacy.rb +109 -3
  46. data/lib/otto/privacy/redacted_fingerprint.rb +8 -10
  47. data/lib/otto/request.rb +34 -0
  48. data/lib/otto/route_definition.rb +3 -2
  49. data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
  50. data/lib/otto/security/config.rb +358 -46
  51. data/lib/otto/security/csrf.rb +17 -2
  52. data/lib/otto/security/csrf_validation.rb +13 -7
  53. data/lib/otto/security/middleware/csrf_middleware.rb +203 -37
  54. data/lib/otto/security/middleware/ip_privacy_middleware.rb +127 -38
  55. data/lib/otto/static.rb +63 -0
  56. data/lib/otto/utils.rb +105 -28
  57. data/lib/otto/version.rb +1 -1
  58. data/lib/otto.rb +37 -9
  59. metadata +6 -2
data/lib/otto/utils.rb CHANGED
@@ -10,8 +10,9 @@ class Otto
10
10
  module Utils
11
11
  extend self
12
12
 
13
- # Forwarded-for style headers consulted (in order) when resolving the real
14
- # client IP from behind a trusted proxy. Shared by IPPrivacyMiddleware and
13
+ # Forwarded-for style headers consulted when resolving the real client IP
14
+ # from behind a trusted proxy. The resolver reads only the first one that
15
+ # is not blank, in this order. Shared by IPPrivacyMiddleware and
15
16
  # Otto::Request so the two resolvers cannot drift.
16
17
  FORWARDED_FOR_HEADERS = %w[
17
18
  HTTP_X_FORWARDED_FOR
@@ -49,10 +50,46 @@ class Otto
49
50
  # forwarded-for family (the CIDR walk, and X-Forwarded-For in depth mode)
50
51
  # and RFC 7239 Forwarded (depth mode with trusted_proxy_header 'Forwarded'
51
52
  # or 'Both'). A header resolve_client_ip starts reading belongs here, so
52
- # that IPPrivacyMiddleware deletes it when no client IP resolves and
53
- # Otto::Testing.env_for refuses it in a request it builds as direct.
53
+ # that IPPrivacyMiddleware removes its address when no client IP resolves
54
+ # (deleting it, or for Forwarded its for= pairs) and Otto::Testing.env_for
55
+ # refuses it in a request it builds as direct.
54
56
  CLIENT_ADDRESS_HEADERS = (FORWARDED_FOR_HEADERS + %w[HTTP_FORWARDED]).freeze
55
57
 
58
+ # Vendor headers in which a CDN or proxy passes on the client address it
59
+ # observed: Cloudflare (CF-Connecting-IP, CF-Connecting-IPv6), Akamai and
60
+ # Cloudflare Enterprise (True-Client-IP), Fastly (Fastly-Client-IP), Fly
61
+ # (Fly-Client-IP), Azure Front Door (X-Azure-ClientIP, X-Azure-SocketIP),
62
+ # CloudFront (CloudFront-Viewer-Address), Vercel (X-Vercel-Forwarded-For),
63
+ # ingress-nginx (X-Original-Forwarded-For), and the older
64
+ # X-Cluster-Client-IP and X-AppEngine-User-IP. The resolver never reads
65
+ # them: Otto cannot tell which vendor, if any, set one, and a client can
66
+ # send any of them. They are listed because they hold the address
67
+ # REMOTE_ADDR holds, so with IP privacy enabled IPPrivacyMiddleware
68
+ # rewrites them alongside X-Forwarded-For (masked IP, or the resolved
69
+ # client IP on the private/loopback exemption) and deletes them when no
70
+ # client IP resolves.
71
+ VENDOR_CLIENT_ADDRESS_HEADERS = %w[
72
+ HTTP_CF_CONNECTING_IP
73
+ HTTP_CF_CONNECTING_IPV6
74
+ HTTP_TRUE_CLIENT_IP
75
+ HTTP_FASTLY_CLIENT_IP
76
+ HTTP_FLY_CLIENT_IP
77
+ HTTP_X_AZURE_CLIENTIP
78
+ HTTP_X_AZURE_SOCKETIP
79
+ HTTP_CLOUDFRONT_VIEWER_ADDRESS
80
+ HTTP_X_VERCEL_FORWARDED_FOR
81
+ HTTP_X_ORIGINAL_FORWARDED_FOR
82
+ HTTP_X_CLUSTER_CLIENT_IP
83
+ HTTP_X_APPENGINE_USER_IP
84
+ ].freeze
85
+
86
+ # Headers that carry nothing but client addresses: the forwarded-for
87
+ # family and the vendor headers. IPPrivacyMiddleware rewrites every one
88
+ # present to a single address, or deletes them when no client IP
89
+ # resolves. (Forwarded also carries proto=/host=/by= and is handled
90
+ # separately.)
91
+ ADDRESS_ONLY_HEADERS = (FORWARDED_FOR_HEADERS + VENDOR_CLIENT_ADDRESS_HEADERS).freeze
92
+
56
93
  # Special-use IPv4/IPv6 ranges that IPAddr's #private?/#loopback?/#link_local?
57
94
  # predicates do not cover but that should still be treated as non-public
58
95
  # (e.g. when picking the real client out of a forwarded chain).
@@ -185,13 +222,19 @@ class Otto
185
222
  # Strips an optional port (IPv6-safe), validates with IPAddr, and returns
186
223
  # the cleaned address string, or nil if the input is blank or malformed.
187
224
  #
225
+ # A range is malformed here. IPAddr.new also parses prefix and netmask
226
+ # notation ("203.0.113.9/0" is 0.0.0.0/0), but every caller hands this a
227
+ # value that must name one address: a forwarded header entry, or the
228
+ # runtime client address in ip_in_cidrs?. Configured ranges are parsed
229
+ # with IPAddr directly and never pass through here.
230
+ #
188
231
  # @param ip [String, nil] candidate address, optionally with a port
189
232
  # @return [String, nil] cleaned IP string, or nil if invalid
190
233
  def normalize_ip(ip)
191
234
  return nil if ip.nil? || ip.empty?
192
235
 
193
236
  candidate = strip_ip_port(ip.strip)
194
- return nil if candidate.nil? || candidate.empty?
237
+ return nil if candidate.nil? || candidate.empty? || candidate.include?('/')
195
238
 
196
239
  # IPAddr validates both IPv4 and IPv6; raises for malformed input
197
240
  IPAddr.new(candidate)
@@ -225,13 +268,26 @@ class Otto
225
268
  # This is the single canonical resolver shared by IPPrivacyMiddleware
226
269
  # ("resolve once") and Otto::Request#client_ipaddress (its no-middleware
227
270
  # fallback), so both paths agree on which headers to trust and how to walk
228
- # a proxy chain. It walks the forwarded chain left-to-right and returns the
229
- # first address that is not itself a trusted proxy; if the peer is not a
230
- # trusted proxy (or there is no config) it returns REMOTE_ADDR unchanged.
271
+ # a proxy chain. It walks the forwarded chain from the right (nearest proxy
272
+ # first, the direction Rack::Request#ip also walks), skips trusted proxies,
273
+ # and returns the first address that is not one. Entries left of that
274
+ # address were supplied by the client and are never selected. If the peer
275
+ # is not a trusted proxy (or there is no config) it returns REMOTE_ADDR
276
+ # unchanged.
277
+ #
278
+ # Returns nil when the walk reaches an entry that is not a valid address
279
+ # before it finds an untrusted one. The proxy tier wrote that entry where
280
+ # the client belongs, so the client is unknown: the entries to its left
281
+ # are client supplied, and REMOTE_ADDR is a proxy. Falling back to the
282
+ # proxy would make a private or loopback peer the client, which exempts
283
+ # the request from masking and lets otto.ip_match test the proxy's own
284
+ # address. Depth mode returns nil for an invalid selected entry for the
285
+ # same reason.
231
286
  #
232
287
  # @param env [Hash] Rack environment
233
288
  # @param security_config [Otto::Security::Config, nil] config exposing #trusted_proxy?
234
- # @return [String, nil] resolved client IP (the raw REMOTE_ADDR when no proxy applies)
289
+ # @return [String, nil] resolved client IP (the raw REMOTE_ADDR when no
290
+ # proxy applies), or nil when the walk reaches an invalid entry
235
291
  def resolve_client_ip(env, security_config)
236
292
  remote_addr = env['REMOTE_ADDR']
237
293
 
@@ -246,19 +302,29 @@ class Otto
246
302
  # is the client. Don't honor forwarded headers from untrusted sources.
247
303
  return remote_addr unless security_config&.trusted_proxy?(remote_addr)
248
304
 
249
- forwarded_ips = FORWARDED_FOR_HEADERS
250
- .filter_map { |header| env[header] }
251
- .flat_map { |value| value.split(/,\s*/) }
252
-
253
- forwarded_ips.each do |candidate|
305
+ # Read one header: the first of FORWARDED_FOR_HEADERS that is not blank.
306
+ # X-Real-IP and X-Client-IP carry a single address, so they are read only
307
+ # when X-Forwarded-For is absent or blank and never become positions in
308
+ # its chain.
309
+ # Split with xff_chain, as depth mode does: it keeps empty fields, a
310
+ # trailing one included, so an empty entry the proxy tier wrote stops
311
+ # the walk below like any other invalid entry instead of vanishing.
312
+ header = FORWARDED_FOR_HEADERS.find { |name| !env[name].to_s.strip.empty? }
313
+ forwarded_ips = header ? xff_chain(env[header]) : []
314
+
315
+ # Walk from the right. A proxy that appends writes the address it received
316
+ # the request from after whatever the client sent, so skip trusted proxies
317
+ # and stop at the first entry that is not one: everything left of it came
318
+ # from the client. An entry that is not a valid address (for example
319
+ # "unknown") ends the walk with no answer: reading past it would reach
320
+ # client-supplied values, and the peer is a proxy, not the client.
321
+ forwarded_ips.reverse_each do |candidate|
254
322
  clean_ip = normalize_ip(candidate.strip)
255
- next unless clean_ip
256
-
257
- # First address in the chain that isn't a known proxy is the client.
323
+ return nil unless clean_ip
258
324
  return clean_ip unless security_config.trusted_proxy?(clean_ip)
259
325
  end
260
326
 
261
- # Whole chain was trusted proxies (or empty): fall back to the peer.
327
+ # Whole chain was trusted proxies, or empty: fall back to the peer.
262
328
  remote_addr
263
329
  end
264
330
 
@@ -286,12 +352,16 @@ class Otto
286
352
  # consulted in depth mode. Positions are counted raw (never dropped), so junk
287
353
  # padding cannot shift the index; only the selected entry is validated. If
288
354
  # the chain is shorter than N+1 (a request that may have bypassed the proxy
289
- # tier) or the selected entry is invalid, REMOTE_ADDR is returned rather than
290
- # a spoofable forwarded value.
355
+ # tier), REMOTE_ADDR is returned rather than a spoofable forwarded value.
356
+ # If the selected entry is not a valid address (blank, `unknown`, an
357
+ # obfuscated `_hidden` token), nil is returned: the proxy tier wrote that
358
+ # entry where the client belongs, so the client is unknown, and the peer
359
+ # is a proxy.
291
360
  #
292
361
  # @param env [Hash] Rack environment
293
362
  # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth and #trusted_proxy_header
294
- # @return [String, nil] resolved client IP (REMOTE_ADDR on short chain / invalid target)
363
+ # @return [String, nil] resolved client IP (REMOTE_ADDR on a short chain,
364
+ # nil on an invalid target)
295
365
  def resolve_client_ip_by_depth(env, security_config)
296
366
  remote_addr = env['REMOTE_ADDR']
297
367
  depth = security_config.trusted_proxy_depth.to_i
@@ -306,7 +376,7 @@ class Otto
306
376
  index = chain.length - (depth + 1)
307
377
  return remote_addr if index.negative? # chain shorter than depth + 1
308
378
 
309
- normalize_ip(chain[index].to_s.strip) || remote_addr
379
+ normalize_ip(chain[index].to_s.strip)
310
380
  end
311
381
 
312
382
  # Positional forwarded-hop chain for depth resolution, selected by header
@@ -333,7 +403,9 @@ class Otto
333
403
  end
334
404
 
335
405
  # Split X-Forwarded-For into raw positional entries. `-1` keeps trailing
336
- # empty fields so a malformed/empty hop still counts as a position.
406
+ # empty fields so a malformed/empty hop still counts as a position (depth
407
+ # mode) and stops the walk (CIDR filter mode, which also splits the
408
+ # single-valued X-Real-IP / X-Client-IP fallback with it).
337
409
  #
338
410
  # @param value [String, nil] raw X-Forwarded-For header value
339
411
  # @return [Array<String>]
@@ -347,7 +419,7 @@ class Otto
347
419
  # (raw position counting). The extracted token is only unquoted here; port
348
420
  # and IPv6 brackets are left for normalize_ip when the entry is selected.
349
421
  # Obfuscated (`for=_hidden`) and `for=unknown` identifiers are preserved as
350
- # positions but normalize to nil (→ REMOTE_ADDR fallback if selected).
422
+ # positions but normalize to nil (the resolver returns nil if selected).
351
423
  # Commas separate forwarded-elements (and join multiple Forwarded headers).
352
424
  # A nil/blank header splits to [] (not ['']), so an absent Forwarded header
353
425
  # yields an empty chain and depth's explicit short-chain guard returns
@@ -366,8 +438,8 @@ class Otto
366
438
  # like for="1.2.3.4;junk" would be truncated to a valid-looking IP instead of
367
439
  # being rejected. Only DQUOTE wrappers are stripped: RFC 7239 quoted-strings
368
440
  # use DQUOTE exclusively, so a value like for='1.2.3.4' keeps its quotes,
369
- # fails normalize_ip, and safely falls back to REMOTE_ADDR rather than being
370
- # permissively accepted. This is deliberately stricter than OTS (which strips
441
+ # fails normalize_ip, and resolves to nil rather than being permissively
442
+ # accepted. This is deliberately stricter than OTS (which strips
371
443
  # both ['"]), consistent with depth's other intentionally-not-reconciled-down
372
444
  # safety properties. The raw value (port / IPv6 brackets intact) is left for
373
445
  # normalize_ip when the entry is selected. Returns '' when the element carries
@@ -435,8 +507,9 @@ class Otto
435
507
  # notation (::a.b.c.d) folds on the same terms, on both sides.
436
508
  #
437
509
  # Asymmetric strictness, on purpose:
438
- # - `ip` is runtime data — nil, blank, or malformed input returns false
439
- # (fail-closed for allowlist callers).
510
+ # - `ip` is runtime data — nil, blank, or malformed input, a range such
511
+ # as "203.0.113.7/32" or an IPAddr with a prefix shorter than a host
512
+ # address included, returns false (fail-closed for allowlist callers).
440
513
  # - `cidrs` entries are configuration — an invalid CIDR string raises
441
514
  # IPAddr::InvalidAddressError, because silently skipping an entry
442
515
  # narrows an allowlist or widens a denylist. Validate entries at
@@ -460,6 +533,10 @@ class Otto
460
533
 
461
534
  IPAddr.new(candidate).native
462
535
  end
536
+ # An IPAddr can hold a range, and IPAddr#include? accepts a range wholly
537
+ # inside the entry. The client is one address: anything shorter than a
538
+ # host prefix is malformed runtime data.
539
+ return false unless client.prefix == (client.ipv4? ? 32 : 128)
463
540
 
464
541
  cidrs.any? do |entry|
465
542
  range = entry.is_a?(IPAddr) ? entry : IPAddr.new(entry.to_s)
data/lib/otto/version.rb CHANGED
@@ -3,5 +3,5 @@
3
3
  # frozen_string_literal: true
4
4
 
5
5
  class Otto
6
- VERSION = '2.12.0'
6
+ VERSION = '2.13.0'
7
7
  end
data/lib/otto.rb CHANGED
@@ -140,7 +140,8 @@ class Otto
140
140
  initialize_options(path, opts)
141
141
  initialize_configurations(opts)
142
142
 
143
- Otto.logger.debug "new Otto: #{opts}" if Otto.debug
143
+ # @option, not opts: OptionHash#to_s redacts the MCP bearer tokens.
144
+ Otto.logger.debug "new Otto: #{@option}" if Otto.debug
144
145
  load(path) unless path.nil?
145
146
  super()
146
147
 
@@ -198,20 +199,28 @@ class Otto
198
199
  start_time = Otto::Utils.now_in_μs
199
200
  request = @request_class.new(env)
200
201
  response_raw = nil
202
+ hook_raw = nil
201
203
 
202
204
  begin
203
- # Use pre-built middleware app (built once at initialization)
204
- response_raw = @app.call(env)
205
- rescue StandardError => e
206
- response_raw = handle_error(e, env)
205
+ response_raw = begin
206
+ # Use pre-built middleware app (built once at initialization)
207
+ @app.call(env)
208
+ rescue StandardError => e
209
+ handle_error(e, env)
210
+ end
211
+ # After error handling, so every response source is covered, and before
212
+ # the completion hooks. The method is normalized the same way the router
213
+ # normalizes it for dispatch.
214
+ response_raw, hook_raw = head_response_pair(response_raw) if env['REQUEST_METHOD'].to_s.upcase == 'HEAD'
207
215
  ensure
208
216
  # Execute request completion hooks if any are registered
209
217
  unless @request_complete_callbacks.empty?
210
218
  begin
211
219
  duration = Otto::Utils.now_in_μs - start_time
220
+ hooked = hook_raw || response_raw
212
221
  # Wrap response tuple in Otto::Response for developer-friendly API
213
222
  # Otto's hook API should provide nice abstractions like Otto::Request/Response
214
- response = @response_class.new(response_raw[2], response_raw[0], response_raw[1])
223
+ response = @response_class.new(hooked[2], hooked[0], hooked[1])
215
224
  @request_complete_callbacks.each do |callback|
216
225
  callback.call(request, response, duration)
217
226
  end
@@ -296,10 +305,12 @@ class Otto
296
305
  end
297
306
 
298
307
  def initialize_options(_path, opts)
299
- @option = {
308
+ # An OptionHash, so neither Otto#inspect nor the FrozenError from a write
309
+ # after the freeze prints the MCP bearer tokens.
310
+ @option = Otto::Core::OptionHash.build({
300
311
  public: nil,
301
312
  locale: 'en',
302
- }.merge(opts)
313
+ }.merge(opts))
303
314
  @route_handler_factory = opts[:route_handler_factory] || Otto::RouteHandlers::HandlerFactory
304
315
  end
305
316
 
@@ -423,7 +434,24 @@ class Otto
423
434
 
424
435
  args.first(params.count { |type, _name| POSITIONAL_PARAMETER_TYPES.include?(type) })
425
436
  end
426
- private :validate_fallback_response!, :rack_triple?, :resolve_fallback_response, :fallback_call_args
437
+
438
+ # The two triples Otto#call needs for a HEAD request. HEAD is dispatched to
439
+ # the GET route when no HEAD route is declared, so the handler writes a
440
+ # body; Otto::Static.head_response replaces it for the server. It does not
441
+ # close the handler's body itself (the server's close of the returned body
442
+ # does), so this cannot raise. The completion hooks get a plain empty Array
443
+ # instead of that closing body, so nothing a hook does to the body can close
444
+ # the handler's body early.
445
+ #
446
+ # @param response [Array] the Rack triple from dispatch or error handling
447
+ # @return [Array(Array, Array)] the triple for the server and the one for the hooks
448
+ def head_response_pair(response)
449
+ served = Otto::Static.head_response(response)
450
+ [served, [served[0], served[1], []]]
451
+ end
452
+
453
+ private :validate_fallback_response!, :rack_triple?, :resolve_fallback_response, :fallback_call_args,
454
+ :head_response_pair
427
455
 
428
456
  # Class methods for Otto framework providing singleton access and configuration
429
457
  module ClassMethods
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: otto
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.12.0
4
+ version: 2.13.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Delano Mandelbaum
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-09-26 00:00:00.000000000 Z
11
+ date: 2026-11-01 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: concurrent-ruby
@@ -122,6 +122,8 @@ files:
122
122
  - docs/adr/adr-002-multi-strategy-authentication-and-authorization.md
123
123
  - docs/adr/adr-003-caddy-tls-route-based-integration.md
124
124
  - docs/adr/adr-004-separate-compatibility-from-security-maintenance.md
125
+ - docs/audits/2026-09-28-v2.12.0-code-audit.md
126
+ - docs/audits/README.md
125
127
  - docs/guides/authentication.md
126
128
  - docs/guides/caddy-tls.md
127
129
  - docs/guides/configuration_freezing.md
@@ -222,6 +224,8 @@ files:
222
224
  - lib/otto/core/lifecycle_hooks.rb
223
225
  - lib/otto/core/middleware_management.rb
224
226
  - lib/otto/core/middleware_stack.rb
227
+ - lib/otto/core/option_hash.rb
228
+ - lib/otto/core/redacted_inspect.rb
225
229
  - lib/otto/core/router.rb
226
230
  - lib/otto/core/static_mounts.rb
227
231
  - lib/otto/core/uri_generator.rb