mcp-auth 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52bce21e865d693725a8cf69feb1fcb72d875e12e947b6b0cb174ffdb6c7c400
-  data.tar.gz: 142b04126e331eaafd075b71c6eb3aeccac11177cd38adca070a72dd09aa56bd
+  metadata.gz: 97784aa216cd18eac56baaf9b0e9520a8a38cc9181eefb5044fe4fef5aad826a
+  data.tar.gz: c36b3baf50130e7646f46592ca937fc834dd3ba1b3ff41de43f6114fbe14af3e
 SHA512:
-  metadata.gz: 493830d702b4331373da5afd18a037c1113ec773f7d19ce7e9bdb68d784dc2168f1d643c924f159fc22804cd1ec8f2ec6c30a9c7f1eaa80f88018c133f10a56d
-  data.tar.gz: 9454e6a60a2d69cf48bb43412553710fd5cfd7b150b14162c7b1782170c7dd0cf1fac76d59ac8fe786245bc463c5918e4408eb99ca6a45608b100c5cbe23c12e
+  metadata.gz: 88be7bed04fcd81edcf6911a1e067133096d4609be7b797b649722cd43abeba4d420785a90fe4656e54f76d5301cc386a6d92f54bcbc21a517e02d60013d86b2
+  data.tar.gz: 37866607f9bab28377ef68346d42908e99bdc17c086b30527495d30df196962a93377356738fdd490c82c2f9a5914ff0660b62e70ba0f50097f6d78a50a1df2d

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -177,7 +215,9 @@ 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.5.0...HEAD
+[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

@@ -186,18 +186,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

data/app/controllers/mcp/auth/oauth_controller.rb

@@ -166,9 +166,31 @@ module Mcp
           params[:redirect_uri].present? &&
           params[:code_challenge].present? &&
           params[:code_challenge_method] == 'S256' &&
+          valid_requested_resource? &&
           registered_client_with_valid_redirect?
       end
 
+      # RFC 8707 / MCP authorization spec: if the client sends a `resource`, it
+      # MUST identify this server. A token whose audience is some other resource
+      # must never be minted, so the request is rejected here — before any code
+      # is issued — rather than silently binding the token to a foreign audience.
+      def valid_requested_resource?
+        return true if params[:resource].blank?
+
+        allowed = Services::TokenService.resource_allowed?(params[:resource], canonical_resource_identifier)
+        Rails.logger.warn "[OAuth] Rejected unknown resource indicator: #{params[:resource]}" unless allowed
+        allowed
+      end
+
+      # Canonical resource identifier this server issues/accepts tokens for
+      # (base_url + configured mcp_server_path). Mirrors the value published in
+      # the protected-resource metadata and minted into the token `aud`.
+      def canonical_resource_identifier
+        path = Mcp::Auth.configuration&.mcp_server_path.presence || '/mcp'
+        path = "/#{path}" unless path.start_with?('/')
+        "#{request.base_url}#{path.chomp('/')}"
+      end
+
       # OAuth 2.1 / RFC 6749 §3.1.2.3: the authorization endpoint MUST reject any
       # redirect_uri that is not pre-registered for the client. This is the gate
       # that prevents authorization-code interception via open redirect, so it is
@@ -195,12 +217,13 @@ module Mcp
 
       # === Authorization Flow ===
 
+      # The authorization endpoint (GET/POST /oauth/authorize) MUST NOT issue a
+      # code on its own: doing so let any client skip consent by appending
+      # `approved=true` to the authorization URL (a GET, so not even CSRF
+      # protected). Approval is an explicit, CSRF-protected POST to
+      # /oauth/approve — so here we only ever render the consent screen.
       def handle_signed_in_user
-        if params[:approved] == 'true'
-          generate_and_redirect_with_code
-        else
-          show_consent_screen
-        end
+        show_consent_screen
       end
 
       def redirect_to_login
@@ -263,10 +286,14 @@ module Mcp
         # RFC 6749 §4.1.3: the code MUST be bound to the client it was issued to.
         # The requesting client identifies itself via HTTP Basic auth (confidential
         # clients) or the client_id parameter (public clients using PKCE).
-        unless requesting_client_id.present? && requesting_client_id == code_data[:client_id]
+        unless requesting_client_owns?(code_data[:client_id])
           return render_error('invalid_grant', 'Authorization code was issued to a different client')
         end
 
+        # RFC 8707: a `resource` sent at the token endpoint (used as the audience
+        # fallback when the code carried none) must still identify this server.
+        return render_error('invalid_target', 'Invalid resource indicator') unless valid_requested_resource?
+
         # Validate PKCE
         unless Services::AuthorizationService.validate_pkce?(code_data[:code_challenge], params[:code_verifier])
           return render_error('invalid_grant', 'PKCE validation failed')
@@ -280,10 +307,13 @@ module Mcp
         # Use the APPROVED scope from the authorization code, not the original request
         Rails.logger.info "[OAuth] Token generation using scope from auth code: #{code_data[:scope]}"
 
-        # Consume the authorization code FIRST (one-time use). Doing this before
-        # token generation guarantees a replayed code can never yield a second
-        # set of tokens even if two requests race.
-        Services::AuthorizationService.consume_authorization_code(params[:code])
+        # Consume the authorization code FIRST (one-time use). consume_* deletes
+        # the row atomically and only the request that actually removed it gets a
+        # truthy result, so a replayed/raced code can never yield a second set of
+        # tokens. Abort if we did not win the consumption.
+        unless Services::AuthorizationService.consume_authorization_code(params[:code])
+          return render_error('invalid_grant', 'Authorization code is invalid or expired')
+        end
 
         # Generate tokens with the APPROVED scope from authorization code
         token_data = code_data.merge(resource: code_data[:resource] || params[:resource])
@@ -303,6 +333,17 @@ module Mcp
 
         return render_error('invalid_grant', 'Refresh token is invalid or expired') unless token_data
 
+        # OAuth 2.1 §4.3.1 / RFC 6749 §6: the authorization server MUST bind the
+        # refresh token to the client it was issued to and reject redemption by
+        # any other client. Without this a refresh token leaked to (or through) a
+        # second client could be exchanged for fresh access tokens.
+        unless requesting_client_owns?(token_data[:client_id])
+          return render_error('invalid_grant', 'Refresh token was issued to a different client')
+        end
+
+        # RFC 8707: a resource indicator, when supplied, must name this server.
+        return render_error('invalid_target', 'Invalid resource indicator') unless valid_requested_resource?
+
         # RFC 6749 §6: a client may request a NARROWER scope on refresh, never a
         # wider one. Silently dropping unknown/extra scopes preserves least privilege.
         token_data[:scope] = narrow_scope(token_data[:scope], params[:scope]) if params[:scope].present?
@@ -340,6 +381,12 @@ module Mcp
         basic_id.presence || params[:client_id]
       end
 
+      # True only when the token-requesting client identifies itself AND that
+      # identity matches the client a grant (code/refresh token) was issued to.
+      def requesting_client_owns?(client_id)
+        requesting_client_id.present? && requesting_client_id == client_id
+      end
+
       # === Client Registration ===
 
       def build_client_registration

data/lib/generators/mcp/auth/templates/initializer.rb

@@ -50,7 +50,12 @@ Mcp::Auth.configure do |config|
   # Expected return value: Hash with keys:
   #   - :email (String) - User's email address
   #   - :api_key_id (String/Integer, optional) - API key ID if using API keys
-  #   - :api_key_secret (String, optional) - API key secret if using API keys
+  #
+  # SECURITY: the access token is a bearer JWT — anyone holding it can decode
+  # its claims, and a copy is stored at rest for revocation. Only embed
+  # non-sensitive values. Return an api_key_id (an opaque reference) and look up
+  # the matching secret server-side at request time. A raw `api_key_secret`
+  # returned here is intentionally IGNORED and never written into the token.
   config.fetch_user_data = proc do |data|
     user = User.find(data[:user_id])
 
@@ -60,11 +65,10 @@ Mcp::Auth.configure do |config|
 
     {
       email: user.email,
-      api_key_id: nil,      # Set to your API key ID if applicable
-      api_key_secret: nil   # Set to your API key secret if applicable
+      api_key_id: nil      # Set to your API key ID if applicable
     }
   rescue ActiveRecord::RecordNotFound
-    { email: 'unknown@example.com', api_key_id: nil, api_key_secret: nil }
+    { email: 'unknown@example.com', api_key_id: nil }
   end
 
   # ============================================================================

data/lib/mcp/auth/services/authorization_service.rb

@@ -52,7 +52,14 @@ module Mcp
             }
           end
 
-          # Consume authorization code (one-time use)
+          # Consume authorization code (one-time use).
+          #
+          # OAuth 2.1 §4.1.2: an authorization code MUST be single-use. The
+          # delete is done as a single atomic DELETE ... WHERE that reports how
+          # many rows it removed, so when two requests race to redeem the same
+          # code exactly ONE sees `deleted == 1` and proceeds; the loser sees 0
+          # and gets nil. Returns the code's data on success, nil if the code was
+          # already consumed (or never existed).
           def consume_authorization_code(code)
             authorization_code = Mcp::Auth::AuthorizationCode.find_by(code: code)
             return nil unless authorization_code
@@ -69,8 +76,10 @@ module Mcp
               created_at: authorization_code.created_at.to_i
             }
 
-            authorization_code.destroy
-            Rails.logger.info "[AuthorizationService] Authorization code consumed"
+            deleted = Mcp::Auth::AuthorizationCode.where(id: authorization_code.id).delete_all
+            return nil unless deleted == 1
+
+            Rails.logger.info '[AuthorizationService] Authorization code consumed'
             code_data
           end
 

data/lib/mcp/auth/services/token_service.rb

@@ -76,8 +76,11 @@ module Mcp
               client_id: data[:client_id],
               email: user_data[:email],
               scope: data[:scope],
+              # Only a non-sensitive API key *identifier* is embedded. A bearer
+              # JWT is decodable by anyone holding it (and is stored at rest), so
+              # the matching secret MUST NOT be placed in the token — the resource
+              # server resolves the secret server-side from this id when needed.
               api_key_id: user_data[:api_key_id],
-              api_key_secret: user_data[:api_key_secret],
               iat: Time.current.to_i,
               exp: exp_time
             }
@@ -260,6 +263,19 @@ module Mcp
             @jwk = nil
           end
 
+          # RFC 8707 §2 / MCP authorization spec: an authorization server MUST
+          # only honor resource indicators that name a resource it actually
+          # serves. A blank resource defaults to the canonical resource, so it is
+          # allowed; otherwise the request is accepted only when the requested
+          # resource matches this server's canonical resource (normalized, never
+          # a substring match). This stops a malicious client from minting tokens
+          # whose `aud` is some other — possibly attacker-controlled — resource.
+          def resource_allowed?(resource, canonical_resource)
+            return true if resource.blank?
+
+            audience_matches?(canonical_resource, resource)
+          end
+
           private
 
           def asymmetric_signing?

data/lib/mcp/auth/version.rb

@@ -2,6 +2,6 @@
 
 module Mcp
   module Auth
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp-auth
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Serhii Borozenets