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
@@ -3,11 +3,13 @@
3
3
  # frozen_string_literal: true
4
4
 
5
5
  require_relative '../config'
6
+ require_relative '../csrf_validation'
6
7
 
7
8
  class Otto
8
9
  module Security
9
10
  module Middleware
10
- # Global middleware that injects CSRF tokens into HTML responses.
11
+ # Global middleware that injects CSRF tokens into HTML responses and
12
+ # sets the CSRF binding cookie on responses to safe requests.
11
13
  #
12
14
  # Token *enforcement* deliberately does NOT live here. This middleware
13
15
  # runs ahead of route matching, so it cannot see per-route options like
@@ -19,6 +21,8 @@ class Otto
19
21
  # forms and meta tags can carry it — which is method/content-type based
20
22
  # and correctly stays global.
21
23
  class CSRFMiddleware
24
+ include Otto::Security::CSRFValidation
25
+
22
26
  def initialize(app, config = nil)
23
27
  @app = app
24
28
  @config = config || Otto::Security::Config.new
@@ -27,76 +31,238 @@ class Otto
27
31
  def call(env)
28
32
  return @app.call(env) unless @config.csrf_enabled?
29
33
 
30
- request = Otto::Request.new(env)
31
- response = @app.call(env)
32
- response = inject_csrf_token(request, response) if html_response?(response)
33
- response
34
+ request = Otto::Request.new(env)
35
+ # Read before @app.call: a session store inside this middleware
36
+ # replaces rack.session there (see #record_store_minted_binding).
37
+ outer_session = env['rack.session']
38
+ response = @app.call(env)
39
+ response = inject_csrf_token(request, with_copied_headers(response), outer_session) if html_response?(response)
40
+
41
+ apply_binding_cookie(request, response)
34
42
  end
35
43
 
36
44
  private
37
45
 
38
- def inject_csrf_token(request, response)
39
- return response unless response.is_a?(Array) && response.length >= 3
46
+ # +response+ with a copy of its headers, so #inject_csrf_token can add
47
+ # Cache-Control and Content-Length without changing the app's
48
+ # headers, which the app may freeze or share between responses.
49
+ def with_copied_headers(response)
50
+ response.dup.tap { |copy| copy[1] = response[1].dup }
51
+ end
40
52
 
41
- status, headers, body = response
42
- content_type = headers.find { |k, _v| k.downcase == 'content-type' }&.last
53
+ # Sets the binding cookie on any response, HTML or not, to a safe
54
+ # request that resolved a binding the client does not already send:
55
+ # one minted, or read from csrf_session_key, which
56
+ # Otto::Security::Config#get_or_create_session_id records in
57
+ # otto.csrf_binding (as does #record_store_minted_binding for a store
58
+ # that runs inside this middleware). A JSON client that never loads an
59
+ # HTML page needs it too, or it would get a new binding, and a 403, on
60
+ # every request.
61
+ #
62
+ # A session id the request already had and a binding read from a
63
+ # cookie are not recorded, so they are never copied: the client sends
64
+ # them again, and a copy would sit in a second cookie whose lifetime
65
+ # and attributes the application does not configure. A session id
66
+ # read from a cookie someone planted would outlive the session cookie
67
+ # there.
68
+ #
69
+ # An unsafe request does not set it: one that passes the CSRF check
70
+ # already carries its binding, and a cross-site one arrives without
71
+ # the SameSite=Lax cookie, so a binding set on its response would
72
+ # replace the victim's and void their open forms. The app's headers
73
+ # are copied rather than changed, as the app may freeze them or share
74
+ # them between responses.
75
+ def apply_binding_cookie(request, response)
76
+ binding_id = request.env['otto.csrf_binding']
77
+ return response unless binding_id && safe_method?(request.request_method)
78
+ return response unless response.is_a?(Array) && response.length >= 2
43
79
 
44
- return response unless content_type&.include?('text/html')
80
+ new_cookie = binding_cookie(request, binding_id)
81
+ return response unless new_cookie
45
82
 
46
- # Get or create session ID
47
- session_id = @config.get_or_create_session_id(request)
83
+ headers = response[1].dup
84
+ append_binding_cookie(headers, new_cookie)
85
+ response.dup.tap { |copy| copy[1] = headers }
86
+ end
87
+
88
+ def inject_csrf_token(request, response, outer_session)
89
+ return response unless response.is_a?(Array) && response.length >= 3
48
90
 
49
- # Ensure session ID is saved to cookie if it was newly created
50
- ensure_session_cookie(request, headers, session_id)
91
+ status, headers, body = response
92
+ return response unless html_content_type?(headers)
93
+
94
+ session_id = token_binding(request, outer_session)
95
+ return response unless session_id
51
96
 
52
97
  # Generate new CSRF token
53
98
  csrf_token = @config.generate_csrf_token(session_id)
54
99
 
55
- # Inject meta tag into HTML head
56
- body_content = body.respond_to?(:join) ? body.join : body.to_s
100
+ # Inject meta tag into HTML head. Rack lets middleware read a body
101
+ # itself only through #to_ary, which also closes it, so the parts
102
+ # it returns replace the body. Any other body, such as a file or a
103
+ # stream, is returned unread.
104
+ return response unless body.respond_to?(:to_ary)
105
+
106
+ # The parts are searched as bytes. The <head> pattern and the meta
107
+ # tag are ASCII, so a part with invalid bytes, or parts in
108
+ # incompatible encodings, can neither raise here nor change. The
109
+ # page then gets the encoding its parts have when joined as text,
110
+ # and stays binary only when they cannot be joined.
111
+ parts = body.to_ary
112
+ strings = parts.map(&:to_s)
113
+ body_content = strings.map(&:b).join
57
114
 
58
115
  head_open_tag = /<head(?:\s[^>]*)?>/i
59
116
  if body_content.match?(head_open_tag)
60
- meta_tag = %(<meta name="csrf-token" content="#{csrf_token}">)
61
- body_content = body_content.sub(head_open_tag) { |tag| "#{tag}\n#{meta_tag}" }
117
+ meta_tag = %(<meta name="csrf-token" content="#{csrf_token}">)
118
+ body_content = body_content.sub(head_open_tag) { |tag| "#{tag}\n#{meta_tag}" }
119
+ text_encoding = begin
120
+ strings.join.encoding
121
+ rescue Encoding::CompatibilityError
122
+ nil
123
+ end
124
+ body_content.force_encoding(text_encoding) if text_encoding
62
125
 
63
126
  # Update content length if present
64
127
  content_length_key = headers.keys.find { |k| k.downcase == 'content-length' }
65
128
  headers[content_length_key] = body_content.bytesize.to_s if content_length_key
129
+ keep_out_of_shared_caches(headers)
66
130
 
67
131
  [status, headers, [body_content]]
68
132
  else
69
- response
133
+ [status, headers, parts]
70
134
  end
71
135
  end
72
136
 
73
- def ensure_session_cookie(request, headers, session_id)
74
- # Check if session ID already exists in cookies
75
- existing_cookie = request.cookies['_otto_session']
76
- return if existing_cookie == session_id
137
+ # The binding the injected token is bound to. A safe request gets one
138
+ # minted when it has none. An unsafe request uses only the binding it
139
+ # already has: a cross-site POST to a csrf=exempt route arrives
140
+ # without the SameSite=Lax binding cookie, and a binding minted for
141
+ # it would replace the victim's (or, behind a session store, commit a
142
+ # new session over theirs). Without a binding the page gets no token.
143
+ def token_binding(request, outer_session)
144
+ return @config.existing_session_id(request) unless safe_method?(request.request_method)
145
+
146
+ existing_id = @config.existing_session_id(request)
147
+ binding_id = @config.get_or_create_session_id(request)
148
+ record_store_minted_binding(request, binding_id, outer_session) unless existing_id
149
+ binding_id
150
+ end
151
+
152
+ # Records a binding minted here in otto.csrf_binding when it is the id
153
+ # a session store created for Otto's write and that store will not
154
+ # send it. get_or_create_session_id does not record a store's id,
155
+ # because the store sends it in its own cookie when it commits. That
156
+ # holds for +outer_session+, set up by a store that wraps this
157
+ # middleware and commits after it returns. A store added inside this
158
+ # middleware (with otto.use before CSRF protection is enabled) has
159
+ # committed before the token is injected, so it never sends the id it
160
+ # creates here, and only the binding cookie can carry it.
161
+ # The id is new, so this copies nothing a client could have planted.
162
+ def record_store_minted_binding(request, binding_id, outer_session)
163
+ return if session_id_of?(outer_session, binding_id)
164
+
165
+ request.env['otto.csrf_binding'] = binding_id
166
+ end
77
167
 
78
- # Set the session cookie
79
- cookie_value = "#{session_id}; Path=/; HttpOnly; SameSite=Lax"
168
+ # Whether +binding_id+ is the id of +session+.
169
+ def session_id_of?(session, binding_id)
170
+ session.respond_to?(:id) && session.id.to_s == binding_id
171
+ rescue StandardError
172
+ false
173
+ end
174
+
175
+ # The Set-Cookie value for the binding cookie, or nil when the request
176
+ # already carries +session_id+ in it. On HTTPS the cookie is
177
+ # __Host-otto_session (Secure, Path=/, no Domain); on HTTP it is
178
+ # _otto_session. See Otto::Security::Config#csrf_binding_cookie_name.
179
+ #
180
+ # The value is URL-encoded because Rack URL-decodes cookie values when
181
+ # it parses them (Rack::Utils.parse_cookies_header). A binding that is
182
+ # not a hex token, such as a value an app stored under
183
+ # csrf_session_key, then reads back unchanged instead of being cut at
184
+ # a ';' or decoded a second time.
185
+ def binding_cookie(request, session_id)
186
+ cookie_name = @config.csrf_binding_cookie_name(request)
187
+ return if request.cookies[cookie_name] == session_id
188
+
189
+ cookie_value = "#{Rack::Utils.escape(session_id.to_s)}; Path=/; HttpOnly; SameSite=Lax"
80
190
  cookie_value += '; Secure' if request.scheme == 'https'
191
+ "#{cookie_name}=#{cookie_value}"
192
+ end
81
193
 
82
- # Handle existing Set-Cookie headers
83
- existing_cookies = headers['set-cookie'] || headers['Set-Cookie']
84
- if existing_cookies
85
- # Append to existing cookies (handle both string and array formats)
86
- if existing_cookies.is_a?(Array)
87
- existing_cookies << "_otto_session=#{cookie_value}"
88
- else
89
- headers['set-cookie'] = [existing_cookies, "_otto_session=#{cookie_value}"]
90
- end
91
- else
92
- headers['set-cookie'] = "_otto_session=#{cookie_value}"
194
+ # Adds +cookie+ to the Set-Cookie header. An existing value, String or
195
+ # Array, is replaced by a new Array rather than appended to in place,
196
+ # since the app may freeze it or share it between responses. A plain
197
+ # Hash that spells the header Set-Cookie keeps that key.
198
+ def append_set_cookie(headers, cookie)
199
+ key = !headers.key?('set-cookie') && headers.key?('Set-Cookie') ? 'Set-Cookie' : 'set-cookie'
200
+ existing = headers[key]
201
+ headers[key] = existing ? [*existing, cookie] : cookie
202
+ end
203
+
204
+ # Adds the binding cookie to +headers+ and keeps the response out of
205
+ # shared caches (#keep_out_of_shared_caches), unless the response
206
+ # already sets a cookie of that name (#sets_cookie?).
207
+ def append_binding_cookie(headers, cookie)
208
+ return if sets_cookie?(headers, cookie[/\A[^=]+/])
209
+
210
+ append_set_cookie(headers, cookie)
211
+ keep_out_of_shared_caches(headers)
212
+ end
213
+
214
+ # Whether +headers+ already set a cookie named +name+, as they do when
215
+ # this middleware runs more than once for a request: added again by
216
+ # the app, or in nested CSRF-enabled Ottos. RFC 6265, section 4.1.1:
217
+ # "Servers SHOULD NOT include more than one Set-Cookie header field in
218
+ # the same response with the same cookie-name."
219
+ #
220
+ # The first, innermost, middleware's cookie is kept. When the configs
221
+ # differ (csrf_session_key without session middleware), so do the
222
+ # bindings, and a browser keeps the last cookie of a name. Keeping
223
+ # the outer one would make the inner Otto, which checks the requests
224
+ # its routes receive, reject the tokens it issued.
225
+ def sets_cookie?(headers, name)
226
+ pattern = /\A\s*#{Regexp.escape(name)}\s*=/
227
+ headers.any? do |key, value|
228
+ key.casecmp?('set-cookie') && Array(value).any? { |lines| lines.to_s.split("\n").any?(pattern) }
93
229
  end
94
230
  end
95
231
 
232
+ # Marks a response that carries the binding cookie or an injected
233
+ # token, both meant for one client, with Cache-Control: private.
234
+ # RFC 9111, section 7.3: "the Set-Cookie response header field
235
+ # [COOKIE] does not inhibit caching". Section 5.2.2.7: "The
236
+ # unqualified private response directive indicates that a shared
237
+ # cache MUST NOT store the response (i.e., the response is intended
238
+ # for a single user)." The browser's own cache may still store it.
239
+ #
240
+ # stale-if-error=0 (RFC 5861) is for a cache that stores the
241
+ # response anyway. CloudFront does when the cache policy's minimum
242
+ # TTL is above 0, and its documentation says: "If the origin is
243
+ # unreachable and the minimum or maximum TTL value is greater than
244
+ # 0, CloudFront will serve the object that it got from the origin
245
+ # previously. To avoid this behavior, include the Cache-Control:
246
+ # stale-if-error=0 directive with the object returned from the
247
+ # origin."
248
+ #
249
+ # A response on which the app set Cache-Control or Expires keeps the
250
+ # app's choice, and gets nothing added.
251
+ def keep_out_of_shared_caches(headers)
252
+ return if headers.each_key.any? { |key| key.casecmp?('cache-control') || key.casecmp?('expires') }
253
+
254
+ headers['cache-control'] = 'private, stale-if-error=0'
255
+ end
256
+
96
257
  def html_response?(response)
97
258
  return false unless response.is_a?(Array) && response.length >= 2
98
259
 
99
- headers = response[1]
260
+ html_content_type?(response[1])
261
+ end
262
+
263
+ # Whether +headers+ declare a text/html Content-Type, under any case
264
+ # of the key.
265
+ def html_content_type?(headers)
100
266
  content_type = headers.find { |k, _v| k.downcase == 'content-type' }&.last
101
267
  content_type&.include?('text/html')
102
268
  end
@@ -67,11 +67,17 @@ class Otto
67
67
  # Client-IP resolution is idempotent, but proxy TRUST is not: the
68
68
  # prior pass may have run under a different (or no) configuration,
69
69
  # so this instance still enforces its own trust posture below.
70
- if env.key?('otto.client_ip')
70
+ #
71
+ # otto.ip_match without otto.client_ip also marks a prior pass: the
72
+ # no-resolvable-IP path installs it alone. That path deletes the
73
+ # forwarded address headers, so re-resolving would see only the peer
74
+ # and could turn "client unknown" into "the proxy is the client".
75
+ if env.key?('otto.client_ip') || prior_no_client_ip_pass?(env)
71
76
  ensure_ip_match_present(env)
72
77
  enforce_proxy_trust_after_prior_pass(env)
73
78
  return @app.call(env)
74
79
  end
80
+ discard_out_of_contract_ip_match(env)
75
81
 
76
82
  # Record the connecting peer's trust decision BEFORE any masking, so
77
83
  # secure? can authorize X-Forwarded-Proto canonically even after
@@ -203,16 +209,51 @@ class Otto
203
209
  end
204
210
  end
205
211
 
212
+ # Whether a prior pass of this middleware resolved no client IP.
213
+ #
214
+ # That pass leaves otto.ip_match without otto.client_ip. otto.ip_match
215
+ # alone is not enough to tell: a spec or app may have stubbed it, and
216
+ # taking a stub for a verdict would skip resolution and masking. Every
217
+ # pass writes otto.peer_relayed before resolving, so the pair is the
218
+ # marker.
219
+ #
220
+ # @param env [Hash] Rack environment
221
+ # @return [Boolean]
222
+ def prior_no_client_ip_pass?(env)
223
+ env.key?('otto.ip_match') && env.key?('otto.peer_relayed')
224
+ end
225
+
226
+ # Drop an otto.ip_match this middleware did not install, and say so.
227
+ #
228
+ # Reached only when #call found no prior pass. Resolution below
229
+ # installs the real capability; the warning makes the overwrite
230
+ # diagnosable, as #ensure_ip_match_present does for a hand-set
231
+ # otto.client_ip.
232
+ #
233
+ # @param env [Hash] Rack environment
234
+ def discard_out_of_contract_ip_match(env)
235
+ return unless env.key?('otto.ip_match')
236
+
237
+ Otto.logger.warn(
238
+ '[IPPrivacyMiddleware] otto.ip_match was set outside this ' \
239
+ 'middleware and is being replaced: resolving and masking the ' \
240
+ 'client IP as usual. Test harnesses can build the env with ' \
241
+ 'Otto::Testing.env_for.'
242
+ )
243
+ env.delete('otto.ip_match')
244
+ end
245
+
206
246
  # Guarantee env['otto.ip_match'] exists on the idempotent-return path.
207
247
  #
208
248
  # Every path in this middleware that sets otto.client_ip installs the
209
249
  # capability first, so a second IPPrivacyMiddleware pass that reaches
210
250
  # this guard finds both keys and leaves the precise closure in place.
211
251
  # (The no-resolvable-IP path installs the capability but never sets
212
- # otto.client_ip, so a second pass re-runs apply_privacy and reinstalls
213
- # an equivalent fail-closed closure — idempotent, since there is nothing
214
- # to double-mask.) The gap is out-of-contract writes: otto.client_ip is
215
- # documented as "Set by: IPPrivacyMiddleware" (see Otto::EnvKeys), but
252
+ # otto.client_ip; #call recognises that pass by otto.ip_match plus
253
+ # otto.peer_relayed, so its fail-closed closure is kept too.) The gap
254
+ # is out-of-contract
255
+ # writes: otto.client_ip is documented as "Set by: IPPrivacyMiddleware"
256
+ # (see Otto::EnvKeys), but
216
257
  # an app or test harness that sets it directly trips the idempotency
217
258
  # guard and leaves the advertised capability nil — downstream policy
218
259
  # code then raises NoMethodError on nil.
@@ -260,8 +301,10 @@ class Otto
260
301
  # its own outcome. To trace resolution here, log a derived value (the
261
302
  # masked IP, the family, the trusted-proxy verdict) — never the address.
262
303
 
263
- # No resolvable client IP (REMOTE_ADDR absent or blank, and no trusted
264
- # forwarded value). There is nothing to mask, and masking would derive
304
+ # No resolvable client IP: REMOTE_ADDR absent or blank with no trusted
305
+ # forwarded value, or a trusted proxy chain whose walk reached an
306
+ # entry that is not an address (Otto::Utils.resolve_client_ip returns
307
+ # nil there). There is nothing to mask, and masking would derive
265
308
  # a nil masked IP (IPPrivacy.mask_ip returns nil for nil/empty input).
266
309
  # Writing that nil back to REMOTE_ADDR / forwarded headers would leave
267
310
  # present-but-nil CGI keys, which violate the Rack SPEC and trip
@@ -279,7 +322,9 @@ class Otto
279
322
  # Likewise, forwarded headers may still carry raw client addresses
280
323
  # (e.g. an X-Forwarded-For / Forwarded value with no usable REMOTE_ADDR
281
324
  # to anchor resolution). There is no masked IP to rewrite them to, so
282
- # DELETE them — leaving them would leak the raw address downstream.
325
+ # the address headers are DELETED and Forwarded loses its for= pairs
326
+ # (its proto=/host=/by= stay) — leaving them would leak the raw
327
+ # address downstream.
283
328
  if client_ip.to_s.empty?
284
329
  Otto.logger.debug '[IPPrivacyMiddleware] No resolvable client IP; skipping IP masking' if Otto.debug
285
330
  scrub_sensitive_headers(
@@ -299,7 +344,14 @@ class Otto
299
344
  env['otto.original_ip'] = client_ip
300
345
  # Canonical client IP downstream reads (exempt: not masked)
301
346
  env['otto.client_ip'] = client_ip
302
- # Don't mask forwarded headers for private IPs
347
+ # Rewrite the forwarded address headers to the exempt client IP
348
+ # rather than leaving them as received. They can carry public
349
+ # addresses: entries left of client_ip in the chain (an unlisted
350
+ # private hop appended after the real client), or a header an
351
+ # untrusted private peer sent. Rack::Request#ip trusts private
352
+ # and loopback peers by default and would read those raw values;
353
+ # rewritten, it returns client_ip.
354
+ rewrite_forwarded_addresses(env, client_ip)
303
355
  #
304
356
  # This early return also means NONE of the privacy fingerprint
305
357
  # values are produced for exempt IPs — no otto.privacy.fingerprint,
@@ -364,7 +416,7 @@ class Otto
364
416
 
365
417
  # Mask X-Forwarded-For headers to prevent leakage
366
418
  # Replace with masked IP so proxy resolution logic finds the masked IP
367
- mask_forwarded_headers(env, fingerprint.masked_ip)
419
+ rewrite_forwarded_addresses(env, fingerprint.masked_ip)
368
420
 
369
421
  Otto.logger.debug "[IPPrivacyMiddleware] Masked IP: #{fingerprint.masked_ip}" if Otto.debug
370
422
 
@@ -491,50 +543,87 @@ class Otto
491
543
  UNTRUSTED_FORWARDING_METADATA_HEADERS.each { |key| env.delete(key) }
492
544
  end
493
545
 
494
- # Delete forwarded IP headers outright.
546
+ # Remove the client addresses from the forwarded headers.
495
547
  #
496
548
  # Used on the no-resolvable-client-IP path, where there is no masked IP
497
- # to rewrite these to. Leaving them would leak a raw client address (in
498
- # X-Forwarded-For / X-Real-IP / X-Client-IP / RFC 7239 Forwarded)
499
- # downstream. Deleting is Rack-SPEC-safe: an absent CGI key is valid.
549
+ # to rewrite these to. Leaving them would leak a raw client address
550
+ # downstream. X-Forwarded-For, X-Real-IP, X-Client-IP and the vendor
551
+ # client-address headers carry nothing but addresses, so they are
552
+ # deleted (an absent CGI key is Rack-SPEC-safe). RFC 7239 Forwarded
553
+ # also carries the scheme (proto=)
554
+ # and host (host=) a trusted proxy asserts, which Rack reads for
555
+ # #scheme, #ssl? and #host; deleting it would turn an https request
556
+ # into http and hand the host to the proxy. Its for= pairs are removed
557
+ # instead (see IPPrivacy.strip_forwarded_for for why not `unknown`),
558
+ # and the header is deleted only if nothing else remains.
500
559
  #
501
560
  # @param env [Hash] Rack environment
502
561
  def scrub_forwarded_headers(env)
503
- Otto::Utils::CLIENT_ADDRESS_HEADERS.each { |key| env.delete(key) }
562
+ Otto::Utils::ADDRESS_ONLY_HEADERS.each { |key| env.delete(key) }
563
+ rewrite_forwarded_for(env, nil)
504
564
  end
505
565
 
506
- # Mask X-Forwarded-For and related proxy headers
566
+ # Rewrite X-Forwarded-For and related proxy headers to one address
507
567
  #
508
- # Replaces forwarded IP headers with the masked IP to prevent leakage
509
- # when downstream code (including Rack's request.ip) parses these headers.
568
+ # Replaces every present forwarded IP header with +address+ so
569
+ # downstream code (including Rack's request.ip) that parses these
570
+ # headers finds only that address. The masking path passes the masked
571
+ # IP; the private/localhost exemption passes the resolved client IP.
572
+ # Absent headers stay absent.
510
573
  #
511
574
  # @param env [Hash] Rack environment
512
- # @param masked_ip [String] The masked IP to use as replacement
513
- def mask_forwarded_headers(env, masked_ip)
575
+ # @param address [String] The address to use as replacement
576
+ def rewrite_forwarded_addresses(env, address)
514
577
  # Defensive: never write a nil replacement into these CGI-style headers
515
578
  # (the Rack SPEC requires String values; a nil trips Rack::Lint — see
516
579
  # issue #167). apply_privacy's early "no client IP" guard already
517
- # guarantees a non-nil masked_ip here, but keep this method
580
+ # guarantees a non-nil address here, but keep this method
518
581
  # self-contained so a future caller change can't reintroduce a
519
582
  # present-but-nil HTTP_X_FORWARDED_FOR.
520
- return if masked_ip.nil?
521
-
522
- # Replace X-Forwarded-For with masked IP
523
- # This prevents Rack::Request#ip from finding the real IP
524
- env['HTTP_X_FORWARDED_FOR'] = masked_ip if env['HTTP_X_FORWARDED_FOR']
525
- env['HTTP_X_REAL_IP'] = masked_ip if env['HTTP_X_REAL_IP']
526
- env['HTTP_X_CLIENT_IP'] = masked_ip if env['HTTP_X_CLIENT_IP']
527
-
528
- # RFC 7239 Forwarded carries the client IP in a structured `for=`
529
- # token, and Otto reads it as an authoritative client-IP source in
530
- # count-based depth mode (trusted_proxy_header 'Forwarded'/'Both').
531
- # Left as-is it would leak the real IP to downstream code. Redact only
532
- # the `for=` value(s) so proto=/host=/by= metadata survives.
533
- if env['HTTP_FORWARDED']
534
- env['HTTP_FORWARDED'] = Otto::Privacy::IPPrivacy.mask_forwarded_for(env['HTTP_FORWARDED'], masked_ip)
535
- end
583
+ return if address.nil?
584
+
585
+ # Replace X-Forwarded-For, X-Real-IP, X-Client-IP and the vendor
586
+ # client-address headers (CF-Connecting-IP, True-Client-IP, ...)
587
+ # with the address. This prevents Rack::Request#ip, or code reading
588
+ # a vendor header, from finding any other address.
589
+ Otto::Utils::ADDRESS_ONLY_HEADERS.each { |key| env[key] = address if env[key] }
590
+
591
+ rewrite_forwarded_for(env, address)
592
+
593
+ Otto.logger.debug "[IPPrivacyMiddleware] Rewrote forwarded headers" if Otto.debug
594
+ end
536
595
 
537
- Otto.logger.debug "[IPPrivacyMiddleware] Masked forwarded headers" if Otto.debug
596
+ # Replace every `for=` value in RFC 7239 Forwarded with +replacement+,
597
+ # or remove the `for=` pairs when +replacement+ is nil.
598
+ #
599
+ # Forwarded carries the client IP in a structured `for=` token, and Otto
600
+ # reads it as an authoritative client-IP source in count-based depth
601
+ # mode (trusted_proxy_header 'Forwarded'/'Both'). Left as-is it would
602
+ # leak the real IP to downstream code. Only the `for=` value(s) are
603
+ # redacted, so proto=/host=/by= metadata survives. A header left with
604
+ # nothing but separators is deleted.
605
+ #
606
+ # The rewrite is a pattern match, so the result is re-read with Rack's
607
+ # parser (and Otto's). If any `for=` other than +replacement+ survives,
608
+ # or Rack cannot parse the result, the header is deleted and the
609
+ # deletion logged: losing proto=/host= is recoverable, a client-chosen
610
+ # address reaching Rack::Request#ip is not.
611
+ #
612
+ # @param env [Hash] Rack environment
613
+ # @param replacement [String, nil] an address, or nil to remove `for=`
614
+ def rewrite_forwarded_for(env, replacement)
615
+ value = env['HTTP_FORWARDED']
616
+ return unless value
617
+
618
+ rewritten = Otto::Privacy::IPPrivacy.redact_forwarded_for(value, replacement)
619
+ if rewritten.empty?
620
+ env.delete('HTTP_FORWARDED')
621
+ elsif Otto::Privacy::IPPrivacy.forwarded_for_only?(rewritten, replacement)
622
+ env['HTTP_FORWARDED'] = rewritten
623
+ else
624
+ env.delete('HTTP_FORWARDED')
625
+ Otto::Privacy::IPPrivacy.log_forwarded_deletion
626
+ end
538
627
  end
539
628
 
540
629
  # Check if the connecting peer counts as a trusted proxy
data/lib/otto/static.rb CHANGED
@@ -2,6 +2,8 @@
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
@@ -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