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.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
 
@@ -386,7 +397,8 @@ class Otto
386
397
  # {#fallback_call_args}); a static triple is used as-is. Either way the
387
398
  # result is copied (see {Otto::Static.copy_response}) so the Rack stack
388
399
  # never receives a container shared with the configuration or with another
389
- # request.
400
+ # request. Configured security headers then fill any fields the fallback did
401
+ # not set explicitly.
390
402
  #
391
403
  # @param name [Symbol] the setting name, for the error message
392
404
  # @param fallback [Array, #call] the configured value
@@ -400,7 +412,11 @@ class Otto
400
412
  "#{name} callable must return a Rack triple [status, headers, body], got #{response.inspect}"
401
413
  end
402
414
 
403
- Otto::Static.copy_response(response)
415
+ copied = Otto::Static.copy_response(response)
416
+ @security_config.security_headers.each_pair do |header, value|
417
+ copied[1][header] = value unless copied[1].key?(header)
418
+ end
419
+ copied
404
420
  end
405
421
 
406
422
  # Trim +args+ to the positional parameters +callable+ declares, so a lambda
@@ -418,7 +434,24 @@ class Otto
418
434
 
419
435
  args.first(params.count { |type, _name| POSITIONAL_PARAMETER_TYPES.include?(type) })
420
436
  end
421
- 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
422
455
 
423
456
  # Class methods for Otto framework providing singleton access and configuration
424
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.11.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-12 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
@@ -314,8 +318,10 @@ files:
314
318
  - lib/otto/security/middleware/validation_middleware.rb
315
319
  - lib/otto/security/rate_limiter.rb
316
320
  - lib/otto/security/rate_limiting.rb
321
+ - lib/otto/security/trusted_proxy_config.rb
317
322
  - lib/otto/security/validator.rb
318
323
  - lib/otto/static.rb
324
+ - lib/otto/testing.rb
319
325
  - lib/otto/utils.rb
320
326
  - lib/otto/version.rb
321
327
  - otto.gemspec