himari 0.5.0 → 0.7.0

data/lib/himari/refresh_token.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'himari/token_string'
+
+module Himari
+  class RefreshToken
+    include TokenString
+
+    def self.magic_header
+      'hmrt'
+    end
+
+    def self.default_lifetime
+      raise ArgumentError, "RefreshToken requires an explicit lifetime:"
+    end
+
+    def initialize(handle:, client_id:, claims:, session_handle:, expiry:, openid: false, scopes: [], secret: nil, secret_hash: nil, secret_hash_prev: nil, version: 1, updated_at: nil)
+      @handle = handle
+      @client_id = client_id
+      @claims = claims
+      @session_handle = session_handle
+      @openid = openid
+      @scopes = scopes
+      @expiry = expiry
+
+      @secret = secret
+      @secret_hash = secret_hash
+      @secret_hash_prev = secret_hash_prev
+      @version = version
+      @updated_at = updated_at || Time.now.to_i
+      @verification = nil
+    end
+
+    attr_reader :handle, :client_id, :claims, :session_handle, :openid, :scopes, :expiry, :version, :updated_at
+
+    # Rotate the token in place (same handle): mint a new current secret while keeping the
+    # just-presented secret valid as the previous one, so a client whose rotation response is
+    # lost can retry with the secret it still holds. The secret to keep is the hash verify!
+    # matched (TokenString#verification) — whichever slot the client used; rotate is therefore
+    # only valid after a successful verify!. version is bumped so a concurrent refresh against
+    # the version we read fails the conditional update. expiry is preserved: the initial
+    # lifetime is an absolute cap on the rotation chain, not slid forward on each refresh.
+    def rotate(claims:, openid:, now: Time.now)
+      raise TokenString::SecretMissing, "rotate requires a verified secret; call verify! first" unless verification
+
+      self.class.new(
+        handle:,
+        client_id:,
+        session_handle:,
+        claims:,
+        openid:,
+        scopes:,
+        secret: SecureRandom.urlsafe_base64(48),
+        secret_hash_prev: verification.secret_hash,
+        version: version + 1,
+        updated_at: now.to_i,
+        expiry:,
+      )
+    end
+
+    def as_log
+      {
+        handle: handle,
+        client_id: client_id,
+        claims: claims,
+        session_handle: session_handle,
+        openid: openid,
+        scopes: scopes,
+        expiry: expiry,
+        version: version,
+        updated_at: updated_at,
+        prev_secret_set: !secret_hash_prev.nil?,
+      }
+    end
+
+    def as_json
+      {
+        handle: handle,
+        secret_hash: secret_hash,
+        secret_hash_prev: secret_hash_prev,
+        client_id: client_id,
+        claims: claims,
+        session_handle: session_handle,
+        openid: openid,
+        scopes: scopes,
+        expiry: expiry.to_i,
+        version: version,
+        updated_at: updated_at.to_i,
+      }
+    end
+  end
+end

data/lib/himari/rule.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Himari
   Rule = Struct.new(:name, :block, keyword_init: true) do
     def call(context, decision)

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,22 +1,42 @@
+# frozen_string_literal: true
+
 require 'rack/oauth2'
 require 'digest/sha2'
 require 'openid_connect'
 
+require 'himari/rack_oauth2_ext'
+
 module Himari
   module Services
     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 issuer [String] issuer identifier, returned to the client as the RFC 9207 `iss` parameter
+      # @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:, issuer:, consent: nil, logger: nil)
         @authz = authz
         @client = client
         @storage = storage
+        @issuer = issuer
+        @consent = consent
         @logger = logger
       end
 
@@ -31,19 +51,57 @@ module Himari
 
       def app(env)
         Rack::OAuth2::Server::Authorize.new do |req, res|
+          # RFC 9207: hand the issuer to rack-oauth2 so both the grant response and any error it
+          # redirects back to the client carry the `iss` parameter (see Himari::RackOAuth2Ext).
+          req.iss = @issuer
+          res.iss = @issuer
+
           # sanity check
           unless @client.id == req.client_id
             @logger&.warn(Himari::LogLine.new('OidcAuthorizationEndpoint: @client.id != req.client_id', req: env['himari.request_as_log'], known_client: @client.id, given_client: req.client_id))
             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,7 +111,9 @@ 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'

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,42 @@ 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,
+            authorization_response_iss_parameter_supported: true, # RFC 9207
+          }.compact
         end
 
         def response