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
@@ -1,22 +1,24 @@
1
1
  # Otto MCP Demo
2
2
 
3
3
  This example boots Otto's Model Context Protocol (MCP) JSON-RPC 2.0 endpoint at
4
- `/_mcp`. Use it to verify endpoint initialization alongside ordinary Otto web
5
- routes.
4
+ `/_mcp`, with one resource and one tool declared in the routes file, alongside
5
+ ordinary Otto web routes.
6
6
 
7
7
  ## What You'll Learn
8
8
 
9
9
  - How to enable an MCP HTTP endpoint
10
+ - How to declare an MCP resource and tool in the routes file
10
11
  - How the endpoint coexists with ordinary Otto web routes
11
- - How to send a JSON-RPC 2.0 `initialize` request
12
+ - How to send JSON-RPC 2.0 requests to list, read, and call them
12
13
  - How bearer-token authentication protects the endpoint
13
- - The current resource and tool limitations described below
14
14
 
15
15
  ## Features Demonstrated
16
16
 
17
17
  - **MCP endpoint**: A single `POST /_mcp` endpoint
18
+ - **Resource and tool**: The `users` resource and the `create_user` tool
18
19
  - **Web interface**: Separate web routes coexist with the MCP endpoint
19
- - **JSON-RPC 2.0**: `initialize`, `resources/list`, and `tools/list` requests
20
+ - **JSON-RPC 2.0**: `initialize`, `resources/list`, `resources/read`,
21
+ `tools/list`, and `tools/call` requests
20
22
 
21
23
  ## How to Run
22
24
 
@@ -38,7 +40,10 @@ If either enabled feature's gem is missing or incompatible, MCP setup raises
38
40
  `enable_validation: false` or `enable_rate_limiting: false` to `enable_mcp!`, or
39
41
  alongside `mcp_enabled: true` in the `Otto.new` options, only when that protection
40
42
  is intentionally disabled. To enforce the configured limits, mount
41
- `Rack::Attack` before Otto in `config.ru`, as this example does.
43
+ `Rack::Attack` before Otto in `config.ru`, as this example does. `Rack::Attack`
44
+ counts requests in a cache store and has no default store outside Rails, so
45
+ `config.ru` sets a small in-process store (`DemoRateLimitStore`). Use a shared
46
+ store, such as Redis, when the app runs in more than one process.
42
47
 
43
48
  ```sh
44
49
  cd /path/to/otto
@@ -64,14 +69,27 @@ and a JSON-RPC `Unauthorized` error. The `requests_per_minute` and
64
69
  `tools_per_minute` values in `config.ru` are applied as configured. See the
65
70
  [MCP guide](../../docs/guides/mcp.md) for the full option list.
66
71
 
67
- ## Current Limitations
72
+ ## Resources and Tools
68
73
 
69
- Although `routes` contains `MCP /users` and `TOOL /create_user` declarations,
70
- the current route-loading path does not register them. Therefore
71
- `resources/list` and `tools/list` both return empty arrays, and `resources/read`
72
- or `tools/call` for those names fails. This README documents the runnable
73
- endpoint behavior; do not use this example as a resource or tool integration
74
- template until those routes are registered.
74
+ `routes` declares one resource and one tool:
75
+
76
+ ```
77
+ GET /mcp/users MCP users UserAPI.mcp_list_users
78
+ POST /mcp/create_user TOOL create_user UserAPI.mcp_create_user
79
+ ```
80
+
81
+ The verb and path are required by the route-file grammar but create no HTTP
82
+ route: the resource and the tool are served only through `POST /_mcp`. The word
83
+ after `MCP` is the resource URI (`users`), and the word after `TOOL` is the tool
84
+ name (`create_user`). MCP must be enabled when the routes file loads, as
85
+ `Otto.new('routes', mcp_enabled: true, ...)` in `config.ru` does. If the file
86
+ loads before MCP is enabled, Otto skips its `MCP` and `TOOL` lines.
87
+
88
+ `UserAPI.mcp_list_users` takes no arguments. A resource handler may instead
89
+ take one argument, the Rack env of the MCP request. `UserAPI.mcp_create_user`
90
+ receives the tool `arguments` and the Rack env. `MCP` and `TOOL` lines cannot
91
+ use `auth=`, `role=`, or `csrf=`; see the
92
+ [MCP guide](../../docs/guides/mcp.md#register-resources-and-tools).
75
93
 
76
94
  ## Interacting with the MCP Endpoint
77
95
 
@@ -101,7 +119,8 @@ curl -X POST http://localhost:9292/_mcp \
101
119
 
102
120
  ### MCP: Initialize
103
121
 
104
- The `initialize` method is a built-in MCP method that returns information about the available resources and tools.
122
+ The `initialize` method is a built-in MCP method that returns the protocol
123
+ version, the server capabilities, and the server name and version.
105
124
 
106
125
  ```sh
107
126
  curl -X POST http://localhost:9292/_mcp \
@@ -114,7 +133,7 @@ curl -X POST http://localhost:9292/_mcp \
114
133
 
115
134
  A successful `initialize` request returns `result.protocolVersion`,
116
135
  `result.capabilities`, and `result.serverInfo` with the same request ID. To
117
- confirm the current registry state, run:
136
+ list the registered resource and tool, run:
118
137
 
119
138
  ```sh
120
139
  curl -X POST http://localhost:9292/_mcp \
@@ -128,34 +147,53 @@ curl -X POST http://localhost:9292/_mcp \
128
147
  -d '{"jsonrpc":"2.0","method":"tools/list","id":3}'
129
148
  ```
130
149
 
131
- Each request returns `"jsonrpc":"2.0"` and an empty `resources` or `tools`
132
- array in the current checkout.
150
+ `resources/list` returns one entry with `"uri":"users"`, and `tools/list`
151
+ returns one entry with `"name":"create_user"`. Read the resource and call the
152
+ tool:
153
+
154
+ ```sh
155
+ curl -X POST http://localhost:9292/_mcp \
156
+ -H 'Content-Type: application/json' \
157
+ -H 'Authorization: Bearer demo-token-123' \
158
+ -d '{"jsonrpc":"2.0","method":"resources/read","id":4,"params":{"uri":"users"}}'
159
+
160
+ curl -X POST http://localhost:9292/_mcp \
161
+ -H 'Content-Type: application/json' \
162
+ -H 'Authorization: Bearer demo-token-123' \
163
+ -d '{"jsonrpc":"2.0","method":"tools/call","id":5,"params":{"name":"create_user","arguments":{"name":"Carol"}}}'
164
+ ```
165
+
166
+ `resources/read` returns `result.contents[0].text`, the JSON list of users
167
+ from `UserAPI.mcp_list_users`. `tools/call` returns `result.content[0].text`,
168
+ starting with `Created user:`. `tools_per_minute: 20` limits each client IP:
169
+ the 21st `tools/call` in the same 60-second window gets HTTP `429`.
133
170
 
134
171
  ## File Structure
135
172
 
136
173
  - `README.md`: This file
137
174
  - `app.rb`: Application logic
138
175
  - `DemoApp`: Web interface and health check
139
- - `UserAPI`: Intended MCP resource and tool handlers (not registered by the current route-loading path)
140
- - `config.ru`: Rack configuration (loads Otto, enables MCP)
176
+ - `UserAPI`: MCP resource and tool handlers
177
+ - `config.ru`: Rack configuration (loads Otto, enables MCP, sets the
178
+ `Rack::Attack` store)
141
179
  - `routes`: Route definitions for web and MCP routes
142
180
 
143
181
  ## Routes
144
182
 
145
- The ordinary web routes in `routes` are active:
146
-
147
183
  ```
148
- GET / DemoApp.index
149
- GET /health DemoApp.health
184
+ GET / DemoApp.index
185
+ GET /health DemoApp.health
186
+ GET /mcp/users MCP users UserAPI.mcp_list_users
187
+ POST /mcp/create_user TOOL create_user UserAPI.mcp_create_user
150
188
  ```
151
189
 
152
- The file also contains `MCP /users UserAPI.mcp_list_users` and
153
- `TOOL /create_user UserAPI.mcp_create_user`. See [Current Limitations](#current-limitations):
154
- they are not registered by this checkout's route-loading path.
190
+ The first two are ordinary web routes. The last two register the MCP resource
191
+ and tool described in [Resources and Tools](#resources-and-tools).
155
192
 
156
193
  ## Next Steps
157
194
 
158
195
  - Build a CLI that communicates with the MCP endpoint
159
196
  - Integrate with AI systems that support MCP
160
- - Combine with [Authentication](../authentication_strategies/) for role-based MCP access
197
+ - Protect the endpoint with `mcp_auth_tokens`. `MCP` and `TOOL` routes cannot use
198
+ `auth=`, `role=`, or `csrf=`; see the [MCP guide](../../docs/guides/mcp.md#register-resources-and-tools)
161
199
  - Explore [Advanced Routes](../advanced_routes/) for more routing patterns
@@ -8,7 +8,7 @@ class DemoApp
8
8
  res.headers['content-type'] = 'text/html; charset=utf-8'
9
9
  res.body = <<~HTML
10
10
  <h1>Otto MCP Demo</h1>
11
- <p>This example demonstrates Otto's Model-Controller-Protocol (MCP) feature, which provides a JSON-RPC 2.0 endpoint for interacting with your application.</p>
11
+ <p>This example demonstrates Otto's Model Context Protocol (MCP) feature, which provides a JSON-RPC 2.0 endpoint for interacting with your application.</p>
12
12
  <p>The MCP endpoint is available at: <code>POST /_mcp</code></p>
13
13
  <p>See the <code>README.md</code> file for detailed `curl` commands to test the API.</p>
14
14
  HTML
@@ -22,8 +22,10 @@ end
22
22
 
23
23
  # UserAPI provides handlers for the MCP tool and resource routes.
24
24
  class UserAPI
25
- # MCP Resource: mcp_list_users
26
- # Accessible via JSON-RPC method "users/list"
25
+ # MCP resource "users" (routes: MCP users UserAPI.mcp_list_users).
26
+ # Read it with the JSON-RPC method resources/read and params {"uri": "users"}.
27
+ # A resource handler may instead take one argument, the Rack env of the MCP
28
+ # request, to check permissions per request.
27
29
  def self.mcp_list_users
28
30
  {
29
31
  users: [
@@ -33,8 +35,9 @@ class UserAPI
33
35
  }.to_json
34
36
  end
35
37
 
36
- # MCP Tool: mcp_create_user
37
- # Accessible via JSON-RPC method "create_user"
38
+ # MCP tool "create_user" (routes: TOOL create_user UserAPI.mcp_create_user).
39
+ # Call it with the JSON-RPC method tools/call and params
40
+ # {"name": "create_user", "arguments": {...}}.
38
41
  def self.mcp_create_user(arguments, _env)
39
42
  name = arguments['name'] || 'Anonymous'
40
43
  email = arguments['email'] || "#{name.downcase}@example.com"
@@ -3,7 +3,53 @@
3
3
  require_relative '../../lib/otto'
4
4
  require_relative 'app'
5
5
 
6
- # Initialize Otto with MCP support
6
+ # Rack::Attack counts requests in a cache store and raises
7
+ # Rack::Attack::MissingStoreError without one. Outside Rails there is no
8
+ # default store, so this demo keeps the counts in process memory. Use a shared
9
+ # store (for example Redis) when the app runs in more than one process.
10
+ class DemoRateLimitStore
11
+ def initialize
12
+ @entries = {}
13
+ @mutex = Mutex.new
14
+ end
15
+
16
+ def read(key)
17
+ @mutex.synchronize { live_value(key) }
18
+ end
19
+
20
+ def write(key, value, expires_in: nil)
21
+ @mutex.synchronize { @entries[key] = [value, expires_in && (now + expires_in)] }
22
+ value
23
+ end
24
+
25
+ # Returns nil for a missing or expired key. Rack::Attack::Cache#do_count
26
+ # accepts nil from a store and writes the first count itself.
27
+ def increment(key, amount = 1, **)
28
+ @mutex.synchronize do
29
+ value = live_value(key)
30
+ value && (@entries[key][0] = value + amount)
31
+ end
32
+ end
33
+
34
+ def delete(key)
35
+ @mutex.synchronize { @entries.delete(key) }
36
+ end
37
+
38
+ private
39
+
40
+ def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
41
+
42
+ def live_value(key)
43
+ value, expires_at = @entries[key]
44
+ return value unless expires_at && expires_at <= now
45
+
46
+ @entries.delete(key)
47
+ nil
48
+ end
49
+ end
50
+
51
+ # Initialize Otto with MCP support. MCP must be enabled when the routes file
52
+ # loads, or Otto skips its MCP and TOOL lines.
7
53
  app = Otto.new('routes', {
8
54
  mcp_enabled: true,
9
55
  auth_tokens: ['demo-token-123', 'another-token-456'],
@@ -11,8 +57,9 @@ app = Otto.new('routes', {
11
57
  tools_per_minute: 20,
12
58
  })
13
59
 
14
- # The `mcp_enabled: true` flag automatically sets up the /_mcp endpoint.
15
- # The routes file maps MCP and TOOL methods to classes.
60
+ # The `mcp_enabled: true` flag sets up the /_mcp endpoint. The routes file
61
+ # declares one MCP resource and one tool for it to serve.
16
62
 
63
+ Rack::Attack.cache.store = DemoRateLimitStore.new
17
64
  use Rack::Attack
18
65
  run app
@@ -1,9 +1,13 @@
1
1
  # Basic HTTP routes
2
- GET / DemoApp.index
3
- GET /health DemoApp.health
2
+ GET / DemoApp.index
3
+ GET /health DemoApp.health
4
4
 
5
- # MCP Resources - provide read-only data
6
- MCP /users UserAPI.mcp_list_users
5
+ # MCP and TOOL declarations need a verb and a path to satisfy the route-file
6
+ # grammar, but they create no HTTP route. The single MCP endpoint (POST /_mcp)
7
+ # serves them.
7
8
 
8
- # MCP Tools - provide actions/operations
9
- TOOL /create_user UserAPI.mcp_create_user
9
+ # MCP resource: read-only data, read with resources/read (uri "users")
10
+ GET /mcp/users MCP users UserAPI.mcp_list_users
11
+
12
+ # MCP tool: an action, called with tools/call (name "create_user")
13
+ POST /mcp/create_user TOOL create_user UserAPI.mcp_create_user
@@ -51,9 +51,9 @@ curl -i -X POST http://127.0.0.1:10770/feedback -d 'message=test'
51
51
 
52
52
  The feedback handler rejects script-like input and limits messages to 1,000 characters; profile fields have their own limits and the email field must match the example's basic format check. The upload form demonstrates filename sanitization and request handling. It displays metadata and does **not** permanently store uploaded files; it does not implement a file-type allowlist.
53
53
 
54
- ### Current limitation
54
+ ### CSRF secret
55
55
 
56
- The home page generates a CSRF token during its first request. Otto freezes configuration at that point, and the generated-secret warning then attempts to modify the frozen security configuration. As a result, `GET /` currently fails with `FrozenError`, so browser-based valid-form verification is unavailable until that example or the initialization sequence is corrected.
56
+ `config.ru` does not set a CSRF secret. Without `OTTO_CSRF_SECRET`, Otto signs tokens with a secret generated for the process and logs a warning about it once, when it freezes the configuration on the first request. The forms on the home page include a token, so submitting the feedback form exercises the valid-token path.
57
57
 
58
58
  ## Files to inspect
59
59
 
@@ -120,16 +120,16 @@ class Otto
120
120
  Otto::Utils.relayed_request?(env)
121
121
  end
122
122
 
123
- # Whether this request is for the protected endpoint. Normalizes
124
- # +PATH_INFO+ through the same +Otto::Utils.normalize_path+ the router
125
- # uses for literal matching, so a percent-encoded, invalid-byte, or
126
- # trailing-slash variant the router would still route cannot slip past the
127
- # guard by normalizing differently here than at dispatch.
123
+ # Whether this request is for the protected endpoint. Compares the path
124
+ # the router itself dispatches on (+Otto::Utils.routing_path+), so a
125
+ # percent-encoded, invalid-byte, or trailing-slash variant the router
126
+ # would still route cannot slip past the guard by normalizing differently
127
+ # here than at dispatch.
128
128
  #
129
129
  # @param env [Hash] Rack environment
130
130
  # @return [Boolean]
131
131
  def targets_endpoint?(env)
132
- normalize_path(env['PATH_INFO']) == @endpoint
132
+ Otto::Utils.routing_path(env) == @endpoint
133
133
  end
134
134
 
135
135
  # Router-equivalent path normalization. Delegates to the single shared
@@ -132,16 +132,20 @@ class Otto
132
132
  respond(req, res, allowed ? 200 : 403, allowed ? 'OK' : 'Forbidden')
133
133
  end
134
134
 
135
- # @param req [Otto::Request]
135
+ # The body is set for HEAD too. Otto#call empties it for HEAD
136
+ # (Otto::Static.head_response) and sets content-length from this Array,
137
+ # so a HEAD response advertises the length a GET would send. An empty
138
+ # Array here would make that content-length 0.
139
+ #
140
+ # @param _req [Otto::Request] unused; kept for the existing signature
136
141
  # @param res [Otto::Response]
137
142
  # @param status [Integer]
138
143
  # @param body [String]
139
144
  # @return [Otto::Response]
140
- def self.respond(req, res, status, body)
145
+ def self.respond(_req, res, status, body)
141
146
  res.status = status
142
147
  res['content-type'] = 'text/plain'
143
- # HEAD must carry no body (Rack SPEC / Rack::Lint); headers still apply.
144
- res.body = req.head? ? [] : [body]
148
+ res.body = [body]
145
149
  res
146
150
  end
147
151
  end
@@ -85,10 +85,12 @@ class Otto
85
85
  @security_config.trusted_proxy_header = opts[:trusted_proxy_header]
86
86
  end
87
87
 
88
- # Set custom security headers
89
- return unless opts[:security_headers]
88
+ # Keep the generic security_headers option compatible while routing a
89
+ # Referrer-Policy entry through the same validated collection as the
90
+ # dedicated setting. When both are present, the dedicated option wins.
91
+ set_security_headers(opts[:security_headers]) if opts[:security_headers]
90
92
 
91
- set_security_headers(opts[:security_headers])
93
+ @security_config.referrer_policy = opts[:referrer_policy] if opts.key?(:referrer_policy)
92
94
  end
93
95
 
94
96
  def configure_authentication(opts)
@@ -0,0 +1,124 @@
1
+ # lib/otto/core/option_hash.rb
2
+ #
3
+ # frozen_string_literal: true
4
+
5
+ require_relative 'redacted_inspect'
6
+
7
+ class Otto
8
+ module Core
9
+ # The Hash behind Otto#option. freeze_configuration! deep-freezes it, and
10
+ # Ruby's FrozenError message embeds #inspect of the frozen receiver, so a
11
+ # late write such as otto.option[:x] = 1 would print every option,
12
+ # including the MCP bearer tokens.
13
+ #
14
+ # .build and every Hash method that can store a value under a key (#[]=,
15
+ # #store, #merge!, #update, #replace, #transform_values!,
16
+ # #transform_keys!) store the values of .secret_keys as RedactedInspect
17
+ # secrets (a SecretList or SecretSet of SecretStrings, or a
18
+ # SecretString), so a write to the frozen token collection or to one
19
+ # token cannot print them either. #inspect also redacts those keys
20
+ # whatever their value. It is still a Hash, and the token values are
21
+ # still an Array, a Set or a String.
22
+ class OptionHash < Hash
23
+ # Option keys whose values are MCP bearer tokens, in both spellings a
24
+ # caller may use (see Otto::MCP::Options::OPTION_ALIASES).
25
+ def self.secret_keys
26
+ @secret_keys ||= Otto::MCP::Options::OPTION_ALIASES.fetch(:auth_tokens).flat_map do |key|
27
+ [key, key.to_s]
28
+ end.freeze
29
+ end
30
+
31
+ # @param hash [Hash] assembled options
32
+ # @return [OptionHash] a copy with secret values wrapped
33
+ def self.build(hash)
34
+ hash.each_with_object(new) do |(key, value), options|
35
+ options[key] = value
36
+ end
37
+ end
38
+
39
+ # Stores value, wrapped by RedactedInspect.secret when key is one of
40
+ # .secret_keys, so a token assigned after construction is covered too.
41
+ def []=(key, value)
42
+ super(key, self.class.secret_keys.include?(key) ? RedactedInspect.secret(value) : value)
43
+ end
44
+ alias store []=
45
+
46
+ # The other Hash methods that can put a value under a key are written in
47
+ # C and do not call #[]=, so each wraps the secret keys after it runs.
48
+ # (default= and default_proc= set no entry.)
49
+
50
+ # @return [self]
51
+ def merge!(...)
52
+ super
53
+ wrap_secret_values!
54
+ end
55
+ alias update merge!
56
+
57
+ # @return [self]
58
+ def replace(...)
59
+ super
60
+ wrap_secret_values!
61
+ end
62
+
63
+ # @return [self]
64
+ def transform_values!(...)
65
+ result = super
66
+ wrap_secret_values!
67
+ result
68
+ end
69
+
70
+ # @return [self]
71
+ def transform_keys!(...)
72
+ result = super
73
+ wrap_secret_values!
74
+ result
75
+ end
76
+
77
+ # @return [String] Hash#inspect with each secret key's value redacted
78
+ def inspect
79
+ redacted_view.inspect
80
+ end
81
+ alias to_s inspect
82
+
83
+ # Hash#pretty_print walks the pairs itself instead of calling #inspect.
84
+ #
85
+ # @param printer [PP]
86
+ def pretty_print(printer)
87
+ printer.pp(redacted_view)
88
+ end
89
+
90
+ private
91
+
92
+ # Re-store each secret key's value through #[]=, which wraps it.
93
+ def wrap_secret_values!
94
+ self.class.secret_keys.each do |key|
95
+ self[key] = fetch(key) if key?(key)
96
+ end
97
+ self
98
+ end
99
+
100
+ # A plain Hash copy with each secret key's value replaced.
101
+ def redacted_view
102
+ to_h do |key, value|
103
+ [key, self.class.secret_keys.include?(key) ? Placeholder.new(value) : value]
104
+ end
105
+ end
106
+
107
+ # Prints the redaction placeholder for a secret value from #inspect and
108
+ # from pp.
109
+ Placeholder = Struct.new(:value) do
110
+ def inspect
111
+ return 'nil' if value.nil?
112
+ return "#{RedactedInspect::PLACEHOLDER} (#{value.size})" if value.is_a?(Enumerable) && !value.is_a?(Hash)
113
+
114
+ RedactedInspect::PLACEHOLDER
115
+ end
116
+
117
+ def pretty_print(printer)
118
+ printer.text(inspect)
119
+ end
120
+ end
121
+ private_constant :Placeholder
122
+ end
123
+ end
124
+ end
@@ -0,0 +1,149 @@
1
+ # lib/otto/core/redacted_inspect.rb
2
+ #
3
+ # frozen_string_literal: true
4
+
5
+ class Otto
6
+ module Core
7
+ # An #inspect in the format of Object#inspect that leaves out secret
8
+ # values. Ruby's FrozenError message embeds the receiver's #inspect, so a
9
+ # write to a frozen object that holds a secret would otherwise put the
10
+ # secret in the exception message, and from there in logs.
11
+ #
12
+ # Including classes override #redacted_inspect_value for the instance
13
+ # variables that hold secrets and return the placeholder from
14
+ # #redacted_placeholder instead of the value.
15
+ #
16
+ # @example
17
+ # class Holder
18
+ # include Otto::Core::RedactedInspect
19
+ #
20
+ # private
21
+ #
22
+ # def redacted_inspect_value(ivar, value)
23
+ # ivar == :@secret ? redacted_placeholder(value) : super
24
+ # end
25
+ # end
26
+ module RedactedInspect
27
+ # Stands in for a redacted value in #inspect output.
28
+ PLACEHOLDER = '[REDACTED]'
29
+
30
+ # A String whose #inspect is PLACEHOLDER. Content, #to_s, ==, eql? and
31
+ # hash are String's, so it compares, hashes and interpolates as the
32
+ # secret it holds. A write to a frozen one raises a FrozenError whose
33
+ # message shows the placeholder.
34
+ class SecretString < String
35
+ # @return [String] PLACEHOLDER
36
+ def inspect
37
+ PLACEHOLDER
38
+ end
39
+
40
+ # pp prints a multi-line String line by line, each as a plain String.
41
+ #
42
+ # @param printer [PP]
43
+ def pretty_print(printer)
44
+ printer.text(inspect)
45
+ end
46
+ end
47
+
48
+ # An Array of secrets whose #inspect (and #to_s, which Array aliases to
49
+ # its C inspect) shows PLACEHOLDER and the element count. Element access,
50
+ # ==, include? and iteration are Array's. A write to a frozen one raises
51
+ # a FrozenError whose message shows the placeholder.
52
+ class SecretList < Array
53
+ # @return [String] "[REDACTED] (N)"
54
+ def inspect
55
+ "#{PLACEHOLDER} (#{size})"
56
+ end
57
+ alias to_s inspect
58
+
59
+ # @param printer [PP]
60
+ def pretty_print(printer)
61
+ printer.text(inspect)
62
+ end
63
+ end
64
+
65
+ # A Set of secrets whose #inspect, #to_s and #pretty_print show
66
+ # PLACEHOLDER and the element count. Membership, ==, include? and
67
+ # iteration are Set's. A write to a frozen one raises a FrozenError
68
+ # without the elements: before Ruby 3.5 Set raises it for its internal
69
+ # Hash, whose keys print as SecretString placeholders.
70
+ class SecretSet < Set
71
+ # @return [String] "[REDACTED] (N)"
72
+ def inspect
73
+ "#{PLACEHOLDER} (#{size})"
74
+ end
75
+ alias to_s inspect
76
+
77
+ # @param printer [PP]
78
+ def pretty_print(printer)
79
+ printer.text(inspect)
80
+ end
81
+ end
82
+
83
+ # Wrap a secret so its #inspect is redacted: a String becomes a frozen
84
+ # SecretString copy, an Array a SecretList and a Set a SecretSet of
85
+ # such SecretStrings. Other values (nil, or something validation will
86
+ # reject) are returned as given. The strings are frozen so a write to
87
+ # one raises a FrozenError that shows the placeholder, also inside a
88
+ # Set, which Otto::Core::Freezable freezes without its elements.
89
+ #
90
+ # @param value [Object]
91
+ # @return [Object] a copy for a String, Array or Set, value otherwise
92
+ def self.secret(value)
93
+ case value
94
+ when SecretString then value.frozen? ? value : SecretString.new(value).freeze
95
+ when String then SecretString.new(value).freeze
96
+ when Array then SecretList.new(value.map { |item| secret(item) })
97
+ when Set then SecretSet.new(value.map { |item| secret(item) })
98
+ else value
99
+ end
100
+ end
101
+
102
+ # Per-fiber set of objects whose #inspect is running, so an object that
103
+ # is reachable from its own instance variables prints as "...".
104
+ IN_PROGRESS_KEY = :__otto_redacted_inspect_in_progress__
105
+ private_constant :IN_PROGRESS_KEY
106
+
107
+ # @return [String] "#<Class:0x... @ivar=value, ...>" with secret values
108
+ # replaced
109
+ def inspect
110
+ head = Kernel.instance_method(:to_s).bind_call(self).delete_suffix('>')
111
+ in_progress = (Thread.current[IN_PROGRESS_KEY] ||= {}.compare_by_identity)
112
+ return "#{head} ...>" if in_progress.key?(self)
113
+
114
+ in_progress[self] = true
115
+ begin
116
+ fields = instance_variables.map do |ivar|
117
+ "#{ivar}=#{redacted_inspect_value(ivar, instance_variable_get(ivar))}"
118
+ end
119
+ fields.empty? ? "#{head}>" : "#{head} #{fields.join(', ')}>"
120
+ ensure
121
+ in_progress.delete(self)
122
+ end
123
+ end
124
+
125
+ private
126
+
127
+ # The text shown for one instance variable. Override to redact.
128
+ #
129
+ # @param _ivar [Symbol] instance variable name, e.g. :@secret
130
+ # @param value [Object] its value
131
+ # @return [String]
132
+ def redacted_inspect_value(_ivar, value)
133
+ value.inspect
134
+ end
135
+
136
+ # The placeholder for a secret value: nil stays "nil" so an unset secret
137
+ # is still visible, and a collection shows how many values it holds.
138
+ #
139
+ # @param value [Object] the secret value
140
+ # @return [String]
141
+ def redacted_placeholder(value)
142
+ return 'nil' if value.nil?
143
+ return "#{PLACEHOLDER} (#{value.size})" if value.is_a?(Enumerable) && value.respond_to?(:size)
144
+
145
+ PLACEHOLDER
146
+ end
147
+ end
148
+ end
149
+ end