standard_id 0.48.1 → 0.49.0

data/lib/standard_id/oauth/client_registration.rb

@@ -11,11 +11,18 @@ module StandardId
     # in the same flow-object style as the other lib/standard_id/oauth/ objects.
     #
     # On success #call returns a Result carrying the persisted client plus the
-    # one-time plaintext secret (confidential clients only); on a metadata or
-    # redirect-uri problem it raises the matching RFC 7591 §3.2.2 error
-    # (InvalidRedirectUriError / InvalidClientMetadataError), which the
-    # controller renders as HTTP 400. A nil owner resolver while the feature is
-    # enabled raises ConfigurationError (a host-app bug, not client input).
+    # one-time plaintext secret (confidential clients only) and, once migration
+    # 20261020120000 has run, the one-time RFC 7592 registration access token;
+    # on a metadata or redirect-uri problem it raises the matching RFC 7591
+    # §3.2.2 error (InvalidRedirectUriError / InvalidClientMetadataError), which
+    # the controller renders as HTTP 400. A nil owner resolver while the
+    # feature is enabled raises ConfigurationError (a host-app bug, not client
+    # input).
+    #
+    # `config.oauth.dynamic_registration_attributes` pins what the client may
+    # not choose (scopes, metadata, lifetimes, consent); `.update` applies an
+    # RFC 7592 §2.2 document to an existing client under the same rules, and
+    # `.deregister` is RFC 7592 §2.3.
     class ClientRegistration
       # RFC 7591 grant_types we support. M2M (client_credentials) is deliberately
       # excluded from DCR — self-registered clients are public/interactive.
@@ -27,26 +34,68 @@ module StandardId
       CONFIDENTIAL_AUTH_METHODS = %w[client_secret_basic client_secret_post].freeze
       SUPPORTED_AUTH_METHODS = (CONFIDENTIAL_AUTH_METHODS + [PUBLIC_AUTH_METHOD]).freeze
       DEFAULT_SCOPE = "openid profile email".freeze
+      # Keys `config.oauth.dynamic_registration_attributes` may pin.
+      PINNABLE_ATTRIBUTES = %w[scopes metadata access_token_lifetime authorization_code_lifetime require_consent description].freeze
+      REGISTRATION_ACCESS_TOKEN_BYTES = 32
 
       # Minimal result object mirroring the gem's `result.success?` /
       # `result.value` convention. `client_secret` is the one-time plaintext for
-      # confidential clients (nil for public clients).
-      Result = Struct.new(:client, :client_secret, :token_endpoint_auth_method, keyword_init: true) do
+      # confidential clients (nil for public clients);
+      # `registration_access_token` the one-time RFC 7592 credential (nil until
+      # migration 20261020120000 has run, and on update).
+      Result = Struct.new(:client, :client_secret, :token_endpoint_auth_method, :registration_access_token, keyword_init: true) do
         def success? = true
         def value = client
       end
 
       # @param metadata [Hash] RFC 7591 client metadata (symbolized or stringified keys)
-      def initialize(metadata)
-        @metadata = (metadata || {}).to_h.symbolize_keys
+      # @param request [ActionDispatch::Request, nil] handed to the owner and
+      #   attributes callables
+      # Accepts the document positionally or as keywords (`call(redirect_uris:
+      # [...])`), since a bare Hash literal binds to keywords in Ruby 3.
+      def initialize(metadata = nil, request: nil, **document)
+        @metadata = (metadata || {}).to_h.merge(document).symbolize_keys
+        @request = request
+      end
+
+      def self.call(metadata = nil, request: nil, **document)
+        new(metadata, request: request, **document).call
       end
 
-      def self.call(metadata)
-        new(metadata).call
+      # RFC 7592 §2.2: apply `metadata` to an already-registered `client`.
+      # Only the client-shaped members change (client_name, redirect_uris,
+      # grant_types, response_types, and scope unless pinned); the pinned
+      # attributes, client_type, PKCE and the registration access token do not.
+      # A `client_id` in the document must match; a `token_endpoint_auth_method`
+      # must match the client's type (there is no secret rotation here).
+      def self.update(client, metadata = nil, request: nil, **document)
+        new(metadata, request: request, **document).update(client)
+      end
+
+      # RFC 7592 §2.3: the client stops being usable. Deactivated rather than
+      # deleted so the refresh_token grant and introspection can say "gone"
+      # (0.48.0 liveness); its live refresh tokens are revoked and its unused
+      # authorization codes removed. The purge job deletes the row later.
+      def self.deregister(client)
+        now = Time.current
+        StandardId::ClientApplication.transaction do
+          client.deactivate!
+          client.authorization_codes.where(consumed_at: nil).delete_all
+          if StandardId::RefreshToken.client_binding_column?
+            client.refresh_tokens.where(revoked_at: nil).update_all(revoked_at: now)
+          end
+        end
+        client
       end
 
       def call
         attrs = mapped_attributes
+        registration_access_token = nil
+        if StandardId::ClientApplication.registration_management_column?
+          registration_access_token = SecureRandom.urlsafe_base64(REGISTRATION_ACCESS_TOKEN_BYTES)
+          attrs[:registration_access_token_digest] =
+            StandardId::ClientApplication.digest_registration_access_token(registration_access_token)
+        end
         client = StandardId::ClientApplication.new(attrs)
 
         secret_plaintext = nil
@@ -61,17 +110,43 @@ module StandardId
           end
         end
 
-        Result.new(client: client, client_secret: secret_plaintext, token_endpoint_auth_method: auth_method)
+        Result.new(client: client, client_secret: secret_plaintext, token_endpoint_auth_method: auth_method,
+          registration_access_token: registration_access_token)
+      rescue ActiveRecord::RecordInvalid => e
+        raise_for(e.record)
+      end
+
+      def update(client)
+        if metadata[:client_id].present? && metadata[:client_id].to_s != client.client_id
+          raise StandardId::InvalidClientMetadataError, "client_id does not match the client being updated"
+        end
+
+        requested_method = metadata[:token_endpoint_auth_method].to_s.strip
+        if requested_method.present? && (requested_method == PUBLIC_AUTH_METHOD) != client.public?
+          raise StandardId::InvalidClientMetadataError,
+            "token_endpoint_auth_method cannot change a client between public and confidential"
+        end
+
+        attrs = {
+          name: client_name,
+          redirect_uris: redirect_uris,
+          grant_types: grant_types,
+          response_types: response_types
+        }
+        attrs[:scopes] = scope unless pinned.key?("scopes") || metadata[:scope].blank?
+
+        client.update!(attrs)
+        Result.new(client: client, token_endpoint_auth_method: client.token_endpoint_auth_method)
       rescue ActiveRecord::RecordInvalid => e
         raise_for(e.record)
       end
 
       private
 
-      attr_reader :metadata
+      attr_reader :metadata, :request
 
       def mapped_attributes
-        {
+        attrs = {
           owner: resolve_owner!,
           name: client_name,
           redirect_uris: redirect_uris,
@@ -81,8 +156,35 @@ module StandardId
           client_type: client_type,
           require_pkce: require_pkce?,
           code_challenge_methods: code_challenge_methods,
-          require_consent: true
+          require_consent: pinned.fetch("require_consent", true)
         }
+        attrs[:metadata] = pinned["metadata"].to_h.stringify_keys if pinned["metadata"].present?
+        %w[access_token_lifetime authorization_code_lifetime description].each do |key|
+          attrs[key.to_sym] = pinned[key] if pinned.key?(key)
+        end
+        attrs
+      end
+
+      # `config.oauth.dynamic_registration_attributes`, resolved for this
+      # registration, keys stringified. An unknown key is a host bug.
+      def pinned
+        return @pinned if defined?(@pinned)
+
+        configured = StandardId.config.oauth.dynamic_registration_attributes
+        if configured.respond_to?(:call)
+          args = StandardId::Utils::CallableParameterFilter.filter(configured, { metadata: metadata, request: request })
+          configured = configured.call(**args)
+        end
+        resolved = (configured || {}).to_h.transform_keys(&:to_s)
+
+        unknown = resolved.keys - PINNABLE_ATTRIBUTES
+        if unknown.any?
+          raise StandardId::ConfigurationError,
+            "oauth.dynamic_registration_attributes has unknown key(s) #{unknown.inspect}; " \
+            "allowed: #{PINNABLE_ATTRIBUTES.join(', ')}"
+        end
+
+        @pinned = resolved
       end
 
       # redirect_uris is REQUIRED (RFC 7591 §2). We pass the raw value through to
@@ -125,9 +227,22 @@ module StandardId
         requested.join(" ")
       end
 
+      # Pinned scopes win over whatever was requested; a pinned audience with
+      # a scope vocabulary is the next best server-side answer; only then the
+      # requested scope.
       def scope
-        scope = metadata[:scope].to_s.strip
-        scope.presence || DEFAULT_SCOPE
+        if pinned.key?("scopes")
+          return Array(pinned["scopes"]).flat_map { |v| v.to_s.split }.reject(&:blank?).uniq.join(" ")
+        end
+
+        audience = pinned.dig("metadata", "audience") || pinned.dig("metadata", :audience)
+        if audience.present?
+          vocabulary = StandardId::Oauth::AudienceScopeResolver.scopes_for(audience: audience.to_s)
+          return vocabulary.join(" ") if vocabulary.any?
+        end
+
+        requested = metadata[:scope].to_s.strip
+        requested.presence || DEFAULT_SCOPE
       end
 
       def auth_method
@@ -152,12 +267,24 @@ module StandardId
 
       def client_type
         method = auth_method
-        return "public" if method == PUBLIC_AUTH_METHOD
-        return "confidential" if CONFIDENTIAL_AUTH_METHODS.include?(method)
+        allowed = allowed_auth_methods
+        unless allowed.include?(method)
+          raise StandardId::InvalidClientMetadataError,
+            "Unsupported token_endpoint_auth_method: #{method.inspect}. " \
+            "Allowed: #{allowed.join(', ')}"
+        end
+
+        method == PUBLIC_AUTH_METHOD ? "public" : "confidential"
+      end
+
+      # `config.oauth.dynamic_registration_auth_methods` ∩ what the gem supports.
+      def allowed_auth_methods
+        configured = Array(StandardId.config.oauth.dynamic_registration_auth_methods).map(&:to_s)
+        allowed = configured & SUPPORTED_AUTH_METHODS
+        return allowed if allowed.any?
 
-        raise StandardId::InvalidClientMetadataError,
-          "Unsupported token_endpoint_auth_method: #{method.inspect}. " \
-          "Allowed: #{SUPPORTED_AUTH_METHODS.join(', ')}"
+        raise StandardId::ConfigurationError,
+          "oauth.dynamic_registration_auth_methods must include at least one of #{SUPPORTED_AUTH_METHODS.join(', ')}"
       end
 
       # Public clients are always forced onto PKCE/S256 (the model also validates
@@ -179,7 +306,8 @@ module StandardId
             "(e.g. -> { Organization.default })"
         end
 
-        owner = resolver.call
+        args = StandardId::Utils::CallableParameterFilter.filter(resolver, { metadata: metadata, request: request })
+        owner = resolver.call(**args)
         if owner.nil?
           raise StandardId::ConfigurationError,
             "oauth.dynamic_registration_owner resolved to nil; it must return the " \

data/lib/standard_id/oauth/direct_mint_flow.rb

@@ -0,0 +1,128 @@
+module StandardId
+  module Oauth
+    # The grant behind StandardId::TokenMinter: a token for an account the host
+    # has ALREADY authenticated by its own means (an operator console, a
+    # service-to-service mint, a self-service "mint me a token" tool), minted
+    # through the same pipeline as every other grant — audience validation,
+    # audience → profile binding, scope_claims / claim_resolvers,
+    # custom_claims, OAUTH_TOKEN_ISSUING / OAUTH_TOKEN_ISSUED (so AccountStatus
+    # and AccountLocking refuse, and audit sees it), optional refresh token and
+    # session persistence.
+    #
+    # Deliberately NOT reachable from /oauth/token: TokensController maps
+    # grant_type strings to flows explicitly, and this one is never in that
+    # map. The caller supplies the account; the flow authenticates nothing.
+    class DirectMintFlow < TokenGrantFlow
+      def initialize(account:, audience:, grant_type:, scopes: nil, client_id: nil, claims: {}, expires_in: nil,
+        refresh_token: false, request: nil, auth_method: nil, auth_provider: nil)
+        super({ audience: audience }, request || NullRequest.new)
+        @account = account
+        @audience = audience
+        @grant_type = grant_type.to_s
+        @scopes = normalize_scopes(scopes)
+        @client_id = client_id.presence&.to_s
+        @claims = claims.to_h.symbolize_keys
+        @expires_in = expires_in
+        @refresh_token = refresh_token
+        @request_given = !request.nil?
+        @auth_method = auth_method
+        @auth_provider = auth_provider
+      end
+
+      # Public so TokenMinter can report the jti the audit event carried.
+      def issued_jti
+        @issued_jti
+      end
+
+      def authenticate!
+        raise StandardId::InvalidGrantError, "Account is required" if @account.nil?
+        raise StandardId::InvalidGrantError, "Account must be persisted" unless @account.respond_to?(:persisted?) && @account.persisted?
+        raise StandardId::InvalidRequestError, "grant_type is required" if @grant_type.blank?
+        # The refresh grant matches the token's client_id against the one the
+        # caller presents, so a refreshable token with none could never be
+        # redeemed.
+        if @refresh_token && @client_id.nil?
+          raise StandardId::InvalidRequestError, "client_id is required for a refreshable token"
+        end
+        if !@expires_in.nil? && @expires_in.to_i <= 0
+          raise StandardId::InvalidRequestError, "expires_in must be a positive number of seconds"
+        end
+      end
+
+      private
+
+      # No new authentication happened here: the host vouches for the account.
+      def login_method_policy_context
+        nil
+      end
+
+      def subject_id = @account.id
+      def client_id = @client_id
+      def token_scope = @scopes
+      def grant_type = @grant_type
+      def audience = @audience
+      def token_account = @account
+      def supports_refresh_token? = @refresh_token
+
+      def token_client
+        return nil if @client_id.nil?
+
+        super
+      end
+
+      # An explicit lifetime wins (validated positive in authenticate!);
+      # otherwise the configured lifetime for this grant_type key, falling
+      # back to default_token_lifetime.
+      def token_expiry
+        return @expires_in.to_i.seconds unless @expires_in.nil?
+
+        super
+      end
+
+      # What the host says about how it authenticated the account, recorded on
+      # the refresh token so a restrictive login_method_policy can judge a
+      # later refresh; nil is recorded as :unspecified, which such a policy
+      # refuses — so pass it when a policy is configured.
+      def refresh_token_auth_lineage
+        StandardId::AuthLineage.build(@auth_method, @auth_provider)
+      end
+
+      # Resolvers and custom_claims see `request: nil` for a sessionless mint,
+      # not the internal stand-in, so a `request&.…` guard takes the nil path.
+      def claim_resolvers_context
+        @claim_resolvers_context ||= super.merge(request: @request_given ? request : nil)
+      end
+
+      # Host-supplied claims ride on top of the standard payload and the
+      # resolver-derived claims, but can never override a reserved JWT key or a
+      # base session field (same rule as config.oauth.custom_claims).
+      def build_jwt_payload(expires_in)
+        extra = @claims.except(*StandardId::JwtService::RESERVED_JWT_KEYS, *StandardId::JwtService::BASE_SESSION_FIELDS)
+        super(expires_in).merge(extra).compact
+      end
+
+      # A session is only materialised when the caller passed a real request:
+      # the resolver and OauthSessionPersistence read remote_ip / user_agent
+      # from it, and a programmatic mint with no request has no client to
+      # describe. Machine-to-machine stays sessionless, as client_credentials is.
+      def maybe_persist_session_for_token!
+        return nil unless @request_given
+
+        super
+      end
+
+      def normalize_scopes(scopes)
+        list = Array(scopes).flat_map { |s| s.to_s.split(/\s+/) }.reject(&:blank?).uniq
+        list.empty? ? nil : list.join(" ")
+      end
+
+      # What the flow reads from a request when the caller gave none.
+      class NullRequest
+        def remote_ip = nil
+        def user_agent = nil
+        def params = {}
+        def headers = {}
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/implicit_authorization_flow.rb

@@ -2,7 +2,7 @@ module StandardId
   module Oauth
     class ImplicitAuthorizationFlow < AuthorizationFlow
       expect_params :client_id
-      permit_params :audience, :scope, :state, :redirect_uri, :nonce, :connection, :prompt, :organization, :invitation
+      permit_params :audience, :resource, :scope, :state, :redirect_uri, :nonce, :connection, :prompt, :organization, :invitation
 
       private
 

data/lib/standard_id/oauth/protected_resource_document.rb

@@ -0,0 +1,171 @@
+module StandardId
+  module Oauth
+    # RFC 9728 OAuth 2.0 Protected Resource Metadata, and the RFC 6750
+    # `WWW-Authenticate` challenge that points clients at it.
+    #
+    # A host declares the resources it serves, keyed by the audience their
+    # tokens carry:
+    #
+    #   c.oauth.protected_resources = {
+    #     "mcp" => {
+    #       path: "/mcp",                           # required: where the resource lives
+    #       scopes_supported: %w[mcp mcp:read],     # default: audience_scopes["mcp"]
+    #       authorization_servers: [...],           # default: [issuer || origin]
+    #       bearer_methods_supported: %w[header],   # default
+    #       resource_name: "Example MCP server"     # any other RFC 9728 member
+    #     }
+    #   }
+    #
+    # `path` may also be an absolute URL for a resource served from another
+    # origin. Any member may be a callable taking one Hash
+    # `{ origin:, audience:, issuer:, request: }`; a nil value removes the member.
+    #
+    # The document for a resource is served at
+    # `<origin>/.well-known/oauth-protected-resource<path>` (RFC 9728 §3.1,
+    # the path-inserted form that is the exact URL the challenge names) by
+    # `standard_id_protected_resource_routes` in the host's routes file, and the
+    # bare `/.well-known/oauth-protected-resource` serves the only configured
+    # resource (or the one marked `root: true`) for clients probing the root
+    # form. The engine also serves both under its own mount.
+    #
+    # Everything here is a pure function of config and an origin so it can be
+    # used from the controller, from StandardId::ResourceServer, and from tests
+    # without a request.
+    #
+    # The origin is the request's (`request.base_url`), on purpose: RFC 9728
+    # §3.3 requires `resource` to equal the identifier the client used, and the
+    # challenge must name a URL on the host the client is talking to. That
+    # makes the document only as trustworthy as the `Host` header, so a host
+    # must pin it (`config.hosts`, or the proxy) — the same requirement every
+    # request-derived URL in a Rails app has, stated here because this one is
+    # served with `Cache-Control: public`.
+    module ProtectedResourceDocument
+      WELL_KNOWN_PATH = "/.well-known/oauth-protected-resource".freeze
+      # `resource` is computed, never configured: RFC 9728 §3.3 requires it to
+      # match the URL the client used, which is the request origin plus `path`.
+      RESERVED_KEYS = %w[path root resource].freeze
+
+      module_function
+
+      # @return [Hash{String => Hash}] configured resources, keys stringified
+      def configured
+        (StandardId.config.oauth.protected_resources || {}).to_h.each_with_object({}) do |(audience, entry), acc|
+          acc[audience.to_s] = (entry || {}).to_h.transform_keys(&:to_s)
+        end
+      end
+
+      # @return [Boolean] whether `audience` names a configured resource
+      def configured?(audience)
+        audience.present? && configured.key?(audience.to_s)
+      end
+
+      # The audience whose `path` is `path` (compared with the trailing slash
+      # removed), or nil.
+      def audience_for_path(path)
+        wanted = normalize_path(path)
+        return nil if wanted.empty?
+
+        configured.each do |audience, entry|
+          return audience if normalize_path(entry["path"]) == wanted
+        end
+        nil
+      end
+
+      # The audience served at the bare well-known URL: the only one configured,
+      # else the one marked `root: true`, else nil.
+      def default_audience
+        all = configured
+        return all.keys.first if all.size == 1
+
+        all.each { |audience, entry| return audience if entry["root"] }
+        nil
+      end
+
+      # Absolute URL of the resource (RFC 9728 `resource`).
+      def resource_url(audience:, origin:)
+        path = path_for!(audience)
+        return path.chomp("/") if absolute?(path)
+
+        "#{origin.to_s.chomp('/')}#{normalize_path(path)}"
+      end
+
+      # Absolute URL of this resource's metadata document — the value the
+      # `resource_metadata` challenge parameter carries. Raises for an
+      # unconfigured audience rather than naming a bare URL that would serve
+      # another resource's document (or nothing).
+      def metadata_url(audience:, origin:)
+        path = path_for!(audience)
+        suffix = absolute?(path) ? normalize_path(URI.parse(path).path) : normalize_path(path)
+        "#{origin.to_s.chomp('/')}#{WELL_KNOWN_PATH}#{suffix}"
+      end
+
+      # @return [String] the configured path
+      # @raise [StandardId::ConfigurationError] when the audience is not
+      #   configured or its entry has no path
+      def path_for!(audience)
+        entry = configured[audience.to_s]
+        raise StandardId::ConfigurationError, "oauth.protected_resources has no entry for #{audience.inspect}" if entry.nil?
+
+        path = entry["path"].to_s
+        raise StandardId::ConfigurationError, "oauth.protected_resources[#{audience.inspect}] has no :path" if path.blank?
+
+        path
+      end
+
+      # @return [Hash] the RFC 9728 document for `audience`
+      # @raise [StandardId::ConfigurationError] when the audience is not configured
+      def build(audience:, origin:, request: nil)
+        entry = configured[audience.to_s]
+        raise StandardId::ConfigurationError, "oauth.protected_resources has no entry for #{audience.inspect}" if entry.nil?
+
+        context = { origin: origin, audience: audience.to_s, issuer: StandardId::Oauth::DiscoveryResolver.issuer, request: request }
+        doc = {
+          resource: resource_url(audience: audience, origin: origin),
+          authorization_servers: [StandardId::Oauth::DiscoveryResolver.issuer.presence || origin.to_s.chomp("/")],
+          bearer_methods_supported: %w[header]
+        }
+        scopes = StandardId::Oauth::AudienceScopeResolver.scopes_for(audience: audience.to_s)
+        doc[:scopes_supported] = scopes if scopes.any?
+
+        entry.each do |key, value|
+          next if RESERVED_KEYS.include?(key)
+
+          resolved = value.respond_to?(:call) ? value.call(context) : value
+          if resolved.nil?
+            doc.delete(key.to_sym)
+          else
+            doc[key.to_sym] = resolved
+          end
+        end
+        doc
+      end
+
+      # RFC 6750 §3 `WWW-Authenticate` value carrying the RFC 9728
+      # `resource_metadata` pointer. `error` is one of the three RFC 6750 codes;
+      # `scope` lists the scopes the resource needed (insufficient_scope).
+      # Quoted values are limited to the RFC 6750 quoted-string charset; a
+      # description that breaks it is dropped rather than emitted broken.
+      def challenge(audience:, origin:, error: "invalid_token", error_description: nil, scope: nil)
+        parts = [%(realm="#{audience}")]
+        parts << %(error="#{error}") if error.present?
+        parts << %(error_description="#{error_description}") if error_description.present? && quotable?(error_description)
+        parts << %(scope="#{Array(scope).join(' ')}") if Array(scope).any?
+        parts << %(resource_metadata="#{metadata_url(audience: audience, origin: origin)}")
+        "Bearer #{parts.join(', ')}"
+      end
+
+      def quotable?(value)
+        !value.to_s.match?(/["\\\r\n]/)
+      end
+
+      def absolute?(path)
+        path.to_s.match?(%r{\Ahttps?://}i)
+      end
+
+      # "" or "/foo" — never "/" and never a trailing slash.
+      def normalize_path(path)
+        StandardId::Oauth::DiscoveryResolver.normalize_path(path)
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -7,7 +7,7 @@ module StandardId
       MAX_REUSE_LEEWAY_SECONDS = 120
 
       expect_params :refresh_token, :client_id
-      permit_params :client_secret, :scope, :audience
+      permit_params :client_secret, :scope, :audience, :resource
 
       # authenticate! runs outside the transaction so reuse-detection
       # revocations (revoke_family!) persist even when the error propagates.

data/lib/standard_id/routing.rb

@@ -99,6 +99,27 @@ module StandardId
       end
     end
 
+    # Draw the RFC 9728 protected-resource metadata at the ORIGIN ROOT:
+    #
+    #   /.well-known/oauth-protected-resource            (the default resource)
+    #   /.well-known/oauth-protected-resource/<path>     (RFC 9728 §3.1, per resource)
+    #
+    # One glob route; which resource a path names is decided per request from
+    # `config.oauth.protected_resources`, so adding a resource is a config
+    # change, not a routes change. The second form is the exact URL the
+    # `WWW-Authenticate resource_metadata` challenge from
+    # StandardId::ResourceServer carries.
+    #
+    #   # config/routes.rb
+    #   standard_id_well_known_routes at: "/api"
+    #   standard_id_protected_resource_routes
+    def standard_id_protected_resource_routes
+      get ".well-known/oauth-protected-resource(/*resource_path)",
+        to: "standard_id/api/well_known/oauth_protected_resource#show",
+        as: :standard_id_root_oauth_protected_resource,
+        format: false
+    end
+
     # @return [Hash] the WELL_KNOWN_DOCUMENTS entries `only:`/`except:` select
     def self.selected_documents(only: nil, except: nil)
       if only.present? && except.present?

data/lib/standard_id/token_minter.rb

@@ -0,0 +1,74 @@
+module StandardId
+  # Mint an access token (and optionally a refresh token) for an account the
+  # host has already authenticated, through the same pipeline /oauth/token
+  # uses — so the claims, the audience → profile binding, the account-status
+  # guards and the OAUTH_TOKEN_ISSUING / OAUTH_TOKEN_ISSUED events are the ones
+  # every other token gets, instead of a hand-rolled JwtService.encode that
+  # re-derives the initializer's claim resolvers by hand.
+  #
+  #   result = StandardId::TokenMinter.mint(
+  #     account: account,
+  #     audience: "harness",
+  #     scopes: "profile permissions",
+  #     grant_type: "harness.mint",       # free-form; lands in the JWT and the audit event
+  #     claims: { permissions: scopes },  # host extras; reserved keys are dropped
+  #     expires_in: 60.minutes
+  #   )
+  #   result.access_token  # the JWT
+  #   result.jti           # what OAUTH_TOKEN_ISSUED carried
+  #
+  # What runs, in order: audience validation (oauth.allowed_audiences),
+  # audience → profile binding (oauth.audience_profile_types, fail-closed),
+  # OAUTH_TOKEN_ISSUING (AccountStatus / AccountLocking refuse here),
+  # scope_claims + claim_resolvers and custom_claims, then the host's own
+  # +claims+, then OAUTH_TOKEN_ISSUED. A refresh token is persisted only when
+  # +refresh_token: true+, bound to +client_id+'s ClientApplication when that
+  # names one. Pass +request:+ to let config.session.session_type_resolver
+  # materialise a session; without it the mint is sessionless.
+  #
+  # Raises the same errors the token endpoint would (InvalidGrantError,
+  # InvalidRequestError, NoBoundProfileError, AccountDeactivatedError, …).
+  module TokenMinter
+    Result = Data.define(:access_token, :refresh_token, :token_type, :expires_in, :scope, :jti)
+
+    module_function
+
+    # @param account [ActiveRecord::Base] a persisted account
+    # @param audience [String, Array<String>] the `aud` claim
+    # @param grant_type [String] recorded in the JWT and the audit events
+    # @param scopes [String, Array<String>, nil] the `scope` claim and the key
+    #   into oauth.scope_claims
+    # @param client_id [String, nil] the `client_id` claim; a registered
+    #   ClientApplication's id binds the refresh token to it
+    # @param claims [Hash] extra claims merged last (reserved keys dropped)
+    # @param expires_in [Integer, ActiveSupport::Duration, nil] access-token
+    #   lifetime; default is oauth.token_lifetimes[grant_type] or
+    #   oauth.default_token_lifetime
+    # @param refresh_token [Boolean] also persist and return a refresh token;
+    #   requires +client_id+, which the refresh grant matches on redemption
+    # @param request [ActionDispatch::Request, nil] lets session_type_resolver
+    #   persist a session; resolvers see `request: nil` without it
+    # @param auth_method [Symbol, String, nil] how the host authenticated the
+    #   account, recorded on the refresh token for login_method_policy; nil is
+    #   judged as :unspecified on refresh, which a restrictive policy refuses
+    # @param auth_provider [String, nil]
+    # @return [Result]
+    def mint(account:, audience:, grant_type:, scopes: nil, client_id: nil, claims: {}, expires_in: nil,
+      refresh_token: false, request: nil, auth_method: nil, auth_provider: nil)
+      flow = StandardId::Oauth::DirectMintFlow.new(
+        account: account, audience: audience, grant_type: grant_type, scopes: scopes, client_id: client_id,
+        claims: claims, expires_in: expires_in, refresh_token: refresh_token, request: request,
+        auth_method: auth_method, auth_provider: auth_provider
+      )
+      response = flow.execute
+      Result.new(
+        access_token: response[:access_token],
+        refresh_token: response[:refresh_token],
+        token_type: response[:token_type],
+        expires_in: response[:expires_in],
+        scope: response[:scope],
+        jti: flow.issued_jti
+      )
+    end
+  end
+end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.48.1"
+  VERSION = "0.49.0"
 end