otto 2.9.0 → 2.11.0

data/docs/guides/privacy.md

@@ -0,0 +1,193 @@
+# Privacy-preserving request data
+
+Otto's default request posture is to reduce the precision of public client
+information before application code, logging, authentication, rate limiting,
+and other middleware see it. The privacy pipeline is a Rack concern, not only a
+router feature: if an outer Rack middleware logs the request before Otto runs,
+place the privacy middleware in the common stack first.
+
+## Default behavior
+
+With the default `:masked` profile:
+
+- public IP addresses are masked by the configured octet precision (one octet
+  by default: `203.0.113.9` becomes `203.0.113.0`);
+- requests from private and loopback addresses are exempt from the privacy
+  fingerprint by default, so their IP, user agent, and referer remain unchanged;
+- for requests that are masked, user-agent version details are anonymized and
+  referer query parameters are removed;
+- original public values are not retained in the Rack environment; and
+- country resolution is country-level only and returns `**` when enabled but no
+  configured source answers.
+
+Downstream code should read `req.ip`, `req.masked_ip`, and the documented privacy
+environment keys rather than re-resolving an address from forwarded headers.
+
+These profiles are technical data-minimization controls, not a compliance
+certification. Whether a deployment meets GDPR, CCPA, or another legal regime
+also depends on its purposes, notices, retention, access controls, vendors, and
+jurisdiction.
+
+## Profiles
+
+Choose a named profile when the deployment posture should be obvious in review:
+
+```ruby
+otto = Otto.new('routes')
+otto.configure_ip_privacy(profile: :masked)     # default
+# or:
+otto.configure_ip_privacy(profile: :anonymous)  # mask private/localhost too
+# or:
+otto.configure_ip_privacy(profile: :audit)      # disable IP privacy
+```
+
+| Profile | Public IPs | Private/localhost IPs | Use when |
+| --- | --- | --- | --- |
+| `:masked` | Masked | Exempt by default | General privacy-by-default deployments and local development. |
+| `:anonymous` | Masked | Masked | Internal addresses must also be treated as identifying data. |
+| `:audit` | Not masked | Not masked | The operator has deliberately accepted raw-IP retention and controls logs and downstream systems. |
+
+The `:audit` profile transfers retention responsibility to the operator. It is
+not a way to obtain precise matching while keeping privacy enabled; use
+`env['otto.ip_match']` for that narrower need.
+
+Configuration is boot-time only. The first request freezes configuration in
+normal operation, so set profiles, trusted proxies, database readers, and other
+privacy settings before serving traffic.
+
+## Privacy-safe request values
+
+Inside a handler:
+
+```ruby
+class Analytics
+  def self.record(req, res)
+    event = {
+      ip: req.ip,
+      country: req.geo_country,
+      asn: req.asn,
+      anonymizer: req.anonymizer,
+      user_agent: req.user_agent,
+    }
+
+    AuditLog.write(event)
+    res.status = 204
+    res.body = []
+  end
+end
+```
+
+Common values are also available in the Rack environment:
+
+| Value | Environment key | Contract |
+| --- | --- | --- |
+| Canonical client IP | `otto.client_ip` | Masked IP when masking applies; resolved full IP under `:audit` or for an exempt private/loopback request. |
+| Precise CIDR verdict | `otto.ip_match` | Callable that checks the resolved full IP against CIDRs and returns only `true` or `false`. |
+| Masked IP | `otto.privacy.masked_ip` | Set when the request runs through the privacy fingerprint; absent for exempt or `:audit` requests. |
+| Rotating IP hash | `otto.privacy.hashed_ip` | Correlation value computed with Otto's rotating key; absent for exempt or `:audit` requests. |
+| Stable correlation hash | `otto.privacy.correlation_hash` | HMAC value when `correlation_secret:` is configured; otherwise `nil`. |
+| Country | `otto.privacy.geo_country` | ISO 3166-1 alpha-2 code, `**` when enabled but unresolved, or `nil` when geo/privacy is disabled. |
+| ASN | `otto.privacy.asn` | `nil` when off, `**` when enabled but unresolved, or a value such as `AS15169`. |
+| Anonymizer | `otto.privacy.anonymizer` | `nil` when off, `**` when no database answers, or a classification label. |
+
+`req.hashed_ip` is designed for short-lived correlation using a rotating key.
+For long-lived correlation, explicitly configure a stable secret and protect
+that secret as sensitive configuration. Changing the secret changes every
+correlation hash.
+
+## Country, ASN, and anonymizer data
+
+These signals have different trust and precision models:
+
+- [Geo-country resolution](geo-country.md) documents trusted provider headers,
+  CIDR trusted-proxy requirements, masked MMDB lookup, and the unknown sentinel.
+- [ASN and anonymizer enrichment](enrichment.md) documents the opt-in database
+  contracts. ASN uses a masked address; anonymizer classification deliberately
+  uses the unmasked address internally and emits only a label.
+
+Enable optional signals explicitly:
+
+```ruby
+otto.configure_ip_privacy(
+  geo: true,
+  geo_db_path: 'data/country.mmdb',
+  asn: true,
+  asn_db_path: 'data/origin-asn.mmdb',
+  anonymizer: true,
+  anonymizer_db_path: 'data/anonymizer.mmdb'
+)
+```
+
+The `maxmind-db` gem is optional and is required only when a database path is
+configured. A reader object responding to `#get(ip)` can be injected instead.
+Database paths are opened at configuration time; invalid paths fail during boot
+rather than on an arbitrary request.
+
+## Trusted proxy and matching boundaries
+
+Configure trusted proxies before relying on forwarded client information:
+
+```ruby
+otto = Otto.new(
+  'routes',
+  trusted_proxies: ['10.0.0.0/8', '192.0.2.0/24']
+)
+```
+
+CIDR-based trust lets Otto verify the proxy peer. Count-based
+`trusted_proxy_depth` is a separate mode and does not make geo headers
+trustworthy. A configured `geo_header` combined with depth mode is rejected at
+configuration time; use a local database in depth-mode deployments instead.
+
+The same trust decision also gates the forwarded host, scheme, and port headers
+that `Rack::Request#host` reads. See
+[Forwarded host authority](forwarded-authority.md), including the explicit
+`trusted_proxies: :none` assertion for directly exposed applications.
+
+For precise access control without exposing the address to application code,
+call the automatically installed `env['otto.ip_match']` capability. It matches
+the resolved full client IP against application CIDRs and returns only
+`true`/`false`; it fails closed when no client IP resolves. Do not log or persist
+the closure.
+
+```ruby
+allowed = req.env.fetch('otto.ip_match').call(['192.0.2.0/24', '2001:db8::/32'])
+```
+
+## Middleware placement
+
+When building a larger Rack stack, put privacy before components that log or
+inspect the request:
+
+```ruby
+builder.use Otto::Security::Middleware::IPPrivacyMiddleware, otto.security_config
+builder.use Rack::CommonLogger
+builder.use Sentry::Rack::CaptureExceptions
+# Then mount the Otto application.
+```
+
+Otto also installs its privacy middleware internally. The outer common-stack
+placement is needed when middleware outside the Otto app would otherwise see the
+raw peer first.
+
+Pass `otto.security_config` as shown. The outer instance resolves `otto.client_ip`
+first and the inner one then short-circuits, so an outer instance constructed
+without the configuration would silently apply defaults instead of the
+application's profile, precision, correlation secret, and enrichment settings.
+Proxy trust is the exception: the inner instance re-applies its own trust
+posture even after an outer pass, and a CIDR configuration that can no longer
+see the connecting peer fails closed. See
+[Forwarded host authority](forwarded-authority.md#place-the-middleware-before-other-request-consumers).
+
+## Operational rules
+
+- Treat `nil`, `'**'`, `'none'`, and a real label as different states. In
+  particular, anonymizer `'none'` means the database was consulted and did not
+  list the address; `'**'` means no database answered.
+- Do not use provider geo headers without a verifiable CIDR trusted proxy. A
+  client can otherwise submit its own country.
+- Do not confuse the masked client IP with the raw peer used to authenticate a
+  local network service. Integrations such as Caddy TLS have their own trust
+  boundary.
+- Test logs and monitoring outside Otto's stack. Privacy is only effective if
+  those components receive the masked environment first.

data/docs/guides/routing.md

@@ -0,0 +1,293 @@
+# Routing applications with Otto
+
+Otto keeps the application boundary small: a plain-text route file maps an HTTP
+verb and path to a Ruby handler. Use this guide to choose a handler style and
+response contract. The exact route grammar is in the [route syntax reference](../reference/route-syntax.md).
+
+## Choose a handler style
+
+| Use this when | Route target | Invocation |
+| --- | --- | --- |
+| You need a class method with direct Rack access | `App.index` | `App.index(req, res)` |
+| You need an object with direct Rack access | `App#show` | `App.new(req, res).show` |
+| You want a constrained, testable application operation | `App::Operation` | `App::Operation.new(strategy_result, params, locale)` |
+| You need a small pre-registered endpoint function | `&name` | `call(req, res, captured_path_params)` |
+
+## Controller-style handlers
+
+Routes can call a class method or instantiate a class for an instance method:
+
+```text
+GET /                         App.index
+GET /products/:id             App#show
+```
+
+```ruby
+class App
+  def initialize(req, res)
+    @req = req
+    @res = res
+  end
+
+  def show
+    @res.body = "Product: #{@req.params[:id]}"
+  end
+
+  def self.index(req, res)
+    res['content-type'] = 'text/plain'
+    res.body = 'Hello Otto'
+  end
+end
+```
+
+Use this style when the handler needs cookies, request headers, the Rack
+request object, or direct response helpers.
+
+## Logic classes
+
+Use a bare class target for an operation with an explicit input context:
+
+```text
+GET  /products/:id  Products::Show auth=session response=json
+POST /products      Products::Create auth=session response=json
+```
+
+```ruby
+class Products::Show
+  def initialize(strategy_result, params, locale)
+    @context = strategy_result
+    @params = params
+    @locale = locale
+  end
+
+  def raise_concerns
+    @product = Product.find(@params[:id])
+    unless @product.public? || @product.owner_id == @context.user_id
+      raise Otto::Security::AuthorizationError, 'Product access denied'
+    end
+  end
+
+  def process
+    { id: @product.id, name: @product.name, locale: @locale }
+  end
+end
+```
+
+Otto runs `raise_concerns` before `process` when those methods exist. Put
+resource loading and resource-level authorization in `raise_concerns`; route
+authentication and broad role checks belong in the route definition.
+
+Logic classes do not receive the Rack environment. This keeps their inputs
+explicit and prevents application operations from depending on ambient request
+state. Choose a controller-style handler when direct request access is part of
+the operation.
+
+## Registered lambda handlers
+
+Lambda routes are useful for small endpoints that do not need a Ruby constant or
+handler class. Register the callable at boot:
+
+```ruby
+otto = Otto.new('routes', lambda_handlers: {
+  health_check: lambda do |_req, res, _extra_params|
+    res['content-type'] = 'text/plain'
+    res.body = 'ok'
+  end,
+})
+```
+
+```text
+GET /health &health_check
+```
+
+The registry is normalized and frozen during configuration. A lambda must
+accept three positional arguments: request, response, and captured path
+parameters. Query and form parameters remain available through `req.params`.
+The route name is an exact registry key; it is not evaluated as Ruby code.
+
+## Response selection
+
+Use `response=` when the handler returns a value that should pass through Otto's
+response handling:
+
+```text
+GET  /api/products  Products::Index response=json
+GET  /dashboard     Dashboard#show response=view
+POST /login         Sessions#create response=redirect
+GET  /data          Data#show response=auto
+```
+
+`response=default` is the default. Keep response selection in the route file
+so the HTTP contract is visible beside the endpoint.
+
+| Response type | Handler contract |
+| --- | --- |
+| `default` | Mutate `res` directly. The handler's return value is ignored. |
+| `json` | Return a Hash for direct JSON serialization. `nil` becomes `{ "success": true }`; another value is wrapped as `data`. A Logic class may instead provide `response_data`. |
+| `view` | Return a value rendered with `to_s`, or provide `view.render` on a Logic object. |
+| `redirect` | Return a path String, or provide `redirect_path` on a Logic object. The fallback path is `/`. |
+| `auto` | A Hash becomes JSON, a path-like String becomes a redirect, and a Logic object with `view` uses the view handler; other results use default behavior. |
+
+An unknown response name currently falls back to `default`. Treat response
+names as a fixed set; a typo otherwise changes the route to direct-response
+behavior.
+
+## Route parameters
+
+Named path segments are available in request parameters:
+
+```text
+GET /products/:id  Products::Show
+```
+
+A handler can read `req.params[:id]` or a Logic class can read `params[:id]`.
+Request query and body parameters are merged according to the handler's request
+contract. JSON bodies are parsed for Logic-class parameters when the content
+type is JSON and the body is a JSON object. A valid non-object JSON body is
+ignored. Malformed JSON is logged and the Logic class still runs with its other
+parameters; perform application validation when malformed JSON must return a
+client error.
+
+## Security options in routes
+
+Authentication, roles, and CSRF exemptions are explicit route options:
+
+```text
+GET  /profile  Profile#show auth=session
+GET  /admin    Admin::Dashboard auth=session role=admin
+POST /hook     Hooks#receive csrf=exempt
+```
+
+Malformed `auth`, `role`, and `csrf` tokens fail route parsing rather than
+silently weakening the route. Do not use `csrf=exempt` as a general API switch;
+choose an independent request-authentication and replay-protection model for
+webhooks or other non-browser endpoints.
+
+## Static files
+
+Otto serves static files in two ways. Both apply the same safety policy: the
+requested path is joined to a canonical root, resolved with `File.realpath`
+(which follows every `..`, `.`, and symlink component), and served only when
+the result is still inside that root and is a regular, readable file owned by
+the process user or group. Anything else, including a symlink that points
+outside the root, is treated as not found.
+
+### Implicit public directory
+
+Passing `public:` serves every file under that directory at its relative path.
+Nothing needs registering; a file added after boot is served on the next
+request, and a symlinked public directory that is repointed by a deploy is
+re-resolved on every request.
+
+```ruby
+otto = Otto.new('routes', public: File.expand_path('public', __dir__))
+# public/css/site.css is served at GET /css/site.css
+```
+
+### Explicit static mounts
+
+`mount_static` binds one URL prefix to one directory. Use it when the files do
+not live under a single public directory, when a URL prefix should map to a
+different directory name, or when a required asset directory must be verified
+at boot.
+
+```ruby
+otto = Otto.new('routes')
+otto.mount_static('/assets', root: 'public/assets')
+otto.mount_static('/vendor', root: File.join(Gem.loaded_specs['some-ui-kit'].full_gem_path, 'dist'))
+otto.mount_static('/', root: 'public/root-files') # favicon.ico, robots.txt
+```
+
+- The prefix must start with `/`. A trailing slash is ignored, and `/`
+  mounts the root at the top level. Empty, `.`, and `..` segments are
+  rejected.
+- The root is expanded and canonicalized once, at registration. A root that
+  is missing, unreadable, not a directory, not owned by the process user or
+  group, or a symlink that cannot be resolved raises `ArgumentError`, so a
+  misconfigured application does not boot. Because the root is fixed at
+  registration, a deploy that repoints a symlinked root takes effect at the
+  next restart.
+- A mount authorizes only files inside its own root. It never exposes the
+  root's parent or siblings, and it does not widen the implicit public
+  directory. Registering the same prefix twice on one instance raises
+  `ArgumentError`; different Otto instances are fully independent.
+- Requests are matched on the decoded, trailing-slash-stripped path, the same
+  normalization every other dispatch stage uses. Only `GET` is served, the
+  prefix itself is not (mounts serve files, not directory listings), and a
+  request for a file the root does not contain falls through to the next
+  dispatch stage.
+- `mount_static` must be called before the first request. After configuration
+  freezing it raises `FrozenError`, and `otto.static_mounts` is a frozen,
+  read-only table.
+
+### Dispatch precedence
+
+Precedence is fixed and does not depend on request history:
+
+1. literal routes, such as `GET /assets/app.css Assets#show`;
+2. explicit static mounts, consulted longest prefix first; when the longest
+   matching mount does not contain the file, shorter matching mounts are tried
+   in turn;
+3. the implicit `public:` directory;
+4. dynamic routes, such as `GET /assets/:name Assets#show`.
+
+So a literal route at a mounted path always wins, a mounted file always beats
+a file at the same URL in the public directory, and a dynamic route only sees
+requests that no static source could serve.
+
+### Migrating from `add_static_path`
+
+`add_static_path` was removed in v2.10.0. It only populated a request-time
+cache; it never registered or restricted anything. Callers that used it to
+"register" files under the public directory can delete the call, because the
+public directory is served without registration. Callers that used it to reach
+files outside the public directory should replace it with `mount_static` and
+an explicit root. There is no compatibility shim: calling the removed method
+raises `NoMethodError` at boot.
+
+## Fallback 404 and 500 responses
+
+A `GET /404` or `GET /500` route in the routes file handles misses and
+unhandled errors like any other route. Without one, Otto uses `not_found=` and
+`server_error=`, which accept either a Rack triple or a callable:
+
+```ruby
+otto.not_found = [404, { 'content-type' => 'application/json' }, ['{"error":"Not Found"}']]
+
+otto.server_error = lambda do |env, error|
+  [500, { 'content-type' => 'text/plain' }, ["Error #{env['otto.error_id']}"]]
+end
+```
+
+A callable is invoked on every request with `env` (`not_found`) or `env` and
+the exception (`server_error`), trimmed to the positional parameters it
+declares, so `->(env) { ... }` and `->(env = nil) { ... }` both work for
+`server_error`. It must return a Rack triple: an Integer status, Hash-like
+headers, and a body that responds to `each` (a bare String is rejected, at
+assignment time for a static triple). A static triple is copied per request
+before it is returned, so middleware that writes response headers in place
+(rack-session, Otto's CSRF middleware, anything calling
+`Rack::Utils.set_cookie_header!`) never mutates the configured object or
+leaks one client's `Set-Cookie` into another's response. Do not rely on
+mutating the configured triple after boot; assign a new value or use the
+callable form instead.
+
+For JSON clients, an unhandled error returns Otto's built-in JSON error body
+regardless of `server_error`; a `/500` route applies to every client.
+
+## Configuration timing
+
+Construct and configure the Otto instance before the first request:
+
+```ruby
+otto = Otto.new('routes')
+otto.add_auth_strategy(
+  'session',
+  Otto::Security::Authentication::Strategies::SessionStrategy.new
+)
+otto.register_request_helpers(MyApp::RequestHelpers)
+# Add middleware and other boot-time options here.
+```
+
+In normal operation, the first request freezes configuration. Runtime route or
+security changes are not part of the application contract.