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
data/lib/otto/static.rb CHANGED
@@ -2,17 +2,19 @@
2
2
  #
3
3
  # frozen_string_literal: true
4
4
 
5
+ require 'rack/utils'
6
+
5
7
  class Otto
6
8
  # Static response utilities for common HTTP responses
7
9
  module Static
8
10
  extend self
9
11
 
10
- def server_error
11
- [500, security_headers.merge({ 'content-type' => 'text/plain' }), ['Server error']]
12
+ def server_error(security_config = nil)
13
+ [500, security_headers(security_config).merge({ 'content-type' => 'text/plain' }), ['Server error']]
12
14
  end
13
15
 
14
- def not_found
15
- [404, security_headers.merge({ 'content-type' => 'text/plain' }), ['Not Found']]
16
+ def not_found(security_config = nil)
17
+ [404, security_headers(security_config).merge({ 'content-type' => 'text/plain' }), ['Not Found']]
16
18
  end
17
19
 
18
20
  # Return a per-request copy of a Rack triple so callers can never hand a
@@ -39,6 +41,67 @@ class Otto
39
41
  [status, copy_headers(headers), body.is_a?(Array) ? body.dup : body]
40
42
  end
41
43
 
44
+ # Replace the body of a response to a HEAD request with an empty one.
45
+ #
46
+ # Rack::Lint rejects a body for HEAD: "Response body was given for HEAD
47
+ # request, but should be empty" (rack/lint.rb). The status and headers,
48
+ # including any content-length the handler set, are kept.
49
+ #
50
+ # Puma and Rack::ContentLength derive content-length from an Array body
51
+ # through #to_ary, so an empty Array would advertise 0 for HEAD while GET
52
+ # advertises the real length, which RFC 9110 section 8.6 forbids. When the
53
+ # handler's body is a plain Array and the response has no content-length
54
+ # or transfer-encoding and a status that allows content, content-length is
55
+ # set from the Array here instead (a plain Array has no #close, so reading
56
+ # it has no side effect). The returned body has no #to_ary, so nothing
57
+ # downstream computes a length from it or closes it early; the handler's
58
+ # body is closed when the server closes the returned body, the same point
59
+ # at which a GET body is closed. A new triple is returned rather than
60
+ # writing into +response+, which may be frozen or shared.
61
+ #
62
+ # @param response [Array] a Rack triple +[status, headers, body]+
63
+ # @return [Array] +[status, headers, HeadBody]+
64
+ def head_response(response)
65
+ status, headers, body = response
66
+ if array_length_applies?(status, headers, body)
67
+ headers = copy_headers(headers)
68
+ headers['content-length'] = body.sum { |part| part.to_s.bytesize }.to_s
69
+ end
70
+ [status, headers, HeadBody.new(body)]
71
+ end
72
+
73
+ # Headers whose presence means #head_response leaves content-length alone.
74
+ HEAD_LENGTH_HEADERS = %w[content-length transfer-encoding].freeze
75
+
76
+ # Whether #head_response should set content-length from an Array body.
77
+ def array_length_applies?(status, headers, body)
78
+ return false unless body.is_a?(Array) && headers
79
+ return false if Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key?(status.to_i)
80
+
81
+ headers.each_key.none? { |key| HEAD_LENGTH_HEADERS.include?(key.to_s.downcase) }
82
+ end
83
+ private :array_length_applies?
84
+
85
+ # Empty body for a HEAD response. It yields nothing and has no #to_ary.
86
+ # Closing it closes the handler's body once.
87
+ class HeadBody
88
+ def initialize(original)
89
+ @original = original
90
+ @closed = false
91
+ end
92
+
93
+ def each; end
94
+
95
+ def close
96
+ return if @closed
97
+
98
+ @closed = true
99
+ @original.close if @original.respond_to?(:close)
100
+ end
101
+
102
+ def closed? = @closed
103
+ end
104
+
42
105
  # Copy a Rack headers container, keeping its class and copying Array values.
43
106
  #
44
107
  # @param headers [Hash, Rack::Headers, nil] the headers to copy
@@ -53,12 +116,13 @@ class Otto
53
116
  copied
54
117
  end
55
118
 
56
- def security_headers
119
+ def security_headers(security_config = nil)
57
120
  {
58
121
  'x-frame-options' => 'DENY',
59
122
  'x-content-type-options' => 'nosniff',
60
123
  'x-xss-protection' => '1; mode=block',
61
- 'referrer-policy' => 'strict-origin-when-cross-origin',
124
+ 'referrer-policy' => security_config&.referrer_policy ||
125
+ Otto::Security::Config::DEFAULT_REFERRER_POLICY,
62
126
  }
63
127
  end
64
128
 
@@ -0,0 +1,148 @@
1
+ # lib/otto/testing.rb
2
+ #
3
+ # frozen_string_literal: true
4
+
5
+ require 'rack/mock'
6
+ require_relative '../otto'
7
+
8
+ class Otto
9
+ # Test support for applications built on Otto, independent of the test
10
+ # framework. `require 'otto'` does not load this file; require
11
+ # 'otto/testing' from a test helper. Loading it is the opt-in for the
12
+ # resets below, which production code must never call.
13
+ #
14
+ # @example RSpec
15
+ # require 'otto/testing'
16
+ # RSpec.configure { |c| c.before { Otto::Testing.reset! } }
17
+ #
18
+ # @example Minitest
19
+ # require 'otto/testing'
20
+ # class Minitest::Test
21
+ # def before_setup
22
+ # super
23
+ # Otto::Testing.reset!
24
+ # end
25
+ # end
26
+ #
27
+ # @example Tryouts (setup runs once per file, so reset inside each case)
28
+ # ## a depth-mode app reading Forwarded
29
+ # Otto::Testing.reset!
30
+ # Otto.new(nil, trusted_proxy_depth: 1, trusted_proxy_header: 'Forwarded')
31
+ module Testing
32
+ # Stands in for the application behind IPPrivacyMiddleware; only the env
33
+ # the middleware leaves behind is of interest.
34
+ RESOLVED_APP = ->(_env) { [200, {}, []] }
35
+ private_constant :RESOLVED_APP
36
+
37
+ module_function
38
+
39
+ # Clear the process-global state Otto accumulates across Otto.new calls,
40
+ # so one test's applications cannot decide whether the next test's raise.
41
+ #
42
+ # Today that is the forwarding-family registry and
43
+ # Rack::Request.forwarded_priority, which Otto pins from
44
+ # trusted_proxy_header. Rack's setting is one per process, so a second
45
+ # application choosing a different family raises ArgumentError; in a
46
+ # suite that builds applications with different families, the outcome
47
+ # would otherwise depend on test order.
48
+ #
49
+ # Call it before every test (or after every test), not once per suite.
50
+ #
51
+ # @return [nil]
52
+ def reset!
53
+ Otto::Security::Config.send(:reset_rack_forwarding_family!)
54
+ nil
55
+ end
56
+
57
+ # Build a Rack env as IPPrivacyMiddleware leaves it for a request arriving
58
+ # directly from client_ip: env['otto.client_ip'] (masked under the
59
+ # privacy profile in force), env['otto.ip_match'] over the unmasked
60
+ # address, the rewritten REMOTE_ADDR, and the proxy-trust verdict when
61
+ # trust is configured.
62
+ #
63
+ # Use it instead of writing env['otto.client_ip'] by hand. A hand-written
64
+ # value looks to the middleware like a prior pass, so the precise
65
+ # otto.ip_match is never built and every CIDR check denies.
66
+ #
67
+ # security_config is required because the app's own IPPrivacyMiddleware
68
+ # keeps whatever this resolution produced: pass the application's
69
+ # (otto.security_config) so the privacy profile and proxy trust match the
70
+ # app under test. nil means an unconfigured middleware: public addresses
71
+ # masked, no proxy trust.
72
+ #
73
+ # The request is direct, so the headers in
74
+ # Otto::Utils::CLIENT_ADDRESS_HEADERS (X-Forwarded-For, X-Real-IP,
75
+ # X-Client-IP, Forwarded) raise ArgumentError: under a config
76
+ # that trusts the peer they would move the resolved address away from
77
+ # client_ip. For a relayed request, build the env with REMOTE_ADDR and the
78
+ # forwarded headers and call {.resolve_client_ip!}.
79
+ #
80
+ # @param uri [String] passed to Rack::MockRequest.env_for
81
+ # @param client_ip [String, nil] the connecting address; nil builds a
82
+ # request with no resolvable client IP, whose otto.ip_match denies
83
+ # every range and whose env['otto.client_ip'] is nil
84
+ # @param security_config [Otto::Security::Config, nil]
85
+ # @param rack_options [Hash] remaining Rack::MockRequest.env_for options
86
+ # (method:, params:, input:, and String env keys such as
87
+ # 'HTTP_USER_AGENT')
88
+ # @return [Hash] the env
89
+ # @raise [ArgumentError] if rack_options carry a forwarded-for header
90
+ #
91
+ # @example
92
+ # env = Otto::Testing.env_for('/admin', client_ip: '203.0.113.9',
93
+ # security_config: otto.security_config)
94
+ # env['otto.client_ip'] # => "203.0.113.0"
95
+ # env['otto.ip_match'].call(['203.0.113.9/32']) # => true
96
+ def env_for(uri = '/', client_ip:, security_config:, **rack_options)
97
+ forwarded = Otto::Utils::CLIENT_ADDRESS_HEADERS & rack_options.keys
98
+ unless forwarded.empty?
99
+ raise ArgumentError, "env_for builds a direct request from client_ip; #{forwarded.join(', ')} " \
100
+ 'would change which address resolves. Build the env yourself and call ' \
101
+ 'Otto::Testing.resolve_client_ip! for a relayed request.'
102
+ end
103
+
104
+ env = Rack::MockRequest.env_for(uri, rack_options)
105
+ if client_ip.nil?
106
+ env.delete('REMOTE_ADDR')
107
+ else
108
+ env['REMOTE_ADDR'] = client_ip
109
+ end
110
+ resolve_client_ip!(env, security_config)
111
+ end
112
+
113
+ # Run IPPrivacyMiddleware over an existing env, in place, so it carries
114
+ # the keys the middleware writes, all derived from one resolution. Use it
115
+ # for relayed requests: REMOTE_ADDR is the proxy and the forwarded headers
116
+ # carry the client.
117
+ #
118
+ # Pass the application's security config. Its proxy trust decides whether
119
+ # the forwarded headers are read at all; resolved without it, the proxy
120
+ # becomes the client, and the app's middleware keeps that result.
121
+ #
122
+ # @param env [Hash] Rack env, with REMOTE_ADDR and any forwarded headers
123
+ # @param security_config [Otto::Security::Config, nil] see {.env_for}
124
+ # @return [Hash] the same env
125
+ # @raise [ArgumentError] if env was already resolved, since the
126
+ # middleware would keep the earlier result instead of applying
127
+ # security_config
128
+ # @raise [RuntimeError] if the middleware returned without installing
129
+ # otto.ip_match, which every path that resolves an env writes
130
+ def resolve_client_ip!(env, security_config)
131
+ if env.key?('otto.client_ip') || env.key?('otto.ip_match')
132
+ raise ArgumentError, 'env already carries otto.client_ip or otto.ip_match, so IPPrivacyMiddleware ' \
133
+ 'would keep that result instead of resolving under this security_config'
134
+ end
135
+
136
+ Otto::Security::Middleware::IPPrivacyMiddleware.new(RESOLVED_APP, security_config).call(env)
137
+ # The middleware's response is discarded, so check its effect instead: a
138
+ # path that answered before resolving would otherwise hand back an env
139
+ # that looks built and is not.
140
+ unless env.key?('otto.ip_match')
141
+ raise 'IPPrivacyMiddleware returned without installing otto.ip_match; Otto::Testing ' \
142
+ 'no longer matches the middleware and needs updating'
143
+ end
144
+
145
+ env
146
+ end
147
+ end
148
+ end
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
@@ -45,6 +46,50 @@ class Otto
45
46
  # fallback scan cannot drift.
46
47
  RELAY_MARKER_HEADERS = (FORWARDED_FOR_HEADERS + FORWARDED_AUTHORITY_HEADERS).uniq.freeze
47
48
 
49
+ # Headers the client-IP resolver may read an address from: the
50
+ # forwarded-for family (the CIDR walk, and X-Forwarded-For in depth mode)
51
+ # and RFC 7239 Forwarded (depth mode with trusted_proxy_header 'Forwarded'
52
+ # or 'Both'). A header resolve_client_ip starts reading belongs here, so
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.
56
+ CLIENT_ADDRESS_HEADERS = (FORWARDED_FOR_HEADERS + %w[HTTP_FORWARDED]).freeze
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
+
48
93
  # Special-use IPv4/IPv6 ranges that IPAddr's #private?/#loopback?/#link_local?
49
94
  # predicates do not cover but that should still be treated as non-public
50
95
  # (e.g. when picking the real client out of a forwarded chain).
@@ -100,20 +145,21 @@ class Otto
100
145
  # scrub invalid/undefined bytes, and strip a single trailing slash.
101
146
  #
102
147
  # This is the SINGLE SOURCE OF TRUTH shared by the router
103
- # (Otto::Core::Router#handle_request, which compares the result against its
104
- # literal-route table) and Otto::CaddyTLS::LocalhostGuard (which compares it
105
- # against the guarded endpoint). The two MUST normalize identically: if a
106
- # crafted path — a trailing slash, a percent-encoded byte, an invalid UTF-8
107
- # byte — normalized differently in the guard than in the router, the router
108
- # could dispatch a request the guard let through, bypassing the loopback
109
- # check. One implementation makes that drift impossible.
110
- #
111
- # Mirrors the empty-path handling and :replace scrubbing the router applies.
112
- # Robust to invalid input: Rack::Utils.unescape raises ArgumentError on an
113
- # already-invalid byte sequence (a raw \xFF in the path), so that is caught
114
- # and the raw string is scrubbed instead — a percent-encoded invalid byte
115
- # (%FF) decodes to the same invalid byte and is scrubbed identically, so the
116
- # two crafted forms normalize alike. The method itself does not raise.
148
+ # (Otto::Core::Router#handle_request, through #routing_path) and every guard
149
+ # that compares a request path or a configured path against what the router
150
+ # dispatches (Otto::CaddyTLS::LocalhostGuard, Otto::MCP.endpoint_path?).
151
+ # For a request, call #routing_path rather than passing PATH_INFO here
152
+ # yourself. Guard and router MUST normalize identically: if a crafted
153
+ # path — a trailing slash, a percent-encoded byte, an invalid UTF-8 byte —
154
+ # normalized differently in the guard than in the router, the router could
155
+ # dispatch a request the guard let through. One implementation makes that
156
+ # drift impossible.
157
+ #
158
+ # Robust to invalid input. Rack::Utils.unescape raises ArgumentError on a
159
+ # malformed escape (%zz, a trailing %) and on an invalid byte in a
160
+ # UTF-8-tagged string (a raw \xFF); either way the raw string is kept.
161
+ # Invalid UTF-8 is scrubbed after that, so a raw \xFF and a percent-encoded
162
+ # %FF normalize alike. The method itself does not raise.
117
163
  #
118
164
  # @param raw_path [String, nil] a raw PATH_INFO or a configured endpoint
119
165
  # @return [String] normalized path suitable for exact literal comparison
@@ -131,18 +177,64 @@ class Otto
131
177
  .gsub(%r{/$}, '')
132
178
  end
133
179
 
180
+ # The path Otto's router matches for this request. Use it in any code that
181
+ # judges a request by its path before the router sees it: guards,
182
+ # throttles, session skips, audit filters.
183
+ #
184
+ # The router does not match raw PATH_INFO. It matches this value, and
185
+ # Otto::Core::Router#handle_request calls this method to get it, so a guard
186
+ # that reads routing_path sees the path the router dispatches on. A guard
187
+ # that reads anything else can see a different path, and when it matches
188
+ # less than the router does the difference is a bypass: GET /%63olonel is
189
+ # '/%63olonel' as raw PATH_INFO and '/colonel' to the router.
190
+ #
191
+ # By default the result is mount-relative. Rack::URLMap
192
+ # (`map '/api' { run otto }`) moves the mount prefix into SCRIPT_NAME and
193
+ # leaves the remainder in PATH_INFO, which is all the router sees; this is
194
+ # the form to compare against paths as written in a routes file.
195
+ #
196
+ # With +include_mount: true+ SCRIPT_NAME and PATH_INFO are joined and then
197
+ # normalized as one string, giving the request's full path. That is
198
+ # the form for middleware shared by several mounted apps and configured
199
+ # with external URLs: inside an app mounted at /api/v2, '/status' is the
200
+ # mount-relative path and '/api/v2/status' the mounted one, and matching
201
+ # the mount-relative form would also match every other app's /status.
202
+ #
203
+ # The value is normalize_path output, so root is '' (the router's literal
204
+ # table keys root the same way) and a configured path must go through
205
+ # normalize_path before an exact comparison. Never raises: a malformed
206
+ # escape such as %zz is kept as written.
207
+ #
208
+ # Not memoized: middleware may rewrite PATH_INFO or SCRIPT_NAME, and the
209
+ # router must see the value as it stands at dispatch.
210
+ #
211
+ # @param env [Hash] Rack environment
212
+ # @param include_mount [Boolean] prepend SCRIPT_NAME (the mount prefix)
213
+ # @return [String] normalized path
214
+ def routing_path(env, include_mount: false)
215
+ path = env['PATH_INFO']
216
+ path = "#{env['SCRIPT_NAME']}#{path}" if include_mount
217
+ normalize_path(path)
218
+ end
219
+
134
220
  # Validate and normalize an IP address (IPv4 and IPv6).
135
221
  #
136
222
  # Strips an optional port (IPv6-safe), validates with IPAddr, and returns
137
223
  # the cleaned address string, or nil if the input is blank or malformed.
138
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
+ #
139
231
  # @param ip [String, nil] candidate address, optionally with a port
140
232
  # @return [String, nil] cleaned IP string, or nil if invalid
141
233
  def normalize_ip(ip)
142
234
  return nil if ip.nil? || ip.empty?
143
235
 
144
236
  candidate = strip_ip_port(ip.strip)
145
- return nil if candidate.nil? || candidate.empty?
237
+ return nil if candidate.nil? || candidate.empty? || candidate.include?('/')
146
238
 
147
239
  # IPAddr validates both IPv4 and IPv6; raises for malformed input
148
240
  IPAddr.new(candidate)
@@ -176,13 +268,26 @@ class Otto
176
268
  # This is the single canonical resolver shared by IPPrivacyMiddleware
177
269
  # ("resolve once") and Otto::Request#client_ipaddress (its no-middleware
178
270
  # fallback), so both paths agree on which headers to trust and how to walk
179
- # a proxy chain. It walks the forwarded chain left-to-right and returns the
180
- # first address that is not itself a trusted proxy; if the peer is not a
181
- # 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.
182
286
  #
183
287
  # @param env [Hash] Rack environment
184
288
  # @param security_config [Otto::Security::Config, nil] config exposing #trusted_proxy?
185
- # @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
186
291
  def resolve_client_ip(env, security_config)
187
292
  remote_addr = env['REMOTE_ADDR']
188
293
 
@@ -197,19 +302,29 @@ class Otto
197
302
  # is the client. Don't honor forwarded headers from untrusted sources.
198
303
  return remote_addr unless security_config&.trusted_proxy?(remote_addr)
199
304
 
200
- forwarded_ips = FORWARDED_FOR_HEADERS
201
- .filter_map { |header| env[header] }
202
- .flat_map { |value| value.split(/,\s*/) }
203
-
204
- 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|
205
322
  clean_ip = normalize_ip(candidate.strip)
206
- next unless clean_ip
207
-
208
- # First address in the chain that isn't a known proxy is the client.
323
+ return nil unless clean_ip
209
324
  return clean_ip unless security_config.trusted_proxy?(clean_ip)
210
325
  end
211
326
 
212
- # 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.
213
328
  remote_addr
214
329
  end
215
330
 
@@ -237,12 +352,16 @@ class Otto
237
352
  # consulted in depth mode. Positions are counted raw (never dropped), so junk
238
353
  # padding cannot shift the index; only the selected entry is validated. If
239
354
  # the chain is shorter than N+1 (a request that may have bypassed the proxy
240
- # tier) or the selected entry is invalid, REMOTE_ADDR is returned rather than
241
- # 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.
242
360
  #
243
361
  # @param env [Hash] Rack environment
244
362
  # @param security_config [Otto::Security::Config] config exposing #trusted_proxy_depth and #trusted_proxy_header
245
- # @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)
246
365
  def resolve_client_ip_by_depth(env, security_config)
247
366
  remote_addr = env['REMOTE_ADDR']
248
367
  depth = security_config.trusted_proxy_depth.to_i
@@ -257,7 +376,7 @@ class Otto
257
376
  index = chain.length - (depth + 1)
258
377
  return remote_addr if index.negative? # chain shorter than depth + 1
259
378
 
260
- normalize_ip(chain[index].to_s.strip) || remote_addr
379
+ normalize_ip(chain[index].to_s.strip)
261
380
  end
262
381
 
263
382
  # Positional forwarded-hop chain for depth resolution, selected by header
@@ -284,7 +403,9 @@ class Otto
284
403
  end
285
404
 
286
405
  # Split X-Forwarded-For into raw positional entries. `-1` keeps trailing
287
- # 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).
288
409
  #
289
410
  # @param value [String, nil] raw X-Forwarded-For header value
290
411
  # @return [Array<String>]
@@ -298,7 +419,7 @@ class Otto
298
419
  # (raw position counting). The extracted token is only unquoted here; port
299
420
  # and IPv6 brackets are left for normalize_ip when the entry is selected.
300
421
  # Obfuscated (`for=_hidden`) and `for=unknown` identifiers are preserved as
301
- # positions but normalize to nil (→ REMOTE_ADDR fallback if selected).
422
+ # positions but normalize to nil (the resolver returns nil if selected).
302
423
  # Commas separate forwarded-elements (and join multiple Forwarded headers).
303
424
  # A nil/blank header splits to [] (not ['']), so an absent Forwarded header
304
425
  # yields an empty chain and depth's explicit short-chain guard returns
@@ -317,8 +438,8 @@ class Otto
317
438
  # like for="1.2.3.4;junk" would be truncated to a valid-looking IP instead of
318
439
  # being rejected. Only DQUOTE wrappers are stripped: RFC 7239 quoted-strings
319
440
  # use DQUOTE exclusively, so a value like for='1.2.3.4' keeps its quotes,
320
- # fails normalize_ip, and safely falls back to REMOTE_ADDR rather than being
321
- # 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
322
443
  # both ['"]), consistent with depth's other intentionally-not-reconciled-down
323
444
  # safety properties. The raw value (port / IPv6 brackets intact) is left for
324
445
  # normalize_ip when the entry is selected. Returns '' when the element carries
@@ -386,8 +507,9 @@ class Otto
386
507
  # notation (::a.b.c.d) folds on the same terms, on both sides.
387
508
  #
388
509
  # Asymmetric strictness, on purpose:
389
- # - `ip` is runtime data — nil, blank, or malformed input returns false
390
- # (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).
391
513
  # - `cidrs` entries are configuration — an invalid CIDR string raises
392
514
  # IPAddr::InvalidAddressError, because silently skipping an entry
393
515
  # narrows an allowlist or widens a denylist. Validate entries at
@@ -411,6 +533,10 @@ class Otto
411
533
 
412
534
  IPAddr.new(candidate).native
413
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)
414
540
 
415
541
  cidrs.any? do |entry|
416
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.11.0'
6
+ VERSION = '2.13.0'
7
7
  end