agent-harness 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5561c80c0a4ccab10925503a30bb20be2c24c929caa58b9d69a4aac2eb27aac
-  data.tar.gz: aae45d0a30105fed84eb442bdbeaaea0c0bc2fc995997bec49bccbed61db4249
+  metadata.gz: c88e49fef781a9b839029456b728f0f0bc99f0678a507084e044d9583d6a1220
+  data.tar.gz: 55d80c399dca1371e95346ac51aa2b83523a6c18a075f325d1eedf6f75e2839f
 SHA512:
-  metadata.gz: 00eb3ec6f37bbdda7bd430abf55eb09f4f6f79f86b565256c7b287cc2f0b9ef840f108b00a33ba84d457d689784772bb4d307191e08e0aae5941247739ceb651
-  data.tar.gz: 51efc497bd800e2d2ef31886ddeb65c502242dee45cfb40947d35f904f76e9ad215bf57520a779bd42a69e1b04759242c37c6b30a6b98b5a75707c759cd66e2a
+  metadata.gz: 4f2b742d3b20a8499cff4480e89e6d0f519626de0c752a8a837af33f2a3bacd65d1a4dfaff499846964c128c240176c1f70824d00e89cfc653bc1d1d4eb79ff5
+  data.tar.gz: 73d8251bc434bc664486759fa84f07e6b27eaa693bc16d98e48522b09b732c3053f3f5e3682aa25980d5cd7b622c247861a01d8ae2a4a50d40d3da9e589be9c8

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.26.0"
+  ".": "0.27.0"
 }

data/CHANGELOG.md

@@ -6,6 +6,13 @@
 * **auth:** add provider-owned PKCE code-exchange API for Claude OAuth (`AgentHarness::Authentication.exchange_code`). Takes an authorization code plus PKCE verifier (and `redirect_uri`/`client_id`), posts an `authorization_code` grant to the Claude token endpoint, and persists the resulting access/refresh tokens in the native `claudeAiOauth` shape. Adds `exchange_code_supported?` and a `code_exchange` key to `auth_capabilities` ([#266](https://github.com/viamin/agent-harness/issues/266)).
 
 
+## [0.27.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.26.0...agent-harness/v0.27.0) (2026-06-27)
+
+
+### Features
+
+* Authentication: Claude OAuth PKCE code-exchange API ([#267](https://github.com/viamin/agent-harness/issues/267)) ([7cabc73](https://github.com/viamin/agent-harness/commit/7cabc73f2a660e292533175e9db3a94d18326031))
+
 ## [0.26.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.25.0...agent-harness/v0.26.0) (2026-06-26)
 
 

data/lib/agent_harness/authentication.rb

@@ -51,9 +51,9 @@ module AgentHarness
         {
           auth_type: provider.auth_type,
           auth_url: flow_supported,
+          exchange_code: flow_supported,
           refresh: flow_supported,
-          exchange: flow_supported,
-          code_exchange: flow_supported
+          exchange: flow_supported
         }
       end
 
@@ -91,6 +91,45 @@ module AgentHarness
         end
       end
 
+      # Check whether PKCE code exchange is supported for a provider.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Boolean] true if exchange_code can be called for the provider
+      # @raise [ProviderNotFoundError] if provider is unknown
+      def exchange_code_supported?(provider_name)
+        auth_capabilities(provider_name)[:exchange_code]
+      end
+
+      # Exchange an OAuth authorization code for tokens using PKCE.
+      #
+      # Performs the code→token exchange with the provider's token endpoint
+      # and stores the resulting credentials in native shape.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @param code [String] the authorization code from the OAuth redirect
+      # @param code_verifier [String] the PKCE code verifier used when generating the auth URL
+      # @return [Hash] result with :success and :credentials keys
+      # @raise [UnsupportedAuthFlowError] if provider doesn't support code exchange
+      # @raise [ArgumentError] if code or code_verifier are blank
+      # @raise [AuthenticationError] if the token exchange request fails
+      def exchange_code(provider_name, code:, code_verifier:)
+        provider_name = provider_name.to_sym
+        provider = resolve_provider(provider_name)
+
+        unless provider.auth_type == :oauth
+          raise UnsupportedAuthFlowError,
+            "Provider #{provider_name} uses #{provider.auth_type} auth and does not support PKCE code exchange"
+        end
+
+        case provider_name
+        when :claude, :anthropic
+          exchange_claude_code(code: code, code_verifier: code_verifier)
+        else
+          raise UnsupportedAuthFlowError,
+            "PKCE code exchange is not yet implemented for provider #{provider_name}"
+        end
+      end
+
       # Check whether credential refresh is supported for a provider.
       #
       # @param provider_name [Symbol] the provider name
@@ -173,74 +212,8 @@ module AgentHarness
         end
       end
 
-      # Check whether PKCE authorization-code exchange is supported for a provider.
-      #
-      # @param provider_name [Symbol] the provider name
-      # @return [Boolean] true if exchange_code can be called
-      # @raise [ProviderNotFoundError] if provider is unknown
-      def exchange_code_supported?(provider_name)
-        auth_capabilities(provider_name)[:code_exchange]
-      end
-
-      # Exchange a PKCE authorization code for tokens and persist them in native shape.
-      #
-      # Posts the authorization code and PKCE verifier to the provider's OAuth
-      # token endpoint, then writes the resulting access/refresh tokens to the
-      # credentials store using the provider's native shape (e.g. +claudeAiOauth+
-      # for Claude).
-      #
-      # Serializes through a file lock so that concurrent callers do not race on
-      # credential writes.
-      #
-      # @param provider_name [Symbol] the provider name
-      # @param code [String] authorization code returned from the OAuth redirect (required)
-      # @param code_verifier [String] PKCE code verifier matching the code_challenge sent on the auth URL (required)
-      # @param redirect_uri [String] redirect URI registered with the authorization request (required)
-      # @param client_id [String] OAuth client identifier (required)
-      # @param state [String, nil] optional state parameter echoed from the authorization request
-      # @return [Hash] credential in claudeAiOauth shape for Claude:
-      #   +{ claudeAiOauth: { accessToken:, refreshToken:, expiresAt: } }+
-      # @raise [UnsupportedAuthFlowError] if provider doesn't support PKCE code exchange
-      # @raise [ArgumentError] if any required parameter is blank
-      # @raise [AuthenticationError] if the exchange fails
-      def exchange_code(provider_name, code:, code_verifier:, redirect_uri:, client_id:, state: nil)
-        provider_name = provider_name.to_sym
-        provider = resolve_provider(provider_name)
-
-        unless provider.auth_type == :oauth
-          raise UnsupportedAuthFlowError,
-            "Provider #{provider_name} uses #{provider.auth_type} auth and does not support code exchange"
-        end
-
-        validate_code_exchange_params!(code: code, code_verifier: code_verifier,
-          redirect_uri: redirect_uri, client_id: client_id)
-
-        case provider_name
-        when :claude, :anthropic
-          exchange_claude_code(
-            code: code.strip,
-            code_verifier: code_verifier.strip,
-            redirect_uri: redirect_uri.strip,
-            client_id: client_id.strip,
-            state: state
-          )
-        else
-          raise UnsupportedAuthFlowError,
-            "Code exchange is not yet implemented for provider #{provider_name}"
-        end
-      end
-
       private
 
-      def validate_code_exchange_params!(code:, code_verifier:, redirect_uri:, client_id:)
-        {code: code, code_verifier: code_verifier,
-         redirect_uri: redirect_uri, client_id: client_id}.each do |name, value|
-          unless non_blank?(value)
-            raise ArgumentError, "#{name} must be a non-empty string"
-          end
-        end
-      end
-
       def claude_oauth_flow_provider?(requested_name, canonical_name)
         [:claude, :anthropic].include?(requested_name) || canonical_name == :claude
       end
@@ -312,6 +285,126 @@ module AgentHarness
         "https://claude.ai/oauth/authorize"
       end
 
+      def claude_token_url
+        "https://claude.ai/oauth/token"
+      end
+
+      # Public OAuth client_id for the Claude Code CLI. This value is the
+      # well-known public client identifier used by the Claude Code CLI's
+      # PKCE login flow; callers building the auth_url must use the same
+      # client_id so the token exchange succeeds.
+      def claude_oauth_client_id
+        "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+      end
+
+      # Redirect URI registered for the Claude Code CLI OAuth client. Must
+      # match the redirect_uri used in the authorization request — per RFC
+      # 6749 §4.1.3 the token endpoint validates that they are identical.
+      def claude_oauth_redirect_uri
+        "https://console.anthropic.com/oauth/code/callback"
+      end
+
+      def exchange_claude_code(code:, code_verifier:)
+        raise ArgumentError, "code must be a non-empty string" unless code.is_a?(String) && !code.strip.empty?
+        raise ArgumentError, "code_verifier must be a non-empty string" unless code_verifier.is_a?(String) && !code_verifier.strip.empty?
+
+        uri = URI.parse(claude_token_url)
+        request = Net::HTTP::Post.new(uri)
+        request.content_type = "application/json"
+        # Include client_id and redirect_uri per RFC 6749 §4.1.3: the token
+        # endpoint requires client_id for public clients and redirect_uri
+        # when one was sent in the authorization request. Callers using
+        # claude_auth_url are expected to build the authorization request
+        # with these same values.
+        request.body = JSON.generate({
+          grant_type: "authorization_code",
+          client_id: claude_oauth_client_id,
+          redirect_uri: claude_oauth_redirect_uri,
+          code: code.strip,
+          code_verifier: code_verifier.strip
+        })
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          http.open_timeout = 10
+          http.read_timeout = 30
+          http.request(request)
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          error_body = begin
+            JSON.parse(response.body)
+          rescue JSON::ParserError
+            {"error" => response.body}
+          end
+          raise AuthenticationError.new(
+            "PKCE code exchange failed (HTTP #{response.code}): #{error_body["error"] || error_body["error_description"] || response.body}",
+            provider: :claude
+          )
+        end
+
+        token_data = JSON.parse(response.body)
+
+        unless token_data["access_token"].is_a?(String) && !token_data["access_token"].strip.empty?
+          raise AuthenticationError.new(
+            "PKCE code exchange returned no access_token",
+            provider: :claude
+          )
+        end
+
+        store_claude_token_response(token_data)
+      end
+
+      def store_claude_token_response(token_data)
+        credentials_path = claude_credentials_path
+        dir = File.dirname(credentials_path)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+
+        lock_path = "#{credentials_path}.lock"
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+
+          credentials = read_claude_credentials
+          credentials = {} unless credentials.is_a?(Hash)
+
+          if credentials.key?("claudeAiOauth")
+            # Preserve the native claudeAiOauth shape so extract_claude_token
+            # picks up the newly exchanged token instead of a stale nested value.
+            oauth = credentials["claudeAiOauth"]
+            oauth = {} unless oauth.is_a?(Hash)
+            oauth["accessToken"] = token_data["access_token"]
+            oauth["refreshToken"] = token_data["refresh_token"] if token_data["refresh_token"]
+            if token_data["expires_in"]
+              oauth["expiresAt"] = (Time.now + token_data["expires_in"].to_i).iso8601
+            else
+              oauth.delete("expiresAt")
+            end
+            credentials["claudeAiOauth"] = oauth
+          else
+            credentials["oauth_token"] = token_data["access_token"]
+            credentials["refreshToken"] = token_data["refresh_token"] if token_data["refresh_token"]
+            if token_data["expires_in"]
+              credentials["expiresAt"] = (Time.now + token_data["expires_in"].to_i).iso8601
+            else
+              credentials.delete("expiresAt")
+              credentials.delete("expires_at")
+            end
+          end
+
+          tmpfile = Tempfile.new(".credentials", dir)
+          begin
+            tmpfile.write(JSON.pretty_generate(credentials))
+            tmpfile.close
+            File.chmod(0o600, tmpfile.path)
+            File.rename(tmpfile.path, credentials_path)
+          rescue
+            tmpfile.close!
+            raise
+          end
+        end
+
+        {success: true, credentials: token_data}
+      end
+
       def provider_config_for(requested_name, canonical_name:)
         requested_key = requested_name.to_sym
         canonical_key = canonical_name.to_sym
@@ -423,103 +516,6 @@ module AgentHarness
         end
       end
 
-      def exchange_claude_code(code:, code_verifier:, redirect_uri:, client_id:, state:)
-        credentials_path = claude_credentials_path
-        lock_path = "#{credentials_path}.lock"
-
-        dir = File.dirname(credentials_path)
-        FileUtils.mkdir_p(dir, mode: 0o700)
-
-        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
-          lock.flock(File::LOCK_EX)
-
-          response_body = post_code_exchange(
-            code: code,
-            code_verifier: code_verifier,
-            redirect_uri: redirect_uri,
-            client_id: client_id,
-            state: state
-          )
-
-          access_token = response_body["access_token"]
-          new_refresh_token = response_body["refresh_token"]
-          expires_in = response_body["expires_in"]
-
-          unless non_blank?(access_token)
-            raise AuthenticationError.new(
-              "Code exchange response did not include an access_token",
-              provider: :claude
-            )
-          end
-
-          expires_at = expires_in ? (Time.now + expires_in).iso8601 : nil
-
-          oauth_block = {
-            "accessToken" => access_token,
-            "refreshToken" => new_refresh_token,
-            "expiresAt" => expires_at
-          }
-
-          credentials = read_claude_credentials
-          credentials = {} unless credentials.is_a?(Hash)
-          credentials["claudeAiOauth"] = oauth_block
-          credentials["oauth_token"] = access_token
-          credentials.delete("expires_at")
-          credentials["expiresAt"] = expires_at
-
-          tmpfile = Tempfile.new(".credentials", dir)
-          begin
-            tmpfile.write(JSON.pretty_generate(credentials))
-            tmpfile.close
-            File.chmod(0o600, tmpfile.path)
-            File.rename(tmpfile.path, credentials_path)
-          rescue
-            tmpfile.close!
-            raise
-          end
-
-          {claudeAiOauth: oauth_block.transform_keys(&:to_sym)}
-        end
-      end
-
-      def post_code_exchange(code:, code_verifier:, redirect_uri:, client_id:, state:)
-        payload = {
-          grant_type: "authorization_code",
-          code: code,
-          code_verifier: code_verifier,
-          redirect_uri: redirect_uri,
-          client_id: client_id
-        }
-        payload[:state] = state if non_blank?(state)
-
-        http = Net::HTTP.new(CLAUDE_TOKEN_ENDPOINT.host, CLAUDE_TOKEN_ENDPOINT.port)
-        http.use_ssl = true
-        http.open_timeout = 10
-        http.read_timeout = 10
-
-        request = Net::HTTP::Post.new(CLAUDE_TOKEN_ENDPOINT.path)
-        request["Content-Type"] = "application/json"
-        request.body = JSON.generate(payload)
-
-        response = http.request(request)
-
-        body = begin
-          JSON.parse(response.body)
-        rescue JSON::ParserError
-          {}
-        end
-
-        unless response.is_a?(Net::HTTPSuccess)
-          error_description = body["error_description"] || body["error"] || body["message"] || response.body
-          raise AuthenticationError.new(
-            "Code exchange failed (HTTP #{response.code}): #{error_description}",
-            provider: :claude
-          )
-        end
-
-        body
-      end
-
       def post_token_exchange(refresh_token)
         http = Net::HTTP.new(CLAUDE_TOKEN_ENDPOINT.host, CLAUDE_TOKEN_ENDPOINT.port)
         http.use_ssl = true

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.26.0"
+  VERSION = "0.27.0"
 end

data/lib/agent_harness.rb

@@ -322,6 +322,24 @@ module AgentHarness
       Authentication.auth_url(provider_name)
     end
 
+    # Check whether PKCE code exchange is supported for a provider
+    # @param provider_name [Symbol] the provider name
+    # @return [Boolean] true if exchange_code can be called for the provider
+    # @raise [ProviderNotFoundError] if provider is unknown
+    def exchange_code_supported?(provider_name)
+      Authentication.exchange_code_supported?(provider_name)
+    end
+
+    # Exchange an OAuth authorization code for tokens using PKCE
+    # @param provider_name [Symbol] the provider name
+    # @param code [String] the authorization code
+    # @param code_verifier [String] the PKCE code verifier
+    # @return [Hash] result with :success and :credentials keys
+    # @raise [UnsupportedAuthFlowError] if provider doesn't support code exchange
+    def exchange_code(provider_name, code:, code_verifier:)
+      Authentication.exchange_code(provider_name, code: code, code_verifier: code_verifier)
+    end
+
     # Check whether credential refresh is supported for a provider
     # @param provider_name [Symbol] the provider name
     # @return [Boolean] true if refresh_auth can be called for the provider

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Bart Agapinan