mcp-auth 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f3afa0eeb6e176bc47801df4caf7b5298646f86c53c2607b2ac28781abe1f83
-  data.tar.gz: 0bbb349fcb1ac5b8ad142946f742a1e75bb9ebdcf11f041f2c9eaf081b8b9d5f
+  metadata.gz: 46fb4e82f6f75e231441aacd12e4adfdfa14efffa64556ca4325f7ad3096eb1d
+  data.tar.gz: 6e9ba1314e2823c309651b5dae0c3ea1efda7e8140fe6266a4204603eab9b816
 SHA512:
-  metadata.gz: b51073154b563e332913f9a08773acd618858b9a6e067ddb4145ddc73a2a5da86c830c93b75a87fc496e6c7e35ac8e064f18cd3fbabec8920fb3f17dea5a8545
-  data.tar.gz: 2f003c85cfa923ea611550c0d2c0f7a86b7c8c7e98ec1d64d2de2c25e50a295b1577209ef3cc500f0168c53135de56763580c94e946d9a6e31c16c72f77f283d
+  metadata.gz: c1326ad826abb70c5f888595aec6d47a2083857c98e9fd167af76d6c253fa4432430748be7b399fd902db4806bbf80df3169247e915be7bea6ba6682d5903bee
+  data.tar.gz: b4d29c3b89881f5e2585342e5b0d20b6aaea2a9a3c5396d1752bc32fb16ae7677b37bb5f1898ca7e66330a9b02c7fdd84f508deff2196808629a63af18369bb2

data/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-25
+
+### Added
+- **Asymmetric JWT signing** — `Mcp::Auth.configure` now accepts
+  `token_signing_algorithm` (`HS256` / `RS256` / `ES256`),
+  `token_signing_private_key` (PEM string or `OpenSSL::PKey`),
+  `token_signing_public_key` (optional — derived from the private key when
+  omitted), and `token_signing_kid` (optional explicit JWK key id;
+  auto-derived via JWT::JWK thumbprint when omitted).
+- **JWKS publication** — `/.well-known/jwks.json` now returns the active
+  public key as a JWK when an asymmetric algorithm is configured. HMAC
+  keys are never exposed; HS256 keeps returning an empty key set.
+- JWT headers now include `kid` for asymmetric algorithms, letting clients
+  pick the right verification key across rotations.
+- `id_token_signing_alg_values_supported` in OIDC discovery metadata now
+  reflects the configured algorithm instead of being hard-coded to HS256.
+- 18 new examples covering signing under each algorithm, JWKS shape, kid
+  override, and configuration validation.
+
+### Changed
+- Default signing algorithm remains `HS256` — existing setups using
+  `oauth_secret` keep working without code changes.
+- `TokenService` internals refactored so encode/decode pick the right key
+  for the configured algorithm; HMAC and asymmetric flows share one path.
+
+### Migration
+
+To switch to asymmetric signing in your host app:
+
+```ruby
+# config/initializers/mcp_auth.rb
+Mcp::Auth.configure do |c|
+  c.token_signing_algorithm  = 'RS256'                                # or 'ES256'
+  c.token_signing_private_key = ENV.fetch('MCP_TOKEN_PRIVATE_KEY')    # PEM
+  # c.token_signing_public_key  = ENV['MCP_TOKEN_PUBLIC_KEY']         # optional
+  # c.token_signing_kid          = 'main-2026-05'                     # optional
+end
+```
+
+Generate the key once (RSA 2048 or EC P-256), store the private half in
+your secrets manager / Rails credentials, and let the JWKS endpoint
+serve the public half to resource servers.
+
+Existing access tokens issued under `HS256` will no longer validate
+after the switch — plan a brief re-auth window for active clients, or
+keep `HS256` until refresh tokens cycle out.
+
+## [0.2.0] - 2026-05-25
+
+### Added
+- **RFC 9207** — `iss` parameter on authorization-error redirects (success
+  redirects already included it). Becomes a MUST in the MCP 2026-07-28
+  spec release candidate.
+- **RFC 7009** — `POST /oauth/revoke` now requires client authentication
+  (HTTP Basic or form body) and only revokes tokens owned by the
+  authenticated client. Honors the optional `token_type_hint` parameter.
+- **RFC 7662** — `POST /oauth/introspect` now requires client
+  authentication. Tokens not owned by the authenticated client are
+  reported as `{active: false}` to prevent token-scanning attacks.
+- Spec coverage for `revoke` + `introspect` endpoints (13 examples).
+
+### Changed
+- `revoke` and `introspect` now return HTTP 401 with
+  `{error: "invalid_client"}` when client authentication fails. Previously
+  they accepted unauthenticated requests. **This is a breaking change for
+  callers that did not authenticate** — update clients to send credentials
+  via HTTP Basic auth (preferred) or `client_id` + `client_secret` form
+  params.
+- `render_error` now accepts a `status:` keyword argument
+  (default `:bad_request`).
+
 ## [0.1.0] - 2025-01-10
 
 ### Added
@@ -39,5 +110,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.1.0...HEAD
+[Unreleased]: https://github.com/SerhiiBorozenets/mcp-auth/compare/v0.3.0...HEAD
+[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/app/controllers/mcp/auth/oauth_controller.rb

@@ -99,49 +99,38 @@ module Mcp
       end
 
       # RFC 7009: Token Revocation
+      # Requires client authentication; only revokes tokens that belong to the
+      # authenticated client (otherwise still returns 200 to avoid leaking which
+      # tokens exist — per RFC 7009 §2.2).
       def revoke
-        token = params[:token]
+        client = authenticate_client
+        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
 
-        # Try refresh token first
-        revoked = Services::TokenService.revoke_refresh_token(token)
-
-        # Try access token if not found
-        unless revoked
-          access_token = Mcp::Auth::AccessToken.find_by(token: token)
-          if access_token
-            access_token.destroy
-            revoked = true
-          end
-        end
+        revoked = revoke_token_for_client(token, client, hint: params[:token_type_hint])
 
-        # RFC 7009: Always return 200 OK
-        Rails.logger.info "[OAuth] Token revocation: #{revoked ? 'success' : 'not found'}"
+        # RFC 7009: Always return 200 OK regardless of whether the token was found.
+        Rails.logger.info "[OAuth] Token revocation by client=#{client.client_id}: #{revoked ? 'success' : 'not found / not owned'}"
         head :ok
       end
 
       # RFC 7662: Token Introspection
+      # Requires client authentication. Tokens not owned by the authenticated
+      # client are reported as `{active: false}` to prevent token-scanning.
       def introspect
-        token = params[:token]
+        client = authenticate_client
+        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
 
-        # Try as JWT access token
-        payload = Services::TokenService.validate_access_token(token)
-
-        response = if payload
-                     build_access_token_introspection(payload)
-                   else
-                     # Try as refresh token
-                     refresh_data = Services::TokenService.validate_refresh_token(token)
-                     refresh_data ? build_refresh_token_introspection(refresh_data) : { active: false }
-                   end
-
+        response = introspect_token_for_client(token, client)
         render json: response, content_type: 'application/json'
       end
 
@@ -239,6 +228,8 @@ module Mcp
         redirect_uri = URI.parse(params[:redirect_uri])
         query_params = { error: error, error_description: description }
         query_params[:state] = params[:state] if params[:state]
+        # RFC 9207: iss MUST be included in authorization responses, including errors.
+        query_params[:iss] = authorization_server_url
 
         redirect_uri.query = URI.encode_www_form(query_params)
         redirect_to redirect_uri.to_s, allow_other_host: true
@@ -335,6 +326,71 @@ module Mcp
         }.compact
       end
 
+      # === Client Authentication (RFC 6749 §2.3, used by revoke + introspect) ===
+
+      # Accepts client credentials from either HTTP Basic auth or form params.
+      # Returns the OauthClient instance on success, nil on failure.
+      def authenticate_client
+        client_id, client_secret = extract_client_credentials
+        return nil if client_id.blank? || client_secret.blank?
+
+        client = Mcp::Auth::OauthClient.find_by(client_id: client_id)
+        return nil unless client
+        return nil unless ActiveSupport::SecurityUtils.secure_compare(client.client_secret.to_s, client_secret.to_s)
+
+        client
+      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
+      end
+
+      # RFC 7009: revoke token only if it belongs to the requesting client.
+      # token_type_hint is a hint, not a constraint — try both regardless.
+      def revoke_token_for_client(token, client, hint: nil)
+        if hint == 'refresh_token'
+          revoke_refresh_for_client(token, client) || revoke_access_for_client(token, client)
+        else
+          revoke_access_for_client(token, client) || revoke_refresh_for_client(token, client)
+        end
+      end
+
+      def revoke_access_for_client(token, client)
+        access_token = Mcp::Auth::AccessToken.find_by(token: token, client_id: client.client_id)
+        return false unless access_token
+
+        access_token.destroy
+        true
+      end
+
+      def revoke_refresh_for_client(token, client)
+        refresh_token = Mcp::Auth::RefreshToken.find_by(token: token, client_id: client.client_id)
+        return false unless refresh_token
+
+        refresh_token.destroy
+        true
+      end
+
+      # RFC 7662: only describe tokens owned by the authenticated client.
+      def introspect_token_for_client(token, client)
+        payload = Services::TokenService.validate_access_token(token)
+        if payload && payload[:client_id] == client.client_id
+          build_access_token_introspection(payload)
+        else
+          refresh_data = Services::TokenService.validate_refresh_token(token)
+          if refresh_data && refresh_data[:client_id] == client.client_id
+            build_refresh_token_introspection(refresh_data)
+          else
+            { active: false }
+          end
+        end
+      end
+
       # === Token Introspection ===
 
       def build_access_token_introspection(payload)
@@ -463,14 +519,14 @@ module Mcp
 
       # === Error Handling ===
 
-      def render_error(error, description)
+      def render_error(error, description, status: :bad_request)
         error_response = {
           error: error,
           error_description: description
         }
 
         Rails.logger.error "[OAuth] Error: #{error_response.inspect}"
-        render json: error_response, status: :bad_request, content_type: 'application/json'
+        render json: error_response, status: status, content_type: 'application/json'
       end
 
       def current_org

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

@@ -78,16 +78,19 @@ module Mcp
           code_challenge_methods_supported: %w[S256],
           token_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post none],
           subject_types_supported: %w[public],
-          id_token_signing_alg_values_supported: %w[HS256]
+          id_token_signing_alg_values_supported: [Mcp::Auth.configuration&.token_signing_algorithm || 'HS256']
         }
 
         render json: metadata, status: :ok, content_type: 'application/json'
       end
 
-      # JWKS endpoint (empty for HMAC)
+      # JWKS endpoint. Returns the active public key as a JWK when the
+      # configured signing algorithm is asymmetric (RS256/ES256). HMAC keys
+      # are NEVER published — for HS256 this stays an empty key set.
       def jwks
-        keys = { keys: [] }
-        render json: keys, status: :ok, content_type: 'application/json'
+        jwk = Mcp::Auth::Services::TokenService.signing_jwk_export
+        keys = jwk ? [jwk] : []
+        render json: { keys: keys }, status: :ok, content_type: 'application/json'
       end
 
       private

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

@@ -5,12 +5,13 @@ module Mcp
     module Services
       class TokenService
         class << self
-          # Validate access token with optional resource verification (RFC 8707)
+          # Validate access token with optional resource verification (RFC 8707).
+          # Supports HS256, RS256, and ES256 — algorithm comes from configuration.
           def validate_access_token(token, resource: nil)
             return nil if token.blank?
 
             begin
-              payload = JWT.decode(token, oauth_secret, true, { algorithm: 'HS256' }).first
+              payload = JWT.decode(token, verification_key, true, { algorithm: signing_algorithm }).first
 
               # Check expiration manually to ensure proper handling
               if payload['exp']
@@ -59,7 +60,8 @@ module Mcp
               exp: exp_time
             }
 
-            token = JWT.encode(payload, oauth_secret, 'HS256')
+            jwt_headers = signing_kid ? { kid: signing_kid } : {}
+            token = JWT.encode(payload, signing_key, signing_algorithm, jwt_headers)
 
             # Store token in database for revocation support
             store_access_token(token, data, audience)
@@ -145,8 +147,104 @@ module Mcp
             raise
           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
+            return nil unless asymmetric_signing?
+
+            cached_public_key
+          end
+
+          # JWK identifier for the current signing key — included as `kid` in
+          # JWT headers and the JWKS entry. Falls back to JWT::JWK's
+          # auto-derived thumbprint when no explicit kid is configured.
+          def signing_kid
+            return nil unless asymmetric_signing?
+
+            Mcp::Auth.configuration&.token_signing_kid.presence || jwk.kid
+          end
+
+          # JWK for the active public key, suitable for the JWKS endpoint.
+          # Returns nil for HS256 (HMAC keys are never published).
+          def signing_jwk_export
+            return nil unless asymmetric_signing?
+
+            exported = jwk.export
+            exported[:kid] = signing_kid
+            exported[:alg] = signing_algorithm
+            exported[:use] = 'sig'
+            exported
+          end
+
           private
 
+          def asymmetric_signing?
+            Mcp::Auth.configuration&.asymmetric_signing? || false
+          end
+
+          def signing_algorithm
+            Mcp::Auth.configuration&.token_signing_algorithm || 'HS256'
+          end
+
+          # Key used to SIGN outgoing JWTs (HMAC secret for HS256, private key
+          # for RS256/ES256).
+          def signing_key
+            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
+          end
+
+          def cached_private_key
+            @cached_private_key ||= load_private_key
+          end
+
+          def cached_public_key
+            @cached_public_key ||= load_public_key
+          end
+
+          def jwk
+            @jwk ||= JWT::JWK.new(cached_public_key)
+          end
+
+          def load_private_key
+            raw = Mcp::Auth.configuration&.token_signing_private_key
+            raise 'token_signing_private_key is not configured' if raw.blank?
+
+            raw.is_a?(OpenSSL::PKey::PKey) ? raw : OpenSSL::PKey.read(raw)
+          end
+
+          def load_public_key
+            raw = Mcp::Auth.configuration&.token_signing_public_key
+            if raw.present?
+              return raw if raw.is_a?(OpenSSL::PKey::PKey)
+
+              return OpenSSL::PKey.read(raw)
+            end
+
+            # Derive from the private key when an explicit public key isn't given.
+            private_key = cached_private_key
+            case private_key
+            when OpenSSL::PKey::RSA then private_key.public_key
+            when OpenSSL::PKey::EC  then ec_public_key_from(private_key)
+            else
+              raise "Unsupported private key type for #{signing_algorithm}: #{private_key.class}"
+            end
+          end
+
+          # OpenSSL::PKey::EC#public_key returns the bare point, not a usable
+          # PKey instance. Build a public-only EC key so JWT::JWK can export it.
+          def ec_public_key_from(private_key)
+            pub = OpenSSL::PKey::EC.new(private_key.group)
+            pub.public_key = private_key.public_key
+            pub
+          end
+
           def oauth_secret
             secret = Mcp::Auth.configuration&.oauth_secret
             secret.presence || Rails.application.secret_key_base

data/lib/mcp/auth/version.rb

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

data/lib/mcp/auth.rb

@@ -22,6 +22,8 @@ module Mcp
     end
 
     class Configuration
+      SUPPORTED_SIGNING_ALGORITHMS = %w[HS256 RS256 ES256].freeze
+
       attr_accessor :oauth_secret,
                     :authorization_server_url,
                     :access_token_lifetime,
@@ -34,7 +36,11 @@ module Mcp
                     :use_custom_consent_view,
                     :mcp_server_path,
                     :mcp_docs_url,
-                    :validate_scope_for_user
+                    :validate_scope_for_user,
+                    :token_signing_algorithm,
+                    :token_signing_private_key,
+                    :token_signing_public_key,
+                    :token_signing_kid
 
       def initialize
         @oauth_secret = nil
@@ -50,6 +56,28 @@ module Mcp
         @mcp_server_path = '/mcp'
         @mcp_docs_url = nil
         @validate_scope_for_user = nil
+        # CP-9255 batch 2: JWT signing.
+        # Default HS256 keeps existing setups working (shared oauth_secret).
+        # Set algorithm to 'RS256' or 'ES256' and provide PEM-encoded keys
+        # via env or config to enable asymmetric signing + JWKS publication.
+        @token_signing_algorithm = 'HS256'
+        @token_signing_private_key = nil
+        @token_signing_public_key = nil
+        @token_signing_kid = nil
+      end
+
+      def token_signing_algorithm=(value)
+        value = value.to_s.upcase
+        unless SUPPORTED_SIGNING_ALGORITHMS.include?(value)
+          raise ArgumentError,
+                "Unsupported token_signing_algorithm: #{value.inspect}. " \
+                "Supported: #{SUPPORTED_SIGNING_ALGORITHMS.join(', ')}"
+        end
+        @token_signing_algorithm = value
+      end
+
+      def asymmetric_signing?
+        token_signing_algorithm != 'HS256'
       end
 
       # Register a custom scope for your application

metadata

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