better_auth-oauth-provider 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 064ea232e262c58fa331b01d271cacace56d0787690411c0c10509573e97575c
-  data.tar.gz: fb803328e302b653dcdad4efbf0f40067a798964e0e0a6c3b830933eb297a942
+  metadata.gz: 83ab585e58d2f6a3559de17278ee3028ba8294cacc5d53b2dbe0e501e891499f
+  data.tar.gz: 11d0780bd5c1e4d87606a0572aca65e7dff9e2389b1ee45e748c4953efd4479d
 SHA512:
-  metadata.gz: 531242dbca74547d088b8de6b7181a962e650725b6739743d1ccde257f28357f547b9f6d1c0fce32618dfaa74c94909a5fbeb8b86cb5bcc6e9a32bf585882b14
-  data.tar.gz: c3d2ad67c5e0ba91433f410accd11575a8e64f4057962c4217dfa591c14f73112fa87a382f5a2009b4427d45a67b964c2339350bcf8fb7d34613062c03e0c6c1
+  metadata.gz: cf0c2712de1ac44420fd6a6b15b42c9d825e5f61b6d5e732afe53d73200251533b83a9e1c0b40ecd4dcadab93dcdf014646d851bbfa82119ea9b8d692e56f752
+  data.tar.gz: 5d86171dde17750573cc62c6ea7ee0f447cce96673d6af0c4915af8d5db9f93648aeb902ea933517becf170392e16122a6d1d297d404e94867ea22fab0a69e87

data/lib/better_auth/oauth_provider/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module OAuthProvider
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/better_auth/plugins/oauth_provider/authorize.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module OAuthProvider
+      module_function
+
+      def validate_issuer_url(value)
+        uri = URI.parse(value.to_s)
+        uri.query = nil
+        uri.fragment = nil
+        if uri.scheme == "http" && !["localhost", "127.0.0.1", "::1"].include?(uri.hostname || uri.host)
+          uri.scheme = "https"
+        end
+        uri.to_s.sub(%r{/+\z}, "")
+      rescue URI::InvalidURIError
+        value.to_s.split(/[?#]/).first.sub(%r{/+\z}, "")
+      end
+    end
+
+    module_function
+
+    def oauth_authorize_endpoint(config)
+      Endpoint.new(path: "/oauth2/authorize", method: "GET") do |ctx|
+        oauth_authorize_flow(ctx, config, OAuthProtocol.stringify_keys(ctx.query))
+      end
+    end
+
+    def oauth_authorize_flow(ctx, config, query, continue_post_login: false)
+      query = oauth_resolve_request_uri!(ctx, config, query)
+      response_type = query["response_type"].to_s
+
+      client = OAuthProtocol.find_client(ctx, "oauthClient", query["client_id"])
+      raise APIError.new("BAD_REQUEST", message: "invalid_client") unless client
+      OAuthProtocol.validate_redirect_uri!(client, query["redirect_uri"])
+      if response_type != "code"
+        raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "unsupported_response_type", "response_type must be code"))
+      end
+
+      scopes = OAuthProtocol.parse_scopes(query["scope"])
+      scopes = OAuthProtocol.parse_scopes(OAuthProtocol.stringify_keys(client)["scopes"] || config[:scopes]) if scopes.empty?
+      prompts = OAuthProtocol.parse_scopes(query["prompt"])
+      client_data = OAuthProtocol.stringify_keys(client)
+      if client_data["disabled"]
+        raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "invalid_client", "client is disabled"))
+      end
+      allowed_scopes = OAuthProtocol.parse_scopes(client_data["scopes"])
+      allowed_scopes = OAuthProtocol.parse_scopes(config[:scopes]) if allowed_scopes.empty?
+      unless scopes.all? { |scope| allowed_scopes.include?(scope) }
+        raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "invalid_scope", "invalid scope"))
+      end
+      pkce_error = OAuthProtocol.validate_authorize_pkce(client_data, scopes, query["code_challenge"], query["code_challenge_method"])
+      raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "invalid_request", pkce_error)) if pkce_error
+
+      session = Routes.current_session(ctx, allow_nil: true)
+      unless session
+        if prompts.include?("none")
+          raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "login_required", state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx))))
+        end
+
+        if prompts.include?("create")
+          raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "create"))
+        end
+
+        raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "login"))
+      end
+
+      if prompts.include?("login") && !continue_post_login
+        raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "login"))
+      end
+
+      if prompts.include?("select_account") && !continue_post_login
+        if prompts.include?("none")
+          raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "account_selection_required", state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx))))
+        end
+
+        raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "select_account"))
+      end
+
+      if config.dig(:post_login, :should_redirect).respond_to?(:call) && !continue_post_login
+        should_redirect = config.dig(:post_login, :should_redirect).call({user: session[:user], session: session[:session], client: client_data, scopes: scopes})
+        if should_redirect
+          if prompts.include?("none")
+            raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "interaction_required", state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx))))
+          end
+
+          raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "post_login", page: should_redirect.is_a?(String) ? should_redirect : nil))
+        end
+      end
+
+      consent_reference_id = oauth_consent_reference(config, session, scopes)
+      requires_consent = !client_data["skipConsent"] && (prompts.include?("consent") || !oauth_consent_granted?(ctx, client_data["clientId"], session[:user]["id"], scopes, consent_reference_id))
+
+      if requires_consent
+        if prompts.include?("none")
+          raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "consent_required", state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx))))
+        end
+
+        consent_code = Crypto.random_string(32)
+        config[:store][:consents][consent_code] = {
+          query: query,
+          session: session,
+          client: client,
+          scopes: scopes,
+          reference_id: consent_reference_id,
+          expires_at: Time.now + 600
+        }
+        raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(config[:consent_page], consent_code: consent_code, client_id: client_data["clientId"], scope: OAuthProtocol.scope_string(scopes)))
+      end
+
+      oauth_redirect_with_code(ctx, config, query, session, client, scopes, reference_id: consent_reference_id)
+    end
+
+    def oauth_prompt_redirect(ctx, config, query, type, page: nil)
+      target = page || oauth_prompt_page(config, type)
+
+      "#{target}?#{oauth_signed_query(ctx, query)}"
+    end
+
+    def oauth_prompt_page(config, type)
+      case type
+      when "create"
+        config.dig(:signup, :page) || config[:login_page]
+      when "select_account"
+        config.dig(:select_account, :page) || config[:login_page]
+      when "post_login"
+        config.dig(:post_login, :page) || config[:login_page]
+      when "consent"
+        config[:consent_page]
+      else
+        config[:login_page]
+      end
+    end
+
+    def oauth_signed_query(ctx, query)
+      data = OAuthProtocol.stringify_keys(query).compact
+      data["exp"] = (Time.now.to_i + 600).to_s
+      unsigned = URI.encode_www_form(data)
+      signature = Crypto.hmac_signature(unsigned, ctx.context.secret, encoding: :base64url)
+      "#{unsigned}&#{URI.encode_www_form("sig" => signature)}"
+    end
+
+    def oauth_verified_query!(ctx, oauth_query)
+      raise APIError.new("BAD_REQUEST", message: "missing oauth query") if oauth_query.to_s.empty?
+
+      pairs = URI.decode_www_form(oauth_query.to_s)
+      signature = pairs.reverse_each.find { |key, _value| key == "sig" }&.last
+      unsigned_pairs = pairs.filter_map { |key, value| [key, value] unless key == "sig" }
+      unsigned = URI.encode_www_form(unsigned_pairs)
+      exp = unsigned_pairs.reverse_each.find { |key, _value| key == "exp" }&.last.to_i
+      unless signature && exp >= Time.now.to_i && Crypto.verify_hmac_signature(unsigned, signature, ctx.context.secret, encoding: :base64url)
+        raise APIError.new("BAD_REQUEST", message: "invalid oauth query")
+      end
+
+      unsigned_pairs.each_with_object({}) do |(key, value), result|
+        next if key == "exp"
+
+        result[key] = if result.key?(key)
+          Array(result[key]) << value
+        else
+          value
+        end
+      end
+    end
+
+    def oauth_delete_prompt!(query, prompt)
+      prompts = OAuthProtocol.parse_scopes(query["prompt"])
+      prompts.delete(prompt)
+      if prompts.empty?
+        query.delete("prompt")
+      else
+        query["prompt"] = OAuthProtocol.scope_string(prompts)
+      end
+    end
+
+    def oauth_redirect_location
+      yield
+    rescue APIError => error
+      location = error.headers["location"]
+      return location if location
+
+      raise
+    end
+
+    def oauth_authorize_error_redirect(ctx, query, error, description)
+      OAuthProtocol.redirect_uri_with_params(
+        query["redirect_uri"],
+        error: error,
+        error_description: description,
+        state: query["state"],
+        iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx))
+      )
+    end
+
+    def oauth_resolve_request_uri!(ctx, config, query)
+      query = OAuthProtocol.stringify_keys(query)
+      return query if query["request_uri"].to_s.empty?
+
+      resolver = config[:request_uri_resolver]
+      unless resolver.respond_to?(:call)
+        return oauth_invalid_request_uri!(ctx, query, "request_uri not supported")
+      end
+
+      resolved = resolver.call({request_uri: query["request_uri"], client_id: query["client_id"], context: ctx})
+      return oauth_invalid_request_uri!(ctx, query, "request_uri is invalid or expired") unless resolved
+
+      OAuthProtocol.stringify_keys(resolved)
+    end
+
+    def oauth_invalid_request_uri!(ctx, query, description)
+      redirect_uri = query["redirect_uri"]
+      raise APIError.new("BAD_REQUEST", message: "invalid_request_uri") if redirect_uri.to_s.empty?
+
+      raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "invalid_request_uri", description))
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module OAuthProvider
+      module Client
+        ID = "oauth-provider-client"
+
+        module_function
+
+        def parse_signed_query(search)
+          query = search.to_s.sub(/\A\?/, "")
+          return nil if query.empty?
+
+          pairs = URI.decode_www_form(query)
+          return nil unless pairs.any? { |key, _value| key == "sig" }
+
+          signed_pairs = []
+          pairs.each do |key, value|
+            signed_pairs << [key, value]
+            break if key == "sig"
+          end
+          URI.encode_www_form(signed_pairs)
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/client_resource.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module OAuthProvider
+      module ClientResource
+        ID = "oauth-provider-resource-client"
+
+        module_function
+
+        def protected_resource_metadata(overrides = {}, authorization_server: nil, oauth_provider_options: nil, external_scopes: [])
+          data = OAuthProtocol.stringify_keys(overrides || {})
+          resource = data["resource"] || authorization_server
+          raise Error, "missing required resource" if resource.to_s.empty?
+
+          validate_resource_scopes!(data["scopes_supported"], oauth_provider_options, external_scopes)
+
+          response = {resource: resource}
+          response[:authorization_servers] = [authorization_server] if authorization_server
+          response.merge!(data.transform_keys(&:to_sym))
+          response[:resource] = resource
+          response
+        end
+
+        def validate_resource_scopes!(scopes_supported, oauth_provider_options, external_scopes)
+          scopes = OAuthProtocol.parse_scopes(scopes_supported)
+          return if scopes.empty?
+
+          allowed = OAuthProtocol.parse_scopes(oauth_provider_options && oauth_provider_options[:scopes]) + OAuthProtocol.parse_scopes(external_scopes)
+          scopes.each do |scope|
+            if scope == "openid"
+              raise Error, "Only the Auth Server should utilize the openid scope"
+            end
+            next if allowed.empty? || allowed.include?(scope)
+
+            raise Error, %(Unsupported scope #{scope}. If external, please add to "externalScopes")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/consent.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def oauth_consent_endpoint(config)
+      Endpoint.new(path: "/oauth2/consent", method: "POST") do |ctx|
+        current_session = Routes.current_session(ctx)
+        body = OAuthProtocol.stringify_keys(ctx.body)
+        consent = config[:store][:consents].delete(body["consent_code"].to_s)
+        raise APIError.new("BAD_REQUEST", message: "invalid consent_code") unless consent
+        raise APIError.new("BAD_REQUEST", message: "expired consent_code") if consent[:expires_at] <= Time.now
+
+        query = consent[:query]
+        if body["accept"] == false || body["accept"].to_s == "false"
+          redirect = OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "access_denied", state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)))
+          next ctx.json({redirectURI: redirect})
+        end
+
+        granted_scopes = OAuthProtocol.parse_scopes(body["scope"] || body["scopes"])
+        granted_scopes = consent[:scopes] if granted_scopes.empty?
+        unless granted_scopes.all? { |scope| consent[:scopes].include?(scope) }
+          raise APIError.new("BAD_REQUEST", message: "invalid_scope")
+        end
+
+        reference_id = oauth_consent_reference(config, current_session, granted_scopes) || consent[:reference_id]
+        oauth_store_consent(ctx, consent[:client], consent[:session], granted_scopes, reference_id)
+        redirect = oauth_authorization_redirect(ctx, config, query, consent[:session], consent[:client], granted_scopes, reference_id: reference_id)
+        ctx.json({redirectURI: redirect})
+      end
+    end
+
+    def oauth_authorization_redirect(ctx, config, query, session, client, scopes, reference_id: nil)
+      code = Crypto.random_string(32)
+      client_reference_id = OAuthProtocol.stringify_keys(client)["referenceId"]
+      OAuthProtocol.store_code(
+        config[:store],
+        code: code,
+        client_id: query["client_id"],
+        redirect_uri: query["redirect_uri"],
+        session: session,
+        scopes: scopes,
+        code_challenge: query["code_challenge"],
+        code_challenge_method: query["code_challenge_method"],
+        nonce: query["nonce"],
+        reference_id: reference_id || client_reference_id
+      )
+      OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], code: code, state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)))
+    end
+
+    def oauth_redirect_with_code(ctx, config, query, session, client, scopes, reference_id: nil)
+      raise ctx.redirect(oauth_authorization_redirect(ctx, config, query, session, client, scopes, reference_id: reference_id))
+    end
+
+    def oauth_consent_granted?(ctx, client_id, user_id, scopes, reference_id = nil)
+      where = [
+        {field: "clientId", value: client_id},
+        {field: "userId", value: user_id}
+      ]
+      where << {field: "referenceId", value: reference_id} if reference_id
+      consent = ctx.context.adapter.find_one(
+        model: "oauthConsent",
+        where: where
+      )
+      return false unless consent
+
+      granted = OAuthProtocol.parse_scopes(consent["scopes"])
+      scopes.all? { |scope| granted.include?(scope) }
+    end
+
+    def oauth_store_consent(ctx, client, session, scopes, reference_id = nil)
+      client_id = OAuthProtocol.stringify_keys(client)["clientId"]
+      user_id = session[:user]["id"]
+      where = [
+        {field: "clientId", value: client_id},
+        {field: "userId", value: user_id}
+      ]
+      where << {field: "referenceId", value: reference_id} if reference_id
+      existing = ctx.context.adapter.find_one(
+        model: "oauthConsent",
+        where: where
+      )
+      data = {clientId: client_id, userId: user_id, scopes: scopes}
+      data[:referenceId] = reference_id if reference_id
+      if existing
+        ctx.context.adapter.update(model: "oauthConsent", where: [{field: "id", value: existing.fetch("id")}], update: data)
+      else
+        ctx.context.adapter.create(model: "oauthConsent", data: data)
+      end
+    end
+
+    def oauth_consent_reference(config, session, scopes)
+      callback = config.dig(:post_login, :consent_reference_id) || config.dig(:post_login, :consentReferenceId)
+      return nil unless callback.respond_to?(:call)
+
+      callback.call({user: session[:user], session: session[:session], scopes: scopes})
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/continue.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def oauth_continue_endpoint(config)
+      Endpoint.new(path: "/oauth2/continue", method: "POST") do |ctx|
+        Routes.current_session(ctx)
+        body = OAuthProtocol.stringify_keys(ctx.body)
+        action = if body["selected"] == true
+          "select_account"
+        elsif body["created"] == true
+          "create"
+        elsif body["postLogin"] == true || body["post_login"] == true
+          "post_login"
+        end
+        raise APIError.new("BAD_REQUEST", message: "Missing parameters") unless action
+
+        query = oauth_verified_query!(ctx, body["oauth_query"])
+        oauth_delete_prompt!(query, action) unless action == "post_login"
+        url = oauth_redirect_location { oauth_authorize_flow(ctx, config, query, continue_post_login: action == "post_login") }
+        ctx.json({redirect: true, url: url})
+      end
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/introspect.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def oauth_introspect_endpoint(config)
+      Endpoint.new(path: "/oauth2/introspect", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+        client = OAuthProtocol.authenticate_client!(ctx, "oauthClient", store_client_secret: config[:store_client_secret], prefix: config[:prefix])
+        body = OAuthProtocol.stringify_keys(ctx.body)
+        token = OAuthProtocol.find_token_by_hint(config[:store], body["token"].to_s, body["token_type_hint"], prefix: config[:prefix])
+        active = token && !token["revoked"] && (!token["expiresAt"] || token["expiresAt"] > Time.now)
+        if active
+          next ctx.json({
+            active: true,
+            client_id: token["clientId"],
+            scope: OAuthProtocol.scope_string(token["scope"] || token["scopes"]),
+            sub: token["subject"] || token.dig("user", "id"),
+            iss: token["issuer"],
+            iat: token["issuedAt"]&.to_i,
+            exp: token["expiresAt"]&.to_i,
+            sid: token["sessionId"],
+            aud: token["audience"]
+          })
+        end
+
+        jwt = oauth_introspect_jwt_access_token(ctx, client, body["token"].to_s)
+        ctx.json(jwt || {active: false})
+      end
+    end
+
+    def oauth_jwt_access_token?(config, audience)
+      !!audience && !config[:disable_jwt_plugin] && !config[:disable_jwt_access_tokens]
+    end
+
+    def oauth_introspect_jwt_access_token(ctx, client, token)
+      payload = ::JWT.decode(token, ctx.context.secret, true, algorithm: "HS256").first
+      client_data = OAuthProtocol.stringify_keys(client)
+      return nil unless payload["azp"] == client_data["clientId"]
+
+      {
+        active: true,
+        client_id: payload["azp"],
+        scope: payload["scope"],
+        sub: payload["sub"],
+        aud: payload["aud"],
+        exp: payload["exp"]
+      }.compact
+    rescue ::JWT::DecodeError
+      nil
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/logout.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def oauth_end_session_endpoint
+      Endpoint.new(path: "/oauth2/end-session", method: ["GET", "POST"], metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+        input = OAuthProtocol.stringify_keys((ctx.method == "GET") ? ctx.query : ctx.body)
+        id_token_hint = input["id_token_hint"].to_s
+        raise APIError.new("UNAUTHORIZED", message: "invalid id token") if id_token_hint.empty?
+
+        decoded = ::JWT.decode(id_token_hint, nil, false).first
+        client_id = input["client_id"] || decoded["aud"]
+        client = OAuthProtocol.find_client(ctx, "oauthClient", client_id)
+        raise APIError.new("BAD_REQUEST", message: "invalid_client") unless client
+
+        client_data = OAuthProtocol.stringify_keys(client)
+        raise APIError.new("BAD_REQUEST", message: "invalid_client") if client_data["disabled"]
+        raise APIError.new("UNAUTHORIZED", message: "client unable to logout") unless client_data["enableEndSession"]
+
+        payload = Crypto.verify_jwt(id_token_hint, client_data["clientId"])
+        raise APIError.new("UNAUTHORIZED", message: "invalid id token") unless payload
+        raise APIError.new("BAD_REQUEST", message: "audience mismatch") if input["client_id"] && payload["aud"] != input["client_id"]
+
+        if payload["sid"]
+          ctx.context.adapter.delete(model: "session", where: [{field: "id", value: payload["sid"]}])
+        end
+
+        if input["post_logout_redirect_uri"]
+          unless OAuthProtocol.client_logout_redirect_uris(client_data).include?(input["post_logout_redirect_uri"])
+            raise APIError.new("BAD_REQUEST", message: "invalid post_logout_redirect_uri")
+          end
+
+          redirect = OAuthProtocol.redirect_uri_with_params(input["post_logout_redirect_uri"], state: input["state"])
+          raise ctx.redirect(redirect)
+        end
+
+        ctx.json({status: true})
+      rescue ::JWT::DecodeError
+        raise APIError.new("UNAUTHORIZED", message: "invalid id token")
+      end
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_provider/mcp.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module OAuthProvider
+      module MCP
+        module_function
+
+        def www_authenticate(resource, resource_metadata_mappings: {})
+          Array(resource).map do |value|
+            metadata_url = resource_metadata_url(value, resource_metadata_mappings)
+            %(Bearer resource_metadata="#{metadata_url}")
+          end.join(", ")
+        end
+
+        def resource_metadata_url(resource, mappings = {})
+          value = resource.to_s
+          uri = URI.parse(value)
+          if uri.scheme && uri.host
+            path = uri.path.to_s.end_with?("/") ? uri.path.to_s.delete_suffix("/") : uri.path.to_s
+            return "#{resource_origin(uri)}/.well-known/oauth-protected-resource#{path}"
+          end
+
+          mapped = OAuthProtocol.stringify_keys(mappings || {})[value] || mappings[value.to_sym]
+          raise APIError.new("INTERNAL_SERVER_ERROR", message: "missing resource_metadata mapping for #{value}") if mapped.to_s.empty?
+
+          mapped
+        rescue URI::InvalidURIError
+          mapped = OAuthProtocol.stringify_keys(mappings || {})[value] || mappings[value.to_sym]
+          raise APIError.new("INTERNAL_SERVER_ERROR", message: "missing resource_metadata mapping for #{value}") if mapped.to_s.empty?
+
+          mapped
+        end
+
+        def resource_origin(uri)
+          default_port = (uri.scheme == "http" && uri.port == 80) || (uri.scheme == "https" && uri.port == 443)
+          port = default_port ? "" : ":#{uri.port}"
+          "#{uri.scheme}://#{uri.host}#{port}"
+        end
+
+        def handle_mcp_errors(error, resource, resource_metadata_mappings: {})
+          raise error unless error.is_a?(APIError) && error.status_code == 401
+
+          raise APIError.new(
+            "UNAUTHORIZED",
+            message: error.message,
+            headers: {"WWW-Authenticate" => www_authenticate(resource, resource_metadata_mappings: resource_metadata_mappings)}
+          )
+        end
+
+        def mcp_handler(resource:, verifier:, resource_metadata_mappings: {}, &handler)
+          lambda do |request|
+            authorization = request.respond_to?(:headers) ? request.headers["authorization"] : nil
+            token = authorization.to_s.delete_prefix("Bearer ").strip
+            raise APIError.new("UNAUTHORIZED", message: "missing authorization header") if token.empty?
+
+            jwt = verifier.call(token)
+            handler.call(request, jwt)
+          rescue APIError => error
+            handle_mcp_errors(error, resource, resource_metadata_mappings: resource_metadata_mappings)
+          end
+        end
+      end
+    end
+  end
+end