himari 0.4.0 → 0.6.0

data/lib/himari/rule_processor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Himari
   class RuleProcessor
     class MissingDecisionError < StandardError; end
@@ -40,6 +42,7 @@ module Himari
 
       rule.call(context, decision)
       raise MissingDecisionError, "rule '#{rule.name}' returned no decision; rule must use one of decision.allow!, deny!, continue!, skip!" unless decision.effect
+
       result.decision_log.push(decision)
 
       case decision.effect

data/lib/himari/services/client_registration_endpoint.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rack/request'
+require 'himari/log_line'
+require 'himari/dynamic_client_registration'
+
+module Himari
+  module Services
+    # RFC 7591 OAuth 2.0 Dynamic Client Registration endpoint. Accepts a JSON client metadata
+    # document via POST, persists a Himari::DynamicClientRegistration, and returns the client
+    # information response (including a one-time client_secret for confidential clients).
+    class ClientRegistrationEndpoint
+      # @param storage [Himari::Storages::Base]
+      # @param registration_lifetime [Integer] seconds a registration stays valid
+      # @param ignore_localhost_redirect_uri_port [Boolean] relax loopback redirect_uri ports for
+      #   registered clients (default true; see RFC 8252 §7.3)
+      # @param logger [Logger, nil]
+      def initialize(storage:, registration_lifetime: Himari::DynamicClientRegistration::REGISTRATION_LIFETIME, ignore_localhost_redirect_uri_port: true, logger: nil)
+        @storage = storage
+        @registration_lifetime = registration_lifetime
+        @ignore_localhost_redirect_uri_port = ignore_localhost_redirect_uri_port
+        @logger = logger
+      end
+
+      def app
+        self
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        return error_response(405, :invalid_request, 'method not allowed') unless request.post?
+
+        metadata = parse_body(request)
+        return error_response(400, :invalid_client_metadata, 'request body must be a JSON object') unless metadata
+
+        client = Himari::DynamicClientRegistration.register(
+          metadata: metadata,
+          lifetime: @registration_lifetime,
+          ignore_localhost_redirect_uri_port: @ignore_localhost_redirect_uri_port,
+          registration_ip: request.ip,
+          registration_remote_addr: env['REMOTE_ADDR'],
+          registration_x_forwarded_for: env['HTTP_X_FORWARDED_FOR'],
+        )
+        @storage.put_dynamic_client(client)
+
+        @logger&.info(Himari::LogLine.new('ClientRegistrationEndpoint: registered', req: env['himari.request_as_log'], client: client.as_log))
+
+        json_response(201, client.registration_response)
+      rescue Himari::DynamicClientRegistration::ValidationError => e
+        @logger&.warn(Himari::LogLine.new('ClientRegistrationEndpoint: rejected', req: env['himari.request_as_log'], err: e.error_code, message: e.message))
+        error_response(400, e.error_code, e.message)
+      end
+
+      private def parse_body(request)
+        return unless request.media_type == 'application/json'
+
+        body = request.body.read
+        parsed = JSON.parse(body, symbolize_names: true)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      private def json_response(status, body)
+        [
+          status,
+          {'Content-Type' => 'application/json', 'Cache-Control' => 'no-store', 'Pragma' => 'no-cache'},
+          [JSON.generate(body), "\n"],
+        ]
+      end
+
+      private def error_response(status, error, description)
+        json_response(status, {error: error, error_description: description})
+      end
+    end
+  end
+end

data/lib/himari/services/downstream_authorization.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/decisions/authorization'
 require 'himari/middlewares/authorization_rule'
 require 'himari/rule_processor'
@@ -21,11 +23,13 @@ module Himari
         end
       end
 
-      Result = Struct.new(:client, :claims, :lifetime, :authz_result) do
+      Result = Struct.new(:client, :claims, :scopes, :lifetime, :mint_jwt_access_token, :authz_result) do
         def as_log
           {
             client: client.as_log,
             claims: claims,
+            scopes: scopes,
+            mint_jwt_access_token: mint_jwt_access_token,
             decision: {
               authorization: authz_result.as_log,
             },
@@ -35,13 +39,19 @@ module Himari
 
       # @param session [Himari::SessionData]
       # @param client [Himari::ClientRegistration]
-      # @param request [Rack::Request]
+      # @param request [Rack::Request] exposed to rules as context.request (an escape hatch); the
+      #   engine never reads it, so requested scopes are supplied explicitly, never derived from it.
+      # @param requested_scopes [Array<String>] scopes asked for, before the client's allow-list
+      #   filter. The caller supplies them from the appropriate source: the authorization endpoint
+      #   passes the request's parsed scope, the refresh flow the scopes recorded on the grant.
       # @param authz_rules [Array<Himari::Rule>] Authorization Rules
       # @param logger [Logger]
-      def initialize(session:, client:, request: nil, authz_rules: [], logger: nil)
+      def initialize(session:, client:, requested_scopes:, grant_type: :initial, request: nil, authz_rules: [], logger: nil)
         @session = session
         @client = client
+        @grant_type = grant_type
         @request = request
+        @requested_scopes = requested_scopes
         @authz_rules = authz_rules
         @logger = logger
       end
@@ -49,25 +59,30 @@ module Himari
       # @param session [Himari::SessionData]
       # @param client [Himari::ClientRegistration]
       # @param request [Rack::Request]
-      def self.from_request(session:, client:, request:)
+      # @param requested_scopes [Array<String>] see #initialize; always supplied by the caller
+      def self.from_request(session:, client:, request:, requested_scopes:, grant_type: :initial)
         new(
           session: session,
           client: client,
+          grant_type: grant_type,
           request: request,
+          requested_scopes: requested_scopes,
           authz_rules: Himari::ProviderChain.new(request.env[Himari::Middlewares::AuthorizationRule::RACK_KEY] || []).collect,
           logger: request.env['rack.logger'],
         )
       end
 
       def perform
-        context = Himari::Decisions::Authorization::Context.new(claims: @session.claims, user_data: @session.user_data, request: @request, client: @client).freeze
+        scopes = @client.filter_scopes(@requested_scopes)
+        context = Himari::Decisions::Authorization::Context.new(claims: @session.claims, user_data: @session.user_data, request: @request, client: @client, scopes: scopes, grant_type: @grant_type).freeze
 
         authorization = Himari::RuleProcessor.new(context, Himari::Decisions::Authorization.new(claims: @session.claims.dup)).run(@authz_rules)
-        raise ForbiddenError.new(Result.new(@client, nil, nil, authorization)) unless authorization.allowed
+        raise ForbiddenError.new(Result.new(@client, nil, scopes, nil, nil, authorization)) unless authorization.allowed
 
         claims = authorization.decision.output_claims
         lifetime = authorization.decision.lifetime
-        Result.new(@client, claims, lifetime, authorization)
+        mint_jwt_access_token = authorization.decision.mint_jwt_access_token
+        Result.new(@client, claims, scopes, lifetime, mint_jwt_access_token, authorization)
       end
     end
   end

data/lib/himari/services/jwks_endpoint.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Himari
   module Services
     class JwksEndpoint
@@ -26,7 +28,7 @@ module Himari
           # https://www.rfc-editor.org/rfc/rfc7517#section-5
           return [404, {'Content-Type' => 'application/json'}, ['{"error": "not_found"}']] unless @env['REQUEST_METHOD'] == 'GET'
 
-          signing_keys = @signing_key_provider.collect()
+          signing_keys = @signing_key_provider.collect
 
           [
             200,

data/lib/himari/services/oidc_authorization_endpoint.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rack/oauth2'
 require 'digest/sha2'
 require 'openid_connect'
@@ -7,16 +9,30 @@ module Himari
     class OidcAuthorizationEndpoint
       class ReauthenticationRequired < StandardError; end
 
+      # Raised when the user must be shown the consent page before a code is granted. Carries the
+      # data the page renders (the requesting client and the requested scopes); app.rb rescues it.
+      class ConsentRequired < StandardError
+        def initialize(client:, scopes:)
+          @client = client
+          @scopes = scopes
+          super('consent required')
+        end
+
+        attr_reader :client, :scopes
+      end
+
       SUPPORTED_RESPONSE_TYPES = ['code'] # TODO: share with oidc metadata
 
       # @param authz [Himari::AuthorizationCode] pending (unpersisted) authz data
       # @param client [Himari::ClientRegistration]
       # @param storage [Himari::Storages::Base]
+      # @param consent [:approve, :deny, nil] the user's consent decision (nil = not yet asked)
       # @param logger [Logger]
-      def initialize(authz:, client:, storage:, logger: nil)
+      def initialize(authz:, client:, storage:, consent: nil, logger: nil)
         @authz = authz
         @client = client
         @storage = storage
+        @consent = consent
         @logger = logger
       end
 
@@ -37,13 +53,46 @@ module Himari
             next req.bad_request!
           end
           raise "[BUG] client.id != authz.cilent_id" unless @authz.client_id == @client.id
-          res.redirect_uri = req.verify_redirect_uri!(@client.redirect_uris)
+
+          given_redirect_uri = req.redirect_uri&.to_s
+          res.redirect_uri = if given_redirect_uri && !given_redirect_uri.empty?
+            # Raise before recording the redirect_uri so we never redirect errors to an unverified URI.
+            next req.bad_request!(:invalid_request, '"redirect_uri" mismatch') unless @client.redirect_uri_covers?(given_redirect_uri)
+
+            given_redirect_uri
+          elsif @client.redirect_uris.size == 1 && @client.redirect_uris.first.is_a?(String)
+            @client.redirect_uris.first
+          else
+            next req.bad_request!(:invalid_request, '"redirect_uri" missing')
+          end
+          # rack-oauth2 redirects subsequent errors back to the verified redirect_uri via this accessor.
+          req.verified_redirect_uri = res.redirect_uri
 
           req.unsupported_response_type! if res.protocol_params_location == :fragment
           req.bad_request!(:request_uri_not_supported, "Request Object is not implemented") if req.request_uri || req.request
           req.bad_request!(:invalid_request, 'prompt=none should not contain any other value') if req.prompt.include?('none') && req.prompt.any? { |x| x != 'none' }
           raise ReauthenticationRequired if req.prompt.include?('login') || req.prompt.include?('select_account')
 
+          # Drop scopes this client does not recognise before they reach consent or the grant.
+          scopes = @client.filter_scopes(req.scope)
+
+          # Consent gate. Clients granted skip_consent (the default for dynamically/metadata-
+          # registered clients) bypass it; prompt=consent forces the page regardless.
+          if !@client.skip_consent || req.prompt.include?('consent')
+            case @consent
+            when :approve
+              # consent given; fall through and grant
+            when :deny
+              next req.access_denied!
+            else
+              # prompt=none forbids interaction (OIDC §3.1.2.1), so surface the error via redirect
+              # instead of rendering the page.
+              next req.consent_required! if req.prompt.include?('none')
+
+              raise ConsentRequired.new(client: @client, scopes: scopes)
+            end
+          end
+
           requested_response_types = [*req.response_type]
           unless SUPPORTED_RESPONSE_TYPES.include?(requested_response_types.map(&:to_s).join(' '))
             next req.unsupported_response_type!
@@ -53,11 +102,15 @@ module Himari
             @authz.redirect_uri = res.redirect_uri
             @authz.nonce = req.nonce
 
-            @authz.openid = req.scope.include?('openid')
+            @authz.scopes = scopes
+            @authz.openid = scopes.include?('openid')
+            @authz.offline_access = scopes.include?('offline_access')
             if req.code_challenge && req.code_challenge_method
               @authz.code_challenge = req.code_challenge
               @authz.code_challenge_method = req.code_challenge_method || 'plain'
               next req.bad_request!(:invalid_request, 'Invalid PKCE parameters') unless @authz.pkce_valid_request?
+            elsif @client.require_pkce
+              next req.bad_request!(:invalid_request, 'PKCE is mandatory')
             end
 
             @storage.put_authorization(@authz)

data/lib/himari/services/oidc_provider_metadata_endpoint.rb

@@ -1,10 +1,24 @@
+# frozen_string_literal: true
+
 module Himari
   module Services
     class OidcProviderMetadataEndpoint
+      # Scopes and claims Himari always advertises; configured values are merged on top.
+      DEFAULT_SCOPES_SUPPORTED = %w(openid offline_access).freeze
+      DEFAULT_CLAIMS_SUPPORTED = %w(sub iss iat nbf exp).freeze
+
       # @param signing_key_provider [Himari::ProviderChain<Himari::SigningKey>]
-      def initialize(signing_key_provider:, issuer:)
+      # @param registration_endpoint [String, nil] advertised when Dynamic Client Registration is enabled
+      # @param client_id_metadata_document_supported [Boolean] advertised when OAuth Client ID Metadata Document support is enabled
+      # @param scopes_supported [Array<String>] extra scopes to advertise alongside the defaults
+      # @param claims_supported [Array<String>] extra claims to advertise alongside the defaults
+      def initialize(signing_key_provider:, issuer:, registration_endpoint: nil, client_id_metadata_document_supported: false, scopes_supported: [], claims_supported: [])
         @signing_key_provider = signing_key_provider
         @issuer = issuer
+        @registration_endpoint = registration_endpoint
+        @client_id_metadata_document_supported = client_id_metadata_document_supported
+        @scopes_supported = scopes_supported
+        @claims_supported = claims_supported
       end
 
       def app
@@ -12,32 +26,41 @@ module Himari
       end
 
       def call(env)
-        Handler.new(signing_key_provider: @signing_key_provider, issuer: @issuer, env: env).response
+        Handler.new(signing_key_provider: @signing_key_provider, issuer: @issuer, registration_endpoint: @registration_endpoint, client_id_metadata_document_supported: @client_id_metadata_document_supported, scopes_supported: @scopes_supported, claims_supported: @claims_supported, env: env).response
       end
 
       class Handler
         class InvalidToken < StandardError; end
 
-        def initialize(signing_key_provider:, issuer:, env:)
+        def initialize(signing_key_provider:, issuer:, env:, registration_endpoint: nil, client_id_metadata_document_supported: false, scopes_supported: [], claims_supported: [])
           @signing_key_provider = signing_key_provider
           @issuer = issuer
+          @registration_endpoint = registration_endpoint
+          @client_id_metadata_document_supported = client_id_metadata_document_supported
+          @scopes_supported = scopes_supported
+          @claims_supported = claims_supported
           @env = env
         end
 
         def metadata
-          signing_keys = @signing_key_provider.collect()
+          signing_keys = @signing_key_provider.collect
           {
             issuer: @issuer,
             authorization_endpoint: "#{@issuer}/oidc/authorize",
             token_endpoint: "#{@issuer}/public/oidc/token",
             userinfo_endpoint: "#{@issuer}/public/oidc/userinfo",
             jwks_uri: "#{@issuer}/public/jwks",
-            scopes_supported: %w(openid),
+            registration_endpoint: @registration_endpoint,
+            client_id_metadata_document_supported: @client_id_metadata_document_supported ? true : nil,
+            scopes_supported: (DEFAULT_SCOPES_SUPPORTED + @scopes_supported).uniq,
             response_types_supported: ['code'], # violation: dynamic OpenID Provider MUST support code, id_token, token+id_token
+            grant_types_supported: %w(authorization_code refresh_token),
+            token_endpoint_auth_methods_supported: %w(client_secret_basic client_secret_post none),
+            code_challenge_methods_supported: %w(S256 plain),
             subject_types_supported: ['public'],
             id_token_signing_alg_values_supported: signing_keys.map(&:alg).uniq.sort,
-            claims_supported: %w(sub iss iat nbf exp),
-          }
+            claims_supported: (DEFAULT_CLAIMS_SUPPORTED + @claims_supported).uniq,
+          }.compact
         end
 
         def response

data/lib/himari/services/oidc_token_endpoint.rb

@@ -1,14 +1,22 @@
+# frozen_string_literal: true
+
 require 'rack/oauth2'
 require 'digest/sha2'
 require 'openid_connect'
 require 'himari/access_token'
+require 'himari/refresh_token'
 require 'himari/id_token'
+require 'himari/storages/base'
+require 'himari/services/downstream_authorization'
+require 'himari/services/upstream_authentication'
 
 module Himari
   module Services
     class OidcTokenEndpoint
       class SigningKeyMissing < StandardError; end
 
+      Issued = Struct.new(:access, :access_token_string, :id_token_jwt, :signing_key, keyword_init: true)
+
       # @param client_provider [Himari::ProviderChain<Himari::ClientRegistration>]
       # @param signing_key_provider [Himari::ProviderChain<Himari::SigningKey>]
       # @param storage [Himari::Storages::Base]
@@ -25,62 +33,241 @@ module Himari
       def call(env)
         app(env).call(env)
       rescue Rack::OAuth2::Server::Abstract::Error => e
-        @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: returning error', req: env['himari.request_as_log'], client: client.as_log, err: e.class.inspect, err_content: e.protocol_params))
+        @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: returning error', req: env['himari.request_as_log'], err: e.class.inspect, err_content: e.protocol_params))
         e.finish
       end
 
       def app(env)
         Rack::OAuth2::Server::Token.new do |req, res|
-          code_dgst = req.code ? Digest::SHA256.hexdigest(req.code) : nil
           client = @client_provider.find(id: req.client_id)
           unless client
-            @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_client, no client registration', req: env['himari.request_as_log'], client_id: req.client_id, code_dgst: code_dgst))
+            @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_client, no client registration', req: env['himari.request_as_log'], client_id: req.client_id))
             next req.invalid_client!
           end
-          unless client.match_secret?(req.client_secret)
-            @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_client, client secret mismatch', req: env['himari.request_as_log'], client: client.as_log, code_dgst: code_dgst))
-            next req.invalid_client! 
+          # Public clients (token_endpoint_auth_method=none) present no secret; they are bound
+          # to the authorization code by PKCE and the client_id check in handle_authorization_code.
+          if client.confidential? && !client.match_secret?(req.client_secret)
+            @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_client, client secret mismatch', req: env['himari.request_as_log'], client: client.as_log))
+            next req.invalid_client!
           end
 
           case req.grant_type
           when :authorization_code
-            authz = @storage.find_authorization(req.code)
-            unless authz
-              @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, no grant code found', req: env['himari.request_as_log'], client: client.as_log))
-              next req.invalid_grant! 
-            end
-            unless authz.valid_redirect_uri?(req.redirect_uri)
-              @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, redirect_uri mismatch', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
-              next req.invalid_grant! 
-            end
-            if authz.expiry <= Time.now.to_i
-              @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, expired grant', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
-              next req.invalid_grant! 
-            end
-            if authz.pkce? && !req.verify_code_verifier!(authz.code_challenge, authz.code_challenge_method)
-              # :nocov:
-              @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, invalid pkce', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
-              next req.invalid_grant!
-              # :nocov:
-            end
-
-            token = AccessToken.from_authz(authz)
-            @storage.put_token(token)
-            res.access_token = token.to_bearer
-
-            if authz.openid
-              signing_key = @signing_key_provider.find(group: client.preferred_key_group, active: true)
-              raise SigningKeyMissing unless signing_key
-              res.id_token = IdToken.from_authz(authz, signing_key: signing_key, access_token: token.format.to_s, issuer: @issuer).to_jwt
-            end
-
-            @storage.delete_authorization(authz)
-            @logger&.info(Himari::LogLine.new('OidcTokenEndpoint: issued', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log, token: token.as_log, signing_key_kid: signing_key&.id))
+            handle_authorization_code(env, req, res, client)
+          when :refresh_token
+            handle_refresh_token(env, req, res, client)
           else
             req.unsupported_response_type!
           end
         end
       end
+
+      private def handle_authorization_code(env, req, res, client)
+        authz = @storage.find_authorization(req.code)
+        unless authz
+          @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, no grant code found', req: env['himari.request_as_log'], client: client.as_log))
+          return req.invalid_grant!
+        end
+        unless authz.client_id == client.id
+          @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, grant client_id mismatch', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
+          return req.invalid_grant!
+        end
+        unless authz.valid_redirect_uri?(req.redirect_uri)
+          @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, redirect_uri mismatch', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
+          return req.invalid_grant!
+        end
+        if authz.expiry <= Time.now.to_i
+          @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, expired grant', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
+          return req.invalid_grant!
+        end
+
+        if authz.pkce?
+          if req.verify_code_verifier!(authz.code_challenge, authz.code_challenge_method)
+            # do nothing
+          else
+            # :nocov:
+            @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, invalid pkce', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
+            return req.invalid_grant!
+            # :nocov:
+          end
+        elsif client.require_pkce
+          @logger&.warn(Himari::LogLine.new('OidcTokenEndpoint: invalid_grant, pkce is mandatory', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log))
+          return req.invalid_grant!
+        end
+
+        issued = issue_access_and_id(
+          client: client,
+          claims: authz.claims,
+          scopes: authz.scopes,
+          lifetime: authz.lifetime,
+          openid: authz.openid,
+          session_handle: authz.session_handle,
+          nonce: authz.nonce,
+          mint_jwt_access_token: authz.mint_jwt_access_token,
+        )
+
+        refresh = nil
+        if authz.offline_access && authz.session_handle && authz.lifetime&.refresh_token
+          refresh = RefreshToken.make(client_id: client.id, claims: authz.claims, session_handle: authz.session_handle, openid: authz.openid, scopes: authz.scopes, lifetime: authz.lifetime.refresh_token)
+          @storage.put_refresh_token(refresh)
+        end
+
+        bearer = issued.access.to_bearer(token_string: issued.access_token_string)
+        bearer.refresh_token = refresh.format.to_s if refresh
+        res.access_token = bearer
+        res.id_token = issued.id_token_jwt if issued.id_token_jwt
+
+        @storage.delete_authorization(authz)
+        @logger&.info(Himari::LogLine.new('OidcTokenEndpoint: issued', req: env['himari.request_as_log'], client: client.as_log, grant: authz.as_log, token: issued.access.as_log, refresh_token: refresh&.as_log, signing_key_kid: issued.signing_key&.id))
+      end
+
+      private def handle_refresh_token(env, req, res, client)
+        given_token_str = req.refresh_token
+        unless given_token_str
+          return reject_refresh!(env, req, client, 'no refresh_token given')
+        end
+
+        begin
+          parsed = Himari::RefreshToken.parse(given_token_str)
+        rescue Himari::TokenString::InvalidFormat => e
+          return reject_refresh!(env, req, client, 'invalid refresh_token format', err: e.class.inspect)
+        end
+
+        refresh = @storage.find_refresh_token(parsed.handle)
+        unless refresh
+          return reject_refresh!(env, req, client, 'unknown refresh_token')
+        end
+
+        begin
+          refresh.verify!(secret: parsed.secret)
+        rescue Himari::TokenString::Error => e
+          return reject_refresh!(env, req, client, 'refresh_token verify failed', refresh: refresh, err: e.class.inspect)
+        end
+
+        unless refresh.client_id == client.id
+          return reject_refresh!(env, req, client, 'refresh_token client_id mismatch', refresh: refresh)
+        end
+
+        session = refresh.session_handle && @storage.find_session(refresh.session_handle)
+        unless session
+          return reject_refresh!(env, req, client, 'refresh_token has no session', refresh: refresh)
+        end
+
+        unless session.refreshable?
+          return reject_refresh!(env, req, client, 'session is not refreshable (no refresh_info)', refresh: refresh, session: session.as_log)
+        end
+
+        unless session.active?
+          return reject_refresh!(env, req, client, 'session expired', refresh: refresh, session: session.as_log)
+        end
+
+        rack_request = Rack::Request.new(env)
+
+        begin
+          authn = Himari::Services::UpstreamAuthentication.revalidate_from_request(session: session, request: rack_request).perform
+        rescue Himari::Services::UpstreamAuthentication::UnauthorizedError => e
+          return reject_refresh!(env, req, client, 'refresh upstream authn denied', refresh: refresh, session: session.as_log, result: e.as_log)
+        end
+
+        updated_session = authn.session_data
+
+        begin
+          downstream = Himari::Services::DownstreamAuthorization.from_request(session: updated_session, client: client, request: rack_request, grant_type: :refresh_token, requested_scopes: refresh.scopes).perform
+        rescue Himari::Services::DownstreamAuthorization::ForbiddenError => e
+          return reject_refresh!(env, req, client, 'refresh downstream authz denied', refresh: refresh, session: updated_session.as_log, result: e.as_log)
+        end
+
+        # Refresh lifetime is recomputed by the authz rules on every refresh; if it is no
+        # longer configured the session is no longer refreshable. Fail closed.
+        unless downstream.lifetime&.refresh_token
+          return reject_refresh!(env, req, client, 'refresh_token lifetime no longer configured', refresh: refresh, session: updated_session.as_log)
+        end
+
+        # Rotate the token in place; verify! above recorded which secret the client presented,
+        # which rotate keeps valid as the previous one. The token's original expiry is
+        # preserved (absolute cap); the lifetime guard above only gates whether refresh is
+        # still permitted by the rules, not how long the rotated token lives.
+        rotated = refresh.rotate(claims: downstream.claims, openid: refresh.openid)
+
+        # Compare-and-swap on the version we read. A concurrent refresh that already rotated
+        # this token bumps the version, so the loser's write conflicts. Reject the loser
+        # without revoking — the winner's rotation (same handle) must survive.
+        begin
+          @storage.put_refresh_token(rotated, if_version: refresh.version)
+        rescue Himari::Storages::Base::Conflict
+          return reject_refresh!(env, req, client, 'refresh_token version conflict (concurrent use)', refresh: refresh, revoke: false)
+        end
+
+        @storage.put_session(updated_session, overwrite: true)
+
+        # OIDC core §12.2: refreshed ID Token MAY be returned, with no nonce on refresh.
+        issued = issue_access_and_id(
+          client: client,
+          claims: downstream.claims,
+          scopes: downstream.scopes,
+          lifetime: downstream.lifetime,
+          openid: refresh.openid,
+          session_handle: updated_session.handle,
+          nonce: nil,
+          mint_jwt_access_token: downstream.mint_jwt_access_token,
+        )
+
+        bearer = issued.access.to_bearer(token_string: issued.access_token_string)
+        bearer.refresh_token = rotated.format.to_s
+        res.access_token = bearer
+        res.id_token = issued.id_token_jwt if issued.id_token_jwt
+
+        @logger&.info(Himari::LogLine.new('OidcTokenEndpoint: refreshed', req: env['himari.request_as_log'], client: client.as_log, session: updated_session.as_log, token: issued.access.as_log, refresh_token: rotated.as_log, prev_version: refresh.version, secret_slot: refresh.verification&.via, signing_key_kid: issued.signing_key&.id))
+      end
+
+      # Reject a refresh request with invalid_grant. By default this revokes the presented
+      # refresh token when one was looked up, keeping refresh failures fail-closed against
+      # replay. revoke: false is used only for the concurrent-conflict path, where the
+      # winning request has already rotated this same handle and must not be revoked.
+      private def reject_refresh!(env, req, client, reason, refresh: nil, revoke: true, **fields)
+        log = {req: env['himari.request_as_log'], client: client.as_log}
+        log[:refresh] = refresh.as_log if refresh
+        @logger&.warn(Himari::LogLine.new("OidcTokenEndpoint: invalid_grant, #{reason}", **log, **fields))
+        @storage.delete_refresh_token(refresh) if refresh && revoke
+        req.invalid_grant!
+      end
+
+      # Mint an access token (and, for OIDC, an id_token JWT). Refresh tokens are handled
+      # separately by each grant path: the authorization_code path mints a fresh one, while
+      # the refresh path rotates the presented token in place.
+      private def issue_access_and_id(client:, claims:, scopes:, lifetime:, openid:, session_handle:, nonce:, mint_jwt_access_token:)
+        access = AccessToken.make(client_id: client.id, claims: claims, scopes: scopes, session_handle: session_handle, lifetime: lifetime.access_token)
+        @storage.put_token(access)
+
+        # Both the ID Token and a JWT access token are signed by the same key; resolve it once.
+        signing_key = nil
+        if openid || mint_jwt_access_token
+          signing_key = @signing_key_provider.find(group: client.preferred_key_group, active: true)
+          raise SigningKeyMissing unless signing_key
+        end
+
+        access_token_string = if mint_jwt_access_token
+          access.to_jwt(signing_key: signing_key, issuer: @issuer)
+        else
+          access.format.to_s
+        end
+
+        id_token_jwt = nil
+        if openid
+          id_token_jwt = IdToken.new(
+            claims: claims,
+            client_id: client.id,
+            nonce: nonce,
+            signing_key: signing_key,
+            issuer: @issuer,
+            # at_hash binds the ID Token to the access token actually delivered (JWT or opaque).
+            access_token: access_token_string,
+            lifetime: lifetime.id_token,
+          ).to_jwt
+        end
+
+        Issued.new(access: access, access_token_string: access_token_string, id_token_jwt: id_token_jwt, signing_key: signing_key)
+      end
     end
   end
 end