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.
- 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/.rubocop_todo.yml +2 -2
- data/AGENTS.md +4 -2
- data/CHANGELOG.rst +792 -0
- data/Gemfile +3 -2
- data/Gemfile.lock +13 -8
- data/README.md +6 -0
- 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 +85 -5
- data/docs/guides/mcp.md +40 -4
- data/docs/guides/privacy.md +28 -2
- data/docs/guides/routing.md +76 -9
- data/docs/guides/testing-guide.md +146 -5
- 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/localhost_guard.rb +6 -6
- data/lib/otto/caddy_tls/server.rb +8 -4
- data/lib/otto/core/configuration.rb +5 -3
- data/lib/otto/core/option_hash.rb +124 -0
- data/lib/otto/core/redacted_inspect.rb +149 -0
- data/lib/otto/core/router.rb +57 -34
- data/lib/otto/core.rb +2 -0
- data/lib/otto/env_keys.rb +30 -6
- 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 +31 -14
- 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/response.rb +5 -2
- data/lib/otto/route.rb +1 -1
- data/lib/otto/route_definition.rb +3 -2
- data/lib/otto/route_handlers/base.rb +1 -1
- data/lib/otto/route_handlers/logic_class.rb +86 -34
- data/lib/otto/security/authentication/route_auth_wrapper.rb +10 -3
- data/lib/otto/security/config.rb +703 -345
- data/lib/otto/security/configurator.rb +82 -45
- data/lib/otto/security/core.rb +4 -2
- data/lib/otto/security/csp/report_middleware.rb +17 -1
- 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 +129 -42
- data/lib/otto/security/rate_limiter.rb +8 -5
- data/lib/otto/security/trusted_proxy_config.rb +396 -0
- data/lib/otto/static.rb +70 -6
- data/lib/otto/testing.rb +148 -0
- data/lib/otto/utils.rb +166 -40
- data/lib/otto/version.rb +1 -1
- data/lib/otto.rb +44 -11
- 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' =>
|
|
124
|
+
'referrer-policy' => security_config&.referrer_policy ||
|
|
125
|
+
Otto::Security::Config::DEFAULT_REFERRER_POLICY,
|
|
62
126
|
}
|
|
63
127
|
end
|
|
64
128
|
|
data/lib/otto/testing.rb
ADDED
|
@@ -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
|
|
14
|
-
#
|
|
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,
|
|
104
|
-
#
|
|
105
|
-
#
|
|
106
|
-
#
|
|
107
|
-
#
|
|
108
|
-
#
|
|
109
|
-
#
|
|
110
|
-
#
|
|
111
|
-
#
|
|
112
|
-
#
|
|
113
|
-
#
|
|
114
|
-
#
|
|
115
|
-
# (
|
|
116
|
-
#
|
|
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
|
|
180
|
-
# first
|
|
181
|
-
#
|
|
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
|
|
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
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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
|
-
|
|
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
|
|
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)
|
|
241
|
-
# a
|
|
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
|
|
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)
|
|
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 (
|
|
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
|
|
321
|
-
#
|
|
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
|
|
390
|
-
#
|
|
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