otto 2.9.0 → 2.10.0

data/Gemfile.lock

@@ -1,13 +1,11 @@
 PATH
   remote: .
   specs:
-    otto (2.9.0)
+    otto (2.10.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
 

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