otto 2.9.0 → 2.11.0

data/CHANGELOG.rst

@@ -7,6 +7,203 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.11.0:
+
+2.11.0 — 2026-09-12
+===================
+
+Added
+-----
+
+- ``Otto#mount_static(prefix, root:)`` serves an explicit directory at a URL
+  prefix. See ``docs/guides/routing.md`` for configuration, dispatch
+  precedence, and migration from ``add_static_path``. (#267)
+
+- ``Otto#not_found=`` and ``Otto#server_error=`` now accept callables for
+  per-request fallback responses. A server-error callable can receive the
+  exception; see ``docs/guides/routing.md`` for the callback contract. (#272)
+
+Security
+--------
+
+- Static Rack triples configured with ``Otto#not_found=`` or
+  ``Otto#server_error=`` are now copied for each request, preventing in-place
+  header changes, including ``Set-Cookie``, from being shared between fallback
+  responses. (#272)
+
+Documentation
+-------------
+
+- Documented static-file dispatch precedence and migration from the removed
+  ``add_static_path`` API in ``docs/guides/routing.md``. Corrected stale
+  ``routes_static`` cache guidance in ``docs/guides/configuration_freezing.md``.
+  (#267)
+
+.. _changelog-2.10.0:
+
+2.10.0 — 2026-09-04
+===================
+
+Added
+-----
+
+- ``APIKeyStrategy`` now accepts a block or ``resolver:`` callable instead of a
+  static ``api_keys:`` list, enabling database-, repository-, or cache-backed
+  key lookup. The resolved account becomes the authenticated user.
+
+- ``APIKeyStrategy.digest(key)`` returns a full SHA-256 hex digest for stores
+  that look up generated API keys by digest. See
+  ``docs/guides/authentication.md`` for the resolver contract and credential
+  storage guidance.
+
+- Directly exposed applications can now set ``trusted_proxies: :none`` or call
+  ``trust_no_proxies!`` to distrust every peer. Otto then ignores forwarded
+  client IPs and strips forwarded host, scheme, and port metadata. Leaving proxy
+  trust unconfigured continues to preserve forwarded metadata. Applications
+  behind a reverse proxy, including one on loopback, must explicitly trust it.
+  The sentinel is only valid as the whole option; a list containing it, such
+  as ``['none']``, is rejected at configuration time. See
+  ``docs/guides/forwarded-authority.md`` for configuration guidance. (#259)
+
+Changed
+-------
+
+- MCP options now accept String or Symbol keys consistently and fail at boot
+  for unknown, conflicting, or invalid values. Constructor gating options must
+  be exactly ``true`` or ``false``; nil or blank token values are rejected.
+  Before upgrading, check option names against the `MCP guide
+  <docs/guides/mcp.md>`__. (#258)
+
+- ``enable_mcp!`` now rejects constructor-only gating options and repeated
+  enablement. Pass all MCP settings in one ``Otto.new`` or ``enable_mcp!`` call.
+  (#258)
+
+- MCP ``Rack::Attack`` throttle names are now endpoint-qualified, such as
+  ``mcp_requests:/_mcp`` and ``mcp_tool_calls:/_mcp``. Update integrations that
+  inspect throttle names directly. (#258)
+
+- Otto applications in one process that resolve proxied requests must now use
+  the same forwarded-header family; incompatible configurations fail during
+  configuration. CIDR-based proxy trust supports only ``X-Forwarded-*`` headers; use
+  depth-based trust for ``Forwarded`` or both families. See
+  ``docs/guides/forwarded-authority.md`` for configuration guidance. (#252)
+
+- Literal routes now consistently take precedence over static files at the same
+  path, regardless of which static files were requested earlier. Static files
+  continue to take precedence over dynamic routes. (#260)
+
+- MaxMind-backed database paths now require ``maxmind-db ~> 1.2``. Before
+  upgrading, declare that range or provide a compatible reader object. See the
+  `geo-country <docs/guides/geo-country.md>`__ and
+  `enrichment <docs/guides/enrichment.md>`__ guides. (#255)
+
+Removed
+-------
+
+- Removed ``add_static_path`` and the ``routes_static`` cache interface. Static
+  files are discovered directly from the configured ``public`` directory and
+  no longer need registration. (#260)
+
+- Removed the unused ``rack-parser`` and ``rexml`` runtime dependencies.
+  Applications using either gem directly must now declare it themselves.
+  (#255)
+
+Fixed
+-----
+
+- MCP middleware now executes rate limiting, authentication, and schema
+  validation in that order. Configured endpoints with a trailing slash are also
+  routable. (#258)
+
+- Repeated MCP rate-limit configuration no longer produces duplicate throttle
+  log entries. (#258)
+
+- MCP JSON-RPC errors now consistently use HTTP 400 for protocol errors, 404
+  for unknown resources or tools, and 500 for handler or server failures.
+  Unknown tools no longer return 500, failing resource handlers no longer
+  appear missing, and handler exception details are logged instead of returned
+  to clients. (#257)
+
+- ``StrategyResult#has_role?`` and ``#has_permission?`` now derive their answer
+  from ``#roles`` and ``#permissions``, so the predicates agree with the
+  accessors for object-backed users exposing ``#roles`` and for ``Set`` or
+  other non-Array collections. A user model defining its own ``#has_role?`` or
+  ``#has_permission?`` is still consulted first.
+
+- MCP rate-limited requests now emit one ``rack.attack`` log entry instead of
+  two. (#255)
+
+Security
+--------
+
+- ``APIKeyStrategy`` now requires exactly one key source and rejects empty
+  static key lists at construction. Invalid presented credentials terminate a
+  multi-strategy authentication chain. Static keys are compared in constant
+  time as fixed-width SHA-256 digests, so configured key lengths are not
+  observable through timing. Blank credentials, empty or whitespace-only, are
+  rejected before any key source is consulted. (#256)
+
+- Successful authentication results no longer expose the raw API key in
+  strategy-generated fields. Static-list callers should replace
+  ``user[:api_key]`` with ``user[:api_key_fingerprint]``. (#256)
+
+- ``APIKeyStrategy`` now reads only the configured header by default. Applications
+  that still accept query or form parameters must opt in with ``param_name:``;
+  see ``docs/guides/authentication.md`` for configuration guidance. (#256)
+
+- Fixed MCP bearer-token authentication being silently omitted when configured
+  through ``Otto.new`` or with String-keyed options. Deployments exposing MCP
+  beyond a trusted local environment should upgrade and verify their
+  ``auth_tokens`` configuration. Intentionally open endpoints now warn unless
+  acknowledged with ``allow_unauthenticated: true``. See the `MCP guide
+  <docs/guides/mcp.md>`__. (#258)
+
+- MCP authentication now fails closed when its authenticator is unavailable.
+  Authentication, validation, and rate limiting also apply only to the exact
+  routed MCP endpoint. (#258)
+
+- MCP rate limiting now honors configured limits and protects custom endpoints,
+  Rack-mounted applications, and distinct MCP endpoints in the same process.
+  Mount ``Rack::Attack`` inside the same ``map`` block as Otto, and use distinct
+  endpoint paths when applications require isolated counters. (#258)
+
+- Static-file serving now rejects symlinks that resolve outside the configured
+  public directory, preventing files outside that root from being served on
+  first access or after another file has populated the directory cache.
+  Symlinks that resolve within the public directory, including a symlinked
+  public root, remain supported. (#257)
+
+- When proxy trust is configured, forwarded host, scheme, and port metadata
+  from untrusted peers is now stripped before it can affect Rack's request
+  authority. Requests from trusted peers retain this metadata; see
+  ``docs/guides/forwarded-authority.md`` for deployment guidance. (#252)
+
+- ``IPPrivacyMiddleware`` enforces its own proxy trust posture even when an
+  outer instance already resolved ``otto.client_ip``. ``trusted_proxies: :none``
+  always strips forwarded authority; a CIDR configuration that can no longer
+  match the connecting peer treats it as untrusted and logs a warning. (#259)
+
+- ``env['otto.peer_relayed']`` records whether a request carried any relay
+  marker header, evaluated before forwarded carriers may be deleted, so
+  ``Otto::CaddyTLS::LocalhostGuard`` still refuses a relayed loopback call once
+  the carriers are stripped. The relay markers cover every carrier the scrub
+  deletes, including ``X-Forwarded-Host`` and the other authority headers, not
+  only the client-IP carriers. (#259)
+
+- MCP now stops configuration with ``Otto::OptionalDependencyError`` rather
+  than starting without enabled schema validation or rate limiting. Before
+  upgrading, add ``json_schemer ~> 2.0`` and ``rack-attack ~> 6.7`` for the
+  default protections, or explicitly set ``enable_validation: false`` or
+  ``enable_rate_limiting: false`` only when that protection is not required.
+  See the `MCP guide <docs/guides/mcp.md>`__. (#255)
+
+Documentation
+-------------
+
+- Added the `MCP guide <docs/guides/mcp.md>`__ covering secure enablement,
+  supported options, authentication, validation, rate limiting, mounted
+  applications, and error behavior. (#258)
+
 .. _changelog-2.9.0:
 
 2.9.0 — 2026-08-18
@@ -790,6 +987,44 @@ Added
 2.0.0 — 2026-03-14
 ==================
 
+This is the stable release of Otto v2, the culmination of 10 pre-releases
+since September 2025.
+
+Highlights
+----------
+
+- **Modular architecture**: the core ``Otto`` class is now a thin composition
+  of focused modules (Router, FileSafety, Configuration, ErrorHandler,
+  UriGenerator).
+- **Security by default**: IP masking, user agent anonymization, CSRF
+  protection, input validation, and backtrace sanitization.
+- **Privacy by default**: public IP masking, country-level geo-location only
+  (no external APIs), daily-rotating IP hashes for analytics.
+- **Handler-level authentication**: authentication moved from middleware to
+  ``RouteAuthWrapper``, so it runs after routing.
+- **Configuration freezing**: configuration is frozen after the first request
+  to prevent runtime security bypasses.
+- **MCP support**: JSON-RPC 2.0 endpoints for CLI automation and integrations.
+- **Base error classes**: ``NotFoundError``, ``BadRequestError``,
+  ``ForbiddenError`` and friends, with automatic HTTP status codes.
+- **Request/response helpers**: extensible ``Otto::Request`` and
+  ``Otto::Response`` with application-specific helper registration.
+
+Breaking changes
+----------------
+
+Individual breaking changes are documented in the pre-release entries below.
+The migrations most applications need:
+
+- Logic class constructor: ``initialize(session, user, params, locale)`` →
+  ``initialize(context, params, locale)``
+- Middleware stack: ``otto.middleware_stack <<`` → ``otto.use()``
+- Request callbacks: ``Otto.on_request_complete`` → ``otto.on_request_complete``
+  (instance method)
+
+See `docs/migrating/v2.0.0.md <docs/migrating/v2.0.0.md>`__ for the full
+upgrade guide.
+
 Added
 -----
 

data/Gemfile

@@ -18,9 +18,9 @@ end
 # bundle config set with 'optional'
 group :development, :test, optional: true do
   # Keep gems that need to be in both environments
-  gem 'json_schemer'
+  gem 'json_schemer', '~> 2.0'
   gem 'maxmind-db', '~> 1.2' # Optional geo DB reader; exercised by geo specs
-  gem 'rack-attack'
+  gem 'rack-attack', '~> 6.7'
   gem 'reek', '~> 6.5'
 end
 
@@ -29,7 +29,7 @@ group :development do
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
   gem 'rake', '~> 13.4', require: false # Provides `rake release` for release-gem.yml
-  gem 'rubocop', '~> 1.89.0', require: false
+  gem 'rubocop', '~> 1.90.0', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,13 +1,11 @@
 PATH
   remote: .
   specs:
-    otto (2.9.0)
+    otto (2.11.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
       rack (~> 3.1, < 4.0)
-      rack-parser (~> 0.7)
-      rexml (~> 3.4)
 
 GEM
   remote: https://rubygems.org/
@@ -106,18 +104,16 @@ GEM
       date
       stringio
     racc (1.8.1)
-    rack (3.2.6)
+    rack (3.2.7)
     rack-attack (6.8.0)
       rack (>= 1.0, < 4)
-    rack-parser (0.7.0)
-      rack
     rack-test (2.2.0)
       rack (>= 1.3)
     rackup (2.3.1)
       rack (>= 3)
     rainbow (3.1.1)
     rake (13.4.2)
-    rbs (4.0.3)
+    rbs (4.1.3)
       logger
       prism (>= 1.6.0)
       tsort
@@ -148,8 +144,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.89.0)
-      json (~> 2.3)
+    rubocop (1.90.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -162,9 +158,9 @@ GEM
     rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    rubocop-performance (1.26.1)
+    rubocop-performance (1.27.0)
       lint_roller (~> 1.1)
-      rubocop (>= 1.75.0, < 2.0)
+      rubocop (>= 1.89.0, < 2.0)
       rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rspec (3.10.2)
       lint_roller (~> 1.1)
@@ -174,7 +170,7 @@ GEM
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.10)
+    ruby-lsp (0.26.11)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -217,17 +213,17 @@ PLATFORMS
 DEPENDENCIES
   benchmark
   debug
-  json_schemer
+  json_schemer (~> 2.0)
   kramdown
   maxmind-db (~> 1.2)
   otto!
-  rack-attack
+  rack-attack (~> 6.7)
   rack-test
   rackup
   rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.89.0)
+  rubocop (~> 1.90.0)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/README.md

@@ -1,22 +1,41 @@
-# Otto - A Ruby Gem
+# Otto - All Rack, no Pinion
 
-**Define your rack-apps in plain-text with built-in security.**
-
-> **v2.0.0-pre6 Available**: This pre-release includes major improvements to middleware management, logging, and request callback handling. See [changelog](CHANGELOG.rst) for details and upgrade notes.
+**Define Rack apps in plain text, with privacy by default and opt-in security features.**
 
 ![Otto mascot](public/img/otto.jpg "Otto - All Rack, no Pinion")
 
-Otto apps have three files: a rackup file, a Ruby class, and a routes file. The routes file is just plain text that maps URLs to Ruby methods.
+Otto apps have three files: a rackup file, a Ruby class, and a routes file. The routes file is plain text that maps URLs to Ruby methods.
+
+## Quick start
+
+Requirements: Ruby `>= 3.2, < 4.1` and Rack `>= 3.1, < 4.0`. Ruby 3.2
+remains compatibility-tested after upstream end of life, but receives no
+interpreter security maintenance. See the [runtime and dependency security
+policy](docs/reference/runtime-and-dependency-security.md) for support tiers and
+consumer lockfile requirements.
 
-```bash
-$ cd myapp && ls
-config.ru app.rb routes
+Install Otto and the Rack server CLI, then create the three files shown below:
+
+```sh
+gem install otto rackup
+mkdir myapp && cd myapp
+```
+
+After creating `routes`, `app.rb`, and `config.ru`, start the app and verify the response:
+
+```sh
+rackup config.ru
+# In another terminal:
+curl -i http://127.0.0.1:9292/
+# HTTP/1.1 200 OK
+# ...
+# <h1>Hello Otto</h1>
 ```
 
 ## Why Otto?
 
-- **Security by Default**: Automatic IP masking for public addresses, user agent anonymization, CSRF protection, and input validation
-- **Privacy First**: Masks public IPs, strips user agent versions, provides country-level geo-location only—no external APIs needed
+- **Privacy by Default**: Masks public IP addresses and anonymizes user agents; country-level geo-location needs no external API
+- **Opt-in Security Features**: CSRF protection, input validation, security headers, and trusted-proxy configuration
 - **Simple Routing**: Define routes in plain-text files with zero configuration overhead
 - **Built-in Authentication**: Multiple strategies including API keys, tokens, role-based access, and custom implementations
 - **Developer Friendly**: Works with any Rack server, minimal dependencies, easy testing and debugging
@@ -26,10 +45,8 @@ config.ru app.rb routes
 # routes
 
 GET   /                         App#index
-POST  /feedback                 App#receive_feedback
 GET   /product/:id              App#show_product
 GET   /robots.txt               App#robots_text
-GET   /404                      App#not_found
 ```
 
 ## Ruby Class
@@ -37,6 +54,8 @@ GET   /404                      App#not_found
 # app.rb
 
 class App
+  attr_reader :req, :res
+
   def initialize(req, res)
     @req, @res = req, res
   end
@@ -51,7 +70,7 @@ class App
   end
 
   def robots_text
-    res.header['Content-Type'] = "text/plain"
+    res.headers['content-type'] = 'text/plain'
     rules = 'User-agent: *', 'Disallow: /private/keep/out'
     res.body = rules.join($/)
   end
@@ -63,9 +82,9 @@ end
 # config.ru
 
 require 'otto'
-require 'app'
+require_relative 'app'
 
-run Otto.new("./routes")
+run Otto.new('routes')
 ```
 
 
@@ -82,7 +101,27 @@ app = Otto.new("./routes", {
 })
 ```
 
-Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
+Security features include CSRF protection, input validation, security headers, rate limiting, and trusted proxy configuration.
+
+### Rate limiting (`rack-attack`)
+
+Rate limiting requires `rack-attack` 6.7.0 or newer in the 6.x series. Add the
+optional dependency and mount it before Otto; `enable_rate_limiting!` configures
+rules, while `Rack::Attack` enforces them:
+
+```ruby
+# Gemfile
+gem 'rack-attack', '~> 6.7'
+
+# config.ru
+use Rack::Attack
+app = Otto.new('./routes')
+app.enable_rate_limiting!(requests_per_minute: 50)
+run app
+```
+
+Enabling rate limiting raises `Otto::OptionalDependencyError` at configuration
+time when the gem is missing or outside the supported range.
 
 ### Content Security Policy (nonce-based emission)
 
@@ -300,7 +339,7 @@ Private and localhost IPs are exempted by default for development convenience, b
 ```ruby
 otto.configure_ip_privacy(
   geo_header: 'X-Client-Country',        # trusted app header, checked first
-  geo_db_path: 'data/country.mmdb'       # offline fallback (needs the maxmind-db gem)
+  geo_db_path: 'data/country.mmdb'       # offline fallback (needs maxmind-db >= 1.2.0, < 2)
 )
 ```
 
@@ -395,8 +434,9 @@ on_demand_tls {
 
 Secure by default: the endpoint is restricted to the loopback interface (the guard
 authenticates the raw TCP peer, so a spoofed `X-Forwarded-For` cannot help), and
-every layer fails closed. See [docs/reverse-proxy-network-services.md](docs/reverse-proxy-network-services.md)
-for the design and deployment notes.
+every layer fails closed. See the [Caddy TLS guide](docs/guides/caddy-tls.md)
+for deployment guidance and [ADR-003](docs/adr/adr-003-caddy-tls-route-based-integration.md)
+for rationale.
 
 ## Examples
 
@@ -406,7 +446,7 @@ Otto includes comprehensive examples demonstrating different features:
 - **[Advanced Routes](examples/advanced_routes/)** - Response types, CSRF exemption, logic classes, and namespaced routing
 - **[Authentication Strategies](examples/authentication_strategies/)** - Token, API key, and role-based authentication
 - **[Security Features](examples/security_features/)** - CSRF protection, input validation, file uploads, and security headers
-- **[MCP Demo](examples/mcp_demo/)** - JSON-RPC 2.0 endpoints for CLI automation and integrations
+- **[MCP Demo](examples/mcp_demo/)** - JSON-RPC 2.0 endpoints for CLI automation and integrations (see the [MCP guide](docs/guides/mcp.md))
 - **[Caddy on-demand TLS](examples/caddy_tls_demo/)** - Reverse-proxy permission endpoint via `Otto::CaddyTLS`
 
 ### Standalone Tutorials
@@ -417,32 +457,30 @@ Otto includes comprehensive examples demonstrating different features:
 
 See the [examples/](examples/) directory for more.
 
-## Requirements
 
-- Ruby 3.2+
-- Rack 3.1+
+## Documentation
 
-## Installation
+- **[Documentation map](docs/README.md)** - Capabilities, current guides, and the documentation structure Otto is growing toward
+- **[Runtime and dependency security policy](docs/reference/runtime-and-dependency-security.md)** - Ruby compatibility, dependency-range guarantees, and consumer lockfile auditing
+- **[CHANGELOG.rst](CHANGELOG.rst)** - Version history, breaking changes, and upgrade notes
 
-```bash
-gem install otto
-```
+## AI-assisted development
 
-## Documentation
+AI tools have contributed to Otto since v1.2.0. They are used for implementation, testing, documentation, maintenance, and additional code review.
 
-- **[AGENTS.md](AGENTS.md)** - Comprehensive developer guidance covering authentication architecture, configuration freezing, IP privacy, structured logging, and multi-app patterns
-- **[docs/](docs/)** - Technical guides and migration guides
-- **[CHANGELOG.rst](CHANGELOG.rst)** - Version history, breaking changes, and upgrade notes
+### Tools used
 
-## AI Development Assistance
+* **Claude Code CLI (Opus and Fable)** - Primary development tool for implementation, test coverage, and adversarial review
+* **Greptile and GitHub Copilot** - Pull request reviews
+* **Claude Desktop routines** - Unattended cloud agents that run on a cron schedule and open pull requests for maintenance chores. Nobody is at the keyboard for these, so they go through the same PR review as human work.
 
-Version 1.2.0's security features were developed with AI assistance:
+### How it is tracked
 
-* **Zed Agent (Claude Sonnet 4)** - Security implementation and testing
-* **Claude Desktop** - Rack 3+ compatibility and debugging
-* **GitHub Copilot** - Code completion
+* All PR reviews are publicly visible. The `greptile-review` and `claude-review` labels are applied to PRs that have been reviewed.
+* Release notes in [CHANGELOG.rst](CHANGELOG.rst) list AI-assisted work under an "AI Assistance" heading.
+* [AGENTS.md](AGENTS.md) sets the conventions agents follow in this repository.
 
-The maintainer remains responsible for all security decisions and implementation. We believe in transparency about development tools, especially for security-focused software.
+The maintainer reviews the resulting changes and remains responsible for security, implementation, and releases.
 
 ## License