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
@@ -10,11 +10,14 @@ require_relative 'schema_validation'
10
10
  require_relative 'rate_limiting'
11
11
  require_relative 'options'
12
12
  require_relative '../security/constant_resolver'
13
+ require_relative '../core/redacted_inspect'
13
14
 
14
15
  class Otto
15
16
  module MCP
16
17
  # MCP server implementation providing Model Context Protocol endpoints
17
18
  class Server
19
+ include Otto::Core::RedactedInspect
20
+
18
21
  attr_reader :protocol, :otto_instance
19
22
 
20
23
  # Normalize raw options into the canonical MCP option hash.
@@ -72,7 +75,7 @@ class Otto
72
75
 
73
76
  @enabled = true
74
77
  @http_endpoint = options[:http_endpoint]
75
- @auth_tokens = options[:auth_tokens]
78
+ @auth_tokens = Otto::Core::RedactedInspect.secret(options[:auth_tokens])
76
79
  @enable_validation = options[:enable_validation]
77
80
  @enable_rate_limiting = options[:enable_rate_limiting]
78
81
  @allow_unauthenticated = options[:allow_unauthenticated]
@@ -105,6 +108,11 @@ class Otto
105
108
 
106
109
  private
107
110
 
111
+ # #inspect shows the bearer tokens as [REDACTED] with their count.
112
+ def redacted_inspect_value(ivar, value)
113
+ ivar == :@auth_tokens ? redacted_placeholder(value) : super
114
+ end
115
+
108
116
  # Publish the per-minute limits under the keys RateLimitMiddleware /
109
117
  # RateLimiter.configure_rack_attack! already read, via Otto's sanctioned
110
118
  # rate-limiting configuration entry point. Before this, the values passed
@@ -222,15 +230,15 @@ class Otto
222
230
  klass_name = klass_method[0..-2].join('::')
223
231
  method_name = klass_method.last
224
232
 
225
- # Create resource handler
226
- handler = lambda do
233
+ # Create resource handler. It receives the Rack env of the MCP request
234
+ # from Registry#read_resource and passes it on when the class method
235
+ # takes one argument, so a resource can check permissions per request.
236
+ handler = lambda do |env|
227
237
  klass = Otto::Security::ConstantResolver.safe_const_get(klass_name)
228
- method = klass.method(method_name)
229
- if method.arity != 0
230
- raise ArgumentError, "Handler #{klass_name}.#{method_name} must be a zero-arity method for resource #{uri}"
231
- end
232
-
233
- klass.public_send(method_name)
238
+ args = Otto::MCP::Registry.resource_handler_args(
239
+ klass.method(method_name), env, "Handler #{klass_name}.#{method_name} for resource #{uri}"
240
+ )
241
+ klass.public_send(method_name, *args)
234
242
  rescue StandardError => e
235
243
  Otto.logger.error "[MCP] Resource handler error for #{uri}: #{e.message}"
236
244
  raise
@@ -9,6 +9,7 @@ require 'digest'
9
9
  require 'concurrent'
10
10
 
11
11
  require_relative '../core/freezable'
12
+ require_relative '../core/redacted_inspect'
12
13
  require_relative '../optional_dependency'
13
14
 
14
15
  class Otto
@@ -31,6 +32,7 @@ class Otto
31
32
  # modules would hide the symmetry that makes them reviewable.
32
33
  class Config
33
34
  include Otto::Core::Freezable
35
+ include Otto::Core::RedactedInspect
34
36
 
35
37
  MAXMIND_DB_REQUIREMENT = '~> 1.2'
36
38
 
@@ -188,7 +190,10 @@ class Otto
188
190
  raise ArgumentError, "correlation_secret must be a String or nil, got: #{value.class}"
189
191
  end
190
192
 
191
- @correlation_secret = value
193
+ # A frozen SecretString copy: the reader cannot hand out a String
194
+ # whose FrozenError would print the secret, and the caller's String is
195
+ # not frozen by deep_freeze!.
196
+ @correlation_secret = Otto::Core::RedactedInspect.secret(value)
192
197
  end
193
198
 
194
199
  # Set the trusted, app-configured geo header.
@@ -519,6 +524,12 @@ class Otto
519
524
 
520
525
  private
521
526
 
527
+ # #inspect (and so a native FrozenError message) shows the correlation
528
+ # secret as [REDACTED]. See Otto::Core::RedactedInspect.
529
+ def redacted_inspect_value(ivar, value)
530
+ ivar == :@correlation_secret ? redacted_placeholder(value) : super
531
+ end
532
+
522
533
  # Profile-governed, so #profile= can assign it through a writer like the
523
534
  # other knobs. Public callers use #disable! and #enable!.
524
535
  attr_writer :disabled
@@ -3,6 +3,7 @@
3
3
  # frozen_string_literal: true
4
4
 
5
5
  require 'ipaddr'
6
+ require 'rack/utils'
6
7
  require 'digest'
7
8
  require 'openssl'
8
9
  require 'socket'
@@ -136,13 +137,118 @@ class Otto
136
137
  return value if value.nil? || masked_ip.nil? || masked_ip.empty?
137
138
 
138
139
  replacement = masked_ip.include?(':') ? %("[#{masked_ip}]") : masked_ip
139
- # Match `for=` only at an element/pair boundary (start, comma, or
140
- # semicolon) so a parameter merely ending in "for" is never touched.
141
- value.gsub(/(\A|[,;]\s*)for\s*=\s*("[^"]*"|[^;,]+)/i) do
140
+ value.gsub(FORWARDED_FOR_PAIR) do
142
141
  "#{Regexp.last_match(1)}for=#{replacement}"
143
142
  end
144
143
  end
145
144
 
145
+ # A `for=` pair in an RFC 7239 Forwarded value. Group 1 is the boundary
146
+ # before it, kept on rewrite.
147
+ #
148
+ # The boundaries are the ones Rack 3.2.7 (Rack::Utils.forwarded_values)
149
+ # accepts before a parameter name: the start of the value, a comma or
150
+ # semicolon, any whitespace (Rack skips it between pairs, after a quoted
151
+ # value, and before the first pair; a newline becomes a separator), or
152
+ # the closing quote of a quoted value, which Rack needs nothing after.
153
+ # A parameter merely ending in "for" is never touched. A quoted value
154
+ # may contain backslash escapes, as in Rack; an unquoted one runs to
155
+ # the next comma, semicolon or newline.
156
+ FORWARDED_FOR_PAIR = /(\A|[\s;,"])for\s*=\s*("(?:[^"\\]|\\.)*"|[^;,\n]*)/i
157
+
158
+ # Redact the `for=` values of an RFC 7239 Forwarded value: replace them
159
+ # with +replacement+ ({.mask_forwarded_for}), or remove them when
160
+ # +replacement+ is nil ({.strip_forwarded_for}).
161
+ #
162
+ # @param value [String] the Forwarded header value
163
+ # @param replacement [String, nil] an address, or nil
164
+ # @return [String] the rewritten value; empty when nothing is left
165
+ def self.redact_forwarded_for(value, replacement)
166
+ replacement ? mask_forwarded_for(value, replacement) : strip_forwarded_for(value)
167
+ end
168
+
169
+ # Guards the once-per-process warning for a deleted Forwarded header.
170
+ FORWARDED_DELETION_LOCK = Mutex.new
171
+ @forwarded_deletion_logged = false
172
+
173
+ # Log that IPPrivacyMiddleware deleted a Forwarded header whose `for=`
174
+ # rewrite it could not verify: at warn the first time in the process,
175
+ # at debug (when Otto.debug is on) after that.
176
+ #
177
+ # A header with an RFC 7239 extension parameter, which Rack rejects, is
178
+ # deleted on every request that carries it, and any client can send
179
+ # one, so a warning per request would be noise. The message never
180
+ # includes the header value, which may hold an address.
181
+ #
182
+ # @return [void]
183
+ def self.log_forwarded_deletion
184
+ message = '[IPPrivacyMiddleware] Deleted a Forwarded header: a for= value survived the ' \
185
+ 'rewrite, or Rack cannot parse it (e.g. an extension parameter).'
186
+ first = FORWARDED_DELETION_LOCK.synchronize do
187
+ next false if @forwarded_deletion_logged
188
+
189
+ @forwarded_deletion_logged = true
190
+ end
191
+
192
+ if first
193
+ Otto.logger.warn("#{message} Later deletions in this process are logged at debug.")
194
+ elsif Otto.debug
195
+ Otto.logger.debug(message)
196
+ end
197
+ end
198
+
199
+ # Make the next Forwarded deletion warn again. Test support.
200
+ #
201
+ # @api private
202
+ # @return [void]
203
+ def self.reset_forwarded_deletion_log!
204
+ FORWARDED_DELETION_LOCK.synchronize { @forwarded_deletion_logged = false }
205
+ end
206
+
207
+ # Whether every `for=` value in an RFC 7239 Forwarded value is
208
+ # +replacement+ (or there is none, when +replacement+ is nil).
209
+ #
210
+ # The rewrite above is a pattern match; this is the check that it
211
+ # caught everything. It reads the header with Rack's parser, which
212
+ # decides Rack::Request#ip, and with Otto's depth-mode parser. A value
213
+ # Rack cannot parse (it rejects parameters other than by, for, host and
214
+ # proto) fails, since it cannot be verified.
215
+ #
216
+ # @param value [String] rewritten Forwarded header value
217
+ # @param replacement [String, nil] the address written into `for=`, or
218
+ # nil when the `for=` pairs were removed
219
+ # @return [Boolean]
220
+ def self.forwarded_for_only?(value, replacement)
221
+ expected = replacement&.include?(':') ? "[#{replacement}]" : replacement
222
+ parsed = Rack::Utils.forwarded_values(value)
223
+ return false if parsed.nil?
224
+
225
+ values = Array(parsed[:for]) + Otto::Utils.rfc7239_for_chain(value).reject(&:empty?)
226
+ values.all?(expected)
227
+ end
228
+
229
+ # Remove every `for=` pair from an RFC 7239 Forwarded header value.
230
+ #
231
+ # For a request with no resolvable client IP there is no address to put
232
+ # in `for=`. The pairs are removed rather than set to `unknown`: Rack
233
+ # returns a `for=` value as the client IP whenever it reads Forwarded,
234
+ # so `for=unknown` made Rack::Request#ip the string "unknown", while
235
+ # with no `for=` it falls back to REMOTE_ADDR as Otto::Request#ip does.
236
+ # RFC 7239 allows an element without `for=`, so `proto=`, `host=` and
237
+ # `by=` stay. An element left with no pairs is dropped.
238
+ #
239
+ # @param value [String, nil] the Forwarded header value
240
+ # @return [String, nil] the header without `for=` pairs; an empty string
241
+ # when nothing else remains, nil for nil input
242
+ def self.strip_forwarded_for(value)
243
+ return value if value.nil?
244
+
245
+ value.gsub(FORWARDED_FOR_PAIR) { Regexp.last_match(1) }
246
+ .split(',', -1)
247
+ .map { |element| element.gsub(/\s*;[\s;]*/, ';').gsub(/\A[\s;]+|[\s;]+\z/, '') }
248
+ .reject(&:empty?)
249
+ .join(', ')
250
+ end
251
+
146
252
  # Mask IPv4 address
147
253
  #
148
254
  # @param addr [IPAddr] IPAddr object (must be IPv4)
@@ -26,16 +26,14 @@ class Otto
26
26
  :request_path, :request_method, :referer
27
27
 
28
28
  # IP-bearing forwarded headers overwritten with the masked IP in the
29
- # geo-resolution env view. Mirrors the set
30
- # IPPrivacyMiddleware#mask_forwarded_headers rewrites, so a custom resolver
31
- # reading env sees masked values everywhere the middleware would. The
32
- # structured RFC 7239 Forwarded header (HTTP_FORWARDED) is handled
33
- # separately in {#geo_env} (dropped, not swapped, to keep valid syntax).
34
- GEO_MASKED_FORWARDED_HEADERS = %w[
35
- HTTP_X_FORWARDED_FOR
36
- HTTP_X_REAL_IP
37
- HTTP_X_CLIENT_IP
38
- ].freeze
29
+ # geo-resolution env view: the forwarded-for family and the vendor
30
+ # client-address headers (CF-Connecting-IP, True-Client-IP, ...). The
31
+ # same list IPPrivacyMiddleware#rewrite_forwarded_addresses rewrites,
32
+ # so a custom resolver reading env sees masked values everywhere the
33
+ # middleware would. The structured RFC 7239 Forwarded header
34
+ # (HTTP_FORWARDED) is handled separately in {#geo_env} (dropped, not
35
+ # swapped, to keep valid syntax).
36
+ GEO_MASKED_FORWARDED_HEADERS = Otto::Utils::ADDRESS_ONLY_HEADERS
39
37
 
40
38
  # Create a new RedactedFingerprint from a Rack environment
41
39
  #
data/lib/otto/request.rb CHANGED
@@ -22,6 +22,33 @@ class Otto
22
22
  #
23
23
  # @see Otto#register_request_helpers
24
24
  class Request < Rack::Request
25
+ # The Hash that #session installs in env['rack.session'] when no session
26
+ # middleware provided one. It is an ordinary, writable Hash; the class
27
+ # marks it as a stand-in, so RouteAuthWrapper can install a strategy's
28
+ # session over it while never replacing a session a middleware installed.
29
+ class DefaultSession < ::Hash
30
+ # Whether +session+ is no session a middleware installed: nil, or a
31
+ # DefaultSession. Checks the class only, so a lazy session object (for
32
+ # example rack-session's SessionHash) is not loaded.
33
+ #
34
+ # @param session [Object, nil] the value of env['rack.session']
35
+ # @return [Boolean]
36
+ def self.vacant?(session)
37
+ session.nil? || session.instance_of?(self)
38
+ end
39
+ end
40
+
41
+ # Rack::Request#session installs the value of this private hook in
42
+ # env['rack.session'] when env has no session (rack 3.1 and 3.2:
43
+ # request.rb, `def default_session; {}; end`). Otto installs a
44
+ # {DefaultSession} instead of a plain Hash.
45
+ #
46
+ # @return [DefaultSession]
47
+ def default_session
48
+ DefaultSession.new
49
+ end
50
+ private :default_session
51
+
25
52
  def user_agent
26
53
  env['HTTP_USER_AGENT']
27
54
  end
@@ -208,6 +235,13 @@ class Otto
208
235
  canonical = env['otto.client_ip']
209
236
  return canonical if canonical && !canonical.empty?
210
237
 
238
+ # otto.ip_match and otto.peer_relayed without a usable otto.client_ip
239
+ # mean the middleware ran and found no client IP (every pass writes
240
+ # otto.peer_relayed; otto.ip_match alone may be a stub). It deleted the
241
+ # forwarded address headers on that path, so re-resolving here would
242
+ # see only the peer and return a proxy as the client.
243
+ return canonical if env.key?('otto.ip_match') && env.key?('otto.peer_relayed')
244
+
211
245
  Otto::Utils.resolve_client_ip(env, otto_security_config)
212
246
  end
213
247
 
@@ -121,8 +121,9 @@ class Otto
121
121
  end
122
122
 
123
123
  # Parse a single whitespace-delimited `key=value` option token, applying
124
- # the security-gating fail-fast rule shared by normal routes and the MCP
125
- # RouteParser (issue #191 and its MCP/TOOL follow-up).
124
+ # the security-gating fail-fast rule for normal routes (issue #191). The
125
+ # MCP RouteParser also calls this, after rejecting auth/role/csrf tokens
126
+ # outright because MCP and TOOL routes do not enforce them.
126
127
  # @param part [String] a single option token, e.g. "auth=session"
127
128
  # @param context [String] human-readable source description for the
128
129
  # raised error message, e.g. "route definition \"GET /admin ...\""
@@ -209,9 +209,16 @@ class Otto
209
209
  # Set environment variables for controllers/logic
210
210
  env['otto.strategy_result'] = result
211
211
 
212
- # SESSION PERSISTENCE: Ensure env['rack.session'] and strategy_result.session
213
- # reference the SAME object for proper session persistence
214
- env['rack.session'] = result.session if result.is_a?(StrategyResult) && result.session
212
+ # SESSION PERSISTENCE: never replace a session a middleware installed
213
+ # (e.g. rack-session's SessionHash); the middleware commits the
214
+ # object it installed. result.session (nil and false are not
215
+ # sessions) goes into env only when env has none, or only the
216
+ # Otto::Request::DefaultSession that Otto::Request#session installs
217
+ # when no middleware did (Otto's CSRF check runs before this wrapper
218
+ # and reads the session that way). The check reads only the class,
219
+ # so it does not load a lazy session.
220
+ session = result.session
221
+ env['rack.session'] = session if session && Otto::Request::DefaultSession.vacant?(env['rack.session'])
215
222
 
216
223
  # Layer 1 Authorization: Check role requirements
217
224
  auth_check = @role_authorizer.check(result, env)