otto 2.8.1 → 2.10.0

data/examples/mcp_demo/README.md

@@ -1,75 +1,96 @@
 # Otto MCP Demo
 
-This example demonstrates Otto's Model-Controller-Protocol (MCP) feature. MCP provides a standardized JSON-RPC 2.0 endpoint (`/_mcp`) for programmatic access to your application resources and tools.
-
-MCP is useful for building CLIs, admin interfaces, integrating with AI systems, or allowing other services to interact with your application.
+This example boots Otto's Model Context Protocol (MCP) JSON-RPC 2.0 endpoint at
+`/_mcp`. Use it to verify endpoint initialization alongside ordinary Otto web
+routes.
 
 ## What You'll Learn
 
-- How to set up an MCP endpoint for programmatic access
-- Exposing application resources via JSON-RPC 2.0
-- Securing MCP endpoints with bearer token authentication
-- Distinguishing between read-only resources and executable tools
-- Organizing methods for both web and MCP interfaces
-- How MCP integrates with your existing Otto application
+- How to enable an MCP HTTP endpoint
+- How the endpoint coexists with ordinary Otto web routes
+- How to send a JSON-RPC 2.0 `initialize` request
+- How bearer-token authentication protects the endpoint
+- The current resource and tool limitations described below
 
 ## Features Demonstrated
 
-- **MCP Endpoint**: Single `POST /_mcp` endpoint for all interactions
-- **Authentication**: Bearer token authentication for secure access
-- **Rate Limiting**: Built-in rate limiting to prevent abuse
-- **Resources**: Read-only data exposed via `MCP` routes
-- **Tools**: Executable actions exposed via `TOOL` routes
-- **Web Interface**: Separate web routes coexist with MCP routes
-- **JSON-RPC 2.0**: Standard protocol for all MCP interactions
+- **MCP endpoint**: A single `POST /_mcp` endpoint
+- **Web interface**: Separate web routes coexist with the MCP endpoint
+- **JSON-RPC 2.0**: `initialize`, `resources/list`, and `tools/list` requests
 
 ## How to Run
 
-### Using rackup (recommended)
+Run this example from an Otto source checkout. It requires Ruby 3.2 through
+4.0, Bundler, and the development dependencies: `rackup` is a development
+dependency in the root `Gemfile` and is not installed with the released `otto`
+gem. MCP enables schema validation and rate limiting by default. Those features
+require `json_schemer` 2.0.0 or newer in the 2.x series and `rack-attack` 6.7.0
+or newer in the 6.x series:
 
-```sh
-cd examples/mcp_demo
-rackup config.ru
+```ruby
+# Gemfile
+gem 'json_schemer', '~> 2.0'
+gem 'rack-attack', '~> 6.7'
 ```
 
-### Using thin
+If either enabled feature's gem is missing or incompatible, MCP setup raises
+`Otto::OptionalDependencyError` during configuration. Pass
+`enable_validation: false` or `enable_rate_limiting: false` to `enable_mcp!`, or
+alongside `mcp_enabled: true` in the `Otto.new` options, only when that protection
+is intentionally disabled. To enforce the configured limits, mount
+`Rack::Attack` before Otto in `config.ru`, as this example does.
 
 ```sh
+cd /path/to/otto
+bundle config set with development
+bundle install
 cd examples/mcp_demo
-thin -R config.ru -p 9292 start
+bundle exec rackup config.ru
 ```
 
-The server will start on `http://localhost:9292`.
 
-- **Web interface**: Navigate to `http://localhost:9292` in your browser
-- **MCP endpoint**: Send JSON-RPC 2.0 requests to `http://localhost:9292/_mcp`
+The server listens at `http://localhost:9292` by default.
+
+- **Web interface**: Open `http://localhost:9292/`.
+- **Health check**: `curl -i http://localhost:9292/health` returns `200` and `OK`.
+- **MCP endpoint**: Send JSON-RPC 2.0 requests to `http://localhost:9292/_mcp`.
 
 ## Authentication
 
-All MCP requests require bearer token authentication via the `Authorization` header.
+`config.ru` configures two bearer tokens, and Otto enforces them: every request
+to `/_mcp` must send `Authorization: Bearer demo-token-123` (or
+`X-MCP-Token: demo-token-123`). Requests without a valid token get HTTP `401`
+and a JSON-RPC `Unauthorized` error. The `requests_per_minute` and
+`tools_per_minute` values in `config.ru` are applied as configured. See the
+[MCP guide](../../docs/guides/mcp.md) for the full option list.
+
+## Current Limitations
 
-Valid tokens:
-- `demo-token-123` - Standard user
-- `another-token-456` - Alternative user
+Although `routes` contains `MCP /users` and `TOOL /create_user` declarations,
+the current route-loading path does not register them. Therefore
+`resources/list` and `tools/list` both return empty arrays, and `resources/read`
+or `tools/call` for those names fails. This README documents the runnable
+endpoint behavior; do not use this example as a resource or tool integration
+template until those routes are registered.
 
 ## Interacting with the MCP Endpoint
 
 All MCP interactions use the `POST /_mcp` endpoint. Each request is a JSON-RPC 2.0 request with:
 
 - `jsonrpc`: Always `"2.0"`
-- `method`: The RPC method name (derived from route path)
+- `method`: The RPC method name
 - `id`: Request ID (for matching responses)
 - `params`: Optional parameters as an object
 
 Required headers:
-- `Authorization: Bearer <token>`
 - `Content-Type: application/json`
+- `Authorization: Bearer demo-token-123` (or `X-MCP-Token: demo-token-123`)
 
 Example:
 ```sh
 curl -X POST http://localhost:9292/_mcp \
-  -H 'Authorization: Bearer demo-token-123' \
   -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer demo-token-123' \
   -d '{
     "jsonrpc": "2.0",
     "method": "initialize",
@@ -84,156 +105,53 @@ The `initialize` method is a built-in MCP method that returns information about
 
 ```sh
 curl -X POST http://localhost:9292/_mcp \
-     -H 'Authorization: Bearer demo-token-123' \
      -H 'Content-Type: application/json' \
+     -H 'Authorization: Bearer demo-token-123' \
      -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}'
 ```
 
-### Resource: List Users
+## Verification
 
-This calls the `UserAPI.mcp_list_users` method defined as an `MCP` route. The method name for the JSON-RPC call is derived from the route path (`/users` -> `users/list`).
+A successful `initialize` request returns `result.protocolVersion`,
+`result.capabilities`, and `result.serverInfo` with the same request ID. To
+confirm the current registry state, run:
 
 ```sh
 curl -X POST http://localhost:9292/_mcp \
-     -H 'Authorization: Bearer demo-token-123' \
-     -H 'Content-Type: application/json' \
-     -d '{"jsonrpc":"2.0","method":"users/list","id":2}'
-```
-
-### Tool: Create User
-
-This calls the `UserAPI.mcp_create_user` method defined as a `TOOL` route. The method name is derived from the route path (`/create_user` -> `create_user`).
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer demo-token-123' \
+  -d '{"jsonrpc":"2.0","method":"resources/list","id":2}'
 
-```sh
 curl -X POST http://localhost:9292/_mcp \
-     -H 'Authorization: Bearer demo-token-123' \
-     -H 'Content-Type: application/json' \
-     -d '{
-          "jsonrpc": "2.0",
-          "method": "create_user",
-          "id": 3,
-          "params": {
-            "name": "Charlie",
-            "email": "charlie@example.com"
-          }
-        }'
-```
-
-## Expected Output
-
-### Successful Initialize Request
-```json
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "resources": [
-      {
-        "uri": "users",
-        "name": "User List",
-        "description": "List all users"
-      }
-    ],
-    "tools": [
-      {
-        "name": "create_user",
-        "description": "Create a new user",
-        "inputSchema": {
-          "type": "object",
-          "properties": {
-            "name": { "type": "string" },
-            "email": { "type": "string" }
-          }
-        }
-      }
-    ]
-  },
-  "id": 1
-}
-```
-
-### Successful Resource Request
-```json
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "users": [
-      { "id": 1, "name": "Alice", "email": "alice@example.com" },
-      { "id": 2, "name": "Bob", "email": "bob@example.com" }
-    ]
-  },
-  "id": 2
-}
-```
-
-### Successful Tool Execution
-```json
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "user": {
-      "id": 3,
-      "name": "Charlie",
-      "email": "charlie@example.com"
-    }
-  },
-  "id": 3
-}
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer demo-token-123' \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":3}'
 ```
 
-### Authentication Failure
-```json
-{
-  "jsonrpc": "2.0",
-  "error": {
-    "code": -32003,
-    "message": "Unauthorized"
-  },
-  "id": 1
-}
-```
+Each request returns `"jsonrpc":"2.0"` and an empty `resources` or `tools`
+array in the current checkout.
 
 ## File Structure
 
 - `README.md`: This file
 - `app.rb`: Application logic
-  - `DemoApp`: Web interface with HTML pages
-  - `UserAPI`: MCP handlers for resources and tools
+  - `DemoApp`: Web interface and health check
+  - `UserAPI`: Intended MCP resource and tool handlers (not registered by the current route-loading path)
 - `config.ru`: Rack configuration (loads Otto, enables MCP)
 - `routes`: Route definitions for web and MCP routes
 
-## Route Types
+## Routes
 
-### Web Routes
-Regular HTTP routes for the web interface:
-```
-GET  /            DemoApp#welcome
-GET  /users       DemoApp#list_users
-```
-
-### MCP Resource Routes
-Read-only resources exposed via MCP:
-```
-MCP  /users       UserAPI#mcp_list_users
-```
-- Called via: `POST /_mcp` with method `users/list`
+The ordinary web routes in `routes` are active:
 
-### MCP Tool Routes
-Executable operations exposed via MCP:
 ```
-TOOL /create_user UserAPI#mcp_create_user
+GET  /        DemoApp.index
+GET  /health  DemoApp.health
 ```
-- Called via: `POST /_mcp` with method `create_user`
 
-## Understanding MCP Method Names
-
-MCP route paths are converted to method names:
-
-| Route Type | Path | Method Name | Handler |
-|-----------|------|-------------|---------|
-| MCP | `/users` | `users/list` | `mcp_list_users` |
-| MCP | `/users/:id` | `users/get` | `mcp_get_user` |
-| TOOL | `/create_user` | `create_user` | `mcp_create_user` |
-| TOOL | `/users/:id/update` | `users/update` | `mcp_update_user` |
+The file also contains `MCP /users UserAPI.mcp_list_users` and
+`TOOL /create_user UserAPI.mcp_create_user`. See [Current Limitations](#current-limitations):
+they are not registered by this checkout's route-loading path.
 
 ## Next Steps
 
@@ -241,7 +159,3 @@ MCP route paths are converted to method names:
 - Integrate with AI systems that support MCP
 - Combine with [Authentication](../authentication_strategies/) for role-based MCP access
 - Explore [Advanced Routes](../advanced_routes/) for more routing patterns
-
-## Further Reading
-
-- [CLAUDE.md](../../CLAUDE.md#mcp) - Detailed MCP documentation (if available)

data/examples/mcp_demo/config.ru

@@ -14,4 +14,5 @@ app = Otto.new('routes', {
 # The `mcp_enabled: true` flag automatically sets up the /_mcp endpoint.
 # The routes file maps MCP and TOOL methods to classes.
 
+use Rack::Attack
 run app

data/examples/security_features/README.md

@@ -1,265 +1,67 @@
 # Otto Security Features Example
 
-This example demonstrates Otto's built-in security features, showing best practices for CSRF protection, input validation, file upload handling, and security headers.
+This source-checkout example configures CSRF protection, request validation, request-size and parameter limits, trusted proxies, and response security headers. It provides forms for feedback, file-upload metadata, and profile input so you can observe those protections.
 
-## What You'll Learn
+## Prerequisites
 
-- Enabling and using CSRF protection
-- Input validation for preventing injection attacks
-- XSS prevention through output escaping
-- Secure file upload handling with filename sanitization
-- Adding security headers (CSP, HSTS, etc.)
-- Request limiting to prevent denial-of-service
-- Trusted proxy configuration for reverse proxies
-- Privacy features (IP masking, user agent anonymization)
+Run this example from an Otto source checkout. Its `config.ru` loads Otto from `../../lib`, rather than from an installed gem.
 
-## Security Features Demonstrated
-
-### CSRF Protection
-All POST/PUT/DELETE requests include CSRF tokens in forms:
-```ruby
-<form method="post">
-  <input type="hidden" name="_csrf_token" value="<%= @req.csrf_token %>">
-  <input type="text" name="message">
-</form>
-```
-
-### Input Validation
-Server-side validation of user-submitted data:
-- Length limits (max 1000 chars for messages)
-- Character restrictions (no HTML tags)
-- Required field validation
-- Type validation
-
-### XSS Prevention
-All output is properly escaped:
-```ruby
-@res.body = "<h1>#{ERB::Util.html_escape(user_input)}</h1>"
-```
-
-### Secure File Uploads
-File uploads are validated and sanitized:
-- File type checking (whitelist approach)
-- Size limits (prevent large uploads)
-- Filename sanitization (remove path traversal)
-- Safe storage location
-
-### Security Headers
-Automatic security headers are sent with responses:
-- `Content-Security-Policy` - Prevents inline scripts
-- `Strict-Transport-Security` - Enforces HTTPS
-- `X-Frame-Options` - Prevents clickjacking
-- `X-Content-Type-Options` - Prevents MIME sniffing
-
-### Request Limiting
-Configure limits to prevent DOS attacks:
-- Maximum request size
-- Maximum parameter keys
-- Maximum parameter depth
-
-### Trusted Proxies
-Configure reverse proxy IPs for X-Forwarded-For headers:
-```ruby
-app.add_trusted_proxy('10.0.0.0/8')
-app.add_trusted_proxy(/^192\.168\./)
-```
-
-### Privacy by Default
-Automatic privacy features:
-- Public IP masking (203.0.113.50 → 203.0.113.0)
-- User agent anonymization (versions stripped)
-- Country-level geo-location only
-- Private/localhost IPs NOT masked by default (configurable via `configure_ip_privacy()`)
-
-## How to Run
-
-### Using rackup (recommended)
+You need a supported Ruby version and Bundler. `rackup` is a development dependency in the root `Gemfile`, so enable the `development` group before installing dependencies:
 
 ```sh
-cd examples/security_features
-rackup config.ru -p 10770
+# From the repository root
+bundle config set with development
+bundle install
 ```
 
-### Using thin
+## Run the example
 
 ```sh
+# From the repository root
 cd examples/security_features
-thin -e dev -R config.ru -p 10770 start
-```
-
-Open your browser and navigate to `http://localhost:10770`.
-
-## Testing Security Features
-
-### XSS Prevention
-
-Try entering `<script>alert("XSS")</script>` in form fields:
-- The script tag is rendered as text, not executed
-- You'll see it displayed as literal HTML tags
-- Browser's developer tools show escaped HTML
-
-### Input Validation
-
-Test validation rules:
-- Submit a message > 1000 characters (fails)
-- Submit special characters like `<>` (fails)
-- Submit valid text (succeeds)
-
-### CSRF Protection
-
-Examine form submissions:
-- All POST forms include a `_csrf_token` hidden field
-- Each request has a unique token
-- Removing the token causes 403 Forbidden
-- Browser's developer tools show token in form data
-
-### File Uploads
-
-Test file upload security:
-- Try uploading an executable file (rejected)
-- Try uploading a legitimate image (accepted)
-- Check saved filename (sanitized, safe)
-- Verify file permissions and location
-
-### Security Headers
-
-Check response headers:
-- Open browser's Network tab in developer tools
-- Click any response to view headers
-- Look for security headers in response
-- Visit `/headers` endpoint to see all headers
-
-## Expected Output
-
-### Successful Form Submission
+bundle exec rackup config.ru -p 10770
 ```
-POST /feedback HTTP/1.1
-Content-Type: application/x-www-form-urlencoded
 
-_csrf_token=abc123...
-message=Hello+world
+Open `http://127.0.0.1:10770/`. Keep the server running and use a second terminal for the checks below.
 
-HTTP/1.1 302 Found
-Location: http://localhost:10770/
-Content-Security-Policy: default-src 'self'
-Strict-Transport-Security: max-age=31536000
-```
-
-### Failed CSRF Validation
-```
-HTTP/1.1 403 Forbidden
-Content-Type: text/plain
+## What this example configures
 
-CSRF token validation failed
-```
+`config.ru` enables CSRF protection and request validation, then sets these limits:
 
-### Failed Input Validation
-```
-HTTP/1.1 400 Bad Request
-Content-Type: text/plain
+- Maximum request size: 5 MiB
+- Maximum parameter nesting depth: 10
+- Maximum parameter keys: 50
 
-Message is too long (max 1000 characters)
-```
+It trusts the listed loopback and private-network proxy ranges. Adjust `trusted_proxies` for a real deployment; do not copy this development-oriented list without confirming the proxies that can reach your application.
 
-### Security Headers Response
-```
-Content-Security-Policy: default-src 'self'
-Strict-Transport-Security: max-age=31536000
-X-Frame-Options: SAMEORIGIN
-X-Content-Type-Options: nosniff
-Referrer-Policy: strict-origin-when-cross-origin
-```
+Every route receives the configured headers:
 
-## File Structure
+- `Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'`
+- `Strict-Transport-Security: max-age=31536000; includeSubDomains`
+- `X-Frame-Options: DENY`
 
-- `README.md`: This file
-- `app.rb`: Main application logic with security implementations
-  - Form validation and escaping
-  - File upload handling
-  - Header configuration
-- `config.ru`: Rack configuration with security features enabled
-- `routes`: URL routes mapped to SecureApp class methods
-
-## Key Configuration
-
-In `config.ru`:
-```ruby
-app = Otto.new("./routes")
-
-# Enable security features
-app.enable_csrf_protection!
-
-# Configure request limits
-app.security_config.request_size_limit = 1.megabyte
-app.security_config.max_parameter_keys = 100
-app.security_config.max_parameter_depth = 5
-
-# Add trusted proxies if behind reverse proxy
-app.add_trusted_proxy('10.0.0.0/8')
-
-# Security headers
-app.add_security_header('X-Custom-Header', 'value')
-```
+## Verify the protections
 
-## Common Attack Scenarios
+Use the diagnostic route to inspect request information and the response headers. A POST without a CSRF token exercises the CSRF rejection path:
 
-### XSS Attack
-```javascript
-<img src=x onerror="alert('XSS')">
-```
-**Result**: Safely displayed as text, not executed
-
-### SQL Injection
-```sql
-'; DROP TABLE users; --
-```
-**Result**: Stored as literal text, invalid SQL
-
-### Path Traversal
-```
-../../../../../../etc/passwd
-```
-**Result**: Filename sanitized to just `etc-passwd`
-
-### Large Request
-```
-POST with 10MB body
+```sh
+curl -i http://127.0.0.1:10770/headers
+curl -i -X POST http://127.0.0.1:10770/feedback -d 'message=test'
 ```
-**Result**: Rejected with 413 Payload Too Large
 
-## Best Practices Demonstrated
+The feedback handler rejects script-like input and limits messages to 1,000 characters; profile fields have their own limits and the email field must match the example's basic format check. The upload form demonstrates filename sanitization and request handling. It displays metadata and does **not** permanently store uploaded files; it does not implement a file-type allowlist.
 
-1. **Defense in Depth**: Multiple layers of security
-2. **Input Validation**: Whitelist approach (allow only safe input)
-3. **Output Escaping**: Escape all user-controlled output
-4. **CSRF Tokens**: Unique tokens for each request
-5. **Security Headers**: Prevent common attack vectors
-6. **File Upload Safety**: Validate type and sanitize names
-7. **Request Limiting**: Prevent denial-of-service
+### Current limitation
 
-## Testing with curl
-
-```sh
-# Test CSRF protection (will fail without token)
-curl -X POST http://localhost:10770/feedback \
-  -d "message=test"
-
-# Test with valid CSRF token (get token from form first)
-curl -X POST http://localhost:10770/feedback \
-  -d "_csrf_token=<token>" \
-  -d "message=test"
-
-# Test input validation
-curl -X POST http://localhost:10770/feedback \
-  -d "message=$(python -c 'print(\"x\" * 2000)')"
-```
+The home page generates a CSRF token during its first request. Otto freezes configuration at that point, and the generated-secret warning then attempts to modify the frozen security configuration. As a result, `GET /` currently fails with `FrozenError`, so browser-based valid-form verification is unavailable until that example or the initialization sequence is corrected.
 
-## Next Steps
+## Files to inspect
 
-- Review the application code to see implementation details
-- Explore other examples for different features
+- `config.ru` creates the Otto application and sets the security configuration.
+- `routes` defines the form and diagnostic endpoints.
+- `app.rb` renders CSRF form fields and handles validation, escaped output, and uploaded-file metadata.
 
-## Further Reading
+## Next steps
 
-- [CLAUDE.md](../../CLAUDE.md#security-features) - Security configuration reference
-- [IP Privacy](../../CLAUDE.md#ip-privacy-privacy-by-default) - Privacy configuration
+- See the [authentication strategies example](../authentication_strategies/README.md) for route authentication.
+- Read the [security configuration in the main README](../../README.md#security-features).