maquina-generators 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e7ab2221409345c84231d6908e18f5f14b265d32a10229f288f23d4c5a03006
-  data.tar.gz: b4966e9de4099d0664da18fd6ba2818b560770cdb2dab121a9f06265e38b4769
+  metadata.gz: 490a44073c9b568e54c4b2b83257db4ad4f279ac9e610f022b7556ca81734606
+  data.tar.gz: dcae3d4b2aa0f3866775c1f162522824614397dd399403c715e38f3fb67cb8cb
 SHA512:
-  metadata.gz: f7b0d031778c2aa4b8cc03079e08f049a79d499500dfe0bb8b44b5e94e7743afdfc0ea6d0625d97b0128c937628980c9eb5317eef5bfe9ea62d68cd25f3e0487
-  data.tar.gz: 2ccfde4751e49534fb7c36149c623ea8fd93849a8e26e860fae0566556f2832173f8f488b708dca6e23f8890e8a6b4243571e61c6811723a325c1535f2a5dde5
+  metadata.gz: 8dffc54baad6e0b5443de42b77802d2fcd35253ebd82acc155c874d4f254181174a40f82e3cf216c4ba0dcbbd29be0bd50569acccaf17e795e65c1c0de7e1da1
+  data.tar.gz: 69cf94a55c483bc857d6780d0e89e36f9fb1228959910381ea2e45eb08e07f172f2a6b6676f2b981cdbb61f5c75bf6468e53ed608891eaed459c20fc66d58fb2

data/README.md

@@ -115,6 +115,141 @@ WEBAUTHN_ORIGINS=https://example.com,https://app.example.com
 - **In a browser:** Chrome's virtual authenticator works in DevTools (More tools > WebAuthn) or over CDP (`WebAuthn.addVirtualAuthenticator` with `ctap2`, `internal`, a resident key and user verification). It answers the sign-in page's autofill request on its own, so loading `/session/new` signs you in without a click. To test the button, make `PublicKeyCredential.isConditionalMediationAvailable` return `false`.
 - **Dev server on another port:** set `WEBAUTHN_ORIGINS=http://localhost:<port>`.
 
+### OAuth -- OAuth 2.1 Sign-In for AI Clients
+
+**OAuth** lets AI clients (the MCP Inspector, Claude, any MCP client) sign people in to your app on top of Clave. It is the authorization server behind `maquina:mcp`. Clients identify themselves with a Client ID Metadata Document (CIMD): the `client_id` is an `https` URL whose JSON names the client and its redirect URIs, so there is no dynamic registration and no client secret. Every flow is PKCE (`S256` only), and people sign in with the email code they already use.
+
+No OAuth gem is added: the endpoints, models and fetcher are generated into your app.
+
+#### What it generates
+
+- **Migrations:** `create_oauth_clients`, `create_oauth_authorization_codes`, `create_access_tokens` (refresh tokens live on the access token row)
+- **Models:** `OauthClient` (fetched metadata, refreshed after 24 hours), `OauthAuthorizationCode` (10-minute, single-use, PKCE-checked), `AccessToken` (1-hour access token, rotating refresh token, `read`/`write` scopes; only SHA-256 digests are stored) and `ConnectedApplication`, which groups a person's grants per client
+- **CIMD fetcher:** `OauthClient::MetadataFetcher`, plain `Net::HTTP`. It refuses non-`https` URLs, literal IPs, hosts that resolve to loopback, private, link-local, unspecified or `100.64.0.0/10` addresses, redirects, bodies over 16 KB, responses slower than 3 seconds and documents whose `client_id` does not match
+- **Discovery:** `GET /.well-known/oauth-authorization-server` and `GET /.well-known/oauth-protected-resource/mcp`
+- **Authorize:** `Oauth::AuthorizationsController` at `/oauth/authorize`, the consent screen. A signed-out visitor signs in with Clave and lands back on the exact authorize URL. An unknown client or a redirect URI the client does not list gets an error page and is never redirected
+- **Token and revoke:** `POST /oauth/token` (authorization code and refresh token grants) and `POST /oauth/revoke` (RFC 7009), JSON with `Cache-Control: no-store`
+- **Connected apps:** `ConnectedApplicationsController` at `<prefix>/connected_apps`, where people see each connected client with its scopes and last use, and revoke it. Revoking stops its tokens at once
+- **Gate:** `app/models/mcp.rb` with `Mcp.enabled_for?(user)`, written only if missing. Your app owns it
+- **Rack::Attack:** `/mcp` and `/oauth/token` leave the per-IP throttle and flood ban (they are limited per token and per client instead), plus an `oauth/token/client` throttle of 30 per minute, when `config/initializers/rack_attack.rb` exists
+- **Locale files:** English and Spanish (`config/locales/oauth.*.yml`)
+- **Tests:** fixtures (`oauth_clients`, `oauth_authorization_codes`, `access_tokens`, and `mcp_*` users and account), `OauthTestHelper`, and tests for PKCE, code reuse and expiry, refresh rotation and reuse, `resource` and `iss` checks, the return-to after sign-in and revoking
+
+#### Usage
+
+```bash
+rails g maquina:clave      # first
+rails g maquina:oauth
+rails db:migrate
+```
+
+Anything the generator cannot place safely (a Rack::Attack initializer that no longer has the expected shape) is listed after the install instead of being forced.
+
+#### Options
+
+```bash
+rails g maquina:oauth                       # Full install
+rails g maquina:oauth --skip-views          # Endpoints only; bring your own consent and Connected apps views
+rails g maquina:oauth --prefix /account     # Connected apps at /account/connected_apps (default: /settings)
+rails g maquina:oauth --flag beta_mcp       # Gate consent and Connected apps behind a feature flag
+rails g maquina:oauth --quiet               # No post-install message
+```
+
+#### Feature flag
+
+Without `--flag`, `Mcp.enabled_for?` returns `true` for everyone. With `--flag beta_mcp`, it reads `Rails.application.credentials.features.beta_mcp`, then `ENV["BETA_MCP"]`. When it is off for someone, consent answers `access_denied`, Connected apps is a 404, their MCP tools return nothing and `server/discover` still answers. Replace the method body with Flipper or a column when you need per-user rollout.
+
+### MCP -- Model Context Protocol Server
+
+**MCP** gives your app a standalone [MCP](https://modelcontextprotocol.io) server at `POST /mcp`, signed in through `maquina:oauth`. It speaks protocol `2026-07-28` over plain HTTP: no SSE, no sessions, no `mcp` gem. It ships a `whoami` tool that proves the wiring works, and `maquina:mcp_tool` adds more.
+
+#### What it generates
+
+- **Controller:** `McpController` (`ActionController::API`) with `McpAuthenticatable`, which reads the `Authorization: Bearer` token and checks that it was issued for `<base>/mcp`. A missing or bad token gets 401 with `WWW-Authenticate` pointing at the protected-resource metadata. `GET` and `DELETE /mcp` return 405
+- **Protocol:** `server/discover` (no token needed), `tools/list` and `tools/call`. The `Mcp-Method` and `Mcp-Name` headers must match the body, `params._meta` must carry protocol `2026-07-28`, and the JSON-RPC error codes live in one table in `McpController`. A write tool called with a `read` token gets 403 `insufficient_scope`
+- **Rate limit:** 120 requests per minute per token (per IP without one)
+- **CORS:** `config/initializers/mcp_cors.rb`, a small Rack middleware for `/mcp`, `/oauth/token`, `/oauth/revoke` and `/.well-known/oauth-*` (never `/oauth/authorize`); no `rack-cors`
+- **Registry:** `app/models/mcp/` -- `Mcp::Tools` (dispatch), `Mcp::ToolDefinitions` (what a user sees), `Mcp::ToolError` and `Mcp::UserScope` (the token's user and the records it may reach). Every file in `app/models/mcp/tools/` is a module with `DEFINITIONS`, `WRITE_TOOLS`, `ADMIN_ONLY` and one method per tool. Arguments are checked against the tool's JSON Schema (required keys, types, enums) before dispatch
+- **Tool:** `app/models/mcp/tools/app.rb` with `whoami` (email, granted scope, server and protocol versions, and the flag state with `--flag`), written only if missing
+- **Tests:** `McpTestHelper` (`mcp_post`, `oauth_token_for`), `test/integration/mcp_flow_test.rb` (discover, authorize, consent, token, `whoami`, revoke, 401), `test/integration/mcp_conformance_test.rb` and `test/models/mcp/tools_test.rb`, which fails when a tool that writes is missing from its module's `WRITE_TOOLS`
+
+#### Usage
+
+```bash
+rails g maquina:oauth      # first
+rails g maquina:mcp
+rails db:migrate
+```
+
+Or all at once: `rails g maquina:app --auth clave --mcp`.
+
+#### Options
+
+```bash
+rails g maquina:mcp                     # Full install
+rails g maquina:mcp --flag beta_mcp     # Set the flag in app/models/mcp.rb if it still says FLAG = nil
+rails g maquina:mcp --prefix /account   # The Connected apps prefix you gave maquina:oauth (default: /settings)
+rails g maquina:mcp --skip-views        # You ran maquina:oauth --skip-views: the flow test skips the consent and Connected apps pages
+rails g maquina:mcp --quiet             # No post-install message
+```
+
+#### Connecting a client
+
+Start the app and run the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+bin/dev
+npx @modelcontextprotocol/inspector
+```
+
+Choose the Streamable HTTP transport, enter `http://localhost:3000/mcp` and connect. The Inspector discovers the authorization server, sends you to the consent screen (sign in with your email code if needed), and lists `whoami`. The app then shows up at `/settings/connected_apps`, where revoking it makes the next call answer 401.
+
+#### Operational tools from other generators
+
+When `app/models/mcp/tools.rb` exists, these generators also write an MCP tool module. Every one is `ADMIN_ONLY`: they read data across every account, so only people on the backstage list (`User#backstage_access?`, see [Backstage access](#backstage-access----clave-sign-in-or-basic-auth)) see or call them. An account's `admin` role is not enough, since registration makes everyone who signs up the admin of their own account. Anyone else's token gets "unknown tool". Lists are capped at 50 rows and times are ISO 8601 UTC.
+
+The tools are read-only unless the generator runs with `--mcp-write`, which adds write tools that need a token with the `write` scope and log each call with the user's id.
+
+| Generator | Tool file | Tools |
+|-----------|-----------|-------|
+| `maquina:solid_errors` | `tools/solid_errors.rb` | `list_failures`, `get_failure`, `top_exceptions` (copies `ErrorsQuery`, `FailureTriage` and `ErrorRedactor` into `app/agents/` if missing); `resolve_failure` with `--mcp-write` |
+| `maquina:solid_queue` | `tools/solid_queue.rb` | `queue_status`, `list_failed_jobs`, `get_failed_job` (arguments redacted); `retry_failed_job` and `discard_failed_job` with `--mcp-write` |
+| `maquina:security` | `tools/security.rb` | `recent_blocks`, `security_summary`; `unban_address` with `--mcp-write` (adds `Rack::Attack.unban!` to an initializer written before it existed) |
+| `maquina:csp_reports` | `tools/csp_reports.rb` | `list_csp_reports`, `csp_report_summary` |
+
+The install order does not matter. A sibling run after `maquina:mcp` writes its own tool file. `maquina:mcp` run after the siblings backfills a tool file for each one it finds (`config/initializers/solid_errors.rb`, `config/solid_queue.yml` or `config/queue.yml`, `app/models/security/abuse_event.rb`, `csp_violations` in `db/security_schema.rb`), using the read-only variants. Existing tool files are never overwritten (to add the write tools later, delete the file and run the generator again with `--mcp-write`), and without MCP the siblings write and print nothing about it.
+
+### MCP Tool -- Add a Tool to the MCP Server
+
+**MCP Tool** adds a tool to `app/models/mcp/tools/app.rb`: its JSON Schema definition, a method stub and a test, without editing the registry by hand. It needs `maquina:mcp`.
+
+#### Usage
+
+```bash
+rails g maquina:mcp_tool list_posts status:enum[draft,published]? limit:integer?
+rails g maquina:mcp_tool publish_post id:integer --write
+```
+
+#### Arguments
+
+- `NAME`: lowercase letters, digits and underscores, starting with a letter. A name already in `tools/app.rb` changes nothing; a name in another tool file stops the generator.
+- `name:type`: `string`, `integer`, `number`, `boolean` or `enum[a,b]` (a string limited to those values). A trailing `?` makes the argument optional; every other argument is required.
+
+#### Options
+
+```bash
+rails g maquina:mcp_tool NAME [arg:type ...]           # Read-only tool (readOnlyHint: true)
+rails g maquina:mcp_tool NAME [arg:type ...] --write   # Needs the write scope; added to WRITE_TOOLS
+rails g maquina:mcp_tool NAME --quiet                  # No "Items to finish" message
+```
+
+#### What it generates
+
+- The definition in `DEFINITIONS`, the name in `WRITE_TOOLS` with `--write`, and `def self.<name>(scope:, ...)` that raises `Mcp::ToolError, "<name> is not implemented yet"`. If a marker comment in `tools/app.rb` is gone, the snippet is printed instead.
+- `test/models/mcp/tools/<name>_test.rb`: listed for a `read` token, -32602 for a missing required argument, 403 `insufficient_scope` for a `read` token with `--write`, and a skipped cross-user test (a record owned by `users(:mcp_other)` must come back as not found) to fill in.
+
+Afterwards, write the description for the model (plain English, units stated), the method body (reach records through `scope.records(:posts)` or `scope.find(:posts, id)` so a tool never sees another user's data) and the cross-user test setup.
+
 ### Registration -- Password-Based Authentication with Accounts
 
 **Registration** generates a password-based authentication system with multi-tenant account support. It builds on top of the Rails 8 authentication generator, adding an Account model (tenant), user roles, and a registration flow.
@@ -162,6 +297,30 @@ All generated code lives in your app -- edit it directly:
 
 ---
 
+### Backstage Access -- Clave Sign-In or Basic Auth
+
+Solid Errors, Mission Control Jobs and Security share one `BackstageController` and one way in.
+
+**With Clave installed** (`app/models/email_verification.rb` is there), each of them puts the backstage behind the app's own sign-in:
+
+- `BackstageController` includes `Authentication` and raises `ActiveRecord::RecordNotFound` unless `Current.user.backstage_access?`. Signed out, a page redirects to the sign-in (303 for PATCH/PUT/DELETE, so the engines' Resolve and Discard buttons are not re-sent); signed in but not listed, it is a 404, so the pages never confirm they exist.
+- `User.backstage_emails` and `User#backstage_access?` are added to `app/models/user.rb`. Access is an unblocked user whose email is on the list in credentials:
+
+  ```yaml
+  backstage:
+    emails:
+      - you@example.com
+  ```
+
+  An empty list is nobody. The same predicate gates the admin-only MCP tools.
+- The Basic Auth comes out of the overview, the Security page and both engines' initializers (Mission Control gets `http_basic_auth_enabled = false`). Do not set `backstage.username` or `password`: Solid Errors turns its Basic Auth back on when a password is set.
+- `test/integration/backstage_access_test.rb` checks signed out, not listed, blocked, an empty list and a listed user, with `backstage_operator` and `backstage_member` fixtures.
+- A generator run later keeps the backstage on the sign-in. A file you changed by hand keeps its Basic Auth, and the post-install message names it.
+
+**Without Clave** (no auth, or `maquina:registration`), the backstage uses HTTP Basic Auth with `backstage.username` / `password` from credentials, or each generator's ENV variables, and answers 503 until they are set.
+
+---
+
 ### Solid Errors -- Error Tracking Dashboard
 
 **Solid Errors** installs the [solid_errors](https://github.com/fractaledmind/solid_errors) gem with HTTP authentication and engine mounting.
@@ -169,11 +328,11 @@ All generated code lives in your app -- edit it directly:
 #### What it generates
 
 - **BackstageController:** Inherits from `ActionController::Base` (bypasses app's ApplicationController concerns)
-- **Initializer:** Credentials-first auth with ENV variable fallback, database connection config
+- **Initializer:** Database connection config, and Basic Auth from credentials or ENV when the app has no Clave (see [Backstage access](#backstage-access----clave-sign-in-or-basic-auth))
 - **Route:** Mounts `SolidErrors::Engine` at `<prefix>/errors`
 - **Mailer templates:** Self-contained `error_occurred` HTML and text templates, so `send_emails` works without the dashboard's helpers
 - **Admin navigation:** Shared navigation bar with Overview, Errors, Jobs and Security tabs
-- **Admin overview:** `BackstageDashboardController` at the prefix root with cards for each installed dashboard and a `@metrics` slot for your own aggregate counts; answers 503 until backstage credentials are set
+- **Admin overview:** `BackstageDashboardController` at the prefix root with cards for each installed dashboard and a `@metrics` slot for your own aggregate counts; behind the backstage sign-in, or with Basic Auth answers 503 until backstage credentials are set
 - **Custom layout:** Tailwind-styled layout with admin navigation and toast flash messages
 - **Stimulus controllers:** `clipboard_controller.js` and `backtrace_filter_controller.js`
 - **Custom views:** Tailwind-styled views to override the gem defaults (included by default, use `--no-copy-views` to skip)
@@ -192,17 +351,22 @@ The generator automatically runs `bundle install`. After running, execute `bin/r
 ```bash
 rails g maquina:solid_errors --prefix /admin                          # Default (with custom views)
 rails g maquina:solid_errors --prefix /admin --no-copy-views          # Without custom views
+rails g maquina:solid_errors --prefix /admin --mcp-write              # Also generate the resolve_failure MCP tool
 rails g maquina:solid_errors --prefix /backstage \
   --user-env-var ADMIN_USER --password-env-var ADMIN_PASSWORD         # Custom env vars
 ```
 
 #### Authentication
 
-Credentials are resolved in order:
+With Clave, the app's sign-in and the backstage list; see [Backstage access](#backstage-access----clave-sign-in-or-basic-auth). Without it, Basic Auth credentials are resolved in order:
 
 1. `Rails.application.credentials.backstage.username` / `.password`
 2. `ENV["SOLID_ERRORS_USER"]` / `ENV["SOLID_ERRORS_PASSWORD"]` (configurable)
 
+#### MCP
+
+With `maquina:mcp` installed, it also writes admin-only MCP tools (`list_failures`, `get_failure`, `top_exceptions`) to `app/models/mcp/tools/solid_errors.rb`. `--mcp-write` adds `resolve_failure`, which needs the `write` scope. See [Operational tools from other generators](#operational-tools-from-other-generators). The old `--mcp-http` endpoint is gone; `--agent` still generates `bin/failures` and the stdio `bin/failures-mcp`.
+
 ---
 
 ### Mission Control Jobs -- Job Queue Dashboard
@@ -216,7 +380,7 @@ Credentials are resolved in order:
 - **Initializer:** Sets base controller class, credentials-first auth with ENV variable fallback
 - **Route:** Mounts `MissionControl::Jobs::Engine` at `<prefix>/jobs`
 - **Admin navigation:** Shared navigation bar with Overview, Errors, Jobs and Security tabs
-- **Admin overview:** `BackstageDashboardController` at the prefix root with cards for each installed dashboard and a `@metrics` slot for your own aggregate counts; answers 503 until backstage credentials are set
+- **Admin overview:** `BackstageDashboardController` at the prefix root with cards for each installed dashboard and a `@metrics` slot for your own aggregate counts; behind the backstage sign-in, or with Basic Auth answers 503 until backstage credentials are set
 - **Custom layout:** Tailwind-styled layout with admin navigation, toast flash messages, application/server selection, and tab navigation
 - **Custom views:** Tailwind-styled views for jobs, queues, workers, and recurring tasks (included by default, use `--no-copy-views` to skip)
 
@@ -240,7 +404,7 @@ rails g maquina:mission_control_jobs --prefix /backstage \
 
 #### Authentication
 
-Credentials are resolved in order:
+With Clave, the app's sign-in and the backstage list; see [Backstage access](#backstage-access----clave-sign-in-or-basic-auth). Without it, Basic Auth credentials are resolved in order:
 
 1. `Rails.application.credentials.backstage.username` / `.password`
 2. `ENV["MISSION_CONTROL_JOBS_USER"]` / `ENV["MISSION_CONTROL_JOBS_PASSWORD"]` (configurable)
@@ -271,8 +435,11 @@ The generator automatically runs `bundle install` and installs migrations.
 ```bash
 rails g maquina:solid_queue                      # Default (sqlite3)
 rails g maquina:solid_queue --database postgresql # PostgreSQL
+rails g maquina:solid_queue --mcp-write           # Also generate the retry_failed_job and discard_failed_job MCP tools
 ```
 
+With `maquina:mcp` installed, it also writes admin-only MCP tools (`queue_status`, `list_failed_jobs`, `get_failed_job`) to `app/models/mcp/tools/solid_queue.rb`. `--mcp-write` adds `retry_failed_job` and `discard_failed_job`, which need the `write` scope.
+
 ---
 
 ### Rack Attack -- Request Protection
@@ -282,6 +449,7 @@ rails g maquina:solid_queue --database postgresql # PostgreSQL
 #### What it generates
 
 - **Initializer:** `config/initializers/rack_attack.rb` with the bans, throttles, safelist, 403 responder and an `[ATTACK]` log line per refusal. Its knobs are constants on `Rack::Attack` (`SCANNER_*`, `GENERAL_*`, `FLOOD_*`, `LOGIN_*`) and `Rack::Attack.banned?(ip)` answers whether an address is banned now.
+- **Route guard:** `Rack::Attack.app_route?(path)` answers whether the app itself routes a path.
 
 #### Usage
 
@@ -295,6 +463,9 @@ The generator automatically runs `bundle install`.
 #### Default Protections
 
 - **Scanner ban (Fail2Ban):** three scanner paths in 10 minutes bans the IP for 7 days. Scanner paths are PHP files (`*.php`), WordPress paths (`wp-admin`, `wp-login`, etc.), sensitive files anywhere in the path (`.env`, `.git`, `/etc/passwd`, etc.), backup archives (`.zip`, `.sql`, `.tar.gz`, `.bak`, etc.) and scanner targets (`phpmyadmin`, `cgi-bin`, etc.). `/rails/active_storage` is exempt.
+  - The list also names what a modern scanner reaches for first: cloud provider credentials (`service-account.json`, `firebase-adminsdk.json`), container runtime internals (`/var/run/secrets/...`, `/proc/self/environ`), infrastructure as code (`docker-compose.yml`, `terraform.tfstate`), bare secret files (`secrets.json`, `credentials.json`), dev-server artefacts (`__vite_rsc_findSourceMapURL`, `/@fs/...`), source maps, dotfile credentials and encoded path traversal (`..%2F`).
+  - The path is unhidden before it is matched, so an encoded traversal is caught like a plain one. A public key is not a private key: `/public_key.pem` is still served.
+- **Route guard:** a scanner rule stands down when the app itself routes the path, so a broad pattern cannot break a real route. A format Rails knows counts as the route, so `/service-worker.js` is `/service-worker(.:format)`, but `/login.php` is not `/login`. A root dynamic segment or catch-all (`/:slug`, `/*path`) does not count, because it would match every path; the app's other routes stay protected.
 - **Flood ban (Allow2Ban):** 600 requests in 5 minutes (twice the general throttle) bans the IP for 1 day.
 - **Throttles:** 300 requests/5min per IP (general; `/assets` and `/rails/active_storage` exempt), 5 `POST /session`/20s per IP
 - **Safelists:** Localhost (`127.0.0.1`, `::1`)
@@ -347,18 +518,23 @@ The generator automatically runs `bundle install`. The page needs maquina_compon
 rails g maquina:security --prefix /admin                      # Default
 rails g maquina:security --prefix /admin --login-path /sign_in  # Different sign-in path
 rails g maquina:security --prefix /admin --no-copy-views      # Without views
+rails g maquina:security --prefix /admin --mcp-write          # Also generate the unban_address MCP tool
 rails g maquina:security --prefix /backstage \
   --user-env-var ADMIN_USER --password-env-var ADMIN_PASSWORD  # Custom env vars
 ```
 
 #### Authentication
 
-HTTP Basic Auth, with credentials resolved in order:
+With Clave, the app's sign-in and the backstage list; see [Backstage access](#backstage-access----clave-sign-in-or-basic-auth). Without it, HTTP Basic Auth, with credentials resolved in order:
 
 1. `Rails.application.credentials.backstage.username` / `.password`
 2. `ENV["SECURITY_USER"]` / `ENV["SECURITY_PASSWORD"]` (configurable)
 
-The page answers 503 until one of them is set, so it is never left open.
+With Basic Auth the page answers 503 until one of them is set, so it is never left open.
+
+#### MCP
+
+With `maquina:mcp` installed, it also writes admin-only MCP tools (`recent_blocks`, `security_summary`). `--mcp-write` adds `unban_address`, which lifts the scanner and flood bans on one address through `Rack::Attack.unban!` and needs the `write` scope.
 
 #### Trying it locally
 
@@ -423,7 +599,7 @@ Watch the Security page while the policy is report-only, then set `content_secur
 9. Adds turbo morphing, `yield :head`, and simplifies `<main>` tag in layout
 10. Optionally installs authentication (`maquina:clave` or `maquina:registration`)
 11. Invokes sub-generators: `maquina:mission_control_jobs`, `maquina:solid_errors`
-12. Runs external installers: `solid_queue:install`, `solid_errors:install`, `solid_cache:install`, `solid_cable:install`, `maquina_components:install`, then `maquina:security` (which installs the `maquina:rack_attack` rules)
+12. Runs external installers: `solid_queue:install`, `solid_errors:install`, `solid_cache:install`, `solid_cable:install`, `maquina_components:install`, then `maquina:security` (which installs the `maquina:rack_attack` rules), `maquina:passkeys` with `--passkeys`, and `maquina:oauth` plus `maquina:mcp` with `--mcp`
 13. Restores custom layouts overwritten by gem installers
 14. Configures multi-database `database.yml` (primary, queue, cache, cable, errors, security)
 15. Creates a HomeController with root route
@@ -436,6 +612,9 @@ Watch the Security page while the policy is report-only, then set `content_secur
 rails g maquina:app
 rails g maquina:app --prefix /backstage --port 3100
 rails g maquina:app --auth registration
+rails g maquina:app --auth clave --passkeys
+rails g maquina:app --auth clave --mcp
+rails g maquina:app --auth clave --mcp --mcp-flag beta_mcp
 ```
 
 #### Options
@@ -443,11 +622,14 @@ rails g maquina:app --auth registration
 - `--prefix` (default: `/admin`) -- Base path prefix for backstage tools (Solid Errors, Mission Control Jobs, Security)
 - `--port` (default: `3000`) -- Default port for the development server
 - `--auth` (default: `none`) -- Authentication type: `none`, `clave`, or `registration`
+- `--passkeys` (default: `false`) -- Adds passkey sign-in with `maquina:passkeys`. It needs `--auth clave` and refuses to run without it. The passkey origin follows `--port`, and the home page links to `/passkeys`.
+- `--mcp` (default: `false`) -- Adds the OAuth-backed MCP server with `maquina:oauth` and `maquina:mcp`, after Security and Passkeys so the Rack::Attack rules and the admin tools from the other generators land. It needs `--auth clave` and refuses to run without it. The README and post-install message point to `/settings/connected_apps` and the MCP Inspector.
+- `--mcp-flag NAME` -- Passed to both as `--flag NAME`, to gate MCP access behind a feature flag.
 
 #### After running
 
 ```bash
-bin/rails credentials:edit                # set backstage username/password
+bin/rails credentials:edit                # --auth clave: backstage.emails; otherwise backstage username/password
 bin/dev
 ```
 

data/Rakefile

@@ -4,7 +4,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/tmp/**/*")
 end
 
 task default: :test

data/lib/generators/maquina/app/USAGE

@@ -9,3 +9,9 @@ Examples:
   rails g maquina:app
 
   rails g maquina:app --prefix /backstage --port 3100
+
+  rails g maquina:app --auth clave --passkeys
+
+  rails g maquina:app --auth clave --mcp
+
+  rails g maquina:app --auth clave --mcp --mcp-flag beta_mcp

data/lib/generators/maquina/app/app_generator.rb

@@ -11,6 +11,20 @@ module Maquina
         desc: "Default port for development server"
       class_option :auth, type: :string, default: "none",
         desc: "Authentication type: none, clave, or registration"
+      class_option :passkeys, type: :boolean, default: false,
+        desc: "Add passkey sign-in on top of clave (requires --auth clave)"
+      class_option :mcp, type: :boolean, default: false,
+        desc: "Add an OAuth-backed MCP server on top of clave (requires --auth clave)"
+      class_option :mcp_flag, type: :string,
+        desc: "Feature flag that gates MCP access (e.g. beta_mcp)"
+
+      # 0. Check options before touching anything
+      def check_options
+        return if options[:auth] == "clave"
+
+        raise Thor::Error, "--passkeys builds on clave. Run with `--auth clave --passkeys`." if options[:passkeys]
+        raise Thor::Error, "--mcp builds on clave. Run with `--auth clave --mcp`." if options[:mcp]
+      end
 
       # 1. Add gems
       def add_gems
@@ -215,6 +229,34 @@ module Maquina
         generate "maquina:security", "--prefix", options[:prefix], "--quiet"
       end
 
+      # 12b. Install passkeys (after security, so its Rack::Attack throttle lands)
+      def install_passkeys
+        return unless options[:passkeys] && rails_app?
+
+        generate "maquina:passkeys", "--quiet"
+      end
+
+      # 12c. Point the passkey origin at the development port
+      def configure_passkeys_origin
+        return unless options[:passkeys] && options[:port] != "3000"
+
+        initializer = File.join(destination_root, "config/initializers/webauthn.rb")
+        return unless File.exist?(initializer)
+
+        gsub_file "config/initializers/webauthn.rb",
+          '"http://localhost:3000"', %("http://localhost:#{options[:port]}")
+      end
+
+      # 12d. Install the MCP server (after security and passkeys, so the
+      #      Rack::Attack rules and every sibling tool marker already exist)
+      def install_mcp
+        return unless options[:mcp] && rails_app?
+
+        flag = options[:mcp_flag].to_s.empty? ? [] : ["--flag", options[:mcp_flag]]
+        generate "maquina:oauth", "--quiet", *flag
+        generate "maquina:mcp", "--quiet", *flag
+      end
+
       # 13. Restore custom layouts overwritten by gem installers
       def restore_custom_layouts
         return unless rails_app?
@@ -321,8 +363,13 @@ module Maquina
         say "Next steps:", :yellow
         say "  1. Set credentials: bin/rails credentials:edit"
         say "     backstage:"
-        say "       username: your_user"
-        say "       password: your_password"
+        if options[:auth] == "clave"
+          say "       emails:"
+          say "         - you@example.com   # who may open #{options[:prefix]} (signed in with Clave)"
+        else
+          say "       username: your_user"
+          say "       password: your_password"
+        end
         say "  2. Start the app: bin/dev"
         say ""
         say "Installed components:", :yellow
@@ -339,6 +386,16 @@ module Maquina
           say "  - Visit /session/new to sign in"
           say "  - Visit /registrations/new to sign up" if options[:auth] == "registration"
           say "  - Visit /registration/new to sign up" if options[:auth] == "clave"
+          if options[:passkeys]
+            say "  - Visit /passkeys to add a passkey"
+            say "  - Production: set WEBAUTHN_RP_ID and WEBAUTHN_ORIGINS before the first passkey"
+          end
+          if options[:mcp]
+            say "  - Visit /settings/connected_apps to see and revoke connected AI apps"
+            say "  - Connect an MCP client: npx @modelcontextprotocol/inspector"
+            say "    and point it at http://localhost:#{options[:port]}/mcp"
+            say "  - MCP access is gated by the #{options[:mcp_flag]} flag (app/models/mcp.rb)" unless options[:mcp_flag].to_s.empty?
+          end
           say "  - Customize: app/controllers/concerns/authentication.rb"
           say "  - Locales: config/locales/"
         end

data/lib/generators/maquina/app/templates/README.md.erb

@@ -26,6 +26,12 @@ Your app will be running at **http://localhost:<%= options[:port] %>**.
 <% if options[:auth] != "none" -%>
 | **Authentication** | <%= options[:auth] == "clave" ? "Clave passwordless email-code authentication" : "Registration-based email/password authentication" %> |
 <% end -%>
+<% if options[:passkeys] -%>
+| **Passkeys** | Passkey sign-in with Face ID, a fingerprint or a device PIN; the email code stays as the way in without one |
+<% end -%>
+<% if options[:mcp] -%>
+| **MCP Server** | OAuth 2.1-backed MCP server at `/mcp` for AI clients, with a Connected apps page to revoke them<%= " (gated by the `#{options[:mcp_flag]}` flag)" unless options[:mcp_flag].to_s.empty? %> |
+<% end -%>
 | **Background Jobs** | Solid Queue with Mission Control Jobs dashboard |
 | **Error Tracking** | Solid Errors with custom UI |
 | **Rate Limiting** | Rack::Attack with sensible defaults |
@@ -52,6 +58,13 @@ Your app will be running at **http://localhost:<%= options[:port] %>**.
 <% elsif options[:auth] == "clave" -%>
 | http://localhost:<%= options[:port] %>/registration/new | Sign up |
 <% end -%>
+<% if options[:passkeys] -%>
+| http://localhost:<%= options[:port] %>/passkeys | Passkeys |
+<% end -%>
+<% if options[:mcp] -%>
+| http://localhost:<%= options[:port] %>/settings/connected_apps | Connected apps |
+| http://localhost:<%= options[:port] %>/mcp | MCP endpoint (`npx @modelcontextprotocol/inspector`) |
+<% end -%>
 <% end -%>
 
 ## Scripts
@@ -67,6 +80,19 @@ Edit credentials with:
 bin/rails credentials:edit
 ```
 
+<% if options[:auth] == "clave" -%>
+The admin dashboards (overview, errors, jobs, security) are behind the app's sign-in. List who may open them; anyone else gets a 404:
+
+```yaml
+backstage:
+  emails:
+    - you@example.com
+```
+<% if options[:mcp] -%>
+
+The same list decides who sees the admin-only MCP tools (errors, jobs, security).
+<% end -%>
+<% else -%>
 Add backstage credentials for the admin dashboards (overview, errors, jobs, security):
 
 ```yaml
@@ -74,6 +100,7 @@ backstage:
   username: your_user
   password: your_password
 ```
+<% end -%>
 
 ## Maquina Ecosystem
 

data/lib/generators/maquina/app/templates/app/views/home/index.html.erb

@@ -15,6 +15,9 @@
         <p class="text-sm text-muted-foreground">
           Signed in as <span class="font-medium text-foreground"><%%= Current.user.email_address %></span>
         </p>
+<% if options[:passkeys] -%>
+        <%%= link_to "Passkeys", passkeys_path, data: { component: "button", variant: "outline", size: "sm" } %>
+<% end -%>
         <%%= button_to t(".sign_out", default: "Sign Out"), session_path, method: :delete, data: { component: "button", variant: "outline", size: "sm" } %>
       </div>
     <%% else %>
@@ -62,7 +65,7 @@
       <%%= render "components/card" do %>
         <%%= render "components/card/header" do %>
           <div class="flex items-center gap-2">
-            <%%= icon_for(:slash, class: "size-5 text-primary") %>
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-5 text-primary" aria-hidden="true"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/></svg>
             <%%= render "components/card/title", text: "Security" %>
           </div>
           <%%= render "components/card/description", text: "See what Rack::Attack throttled, blocked, and banned this week." %>