keycardai-oauth 0.1.0

data/lib/keycardai/oauth/client_secret.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # Static client_id + client_secret credential, authenticating with
+    # client_secret_basic (RFC 6749 §2.3.1 / RFC 7617). The simplest
+    # credential type, suitable for development and workloads that can safely
+    # hold a long-lived secret.
+    #
+    # Implements the Credential interface: authorization_header(issuer:) plus
+    # prepare_token_exchange_request. Never reads environment variables; the
+    # caller sources the secret from its own config or secret manager.
+    #
+    # Single zone:
+    #   ClientSecret.new("client_abc", "secret")
+    #
+    # Multi-zone, keyed by the zone's issuer URL:
+    #   ClientSecret.new(
+    #     "https://acme.keycard.cloud" => ["client_a", "secret_a"],
+    #     "https://beta.keycard.cloud" => ["client_b", "secret_b"],
+    #   )
+    #
+    # A token operation for a zone not in the map fails closed: the credential
+    # raises rather than fall back to another zone's secret.
+    class ClientSecret
+      # @overload initialize(client_id, client_secret)
+      # @overload initialize(issuer_map)
+      #   @param issuer_map [Hash{String => Array(String, String)}]
+      # @raise [ConfigurationError] empty id/secret, or an empty zone map
+      def initialize(client_id_or_map, client_secret = nil)
+        if client_id_or_map.is_a?(Hash)
+          raise ConfigurationError, "multi-zone ClientSecret requires at least one zone" if client_id_or_map.empty?
+
+          @pairs = client_id_or_map.to_h do |issuer, (id, secret)|
+            validate_pair(id, secret)
+            [issuer.chomp("/"), [id, secret]]
+          end
+        else
+          validate_pair(client_id_or_map, client_secret)
+          @pair = [client_id_or_map, client_secret]
+        end
+      end
+
+      # @return [Boolean] whether this credential holds per-zone pairs
+      def multi_zone?
+        !@pairs.nil?
+      end
+
+      # @return [Array<String>] the issuer URLs this credential can serve
+      def issuers
+        multi_zone? ? @pairs.keys : []
+      end
+
+      # The HTTP Basic Authorization header for a token operation.
+      #
+      # @param issuer [String, nil] the target zone; required for multi-zone
+      # @return [String]
+      # @raise [ConfigurationError] multi-zone lookup for an unconfigured zone
+      #   (fails closed, never another zone's secret)
+      def authorization_header(issuer: nil)
+        client_id, client_secret = resolve_pair(issuer)
+        HTTP.basic_authorization(client_id, client_secret)
+      end
+
+      # Build the token-exchange form parameters. Client authentication rides
+      # in the Basic header, never in the body.
+      #
+      # @param subject_token [String]
+      # @param resource [String, nil]
+      # @param audience [String, nil]
+      # @param scope [String, nil]
+      # @param token_endpoint [String, nil] unused; part of the interface
+      # @param issuer [String, nil] unused here; auth resolution is per-header
+      # @return [Hash]
+      def prepare_token_exchange_request(subject_token:, resource: nil, audience: nil, scope: nil,
+                                         token_endpoint: nil, issuer: nil)
+        {
+          "grant_type" => GrantType::TOKEN_EXCHANGE,
+          "subject_token" => subject_token,
+          "subject_token_type" => TokenType::ACCESS_TOKEN,
+          "resource" => resource,
+          "audience" => audience,
+          "scope" => scope
+        }.compact
+      end
+
+      private
+
+      def validate_pair(client_id, client_secret)
+        return unless client_id.nil? || client_id.empty? || client_secret.nil? || client_secret.empty?
+
+        raise ConfigurationError, "ClientSecret requires a non-empty client_id and client_secret"
+      end
+
+      def resolve_pair(issuer)
+        return @pair unless multi_zone?
+        raise ConfigurationError, "multi-zone ClientSecret requires an issuer to resolve credentials" if issuer.nil?
+
+        @pairs[issuer.chomp("/")] ||
+          raise(ConfigurationError, "no credentials configured for zone #{issuer}")
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/discovery.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Keycardai
+  # Authorization-server discovery (RFC 8414): the operation, its metadata
+  # type, and the URL/parsing internals shared with JWKSKeyring.
+  module OAuth
+    # OAuth 2.0 authorization-server metadata (RFC 8414). Standard fields are
+    # first-class members; the complete document, including unknown fields, is
+    # preserved in +raw+ and reachable through +[]+.
+    AuthorizationServerMetadata = Data.define(
+      :issuer, :token_endpoint, :authorization_endpoint, :jwks_uri, :registration_endpoint,
+      :grant_types_supported, :token_endpoint_auth_methods_supported, :response_types_supported, :raw
+    ) do
+      # @param field [String] a metadata field name
+      # @return [Object, nil] the field's value from the full document
+      def [](field)
+        raw[field]
+      end
+    end
+
+    # Discover OAuth 2.0 authorization-server metadata from an issuer URL
+    # (RFC 8414). Performs a single fetch and does not cache; caching belongs
+    # to the callers that depend on the endpoints.
+    #
+    # @param issuer [String] the authorization server's identifier URL
+    # @param http_client [#get] pluggable transport
+    # @param timeout [Numeric, nil] fetch timeout in seconds
+    # @return [AuthorizationServerMetadata]
+    # @raise [ConfigurationError] empty or invalid issuer input
+    # @raise [HTTPError] non-2xx response
+    # @raise [ProtocolError] issuer mismatch (code issuer_mismatch) or a
+    #   malformed document (code invalid_metadata)
+    # @raise [NetworkError] transport failure
+    def self.fetch_authorization_server_metadata(issuer, http_client: HTTP::NetHTTPClient.new, timeout: nil)
+      url = Discovery.metadata_url(issuer)
+      response = http_client.get(url, headers: { "Accept" => "application/json" }, timeout: timeout)
+      unless response.success?
+        raise HTTPError.new("discovery for #{issuer} returned HTTP #{response.status}",
+                            status: response.status, body: response.body)
+      end
+
+      Discovery.parse_metadata(issuer, response.body)
+    end
+
+    # Internals of authorization-server discovery, shared with JWKSKeyring.
+    module Discovery
+      module_function
+
+      # RFC 8414: the well-known path segment is inserted between the host and
+      # any issuer path component.
+      def metadata_url(issuer)
+        raise ConfigurationError, "issuer must be a non-empty URL" if issuer.nil? || issuer.empty?
+
+        uri = URI(issuer)
+        raise ConfigurationError, "issuer must be an absolute http(s) URL" unless uri.is_a?(URI::HTTP)
+
+        path = uri.path.chomp("/")
+        uri.path = "/.well-known/oauth-authorization-server#{path}"
+        uri.to_s
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "issuer is not a valid URL"
+      end
+
+      def parse_metadata(issuer, body)
+        document = parse_document(issuer, body)
+        validate_issuer(issuer, document)
+
+        AuthorizationServerMetadata.new(
+          issuer: document["issuer"],
+          token_endpoint: document["token_endpoint"],
+          authorization_endpoint: document["authorization_endpoint"],
+          jwks_uri: document["jwks_uri"],
+          registration_endpoint: document["registration_endpoint"],
+          grant_types_supported: document["grant_types_supported"],
+          token_endpoint_auth_methods_supported: document["token_endpoint_auth_methods_supported"],
+          response_types_supported: document["response_types_supported"],
+          raw: document
+        )
+      end
+
+      def parse_document(issuer, body)
+        document = JSON.parse(body)
+        unless document.is_a?(Hash)
+          raise ProtocolError.new("metadata for #{issuer} is not a JSON object",
+                                  code: "invalid_metadata")
+        end
+
+        document
+      rescue JSON::ParserError
+        raise ProtocolError.new("metadata for #{issuer} is not valid JSON", code: "invalid_metadata")
+      end
+
+      # RFC 8414 §3.3: the response issuer must be present and match the
+      # requested issuer, ignoring a trailing slash.
+      def validate_issuer(issuer, document)
+        unless document["issuer"].is_a?(String)
+          raise ProtocolError.new("metadata for #{issuer} has no issuer", code: "invalid_metadata")
+        end
+        return if document["issuer"].chomp("/") == issuer.chomp("/")
+
+        raise ProtocolError.new("metadata issuer #{document["issuer"]} does not match requested issuer #{issuer}",
+                                code: "issuer_mismatch")
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/errors.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Keycardai
+  # Root of the Keycard error taxonomy. Every error raised by any Keycard gem
+  # is a subclass, so `rescue Keycardai::Error` catches the whole family.
+  class Error < StandardError; end
+
+  module OAuth
+    # Invalid configuration detected at construction time: missing credential,
+    # empty issuer list, an algorithm the verifier does not implement.
+    class ConfigurationError < Keycardai::Error; end
+
+    # A transport-level failure (DNS, TLS, timeout) wrapping the underlying
+    # exception as +cause+.
+    class NetworkError < Keycardai::Error; end
+
+    # A non-2xx HTTP response. Carries the status code and response body.
+    class HTTPError < Keycardai::Error
+      # @return [Integer]
+      attr_reader :status
+      # @return [String]
+      attr_reader :body
+
+      def initialize(message, status:, body: "")
+        super(message)
+        @status = status
+        @body = body
+      end
+    end
+
+    # An OAuth error response from the authorization server (RFC 6749 §5.2).
+    # Carries the wire error code plus the optional description and URI.
+    class OAuthError < HTTPError
+      # @return [String] the OAuth error code (e.g. invalid_grant)
+      attr_reader :error
+      # @return [String, nil]
+      attr_reader :error_description
+      # @return [String, nil]
+      attr_reader :error_uri
+
+      def initialize(message, error:, status:, body: "", error_description: nil, error_uri: nil)
+        super(message, status: status, body: body)
+        @error = error
+        @error_description = error_description
+        @error_uri = error_uri
+      end
+    end
+
+    # The server's response violates the protocol contract: metadata with a
+    # mismatched or missing issuer, a token response with no access token.
+    # The +code+ discriminates the case (issuer_mismatch, invalid_metadata,
+    # invalid_response).
+    class ProtocolError < Keycardai::Error
+      # @return [String]
+      attr_reader :code
+
+      def initialize(message, code:)
+        super(message)
+        @code = code
+      end
+    end
+
+    # A bearer token failed verification: malformed, disallowed algorithm,
+    # untrusted issuer, missing required claim, expired, audience mismatch,
+    # missing kid, or bad signature. One category for every rejection, so
+    # callers handle all verification failures the same way.
+    class InvalidTokenError < Keycardai::Error; end
+
+    # Base class for JWKS key-resolution failures.
+    class JWKSError < Keycardai::Error; end
+
+    # Authorization server discovery failed or its metadata carries no
+    # +jwks_uri+.
+    class JWKSDiscoveryError < JWKSError; end
+
+    # The discovered +jwks_uri+ does not share the issuer's origin. Rejected
+    # before any key fetch.
+    class JWKSUriValidationError < JWKSError; end
+
+    # The JWKS endpoint returned a non-2xx response or could not be reached.
+    class JWKSFetchError < JWKSError; end
+
+    # The token's +kid+ is not present in the issuer's fetched JWKS.
+    class JWKSKeyNotFoundError < JWKSError; end
+
+    # The user did not complete the browser redirect within the loopback
+    # flow's callback timeout.
+    class InteractionTimeoutError < Keycardai::Error; end
+
+    # Raised by AccessContext#access when a token cannot be handed out. The
+    # error_type identifies the condition: global_error (a context-wide error
+    # is set), resource_error (the named resource's exchange failed), or
+    # missing_token (the resource was never granted). For missing_token,
+    # available_resources lists what was granted.
+    class ResourceAccessError < Keycardai::Error
+      # @return [String]
+      attr_reader :resource
+      # @return [String] global_error | resource_error | missing_token
+      attr_reader :error_type
+      # @return [Array<String>]
+      attr_reader :available_resources
+      # @return [Object, nil] the recorded upstream error, when one exists
+      attr_reader :error_details
+
+      def initialize(message, resource:, error_type:, available_resources: [], error_details: nil)
+        super(message)
+        @resource = resource
+        @error_type = error_type
+        @available_resources = available_resources
+        @error_details = error_details
+      end
+    end
+
+    # A workload-identity source is misconfigured at construction: missing
+    # token file, no discovery env var set, missing required audience.
+    # Carries the source identifier (file, gcp-metadata, fly, custom).
+    class WorkloadIdentityConfigurationError < ConfigurationError
+      # @return [String]
+      attr_reader :source
+
+      def initialize(message, source:)
+        super(message)
+        @source = source
+      end
+    end
+
+    # A workload-identity source failed at request time: file unreadable or
+    # empty, endpoint unreachable, non-200 response, empty token. Carries the
+    # source identifier and preserves the underlying cause.
+    class WorkloadIdentityRuntimeError < Keycardai::Error
+      # @return [String]
+      attr_reader :source
+
+      def initialize(message, source:)
+        super(message)
+        @source = source
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/exchange_tokens.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Keycardai
+  # The delegated-access orchestration that feeds an AccessContext.
+  module OAuth
+    # Exchange a subject token for tokens targeting multiple resources,
+    # recording each success or failure on an AccessContext. Non-throwing by
+    # design: per-resource failures land on the context so a partial-success
+    # flow can proceed. When user_identifier is set, each exchange is an
+    # impersonation instead of a subject-token exchange.
+    #
+    # @param client [TokenExchangeClient] carries the credential and zone
+    # @param resources [Array<String>] the target resources
+    # @param subject_token [String, nil] the inbound token being delegated;
+    #   required unless user_identifier is given
+    # @param access_context [AccessContext] the container to populate
+    # @param user_identifier [String, nil] impersonation target
+    # @param request_scopes [String, Hash{String => String}, nil] scopes for
+    #   every exchange, or a per-resource map
+    # @param issuer [String, nil] per-call zone selection
+    # @return [AccessContext]
+    def self.exchange_tokens_for_resources(client:, resources:, subject_token: nil,
+                                           access_context: AccessContext.new, user_identifier: nil,
+                                           request_scopes: nil, issuer: nil)
+      if subject_token.nil? && user_identifier.nil?
+        raise ArgumentError, "subject_token is required unless user_identifier is given"
+      end
+
+      resources.each do |resource|
+        scope = request_scopes.is_a?(Hash) ? request_scopes[resource] : request_scopes
+        token = ExchangeTokens.exchange_one(client: client, resource: resource, subject_token: subject_token,
+                                            user_identifier: user_identifier, scope: scope, issuer: issuer)
+        access_context.set_token(resource, token)
+      rescue Keycardai::Error => e
+        access_context.set_resource_error(resource, e)
+      end
+      access_context
+    end
+
+    # Internals of exchange_tokens_for_resources. Not public API.
+    module ExchangeTokens
+      module_function
+
+      def exchange_one(client:, resource:, subject_token:, user_identifier:, scope:, issuer:)
+        if user_identifier
+          client.impersonate(user_identifier: user_identifier, resource: resource, scope: scope, issuer: issuer)
+        else
+          client.exchange_token(subject_token: subject_token, resource: resource, scope: scope, issuer: issuer)
+        end
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/http.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Keycardai
+  module OAuth
+    # Pluggable HTTP transport. Every network operation in the SDK goes
+    # through an object with this surface, so tests and custom transport
+    # policies can inject their own client. No hidden retries: retry policy
+    # belongs to the injected client.
+    module HTTP
+      # A minimal HTTP response: numeric status, header hash, body string.
+      Response = Data.define(:status, :headers, :body) do
+        # @return [Boolean] whether the status is 2xx
+        def success?
+          (200..299).cover?(status)
+        end
+      end
+
+      # Build an HTTP Basic Authorization header value (RFC 7617).
+      #
+      # @return [String]
+      def self.basic_authorization(client_id, client_secret)
+        "Basic #{["#{client_id}:#{client_secret}"].pack("m0")}"
+      end
+
+      # Default transport backed by Net::HTTP. TLS is used for https URLs.
+      class NetHTTPClient
+        # @param url [String]
+        # @param headers [Hash{String => String}]
+        # @param timeout [Numeric, nil] open/read timeout in seconds
+        # @return [Response]
+        # @raise [NetworkError] on DNS, TLS, connect, or timeout failures
+        def get(url, headers: {}, timeout: nil)
+          uri = URI(url)
+          request = Net::HTTP::Get.new(uri)
+          headers.each { |name, value| request[name] = value }
+          perform(uri, request, timeout)
+        end
+
+        # @param url [String]
+        # @param params [Hash] form fields, sent application/x-www-form-urlencoded
+        # @param headers [Hash{String => String}]
+        # @param timeout [Numeric, nil] open/read timeout in seconds
+        # @return [Response]
+        # @raise [NetworkError] on DNS, TLS, connect, or timeout failures
+        def post_form(url, params, headers: {}, timeout: nil)
+          uri = URI(url)
+          request = Net::HTTP::Post.new(uri)
+          headers.each { |name, value| request[name] = value }
+          request.set_form_data(params)
+          perform(uri, request, timeout)
+        end
+
+        # @param url [String]
+        # @param payload [Hash] request body, sent as application/json
+        # @param headers [Hash{String => String}]
+        # @param timeout [Numeric, nil] open/read timeout in seconds
+        # @return [Response]
+        # @raise [NetworkError] on DNS, TLS, connect, or timeout failures
+        def post_json(url, payload, headers: {}, timeout: nil)
+          uri = URI(url)
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          headers.each { |name, value| request[name] = value }
+          request.body = JSON.dump(payload)
+          perform(uri, request, timeout)
+        end
+
+        private
+
+        def perform(uri, request, timeout)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          if timeout
+            http.open_timeout = timeout
+            http.read_timeout = timeout
+          end
+          response = http.request(request)
+          Response.new(status: response.code.to_i, headers: response.to_hash, body: response.body.to_s)
+        rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, EOFError => e
+          raise NetworkError, "request to #{uri.host} failed: #{e.class}"
+        end
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/jwks_keyring.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "jwt"
+require "uri"
+
+module Keycardai
+  module OAuth
+    # Resolves and caches JWKS verification keys for an issuer (RFC 7517), so
+    # bearer-token verification on a hot path does not hit the network per
+    # request. Resolution is a lookup keyed by (issuer, kid): discover the
+    # issuer's jwks_uri (RFC 8414), fetch the key set, select the key matching
+    # the kid. Both steps are cached with a TTL; the key cache is bounded and
+    # evicts its oldest entry on overflow.
+    #
+    # The cache is in-memory and local to this instance. Thread-safe:
+    # concurrent resolutions for the same issuer are de-duplicated so a burst
+    # of cold-cache requests triggers a single discovery and a single JWKS
+    # fetch.
+    class JWKSKeyring
+      DEFAULT_KEY_TTL = 300
+      DEFAULT_DISCOVERY_TTL = 3600
+      DEFAULT_FETCH_TIMEOUT = 10
+      MAX_CACHED_KEYS = 256
+
+      # @param http_client [#get] pluggable transport (see HTTP::NetHTTPClient)
+      # @param key_ttl [Numeric] per-key cache lifetime in seconds
+      # @param discovery_ttl [Numeric] jwks_uri cache lifetime in seconds
+      # @param fetch_timeout [Numeric] timeout for discovery and JWKS fetches
+      # @param clock [#call] returns the current Time; override in tests
+      def initialize(http_client: HTTP::NetHTTPClient.new, key_ttl: DEFAULT_KEY_TTL,
+                     discovery_ttl: DEFAULT_DISCOVERY_TTL, fetch_timeout: DEFAULT_FETCH_TIMEOUT,
+                     clock: -> { Time.now })
+        @http_client = http_client
+        @key_ttl = key_ttl
+        @discovery_ttl = discovery_ttl
+        @fetch_timeout = fetch_timeout
+        @clock = clock
+        @keys = {}
+        @discovery = {}
+        @issuer_locks = {}
+        @mutex = Mutex.new
+      end
+
+      # Resolve the verification key for a token's issuer and kid.
+      #
+      # @param issuer [String] the token issuer URL
+      # @param kid [String] the kid from the JWT header
+      # @return [OpenSSL::PKey::PKey] the verification key
+      # @raise [JWKSDiscoveryError] discovery failed or metadata has no jwks_uri
+      # @raise [JWKSUriValidationError] jwks_uri is cross-origin with the issuer
+      # @raise [JWKSFetchError] the JWKS endpoint failed
+      # @raise [JWKSKeyNotFoundError] the kid is absent from the fetched JWKS
+      def key(issuer, kid)
+        cached = @mutex.synchronize { fresh_key(issuer, kid) }
+        return cached if cached
+
+        issuer_lock(issuer).synchronize do
+          cached = @mutex.synchronize { fresh_key(issuer, kid) }
+          cached || resolve(issuer, kid)
+        end
+      end
+
+      # Drop cached keys and discovery results, for one issuer or all.
+      #
+      # @param issuer [String, nil] limit invalidation to this issuer
+      # @return [void]
+      def invalidate(issuer = nil)
+        @mutex.synchronize do
+          if issuer
+            @keys.delete_if { |(cached_issuer, _), _| cached_issuer == issuer }
+            @discovery.delete(issuer)
+          else
+            @keys.clear
+            @discovery.clear
+          end
+        end
+      end
+
+      private
+
+      def fresh_key(issuer, kid)
+        entry = @keys[[issuer, kid]]
+        return nil unless entry
+        return nil if now - entry[:cached_at] > @key_ttl
+
+        entry[:key]
+      end
+
+      def issuer_lock(issuer)
+        @mutex.synchronize { @issuer_locks[issuer] ||= Mutex.new }
+      end
+
+      def resolve(issuer, kid)
+        jwks_uri = resolve_jwks_uri(issuer)
+        jwk = fetch_jwks(jwks_uri).find { |candidate| candidate["kid"] == kid }
+        raise JWKSKeyNotFoundError, "kid #{kid.inspect} not found in JWKS for #{issuer}" unless jwk
+
+        key = import_key(jwk)
+        cache_key(issuer, kid, key)
+        key
+      end
+
+      def resolve_jwks_uri(issuer)
+        cached = @mutex.synchronize do
+          entry = @discovery[issuer]
+          entry[:jwks_uri] if entry && now - entry[:fetched_at] <= @discovery_ttl
+        end
+        return cached if cached
+
+        jwks_uri = discover_jwks_uri(issuer)
+        assert_same_origin(issuer, jwks_uri)
+        @mutex.synchronize { @discovery[issuer] = { jwks_uri: jwks_uri, fetched_at: now } }
+        jwks_uri
+      end
+
+      def discover_jwks_uri(issuer)
+        metadata = OAuth.fetch_authorization_server_metadata(issuer, http_client: @http_client,
+                                                                     timeout: @fetch_timeout)
+        metadata.jwks_uri || raise(JWKSDiscoveryError, "metadata for #{issuer} has no jwks_uri")
+      rescue HTTPError, ProtocolError, NetworkError, ConfigurationError => e
+        raise JWKSDiscoveryError, "discovery for #{issuer} failed: #{e.message}"
+      end
+
+      def assert_same_origin(issuer, jwks_uri)
+        issuer_uri = URI(issuer)
+        keys_uri = URI(jwks_uri)
+        same = issuer_uri.scheme == keys_uri.scheme && issuer_uri.host == keys_uri.host &&
+               issuer_uri.port == keys_uri.port
+        return if same
+
+        raise JWKSUriValidationError, "jwks_uri #{jwks_uri} is cross-origin with issuer #{issuer}"
+      end
+
+      def fetch_jwks(jwks_uri)
+        response = begin
+          @http_client.get(jwks_uri, headers: { "Accept" => "application/json" }, timeout: @fetch_timeout)
+        rescue NetworkError => e
+          raise JWKSFetchError, "JWKS fetch from #{jwks_uri} failed: #{e.message}"
+        end
+        raise JWKSFetchError, "JWKS fetch from #{jwks_uri} returned HTTP #{response.status}" unless response.success?
+
+        document = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise JWKSFetchError, "JWKS from #{jwks_uri} is invalid JSON"
+        end
+        document["keys"] || raise(JWKSFetchError, "JWKS from #{jwks_uri} has no keys field")
+      end
+
+      def import_key(jwk)
+        JWT::JWK.import(jwk.transform_keys(&:to_sym)).verify_key
+      rescue JWT::JWKError, ArgumentError
+        raise JWKSKeyNotFoundError, "JWK with kid #{jwk["kid"].inspect} could not be converted to a verification key"
+      end
+
+      def cache_key(issuer, kid, key)
+        @mutex.synchronize do
+          @keys.shift while @keys.size >= MAX_CACHED_KEYS
+          @keys[[issuer, kid]] = { key: key, cached_at: now }
+        end
+      end
+
+      def now
+        @clock.call
+      end
+    end
+  end
+end