mcp-auth 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4640ff06bc400ec8ec8b2869a90194a1ec6d89de1772ae23f4056cf4bfcb2d54
-  data.tar.gz: 7f55acb2a222a430ecc1552b9073b71613a6b52f506f15b54224cc71fef66e24
+  metadata.gz: 46fb4e82f6f75e231441aacd12e4adfdfa14efffa64556ca4325f7ad3096eb1d
+  data.tar.gz: 6e9ba1314e2823c309651b5dae0c3ea1efda7e8140fe6266a4204603eab9b816
 SHA512:
-  metadata.gz: f7719d166eacb474ddd2769d4ea2dfeab40eea73592d5e284136f5036b06bb91bec299f6edf4527808ce0d5ec2cf5870e5a97c253bbb0f0a806851549f4c5306
-  data.tar.gz: cf4b4977f5d8613a3d1102961a38129de1b8a52966efe130adb2399e38c4e378714bc0487a666e77c01748a4af57864f2b8813ca43ed6e086b18969e27276306
+  metadata.gz: c1326ad826abb70c5f888595aec6d47a2083857c98e9fd167af76d6c253fa4432430748be7b399fd902db4806bbf80df3169247e915be7bea6ba6682d5903bee
+  data.tar.gz: b4d29c3b89881f5e2585342e5b0d20b6aaea2a9a3c5396d1752bc32fb16ae7677b37bb5f1898ca7e66330a9b02c7fdd84f508deff2196808629a63af18369bb2

data/CHANGELOG.md

@@ -7,6 +7,53 @@ 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
@@ -63,6 +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.2.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/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.2.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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Serhii Borozenets