otto 2.9.0 → 2.10.0

data/docs/guides/authentication.md

@@ -0,0 +1,377 @@
+# Authentication and authorization
+
+Otto authenticates at the route handler boundary. Authentication is not a
+middleware that runs before routing; only routes with `auth=` requirements are
+wrapped. This lets a route declare its access requirement next to its HTTP
+contract.
+
+Authentication answers **who is this request from?** Authorization answers
+**may that subject perform this action?** Keep those questions separate.
+
+## Register strategies before the first request
+
+Register named strategy instances during boot:
+
+```ruby
+otto = Otto.new('routes')
+otto.add_auth_strategy(
+  'session',
+  Otto::Security::Authentication::Strategies::SessionStrategy.new(
+    session_key: 'user_id'
+  )
+)
+api_keys = ENV.fetch('API_KEYS').split(',').reject(&:empty?)
+raise 'API_KEYS is empty' if api_keys.empty?
+
+otto.add_auth_strategy(
+  'api_key',
+  Otto::Security::Authentication::Strategies::APIKeyStrategy.new(api_keys: api_keys)
+)
+```
+
+`APIKeyStrategy` fails closed. Its constructor requires exactly one key source
+(`api_keys:`, `resolver:`, or a block; see below) and raises `ArgumentError`
+when none is given, or when an `api_keys:` list normalizes to empty (`[]` or
+only blank strings), so the strategy enforces the check the example above makes
+explicit. A request that presents a key is accepted only when that key matches a
+configured key under constant-time comparison. Both sides are reduced to
+fixed-width SHA-256 digests before comparing, so the check never short-circuits
+on a length mismatch and configured key lengths are not observable. A blank
+credential (empty or whitespace-only) is rejected as missing.
+A presented-but-invalid key is a terminal failure, so it aborts the strategy
+chain instead of falling through to a later strategy in a multi-strategy `OR`
+route.
+
+By default, the strategy reads only the `X-API-Key` header. Use `header_name:`
+to select a different header. The query/form parameter path is opt-in via
+`param_name:`, because a key placed in a URL is captured by access logs,
+proxies, and browser history:
+
+```ruby
+Otto::Security::Authentication::Strategies::APIKeyStrategy.new(
+  api_keys: api_keys,
+  param_name: 'api_key' # caution: keys in URLs are logged; prefer the header
+)
+```
+
+The strategy never places the raw key in the result. `metadata[:api_key_fingerprint]`
+(and, for the static list, `user[:api_key_fingerprint]`) holds a truncated
+SHA-256 digest of the presented key, so audit logs can correlate requests
+without recording the credential. With a resolver, `user` is whatever the
+resolver returns, so that guarantee covers only the strategy's own fields; see
+the rules below.
+
+### Resolve keys from a database
+
+A static list is the simple default. When keys live in a database, a
+repository, or a cache, give the strategy a resolver instead. The resolver
+receives the presented key and returns the account behind it, or `nil` when
+there is none:
+
+```ruby
+APIKeyStrategy = Otto::Security::Authentication::Strategies::APIKeyStrategy
+
+otto.add_auth_strategy(
+  'api_key',
+  APIKeyStrategy.new do |presented_key|
+    ApiKey.find_by(digest: APIKeyStrategy.digest(presented_key))&.account
+  end
+)
+```
+
+Anything that responds to `#call` works as well, passed as `resolver:`:
+
+```ruby
+APIKeyStrategy.new(resolver: repo.method(:find_by_key))
+APIKeyStrategy.new(resolver: ->(key) { KeyCache.fetch(APIKeyStrategy.digest(key)) })
+```
+
+The rules are the same in every form:
+
+- Exactly one source: `api_keys:`, `resolver:`, or a block. Passing none, or
+  more than one, raises `ArgumentError`, as does a `resolver:` that does not
+  respond to `#call`.
+- The resolver receives only the presented key, as a non-blank `String`, and
+  nothing else. The blank check (empty or whitespace-only) and the non-String
+  rejection run before it, so a missing or blank header is still the
+  non-terminal `No API key provided` failure and the resolver is never asked
+  about it.
+- A `nil` or `false` return is a terminal `Invalid API key` failure, identical
+  to a static mismatch. It aborts the strategy chain with a 401. Every other
+  return value is a match, including empty containers: a `where(...)` relation,
+  an empty Array from `select`, or `{}` from a cache miss is truthy and
+  authenticates every presented key. Return one record (`find_by`, `first`) or
+  `nil`.
+- Exceptions from the resolver propagate. The strategy does not rescue them,
+  so a database outage surfaces as an error rather than a silent 401, and can
+  never become a success.
+- Whatever the resolver returns becomes `user` in the result, verbatim, and
+  `api_key_fingerprint` is still set in the result metadata. The strategy
+  itself never places the raw key in the result, but the result is stored in
+  `env['otto.strategy_result']` and exposed to handlers, so anything the
+  application serializes or logs from it carries `user`. It is the resolver's
+  responsibility not to return an object that carries the raw key. Return the
+  account, not the `ApiKey` row that stores the key, and store digests. A
+  resolver that returns the presented key string itself as the user raises
+  `ArgumentError`.
+
+The strategy cannot make a black-box lookup constant-time. Store SHA-256
+digests rather than raw keys and look up by `APIKeyStrategy.digest(key)`, as
+in the example above. This produces a fixed-width lookup value and keeps raw
+keys out of storage, but it does not make the application's database or cache
+lookup constant-time. A database dump of high-entropy keys (generate them with
+`SecureRandom`, 32 bytes or more) does not expose usable credentials through a
+practical brute-force search. Unsalted SHA-256 is not a password hash, so do
+not accept user-chosen keys. `APIKeyStrategy.digest(key)` returns the full hex
+digest; the fingerprint in the result is its first 12 characters.
+
+### What `APIKeyStrategy` does not provide
+
+`APIKeyStrategy` is a conventional small static-allowlist authenticator
+included as a low-dependency convenience and reference implementation. The
+fail-closed changes in #256 make that existing convenience safe by default;
+they do not establish that all Otto API-key authentication should use
+boot-loaded lists.
+
+The shape is deliberate and has precedent. A key list loaded once at start,
+checked with a constant-time comparison, is what the Rails guides show for
+`authenticate_or_request_with_http_token` (a token from the environment,
+compared with `ActiveSupport::SecurityUtils.secure_compare`), what the
+Kubernetes API server does with its `--token-auth-file` CSV, and what Traefik
+and nginx do with their basic-auth user lists. Warden and Devise token
+examples, and the common Sinatra `before` filter that compares a header
+against `ENV['API_KEY']`, are the same pattern. All of them share the
+properties here: no source configured means no access, the set of keys is
+fixed for the life of the process, and a mismatch is final. The resolver form
+is the escape hatch for the dynamic case those tools also leave to an external
+store.
+
+In either form, the strategy has no native support for:
+
+- Runtime addition or immediate revocation.
+- Expiration.
+- Per-client roles or scopes.
+- Ownership and descriptive metadata.
+- Usage quotas.
+- A management API.
+- Persisted audit history.
+- Hashed verifier storage.
+
+With a static list, none of these exist: changing the set of valid keys means
+restarting the process, and every key is equal. With a resolver, the first
+four and the last become the application's key store's responsibility. The
+resolver decides whether a key is still valid, and whatever it returns is the
+`user` the handler sees, so roles, scopes, ownership, and expiry live on that
+record. Quotas, a management API, and audit history remain outside the
+strategy entirely. An application that needs them should build a custom
+`AuthStrategy` around its own key model, using `APIKeyStrategy` as the
+reference for header handling, terminal failures, and fingerprinting.
+
+A strategy implements `authenticate(env, requirement)` and returns a
+`StrategyResult`, `AuthFailure`, or `AuthorizationFailure`. Subclass
+`Otto::Security::Authentication::AuthStrategy` to use its `success`, `failure`,
+and `authorization_failure` helpers.
+
+Strategy names must be unique. Registration and other security configuration
+must happen before the first request, when Otto freezes configuration.
+
+## Protect a route
+
+Put the strategy name in the route file:
+
+```text
+GET /profile    Profile#show auth=session
+GET /api/data   Api::Data response=json auth=api_key
+```
+
+The strategy receives the full requirement string. Exact names resolve directly;
+colon-qualified requirements such as `oauth:google` first try an exact match,
+then fall back to the registered `oauth` strategy while preserving the full
+requirement for that strategy.
+
+A route without `auth=` receives an anonymous `StrategyResult` and runs without
+an authentication check. `StrategyResult#authenticated?` tells application code
+whether a user is present; `auth_attempt_succeeded?` tells it whether the
+current route's authentication attempt produced an authenticated result.
+
+## Combine strategies with OR logic
+
+Use comma-separated requirements when more than one credential mechanism may
+satisfy the same route:
+
+```text
+GET /api/data Api::Data#show auth=session,api_key,oauth response=json
+```
+
+The chain behaves as follows:
+
+1. Strategies run left to right.
+2. The first authenticated success wins and later strategies do not run.
+3. A plain failure allows the next strategy to run.
+4. An anonymous success, such as `noauth`, is held as a fallback while the rest
+   of the chain runs.
+5. If every strategy fails, Otto returns an authentication or authorization
+   failure. If an anonymous fallback exists and no terminal failure occurred,
+   it wins.
+6. A terminal authentication failure stops the chain immediately. Strategies
+   should mark a failure terminal only when explicit credentials were presented,
+   examined, and rejected. This prevents invalid credentials from degrading to
+   an anonymous success in a mixed chain such as
+   `auth=basicauth,noauth`.
+
+Put the common and least expensive strategy first, but do not use ordering to
+make invalid explicit credentials harmless: terminal failures are intentionally
+fail-closed.
+
+## Route-level roles
+
+Add `role=` for a broad route-level authorization check:
+
+```text
+GET /admin     Admin::Dashboard auth=session role=admin
+GET /edit      Editorial#edit auth=session role=admin,editor
+```
+
+`role=` checks the successful strategy result; it does not read
+`env['rack.session']` independently. The built-in `SessionStrategy` returns a
+user containing only `id` and `user_id`, so it is sufficient for authentication
+but not for these role checks. If the application uses role-protected session
+routes, register a role-aware application strategy instead of the built-in
+strategy shown earlier:
+
+```ruby
+class RoleAwareSessionStrategy < Otto::Security::Authentication::AuthStrategy
+  def authenticate(env, _requirement)
+    session = env['rack.session']
+    return failure('No session available') unless session
+
+    user_id = session['user_id']
+    return failure('Not authenticated') unless user_id
+
+    success(
+      user: {
+        id: user_id,
+        roles: Array(session['user_roles']).map(&:to_s),
+      },
+      session: session,
+      auth_method: 'session'
+    )
+  end
+end
+
+otto.add_auth_strategy('session', RoleAwareSessionStrategy.new)
+```
+
+Multiple route roles use OR logic. The role check reads, in precedence order:
+
+1. `result.user_roles`, if the result exposes it
+2. `result.user[:roles]` or `result.user['roles']` for a Hash-backed user
+3. `result.user.roles`, falling back to `result.user.role`, for an object-backed user
+4. `result.metadata[:user_roles]`
+
+Use strings for result-level, Hash-backed, or metadata roles so they match the
+string values parsed from the route. Object-backed `#roles` and `#role` values
+are normalized to strings.
+
+Missing authentication returns `401`. A valid authenticated subject without one
+of the required roles returns `403`. `response=json` makes these route errors
+JSON regardless of the request's `Accept` header.
+
+## Resource-level authorization
+
+Route-level roles cannot decide ownership or relationship rules without loading
+the resource. Put that decision in a Logic class's `raise_concerns` method:
+
+```ruby
+class Posts::Edit
+  def initialize(strategy_result, params, _locale)
+    @context = strategy_result
+    @params = params
+  end
+
+  def raise_concerns
+    @post = Post.find(@params[:id])
+    return if @post.user_id == @context.user_id
+
+    raise Otto::Security::AuthorizationError.new(
+      'Cannot edit another user\'s post',
+      resource: 'Post',
+      action: 'edit',
+      user_id: @context.user_id
+    )
+  end
+
+  def process
+    # Perform the edit.
+  end
+end
+```
+
+`Otto::Security::AuthorizationError` is registered automatically and produces a
+`403` response. It can carry resource, action, and user ID context for structured
+logging. Authenticate first, then perform resource-level checks; do not rely on
+an ownership check as a substitute for authentication.
+
+## Strategy result contract
+
+Otto stores the result for the request in `env['otto.strategy_result']` and uses
+it to construct Logic-class context. Useful accessors include:
+
+```ruby
+result.authenticated?
+result.anonymous?
+result.user_id
+result.user_name
+result.has_role?('admin')
+result.has_permission?('write')
+result.session
+result.metadata
+result.strategy_name
+```
+
+Application code should read the result created by Otto rather than constructing
+its own `StrategyResult`. The `Data` record does not allow member reassignment,
+but contained `session`, `user`, and `metadata` objects are not deep-frozen;
+their mutability remains the application's responsibility.
+
+## Failure and response behavior
+
+- Unknown strategy names fail before any strategy in the route runs.
+- Authentication failures are `401`; browser-oriented failures may redirect to
+  the configured login path, while JSON routes return JSON.
+- Authorization failures are `403` and should not ask an already authenticated
+  subject to authenticate again.
+- A strategy should return an `AuthorizationFailure` when credentials are valid
+  but the subject is not permitted, and an `AuthFailure` when authentication did
+  not succeed.
+- Failure reasons and attempted strategies are included in Otto's structured
+  authentication logging; do not put secrets or raw credentials in those
+  reasons.
+
+## Built-in strategy starting points
+
+Otto includes these strategy classes as implementation starting points:
+
+- `SessionStrategy` — reads a configured key from `env['rack.session']`.
+- `APIKeyStrategy` — checks the configured header; the query parameter is opt-in
+  via `param_name:`. Keys come from a non-empty `api_keys:` list, a `resolver:`
+  callable, or a block that looks the presented key up; a rejected key is a
+  terminal failure, and the result exposes only a key fingerprint.
+- `RoleStrategy` — checks session roles against allowed roles or a
+  colon-qualified requirement.
+- `PermissionStrategy` — checks application-provided permission data.
+- `NoAuthStrategy` — produces an anonymous success for an explicitly configured
+  anonymous fallback.
+
+For production credentials, choose the credential storage, rotation, transport,
+and revocation policy in the application. Otto supplies the route boundary and
+result contract; it does not provide a user database or a universal session
+store.
+
+## Related contracts
+
+- [Route syntax](../reference/route-syntax.md) — `auth=`, `role=`, and route
+  parsing rules.
+- [Routing guide](routing.md) — choosing controller, Logic, and lambda handlers.
+- [Configuration freezing](configuration_freezing.md) — boot-time mutation
+  boundary and multi-step setup.

data/docs/guides/caddy-tls.md

@@ -0,0 +1,205 @@
+# Caddy on-demand TLS
+
+`Otto::CaddyTLS` provides the permission endpoint Caddy calls before obtaining
+or loading a certificate for a domain. Otto owns the route, parameter-shape
+checks, access guard, response semantics, and fail-closed behavior. The
+application supplies one decision block: whether the requested domain is
+allowed.
+
+This guide covers the shipped integration. [ADR-003: Caddy TLS route-based
+integration](../adr/adr-003-caddy-tls-route-based-integration.md) explains the
+rejected alternatives and the security rationale in more detail.
+
+## Enable the endpoint
+
+Configure it before the first request:
+
+```ruby
+require 'otto'
+
+otto = Otto.new('routes')
+otto.enable_caddy_tls! do |domain|
+  MyApp::CustomDomain.verified?(domain)
+end
+
+run otto
+```
+
+The block receives the stripped `domain` string from `?domain=`. Otto checks
+that the parameter is a non-empty string, but does not validate DNS syntax,
+lowercase the value, remove a trailing dot, or convert internationalized names.
+Perform any application-specific hostname normalization and validation in the
+block before querying domain data. A truthy result returns `200 OK`; a falsey
+result returns `403 Forbidden`. An exception raised by the block is logged and
+treated as a denial.
+
+The default endpoint is `/_caddy/tls-permission`. No entry in the routes file is
+required. Enabling without a block raises `ArgumentError`, and repeated enable
+calls are idempotent: the first configuration and decision block remain active.
+
+## Configure Caddy
+
+`on_demand_tls` is a global Caddy option, and configuring its permission check
+does not enable on-demand TLS for a site. A complete minimal configuration is:
+
+```caddyfile
+{
+  on_demand_tls {
+    permission http http://127.0.0.1:PORT/_caddy/tls-permission
+  }
+}
+
+https:// {
+  tls {
+    on_demand
+  }
+
+  reverse_proxy 127.0.0.1:APP_PORT
+}
+```
+
+Replace `PORT` with the loopback port serving the Otto permission endpoint and
+`APP_PORT` with the application port receiving normal traffic. If the same Otto
+app serves both, the ports may be the same.
+
+Caddy also documents `ask` as a backwards-compatible shortcut for the built-in
+HTTP permission module:
+
+```caddyfile
+{
+  on_demand_tls {
+    ask http://127.0.0.1:PORT/_caddy/tls-permission
+  }
+}
+```
+
+Both forms append `?domain=<host>` and treat a non-`2xx` response as a denial.
+Validate the chosen form with the Caddy version you deploy:
+
+```sh
+caddy adapt --config Caddyfile --adapter caddyfile
+```
+
+See Caddy's [`on_demand_tls` documentation](https://caddyserver.com/docs/caddyfile/options#on-demand-tls)
+for the current module syntax and deployment requirements.
+
+## Request contract
+
+The endpoint accepts a `GET` request with a string `domain` query parameter:
+
+| Request | Result |
+| --- | --- |
+| `GET /_caddy/tls-permission?domain=verified.example` and callback allows | `200`, `text/plain`, `OK` |
+| Domain missing, blank, or array-valued | `400`, callback is not called |
+| Callback returns false or `nil` | `403`, `text/plain`, `Forbidden` |
+| Callback raises | `403`, callback error is logged |
+| `HEAD` with a valid domain | Same status decision, empty response body |
+
+Only `domain` reaches the callback. Additional query parameters are ignored;
+there is no verification-bypass parameter.
+
+## Security boundary
+
+The localhost guard is enabled by default. For the protected endpoint, both
+conditions must hold:
+
+1. the raw socket peer is loopback; and
+2. no non-empty forwarding header indicates that the request was relayed
+   through another proxy.
+
+The guard authenticates the original peer, not the resolved client address in
+`REMOTE_ADDR` or `otto.client_ip`. This matters when a loopback proxy is also a
+trusted proxy: forwarded headers must not be able to turn a remote caller into a
+local one. The guard rejects the endpoint request when any of these headers has a
+non-empty value:
+
+- `X-Forwarded-For`
+- `X-Real-IP`
+- `X-Client-IP`
+- `Forwarded`
+- `X-Forwarded-Host`
+- `X-Forwarded-Proto`
+- `X-Forwarded-Scheme`
+- `X-Forwarded-SSL`
+- `X-Forwarded-Port`
+
+The list is the full set (`Otto::Utils::RELAY_MARKER_HEADERS`): every forwarding
+carrier Otto knows, including the authority headers, not only the client-IP
+carriers. A front server that adds any of them to the permission request, even
+one that only records the scheme or port, turns the call into a relayed request
+and the guard returns `401`. Configure the permission endpoint so the request
+reaches Otto without forwarding headers.
+
+The guard is path-scoped. Other application routes pass through it unchanged,
+and path normalization is shared with the router so encoded or trailing-slash
+variants cannot bypass the check.
+
+This protection assumes the Rack server leaves the actual connecting peer in
+`REMOTE_ADDR` and that no earlier proxy or middleware removes relay-marker
+headers before Otto records them. If PROXY protocol or an outer middleware
+rewrites either input, verify that Otto still receives an authentic peer address
+and the original forwarding markers. The strongest boundary is a dedicated
+loopback-only listener.
+
+## Deployment topology
+
+The recommended deployment is a small Otto app bound to a loopback-only port on
+the same host as Caddy:
+
+```text
+Caddy -- loopback --> Otto CaddyTLS endpoint -- authenticated app channel --> domain data
+```
+
+Caddy expects this decision in a few milliseconds. Prefer an indexed local
+lookup or in-process cache. If the permission app must call an internal service,
+use a short timeout and cache the result: an exception or timeout that reaches
+the block's fail-closed wrapper becomes a denial and can fail the TLS handshake.
+That data channel is an application responsibility; it does not widen the Caddy
+endpoint's network trust boundary.
+
+If the endpoint is mounted in a larger public app, add defense in depth:
+
+- bind a dedicated permission app to `127.0.0.1` where possible;
+- block the endpoint path at the public proxy;
+- ensure the proxy's direct Caddy control-plane request is not relayed with
+  forwarding headers;
+- keep the guard enabled unless network isolation is independently enforced.
+
+## Disabling the guard
+
+`localhost_only: false` removes the built-in access control and logs a warning:
+
+```ruby
+otto.enable_caddy_tls!(localhost_only: false) do |domain|
+  MyApp::CustomDomain.verified?(domain)
+end
+```
+
+Use this only when the endpoint is isolated by a stronger network-level control
+that you have verified. It is not the normal deployment path.
+
+## Custom endpoint
+
+An application can choose another endpoint path:
+
+```ruby
+otto.enable_caddy_tls!(endpoint: '/internal/acme/permission') do |domain|
+  MyApp::CustomDomain.verified?(domain)
+end
+```
+
+Otto normalizes the configured endpoint before registering the route and guard.
+The endpoint must still be configured before the first request; attempting to
+change it after configuration freezes raises `FrozenError`.
+
+## Troubleshooting
+
+- **Caddy receives a denial:** check that the request reaches the configured
+  loopback port, includes a non-empty `domain`, and that the callback returns
+  truthy for that exact stripped domain.
+- **The callback is never called:** a missing/blank domain produces `400`, while
+  a non-loopback peer or any non-empty forwarding header produces `401`.
+- **A proxied public request reaches the same app:** keep the forwarding-header
+  rejection and add a proxy path block or a dedicated loopback-only endpoint.
+- **A second `enable_caddy_tls!` call does not change behavior:** this is
+  intentional idempotency; configure the endpoint and block on the first call.