mcp-auth 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46fb4e82f6f75e231441aacd12e4adfdfa14efffa64556ca4325f7ad3096eb1d
-  data.tar.gz: 6e9ba1314e2823c309651b5dae0c3ea1efda7e8140fe6266a4204603eab9b816
+  metadata.gz: 52bce21e865d693725a8cf69feb1fcb72d875e12e947b6b0cb174ffdb6c7c400
+  data.tar.gz: 142b04126e331eaafd075b71c6eb3aeccac11177cd38adca070a72dd09aa56bd
 SHA512:
-  metadata.gz: c1326ad826abb70c5f888595aec6d47a2083857c98e9fd167af76d6c253fa4432430748be7b399fd902db4806bbf80df3169247e915be7bea6ba6682d5903bee
-  data.tar.gz: b4d29c3b89881f5e2585342e5b0d20b6aaea2a9a3c5396d1752bc32fb16ae7677b37bb5f1898ca7e66330a9b02c7fdd84f508deff2196808629a63af18369bb2
+  metadata.gz: 493830d702b4331373da5afd18a037c1113ec773f7d19ce7e9bdb68d784dc2168f1d643c924f159fc22804cd1ec8f2ec6c30a9c7f1eaa80f88018c133f10a56d
+  data.tar.gz: 9454e6a60a2d69cf48bb43412553710fd5cfd7b150b14162c7b1782170c7dd0cf1fac76d59ac8fe786245bc463c5918e4408eb99ca6a45608b100c5cbe23c12e

data/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-29
+
+Security-hardening release. Closes four OAuth correctness bugs and adds the
+resource-server half of the MCP authorization spec.
+
+### Security (breaking where noted)
+- **Authorization endpoint now validates `redirect_uri`** against the client's
+  registered URIs (RFC 6749 §3.1.2.3) and rejects unknown `client_id`s. An
+  unregistered/mismatched `redirect_uri` is answered with an error and is never
+  redirected to. **Breaking:** flows that relied on unvalidated redirect URIs
+  will now be rejected — register every redirect URI.
+- **Access-token revocation now takes effect.** `validate_access_token` checks
+  that the stored token row still exists, so `POST /oauth/revoke` and an
+  expired/destroyed row immediately invalidate the JWT instead of it remaining
+  valid until natural expiry. Introspection reflects this too.
+- **Token endpoint binds the authorization code to the client** (RFC 6749
+  §4.1.3): the requesting `client_id` (Basic auth or body) must match the code.
+- **Audience binding honors `mcp_server_path`.** The default token `aud` is now
+  `base_url + mcp_server_path`, matching the published protected-resource
+  metadata (previously hard-coded to `/mcp`, breaking RFC 8707 on custom paths).
+- **Audience matching is exact**, no longer a string prefix (which let
+  `https://api.example.com.evil.com` match `https://api.example.com`).
+- HTTPS is now enforced on `register`, `revoke`, `introspect`, and `userinfo`
+  (in addition to `authorize`/`token`), except in dev/test/local.
+
+### Added
+- **`Mcp::Auth::ProtectedResource`** controller concern — validates the incoming
+  Bearer token on your MCP endpoint, exposes the principal via
+  `Mcp::Auth::ControllerHelpers` (`mcp_user_id`, `mcp_scope`, …), and answers
+  401 with the RFC 9728 `WWW-Authenticate: Bearer … resource_metadata="…"`
+  header the MCP spec requires. Includes `require_mcp_scope!` for per-action
+  scope enforcement.
+- **OpenID Connect id_token issuance** — when the `openid` scope is granted, the
+  token response includes an `id_token` (with `email`/`profile` claims gated by
+  scope), making the advertised OIDC discovery real.
+- **Signing-key rotation** — `token_signing_additional_public_keys` accepts extra
+  public keys that are honored for verification and published in JWKS, so a key
+  roll doesn't invalidate outstanding tokens. `TokenService.reset_signing_keys!`
+  clears the in-process key cache.
+- Refresh grant supports **scope narrowing** (RFC 6749 §6) and the wired-up
+  `current_user_method` config option.
+- Dynamic client registration now validates redirect URIs (RFC 7591/8252),
+  rejecting empty sets and dangerous schemes (`javascript:`/`data:`).
+
+### Changed
+- Refresh-token rotation and authorization-code consumption now happen *before*
+  new tokens are minted, so a replayed code/refresh token can't double-issue.
+- `store_access_token` failures now propagate instead of silently handing the
+  client an unrevocable token.
+- `none` removed from advertised revocation/introspection auth methods (those
+  endpoints require client authentication).
+- Migration template for `mcp_auth_oauth_clients` uses a portable `string`
+  primary key instead of Postgres-only `uuid`/`gen_random_uuid()`.
+
+### Migration
+
+Mostly drop-in. Two things to check:
+1. Ensure all OAuth clients have their `redirect_uris` registered — the
+   authorization endpoint now enforces them.
+2. To protect your MCP endpoint, include the new concern:
+   ```ruby
+   class McpController < ApplicationController
+     include Mcp::Auth::ProtectedResource
+     before_action :authenticate_mcp_token!
+   end
+   ```
+
 ## [0.3.0] - 2026-05-25
 
 ### Added

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

@@ -6,17 +6,17 @@ module Mcp
       skip_before_action :verify_authenticity_token, only: %i[token register revoke introspect userinfo]
       before_action :set_cors_headers
       before_action :handle_options_request
-      before_action :require_https, only: %i[authorize token]
+      before_action :require_https, only: %i[authorize approve token register revoke introspect userinfo]
 
       # OAuth 2.1 Authorization endpoint (GET/POST)
       def authorize
-        Rails.logger.info "[OAuth] Authorization request: #{params.inspect}"
+        Rails.logger.info "[OAuth] Authorization request for client=#{params[:client_id]} scope=#{params[:scope]}"
 
         unless valid_authorization_params?
           return render_error('invalid_request', 'Missing or invalid required parameters')
         end
 
-        if user_signed_in?
+        if mcp_user_signed_in?
           handle_signed_in_user
         else
           redirect_to_login
@@ -25,13 +25,9 @@ module Mcp
 
       # Consent approval endpoint
       def approve
-        unless user_signed_in?
-          return redirect_to main_app.new_user_session_path
-        end
+        return redirect_to main_app.new_user_session_path unless mcp_user_signed_in?
 
-        unless valid_authorization_params?
-          return render_error('invalid_request', 'Missing required parameters')
-        end
+        return render_error('invalid_request', 'Missing required parameters') unless valid_authorization_params?
 
         if params[:approved] == 'true'
           # Get selected scopes from checkboxes
@@ -41,7 +37,7 @@ module Mcp
 
           # Validate selected scopes
           if selected_scopes.blank?
-            Rails.logger.warn "[OAuth] No scopes selected"
+            Rails.logger.warn '[OAuth] No scopes selected'
             return render_error('invalid_request', 'At least one scope must be selected')
           end
 
@@ -58,8 +54,15 @@ module Mcp
             return render_error('invalid_request', 'Required scopes must be selected')
           end
           approved_scopes = Mcp::Auth::ScopeRegistry.validate_scopes(selected_scopes)
+
+          # Preserve standard OpenID Connect scopes that were originally requested.
+          # They gate identity claims (already governed by the userinfo/id_token
+          # endpoints) rather than application resources, so they are not rendered
+          # as individual consent checkboxes but must survive the approval step.
+          oidc_scopes = requested_scopes & Mcp::Auth::ScopeRegistry::STANDARD_OIDC_SCOPES
+          approved_scope_string = (approved_scopes + oidc_scopes).uniq.join(' ')
+
           # Generate authorization code with ONLY approved scopes
-          approved_scope_string = approved_scopes.join(' ')
           generate_and_redirect_with_code(approved_scope_string)
         else
           redirect_with_error('access_denied', 'User denied the request')
@@ -80,7 +83,7 @@ module Mcp
 
       # RFC 7591: Dynamic Client Registration
       def register
-        Rails.logger.info "[OAuth] Client registration request"
+        Rails.logger.info '[OAuth] Client registration request'
 
         begin
           client_data = build_client_registration
@@ -107,9 +110,7 @@ module Mcp
         return render_error('invalid_client', 'Client authentication failed', status: :unauthorized) unless client
 
         token = params[:token]
-        if token.blank?
-          return render_error('invalid_request', 'Token parameter is required')
-        end
+        return render_error('invalid_request', 'Token parameter is required') if token.blank?
 
         revoked = revoke_token_for_client(token, client, hint: params[:token_type_hint])
 
@@ -126,9 +127,7 @@ module Mcp
         return render_error('invalid_client', 'Client authentication failed', status: :unauthorized) unless client
 
         token = params[:token]
-        if token.blank?
-          return render json: { active: false }, content_type: 'application/json'
-        end
+        return render json: { active: false }, content_type: 'application/json' if token.blank?
 
         response = introspect_token_for_client(token, client)
         render json: response, content_type: 'application/json'
@@ -138,16 +137,12 @@ module Mcp
       def userinfo
         auth_header = request.headers['Authorization']
 
-        unless auth_header&.start_with?('Bearer ')
-          return render json: { error: 'invalid_token' }, status: :unauthorized
-        end
+        return render json: { error: 'invalid_token' }, status: :unauthorized unless auth_header&.start_with?('Bearer ')
 
         token = auth_header.split(' ', 2).last
         payload = Services::TokenService.validate_access_token(token)
 
-        unless payload
-          return render json: { error: 'invalid_token' }, status: :unauthorized
-        end
+        return render json: { error: 'invalid_token' }, status: :unauthorized unless payload
 
         user_info = {
           sub: payload[:sub],
@@ -170,7 +165,32 @@ module Mcp
           params[:client_id].present? &&
           params[:redirect_uri].present? &&
           params[:code_challenge].present? &&
-          params[:code_challenge_method] == 'S256'
+          params[:code_challenge_method] == 'S256' &&
+          registered_client_with_valid_redirect?
+      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
+      # validated BEFORE the code is ever issued — and on failure we render an
+      # error instead of redirecting (we must never redirect to an unverified URI).
+      def registered_client_with_valid_redirect?
+        client = oauth_client
+        unless client
+          Rails.logger.warn "[OAuth] Unknown client_id: #{params[:client_id]}"
+          return false
+        end
+
+        return true if client.valid_redirect_uri?(params[:redirect_uri])
+
+        Rails.logger.warn "[OAuth] Unregistered redirect_uri for client=#{params[:client_id]}: #{params[:redirect_uri]}"
+        false
+      end
+
+      def oauth_client
+        return @oauth_client if defined?(@oauth_client)
+
+        @oauth_client = Mcp::Auth::OauthClient.find_by(client_id: params[:client_id])
       end
 
       # === Authorization Flow ===
@@ -203,13 +223,11 @@ module Mcp
         # Pass the params with approved scope to authorization service
         code = Services::AuthorizationService.generate_authorization_code(
           auth_params,
-          user: current_user,
+          user: mcp_current_user,
           org: current_org
         )
 
-        unless code
-          return render_error('server_error', 'Failed to generate authorization code')
-        end
+        return render_error('server_error', 'Failed to generate authorization code') unless code
 
         redirect_with_code(code)
       end
@@ -240,8 +258,13 @@ module Mcp
       def handle_authorization_code_grant
         code_data = Services::AuthorizationService.validate_authorization_code(params[:code])
 
-        unless code_data
-          return render_error('invalid_grant', 'Authorization code is invalid or expired')
+        return render_error('invalid_grant', 'Authorization code is invalid or expired') unless code_data
+
+        # 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]
+          return render_error('invalid_grant', 'Authorization code was issued to a different client')
         end
 
         # Validate PKCE
@@ -257,39 +280,64 @@ 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])
+
         # Generate tokens with the APPROVED scope from authorization code
         token_data = code_data.merge(resource: code_data[:resource] || params[:resource])
         token_response = Services::TokenService.generate_token_response(
-          token_data,  # This includes the approved :scope from authorization code
+          token_data, # This includes the approved :scope from authorization code
           base_url: request.base_url
         )
 
-        # Consume authorization code (one-time use)
-        Services::AuthorizationService.consume_authorization_code(params[:code])
-
         render json: token_response, content_type: 'application/json'
+      rescue StandardError => e
+        Rails.logger.error "[OAuth] Token generation failed: #{e.message}"
+        render_error('server_error', 'Failed to issue tokens', status: :internal_server_error)
       end
 
       def handle_refresh_token_grant
         token_data = Services::TokenService.validate_refresh_token(params[:refresh_token])
 
-        unless token_data
-          return render_error('invalid_grant', 'Refresh token is invalid or expired')
-        end
+        return render_error('invalid_grant', 'Refresh token is invalid or expired') unless token_data
+
+        # 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?
 
         # Include resource parameter if provided
         token_data[:resource] = params[:resource] if params[:resource]
 
+        # Rotate refresh token (OAuth 2.1 requirement) BEFORE issuing the new one
+        # so a replayed refresh token cannot mint a second token family.
+        Services::TokenService.revoke_refresh_token(params[:refresh_token])
+
         # Generate new tokens
         token_response = Services::TokenService.generate_token_response(
           token_data,
           base_url: request.base_url
         )
 
-        # Rotate refresh token (OAuth 2.1 requirement)
-        Services::TokenService.revoke_refresh_token(params[:refresh_token])
-
         render json: token_response, content_type: 'application/json'
+      rescue StandardError => e
+        Rails.logger.error "[OAuth] Token refresh failed: #{e.message}"
+        render_error('server_error', 'Failed to issue tokens', status: :internal_server_error)
+      end
+
+      # Intersection of the originally granted scope and a requested subset.
+      def narrow_scope(granted_scope, requested_scope)
+        granted = granted_scope.to_s.split
+        requested = requested_scope.to_s.split
+        (granted & requested).join(' ')
+      end
+
+      # client_id of the party making a token request: HTTP Basic auth wins for
+      # confidential clients, otherwise the public client_id parameter.
+      def requesting_client_id
+        basic_id, = extract_client_credentials_from_basic
+        basic_id.presence || params[:client_id]
       end
 
       # === Client Registration ===
@@ -342,12 +390,21 @@ module Mcp
       end
 
       def extract_client_credentials
-        if (auth = request.authorization) && auth.start_with?('Basic ')
-          decoded = Base64.decode64(auth.split(' ', 2).last)
-          decoded.split(':', 2)
-        else
-          [params[:client_id], params[:client_secret]]
-        end
+        basic_id, basic_secret = extract_client_credentials_from_basic
+        return [basic_id, basic_secret] if basic_id.present?
+
+        [params[:client_id], params[:client_secret]]
+      end
+
+      # Returns [client_id, client_secret] from an HTTP Basic Authorization
+      # header, or [nil, nil] when the header is absent/not Basic.
+      def extract_client_credentials_from_basic
+        auth = request.authorization
+        return [nil, nil] unless auth&.start_with?('Basic ')
+
+        decoded = Base64.decode64(auth.split(' ', 2).last)
+        id, secret = decoded.split(':', 2)
+        [id, secret]
       end
 
       # RFC 7009: revoke token only if it belongs to the requesting client.
@@ -438,13 +495,13 @@ module Mcp
         config = Rails.application.config.mcp_auth
         config.use_custom_consent_view &&
           template_exists?(config.consent_view_path)
-      rescue
+      rescue StandardError
         false
       end
 
       def template_exists?(path)
         lookup_context.exists?(path, [], false)
-      rescue
+      rescue StandardError
         false
       end
 
@@ -465,7 +522,7 @@ module Mcp
         if Mcp::Auth.configuration.validate_scope_for_user
           all_available = all_available.select do |scope|
             Mcp::Auth.configuration.validate_scope_for_user.call(
-              current_user,
+              mcp_current_user,
               current_org,
               scope
             )
@@ -507,7 +564,7 @@ module Mcp
       end
 
       def require_https
-        return if request.ssl? || request.local? || Rails.env.development?
+        return if request.ssl? || request.local? || Rails.env.local?
 
         render_error('invalid_request', 'HTTPS required')
       end
@@ -529,6 +586,22 @@ module Mcp
         render json: error_response, status: status, content_type: 'application/json'
       end
 
+      # Resolve the signed-in user via the configured `current_user_method`
+      # (defaults to :current_user). Accepts either a symbol naming a method on
+      # the host ApplicationController or a proc evaluated in this context.
+      def mcp_current_user
+        method_name = Mcp::Auth.configuration&.current_user_method || :current_user
+        return instance_exec(&method_name) if method_name.respond_to?(:call)
+
+        send(method_name) if respond_to?(method_name, true)
+      rescue NoMethodError
+        nil
+      end
+
+      def mcp_user_signed_in?
+        mcp_current_user.present?
+      end
+
       def current_org
         # If current_org_method is nil in config, always return nil
         return nil if Mcp::Auth.configuration.current_org_method.nil?

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

@@ -51,9 +51,10 @@ module Mcp
           require_pushed_authorization_requests: false,
           require_signed_request_object: false,
 
-          # Token revocation and introspection
-          revocation_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post none],
-          introspection_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post none]
+          # Token revocation and introspection require client authentication
+          # (RFC 7009 §2.1 / RFC 7662 §2.1) — `none` is intentionally not offered.
+          revocation_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post],
+          introspection_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post]
         }
 
         render json: metadata, status: :ok, content_type: 'application/json'
@@ -88,8 +89,7 @@ module Mcp
       # configured signing algorithm is asymmetric (RS256/ES256). HMAC keys
       # are NEVER published — for HS256 this stays an empty key set.
       def jwks
-        jwk = Mcp::Auth::Services::TokenService.signing_jwk_export
-        keys = jwk ? [jwk] : []
+        keys = Mcp::Auth::Services::TokenService.signing_jwks_export
         render json: { keys: keys }, status: :ok, content_type: 'application/json'
       end
 

data/app/models/mcp/auth/access_token.rb

@@ -1,12 +1,14 @@
+# frozen_string_literal: true
+
 module Mcp
   module Auth
     class AccessToken < ActiveRecord::Base
-      self.table_name = "mcp_auth_access_tokens"
+      self.table_name = 'mcp_auth_access_tokens'
 
       belongs_to :user
       belongs_to :org, optional: true
       belongs_to :oauth_client,
-                 class_name: "Mcp::Auth::OauthClient",
+                 class_name: 'Mcp::Auth::OauthClient',
                  foreign_key: :client_id,
                  primary_key: :client_id,
                  optional: true

data/app/models/mcp/auth/oauth_client.rb

@@ -3,33 +3,34 @@
 module Mcp
   module Auth
     class OauthClient < ActiveRecord::Base
-      self.table_name = "mcp_auth_oauth_clients"
-      self.primary_key = "client_id"
+      self.table_name = 'mcp_auth_oauth_clients'
+      self.primary_key = 'client_id'
 
       # Set defaults BEFORE validation
       before_validation :set_defaults, on: :create
 
       validates :client_id, presence: true, uniqueness: true
       validates :client_secret, presence: true
+      validate :validate_redirect_uris
 
       serialize :redirect_uris, coder: JSON
       serialize :grant_types, coder: JSON
       serialize :response_types, coder: JSON
 
       has_many :authorization_codes,
-               class_name: "Mcp::Auth::AuthorizationCode",
+               class_name: 'Mcp::Auth::AuthorizationCode',
                foreign_key: :client_id,
                primary_key: :client_id,
                dependent: :destroy
 
       has_many :access_tokens,
-               class_name: "Mcp::Auth::AccessToken",
+               class_name: 'Mcp::Auth::AccessToken',
                foreign_key: :client_id,
                primary_key: :client_id,
                dependent: :destroy
 
       has_many :refresh_tokens,
-               class_name: "Mcp::Auth::RefreshToken",
+               class_name: 'Mcp::Auth::RefreshToken',
                foreign_key: :client_id,
                primary_key: :client_id,
                dependent: :destroy
@@ -55,6 +56,34 @@ module Mcp
         self.response_types ||= %w[code]
         self.scope ||= Mcp::Auth::ScopeRegistry.default_scope_string
       end
+
+      # RFC 7591 / RFC 8252: a client using the authorization_code grant must
+      # register at least one redirect URI, and each must be an absolute URI.
+      # We reject scheme-only values (e.g. `javascript:`/`data:`) that would be
+      # XSS-redirect vectors, while still allowing http(s) and native app schemes.
+      def validate_redirect_uris
+        return unless Array(grant_types).include?('authorization_code')
+
+        uris = Array(redirect_uris)
+        if uris.empty?
+          errors.add(:redirect_uris, 'must include at least one redirect URI')
+          return
+        end
+
+        uris.each do |uri|
+          errors.add(:redirect_uris, "contains an invalid redirect URI: #{uri}") unless valid_redirect_uri_format?(uri)
+        end
+      end
+
+      def valid_redirect_uri_format?(uri)
+        parsed = URI.parse(uri.to_s)
+        return true if parsed.is_a?(URI::HTTP) && parsed.host.present? # http(s) with host
+        return true if parsed.scheme.present? && uri.to_s.include?('://') # native app scheme
+
+        false
+      rescue URI::InvalidURIError
+        false
+      end
     end
   end
-end
+end

data/lib/generators/mcp/auth/templates/create_oauth_clients.rb.erb

@@ -1,7 +1,11 @@
 class CreateMcpAuthOauthClients < ActiveRecord::Migration<%= migration_version %>
   def up
+    # client_id is a string primary key (the model generates a UUID via
+    # SecureRandom.uuid in a before_validation hook). Using :string instead of
+    # the Postgres-only :uuid / gen_random_uuid() keeps the gem portable across
+    # SQLite, MySQL, and Postgres.
     create_table :mcp_auth_oauth_clients, id: false do |t|
-      t.uuid :client_id, primary_key: true, null: false, default: -> { 'gen_random_uuid()' }
+      t.string :client_id, primary_key: true, null: false
       t.string :client_secret, null: false
       t.text :redirect_uris
       t.text :grant_types

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

@@ -193,6 +193,38 @@ Mcp::Auth.configure do |config|
   #    - @authorization_params: Hash of OAuth parameters to preserve
 end
 
+  # ============================================================================
+  # JWT SIGNING (OPTIONAL)
+  # ============================================================================
+  #
+  # By default tokens are signed with HS256 using `oauth_secret`. To use
+  # asymmetric signing (recommended when token consumers should verify without
+  # the shared secret), set an algorithm and provide PEM-encoded keys:
+  #
+  # config.token_signing_algorithm = 'RS256' # or 'ES256'
+  # config.token_signing_private_key = ENV.fetch('MCP_JWT_PRIVATE_KEY')
+  # config.token_signing_public_key  = ENV['MCP_JWT_PUBLIC_KEY'] # optional; derived if omitted
+  # config.token_signing_kid         = 'main-2026' # optional explicit JWK key id
+  #
+  # Key rotation: list the previous public key(s) here so already-issued tokens
+  # keep verifying and both keys are published at /.well-known/jwks.json:
+  # config.token_signing_additional_public_keys = [ENV['MCP_JWT_PREVIOUS_PUBLIC_KEY']]
+
+# ============================================================================
+# PROTECTING YOUR MCP ENDPOINT (RESOURCE SERVER)
+# ============================================================================
+#
+# Include the resource-server concern in the controller that serves your MCP
+# endpoint. It validates the Bearer access token, exposes the principal via
+# mcp_user_id / mcp_scope / mcp_email, and returns a spec-compliant 401 with a
+# WWW-Authenticate header pointing at the protected-resource metadata.
+#
+#   class McpController < ApplicationController
+#     include Mcp::Auth::ProtectedResource
+#     before_action :authenticate_mcp_token!
+#     before_action -> { require_mcp_scope!('mcp:read') }, only: :show
+#   end
+
 # Include controller helpers in ApplicationController
 Rails.application.config.to_prepare do
   ApplicationController.include Mcp::Auth::ControllerHelpers

data/lib/mcp/auth/protected_resource.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Mcp
+  module Auth
+    # Resource-server side of the MCP authorization spec. Include this in the
+    # controller that serves your MCP endpoint to validate the incoming Bearer
+    # token and expose the authenticated principal via Mcp::Auth::ControllerHelpers
+    # (mcp_user_id, mcp_scope, ...).
+    #
+    #   class McpController < ApplicationController
+    #     include Mcp::Auth::ProtectedResource
+    #     before_action :authenticate_mcp_token!
+    #     before_action -> { require_mcp_scope!('mcp:read') }, only: :show
+    #   end
+    #
+    # On a missing/invalid/expired token it answers 401 with the RFC 9728
+    # WWW-Authenticate header so MCP clients can discover the authorization
+    # server from the protected-resource metadata.
+    module ProtectedResource
+      extend ActiveSupport::Concern
+      include Mcp::Auth::ControllerHelpers
+
+      # Validates the Bearer access token (signature, expiry, revocation status,
+      # and — when a resource is configured — the RFC 8707 audience). On success
+      # the decoded claims are stashed in request.env for ControllerHelpers and
+      # the payload is returned; on failure it renders 401 and halts the action.
+      def authenticate_mcp_token!
+        token = mcp_bearer_token
+        payload = token && Services::TokenService.validate_access_token(token, resource: mcp_resource_identifier)
+
+        unless payload
+          render_mcp_unauthorized('invalid_token', 'The access token is missing, invalid, or expired')
+          return false
+        end
+
+        request.env['mcp.user_id'] = payload[:sub]
+        request.env['mcp.org_id']  = payload[:org]
+        request.env['mcp.email']   = payload[:email]
+        request.env['mcp.token']   = token
+        request.env['mcp.scope']   = payload[:scope]
+        request.env['mcp.api_key'] = payload[:api_key_id]
+        payload
+      end
+
+      # Enforce that the validated token carries every given scope. Renders 403
+      # insufficient_scope and returns false when any is missing.
+      def require_mcp_scope!(*required)
+        granted = mcp_scope.to_s.split
+        missing = required.map(&:to_s) - granted
+        return true if missing.empty?
+
+        render_mcp_unauthorized(
+          'insufficient_scope',
+          "Missing required scope: #{missing.join(' ')}",
+          status: :forbidden
+        )
+        false
+      end
+
+      private
+
+      def mcp_bearer_token
+        header = request.authorization || request.headers['Authorization']
+        return nil unless header&.start_with?('Bearer ')
+
+        header.split(' ', 2).last.presence
+      end
+
+      # Canonical resource identifier for this server (base_url + mcp_server_path),
+      # matching the audience minted into access tokens.
+      def mcp_resource_identifier
+        path = Mcp::Auth.configuration&.mcp_server_path.presence || '/mcp'
+        path = "/#{path}" unless path.start_with?('/')
+        "#{request.base_url}#{path.chomp('/')}"
+      end
+
+      # RFC 9728 §5.1 / MCP authorization spec: a 401 MUST advertise the
+      # protected-resource metadata document via WWW-Authenticate so clients can
+      # bootstrap the OAuth flow.
+      def render_mcp_unauthorized(error, description, status: :unauthorized)
+        metadata_url = "#{request.base_url}/.well-known/oauth-protected-resource"
+        response.headers['WWW-Authenticate'] =
+          %(Bearer error="#{error}", error_description="#{description}", resource_metadata="#{metadata_url}")
+        render json: { error: error, error_description: description }, status: status
+      end
+    end
+  end
+end

data/lib/mcp/auth/scope_registry.rb

@@ -14,6 +14,11 @@ module Mcp
     #     required: false
     #   )
     class ScopeRegistry
+      # Standard OpenID Connect scopes. These are not application resource scopes
+      # (so they are not registered or shown as consent checkboxes) but are
+      # recognized when present so OIDC discovery/id_token issuance works.
+      STANDARD_OIDC_SCOPES = %w[openid profile email].freeze
+
       class << self
         # Custom scopes registered by the application
         def custom_scopes
@@ -72,9 +77,7 @@ module Mcp
         # Validate and filter requested scopes
         def validate_scopes(requested_scopes)
           # If no scopes requested, return all required scopes
-          if requested_scopes.blank?
-            return available_scopes.select { |_, meta| meta[:required] }.keys
-          end
+          return available_scopes.select { |_, meta| meta[:required] }.keys if requested_scopes.blank?
 
           scopes = requested_scopes.is_a?(String) ? requested_scopes.split : requested_scopes
 

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

@@ -11,24 +11,27 @@ module Mcp
             return nil if token.blank?
 
             begin
-              payload = JWT.decode(token, verification_key, true, { algorithm: signing_algorithm }).first
+              payload = decode_with_known_keys(token)
+              return nil unless payload
 
               # Check expiration manually to ensure proper handling
-              if payload['exp']
-                return nil if payload['exp'] <= Time.current.to_i
-              end
+              return nil if payload['exp'] && (payload['exp'] <= Time.current.to_i)
+
+              # Revocation check (RFC 7009): a JWT remains cryptographically valid
+              # until it expires, so a stored-and-still-present row is what makes
+              # `revoke` actually take effect. Without this, destroyed tokens would
+              # keep validating until natural expiry.
+              return nil unless Mcp::Auth::AccessToken.active.exists?(token: token)
 
               # Validate audience if resource provided (RFC 8707 compliance)
-              if resource && payload['aud'].present?
-                unless audience_matches?(payload['aud'], resource)
-                  Rails.logger.warn "[TokenService] Token audience mismatch: expected #{resource}, got #{payload['aud']}"
-                  return nil
-                end
+              if resource && payload['aud'].present? && !audience_matches?(payload['aud'], resource)
+                Rails.logger.warn "[TokenService] Token audience mismatch: expected #{resource}, got #{payload['aud']}"
+                return nil
               end
 
               payload.symbolize_keys
             rescue JWT::DecodeError, JWT::ExpiredSignature => e
-              Rails.logger.debug "[TokenService] Token validation failed: #{e.message}"
+              Rails.logger.debug { "[TokenService] Token validation failed: #{e.message}" }
               nil
             rescue StandardError => e
               Rails.logger.error "[TokenService] Token validation error: #{e.message}"
@@ -36,12 +39,31 @@ module Mcp
             end
           end
 
+          # Decode against every key we currently trust. For HS256 that is the
+          # single shared secret; for RS256/ES256 it is the active public key plus
+          # any additional public keys configured for rotation, so tokens signed
+          # with the previous key keep validating across a key roll.
+          def decode_with_known_keys(token)
+            last_error = nil
+            verification_keys.each do |key|
+              return JWT.decode(token, key, true, { algorithm: signing_algorithm }).first
+            rescue JWT::DecodeError => e
+              last_error = e
+            end
+            raise last_error if last_error
+
+            nil
+          end
+
           # Generate JWT access token with proper audience binding
           def generate_access_token(data, base_url:)
             user_data = fetch_user_data(data)
 
-            # RFC 8707: Use provided resource or default to MCP API endpoint
-            audience = normalize_resource_uri(data[:resource].presence || "#{base_url}/mcp")
+            # RFC 8707: Use provided resource or default to the configured MCP
+            # endpoint. The default MUST mirror the canonical resource published in
+            # the protected-resource metadata, which is built from mcp_server_path —
+            # otherwise audience validation breaks for any non-default path.
+            audience = normalize_resource_uri(data[:resource].presence || default_audience(base_url))
 
             # Calculate expiration time
             exp_time = data[:expires_at] ? data[:expires_at].to_i : (Time.current.to_i + token_lifetime)
@@ -124,7 +146,7 @@ module Mcp
             return false unless token_record
 
             token_record.destroy
-            Rails.logger.info "[TokenService] Refresh token revoked"
+            Rails.logger.info '[TokenService] Refresh token revoked'
             true
           end
 
@@ -141,12 +163,48 @@ module Mcp
             }
 
             response[:refresh_token] = refresh_token if refresh_token
+
+            # OpenID Connect: only issue an id_token when the `openid` scope was granted.
+            if openid_scope?(data[:scope])
+              id_token = generate_id_token(data, base_url: base_url)
+              response[:id_token] = id_token if id_token
+            end
+
             response
           rescue StandardError => e
             Rails.logger.error "[TokenService] Failed to generate token response: #{e.message}"
             raise
           end
 
+          # OpenID Connect ID Token. Audience is the client_id (not the resource),
+          # per the OIDC core spec. Only the claims permitted by the granted
+          # profile/email scopes are included.
+          def generate_id_token(data, base_url:)
+            return nil if data[:client_id].blank?
+
+            user_data = fetch_user_data(data)
+            scopes = data[:scope].to_s.split
+
+            payload = {
+              iss: base_url,
+              sub: data[:user_id].to_s,
+              aud: data[:client_id],
+              iat: Time.current.to_i,
+              exp: Time.current.to_i + token_lifetime
+            }
+            if scopes.include?('email')
+              payload[:email] = user_data[:email]
+              payload[:email_verified] = true
+            end
+            payload[:name] = user_data[:email] if scopes.include?('profile')
+
+            jwt_headers = signing_kid ? { kid: signing_kid } : {}
+            JWT.encode(payload, signing_key, signing_algorithm, jwt_headers)
+          rescue StandardError => e
+            Rails.logger.error "[TokenService] Failed to generate id_token: #{e.message}"
+            nil
+          end
+
           # Public key used to sign new JWTs. Configured via Mcp::Auth.configure;
           # built lazily so apps that stay on HS256 don't have to set anything.
           def signing_public_key
@@ -176,12 +234,60 @@ module Mcp
             exported
           end
 
+          # All public JWKs to publish at the JWKS endpoint: the active key plus
+          # any additional rotation keys. During a key roll the previous key stays
+          # listed so already-issued tokens keep verifying. Empty for HS256.
+          def signing_jwks_export
+            return [] unless asymmetric_signing?
+
+            keys = [signing_jwk_export]
+            additional_public_keys.each do |pkey|
+              additional_jwk = JWT::JWK.new(pkey)
+              exported = additional_jwk.export
+              exported[:alg] = signing_algorithm
+              exported[:use] = 'sig'
+              keys << exported
+            end
+            keys.compact
+          end
+
+          # Clears memoized key material. Call after rotating signing keys at
+          # runtime (otherwise the previously loaded keys stay cached for the
+          # life of the process).
+          def reset_signing_keys!
+            @cached_private_key = nil
+            @cached_public_key = nil
+            @jwk = nil
+          end
+
           private
 
           def asymmetric_signing?
             Mcp::Auth.configuration&.asymmetric_signing? || false
           end
 
+          # Canonical resource URI used as the default token audience, derived from
+          # the configured mcp_server_path so it matches the published metadata.
+          def default_audience(base_url)
+            path = Mcp::Auth.configuration&.mcp_server_path.presence || '/mcp'
+            path = "/#{path}" unless path.start_with?('/')
+            path = path.chomp('/')
+            "#{base_url}#{path}"
+          end
+
+          def openid_scope?(scope)
+            scope.to_s.split.include?('openid')
+          end
+
+          # Public keys accepted for verification beyond the active one (rotation).
+          def additional_public_keys
+            Array(Mcp::Auth.configuration&.token_signing_additional_public_keys).filter_map do |raw|
+              next raw if raw.is_a?(OpenSSL::PKey::PKey)
+
+              OpenSSL::PKey.read(raw) if raw.present?
+            end
+          end
+
           def signing_algorithm
             Mcp::Auth.configuration&.token_signing_algorithm || 'HS256'
           end
@@ -192,12 +298,13 @@ module Mcp
             asymmetric_signing? ? cached_private_key : oauth_secret
           end
 
-          # Key used to VERIFY incoming JWTs (HMAC secret for HS256, public key
-          # for RS256/ES256). For asymmetric algorithms callers may eventually
-          # want per-token key lookup via the JWT `kid` header, but for now we
-          # only have one active key so a single value is fine.
-          def verification_key
-            asymmetric_signing? ? cached_public_key : oauth_secret
+          # Keys used to VERIFY incoming JWTs. HS256 verifies with the single
+          # shared secret; RS256/ES256 verifies against the active public key plus
+          # any configured rotation keys.
+          def verification_keys
+            return [oauth_secret] unless asymmetric_signing?
+
+            [cached_public_key, *additional_public_keys].compact
           end
 
           def cached_private_key
@@ -260,14 +367,20 @@ module Mcp
 
           # RFC 8707: Normalize resource URI (remove trailing slash, lowercase scheme/host)
           def normalize_resource_uri(uri)
-            parsed = URI.parse(uri)
+            parsed = URI.parse(uri.to_s)
+
+            # A resource indicator must be an absolute URI with scheme + host.
+            # Anything else (relative path, mailto, garbage) is returned verbatim
+            # so callers compare it as an opaque string rather than crashing.
+            return uri.to_s if parsed.scheme.nil? || parsed.host.nil?
+
             normalized = "#{parsed.scheme.downcase}://#{parsed.host.downcase}"
             normalized += ":#{parsed.port}" if parsed.port && !default_port?(parsed)
             normalized += parsed.path.chomp('/') if parsed.path.present? && parsed.path != '/'
             normalized
-          rescue URI::InvalidURIError => e
+          rescue URI::InvalidURIError, ArgumentError => e
             Rails.logger.warn "[TokenService] Invalid resource URI: #{uri} - #{e.message}"
-            uri
+            uri.to_s
           end
 
           def default_port?(parsed_uri)
@@ -275,14 +388,16 @@ module Mcp
               (parsed_uri.scheme == 'https' && parsed_uri.port == 443)
           end
 
-          # RFC 8707: Check if token audience matches requested resource
+          # RFC 8707: Check if token audience matches requested resource.
+          # `aud` may be a single value or an array (RFC 7519 §4.1.3). Comparison
+          # is on the normalized canonical URI — NOT a string prefix, which would
+          # let `https://api.example.com.evil.com` match `https://api.example.com`.
           def audience_matches?(token_audience, resource)
-            normalized_audience = normalize_resource_uri(token_audience)
             normalized_resource = normalize_resource_uri(resource)
 
-            # Exact match or audience is a prefix of resource
-            normalized_audience == normalized_resource ||
-              normalized_resource.start_with?(normalized_audience)
+            Array(token_audience).any? do |aud|
+              normalize_resource_uri(aud) == normalized_resource
+            end
           end
 
           def store_access_token(token, data, audience)
@@ -300,7 +415,11 @@ module Mcp
             )
             Rails.logger.info "[TokenService] Access token stored for user #{data[:user_id]}"
           rescue ActiveRecord::RecordInvalid => e
+            # Validation now depends on the stored row existing, so a token we
+            # failed to persist would be useless AND unrevocable. Fail loudly
+            # instead of handing the client a dead bearer token.
             Rails.logger.error "[TokenService] Failed to store access token: #{e.message}"
+            raise
           end
 
           def fetch_user_data(data)

data/lib/mcp/auth/version.rb

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

data/lib/mcp/auth.rb

@@ -37,11 +37,15 @@ module Mcp
                     :mcp_server_path,
                     :mcp_docs_url,
                     :validate_scope_for_user,
-                    :token_signing_algorithm,
                     :token_signing_private_key,
                     :token_signing_public_key,
+                    :token_signing_additional_public_keys,
                     :token_signing_kid
 
+      # token_signing_algorithm has a validating writer defined below, so only
+      # the reader is generated here.
+      attr_reader :token_signing_algorithm
+
       def initialize
         @oauth_secret = nil
         @authorization_server_url = nil
@@ -63,6 +67,9 @@ module Mcp
         @token_signing_algorithm = 'HS256'
         @token_signing_private_key = nil
         @token_signing_public_key = nil
+        # Additional public keys (PEM strings or OpenSSL::PKey instances) accepted
+        # for verification and published in the JWKS during key rotation.
+        @token_signing_additional_public_keys = []
         @token_signing_kid = nil
       end
 
@@ -132,6 +139,8 @@ module Mcp
   end
 end
 
+# Loaded after the module body so they can reference Mcp::Auth::Configuration
+# and Mcp::Auth::ControllerHelpers defined above. The services are already
+# required at the top of this file.
 require 'mcp/auth/scope_registry'
-require 'mcp/auth/services/token_service'
-require 'mcp/auth/services/authorization_service'
+require 'mcp/auth/protected_resource'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp-auth
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Serhii Borozenets
@@ -221,6 +221,7 @@ files:
 - lib/generators/mcp/auth/templates/views/consent.html.erb
 - lib/mcp/auth.rb
 - lib/mcp/auth/engine.rb
+- lib/mcp/auth/protected_resource.rb
 - lib/mcp/auth/scope_registry.rb
 - lib/mcp/auth/services/authorization_service.rb
 - lib/mcp/auth/services/token_service.rb