keycardai-oauth 0.1.0

data/lib/keycardai/oauth/jwt_signer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module Keycardai
+  module OAuth
+    # Signs compact JWTs (RFC 7519) with RS256, the baseline algorithm the SDK
+    # family uses for private_key_jwt client assertions (RFC 7523) and signed
+    # access tokens (RFC 9068).
+    #
+    # The signer writes the JWT header ({alg, kid}) from its construction-time
+    # key material. Claims are signed verbatim: temporal claims (exp, iat, nbf)
+    # come from the caller and the signer does not invent an expiry. When the
+    # claims omit iss and the signer carries an issuer, iss is filled in; a
+    # caller-supplied iss is preserved.
+    class JWTSigner
+      ALGORITHM = "RS256"
+
+      # @param key [OpenSSL::PKey::RSA] the RSA private signing key
+      # @param kid [String] key id written to the JWT header
+      # @param issuer [String, nil] default iss, applied only when claims omit it
+      # @raise [ConfigurationError] when the key is not an RSA private key
+      def initialize(key:, kid:, issuer: nil)
+        unless key.is_a?(OpenSSL::PKey::RSA) && key.private?
+          raise ConfigurationError, "JWTSigner requires an RSA private key"
+        end
+        raise ConfigurationError, "JWTSigner requires a kid" if kid.nil? || kid.empty?
+
+        @key = key
+        @kid = kid
+        @issuer = issuer
+      end
+
+      # Sign a claim set into a compact JWS (header.payload.signature).
+      #
+      # @param claims [Hash] payload claims; string or symbol keys
+      # @return [String] the signed compact JWT
+      def sign(claims)
+        payload = claims.transform_keys(&:to_s)
+        payload["iss"] = @issuer if @issuer && !payload.key?("iss")
+        JWT.encode(payload, @key, ALGORITHM, { "kid" => @kid })
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/jwt_verifier.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Keycardai
+  module OAuth
+    # Verifies compact JWTs (RFC 7519) against the RFC 9068 access-token
+    # profile, fail-closed. Cheap policy checks (algorithm, trusted issuer,
+    # required claims, expiry, audience, kid) run before any key resolution,
+    # so a token carrying an attacker-controlled iss never drives key lookup
+    # or network I/O. Verification keys are resolved by (issuer, kid) through
+    # the injected keyring (see JWKSKeyring).
+    #
+    # Every rejection raises InvalidTokenError; misconfiguration raises
+    # ConfigurationError at construction.
+    class JWTVerifier
+      SUPPORTED_ALGORITHMS = ["RS256"].freeze
+      REQUIRED_CLAIMS = %w[iss sub aud exp iat client_id].freeze
+
+      # @param issuers [String, Array<String>] trusted-issuer allowlist
+      # @param keyring [#key] resolves a verification key for (issuer, kid)
+      # @param audiences [String, Array<String>, nil] when set, the token's aud
+      #   must intersect this set
+      # @param algorithms [Array<String>] allowed alg header values
+      # @param clock_skew [Numeric] leeway in seconds applied to exp and nbf
+      # @param clock [#call] returns the current Time; override in tests
+      # @raise [ConfigurationError] no trusted issuer, or an algorithm the
+      #   verifier does not implement
+      def initialize(issuers:, keyring:, audiences: nil, algorithms: SUPPORTED_ALGORITHMS,
+                     clock_skew: 0, clock: -> { Time.now })
+        @issuers = Array(issuers).reject { |issuer| issuer.nil? || issuer.empty? }
+        raise ConfigurationError, "JWTVerifier requires at least one trusted issuer" if @issuers.empty?
+
+        unimplemented = Array(algorithms) - SUPPORTED_ALGORITHMS
+        raise ConfigurationError, "unimplemented algorithms: #{unimplemented.join(", ")}" unless unimplemented.empty?
+
+        @keyring = keyring
+        @audiences = audiences.nil? ? nil : Array(audiences)
+        @algorithms = Array(algorithms)
+        @clock_skew = clock_skew
+        @clock = clock
+      end
+
+      # Verify a compact JWT and return its claim set.
+      #
+      # @param token [String]
+      # @return [Hash] the verified claims, string-keyed
+      # @raise [InvalidTokenError] on any verification failure
+      # @raise [JWKSError] when key resolution fails (see JWKSKeyring)
+      def verify(token)
+        header, claims, signature, signing_input = decode_parts(token)
+        check_algorithm(header)
+        check_issuer(claims)
+        check_required_claims(claims)
+        check_temporal(claims)
+        check_audience(claims)
+        kid = header["kid"]
+        raise InvalidTokenError, "token header has no kid" if kid.nil? || kid.empty?
+
+        key = @keyring.key(claims["iss"], kid)
+        check_signature(key, signature, signing_input)
+        claims
+      end
+
+      private
+
+      def decode_parts(token)
+        parts = String(token).split(".")
+        raise InvalidTokenError, "token is not a three-part compact JWT" unless parts.length == 3
+
+        header = decode_json_segment(parts[0], "header")
+        claims = decode_json_segment(parts[1], "payload")
+        signature = decode_segment(parts[2], "signature")
+        [header, claims, signature, parts[0..1].join(".")]
+      end
+
+      def decode_segment(segment, name)
+        padded = segment.tr("-_", "+/")
+        padded += "=" * ((4 - (padded.length % 4)) % 4)
+        padded.unpack1("m0")
+      rescue ArgumentError
+        raise InvalidTokenError, "token #{name} does not decode"
+      end
+
+      def decode_json_segment(segment, name)
+        document = JSON.parse(decode_segment(segment, name))
+        raise InvalidTokenError, "token #{name} is not a JSON object" unless document.is_a?(Hash)
+
+        document
+      rescue JSON::ParserError
+        raise InvalidTokenError, "token #{name} is not valid JSON"
+      end
+
+      def check_algorithm(header)
+        algorithm = header["alg"]
+        raise InvalidTokenError, "token alg is missing" if algorithm.nil? || algorithm.empty?
+        raise InvalidTokenError, "token alg none is rejected" if algorithm.casecmp("none").zero?
+        raise InvalidTokenError, "token alg #{algorithm} is not allowed" unless @algorithms.include?(algorithm)
+      end
+
+      def check_issuer(claims)
+        issuer = claims["iss"]
+        return if issuer.is_a?(String) && @issuers.include?(issuer)
+
+        raise InvalidTokenError, "token issuer is not trusted"
+      end
+
+      def check_required_claims(claims)
+        missing = REQUIRED_CLAIMS.reject { |name| claims.key?(name) }
+        raise InvalidTokenError, "token is missing required claims: #{missing.join(", ")}" unless missing.empty?
+        return if claims["exp"].is_a?(Numeric) && claims["exp"].to_f.finite?
+
+        raise InvalidTokenError,
+              "token exp is not a number"
+      end
+
+      def check_temporal(claims)
+        current = @clock.call.to_i
+        raise InvalidTokenError, "token is expired" if current > claims["exp"] + @clock_skew
+
+        not_before = claims["nbf"]
+        return unless not_before.is_a?(Numeric)
+        raise InvalidTokenError, "token is not yet valid" if current < not_before - @clock_skew
+      end
+
+      def check_audience(claims)
+        return if @audiences.nil?
+
+        token_audiences = Array(claims["aud"])
+        return if token_audiences.intersect?(@audiences)
+
+        raise InvalidTokenError, "token audience does not match"
+      end
+
+      def check_signature(key, signature, signing_input)
+        # RS256: RSASSA-PKCS1-v1_5 with SHA-256.
+        return if key.verify(OpenSSL::Digest.new("SHA256"), signature, signing_input)
+
+        raise InvalidTokenError, "token signature does not validate"
+      rescue OpenSSL::PKey::PKeyError
+        raise InvalidTokenError, "token signature does not validate"
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/pkce.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module Keycardai
+  module OAuth
+    # PKCE primitives (RFC 7636): generate a code verifier and derive its
+    # challenge. S256 is the default and the method public clients should use;
+    # plain is RFC-permitted but not recommended.
+    module PKCE
+      VERIFIER_CHARSET = [*"A".."Z", *"a".."z", *"0".."9", "-", ".", "_", "~"].freeze
+      DEFAULT_VERIFIER_LENGTH = 128
+      METHODS = %w[S256 plain].freeze
+
+      # A verifier with its derived challenge.
+      Pair = Data.define(:code_verifier, :code_challenge, :code_challenge_method)
+
+      module_function
+
+      # Generate a cryptographically random verifier (RFC 7636 §4.1).
+      #
+      # @param length [Integer] 43 to 128
+      # @return [String]
+      def generate_code_verifier(length: DEFAULT_VERIFIER_LENGTH)
+        raise ArgumentError, "verifier length must be between 43 and 128, got #{length}" unless (43..128).cover?(length)
+
+        Array.new(length) { VERIFIER_CHARSET[SecureRandom.random_number(VERIFIER_CHARSET.length)] }.join
+      end
+
+      # Derive the challenge for a verifier (RFC 7636 §4.2).
+      #
+      # @param code_verifier [String]
+      # @param method ["S256", "plain"]
+      # @return [String]
+      def generate_code_challenge(code_verifier, method: "S256")
+        case method
+        when "S256"
+          [OpenSSL::Digest.digest("SHA256", code_verifier)].pack("m0").tr("+/", "-_").delete("=")
+        when "plain"
+          code_verifier
+        else
+          raise ArgumentError, "unsupported code_challenge_method #{method.inspect}"
+        end
+      end
+
+      # Generate a verifier and its challenge together.
+      #
+      # @param length [Integer] verifier length, 43 to 128
+      # @param method ["S256", "plain"]
+      # @return [Pair]
+      def generate_pair(length: DEFAULT_VERIFIER_LENGTH, method: "S256")
+        code_verifier = generate_code_verifier(length: length)
+        Pair.new(
+          code_verifier: code_verifier,
+          code_challenge: generate_code_challenge(code_verifier, method: method),
+          code_challenge_method: method
+        )
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/private_key.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "jwt"
+require "openssl"
+require "securerandom"
+
+module Keycardai
+  module OAuth
+    # Pluggable keypair persistence for WebIdentity. The duck type is
+    # load(key_id) returning a PEM string or nil, and store(key_id, pem).
+    # This default stores PEM files on disk, checking legacy directories on
+    # load so existing keys keep working.
+    class FilePrivateKeyStorage
+      DEFAULT_DIR = "./server_keys"
+      LEGACY_DIRS = ["./mcp_keys"].freeze
+
+      # @param dir [String] directory for new and existing keys
+      def initialize(dir: DEFAULT_DIR)
+        @dir = dir
+      end
+
+      # @param key_id [String]
+      # @return [String, nil] the stored PEM, or nil when absent
+      def load(key_id)
+        [@dir, *LEGACY_DIRS].each do |dir|
+          path = File.join(dir, "#{key_id}.pem")
+          return File.read(path) if File.file?(path)
+        end
+        nil
+      end
+
+      # @param key_id [String]
+      # @param pem [String]
+      # @return [void]
+      def store(key_id, pem)
+        FileUtils.mkdir_p(@dir)
+        path = File.join(@dir, "#{key_id}.pem")
+        File.write(path, pem)
+        File.chmod(0o600, path)
+      end
+    end
+
+    # Generates, persists, and loads an RSA-2048 keypair, and signs RFC 7523
+    # private_key_jwt client assertions with it. WebIdentity composes this;
+    # it is also usable standalone.
+    class PrivateKeyManager
+      ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+      DEFAULT_ASSERTION_LIFETIME = 300
+
+      # @return [String] the key id (the JWT kid)
+      attr_reader :key_id
+
+      # @param key_id [String]
+      # @param storage [#load, #store] keypair persistence
+      # @param clock [#call] returns the current Time; override in tests
+      def initialize(key_id:, storage: FilePrivateKeyStorage.new, clock: -> { Time.now })
+        @key_id = key_id
+        @storage = storage
+        @clock = clock
+        @key = nil
+        @mutex = Mutex.new
+      end
+
+      # Load the persisted keypair, generating and storing one on first use.
+      #
+      # @return [OpenSSL::PKey::RSA]
+      def key
+        @mutex.synchronize do
+          @key ||= begin
+            pem = @storage.load(@key_id)
+            pem ? OpenSSL::PKey::RSA.new(pem) : generate
+          end
+        end
+      end
+
+      # Sign a short-lived client assertion (RFC 7523 §3).
+      #
+      # @param client_id [String] becomes iss and sub
+      # @param audience [String] the authorization server's token endpoint
+      # @param expiry_seconds [Integer]
+      # @return [String] the signed assertion
+      def create_client_assertion(client_id:, audience:, expiry_seconds: DEFAULT_ASSERTION_LIFETIME)
+        now = @clock.call.to_i
+        claims = {
+          "iss" => client_id, "sub" => client_id, "aud" => audience,
+          "jti" => SecureRandom.uuid, "iat" => now, "exp" => now + expiry_seconds
+        }
+        JWTSigner.new(key: key, kid: @key_id).sign(claims)
+      end
+
+      # The public half as a JWKS document, for the authorization server to
+      # verify assertions against.
+      #
+      # @return [Hash] {"keys" => [...]}
+      def public_jwks
+        jwk = JWT::JWK.new(key.public_key, { kid: @key_id, use: "sig", alg: "RS256" })
+        { "keys" => [jwk.export.transform_keys(&:to_s)] }
+      end
+
+      private
+
+      def generate
+        key = OpenSSL::PKey::RSA.new(2048)
+        @storage.store(@key_id, key.to_pem)
+        key
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/registration.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Keycardai
+  # Dynamic client registration (RFC 7591).
+  module OAuth
+    # The result of registering a client (RFC 7591 §3.2.1). The server's full
+    # response, including echoed metadata and AS-specific fields, is preserved
+    # in +raw+.
+    ClientRegistrationResponse = Data.define(
+      :client_id, :client_secret, :client_id_issued_at, :client_secret_expires_at,
+      :registration_access_token, :registration_client_uri, :raw
+    ) do
+      # @param field [String] a response field name
+      # @return [Object, nil] the field's value from the full response body
+      def [](field)
+        raw[field]
+      end
+    end
+
+    REGISTRATION_METADATA_FIELDS = %w[
+      client_name redirect_uris grant_types response_types scope
+      token_endpoint_auth_method jwks_uri jwks client_uri logo_uri tos_uri
+      policy_uri software_id software_version
+    ].freeze
+
+    # Register a new OAuth client with the zone (RFC 7591). Sends only the
+    # fields the caller supplies; omitted metadata is defaulted by the
+    # authorization server. Vendor-extension fields go in additional_metadata,
+    # with named fields winning on conflict.
+    #
+    # @param issuer [String] the zone's issuer URL; supplies the registration endpoint
+    # @param client_name [String, nil]
+    # @param redirect_uris [Array<String>, nil] required by RFC 7591 when
+    #   grant_types includes authorization_code; enforced by the server
+    # @param grant_types [Array<String>, nil]
+    # @param response_types [Array<String>, nil]
+    # @param scope [String, nil] space-separated scopes
+    # @param token_endpoint_auth_method [String, nil]
+    # @param jwks_uri [String, nil]
+    # @param jwks [Hash, nil]
+    # @param client_uri [String, nil]
+    # @param logo_uri [String, nil]
+    # @param tos_uri [String, nil]
+    # @param policy_uri [String, nil]
+    # @param software_id [String, nil]
+    # @param software_version [String, nil]
+    # @param additional_metadata [Hash, nil] vendor or AS-specific fields
+    # @param initial_access_token [String, nil] RFC 7591 §3.1 registration
+    #   authentication, sent as a Bearer credential
+    # @param http_client [#get, #post_json] pluggable transport
+    # @param timeout [Numeric, nil]
+    # @return [ClientRegistrationResponse]
+    # @raise [OAuthError] an RFC 7591 §3.2.2 error (invalid_client_metadata,
+    #   invalid_redirect_uri, ...)
+    # @raise [HTTPError, ProtocolError, NetworkError]
+    def self.register_client(issuer, client_name: nil, redirect_uris: nil, grant_types: nil,
+                             response_types: nil, scope: nil, token_endpoint_auth_method: nil,
+                             jwks_uri: nil, jwks: nil, client_uri: nil, logo_uri: nil, tos_uri: nil,
+                             policy_uri: nil, software_id: nil, software_version: nil,
+                             additional_metadata: nil, initial_access_token: nil,
+                             http_client: HTTP::NetHTTPClient.new, timeout: nil)
+      named = {
+        "client_name" => client_name, "redirect_uris" => redirect_uris, "grant_types" => grant_types,
+        "response_types" => response_types, "scope" => scope,
+        "token_endpoint_auth_method" => token_endpoint_auth_method, "jwks_uri" => jwks_uri,
+        "jwks" => jwks, "client_uri" => client_uri, "logo_uri" => logo_uri, "tos_uri" => tos_uri,
+        "policy_uri" => policy_uri, "software_id" => software_id, "software_version" => software_version
+      }.compact
+      body = (additional_metadata || {}).transform_keys(&:to_s).merge(named)
+
+      Registration.post(issuer, body, initial_access_token, http_client, timeout)
+    end
+
+    # Internals of dynamic client registration. Not public API.
+    module Registration
+      module_function
+
+      def post(issuer, body, initial_access_token, http_client, timeout)
+        metadata = OAuth.fetch_authorization_server_metadata(issuer, http_client: http_client, timeout: timeout)
+        endpoint = metadata.registration_endpoint ||
+                   raise(ProtocolError.new("metadata for #{issuer} has no registration_endpoint",
+                                           code: "invalid_metadata"))
+
+        headers = { "Accept" => "application/json" }
+        headers["Authorization"] = "Bearer #{initial_access_token}" if initial_access_token
+        parse(http_client.post_json(endpoint, body, headers: headers, timeout: timeout))
+      end
+
+      def parse(response)
+        raise TokenRequests.error_for(response) unless response.success?
+
+        build(parse_document(response.body))
+      end
+
+      def parse_document(body)
+        document = JSON.parse(body)
+        unless document.is_a?(Hash) && document["client_id"].is_a?(String) && !document["client_id"].empty?
+          raise ProtocolError.new("registration response has no client_id", code: "invalid_response")
+        end
+
+        document
+      rescue JSON::ParserError
+        raise ProtocolError.new("registration response is not valid JSON", code: "invalid_response")
+      end
+
+      def build(document)
+        ClientRegistrationResponse.new(
+          client_id: document["client_id"],
+          client_secret: document["client_secret"],
+          client_id_issued_at: document["client_id_issued_at"],
+          client_secret_expires_at: document["client_secret_expires_at"],
+          registration_access_token: document["registration_access_token"],
+          registration_client_uri: document["registration_client_uri"],
+          raw: document
+        )
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/substitute_user.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Keycardai
+  # The substitute-user token builder for impersonation exchanges.
+  module OAuth
+    # Build the unsigned substitute-user JWT used as the subject token of an
+    # impersonation exchange. The authorization server derives the acting
+    # party from client authentication; this token only names the target user.
+    #
+    # Shape: header {"typ": "vnd.kc.su+jwt", "alg": "none"}, payload
+    # {"sub": user_identifier}, encoded header.payload. with a trailing dot
+    # and no signature.
+    #
+    # @param user_identifier [String] the target user (becomes sub)
+    # @return [String]
+    def self.build_substitute_user_token(user_identifier)
+      if user_identifier.nil? || user_identifier.empty?
+        raise ArgumentError, "user_identifier must be a non-empty string"
+      end
+
+      header = { "typ" => "vnd.kc.su+jwt", "alg" => "none" }
+      payload = { "sub" => user_identifier }
+      encode = ->(part) { [JSON.dump(part)].pack("m0").tr("+/", "-_").delete("=") }
+      "#{encode.call(header)}.#{encode.call(payload)}."
+    end
+  end
+end

data/lib/keycardai/oauth/token_exchange_client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # RFC 8693 token exchange: swap a subject token for a fresh token scoped
+    # to a downstream resource, the core delegation primitive. Also exposes
+    # the impersonation convenience, a substitute-user exchange where the
+    # authorization server derives the acting party from client
+    # authentication.
+    #
+    # The token endpoint is discovered from the issuer on first use and
+    # cached. Requests do not retry transparently.
+    class TokenExchangeClient
+      include TokenRequests
+
+      # @param issuer [String] the zone's issuer URL
+      # @param credential [Object, nil] an application credential (ClientSecret,
+      #   WebIdentity, WorkloadIdentity); exclusive with client_id/client_secret
+      # @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
+
+      # Exchange a subject token (RFC 8693).
+      #
+      # @param subject_token [String] the token being exchanged
+      # @param subject_token_type [String] type of the subject token
+      # @param resource [String, nil] RFC 8707 target resource
+      # @param audience [String, nil] target audience (alternative to resource)
+      # @param scope [String, nil] space-separated scopes for the issued token
+      # @param requested_token_type [String, nil]
+      # @param actor_token [String, nil] the acting party's token, for explicit
+      #   delegation; requires actor_token_type
+      # @param actor_token_type [String, nil]
+      # @param client_assertion [String, nil] client-authentication assertion,
+      #   form-encoded in the body
+      # @param client_assertion_type [String, nil]
+      # @param issuer [String, nil] per-call zone selection: resolves the zone's
+      #   token endpoint and, for a multi-zone credential, that zone's client
+      #   authentication. Defaults to the client's issuer.
+      # @return [TokenResponse]
+      # @raise [OAuthError] an RFC 6749 §5.2 error response (invalid_grant,
+      #   invalid_target, invalid_scope, unauthorized_client, ...)
+      # @raise [HTTPError, ProtocolError, NetworkError]
+      def exchange_token(subject_token:, subject_token_type: nil, resource: nil,
+                         audience: nil, scope: nil, requested_token_type: nil, actor_token: nil,
+                         actor_token_type: nil, client_assertion: nil, client_assertion_type: nil,
+                         issuer: nil)
+        raise ArgumentError, "actor_token_type is required when actor_token is set" if actor_token && !actor_token_type
+
+        target = issuer || @issuer
+        overrides = {
+          "subject_token_type" => subject_token_type,
+          "resource" => resource,
+          "audience" => audience,
+          "scope" => scope,
+          "requested_token_type" => requested_token_type,
+          "actor_token" => actor_token,
+          "actor_token_type" => actor_token_type,
+          "client_assertion" => client_assertion,
+          "client_assertion_type" => client_assertion_type
+        }.compact
+        post_token_request(base_exchange_params(subject_token, target).merge(overrides), issuer: target)
+      end
+
+      # Impersonate a named user: a substitute-user token exchange for
+      # privileged operations performed on the user's behalf. No actor token
+      # is sent; the authorization server derives the acting party from client
+      # authentication and records it in the issued token's act chain.
+      #
+      # @param user_identifier [String] the target user (becomes sub)
+      # @param resource [String] target resource for the issued token
+      # @param scope [String, nil] space-separated scopes
+      # @param issuer [String, nil] per-call zone selection
+      # @return [TokenResponse]
+      # @raise [OAuthError] invalid_grant (unknown user), unauthorized_client
+      #   (impersonation not permitted), and all token-exchange errors
+      def impersonate(user_identifier:, resource:, scope: nil, issuer: nil)
+        raise ArgumentError, "resource must be a non-empty string" if resource.nil? || resource.empty?
+
+        exchange_token(
+          subject_token: OAuth.build_substitute_user_token(user_identifier),
+          subject_token_type: TokenType::SUBSTITUTE_USER,
+          resource: resource,
+          scope: scope,
+          issuer: issuer
+        )
+      end
+
+      private
+
+      # The base exchange parameters: built by the credential when one is
+      # configured (it supplies assertion fields and defaults), otherwise the
+      # bare RFC 8693 defaults. Caller-supplied fields are merged on top.
+      def base_exchange_params(subject_token, issuer)
+        if @credential
+          @credential.prepare_token_exchange_request(subject_token: subject_token,
+                                                     token_endpoint: token_endpoint(issuer), issuer: issuer)
+        else
+          {
+            "grant_type" => GrantType::TOKEN_EXCHANGE,
+            "subject_token" => subject_token,
+            "subject_token_type" => TokenType::ACCESS_TOKEN
+          }
+        end
+      end
+    end
+  end
+end