token_authority 0.2.1 → 0.3.0

data/lib/token_authority/errors.rb

@@ -218,4 +218,33 @@ module TokenAuthority
       super
     end
   end
+
+  # Raised when no protected resource configuration exists for the requested subdomain.
+  #
+  # This error occurs in the RFC 9728 protected resource metadata endpoint when:
+  # 1. A subdomain-specific request arrives but that subdomain isn't in protected_resources
+  # 2. The fallback protected_resource configuration is also empty or nil
+  # 3. A bare domain request arrives but protected_resource isn't configured
+  #
+  # The ResourceMetadataController catches this error and returns HTTP 404, which is
+  # semantically correct: the client is asking about a resource that doesn't exist in
+  # the configuration. This differs from a 500 error which would imply a server problem.
+  #
+  # This separation of concerns (model raises domain error, controller maps to HTTP status)
+  # keeps the model focused on business logic without coupling it to HTTP semantics.
+  #
+  # @example Subdomain not configured
+  #   # config.protected_resources = { "api" => {...} }
+  #   # Request to mcp.example.com/.well-known/oauth-protected-resource
+  #   # Raises this error because "mcp" isn't configured
+  #
+  # @see ResourceMetadataController#show
+  # @since 0.3.0
+  class ResourceNotConfiguredError < StandardError
+    # Creates a new ResourceNotConfiguredError.
+    # @param msg [String] custom error message
+    def initialize(msg = "No protected resource configuration found for this subdomain")
+      super
+    end
+  end
 end

data/lib/token_authority/routing/constraints.rb

@@ -62,9 +62,9 @@ module TokenAuthority
       # Determines if dynamic client registration is enabled in the configuration.
       #
       # @param _request [ActionDispatch::Request] the Rails request object (unused)
-      # @return [Boolean] true if RFC 7591 dynamic registration is enabled
+      # @return [Boolean] true if dynamic client registration is enabled
       def matches?(_request)
-        TokenAuthority.config.rfc_7591_enabled
+        TokenAuthority.config.dcr_enabled
       end
     end
   end

data/lib/token_authority/routing/routes.rb

@@ -4,36 +4,94 @@ module ActionDispatch
   module Routing
     class Mapper
       ##
-      # Adds all TokenAuthority routes including OAuth 2.0 metadata endpoints
-      # (RFC 8414, RFC 9728) and mounts the TokenAuthority engine.
+      # Registers authorization server routes including OAuth endpoints and RFC 8414 metadata.
       #
-      # Both RFC 8414 and RFC 9728 require the metadata endpoints to be at the
-      # root level `/.well-known/` path, not under the engine mount path.
+      # This is the primary route helper for setting up OAuth authorization server functionality.
+      # It registers two things:
+      # 1. The RFC 8414 metadata endpoint at /.well-known/oauth-authorization-server
+      # 2. The full TokenAuthority engine at your chosen mount path
       #
-      # @param at [String] the path where TokenAuthority engine is mounted (default: "/oauth")
+      # The metadata endpoint receives the mount path as a parameter so it can generate
+      # correct URLs for the authorization and token endpoints in its response. This allows
+      # clients to discover the OAuth endpoints dynamically.
       #
-      # @example
+      # @param at [String] mount path for OAuth endpoints (default: "/oauth")
+      #
+      # @example Basic usage
       #   Rails.application.routes.draw do
-      #     token_authority_routes  # Mounts at default "/oauth"
+      #     token_authority_auth_server_routes
+      #     # Creates routes at /oauth/authorize, /oauth/token, etc.
+      #     # Metadata at /.well-known/oauth-authorization-server
       #   end
       #
-      # @example Custom mount path
+      # @example Authorization server on dedicated subdomain
       #   Rails.application.routes.draw do
-      #     token_authority_routes(at: "/auth")
+      #     constraints subdomain: "auth" do
+      #       token_authority_auth_server_routes
+      #       # Creates https://auth.example.com/oauth/authorize, etc.
+      #     end
       #   end
-      def token_authority_routes(at: "/oauth")
-        # RFC 8414: Authorization Server Metadata
+      #
+      # @example Custom mount path
+      #   token_authority_auth_server_routes(at: "/oauth2")
+      #   # Creates /oauth2/authorize, /oauth2/token instead of /oauth/*
+      #
+      def token_authority_auth_server_routes(at: "/oauth")
         get "/.well-known/oauth-authorization-server",
           to: "token_authority/metadata#show",
           defaults: {mount_path: at}
 
-        # RFC 9728: Protected Resource Metadata
-        get "/.well-known/oauth-protected-resource",
-          to: "token_authority/resource_metadata#show",
-          defaults: {mount_path: at}
-
         mount TokenAuthority::Engine => at
       end
+
+      ##
+      # Registers RFC 9728 Protected Resource Metadata endpoint for client discovery.
+      #
+      # Creates a route at /.well-known/oauth-protected-resource that returns metadata
+      # about the protected resource, including which authorization servers can issue
+      # tokens for it, what scopes are supported, and how to present bearer tokens.
+      #
+      # This helper is designed to be called multiple times with different subdomain
+      # constraints, enabling a single Rails application to serve metadata for multiple
+      # protected resources. The controller extracts the subdomain from each request and
+      # looks it up as a symbol key in config.resources to find the appropriate metadata.
+      #
+      # For single-resource deployments, configure one entry in config.resources - it will
+      # be used as the fallback for any request. For multi-resource deployments, configure
+      # entries for each subdomain. The first entry in config.resources is used as the
+      # fallback when no subdomain matches.
+      #
+      # Returns 404 if config.resources is empty.
+      #
+      # @example Single protected resource
+      #   Rails.application.routes.draw do
+      #     token_authority_auth_server_routes
+      #     token_authority_protected_resource_route
+      #     # Serves metadata from first entry in config.resources
+      #   end
+      #
+      # @example Multiple protected resources at different subdomains
+      #   Rails.application.routes.draw do
+      #     token_authority_auth_server_routes
+      #
+      #     # REST API protected resource
+      #     constraints subdomain: "api" do
+      #       token_authority_protected_resource_route
+      #       # Serves metadata from config.resources[:api]
+      #     end
+      #
+      #     # MCP server protected resource
+      #     constraints subdomain: "mcp" do
+      #       token_authority_protected_resource_route
+      #       # Serves metadata from config.resources[:mcp]
+      #     end
+      #   end
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc9728.html RFC 9728
+      def token_authority_protected_resource_route
+        get "/.well-known/oauth-protected-resource",
+          to: "token_authority/protected_resource_metadata#show"
+      end
     end
   end
 end

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.2.1"
+  VERSION = "0.3.0"
 end

data/lib/token_authority.rb

@@ -19,8 +19,8 @@ require "token_authority/routing/routes"
 # @example Basic configuration
 #   TokenAuthority.configure do |config|
 #     config.secret_key = Rails.application.credentials.secret_key_base
-#     config.rfc_9068_audience_url = "https://api.example.com"
-#     config.rfc_9068_issuer_url = "https://example.com"
+#     config.token_audience_url = "https://api.example.com"
+#     config.token_issuer_url = "https://example.com"
 #   end
 #
 # @since 0.2.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: token_authority
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Dick Davis
@@ -56,7 +56,7 @@ files:
 - app/controllers/token_authority/authorizations_controller.rb
 - app/controllers/token_authority/clients_controller.rb
 - app/controllers/token_authority/metadata_controller.rb
-- app/controllers/token_authority/resource_metadata_controller.rb
+- app/controllers/token_authority/protected_resource_metadata_controller.rb
 - app/controllers/token_authority/sessions_controller.rb
 - app/helpers/token_authority/authorization_grants_helper.rb
 - app/models/concerns/token_authority/claim_validatable.rb

data/app/controllers/token_authority/resource_metadata_controller.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module TokenAuthority
-  ##
-  # Controller for RFC 9728 OAuth 2.0 Protected Resource Metadata
-  class ResourceMetadataController < ActionController::API
-    def show
-      metadata = ProtectedResourceMetadata.new(mount_path: params[:mount_path])
-      render json: metadata.to_h
-    end
-  end
-end