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.
- checksums.yaml +4 -4
- data/.github/workflows/ci.yml +1 -1
- data/.github/workflows/claude-code-review.yml +1 -1
- data/.github/workflows/claude.yml +1 -1
- data/.github/workflows/code-smells.yml +2 -2
- data/.github/workflows/release-gem.yml +1 -1
- data/.github/workflows/ruby-lint.yml +1 -1
- data/.github/workflows/yardoc.yml +1 -1
- data/AGENTS.md +4 -2
- data/CHANGELOG.rst +692 -0
- data/Gemfile +1 -0
- data/Gemfile.lock +6 -1
- data/docs/README.md +4 -0
- data/docs/audits/2026-09-28-v2.12.0-code-audit.md +732 -0
- data/docs/audits/README.md +63 -0
- data/docs/guides/authentication.md +329 -0
- data/docs/guides/forwarded-authority.md +80 -4
- data/docs/guides/mcp.md +40 -4
- data/docs/guides/privacy.md +23 -2
- data/docs/guides/routing.md +8 -4
- data/docs/guides/testing-guide.md +31 -3
- data/docs/migrating/v2.3.0.md +13 -7
- data/docs/reference/authentication.md +70 -22
- data/examples/lambda_handlers/README.md +4 -4
- data/examples/lambda_handlers/handlers.rb +4 -5
- data/examples/lambda_handlers/routes +2 -2
- data/examples/mcp_demo/README.md +65 -27
- data/examples/mcp_demo/app.rb +8 -5
- data/examples/mcp_demo/config.ru +50 -3
- data/examples/mcp_demo/routes +10 -6
- data/examples/security_features/README.md +2 -2
- data/lib/otto/caddy_tls/server.rb +8 -4
- data/lib/otto/core/option_hash.rb +124 -0
- data/lib/otto/core/redacted_inspect.rb +149 -0
- data/lib/otto/core/router.rb +41 -14
- data/lib/otto/core.rb +2 -0
- data/lib/otto/env_keys.rb +30 -7
- data/lib/otto/logging_helpers.rb +1 -1
- data/lib/otto/mcp/auth/token.rb +12 -1
- data/lib/otto/mcp/protocol.rb +3 -3
- data/lib/otto/mcp/registry.rb +28 -2
- data/lib/otto/mcp/route_parser.rb +20 -8
- data/lib/otto/mcp/server.rb +17 -9
- data/lib/otto/privacy/config.rb +12 -1
- data/lib/otto/privacy/ip_privacy.rb +109 -3
- data/lib/otto/privacy/redacted_fingerprint.rb +8 -10
- data/lib/otto/request.rb +34 -0
- data/lib/otto/route_definition.rb +3 -2
- data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
- data/lib/otto/security/config.rb +358 -46
- data/lib/otto/security/csrf.rb +17 -2
- data/lib/otto/security/csrf_validation.rb +13 -7
- data/lib/otto/security/middleware/csrf_middleware.rb +203 -37
- data/lib/otto/security/middleware/ip_privacy_middleware.rb +127 -38
- data/lib/otto/static.rb +63 -0
- data/lib/otto/utils.rb +105 -28
- data/lib/otto/version.rb +1 -1
- data/lib/otto.rb +37 -9
- metadata +6 -2
data/lib/otto/mcp/server.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|
data/lib/otto/privacy/config.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
30
|
-
#
|
|
31
|
-
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
|
125
|
-
# RouteParser
|
|
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:
|
|
213
|
-
#
|
|
214
|
-
|
|
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)
|