otto 2.9.0 → 2.10.0

data/docs/guides/geo-country.md

@@ -0,0 +1,168 @@
+# Geo-country resolution
+
+Otto exposes a country-level ISO 3166-1 alpha-2 code as `req.geo_country` and
+`env['otto.privacy.geo_country']`. It does not expose city or region data. For a
+request that enters the privacy fingerprint, enabled but unresolved geo returns
+`**`. The value is `nil` when IP privacy or geo resolution is disabled, or when
+a private/loopback request is exempt from the fingerprint.
+
+For the surrounding privacy profiles and environment-key contracts, see
+[Privacy-preserving request data](privacy.md). ASN and anonymizer signals are
+covered separately in [ASN and anonymizer enrichment](enrichment.md).
+
+## Resolution order
+
+For requests handled by Otto, the first valid result wins:
+
+1. the application-configured `geo_header`;
+2. built-in provider headers for Cloudflare, AWS CloudFront, Fastly, Akamai,
+   Azure Front Door, Vercel, and several semi-standard country headers;
+3. the process-wide `Otto::Privacy::GeoResolver.custom_resolver` callable;
+4. a local MMDB reader configured with `geo_db_path` or `geo_db_reader`;
+5. `**` when no source resolves a country.
+
+Header sources are consulted only when the request arrived through a configured
+CIDR trusted proxy. See [Trust geo headers](#trust-geo-headers).
+
+The middleware gives custom resolvers a copy of the Rack environment with the
+client address masked or removed. The local database lookup also masks the IP
+again before calling its reader. A custom resolver called directly outside the
+middleware does not receive that additional environment protection.
+
+## Configure a trusted header or local database
+
+All configuration is boot-time only and must be complete before the first
+request:
+
+```ruby
+otto.configure_ip_privacy(
+  geo: true,                              # default
+  geo_header: 'X-Client-Country',         # optional trusted header
+  geo_db_path: 'data/user-country.mmdb'   # optional local fallback
+)
+```
+
+- `geo: false` disables all country resolution and releases the loaded reader.
+- `geo_header:` accepts an HTTP header name such as `X-Client-Country` or its
+  Rack key, `HTTP_X_CLIENT_COUNTRY`. A blank string clears the setting.
+- `geo_db_path:` opens the database in memory during configuration. A blank
+  string clears the path. An unreadable or invalid file raises `ArgumentError`;
+  a missing or incompatible `maxmind-db` gem raises
+  `Otto::OptionalDependencyError`.
+- `geo_db_reader:` accepts an object responding to `#get(ip)`. It wins over a
+  path supplied in the same call and lets applications use another MMDB reader
+  or a test double.
+
+Omitting a keyword leaves its current value unchanged. Supplying a new path
+without a reader clears an earlier reader override.
+
+`Otto::Privacy::GeoResolver.custom_resolver` is different from the options
+above: it is shared by every Otto instance in the process. Set it once during
+single-threaded initialization. For per-application behavior, prefer
+`geo_db_reader:`.
+
+## Install the MMDB reader
+
+The [`maxmind-db`](https://rubygems.org/gems/maxmind-db) gem is optional. Otto
+accepts versions 1.2 or newer within the 1.x series. Add it to the application:
+
+```sh
+bundle add maxmind-db --version '~> 1.2'
+```
+
+Applications that manage `Gemfile` entries manually can instead add
+`gem 'maxmind-db', '~> 1.2'` and run `bundle install`.
+
+## Download a current country database
+
+Otto does not bundle country data. The current
+[`user-country`](https://github.com/sapics/ip-location-db/tree/main/user-country/)
+dataset from `sapics/ip-location-db` is an IPv4-and-IPv6 country MMDB updated
+daily. Upstream recommends it for general end-user country lookup and publishes
+it under PDDL 1.0. Review the upstream methodology and license for the version
+you deploy.
+
+The older `geo-whois-asn-country.mmdb` asset is no longer published. Use the
+current release asset and checksum URLs:
+
+```sh
+mkdir -p data
+curl -fL --retry 3 \
+  -o data/user-country.mmdb \
+  https://github.com/sapics/ip-location-db/releases/download/latest/user-country.mmdb
+curl -fL --retry 3 \
+  -o data/user-country.mmdb.sha256 \
+  https://github.com/sapics/ip-location-db/releases/download/checksum/user-country.mmdb.sha256
+```
+
+Verify the download from the directory containing both files:
+
+```sh
+(cd data && shasum -a 256 -c user-country.mmdb.sha256)      # macOS/BSD
+# or
+(cd data && sha256sum --check user-country.mmdb.sha256)     # GNU/Linux
+```
+
+Inspect a lookup before configuring Otto:
+
+```sh
+bundle exec ruby -rmaxmind/db -e \
+  "p MaxMind::DB.new('data/user-country.mmdb', mode: MaxMind::DB::MODE_MEMORY).get('8.8.8.8')"
+```
+
+The result should be a hash containing a two-letter `country_code`. Otto also
+accepts GeoLite2-style nested `country.iso_code` records and a bare string in
+the `country` field. Other MMDB datasets can therefore work, but their licenses,
+update requirements, schemas, and accuracy remain the operator's responsibility.
+
+Refresh the data on an operational schedule and verify the checksum before
+replacing the active file. Because Otto opens the file at boot, restart the
+application after replacement.
+
+## Understand masking and accuracy
+
+Database and custom-resolver lookups in the middleware receive a masked address.
+For IPv4, the default `octet_precision: 1` keeps a `/24`; `octet_precision: 2`
+keeps a `/16`. For IPv6, those settings keep `/48` and `/32`, respectively.
+Masking can therefore reduce lookup accuracy when a database has more-specific
+country ranges, especially for IPv6 and the coarser precision setting. Such a
+miss falls through to `**`.
+
+Header results do not depend on the masked address. Keep the default precision
+and test representative IPv4 and IPv6 ranges if the MMDB fallback is important
+to the application.
+
+## Trust geo headers
+
+Country headers are client-spoofable unless Otto can verify the connecting
+proxy. Configure the CDN or reverse proxy addresses as trusted CIDRs:
+
+```ruby
+otto = Otto.new(
+  'routes',
+  trusted_proxies: ['10.0.0.0/8', '192.0.2.0/24']
+)
+```
+
+Otto ignores configured and built-in geo headers when:
+
+- proxy trust is not configured;
+- `trusted_proxies: :none` is configured;
+- the connecting peer does not match a configured trusted proxy; or
+- count-based `trusted_proxy_depth` mode is used.
+
+A configured `geo_header` and `trusted_proxy_depth` are rejected together at
+configuration time. In depth-mode deployments, use `geo_db_path` or
+`geo_db_reader` instead. For the broader forwarded-header boundary, see
+[Forwarded host authority](forwarded-authority.md).
+
+## Behavior summary
+
+| Scenario | Result |
+| --- | --- |
+| Trusted configured header contains a valid code | Wins over provider headers |
+| Geo headers are not trusted | Headers are skipped; resolver/database fallback continues |
+| Local database lookup | Receives only the masked IP |
+| `geo: false`, IP privacy disabled, or privacy-exempt request | `nil` |
+| Enabled, but nothing resolves | `**` |
+| Invalid path or database | Configuration fails at boot |

data/docs/guides/ip_privacy.md

@@ -0,0 +1,39 @@
+# Configure IP privacy
+
+This page is a short entry point for existing links and searches. The canonical
+[privacy guide](privacy.md) documents Otto's current profiles, request helpers,
+environment keys, proxy trust boundary, and middleware placement.
+
+## Choose a profile
+
+Configure privacy before the first request:
+
+```ruby
+otto = Otto.new('routes')
+otto.configure_ip_privacy(profile: :masked)     # default: mask public IPs
+otto.configure_ip_privacy(profile: :anonymous)  # also mask private and loopback IPs
+```
+
+Use `profile: :audit` only when the application must retain resolved client IPs
+and the deployment has its own access, logging, and retention controls. See
+[Profiles](privacy.md#profiles) for the exact behavior of each profile.
+
+These profiles are technical data-minimization controls. They do not determine
+whether an application complies with GDPR, CCPA, or another legal regime.
+Compliance also depends on the application's purposes, notices, retention,
+access controls, vendors, and jurisdiction.
+
+## Complete common tasks
+
+- Read the current request helpers and Rack environment keys in
+  [Privacy-safe request values](privacy.md#privacy-safe-request-values).
+- Put privacy ahead of logging and monitoring middleware outside Otto's own
+  stack by following [Middleware placement](privacy.md#middleware-placement).
+- Configure forwarded client-IP trust in
+  [Trusted proxy and matching boundaries](privacy.md#trusted-proxy-and-matching-boundaries).
+- Configure country lookup in [Geo-country resolution](geo-country.md).
+- Configure opt-in ASN or anonymizer lookup in
+  [ASN and anonymizer enrichment](enrichment.md).
+
+Do not copy configuration or environment-key examples from older versions of
+this page; use the linked canonical sections instead.

data/docs/guides/ipaddr-encoding-quirk.md

@@ -0,0 +1,56 @@
+# Implementation note: `IPAddr#to_s` string encoding
+
+This note documents why Otto normalizes IP strings produced by its masking
+helpers. It is an implementation detail, not a claim about every Ruby 3 release
+or every version of the `ipaddr` default gem.
+
+## Verified behavior
+
+Otto's blocking compatibility targets are Ruby 3.2, 3.3, and 3.4. The following
+behavior was reproduced locally with representative installed patch releases:
+
+| Ruby | `ipaddr` | IPv4 `IPAddr#to_s` | IPv6 `IPAddr#to_s` |
+| --- | --- | --- | --- |
+| 3.2.4 | 1.2.5 | `US-ASCII` | `UTF-8` |
+| 3.3.5 | 1.2.7 | `US-ASCII` | `UTF-8` |
+| 3.4.10 | 1.2.7 | `US-ASCII` | `UTF-8` |
+
+Ruby 4.0.6 with `ipaddr` 1.2.8 showed the same result, but Ruby 4.0 is a
+provisional, non-blocking Otto target. See the
+[runtime and dependency security policy](../reference/runtime-and-dependency-security.md)
+for the current support matrix.
+
+You can check the active runtime directly:
+
+```ruby
+require 'ipaddr'
+
+puts RUBY_DESCRIPTION
+puts IPAddr::VERSION if defined?(IPAddr::VERSION)
+p IPAddr.new('192.168.1.1').to_s.encoding
+p IPAddr.new('::1').to_s.encoding
+```
+
+The result comes from the `ipaddr` implementation's separate IPv4 and IPv6
+formatting paths. Treat it as version-specific behavior and rerun the check when
+changing Ruby or overriding the default `ipaddr` gem.
+
+## Otto's normalization
+
+An IP address string contains only ASCII bytes, so relabeling a generated
+`US-ASCII` address as `UTF-8` does not change its bytes. Otto uses this at the
+boundary where `IPPrivacy.mask_ip` creates IPv4 and IPv6 strings:
+
+```ruby
+IPAddr.new(masked_integer, address_family).to_s.force_encoding(Encoding::UTF_8)
+```
+
+This gives downstream Rack code one encoding for Otto-generated masked
+addresses. A `US-ASCII` string is normally compatible with UTF-8 text; the
+encoding difference alone does not imply an error. Normalization prevents code
+that requires an explicit UTF-8 label from receiving different labels for IPv4
+and IPv6.
+
+Use `force_encoding` here only because Otto constructed the value from an IP
+address and therefore knows every byte is ASCII. Do not apply the same operation
+to arbitrary external bytes without validating or transcoding them first.

data/docs/guides/mcp.md

@@ -0,0 +1,282 @@
+# Model Context Protocol (MCP)
+
+`Otto::MCP` adds one JSON-RPC 2.0 HTTP endpoint to an Otto application. An MCP
+client can use that endpoint to initialize a connection, list registered
+resources and tools, read resources, and call tools. The default endpoint is
+`POST /_mcp`.
+
+MCP is opt-in. It can invoke the handlers that you register, so require bearer
+tokens before exposing the endpoint outside a trusted local environment.
+
+## Before you start
+
+MCP validation and rate limiting are enabled by default. Add their optional
+dependencies to the application's `Gemfile` before enabling MCP:
+
+```ruby
+# Gemfile
+gem 'json_schemer', '~> 2.0'
+gem 'rack-attack', '~> 6.7'
+```
+
+Mount `Rack::Attack` in the Rack application. Without it, the configured MCP
+rate limits are not enforced.
+
+```ruby
+# config.ru
+use Rack::Attack
+run otto
+```
+
+If a dependency is missing, enabling its corresponding feature raises
+`Otto::OptionalDependencyError`. You may disable validation or rate limiting
+with `enable_validation: false` or `enable_rate_limiting: false`, but doing so
+removes that protection.
+
+Configure MCP during boot, before Otto serves its first request. See
+[configuration freezing](configuration_freezing.md) for the lifecycle rule.
+
+## Enable a protected endpoint
+
+Use `mcp_enabled: true` when constructing the application. Use
+`ENV.fetch('MCP_TOKEN')` without a default so a missing deployment secret stops
+boot instead of creating an open endpoint.
+
+```ruby
+# config.ru
+require 'otto'
+require_relative 'app'
+
+otto = Otto.new('routes',
+  mcp_enabled: true,
+  mcp_auth_tokens: [ENV.fetch('MCP_TOKEN')],
+  mcp_requests_per_minute: 120,
+  mcp_tool_calls_per_minute: 30,
+)
+
+use Rack::Attack
+run otto
+```
+
+The endpoint is `POST /_mcp` unless `mcp_endpoint:` (or `http_endpoint:`) sets
+another slash-prefixed path. `mcp_enabled?` returns `true` after MCP has been
+enabled.
+
+For multi-step boot configuration, call `enable_mcp!` instead:
+
+```ruby
+otto = Otto.new('routes')
+otto.enable_mcp!(
+  http_endpoint: '/api/mcp',
+  auth_tokens: [ENV.fetch('MCP_TOKEN')],
+)
+```
+
+Enable MCP only once per `Otto` instance. A second call raises `ArgumentError`;
+provide all MCP settings in the first call.
+
+## Register resources and tools
+
+Declare resources and tools in the normal Otto routes file. The initial verb
+and path are required by the route-file grammar, but they do not create HTTP
+routes for these declarations. Otto registers the MCP definition that follows
+them. The single MCP HTTP endpoint remains the only transport route.
+
+```text
+# routes
+GET  /mcp/users        MCP users AppMCP.users
+POST /mcp/create-user  TOOL create_user AppMCP.create_user
+```
+
+`MCP` registers a resource. Its resource URI is `users`: Otto removes one
+leading slash from the declaration. The handler must be a zero-argument class
+method. Otto returns its value as text with the `text/plain` MIME type.
+
+`TOOL` registers a tool. Its handler is a class method that receives
+`arguments` and the Rack `env`:
+
+```ruby
+# app.rb
+require 'json'
+
+class AppMCP
+  def self.users
+    JSON.generate(users: [{ id: 1, name: 'Ada' }])
+  end
+
+  def self.create_user(arguments, _env)
+    "Created user: #{arguments.fetch('name')}"
+  end
+end
+```
+
+A resource declaration currently supplies its name, description, and MIME type
+automatically: the resource URI determines the name, descriptions are generated
+from the URI or tool name, and resources use `text/plain`. Tool declarations
+currently advertise an empty input schema. A tool still receives the
+`params.arguments` object supplied by the client, so validate its fields in the
+handler before using them.
+
+## Call the endpoint
+
+Every request must be a JSON-RPC 2.0 `POST` with
+`Content-Type: application/json`. A request needs `jsonrpc`, `id`, and
+`method`; `params`, when present, must be an object.
+
+Pass a configured token in either header. `Authorization` is checked first.
+
+```text
+Authorization: Bearer <token>
+X-MCP-Token: <token>
+```
+
+Initialize the connection:
+
+```sh
+curl -sS -X POST http://localhost:9292/_mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer s3cret' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+```
+
+Replace `s3cret` in these requests with a configured token. A successful
+response has the same `id` and a `result` containing the protocol version,
+supported capabilities, and server information.
+
+After registering the preceding routes, list the available resources and tools:
+
+```sh
+curl -sS -X POST http://localhost:9292/_mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer s3cret' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"resources/list","params":{}}'
+
+curl -sS -X POST http://localhost:9292/_mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer s3cret' \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}'
+```
+
+Read the `users` resource or call the `create_user` tool:
+
+```sh
+curl -sS -X POST http://localhost:9292/_mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer s3cret' \
+  -d '{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"users"}}'
+
+curl -sS -X POST http://localhost:9292/_mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer s3cret' \
+  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"create_user","arguments":{"name":"Ada"}}}'
+```
+
+## Authentication
+
+`auth_tokens:` accepts a string or an array of strings. The endpoint accepts a
+request when the token matches any configured token. Missing, malformed, or
+unknown credentials return HTTP `401` and this JSON-RPC error:
+
+```json
+{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"Unauthorized","data":"Valid token required"}}
+```
+
+Supplying `nil`, a blank string, or an otherwise empty token value raises
+`ArgumentError`. An explicit empty array means no token authentication is
+mounted, so do not use it as a way to disable access.
+
+For a deliberate localhost-only endpoint, omit `auth_tokens:` and acknowledge
+that choice explicitly:
+
+```ruby
+otto.enable_mcp!(allow_unauthenticated: true)
+```
+
+This option only suppresses Otto's unauthenticated-endpoint warning; it does
+not add or remove authentication. An open endpoint lets any caller list and
+invoke every registered MCP resource and tool.
+
+## Configuration reference
+
+Both enablement forms accept the canonical option names below and the listed
+`mcp_` aliases. Keys may be Symbols or Strings. Providing two spellings of one
+option with different values raises `ArgumentError`.
+
+| Option | Alias | Default | Effect |
+| --- | --- | --- | --- |
+| `http_endpoint` | `mcp_endpoint` | `'/_mcp'` | Slash-prefixed endpoint path. |
+| `auth_tokens` | `mcp_auth_tokens` | `[]` | String or array of bearer tokens. |
+| `enable_validation` | `mcp_validation` | `true` | Validates the JSON-RPC request envelope. |
+| `enable_rate_limiting` | `mcp_rate_limiting` | `true` | Enables MCP rate-limit configuration. |
+| `requests_per_minute` | `mcp_requests_per_minute` | `60` | Per-client-IP limit for all MCP endpoint requests. |
+| `tools_per_minute` | `tool_calls_per_minute`, `mcp_tool_calls_per_minute` | `20` | Additional per-client-IP limit for `tools/call`. |
+| `allow_unauthenticated` | `mcp_allow_unauthenticated` | `false` | Acknowledges an intentionally open endpoint. |
+
+Limits must be positive integers. Endpoint paths must be strings beginning with
+`/`; tokens must be non-blank strings; and all flags must be exactly `true` or
+`false`. Invalid values fail at boot with `ArgumentError`.
+
+`mcp_enabled`, `mcp_http`, and `mcp_stdio` are constructor-only gating options:
+
+| Constructor option | Effect |
+| --- | --- |
+| `mcp_enabled: true` | Creates the MCP server and enables its HTTP endpoint. |
+| `mcp_http: false` | Does not register the HTTP endpoint or its middleware. It is useful only with another MCP gate such as `mcp_enabled: true`. |
+| `mcp_stdio: true` | Creates the MCP server, but Otto does not provide an stdio transport. Because HTTP is enabled by default, also set `mcp_http: false` to avoid enabling HTTP. |
+
+`enable_mcp!` always enables HTTP and rejects these gating options. It is strict:
+unknown keys, including common near-misses such as `auth_token:`, raise
+`ArgumentError`. The `Otto.new` constructor ignores unknown non-MCP options but
+rejects unknown `mcp_`-prefixed options.
+
+## Rate limiting and validation
+
+Rate limits use a rolling 60-second period. `tools_per_minute` is additional to
+`requests_per_minute`, not a replacement. The guards run in this order:
+
+1. Rate limiting
+2. Token authentication
+3. JSON-schema validation
+
+Therefore, a malformed request without a valid token receives `401` instead of
+a validation response. Set either feature to `false` only when you accept the
+resulting exposure.
+
+MCP guards match the configured endpoint exactly, using Otto's normalized path.
+A sibling such as `/admin` beside an endpoint at `/a` is not challenged,
+validated, or counted. A configured trailing slash is accepted with or without
+the trailing slash.
+
+When Otto is mounted under a Rack path prefix, mount `Rack::Attack` inside the
+same `map` block so it receives the same `PATH_INFO` that Otto routes:
+
+```ruby
+# config.ru
+map '/api' do
+  use Rack::Attack
+  run otto # An endpoint at /_mcp is reached at POST /api/_mcp.
+end
+```
+
+`Rack::Attack` configuration is process-global. Separate Otto applications in
+the same process get independent MCP counters when their endpoint paths differ.
+Applications that share the same endpoint path also share its throttle
+configuration and counters; use distinct endpoint paths when isolation matters.
+
+If general Otto rate limiting is also enabled, its `Rack::Attack` responder
+replaces MCP's JSON-RPC-specific `429` response. Do not rely on the MCP error
+body in that combined configuration.
+
+## Errors and limits
+
+| Situation | HTTP status and JSON-RPC code |
+| --- | --- |
+| Missing or invalid bearer token | `401`, `-32000` (`Unauthorized`) |
+| Invalid JSON, request envelope, HTTP method, or content type | `400`, `-32700` or `-32600` |
+| Unknown protocol method or invalid method parameters | `400`, `-32601` or `-32602` |
+| Unknown resource or tool | `404`, `-32001` or `-32002` |
+| Resource or tool handler raises | `500`, `-32603`; details are logged, not returned to the client |
+| MCP rate limit exceeded | `429`, `-32000` unless general Otto rate limiting overrides the response body |
+
+Otto currently provides HTTP transport only. It does not implement an stdio
+transport, resource subscriptions, or resource-list change notifications.