keycardai-oauth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 33aa8b51bc6809128ee7546762842456ad9e204d0e60655217e879cb498a0b63
+  data.tar.gz: ee37eb4012f1bf46e01058476c6ce4abd4ba23be66c83841fb5114241ec365c4
+SHA512:
+  metadata.gz: 6f150494708f23dddb34ecdcb7bdaaac837cd9d13f6ca1e0730df19536cec26db3d497474b8484cfad13f4d640dbb1831295c5172f6203a4e8c67b6e0683adc5
+  data.tar.gz: 9edbb0dda964b5f65eb88fae046bcb68b29e0b11f447633c27d0af9178b78ed377af2d7c42a2dcfb2fb75fbcffcda0e5c194e984a6ed8fc332ec5ecdc6e021ac

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+Entries from 0.2.0 onward are generated by commitizen on each bump. This first
+one is written by hand because 0.1.0 is published from a baseline tag rather
+than from a bump.
+
+## 0.1.0
+
+Initial release.
+
+OAuth 2.0 primitives for the Keycard platform: authorization server discovery
+(RFC 8414), client credentials, token exchange and impersonation (RFC 8693),
+dynamic client registration (RFC 7591), authorization code with PKCE including
+the loopback flow (RFC 8252), JWT signing and verification with a caching JWKS
+keyring, the three application credentials (ClientSecret with multi-zone,
+WebIdentity, WorkloadIdentity with pluggable token sources), and AccessContext.

data/LICENSE

@@ -0,0 +1,9 @@
+MIT LICENSE
+
+Copyright © 2026 Keycard Labs, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# keycardai-oauth
+
+OAuth 2.0 primitives for the Keycard platform. The foundation gem of the
+[Keycard Ruby SDK](https://github.com/keycardai/ruby-sdk); `keycardai-mcp` and
+`keycardai-a2a` build on it.
+
+> **Preview.** APIs may change between minor versions while the surface settles.
+> Conformance against the cross-SDK contract is tracked in the
+> [conformance report](https://github.com/keycardai/ruby-sdk/blob/main/docs/conformance-report.md).
+
+```sh
+bundle add keycardai-oauth
+```
+
+Capabilities (per [keycard-sdk-spec](https://github.com/keycardai/keycard-sdk-spec)):
+
+- Token exchange and impersonation (RFC 8693)
+- Client credentials grant (RFC 6749 §4.4)
+- Authorization code + PKCE, including the challenge-driven loopback flow (RFC 8252)
+- Dynamic client registration (RFC 7591)
+- Authorization server discovery (RFC 8414)
+- JWT signing and verification, JWKS keyring with caching
+- Application credentials: ClientSecret (incl. multi-zone), WebIdentity (RFC 7523),
+  WorkloadIdentity with pluggable identity token sources
+- AccessContext: the non-throwing per-request container for delegated tokens
+
+## Quickstart
+
+### Verify an inbound token
+
+```ruby
+require "keycardai/oauth"
+
+verifier = Keycardai::OAuth::TokenVerifier.new(
+  issuers: "https://your-zone.keycard.cloud",
+  audiences: "your-resource-id",
+)
+
+begin
+  token = verifier.verify_token(bearer_token)
+  puts token.subject
+  puts token.scopes
+rescue Keycardai::OAuth::InvalidTokenError => e
+  # Fail closed: every verification failure is this one error type.
+  warn "rejected: #{e.message}"
+end
+```
+
+The verifier resolves signing keys through a JWKS keyring that caches per
+`(issuer, kid)`, so a second verification of the same token does no network I/O.
+
+### Exchange a caller's token for a downstream resource
+
+```ruby
+client = Keycardai::OAuth::TokenExchangeClient.new(
+  issuer: "https://your-zone.keycard.cloud",
+  client_id: ENV.fetch("KEYCARD_CLIENT_ID"),
+  client_secret: ENV.fetch("KEYCARD_CLIENT_SECRET"),
+)
+
+result = client.exchange_token(
+  subject_token: bearer_token,
+  resource: "https://api.github.com",
+  scope: "repo:read",
+)
+result.access_token
+```
+
+Nothing here reads the environment on your behalf. Configuration is read in
+application code and passed in explicitly, which is the cross-SDK contract.
+
+### Several resources at once
+
+```ruby
+context = Keycardai::OAuth.exchange_tokens_for_resources(
+  client: client,
+  subject_token: bearer_token,
+  resources: ["https://api.github.com", "https://slack.com/api"],
+)
+
+context.status                        # "success", "partial_error", or "error"
+context.access("https://api.github.com")  # raises if that one resource failed
+context.failed_resources
+```
+
+One resource failing never takes down the others; the failure lands on the
+context rather than raising, and `access` is where you choose to raise.
+
+### Act as a named user
+
+```ruby
+result = client.impersonate(
+  user_identifier: "user@example.com",
+  resource: "https://api.github.com",
+)
+```
+
+The issued token's `sub` is the target user. It is a leaf credential: a zone
+refuses it as the subject of a further exchange, so impersonate again rather
+than trying to trade it up.

data/lib/keycardai/oauth/access_context.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # The per-request container of exchanged downstream tokens, keyed by
+    # resource, with per-resource error tracking. The grant layer constructs
+    # and populates it before the handler runs; handlers read it from the
+    # request context. Population is non-throwing by design: failures land on
+    # the context so a partial-success flow can proceed when only some
+    # exchanges failed.
+    #
+    # Reading is split between the throwing accessor #access and the
+    # non-throwing getters (#resource_error, #error, #errors?, #status, ...),
+    # so handlers can inspect state and choose to proceed, degrade, or fail.
+    class AccessContext
+      # @param tokens [Hash{String => TokenResponse}] seed of successful exchanges
+      def initialize(tokens = {})
+        @tokens = tokens.dup
+        @resource_errors = {}
+        @error = nil
+        @mutex = Mutex.new
+      end
+
+      # The exchanged token for a resource.
+      #
+      # @param resource [String]
+      # @return [TokenResponse]
+      # @raise [ResourceAccessError] a global error is set (global_error), the
+      #   resource recorded an error (resource_error), or no token exists for
+      #   it (missing_token)
+      def access(resource)
+        @mutex.synchronize do
+          raise_access_error("global_error", resource, details: @error) if @error
+          if @resource_errors.key?(resource)
+            raise_access_error("resource_error", resource, details: @resource_errors[resource])
+          end
+
+          @tokens[resource] || raise_access_error("missing_token", resource, available: @tokens.keys)
+        end
+      end
+
+      # @param resource [String]
+      # @return [Object, nil] the recorded error for the resource, nil when it succeeded
+      def resource_error(resource)
+        @mutex.synchronize { @resource_errors[resource] }
+      end
+
+      # @return [Object, nil] the global (context-wide) error
+      def error
+        @mutex.synchronize { @error }
+      end
+
+      # @return [Hash] { resources: Hash{String => Object}, error: Object | nil }
+      def errors
+        @mutex.synchronize { { resources: @resource_errors.dup, error: @error } }
+      end
+
+      # @param resource [String]
+      # @return [Boolean]
+      def resource_error?(resource)
+        @mutex.synchronize { @resource_errors.key?(resource) }
+      end
+
+      # @return [Boolean] whether a global error was set
+      def error?
+        @mutex.synchronize { !@error.nil? }
+      end
+
+      # @return [Boolean] whether a global error or any per-resource error exists
+      def errors?
+        @mutex.synchronize { !@error.nil? || !@resource_errors.empty? }
+      end
+
+      # @return ["success", "partial_error", "error"]
+      def status
+        @mutex.synchronize do
+          next "error" unless @error.nil?
+          next "partial_error" unless @resource_errors.empty?
+
+          "success"
+        end
+      end
+
+      # @return [Array<String>] resources holding a successful token
+      def successful_resources
+        @mutex.synchronize { @tokens.keys }
+      end
+
+      # @return [Array<String>] resources with a recorded error
+      def failed_resources
+        @mutex.synchronize { @resource_errors.keys }
+      end
+
+      # Record a successful token, clearing any prior error for the resource.
+      # Called by the grant layer, not by handlers.
+      #
+      # @return [void]
+      def set_token(resource, token)
+        @mutex.synchronize do
+          @resource_errors.delete(resource)
+          @tokens[resource] = token
+        end
+      end
+
+      # Record multiple successful tokens at once.
+      #
+      # @param tokens [Hash{String => TokenResponse}]
+      # @return [void]
+      def set_bulk_tokens(tokens)
+        @mutex.synchronize do
+          tokens.each do |resource, token|
+            @resource_errors.delete(resource)
+            @tokens[resource] = token
+          end
+        end
+      end
+
+      # Record a per-resource error, clearing any prior token for the resource.
+      #
+      # @return [void]
+      def set_resource_error(resource, error)
+        @mutex.synchronize do
+          @tokens.delete(resource)
+          @resource_errors[resource] = error
+        end
+      end
+
+      # Record a global (context-wide) error.
+      #
+      # @return [void]
+      def set_error(error)
+        @mutex.synchronize { @error = error }
+      end
+
+      # Merge another context's tokens and errors into this one.
+      #
+      # @param other [AccessContext]
+      # @return [void]
+      def merge(other)
+        snapshot = other.errors
+        unless snapshot[:error]
+          set_bulk_tokens(other.successful_resources.to_h { |resource| [resource, other.access(resource)] })
+        end
+        snapshot[:resources].each { |resource, error| set_resource_error(resource, error) }
+        set_error(snapshot[:error]) if snapshot[:error]
+      end
+
+      private
+
+      def raise_access_error(error_type, resource, details: nil, available: [])
+        message = {
+          "global_error" => "a context-wide error is set",
+          "resource_error" => "the exchange for #{resource} failed",
+          "missing_token" => "no token was granted for #{resource}"
+        }.fetch(error_type)
+        raise ResourceAccessError.new(message, resource: resource, error_type: error_type,
+                                               error_details: details, available_resources: available)
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/authenticate.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "socket"
+require "uri"
+
+module Keycardai
+  # The high-level authorization-code convenience: open the browser, receive
+  # the redirect on a loopback server (RFC 8252), exchange the code.
+  module OAuth
+    DEFAULT_CALLBACK_PORT = 8765
+    DEFAULT_CALLBACK_TIMEOUT = 300
+
+    # Run the full authorization-code + PKCE login flow: generate the PKCE
+    # pair and a CSRF state, build the authorize URL, open the user's
+    # browser, receive the redirect on a local loopback server, validate the
+    # state, and exchange the code for a token.
+    #
+    # @param issuer [String] the zone's issuer URL
+    # @param client_id [String]
+    # @param scope [String, nil] space-separated scopes
+    # @param resource [String, nil] RFC 8707 resource indicator
+    # @param port [Integer] loopback port; 0 binds an ephemeral port
+    # @param callback_timeout [Numeric] seconds to wait for the redirect
+    # @param client_secret [String, nil] confidential clients only
+    # @param verifier_length [Integer] PKCE verifier length, 43 to 128
+    # @param http_client [#get, #post_form] pluggable transport
+    # @param browser_opener [#call, nil] receives the authorize URL; defaults
+    #   to the platform opener (open / xdg-open / cmd start), shell-free
+    # @param timeout [Numeric, nil] HTTP timeout for discovery and exchange
+    # @return [TokenResponse]
+    # @raise [InteractionTimeoutError] the user did not complete the redirect
+    # @raise [OAuthError] the authorization server denied the request
+    # @raise [ProtocolError] the redirect's state did not match (code state_mismatch)
+    def self.authenticate(issuer:, client_id:, scope: nil, resource: nil, port: DEFAULT_CALLBACK_PORT,
+                          callback_timeout: DEFAULT_CALLBACK_TIMEOUT, client_secret: nil,
+                          verifier_length: PKCE::DEFAULT_VERIFIER_LENGTH,
+                          http_client: HTTP::NetHTTPClient.new, browser_opener: nil, timeout: nil)
+      authorization_endpoint = authorization_endpoint_for(issuer, http_client, timeout)
+      pair = PKCE.generate_pair(length: verifier_length)
+      state = SecureRandom.urlsafe_base64(24)
+
+      Loopback::CallbackServer.open(port: port) do |server|
+        open_authorize_page(server, authorization_endpoint, pair, state,
+                            client_id: client_id, scope: scope, resource: resource,
+                            browser_opener: browser_opener)
+        code = server.wait_for_code(state: state, timeout: callback_timeout)
+        exchange_authorization_code(
+          issuer,
+          code: code, code_verifier: pair.code_verifier, redirect_uri: server.redirect_uri,
+          client_id: client_id, client_secret: client_secret, resource: resource,
+          http_client: http_client, timeout: timeout
+        )
+      end
+    end
+
+    def self.authorization_endpoint_for(issuer, http_client, timeout)
+      metadata = fetch_authorization_server_metadata(issuer, http_client: http_client, timeout: timeout)
+      metadata.authorization_endpoint ||
+        raise(ProtocolError.new("metadata for #{issuer} has no authorization_endpoint", code: "invalid_metadata"))
+    end
+    private_class_method :authorization_endpoint_for
+
+    def self.open_authorize_page(server, endpoint, pair, state, client_id:, scope:, resource:, browser_opener:)
+      url = build_authorize_url(
+        endpoint,
+        client_id: client_id, redirect_uri: server.redirect_uri, code_challenge: pair.code_challenge,
+        code_challenge_method: pair.code_challenge_method, scope: scope, state: state, resource: resource
+      )
+      (browser_opener || Loopback.method(:open_browser)).call(url)
+    end
+    private_class_method :open_authorize_page
+
+    # Resolve the issuer from a resource's WWW-Authenticate challenge
+    # (RFC 9728): fetch the challenge's resource_metadata document and return
+    # its first authorization server.
+    #
+    # @param www_authenticate [String] the WWW-Authenticate header value
+    # @param http_client [#get] pluggable transport
+    # @param timeout [Numeric, nil]
+    # @return [String] the issuer URL
+    # @raise [ProtocolError] no resource_metadata parameter, or a metadata
+    #   document without authorization_servers
+    def self.resolve_issuer_from_challenge(www_authenticate, http_client: HTTP::NetHTTPClient.new, timeout: nil)
+      metadata_url = www_authenticate.to_s[/resource_metadata="([^"]+)"/, 1]
+      unless metadata_url
+        raise ProtocolError.new("challenge carries no resource_metadata parameter", code: "invalid_metadata")
+      end
+
+      document = Loopback.fetch_resource_metadata(metadata_url, http_client, timeout)
+      issuer = Array(document["authorization_servers"]).first
+      issuer || raise(ProtocolError.new("resource metadata lists no authorization_servers", code: "invalid_metadata"))
+    end
+
+    # Challenge-driven entry to the login flow: resolve the issuer from a
+    # WWW-Authenticate challenge, then run authenticate against it.
+    #
+    # @param www_authenticate [String] the WWW-Authenticate header value
+    # @param options [Hash] forwarded to authenticate
+    # @return [TokenResponse]
+    def self.authenticate_from_challenge(www_authenticate, http_client: HTTP::NetHTTPClient.new, **options)
+      issuer = resolve_issuer_from_challenge(www_authenticate, http_client: http_client,
+                                                               timeout: options[:timeout])
+      authenticate(issuer: issuer, http_client: http_client, **options)
+    end
+
+    # Internals of the loopback flow. Not public API.
+    module Loopback
+      SUCCESS_PAGE = "<html><body><p>Authentication complete. You can close this window.</p></body></html>"
+
+      module_function
+
+      def fetch_resource_metadata(url, http_client, timeout)
+        response = http_client.get(url, headers: { "Accept" => "application/json" }, timeout: timeout)
+        unless response.success?
+          raise HTTPError.new("resource metadata fetch returned HTTP #{response.status}",
+                              status: response.status, body: response.body)
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise ProtocolError.new("resource metadata is not valid JSON", code: "invalid_metadata")
+      end
+
+      # Open the system browser without a shell.
+      def open_browser(url)
+        command = case RUBY_PLATFORM
+                  when /darwin/ then ["open", url]
+                  when /mswin|mingw/ then ["cmd", "/c", "start", "", url]
+                  else ["xdg-open", url]
+                  end
+        Process.spawn(*command, %i[out err] => File::NULL)
+      end
+
+      # A single-shot loopback HTTP server receiving the OAuth redirect.
+      class CallbackServer
+        PATH = "/callback"
+
+        # @return [String] the redirect URI registered for this flow
+        attr_reader :redirect_uri
+
+        def self.open(port:)
+          server = new(port: port)
+          begin
+            yield server
+          ensure
+            server.close
+          end
+        end
+
+        def initialize(port:)
+          @server = TCPServer.new("127.0.0.1", port)
+          @redirect_uri = "http://127.0.0.1:#{@server.addr[1]}#{PATH}"
+        end
+
+        def close
+          @server.close unless @server.closed?
+        end
+
+        # Wait for the redirect, validate its state, and return the code.
+        #
+        # @raise [InteractionTimeoutError] no redirect within the timeout
+        # @raise [ProtocolError] state mismatch (code state_mismatch)
+        # @raise [OAuthError] the redirect carried an OAuth error
+        def wait_for_code(state:, timeout:)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise InteractionTimeoutError, "no redirect received within #{timeout}s" if remaining <= 0
+            next unless @server.wait_readable(remaining)
+
+            params = accept_redirect
+            next unless params
+
+            return validate(params, state)
+          end
+        end
+
+        private
+
+        def accept_redirect
+          client = @server.accept
+          request_line = client.gets.to_s
+          drain_headers(client)
+          client.write("HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n" \
+                       "Content-Length: #{SUCCESS_PAGE.bytesize}\r\nConnection: close\r\n\r\n#{SUCCESS_PAGE}")
+          client.close
+          parse_target(request_line)
+        end
+
+        def drain_headers(client)
+          loop do
+            line = client.gets
+            break if line.nil? || line.strip.empty?
+          end
+        end
+
+        def parse_target(request_line)
+          target = request_line.split[1].to_s
+          uri = URI("http://127.0.0.1#{target}")
+          return nil unless uri.path == PATH
+
+          URI.decode_www_form(uri.query.to_s).to_h
+        end
+
+        def validate(params, state)
+          if params["error"]
+            raise OAuthError.new("authorization was denied: #{params["error"]}",
+                                 error: params["error"], error_description: params["error_description"],
+                                 status: 400)
+          end
+          unless params["state"] == state
+            raise ProtocolError.new("redirect state does not match the authorization request",
+                                    code: "state_mismatch")
+          end
+
+          params["code"] || raise(ProtocolError.new("redirect carries no code", code: "invalid_response"))
+        end
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/authorization_code.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Keycardai
+  # Authorization-code grant building blocks (RFC 6749 §4.1 + RFC 7636): the
+  # authorize-URL builder and the back-channel code exchange.
+  module OAuth
+    # Build the authorization request URL.
+    #
+    # @param authorization_endpoint [String] from discovery
+    # @param client_id [String]
+    # @param redirect_uri [String]
+    # @param code_challenge [String] the PKCE challenge
+    # @param code_challenge_method [String] the method the challenge was derived with
+    # @param scope [String, nil] space-separated scopes
+    # @param state [String, nil] CSRF state value
+    # @param resource [String, nil] RFC 8707 resource indicator
+    # @return [String] the authorize URL
+    def self.build_authorize_url(authorization_endpoint, client_id:, redirect_uri:, code_challenge:,
+                                 code_challenge_method: "S256", scope: nil, state: nil, resource: nil)
+      params = {
+        "response_type" => "code",
+        "client_id" => client_id,
+        "redirect_uri" => redirect_uri,
+        "code_challenge" => code_challenge,
+        "code_challenge_method" => code_challenge_method,
+        "scope" => scope,
+        "state" => state,
+        "resource" => resource
+      }.compact
+
+      uri = URI(authorization_endpoint)
+      query = URI.encode_www_form(params)
+      uri.query = uri.query.nil? || uri.query.empty? ? query : "#{uri.query}&#{query}"
+      uri.to_s
+    end
+
+    # Exchange an authorization code for a token (RFC 6749 §4.1.3). A public
+    # client sends its client_id in the body; a confidential client
+    # authenticates with HTTP Basic and omits client_id from the body.
+    #
+    # @param issuer [String] the zone's issuer URL; supplies the token endpoint
+    # @param code [String] the authorization code from the redirect
+    # @param code_verifier [String] the PKCE verifier matching the challenge
+    # @param redirect_uri [String] must match the authorization request
+    # @param client_id [String, nil] public-client identifier
+    # @param client_secret [String, nil] confidential-client secret; requires client_id
+    # @param resource [String, nil] RFC 8707 resource indicator
+    # @param http_client [#get, #post_form] pluggable transport
+    # @param timeout [Numeric, nil]
+    # @return [TokenResponse]
+    # @raise [OAuthError] an RFC 6749 §5.2 error response (invalid_grant, ...)
+    # @raise [HTTPError, ProtocolError, NetworkError, ConfigurationError]
+    def self.exchange_authorization_code(issuer, code:, code_verifier:, redirect_uri:, client_id: nil,
+                                         client_secret: nil, resource: nil,
+                                         http_client: HTTP::NetHTTPClient.new, timeout: nil)
+      raise ConfigurationError, "client_secret requires client_id" if client_secret && client_id.nil?
+
+      metadata = fetch_authorization_server_metadata(issuer, http_client: http_client, timeout: timeout)
+      endpoint = metadata.token_endpoint ||
+                 raise(ProtocolError.new("metadata for #{issuer} has no token_endpoint", code: "invalid_metadata"))
+
+      # A confidential client authenticates with Basic and omits client_id
+      # from the body; a public client carries client_id in the body.
+      params = {
+        "grant_type" => GrantType::AUTHORIZATION_CODE,
+        "code" => code,
+        "code_verifier" => code_verifier,
+        "redirect_uri" => redirect_uri,
+        "client_id" => client_secret ? nil : client_id,
+        "resource" => resource
+      }.compact
+      headers = { "Accept" => "application/json" }
+      headers["Authorization"] = HTTP.basic_authorization(client_id, client_secret) if client_secret
+
+      TokenRequests.parse_response(http_client.post_form(endpoint, params, headers: headers, timeout: timeout))
+    end
+  end
+end

data/lib/keycardai/oauth/client_credentials_client.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # OAuth 2.0 client_credentials grant (RFC 6749 §4.4): autonomous workload
+    # authentication. The client requests a token for itself, with no user in
+    # the loop, and authenticates with a shared secret (HTTP Basic) or a
+    # client assertion carried on the request.
+    #
+    # The token endpoint is discovered from the issuer on first use and
+    # cached. Requests do not retry transparently.
+    class ClientCredentialsClient
+      include TokenRequests
+
+      # @param issuer [String] the zone's issuer URL
+      # @param credential [Object, nil] a Basic-auth credential (ClientSecret);
+      #   exclusive with client_id/client_secret. Assertion-based credentials
+      #   supply their assertion through the request fields instead.
+      # @param client_id [String, nil] shared-secret client id (HTTP Basic)
+      # @param client_secret [String, nil] shared-secret client secret;
+      #   provide both or neither
+      # @param http_client [#get, #post_form] pluggable transport
+      # @param timeout [Numeric, nil] request timeout in seconds
+      # @raise [ConfigurationError] when only one of client_id/client_secret is
+      #   given, or a credential is combined with a raw pair
+      def initialize(issuer:, credential: nil, client_id: nil, client_secret: nil,
+                     http_client: HTTP::NetHTTPClient.new, timeout: nil)
+        initialize_token_client(issuer: issuer, credential: credential, client_id: client_id,
+                                client_secret: client_secret, http_client: http_client, timeout: timeout)
+      end
+
+      # Request a token for the client itself.
+      #
+      # @param scope [String, nil] space-separated scopes for the token
+      # @param resource [String, nil] RFC 8707 resource indicator
+      # @param client_assertion [String, nil] client-authentication assertion,
+      #   form-encoded in the body
+      # @param client_assertion_type [String, nil]
+      # @return [TokenResponse]
+      # @raise [OAuthError] an RFC 6749 §5.2 error response (invalid_client,
+      #   invalid_scope, ...)
+      # @raise [HTTPError, ProtocolError, NetworkError]
+      def request_token(scope: nil, resource: nil, client_assertion: nil, client_assertion_type: nil,
+                        issuer: nil)
+        post_token_request(
+          {
+            "grant_type" => GrantType::CLIENT_CREDENTIALS,
+            "scope" => scope,
+            "resource" => resource,
+            "client_assertion" => client_assertion,
+            "client_assertion_type" => client_assertion_type
+          },
+          issuer: issuer || @issuer
+        )
+      end
+    end
+  end
+end