himari 0.5.0 → 0.6.0

data/lib/himari/item_providers/oauth_client_metadata.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'addressable/uri'
+require 'concurrent/map'
+require 'concurrent/atomic/atomic_fixnum'
+require 'httpx'
+
+require 'himari/log_line'
+require 'himari/item_provider'
+require 'himari/client_registration'
+require 'himari/dynamic_client_registration'
+
+module Himari
+  module ItemProviders
+    # Resolves clients whose client_id is an https URL pointing to a JSON client metadata
+    # document, per draft-ietf-oauth-client-id-metadata-document. When the OIDC endpoints look
+    # a client up by id, this provider fetches and validates that document on demand and
+    # presents it as a public ClientRegistration.
+    #
+    # The HTTPX session is built once and retained for connection reuse; successful documents
+    # are cached in-memory (respecting HTTP cache headers within configured bounds). Errors and
+    # malformed documents are never cached, and the provider always fails closed (returns []),
+    # so a fetch problem surfaces as an unknown client rather than an exception.
+    class OauthClientMetadata
+      include Himari::ItemProvider
+
+      class FetchError < StandardError; end
+      class InvalidDocument < StandardError; end
+
+      CacheEntry = Struct.new(:value, :expires_at, :size, :seq)
+
+      # @param session [HTTPX::Session] persistent, SSRF-filtered session (built by the middleware)
+      # @param allowed_client_ids [Array<String, Regexp>] empty = allow any compliant https URL
+      def initialize(session:, allowed_client_ids: [], require_pkce: true, ignore_localhost_redirect_uri_port: true,
+        skip_consent: false, scopes: Himari::ClientRegistration::IMPLICIT_SCOPES,
+        max_response_size: 5120,
+        cache_min_ttl: 60, cache_max_ttl: 86400, cache_default_ttl: 300, cache_max_total_size: 1_048_576, logger: nil)
+        @session = session
+        @allowed_client_ids = allowed_client_ids
+        @require_pkce = require_pkce
+        @ignore_localhost_redirect_uri_port = ignore_localhost_redirect_uri_port
+        @skip_consent = skip_consent
+        @scopes = scopes
+        @max_response_size = max_response_size
+        @cache_min_ttl = cache_min_ttl
+        @cache_max_ttl = cache_max_ttl
+        @cache_default_ttl = cache_default_ttl
+        @cache_max_total_size = cache_max_total_size
+        @logger = logger
+        @cache = Concurrent::Map.new
+        @cache_total_size = Concurrent::AtomicFixnum.new(0)
+        @cache_seq = Concurrent::AtomicFixnum.new(0)
+      end
+
+      def collect(id: nil, **_hint)
+        return [] unless id.is_a?(String)
+        return [] unless compliant_client_id_url?(id)
+        return [] unless allowed?(id)
+
+        cached = cache_get(id)
+        return [cached] if cached
+
+        registration, ttl, size = fetch_and_build(id)
+        cache_put(id, registration, ttl, size) if ttl.positive?
+        [registration]
+      rescue HTTPX::Error, FetchError, InvalidDocument, JSON::ParserError, Himari::DynamicClientRegistration::ValidationError => e
+        @logger&.warn(Himari::LogLine.new('OauthClientMetadata: client_id rejected', client_id: id, error: e.message))
+        []
+      end
+
+      private def compliant_client_id_url?(id)
+        uri = begin
+          Addressable::URI.parse(id)
+        rescue Addressable::URI::InvalidURIError
+          nil
+        end
+        return false unless uri
+        return false unless uri.scheme == 'https'
+        return false if uri.fragment
+        return false if uri.user || uri.password
+
+        path = uri.path
+        return false if path.nil? || path.empty?
+        return false if path.split('/').any? { |seg| seg == '.' || seg == '..' }
+
+        true
+      end
+
+      private def allowed?(id)
+        return true if @allowed_client_ids.empty?
+
+        @allowed_client_ids.any? do |matcher|
+          matcher.is_a?(Regexp) ? matcher.match?(id) : matcher.to_s == id
+        end
+      end
+
+      private def fetch_and_build(url)
+        # stream: true must be passed to the request (not preset on the session via .with, which
+        # would yield an already-buffered Response with no #each). It returns a StreamResponse:
+        # status and headers are inspected first, then the body is consumed under a hard byte cap
+        # below, without buffering the whole body up front.
+        resp = @session.get(url, stream: true)
+        # Surfaces transport/SSRF failures (HTTPX::Error) and HTTP >= 400. The draft also forbids
+        # following redirects, so anything other than 200 (including 3xx) is an error too.
+        resp.raise_for_status
+        raise FetchError, "unexpected status: #{resp.status}" unless resp.status == 200
+
+        content_length = resp.headers['content-length']
+        raise FetchError, 'response exceeds maximum size' if content_length && content_length.to_i > @max_response_size
+        raise FetchError, 'unexpected content-type' unless json_content_type?(resp.headers['content-type'])
+
+        body = read_capped_body(resp)
+
+        doc = JSON.parse(body, symbolize_names: true)
+        registration = build_registration(doc, url)
+        # The whole document is safe to log: it is size-capped and client_secret* is rejected.
+        @logger&.info(Himari::LogLine.new('OauthClientMetadata: fetched', client_id: url, metadata: doc))
+        [registration, compute_ttl(resp), body.bytesize]
+      end
+
+      # Stream the body and abort as soon as it exceeds the cap. The client_id URL is
+      # attacker-influenced and HTTPX has no hard body limit, so a malicious host could omit
+      # Content-Length and stream an unbounded response; capping during the read (rather than
+      # after buffering the whole body) prevents that memory/disk exhaustion.
+      #
+      # FIXME: this streaming read is a workaround for the lack of a built-in maximum body size in
+      # HTTPX. Replace it with a native body cap once available:
+      # https://gitlab.com/os85/httpx/-/work_items/383
+      private def read_capped_body(resp)
+        body = +''
+        resp.each do |chunk|
+          body << chunk
+          raise FetchError, 'response exceeds maximum size' if body.bytesize > @max_response_size
+        end
+        body
+      end
+
+      private def build_registration(doc, url)
+        raise InvalidDocument, 'document must be a JSON object' unless doc.is_a?(Hash)
+        raise InvalidDocument, 'client_id does not match document URL' unless doc[:client_id] == url
+        raise InvalidDocument, 'client_secret must not be present' if doc.key?(:client_secret) || doc.key?(:client_secret_expires_at)
+
+        auth_method = doc[:token_endpoint_auth_method]
+        raise InvalidDocument, "token_endpoint_auth_method must be 'none'" if auth_method && auth_method.to_s != 'none'
+
+        redirect_uris = Himari::DynamicClientRegistration.validate_redirect_uris(doc[:redirect_uris])
+
+        Himari::ClientRegistration.new(
+          id: url,
+          redirect_uris: redirect_uris,
+          confidential: false,
+          require_pkce: @require_pkce,
+          ignore_localhost_redirect_uri_port: @ignore_localhost_redirect_uri_port,
+          skip_consent: @skip_consent,
+          scopes: @scopes,
+        )
+      end
+
+      private def json_content_type?(value)
+        type = value.to_s.split(';', 2).first.to_s.strip.downcase
+        type == 'application/json' || type.end_with?('+json')
+      end
+
+      # Honour Cache-Control/Expires within configured bounds. no-store/no-cache disables caching.
+      private def compute_ttl(resp)
+        cache_control = resp.headers['cache-control'].to_s.downcase
+        return 0 if cache_control.include?('no-store') || cache_control.include?('no-cache')
+
+        ttl = if (m = cache_control.match(/max-age\s*=\s*(\d+)/))
+          m[1].to_i
+        elsif (expires = resp.headers['expires'])
+          parsed = begin
+            Time.httpdate(expires)
+          rescue ArgumentError
+            nil
+          end
+          parsed && (parsed - Time.now).to_i
+        end
+
+        (ttl || @cache_default_ttl).clamp(@cache_min_ttl, @cache_max_ttl)
+      end
+
+      private def cache_get(id)
+        entry = @cache[id]
+        return unless entry
+        return entry.value if entry.expires_at > Time.now.to_f
+
+        forget(id, entry)
+        nil
+      end
+
+      private def cache_put(id, value, ttl, size)
+        entry = CacheEntry.new(value, Time.now.to_f + ttl, size, @cache_seq.increment)
+        previous = @cache[id]
+        @cache[id] = entry
+        delta = size - (previous&.size || 0)
+        @cache_total_size.update { |total| total + delta }
+        evict_until_within_limit
+      end
+
+      # Drop the oldest (lowest seq) entries until the tracked total body size fits the limit.
+      # Sizes are approximate (original JSON body bytes); concurrent eviction may overshoot a
+      # little, which is acceptable for a cache.
+      private def evict_until_within_limit
+        while @cache_total_size.value > @cache_max_total_size
+          oldest = @cache.each_pair.min_by { |_id, entry| entry.seq }
+          break unless oldest
+
+          forget(*oldest)
+        end
+      end
+
+      private def forget(id, entry)
+        return unless @cache.delete_pair(id, entry)
+
+        @cache_total_size.update { |total| total - entry.size }
+      end
+    end
+  end
+end

data/lib/himari/item_providers/static.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/item_provider'
 
 module Himari

data/lib/himari/item_providers/storage.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'himari/item_provider'
+require 'himari/client_registration'
+
+module Himari
+  module ItemProviders
+    # Looks up dynamically registered clients from storage and presents them to the OIDC
+    # endpoints as plain ClientRegistration objects. Lookups always carry an id hint; without
+    # one this returns nothing (there is no list operation). Expired registrations are filtered
+    # out here so backends without TTL (Memory, Filesystem) and DynamoDB's delayed TTL both
+    # fail closed.
+    class Storage
+      include Himari::ItemProvider
+
+      # @param storage [Himari::Storages::Base]
+      # @param skip_consent [Boolean] applied to every dynamic client this provider resolves
+      # @param scopes [Array<String>] recognised scopes applied to every dynamic client resolved
+      def initialize(storage:, skip_consent: false, scopes: Himari::ClientRegistration::IMPLICIT_SCOPES)
+        @storage = storage
+        @skip_consent = skip_consent
+        @scopes = scopes
+      end
+
+      def collect(id: nil, **_hint)
+        return [] unless id
+
+        client = @storage.find_dynamic_client(id)
+        client&.active? ? [client.to_client_registration(skip_consent: @skip_consent, scopes: @scopes)] : []
+      end
+    end
+  end
+end

data/lib/himari/jwt_token.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json/jwt'
+
+module Himari
+  # Shared minting process for the JWTs Himari signs for relying parties: the OIDC ID Token
+  # and the RFC 9068 access token. Holds the common claim derivation (registered claims merged
+  # over the IdP claims) and the signing step (kid, optional JOSE header fields, signature).
+  # Subclasses add their token-specific claims/header by overriding #final_claims / #jwt_header.
+  class JwtToken
+    def initialize(claims:, client_id:, signing_key:, issuer:, time: Time.now, lifetime: 3600)
+      @claims = claims
+      @client_id = client_id
+      @signing_key = signing_key
+      @issuer = issuer
+      @time = time
+      @lifetime = lifetime
+    end
+
+    attr_reader :claims, :client_id, :signing_key, :issuer
+
+    # Registered claims common to every Himari-minted JWT. The IdP claims (sub and the rest) are
+    # carried verbatim so the access token exposes the same claim set as the ID Token.
+    def standard_claims
+      claims.merge(
+        iss: @issuer,
+        aud: @client_id,
+        iat: @time.to_i,
+        nbf: @time.to_i,
+        exp: (@time + @lifetime).to_i,
+      )
+    end
+
+    def final_claims
+      standard_claims
+    end
+
+    # JOSE header fields beyond kid; subclasses override (e.g. typ=at+jwt for RFC 9068).
+    def jwt_header
+      {}
+    end
+
+    def to_jwt
+      jwt = JSON::JWT.new(final_claims)
+      jwt.kid = @signing_key.id
+      jwt_header.each { |k, v| jwt.header[k] = v }
+      jwt.sign(@signing_key.pkey, @signing_key.alg.to_sym).to_s
+    end
+  end
+end

data/lib/himari/lifetime_value.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Himari
-  LifetimeValue = Struct.new(:access_token, :id_token, :code, keyword_init: true) do
+  LifetimeValue = Struct.new(:access_token, :id_token, :code, :refresh_token, keyword_init: true) do
     def self.from_integer(i)
-      new(access_token: i, id_token: i, code: nil)
+      new(access_token: i, id_token: i, code: nil, refresh_token: nil)
     end
 
     def as_log
@@ -9,7 +11,7 @@ module Himari
     end
 
     def as_json
-      {access_token: access_token, id_token: id_token, code: code}
+      {access_token: access_token, id_token: id_token, code: code, refresh_token: refresh_token}
     end
   end
 end

data/lib/himari/log_line.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 
 module Himari

data/lib/himari/middlewares/authentication_rule.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/rule'
 require 'himari/item_providers/static'
 

data/lib/himari/middlewares/authorization_rule.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/rule'
 require 'himari/item_providers/static'
 

data/lib/himari/middlewares/claims_rule.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/rule'
 require 'himari/item_providers/static'
 

data/lib/himari/middlewares/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/client_registration'
 require 'himari/item_providers/static'
 

data/lib/himari/middlewares/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/config'
 
 module Himari

data/lib/himari/middlewares/dynamic_clients.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'himari/dynamic_client_registration'
+require 'himari/item_providers/storage'
+require 'himari/middlewares/client'
+require 'himari/middlewares/config'
+
+module Himari
+  module Middlewares
+    # Enables RFC 7591 Dynamic Client Registration. Its presence in the Rack env
+    # (RACK_KEY) is what turns on the registration endpoint and its advertisement in the
+    # OIDC discovery document. It also appends a storage-backed provider to the client
+    # chain (Middlewares::Client::RACK_KEY) so registered clients resolve through the same
+    # client_provider.find(id:) lookup the OIDC endpoints already use.
+    #
+    # Must be placed after Middlewares::Config (it reads storage from the config).
+    class DynamicClients
+      RACK_KEY = 'himari.dynamic_clients'
+
+      Options = Data.define(:registration_lifetime, :ignore_localhost_redirect_uri_port, :skip_consent, :scopes, :grant_types_supported, :response_types_supported, :token_endpoint_auth_methods_supported)
+
+      # @param registration_lifetime [Integer] seconds a registration stays valid (default 180 days)
+      # @param ignore_localhost_redirect_uri_port [Boolean] relax the port of loopback redirect_uris
+      #   for registered clients (default true; see RFC 8252 §7.3)
+      # @param skip_consent [Boolean] let registered clients bypass the consent page (default false)
+      # @param scopes [Array<String>] recognised scopes inherited by registered clients; scopes
+      #   outside this list are dropped from authorization requests (default openid, offline_access)
+      def initialize(app, kwargs = {})
+        @app = app
+        @options = Options.new(
+          registration_lifetime: kwargs.fetch(:registration_lifetime) { Himari::DynamicClientRegistration::REGISTRATION_LIFETIME },
+          ignore_localhost_redirect_uri_port: kwargs.fetch(:ignore_localhost_redirect_uri_port, true),
+          skip_consent: kwargs.fetch(:skip_consent, false),
+          scopes: kwargs.fetch(:scopes, Himari::ClientRegistration::IMPLICIT_SCOPES),
+          grant_types_supported: Himari::DynamicClientRegistration::SUPPORTED_GRANT_TYPES,
+          response_types_supported: Himari::DynamicClientRegistration::SUPPORTED_RESPONSE_TYPES,
+          token_endpoint_auth_methods_supported: Himari::DynamicClientRegistration::SUPPORTED_TOKEN_ENDPOINT_AUTH_METHODS,
+        )
+      end
+
+      attr_reader :app
+
+      def call(env)
+        config = env[Himari::Middlewares::Config::RACK_KEY]
+        raise "Himari::Middlewares::DynamicClients must be placed after Himari::Middlewares::Config" unless config
+
+        env[RACK_KEY] = @options
+        env[Himari::Middlewares::Client::RACK_KEY] ||= []
+        env[Himari::Middlewares::Client::RACK_KEY] += [Himari::ItemProviders::Storage.new(storage: config.storage, skip_consent: @options.skip_consent, scopes: @options.scopes)]
+
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/himari/middlewares/metadata_clients.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'httpx'
+
+require 'himari/version'
+require 'himari/item_providers/oauth_client_metadata'
+require 'himari/middlewares/client'
+require 'himari/middlewares/config'
+
+module Himari
+  module Middlewares
+    # Enables OAuth Client ID Metadata Document support
+    # (draft-ietf-oauth-client-id-metadata-document). Its presence in the Rack env (RACK_KEY)
+    # advertises support in the discovery documents. It appends a single, long-lived
+    # OauthClientMetadata provider to the client chain (Middlewares::Client::RACK_KEY) so URL
+    # client_ids resolve through the same client_provider.find(id:) lookup the OIDC endpoints
+    # already use; the provider retains its HTTPX session and document cache across requests.
+    #
+    # Must be placed after Middlewares::Config.
+    #
+    # Options:
+    # - allowed_client_ids [Array<String, Regexp>] empty (default) accepts any compliant https
+    #   URL; otherwise a client_id must match an entry (String exact, Regexp =~).
+    # - require_pkce [Boolean] force PKCE for metadata clients (default true; they are public).
+    # - ignore_localhost_redirect_uri_port [Boolean] relax the port of loopback redirect_uris when
+    #   matching at the authorization endpoint (default true; see RFC 8252 §7.3).
+    # - skip_consent [Boolean] let metadata clients bypass the consent page (default false).
+    # - scopes [Array<String>] recognised scopes inherited by metadata clients; scopes outside
+    #   this list are dropped from authorization requests (default openid, offline_access).
+    # - ssrf [true, false, Hash] SSRF filtering. true (default) restricts to https; a Hash is
+    #   merged into the ssrf_filter plugin options (e.g. allowed_schemes); false disables it
+    #   (only for an authorization server running on a loopback address).
+    # - user_agent [String] User-Agent header for fetches.
+    # - http_timeout [Hash] HTTPX timeout options.
+    # - max_response_size [Integer] reject documents larger than this many bytes (default 5 KiB).
+    # - cache_min_ttl / cache_max_ttl / cache_default_ttl [Integer] cache bounds in seconds.
+    # - cache_max_total_size [Integer] approximate cap on total cached document bytes; the oldest
+    #   entries are evicted once exceeded (default 1 MiB).
+    class MetadataClients
+      RACK_KEY = 'himari.metadata_clients'
+
+      DEFAULT_USER_AGENT = "Himari-OauthClientMetadataFetch/#{Himari::VERSION} (+https://github.com/sorah/himari)"
+      # read_timeout is set explicitly: the stream plugin otherwise defaults it to Infinity, which
+      # would let a slow sender hold the fetch open indefinitely.
+      DEFAULT_HTTP_TIMEOUT = {connect_timeout: 5, request_timeout: 10, read_timeout: 10}.freeze
+
+      Options = Data.define(:allowed_client_ids, :require_pkce, :ignore_localhost_redirect_uri_port, :skip_consent, :scopes, :ssrf, :user_agent, :http_timeout, :max_response_size, :cache_min_ttl, :cache_max_ttl, :cache_default_ttl, :cache_max_total_size)
+
+      def initialize(app, kwargs = {})
+        @app = app
+        @options = Options.new(
+          allowed_client_ids: kwargs.fetch(:allowed_client_ids, []),
+          require_pkce: kwargs.fetch(:require_pkce, true),
+          ignore_localhost_redirect_uri_port: kwargs.fetch(:ignore_localhost_redirect_uri_port, true),
+          skip_consent: kwargs.fetch(:skip_consent, false),
+          scopes: kwargs.fetch(:scopes, Himari::ClientRegistration::IMPLICIT_SCOPES),
+          ssrf: kwargs.fetch(:ssrf, true),
+          user_agent: kwargs.fetch(:user_agent, DEFAULT_USER_AGENT),
+          http_timeout: kwargs.fetch(:http_timeout, DEFAULT_HTTP_TIMEOUT),
+          max_response_size: kwargs.fetch(:max_response_size, 5120),
+          cache_min_ttl: kwargs.fetch(:cache_min_ttl, 60),
+          cache_max_ttl: kwargs.fetch(:cache_max_ttl, 86400),
+          cache_default_ttl: kwargs.fetch(:cache_default_ttl, 300),
+          cache_max_total_size: kwargs.fetch(:cache_max_total_size, 1_048_576),
+        )
+        @provider = Himari::ItemProviders::OauthClientMetadata.new(
+          session: build_session(@options),
+          allowed_client_ids: @options.allowed_client_ids,
+          require_pkce: @options.require_pkce,
+          ignore_localhost_redirect_uri_port: @options.ignore_localhost_redirect_uri_port,
+          skip_consent: @options.skip_consent,
+          scopes: @options.scopes,
+          max_response_size: @options.max_response_size,
+          cache_min_ttl: @options.cache_min_ttl,
+          cache_max_ttl: @options.cache_max_ttl,
+          cache_default_ttl: @options.cache_default_ttl,
+          cache_max_total_size: @options.cache_max_total_size,
+          logger: kwargs[:logger],
+        )
+      end
+
+      attr_reader :app, :options
+
+      def call(env)
+        config = env[Himari::Middlewares::Config::RACK_KEY]
+        raise "Himari::Middlewares::MetadataClients must be placed after Himari::Middlewares::Config" unless config
+
+        env[RACK_KEY] = @options
+        env[Himari::Middlewares::Client::RACK_KEY] ||= []
+        env[Himari::Middlewares::Client::RACK_KEY] += [@provider]
+
+        @app.call(env)
+      end
+
+      # Build a persistent, SSRF-filtered HTTPX session with the stream plugin loaded, so the
+      # provider can request a streaming response (get(url, stream: true)) and cap the body during
+      # the read instead of buffering it whole. stream: true is passed per-request, not set here
+      # via .with: a session-level stream option yields an already-buffered Response with no #each.
+      # Notably it does not enable the follow_redirects plugin: the draft requires redirects not be
+      # followed.
+      private def build_session(options)
+        session = HTTPX.plugin(:persistent).plugin(:stream)
+        session = case options.ssrf
+        when true
+          session.plugin(:ssrf_filter, allowed_schemes: %w(https))
+        when Hash
+          ssrf_options = {allowed_schemes: %w(https)}.merge(options.ssrf)
+          session.plugin(:ssrf_filter, **ssrf_options)
+        when false
+          session
+        else
+          raise ArgumentError, "ssrf option must be true, false, or a Hash"
+        end
+        session.with(
+          headers: {'user-agent' => options.user_agent, 'accept' => 'application/json'},
+          timeout: options.http_timeout,
+        )
+      end
+    end
+  end
+end

data/lib/himari/middlewares/signing_key.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'himari/signing_key'
 require 'himari/item_providers/static'
 

data/lib/himari/provider_chain.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Himari
   class ProviderChain
     # @param providers [Array<ItemProvider>]
@@ -8,7 +10,7 @@ module Himari
     attr_reader :providers
 
     def find(**hint, &block)
-      block ||= proc { |i,h| i.match_hint?(**h) } # ItemProvider#collect doesn't guarantee exact matches, so do exact match by match_hint?
+      block ||= proc { |i, h| i.match_hint?(**h) } # ItemProvider#collect doesn't guarantee exact matches, so do exact match by match_hint?
       @providers.each do |provider|
         provider.collect(**hint).each do |item|
           return item if block.call(item, hint)

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)