otto 2.9.0 → 2.11.0

data/docs/README.md

@@ -0,0 +1,166 @@
+# Otto documentation
+
+Otto is a Rack router whose application model starts with a plain-text route
+file and Ruby handlers. It also provides opt-in security controls,
+privacy-preserving request handling, authentication hooks, and small
+integrations for network services.
+
+This page is the documentation map. It is intentionally a map, not an
+exhaustive API reference: public classes, method signatures, and implementation
+details remain in the code and its generated API documentation. Guides should
+explain when to use a capability, its security and operational constraints, and
+the smallest complete configuration that uses it safely.
+
+## Capabilities at a glance
+
+| Area | What Otto provides | Reader-facing guide or next destination |
+| --- | --- | --- |
+| Application model | Plain-text routes; class, instance, Logic-class, and registered lambda handlers; response selection | [Routing](guides/routing.md) and [route syntax](reference/route-syntax.md) |
+| Request lifecycle | Rack integration, middleware ordering, helper registration, lifecycle hooks, and boot-time configuration | `guides/application-lifecycle.md` |
+| Authentication and authorization | Named authentication strategies, ordered multi-strategy fallback, terminal failures, route roles, and resource-level authorization | [Authentication](guides/authentication.md) |
+| Security | CSRF enforcement, request validation, rate limiting, security headers, CSP, error handling, and trusted proxies | `guides/security.md`; [forwarded host authority](guides/forwarded-authority.md) |
+| Runtime and dependencies | Ruby compatibility tiers, upstream security-maintenance limits, dependency-range guarantees, and consumer lockfile auditing | [Runtime and dependency security policy](reference/runtime-and-dependency-security.md) |
+| Privacy and network identity | IP privacy profiles, privacy-safe client signals, country resolution, ASN lookup, and anonymizer classification | [Privacy](guides/privacy.md), [geo-country](guides/geo-country.md), and [enrichment](guides/enrichment.md) |
+| Internationalization | Locale configuration and request locale resolution | `guides/locales.md` |
+| Operations | Structured logging, safe error reporting, static files, and testing Otto applications | `guides/operations.md` |
+| Integrations | Model Context Protocol (MCP) endpoints and Caddy on-demand TLS permission checks | [MCP](guides/mcp.md) and [Caddy TLS](guides/caddy-tls.md) |
+
+## Start here today
+
+- [Project README](../README.md) — installation and a minimal Rack app.
+- [Runtime and dependency security policy](reference/runtime-and-dependency-security.md)
+  — choose a maintained Ruby and keep the application's resolved bundle audited.
+- [Routing guide](guides/routing.md) — choose a handler style and response
+  contract.
+- [Authentication guide](guides/authentication.md) — protect routes and separate
+  authentication from authorization.
+- [Privacy guide](guides/privacy.md) — privacy profiles and request-safe client
+  signals.
+- [Geo-country resolution](guides/geo-country.md) — trusted headers, local MMDB
+  fallback, and the privacy model.
+- [ASN and anonymizer enrichment](guides/enrichment.md) — opt-in network signals
+  and their database contracts.
+- [Forwarded host authority](guides/forwarded-authority.md) — trust-gated
+  handling of `X-Forwarded-Host` and `Forwarded`, and the process-global Rack
+  forwarding family.
+- [MCP guide](guides/mcp.md) — enable the JSON-RPC endpoint, require bearer
+  tokens, and tune rate limits.
+- [Caddy TLS integration](guides/caddy-tls.md) — deploy the loopback-only
+  permission endpoint.
+- [Migration guides](migrating/) — version-specific behavior changes.
+- [Changelog](../CHANGELOG.rst) — release history and upgrade-impacting changes.
+
+The [architecture decision records](adr/) preserve durable technical rationale.
+They are **not** the primary entry point for implementing an application:
+
+- [ADR-001: Route authentication at the handler boundary](adr/adr-001-route-authentication-at-handler-boundary.md)
+- [ADR-002: Multi-strategy authentication and authorization](adr/adr-002-multi-strategy-authentication-and-authorization.md)
+- [ADR-003: Caddy TLS route-based integration](adr/adr-003-caddy-tls-route-based-integration.md)
+- [ADR-004: Compatibility support and security maintenance](adr/adr-004-separate-compatibility-from-security-maintenance.md)
+- [Ruby `IPAddr#to_s` encoding note](guides/ipaddr-encoding-quirk.md)
+
+## Target structure
+
+The documentation should grow by reader task and stability, not by the order in
+which implementation work occurred:
+
+```text
+docs/
+├── README.md                         # this map and current entry point
+├── getting-started.md                # first app after the README example
+├── guides/                           # stable, task-oriented application guides
+│   ├── routing.md
+│   ├── application-lifecycle.md
+│   ├── authentication.md
+│   ├── security.md
+│   ├── privacy.md
+│   ├── locales.md
+│   └── operations.md
+├── integrations/                     # deployment-specific contracts
+│   ├── mcp.md
+│   └── caddy-tls.md
+├── reference/                        # compact, stable contracts—not a code mirror
+│   ├── route-syntax.md
+│   ├── configuration.md
+│   ├── request-and-response.md
+│   ├── errors.md
+│   └── runtime-and-dependency-security.md
+├── migrating/                        # release-specific upgrade guides
+├── adr/                              # accepted architecture decision records
+└── maintainers/
+    └── investigations/                # local working notes; untracked by design
+```
+
+### What belongs where
+
+- **Getting started** gets a reader from an installed gem to a running app and
+  links to the next common task.
+- **Guides** answer a single application task. They include safe defaults,
+  prerequisites, a compact example, verification, and links to the relevant
+  compact reference.
+- **Integrations** document an external system's HTTP or deployment contract,
+  including trust boundaries and failure behavior.
+- **Reference** records only contracts that must be precise across multiple
+  guides: route grammar, configuration names, request/response helpers, error
+  behavior, and environment keys. It links to code rather than repeating every
+  method.
+- **Migration** documents a release-bound action and its before/after behavior.
+  It does not become a general guide.
+- **Architecture decision records** preserve the context, decision, and
+  consequences of durable technical choices without asking application developers
+  to infer the current contract from a proposal.
+- **Maintainer investigations** preserve unfinished exploration separately from
+  accepted decisions and application documentation.
+
+## Migration plan for the current directory
+
+This is a classification plan, not a request to rewrite every document now.
+Move or replace a document only when its destination guide is ready. Some
+working-tree documents are currently ignored by `docs/.gitignore`; reconcile
+and explicitly track them before treating them as published documentation.
+
+| Current material | Target disposition | Reason |
+| --- | --- | --- |
+| `geo-country.md`, `enrichment.md` | Fold into `guides/privacy.md`; retain focused pages while they remain useful | They are current, task-oriented, and contain important privacy constraints. |
+| `authentication.md`, `AUTH_STRATEGIES.txt` | Replace with `guides/authentication.md` and `reference/route-syntax.md` | The guide should reflect current strategy results, role rules, ordered fallback, and terminal failures in one maintained place. |
+| `ADVANCED_ROUTES.txt` | Replace with `guides/routing.md` and `reference/route-syntax.md` | Route grammar and target kinds are a public contract; the current quick reference is incomplete for modern handler types and security-gating validation. |
+| `ip_privacy.md`, `structured_logging.md`, `configuration_freezing.md` | Reconcile against current behavior, then fold into privacy, operations, and lifecycle guides | They describe durable concepts, but must be verified before being promoted as canonical documentation. |
+| `reverse-proxy-network-services.md` | Extract `guides/caddy-tls.md`; retain its decision as [ADR-003](adr/adr-003-caddy-tls-route-based-integration.md) | Operators need a concise deployment guide; implementation rationale should remain separately discoverable. |
+| `MCP_IMPLEMENTATION.md` | Done: published as [guides/mcp.md](guides/mcp.md); implementation notes belong under `maintainers/` | The protocol user and the maintainer have different questions. |
+| `multi-strategy-authentication-design.md`, `route-auth-wrapper-resolution.md` | Retain the accepted decisions as [ADR-002](adr/adr-002-multi-strategy-authentication-and-authorization.md) and [ADR-001](adr/adr-001-route-authentication-at-handler-boundary.md) | They explain durable architecture choices rather than the current application contract. |
+| Dated architecture, hardening, enhancement, and streaming files | Move to `maintainers/investigations/`; keep only active proposals in the main tree | Dates and working notes are valuable history but should not compete with supported guides. |
+| `testing-guide.md` | Reconcile with current test support, then publish as `guides/operations.md` or `guides/testing.md` | Testing is an application task, not an implementation design. |
+
+## Documentation rules for future changes
+
+1. Add a capability to this map only when a stable guide exists, or when the
+   README provides the complete safe first-use example.
+2. Update the affected guide and its compact reference in the same change as a
+   public behavior change. Use the changelog for the release record, not as a
+   substitute for instructions.
+3. Record security defaults, trust boundaries, configuration-freezing timing,
+   and failure behavior where they affect use. Those are part of the contract.
+4. Keep a proposal separate from its outcome. When work lands, add a short
+   status/outcome note and link from the guide to the decision only when the
+   rationale helps a maintainer.
+5. Prefer one canonical page for each task. Other pages should link to it rather
+   than copy examples or option lists.
+6. Validate every new command and example against the supported Ruby and Rack
+   versions before publishing it as runnable documentation.
+
+## First documentation milestone
+
+A useful first milestone is intentionally small:
+
+1. Publish this map and make it the `README` documentation destination. **Done.**
+2. Write `reference/route-syntax.md` from `Otto::RouteDefinition` and route
+   handler behavior, including handler kinds and fail-fast `auth=`, `role=`, and
+   `csrf=` option syntax. **Done.**
+3. Publish `guides/routing.md`, `guides/authentication.md`, `guides/privacy.md`,
+   and `guides/caddy-tls.md` by reconciling the existing material with the
+   current code and specs. **Initial guides done.**
+4. Move completed designs and working investigations behind `maintainers/` so
+   the top-level reader journey remains stable. **Done.**
+
+That sequence makes Otto's current shape visible quickly while leaving room for
+new capabilities without turning `docs/` into a second, drifting codebase.

data/docs/adr/README.md

@@ -0,0 +1,16 @@
+# Architecture decision records
+
+Architecture decision records (ADRs) document durable technical decisions that
+shape Otto's architecture. They preserve the context, decision, and consequences
+without replacing the supported application documentation.
+
+## Records
+
+- [ADR-001: Enforce route authentication at the handler boundary](adr-001-route-authentication-at-handler-boundary.md)
+- [ADR-002: Use ordered authentication strategy chains and two-layer authorization](adr-002-multi-strategy-authentication-and-authorization.md)
+- [ADR-003: Provide Caddy on-demand TLS as a route-based feature integration](adr-003-caddy-tls-route-based-integration.md)
+- [ADR-004: Separate compatibility support from security maintenance](adr-004-separate-compatibility-from-security-maintenance.md)
+
+New records use the next three-digit sequence number and describe their status,
+context, decision, and consequences. Update a record's status when a later ADR
+supersedes it; do not rewrite accepted decisions to reflect later changes.

data/docs/adr/adr-001-route-authentication-at-handler-boundary.md

@@ -0,0 +1,38 @@
+# ADR-001: Enforce route authentication at the handler boundary
+
+- **Status:** Accepted
+- **Date:** 2025-10-10
+
+## Context
+
+Route declarations carry their `auth=` requirements. Authentication middleware
+runs before routing, so it cannot reliably inspect the matched route or enforce
+that requirement. That left route-level authentication dependent on application
+code instead of Otto's routing contract.
+
+## Decision
+
+Otto enforces authentication with `RouteAuthWrapper`, which wraps a route handler
+after Otto has resolved the route and before the application handler runs. The
+wrapper reads the route definition, executes its configured authentication
+strategy or strategy chain, and stores the resulting `StrategyResult` in the
+request environment.
+
+Routes without `auth=` receive an anonymous `StrategyResult`. This gives Logic
+classes a consistent context while preserving public-route behavior.
+
+## Consequences
+
+- `auth=` is enforced at the point where the route definition is available.
+- Authentication remains handler-level architecture, not a global middleware
+  concern.
+- Logic classes and handlers can rely on `env['otto.strategy_result']` being set
+  when authentication is configured.
+- Authentication strategy registration must finish before the first request,
+  when Otto freezes configuration.
+
+## Related documentation
+
+- [Authentication and authorization guide](../guides/authentication.md)
+- [Route syntax reference](../reference/route-syntax.md)
+- [ADR-002: Multi-strategy authentication and authorization](adr-002-multi-strategy-authentication-and-authorization.md)

data/docs/adr/adr-002-multi-strategy-authentication-and-authorization.md

@@ -0,0 +1,50 @@
+# ADR-002: Use ordered authentication strategy chains and two-layer authorization
+
+- **Status:** Accepted
+- **Date:** 2025-11
+
+## Context
+
+An Otto route may need to accept more than one credential mechanism, such as a
+browser session and an API key. Authentication must support that without making
+invalid explicit credentials silently fall back to anonymous access. It must also
+separate broad route access checks from authorization that depends on a loaded
+resource.
+
+## Decision
+
+Use a comma-separated `auth=` value for an ordered, OR-based strategy chain:
+
+```text
+GET /api/data  Api::Data#show auth=session,api_key response=json
+```
+
+Otto validates all named strategies before it executes the chain. Strategies run
+left to right, and the first authenticated result wins. Plain failures allow the
+next strategy to run. An anonymous result, such as `noauth`, is held as a
+fallback until the chain completes. A terminal `AuthFailure` stops the chain and
+returns an authentication failure; it is reserved for explicitly presented
+credentials that were examined and rejected.
+
+Use `role=` for broad route-level authorization after authentication. Multiple
+roles use OR logic. Perform ownership, relationship, and other resource-specific
+authorization in a Logic class's `raise_concerns` method; raise
+`Otto::Security::AuthorizationError` when access is denied.
+
+## Consequences
+
+- A route can accept multiple credential types without duplicate handlers.
+- Strategy declaration order determines the order of ordinary attempts, but a
+  terminal failure always fails closed.
+- Unknown strategy names fail before any configured strategy runs, preventing a
+  partially configured route from serving traffic.
+- Missing authentication results in `401`; a valid subject denied by a strategy,
+  role check, or resource check results in `403`.
+- Applications should configure inexpensive, common strategies first and mark a
+  failure terminal only when explicit credentials were rejected.
+
+## Related documentation
+
+- [Authentication and authorization guide](../guides/authentication.md)
+- [Route syntax reference](../reference/route-syntax.md)
+- [ADR-001: Route authentication at the handler boundary](adr-001-route-authentication-at-handler-boundary.md)

data/docs/adr/adr-003-caddy-tls-route-based-integration.md

@@ -0,0 +1,48 @@
+# ADR-003: Provide Caddy on-demand TLS as a route-based feature integration
+
+- **Status:** Accepted
+- **Date:** 2026-07
+
+## Context
+
+Caddy's on-demand TLS permission check has a fixed HTTP contract, but each
+application previously had to implement routing, input validation, caller
+restriction, response semantics, and failure handling around its domain-allow
+policy. A manually wired handler and guard makes it possible to expose the
+certificate-issuance endpoint without its required protection.
+
+## Decision
+
+Provide `Otto::CaddyTLS` as an opt-in, feature-named integration. Calling
+`enable_caddy_tls!` registers the permission route and, by default, its
+path-scoped `LocalhostGuard`; the application supplies only the domain allow or
+deny decision.
+
+The guard authorizes a direct loopback socket peer, not a client address derived
+from forwarding headers. It also rejects forwarding headers for the protected
+path. The endpoint therefore remains loopback-only even in cross-host
+deployments: run a small permission app alongside Caddy and let the application
+callback use its existing trusted data channel.
+
+The integration fails closed: a missing or invalid `domain` is rejected, a falsey
+or exception-raising permission callback denies the request, and enabling the
+integration without a callback raises an error. The default endpoint is
+`/_caddy/tls-permission`.
+
+## Consequences
+
+- Caddy TLS setup has one code-side entry point that bundles the route, guard,
+  and decision callback.
+- The endpoint cannot be reached successfully through a public reverse-proxy
+  path merely because the proxy connects to Otto over loopback.
+- `localhost_only: false` is an explicit opt-out; the deployment must then
+  provide network-level isolation.
+- A generic network-services registry is not introduced. Future integrations
+  should use a feature-specific namespace and promote only mechanisms shared by
+  more than one concrete feature.
+
+## Related documentation
+
+- [Caddy on-demand TLS guide](../guides/caddy-tls.md)
+- [Caddy TLS example](../../examples/caddy_tls_demo/README.md)
+- [`Otto::CaddyTLS::LocalhostGuard`](../../lib/otto/caddy_tls/localhost_guard.rb)

data/docs/adr/adr-004-separate-compatibility-from-security-maintenance.md

@@ -0,0 +1,58 @@
+# ADR-004: Separate compatibility support from security maintenance
+
+- **Status:** Accepted
+- **Date:** 2026-09-04
+
+## Context
+
+Otto declares Ruby and dependency version ranges so that applications can resolve
+a compatible bundle. Those declarations can be mistaken for security guarantees:
+a Ruby version may remain compatible with Otto after upstream security maintenance
+ends, and a gem version may satisfy Otto's dependency range after a new advisory
+makes that version unsafe.
+
+Otto's own lockfile and CI matrix test Otto's development resolution and API
+compatibility. They cannot determine or secure the final dependency graph resolved
+by every application that installs Otto. The current Ruby support matrix,
+dependency constraints, and audit procedures also change over time, so they belong
+in maintained reference documentation rather than in a historical decision record.
+
+## Decision
+
+Otto treats compatibility support as distinct from upstream security maintenance.
+Compatibility testing means that Otto is expected to work on a runtime or with a
+dependency version; it does not mean that the runtime or dependency still receives
+security fixes.
+
+The version ranges in `otto.gemspec` express API compatibility. Their lower bounds
+are not guaranteed security floors, and installation success does not certify a
+resolved bundle as free of known vulnerabilities.
+
+Applications that consume Otto own the security auditing and maintenance of their
+resolved lockfiles. Otto may constrain a known-bad version when warranted, but
+maintainer constraints and CI do not replace application-level auditing.
+
+Otto continues to test Ruby 3.2 as a compatibility target despite its upstream end
+of life. This preserves compatibility for users who still need that runtime without
+representing Ruby 3.2 as security-maintained.
+
+## Consequences
+
+- Otto can retain useful compatibility coverage without implying that it provides
+  upstream interpreter or dependency security maintenance.
+- Applications with security-maintenance requirements must select an upstream-
+  maintained Ruby, audit their complete resolved bundles, and deploy audited
+  lockfiles.
+- Dependency lower bounds remain stable compatibility baselines unless an API or
+  security issue requires a targeted constraint change.
+- Ruby 3.2 compatibility failures remain release-relevant while it is a blocking
+  target, even though applications should not infer that Ruby 3.2 receives security
+  fixes.
+- The current support matrix, compatibility ranges, audit commands, and consumer
+  procedures may change in the canonical reference without rewriting this ADR. A
+  later architectural decision may supersede this record if the policy changes.
+
+## Related documentation
+
+- [Runtime and dependency security policy](../reference/runtime-and-dependency-security.md)
+  — canonical current matrix, compatibility policy, and consumer audit procedures