keycardai-oauth 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fda3b3f30a1e8ccdf5d8c1dad0a9bc3ef99145990b1952c3382be766bffdd753
-  data.tar.gz: e4bb93fb097bc3dfd4cf894926860c241413c21b8e1cc05aff6432a632062e68
+  metadata.gz: 377cff115fcfdf240200ae12b5d76d9c395e7a88a7e68cada08eb2bbe2dedaa2
+  data.tar.gz: 2d225d8679d1d4a901419aece54de5aceed70ef6998bb6f58966fda86512450d
 SHA512:
-  metadata.gz: 1a48955a16091ebec04bc7bef9b7effa8e1036a8dd273a9c351724bd86c729cf60f305c2d396dad3bbd50ff8b34af34bf6d8db7db6ccbd9c4d1e4fd91f058b1e
-  data.tar.gz: 8ed634c0e436e8a6ea9603bce24a7e861a56ac22df7caff2971e089ed641fc698d998c8b5750a2d1c746162c1437243fa0c8524bd31e617096ae00be9a5710f4
+  metadata.gz: cbdc7911049fbf06b769cf708b3be1f53c8a5dcfb6f2db3e9a920ad050b31526b245e0558d3a90d405a612713985c82ea4cd6f51cde7e23e0a64acc2591ed18d
+  data.tar.gz: 84047019c88c419316be53c29b79acee9558cdcf657b1297d2ee840426f5459dbc8759943f9737f8d6f3a86ed08f2be8d349925a99697ab1d9d720477ebc3a5a

data/CHANGELOG.md

@@ -15,6 +15,12 @@ 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.
 
+## 0.4.0-keycardai-oauth (2026-09-05)
+
+
+- feat(keycardai-oauth): expire the cached token endpoint after discovery_ttl
+- ECO-366 Ruby leg, audited against keycard-sdk-spec's metadata-failures-are-not-sticky contract. The sticky-failure defect does not exist in Ruby: token-endpoint discovery stored outcomes with ||= under a mutex, so a raise cached nothing and an interrupted caller left nothing behind. The one gap was the endpoint being cached for the client lifetime; it is now cached for discovery_ttl (3600s default, the JWKS keyring's knob and default) with a clock: keyword mirroring TokenVerifier. No negative cache and no retryable field: the spec makes deterministic-failure caching optional and Ruby never stored failures, and retryability classification is ECO-360's Ruby leg. Conformance tests cover the spec's discovery rows on both clients via one shared example group.
+
 ## 0.3.0-keycardai-oauth (2026-09-01)
 
 

data/lib/keycardai/oauth/client_credentials_client.rb

@@ -8,7 +8,8 @@ module Keycardai
     # client assertion carried on the request.
     #
     # The token endpoint is discovered from the issuer on first use and
-    # cached. Requests do not retry transparently.
+    # cached for discovery_ttl; a failed discovery is not cached. Requests do
+    # not retry transparently.
     class ClientCredentialsClient
       include TokenRequests
 
@@ -21,12 +22,16 @@ module Keycardai
       #   provide both or neither
       # @param http_client [#get, #post_form] pluggable transport
       # @param timeout [Numeric, nil] request timeout in seconds
+      # @param discovery_ttl [Numeric] token-endpoint cache lifetime in seconds
+      # @param clock [#call] returns the current Time; override in tests
       # @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)
+                     http_client: HTTP::NetHTTPClient.new, timeout: nil,
+                     discovery_ttl: TokenRequests::DEFAULT_DISCOVERY_TTL, clock: -> { Time.now })
         initialize_token_client(issuer: issuer, credential: credential, client_id: client_id,
-                                client_secret: client_secret, http_client: http_client, timeout: timeout)
+                                client_secret: client_secret, http_client: http_client, timeout: timeout,
+                                discovery_ttl: discovery_ttl, clock: clock)
       end
 
       # Request a token for the client itself.

data/lib/keycardai/oauth/token_exchange_client.rb

@@ -9,7 +9,8 @@ module Keycardai
     # authentication.
     #
     # The token endpoint is discovered from the issuer on first use and
-    # cached. Requests do not retry transparently.
+    # cached for discovery_ttl; a failed discovery is not cached. Requests do
+    # not retry transparently.
     class TokenExchangeClient
       include TokenRequests
 
@@ -21,12 +22,16 @@ module Keycardai
       #   provide both or neither
       # @param http_client [#get, #post_form] pluggable transport
       # @param timeout [Numeric, nil] request timeout in seconds
+      # @param discovery_ttl [Numeric] token-endpoint cache lifetime in seconds
+      # @param clock [#call] returns the current Time; override in tests
       # @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)
+                     http_client: HTTP::NetHTTPClient.new, timeout: nil,
+                     discovery_ttl: TokenRequests::DEFAULT_DISCOVERY_TTL, clock: -> { Time.now })
         initialize_token_client(issuer: issuer, credential: credential, client_id: client_id,
-                                client_secret: client_secret, http_client: http_client, timeout: timeout)
+                                client_secret: client_secret, http_client: http_client, timeout: timeout,
+                                discovery_ttl: discovery_ttl, clock: clock)
       end
 
       # Exchange a subject token (RFC 8693).

data/lib/keycardai/oauth/token_requests.rb

@@ -8,6 +8,10 @@ module Keycardai
     # endpoint discovery with caching, shared-secret (HTTP Basic) client
     # authentication, and RFC 6749 §5.2 error parsing. Not public API.
     module TokenRequests
+      # Default lifetime of a discovered token endpoint, in seconds; the same
+      # knob and default as the JWKS keyring's jwks_uri cache.
+      DEFAULT_DISCOVERY_TTL = 3600
+
       # Parse a token-endpoint response: a TokenResponse on 2xx, a raised
       # typed error otherwise.
       #
@@ -52,13 +56,16 @@ module Keycardai
 
       private
 
-      def initialize_token_client(issuer:, credential:, client_id:, client_secret:, http_client:, timeout:)
+      def initialize_token_client(issuer:, credential:, client_id:, client_secret:, http_client:, timeout:,
+                                  discovery_ttl: DEFAULT_DISCOVERY_TTL, clock: -> { Time.now })
         validate_client_auth(credential, client_id, client_secret)
 
         @issuer = issuer
         @credential = credential || (client_id ? ClientSecret.new(client_id, client_secret) : nil)
         @http_client = http_client
         @timeout = timeout
+        @discovery_ttl = discovery_ttl
+        @clock = clock
         @token_endpoints = {}
         @token_endpoint_mutex = Mutex.new
       end
@@ -72,19 +79,33 @@ module Keycardai
         raise ConfigurationError, "client_id and client_secret must be provided together"
       end
 
-      # Discover a zone's token endpoint once and cache it, keyed by issuer
-      # so multi-zone clients never reuse another zone's endpoint.
+      # Discover a zone's token endpoint and cache it for discovery_ttl, keyed
+      # by issuer so multi-zone clients never reuse another zone's endpoint.
+      # Only a success is recorded: a failed discovery raises to its caller and
+      # the next call discovers again. The mutex serializes cold-cache callers
+      # so concurrent first calls perform a single fetch; an interrupted caller
+      # releases it and leaves nothing behind for the others.
       def token_endpoint(issuer = @issuer)
         @token_endpoint_mutex.synchronize do
-          @token_endpoints[issuer] ||= begin
-            metadata = OAuth.fetch_authorization_server_metadata(issuer, http_client: @http_client,
-                                                                         timeout: @timeout)
-            metadata.token_endpoint ||
-              raise(ProtocolError.new("metadata for #{issuer} has no token_endpoint", code: "invalid_metadata"))
-          end
+          fresh_token_endpoint(issuer) || discover_token_endpoint(issuer)
         end
       end
 
+      def fresh_token_endpoint(issuer)
+        entry = @token_endpoints[issuer]
+        return nil unless entry
+
+        entry[:endpoint] if @clock.call - entry[:fetched_at] <= @discovery_ttl
+      end
+
+      def discover_token_endpoint(issuer)
+        metadata = OAuth.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"))
+        @token_endpoints[issuer] = { endpoint: endpoint, fetched_at: @clock.call }
+        endpoint
+      end
+
       def post_token_request(params, issuer: @issuer)
         headers = { "Accept" => "application/json" }
         authorization = @credential&.authorization_header(issuer: issuer)

data/lib/keycardai/oauth/version.rb

@@ -2,6 +2,6 @@
 
 module Keycardai
   module OAuth
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycardai-oauth
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Keycard