mcp-auth 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52bce21e865d693725a8cf69feb1fcb72d875e12e947b6b0cb174ffdb6c7c400
-  data.tar.gz: 142b04126e331eaafd075b71c6eb3aeccac11177cd38adca070a72dd09aa56bd
+  metadata.gz: 9fe9d6d6722194f34e61bc2b2fc1104997c41c6e54fe1d8493b556d1b2004119
+  data.tar.gz: f65dbf8e46cd6cedcdd39b2cdf963c33c165a533d0d6295f5d140bf3a6e0b4ef
 SHA512:
-  metadata.gz: 493830d702b4331373da5afd18a037c1113ec773f7d19ce7e9bdb68d784dc2168f1d643c924f159fc22804cd1ec8f2ec6c30a9c7f1eaa80f88018c133f10a56d
-  data.tar.gz: 9454e6a60a2d69cf48bb43412553710fd5cfd7b150b14162c7b1782170c7dd0cf1fac76d59ac8fe786245bc463c5918e4408eb99ca6a45608b100c5cbe23c12e
+  metadata.gz: 77d89518c11901729bc2001ce45b2e1ffb64c756fd267429b160e0fc2972c81f44261f8f4c208da3b1e3b4424efea5c752e0dd75a1c34e52866997a16b56a6a7
+  data.tar.gz: 23a62caa06957f5885433a6a4d780ebf3b85d2c1833d92a1a6583f940c35e9622a8848681cbbed2a11a05dd90f8bca74bcdbbf46b88c08e12035941e491da410

data/CHANGELOG.md

@@ -7,6 +7,257 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-28
+
+Second security-hardening round (audit follow-ups), delivered in two phases.
+Phase 1 — code-level fixes, no migration:
+
+### Security (breaking where noted)
+- **Authorization-code TTL was 30 HOURS, not 30 minutes.** The lifetime (a value
+  in seconds, e.g. `1800`) was applied with `.minutes`. Now applied as seconds,
+  and read from the single canonical config source so configured and default
+  deployments agree. **Breaking:** codes now expire in ~30 min as intended.
+- **Issuer / audience / discovery URLs are pinned to the configured origin.**
+  `iss` and all discovery/JWKS URLs derive from `authorization_server_url`, and
+  the MCP resource (token `aud`, protected-resource metadata, 401 challenge)
+  from the new `mcp_server_url`, instead of the raw request Host — closing a
+  Host/`X-Forwarded-Host` header-injection vector. The two are separate so a
+  deployment with a distinct authorization server keeps its resource on the MCP
+  host. **When unset**, each falls back to the request origin, so the host app
+  MUST restrict permitted hosts via Rails `config.hosts`.
+- **JWT validation hardened.** Access tokens now carry a `token_use` claim and an
+  id_token can no longer be replayed as an access token; decode enforces
+  `required_claims` (`iss`/`aud`/`sub`/`exp`, also checked explicitly so older
+  ruby-jwt versions that ignore that option are covered); `exp` is strict and
+  `nbf` allows a bounded clock-skew leeway;
+  a missing audience is no longer silently accepted.
+- **Confidential-client auth at the token endpoint.** A `client_secret` presented
+  on a code/refresh request is now verified (constant-time); an invalid secret is
+  rejected. (Full *requirement* of a secret for confidential clients lands with
+  the `token_endpoint_auth_method` column in Phase 2.)
+- **Refresh-token rotation is atomic.** Rotation is gated on a conditional delete,
+  so two concurrent redemptions of one refresh token can no longer each mint a
+  new token family.
+- **Consent enforces least privilege.** A client can no longer be granted a scope
+  it never requested; approved scopes are intersected with the requested set
+  (plus the server's registered required scopes). If nothing the user approved
+  was requested, the flow ends with `invalid_scope` instead of falling back to
+  the original request.
+- **A dedicated `oauth_secret` is required outside development/test.** The gem
+  no longer signs HS256 tokens with `Rails.application.secret_key_base` (key
+  separation): an unset secret, or one equal to `secret_key_base`, now raises.
+  The generated initializer no longer falls back to `secret_key_base`, and the
+  unused `MCP_OAUTH_PRIVATE_KEY` engine setting is removed. Dev/test still fall
+  back. **Breaking** — see Upgrade.
+
+Phase 2 — secrets hashed at rest (adds a migration) + medium fixes:
+
+### Security
+- **All persisted secrets are now hashed at rest.** Access-token JWTs, refresh
+  tokens, authorization codes, and client secrets are stored as SHA-256 digests
+  (prefixed `sha256$`); a database leak no longer yields usable credentials. The
+  plaintext client secret is returned exactly once at registration; tokens/codes
+  are returned once to the client and matched by digest thereafter.
+- **Dynamic Client Registration rejects unsupported grant/response types**
+  (RFC 7591 §2) instead of storing arbitrary metadata.
+- **Refresh-token reuse detection** (OAuth 2.1 §4.14.2). Rotation now marks the
+  presented token revoked (grouped by a `family_id`) instead of deleting it, so
+  an authenticated client replaying an already-rotated token is detected as theft
+  and the **entire family is revoked — both the refresh tokens and the access
+  tokens already issued to that principal** (immediate cut-off, not left valid
+  until expiry). Client authentication is checked *before* this reaction, so an
+  unauthenticated replay can't trigger family revocation. Rotation is atomic
+  (only the request that flips `revoked_at` wins), superseding the delete-based
+  race fix. The migration backfills a `family_id` for pre-existing tokens so
+  reuse detection covers them too. A configurable **rotation grace period**
+  (`refresh_token_reuse_grace_period`, default 10s) treats a rotated token
+  replayed moments later as a benign concurrent-refresh race (rejected softly,
+  family kept) rather than theft, so well-behaved MCP clients that fire several
+  refreshes when the access token expires aren't logged out.
+- **Access tokens carry a unique `jti`** (RFC 7519) so two tokens issued in the
+  same second for the same principal/scope don't collide on the unique token
+  index (which previously raised on rapid/concurrent refreshes).
+- **Confidential-client authentication is now enforced.** Clients carry a
+  `token_endpoint_auth_method`; a confidential client (`client_secret_basic` /
+  `client_secret_post`) MUST present a valid secret at the token endpoint, while
+  a public client (`none`, the default) relies on PKCE. **Existing clients
+  default to `none`, so nothing that worked before starts requiring a secret** —
+  a client opts into confidential auth explicitly at registration.
+
+- **Refresh rotation and successor issuance are one transaction.** If minting
+  the new tokens fails (or yields no refresh token), the rotation rolls back and
+  the client can retry with the token it holds, instead of being left with no
+  valid refresh token (a forced logout).
+- **`WWW-Authenticate` on a protected-resource 401 can be pinned.** The
+  `resource_metadata` URL derives from `mcp_server_url` when set, so a forged
+  Host header can't steer clients to attacker-controlled metadata.
+- **Dangerous redirect-URI schemes are rejected at registration.**
+  `javascript:`, `data:`, `vbscript:`, `file:`, `about:` and `blob:` are refused
+  even when written with `://` (e.g. `javascript://%0aalert(1)`), which the
+  native-app-scheme check previously let through.
+
+- **The per-user scope policy is enforced at approval.** `validate_scope_for_user`
+  only filtered what the consent screen showed; a user could POST a hidden scope
+  name to `/oauth/approve` and have it granted, and required scopes were re-added
+  even when the policy denied them. The policy now filters the granted set.
+- **OAuth credentials are filtered from logs.** The engine adds `code`,
+  `code_verifier`, `client_secret`, `refresh_token`, `access_token`, `id_token`
+  and `token` to `filter_parameters` (Rails' defaults miss `code` and
+  `code_verifier`), and filters redirects carrying `?code=`.
+- **Token responses are not cacheable** (RFC 6749 §5.1): `Cache-Control: no-store`
+  and `Pragma: no-cache` on token, register, introspect and userinfo.
+- **The consent page can't be framed or read cross-origin.** `X-Frame-Options:
+  DENY` and `frame-ancestors 'none'` on authorize/approve, and CORS headers are no
+  longer sent there (RFC 9700 §2.6); the other endpoints keep CORS.
+
+### Security (DCR hardening)
+- **Redirect-URI policy at registration.** Plain `http` is rejected except for
+  loopback hosts (`localhost`, `127.0.0.1`, `[::1]`, any port; RFC 8252 §7.3);
+  optional `allowed_redirect_uri_patterns` restricts registration to known
+  clients (Regexps must match the whole URI, anchored or not), and
+  `allow_loopback_redirects` can disable loopback. The policy applies to every
+  registered redirect URI regardless of grant types, and `/oauth/authorize`
+  refuses clients that didn't register the `authorization_code` grant.
+  **Breaking:** non-loopback `http://` redirect URIs no longer register.
+- **Unknown scopes are rejected** at registration (`invalid_client_metadata`) and
+  at `/oauth/authorize` (`invalid_scope` redirect, RFC 6749 §4.1.2.1) instead of
+  being stored/echoed or silently dropped. OIDC scopes and `offline_access` are
+  accepted. `strict_scope_validation = false` restores the old narrowing.
+- **`client_name` is sanitized** (control/bidi/zero-width characters stripped,
+  100-char cap) and `client_uri` must be an http(s) URL, since both are
+  attacker-chosen at open registration and shown on the consent page.
+- **Consent screen shows the redirect host** and flags applications whose host
+  isn't in `verified_redirect_hosts` as unverified (loopback is exempt).
+  **Existing installs:** the install generator copied the consent view into
+  your app (`app/views/mcp/auth/consent.html.erb`), and that copy overrides the
+  gem's, so you won't see these additions until you merge them in. Compare
+  your copy with the gem's `lib/generators/mcp/auth/templates/views/consent.html.erb`
+  (the "redirect-info" paragraph and the "Unverified application" box).
+
+### Fixed
+- The generated initializer closed the `Mcp::Auth.configure` block before the
+  JWT-signing and `secret_dual_read` sections, so uncommenting
+  `config.secret_dual_read = false` (as the upgrade generator instructs) raised
+  `NameError` at boot.
+- The secrets-hashing backfill migration processes rows in batches of 1000
+  (keyset-paginated by primary key) instead of loading each table into memory.
+- Re-enabled a dead spec file (`spec/services/authorization_service.rb` →
+  `…_spec.rb`) that RSpec never ran, restoring ~130 lines of coverage.
+- `mcp_auth:revoke_*` rake tasks now delete across the three tables inside a
+  transaction (no partial revocation on mid-way failure).
+
+### Added
+- **`config.mcp_server_url`** — public origin of the MCP resource server. Pins the
+  token audience, protected-resource metadata, and 401 `resource_metadata` URL.
+  Optional (defaults to the request origin); set it whenever
+  `authorization_server_url` points at a different host.
+- **`Mcp::Auth::ProtectedResource.www_authenticate(base_url, error:, description:)`**
+  — the RFC 9728 `WWW-Authenticate` challenge as a plain function, so a Rack
+  middleware guarding `/mcp` can emit the same header the controller concern
+  does (without it, spec-compliant MCP clients can't discover the metadata and
+  re-authorize).
+- **Pending-migration guard.** If the gem is upgraded but its migrations haven't
+  run, mcp-auth now says so instead of failing with a cryptic `unknown attribute`:
+  a clear warning is logged at boot, the OAuth endpoints return an actionable
+  `server_error` ("run a pending migration"), and `rake mcp_auth:doctor` reports
+  schema drift and exits non-zero. Fully guarded — never breaks boot, CI, or
+  `db:*` tasks when the database is absent or unmigrated.
+- **`rails generate mcp:auth:upgrade`** — copies the pending schema migration for
+  an existing install (no initializer/view overwrite prompts, unlike re-running
+  the full install generator); **`rails generate mcp:auth:hash_secrets`** copies
+  the secrets-hashing backfill, run once every server is upgraded.
+- **`config.secret_dual_read`** (default `true`) — transitional dual-read: a
+  presented secret/token/code is matched against both its digest and any legacy
+  plaintext row not yet backfilled, so 0.6.0 keeps working before and during
+  the backfill. It does NOT make older versions read hashed rows (see Upgrade).
+  Set to `false` once every row is hashed to harden.
+
+### Upgrade
+
+Two migrations, applied in **two separate steps** so no server ever sees a
+schema or data format it can't handle:
+
+- `add_mcp_auth_confidential_client_and_reuse`: **additive columns**
+  (`token_endpoint_auth_method` on clients; `family_id` + `revoked_at` on refresh
+  tokens). 0.5.0 ignores them; 0.6.0 **requires** them (its OAuth endpoints
+  return a 500 with a "run a pending migration" message until they exist).
+- `hash_mcp_auth_secrets_at_rest`: a **data backfill** that hashes existing
+  secrets in place. 0.6.0 reads both forms (`secret_dual_read`); **0.5.0 cannot
+  read hashed rows**.
+
+**Before deploying (HS256 users):** set a dedicated `MCP_HMAC_SECRET` (`rails
+secret`). Outside development/test, token signing now fails if `oauth_secret` is
+unset **or equal to `secret_key_base`**, which is exactly what initializers
+generated by earlier versions (`ENV.fetch('MCP_HMAC_SECRET', secret_key_base)`)
+fall back to. Change that line to `config.oauth_secret = ENV['MCP_HMAC_SECRET']`.
+`rake mcp_auth:doctor` and a boot-time warning report the problem. Changing the
+secret invalidates outstanding access tokens (clients refresh); refresh tokens
+are unaffected.
+
+```bash
+bundle update mcp-auth
+
+# Step 1 — schema. Run BEFORE the new code serves traffic (e.g. release phase).
+rails generate mcp:auth:upgrade
+rails db:migrate
+# ...deploy 0.6.0 to every server...
+bin/rails mcp_auth:doctor          # schema + signing-secret check
+
+# Step 2 — once NO server runs <= 0.5.0 (a later deploy is fine):
+rails generate mcp:auth:hash_secrets
+rails db:migrate
+# then: config.secret_dual_read = false
+```
+
+The backfill hashes the plaintext already present in each column, so **existing
+clients and tokens keep working without re-registration** — the client still
+presents its original value and the gem re-hashes it to match. Existing clients
+get `token_endpoint_auth_method = 'none'` (public), so none of them suddenly
+requires a secret.
+
+**During the step-1 rollout** (both versions serving), tokens and codes *issued
+by* 0.6.0 servers are stored hashed, so a 0.5.0 server can't validate them until
+it is replaced; keep that window short. After step 2, rolling back to ≤ 0.5.0
+signs every client out. The hashing backfill is idempotent and irreversible.
+
+## [0.5.0] - 2026-06-15
+
+Security-hardening release. Closes five OAuth 2.1 / MCP authorization
+vulnerabilities found in an adversarial audit of the authorization server and
+protected-resource layer. Each fix ships with an RSpec test that fails before
+and passes after.
+
+### Security (breaking where noted)
+- **Consent can no longer be bypassed.** `GET /oauth/authorize` previously issued
+  an authorization code immediately when `approved=true` was present on the
+  request URL — a GET, so not even CSRF-protected — skipping the consent screen
+  entirely. The authorization endpoint now always renders consent; a code is
+  granted only via the CSRF-protected `POST /oauth/approve`. **Breaking:** clients
+  that appended `approved=true` to the authorize URL to auto-approve must go
+  through the consent/approve step.
+- **Refresh tokens are bound to the issuing client** (OAuth 2.1 §4.3.1). The
+  refresh grant now rejects redemption unless the requesting `client_id` (Basic
+  auth or body) matches the client the token was issued to, and does not rotate
+  the token on a failed check. **Breaking:** a refresh request must include the
+  matching `client_id` — the documented flow already does.
+- **Authorization codes are consumed atomically** (OAuth 2.1 §4.1.2). Consumption
+  now deletes the code in a single atomic operation and the token grant aborts
+  unless it won that deletion, eliminating a race that could mint two token sets
+  from one code.
+- **Resource indicators are validated** (RFC 8707 / MCP authorization spec).
+  `authorize` and both token grants reject any `resource` that does not identify
+  this server (`invalid_target`), so the server can no longer mint a token whose
+  audience is some other — possibly attacker-controlled — resource. **Breaking:**
+  requests carrying a `resource` for a different host/path are rejected.
+- **`api_key_secret` is no longer embedded in access tokens.** A bearer JWT is
+  decodable by anyone holding it and is stored at rest, so only the non-sensitive
+  `api_key_id` is now included; resolve the matching secret server-side from that
+  id. Any `api_key_secret` returned by `fetch_user_data` is ignored.
+
+### Changed
+- README and the generated initializer document that `fetch_user_data` must not
+  return secrets (they are ignored and never written into the token).
+
 ## [0.4.0] - 2026-05-29
 
 Security-hardening release. Closes four OAuth correctness bugs and adds the
@@ -158,7 +409,8 @@ keep `HS256` until refresh tokens cycle out.
 - Protected Resource Metadata (RFC 9728)
 - Resource Indicators support (RFC 8707) for token audience binding
 - OpenID Connect Discovery support
-- Automatic middleware for protecting `/mcp/*` routes
+- Opt-in resource-server protection for MCP routes via the
+  `Mcp::Auth::ProtectedResource` concern
 - JWT access tokens with proper audience validation
 - Refresh token rotation for enhanced security
 - Database-backed token storage for revocation support
@@ -177,7 +429,10 @@ keep `HS256` until refresh tokens cycle out.
 - Token audience validation to prevent confused deputy attacks
 - WWW-Authenticate header with resource metadata on 401 responses
 
-[Unreleased]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/SerhiiBorozenets/mcp-auth/releases/tag/v0.1.0

data/README.md

@@ -135,6 +135,11 @@ rails generate mcp:auth:install
 rails db:migrate
 ```
 
+**Upgrading an existing install?** Don't re-run the install generator. Use
+`rails generate mcp:auth:upgrade` (schema, before deploying) and, once every
+server runs the new version, `rails generate mcp:auth:hash_secrets`. See the
+0.6.0 "Upgrade" section in [CHANGELOG.md](CHANGELOG.md) for the exact order.
+
 ## Quick Start
 
 ### 1. Mount Routes
@@ -162,12 +167,17 @@ Edit `config/initializers/mcp_auth.rb`:
 
 ```ruby
 Mcp::Auth.configure do |config|
-  # OAuth secret for JWT signing
-  config.oauth_secret = ENV.fetch('MCP_HMAC_SECRET', Rails.application.secret_key_base)
+  # OAuth secret for JWT signing (HS256) — required outside development/test,
+  # and must not be secret_key_base. Generate with `rails secret`.
+  config.oauth_secret = ENV['MCP_HMAC_SECRET']
   
   # Authorization server URL (optional - defaults to same as resource server)
   config.authorization_server_url = ENV.fetch('MCP_AUTHORIZATION_SERVER_URL', nil)
   
+  # Public origin of the MCP resource server (optional - defaults to the request
+  # origin). Pins the token audience and protected-resource metadata URLs.
+  config.mcp_server_url = ENV.fetch('MCP_SERVER_URL', nil)
+
   # MCP Server Path - where your MCP server is mounted
   # Change this if your MCP server is NOT at '/mcp'
   config.mcp_server_path = ENV.fetch('MCP_SERVER_PATH', '/mcp')
@@ -186,18 +196,22 @@ Mcp::Auth.configure do |config|
   config.authorization_code_lifetime = 1800  # 30 minutes
 
   # User data fetcher - CUSTOMIZE THIS
+  #
+  # SECURITY: only NON-sensitive values are embedded into the access token (a
+  # bearer JWT is decodable by anyone holding it and is stored at rest). Return
+  # an api_key_id (an opaque reference) and resolve the matching secret
+  # server-side from that id at request time. Never return a raw secret here —
+  # any `api_key_secret` is intentionally ignored and NOT placed in the token.
   config.fetch_user_data = proc do |data|
     user = User.find(data[:user_id])
     org = Org.find(data[:org_id]) if data[:org_id]
-    
-    # Return user data + API key (if you have one)
+
     {
       email: user.email,
-      api_key_id: org&.api_key&.id,
-      api_key_secret: org&.api_key&.secret
+      api_key_id: org&.api_key&.id
     }
   rescue ActiveRecord::RecordNotFound
-    { email: 'unknown@example.com', api_key_id: nil, api_key_secret: nil }
+    { email: 'unknown@example.com', api_key_id: nil }
   end
 
   # Methods for authentication
@@ -518,6 +532,10 @@ If you want to use a separate authorization server:
 ```ruby
 # config/initializers/mcp_auth.rb
 config.authorization_server_url = 'https://auth.example.com'
+# Public origin of THIS app's MCP endpoint (the token audience). Optional —
+# defaults to the request origin — but set it to pin the audience and metadata
+# URLs against a forged Host header.
+config.mcp_server_url = 'https://api.example.com'
 ```
 
 This is useful for: