token_authority 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30eb5cd2101ab6cc044d31d5dc15396ffef4c9efd955960c6dec70e57e613583
-  data.tar.gz: 6a24f7df903407dff09561e1ece8495c803dc6fa7175f0d3ff3641d8120ddc8f
+  metadata.gz: bba8d56df2875f6c50fc9937d6777f03ef3e0591e7adf5e39072820577946f1b
+  data.tar.gz: 934c70d43ada6108f9d46a2d11f1473a5925fa2bc9d8da9aa41313fc01a3ea3c
 SHA512:
-  metadata.gz: 62f5c24dd950f5956817ca5531cd695b0ab3b1a2785e67c828c3ca116a2254ff25b376abf5db01cf9931da8bfce13c9869dbff332c8a8955f30009ef5e296a41
-  data.tar.gz: be5cd3a31b883f6bf7bc0b80a1d2d1d87bcfaa1dc4c8469d3c36b874aeac2a471cf0286a0c8c35e11b5a4fec0bb8b749a98acf9fc3709a4c26253bd0728637ec
+  metadata.gz: 3acf7f1a3e38bb6145fc94b760fde4ef2ee74ba5a1e7049ee677f7875ed8799af6a840950cfbe7efeda1adda2f7b129984161ead5404e559626b9cd2fa44c019
+  data.tar.gz: e058adbe90a2367b1b28d89cf4df9d82cd79486f52594e96011da4d538d13cfdfec4ee496a9bbd1562a59fd2e11cdfda6558cd888ad479f0cdf922322390800a

data/CHANGELOG.md

@@ -1,12 +1,24 @@
 ## [Unreleased]
 
-## [0.3.1] - 2025-01-25
+## [0.3.2] - 2026-01-26
+
+### Added
+
+- WWW-Authenticate header on 401 responses from protected endpoints per RFC 9728, enabling automatic OAuth discovery for MCP clients
+- `client_secret_post` authentication for confidential clients on token and revocation endpoints
+- HTML redirect page for OAuth authorization completion, improving UX for desktop apps with custom URI schemes
+
+### Fixed
+
+- Resource URI comparison now normalizes trailing slashes, preventing `invalid_target` errors
+
+## [0.3.1] - 2026-01-25
 
 ### Fixed
 
 - Do not expire OAuth sessions when access tokens expire; this was preventing session refresh flow from completing successfully in some cases.
 
-## [0.3.0] - 2025-01-24
+## [0.3.0] - 2026-01-24
 
 ### Added
 
@@ -46,7 +58,7 @@
   - `rfc_7591_software_statement_required` → `dcr_software_statement_required`
   - `rfc_7591_jwks_cache_ttl` → `dcr_jwks_cache_ttl`
 
-## [0.2.1] - 2025-01-24
+## [0.2.1] - 2026-01-24
 
 ### Fixes
 
@@ -57,7 +69,7 @@
 
 - Update README to include link to MCP Quickstart guide.
 
-## [0.2.0] - 2025-01-23
+## [0.2.0] - 2026-01-23
 
 - Implemented support for OAuth 2.1 authorization flows and JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens (RFC 9068).
 - Implemented support for OAuth 2.0 Authorization Server Metadata (RFC 8414).
@@ -75,7 +87,8 @@
 
 - Initial release
 
-[Unreleased]: https://github.com/dickdavis/token_authority/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/dickdavis/token_authority/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/dickdavis/token_authority/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/dickdavis/token_authority/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/dickdavis/token_authority/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/dickdavis/token_authority/compare/v0.2.0...v0.2.1

data/app/controllers/concerns/token_authority/client_authentication.rb

@@ -4,13 +4,14 @@ module TokenAuthority
   # Provides OAuth client authentication for controllers.
   #
   # This concern handles authentication of OAuth clients during authorization
-  # and token requests. It supports both confidential clients (using HTTP Basic
-  # authentication with client_id and client_secret) and public clients (using
-  # only client_id).
+  # and token requests. It supports multiple authentication methods:
+  # - Public clients (using only client_id, no secret required)
+  # - HTTP Basic authentication (client_secret_basic)
+  # - POST body credentials (client_secret_post)
   #
   # The concern automatically:
   # - Resolves client_id to either a registered Client or URL-based ClientMetadataDocument
-  # - Validates HTTP Basic credentials for confidential clients
+  # - Validates credentials via HTTP Basic or POST body for confidential clients
   # - Emits authentication events for monitoring and security auditing
   # - Handles authentication errors with appropriate HTTP responses
   #
@@ -89,6 +90,14 @@ module TokenAuthority
         return
       end
 
+      if client_secret_post_auth_successful?
+        notify_event("authentication.client.succeeded",
+          client_id: @token_authority_client.public_id,
+          client_type: @token_authority_client.client_type,
+          auth_method: "client_secret_post")
+        return
+      end
+
       notify_event("authentication.client.failed",
         client_id: client_id,
         failure_reason: "missing_credentials",
@@ -111,6 +120,29 @@ module TokenAuthority
       @token_authority_client = nil
     end
 
+    # Attempts to authenticate using client_secret_post (credentials in POST body).
+    #
+    # Validates the client_secret from POST parameters against the loaded client.
+    # Accepts POST body credentials for confidential clients configured with either
+    # client_secret_post or client_secret_basic auth methods.
+    #
+    # @return [Boolean] true if authentication succeeds
+    # @api private
+    def client_secret_post_auth_successful?
+      return false if params[:client_secret].blank?
+      return false if @token_authority_client.blank?
+      return false if @token_authority_client.public_client_type?
+
+      authenticated = @token_authority_client.authenticate_with_secret(params[:client_secret])
+      unless authenticated
+        notify_event("authentication.client.failed",
+          client_id: @token_authority_client.public_id,
+          failure_reason: "invalid_secret",
+          auth_method_attempted: "client_secret_post")
+      end
+      authenticated
+    end
+
     # Attempts to authenticate using HTTP Basic credentials.
     #
     # Verifies that the client_id in Basic auth matches params[:client_id] if present,

data/app/controllers/concerns/token_authority/token_authentication.rb

@@ -102,6 +102,7 @@ module TokenAuthority
       notify_event("authentication.token.failed",
         failure_reason: "missing_authorization_header")
 
+      set_www_authenticate_header
       render json: {error: I18n.t("token_authority.errors.missing_auth_header")}, status: :unauthorized
     end
 
@@ -112,6 +113,7 @@ module TokenAuthority
       notify_event("authentication.token.failed",
         failure_reason: "invalid_token_format")
 
+      set_www_authenticate_header(error: "invalid_token")
       render json: {error: I18n.t("token_authority.errors.invalid_token")}, status: :unauthorized
     end
 
@@ -122,7 +124,91 @@ module TokenAuthority
       notify_event("authentication.token.failed",
         failure_reason: "unauthorized_token")
 
+      set_www_authenticate_header(error: "invalid_token")
       render json: {error: I18n.t("token_authority.errors.unauthorized_token")}, status: :unauthorized
     end
+
+    # Sets the WWW-Authenticate header for 401 responses per RFC 9728 and MCP spec.
+    #
+    # This header tells OAuth clients where to find the protected resource
+    # metadata, enabling automatic OAuth flow discovery (including DCR).
+    #
+    # Per MCP Authorization spec, the header SHOULD include a scope parameter
+    # to indicate scopes required for accessing the resource (RFC 6750 Section 3).
+    #
+    # @param error [String, nil] optional OAuth error code (e.g., "invalid_token")
+    # @return [void]
+    # @api private
+    def set_www_authenticate_header(error: nil)
+      resource_config = current_protected_resource_config
+      metadata_url = protected_resource_metadata_url(resource_config)
+      return if metadata_url.blank?
+
+      header_value = %(Bearer resource_metadata="#{metadata_url}")
+      header_value += %(, scope="#{www_authenticate_scope(resource_config)}") if www_authenticate_scope(resource_config).present?
+      header_value += %(, error="#{error}") if error.present?
+
+      response.headers["WWW-Authenticate"] = header_value
+    end
+
+    # Returns the current protected resource configuration.
+    #
+    # Looks up the resource by request subdomain. If no subdomain match is found,
+    # the first configured resource is used.
+    #
+    # @return [Hash, nil] the resource configuration
+    # @api private
+    def current_protected_resource_config
+      subdomain = request.subdomain.presence
+      TokenAuthority.config.protected_resource_for(subdomain)
+    end
+
+    # Returns the URL for the protected resource metadata endpoint.
+    #
+    # Derives the URL from the resource configuration's :resource field,
+    # which represents the protected resource URI. The well-known path is
+    # appended to form the complete metadata URL.
+    #
+    # If no resources are configured, falls back to deriving from the current
+    # request host.
+    #
+    # Controllers can override this method to customize the metadata URL.
+    #
+    # @param resource_config [Hash, nil] the resource configuration
+    # @return [String] the metadata URL
+    # @api private
+    def protected_resource_metadata_url(resource_config = nil)
+      resource_config ||= current_protected_resource_config
+
+      if resource_config.is_a?(Hash) && resource_config[:resource].present?
+        resource_uri = URI(resource_config[:resource])
+        return "#{resource_uri.scheme}://#{resource_uri.host}/.well-known/oauth-protected-resource"
+      end
+
+      # Fallback: derive from request origin
+      "#{request.protocol}#{request.host_with_port}/.well-known/oauth-protected-resource"
+    end
+
+    # Returns the scope value for the WWW-Authenticate header.
+    #
+    # Uses the resource's scopes_supported configuration to indicate what
+    # scopes are required for accessing this resource. Per MCP spec, this
+    # provides clients with guidance on appropriate scopes to request.
+    #
+    # Controllers can override this method to specify different scopes
+    # (e.g., endpoint-specific required scopes).
+    #
+    # @param resource_config [Hash, nil] the resource configuration
+    # @return [String, nil] space-separated scope string, or nil if no scopes configured
+    # @api private
+    def www_authenticate_scope(resource_config = nil)
+      resource_config ||= current_protected_resource_config
+      return nil unless resource_config.is_a?(Hash)
+
+      scopes = resource_config[:scopes_supported]
+      return nil unless scopes.is_a?(Array) && scopes.any?
+
+      scopes.join(" ")
+    end
   end
 end

data/app/controllers/token_authority/authorization_grants_controller.rb

@@ -102,7 +102,9 @@ module TokenAuthority
     def redirect_to_client(params_for_redirect:)
       clear_internal_state
       url = @token_authority_client.url_for_redirect(params: params_for_redirect.compact)
-      redirect_to url, allow_other_host: true
+      render "token_authority/redirect",
+        layout: TokenAuthority.config.consent_page_layout,
+        locals: {redirect_url: url}
     end
 
     def clear_internal_state

data/app/helpers/token_authority/authorization_grants_helper.rb

@@ -6,10 +6,14 @@ module TokenAuthority
     # Looks up the URI in the resource registry derived from protected resources.
     # Falls back to the URI itself if no mapping is configured.
     #
+    # The URI is normalized (trailing slash removed) before lookup to match
+    # how the resource registry stores URIs.
+    #
     # @param resource_uri [String] The resource URI
     # @return [String] The display name or the URI if no mapping exists
     def resource_display_name(resource_uri)
-      TokenAuthority.config.resource_registry[resource_uri] || resource_uri
+      normalized_uri = TokenAuthority.config.normalize_resource_uri(resource_uri)
+      TokenAuthority.config.resource_registry[normalized_uri] || resource_uri
     end
 
     # Returns a human-friendly display name for a scope.
@@ -22,5 +26,15 @@ module TokenAuthority
       scopes = TokenAuthority.config.scopes || {}
       scopes[scope] || scope
     end
+
+    # Generates a script tag that redirects the browser to the given URL.
+    # Used for OAuth redirects where the browser may not navigate away
+    # (e.g., custom URI schemes like claude://).
+    #
+    # @param url [String] The URL to redirect to
+    # @return [String] A script tag with the redirect JavaScript
+    def redirect_script_tag(url)
+      javascript_tag "window.location.href = #{url.to_json};"
+    end
   end
 end

data/app/models/concerns/token_authority/resourceable.rb

@@ -84,19 +84,25 @@ module TokenAuthority
     # Checks if all requested resources are in the allowed resources list.
     #
     # Returns true if resource indicators are not enabled in configuration.
+    # URIs are normalized (trailing slashes removed) before comparison for
+    # interoperability.
     #
     # @return [Boolean] true if all resources are allowed
     # @api private
     def allowed_resources?
       return true unless TokenAuthority.config.resources_enabled?
 
-      resources.all? { |uri| TokenAuthority.config.resource_registry.key?(uri) }
+      resources.all? do |uri|
+        normalized_uri = TokenAuthority.config.normalize_resource_uri(uri)
+        TokenAuthority.config.resource_registry.key?(normalized_uri)
+      end
     end
 
     # Checks if the current resources are a subset of the granted resources.
     #
     # Used during token refresh to ensure the new token doesn't request
     # access to more resources than the original grant.
+    # URIs are normalized (trailing slashes removed) before comparison.
     #
     # @param granted [Array<String>, nil] the originally granted resources
     #
@@ -105,7 +111,10 @@ module TokenAuthority
     def resources_subset_of?(granted)
       return true if granted.blank? || resources.blank?
 
-      (resources - granted).empty?
+      normalized_resources = resources.map { |uri| TokenAuthority.config.normalize_resource_uri(uri) }
+      normalized_granted = granted.map { |uri| TokenAuthority.config.normalize_resource_uri(uri) }
+
+      (normalized_resources - normalized_granted).empty?
     end
   end
 end

data/app/views/token_authority/redirect.html.erb

@@ -0,0 +1,6 @@
+<div>
+  <h2><%= t('token_authority.redirect.title') %></h2>
+  <p><%= t('token_authority.redirect.message') %></p>
+</div>
+
+<%= redirect_script_tag(redirect_url) %>

data/config/locales/token_authority.en.yml

@@ -238,6 +238,9 @@ en:
     client_error:
       title: 'Client Error'
       lede: 'The request provided by the client to this server is malformed. Please report this error through the client support channel.'
+    redirect:
+      title: 'Authorization Complete'
+      message: 'You may close this window.'
     errors:
       invalid_grant: 'The authorization grant is invalid'
       mismatched_refresh_token: 'The provided refresh token JTI does not match the refresh token JTI of the target OAuthSession.'

data/lib/token_authority/configuration.rb

@@ -408,11 +408,28 @@ module TokenAuthority
       resources.each_with_object({}) do |(_key, config), registry|
         next unless config.is_a?(Hash) && config[:resource].present?
 
-        uri = config[:resource]
+        uri = normalize_resource_uri(config[:resource])
         registry[uri] = config[:resource_name] || uri
       end
     end
 
+    # Normalizes a resource URI for consistent comparison.
+    #
+    # This method removes trailing slashes from resource URIs to ensure consistent
+    # matching between configured resources and client-provided resource parameters.
+    #
+    # @param uri [String] the resource URI to normalize
+    # @return [String] the normalized URI without trailing slash
+    #
+    # @example
+    #   normalize_resource_uri("https://mcp.example.com/")
+    #   # => "https://mcp.example.com"
+    def normalize_resource_uri(uri)
+      return uri if uri.blank?
+
+      uri.to_s.chomp("/")
+    end
+
     # Validates the configuration for internal consistency.
     # Ensures that required features are properly configured before use.
     #

data/lib/token_authority/version.rb

@@ -2,5 +2,5 @@ module TokenAuthority
   # The current version of the TokenAuthority gem.
   #
   # @return [String] the version string in semantic versioning format
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: token_authority
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Dick Davis
@@ -86,6 +86,7 @@ files:
 - app/models/token_authority/software_statement.rb
 - app/views/token_authority/authorization_grants/new.html.erb
 - app/views/token_authority/client_error.html.erb
+- app/views/token_authority/redirect.html.erb
 - config/locales/token_authority.en.yml
 - config/routes.rb
 - lib/generators/token_authority/install/install_generator.rb