keycardai-oauth 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cd4432729ce7f9f1e54d2fe539c92cc86c69b6b8914abd78b407f9aa75cfe72
-  data.tar.gz: 65378c59aea04d972e50922379d5c45c01361cda5eb210421f00633093982388
+  metadata.gz: df6d3bc89be61e489dd76756c9c07f3239a7dd5d512f8569a85ab2ade99dbdca
+  data.tar.gz: c977ddd06c80a631b36e61c728a77bb097f7ce69d553c338bde680cd8d06abce
 SHA512:
-  metadata.gz: 964ed9c9d520da2470d0f31ca9427da6397752cf5d5265e7f9517367e67719e741d869f38a62042275f9af2049a2921b96d096a76171b7920c407c5be5e72189
-  data.tar.gz: b02efcd68eef6b896b7b1cfde8e29e0b537fcf86397bd33e1d3ac9d7322ddf8015319c5d544feec0766f4e1032eec5d6d679f4e11662797a5fb06dbe4c93946c
+  metadata.gz: '0112832ebca175689a4ef54071d1720178884a869af1835297a8ef777b069f83dced903f0626a9aa8be2a5e5efd466e65756260111894ea770299eaef68452fa'
+  data.tar.gz: e5b5c1a8d5d973570cb6049baa8109f4e0495a71f83ac38683d4741569f00a44cd01c3621d0c688e8da343d50febc601aa69bbfeab522ab9a97da776b95f1be0

data/CHANGELOG.md

@@ -15,6 +15,14 @@ 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.6.1-keycardai-oauth (2026-11-06)
+
+
+- fix(keycardai-oauth): throttle JWKS refetches for unknown key ids, and time out zone requests by default (#49)
+- JWKSKeyring keeps the last key set per jwks_uri for key_ttl, looks a kid up there before fetching, refetches for a missing kid at most once per refetch_cooldown (default 30 seconds, 0 fetches per miss), and drops the set in invalidate. NetHTTPClient gives a request with no timeout: 10 seconds instead of Net::HTTP's 60, so every request to the zone is bounded while callers can still pass timeout:. Follows typescript-sdk #309 and #310. SDK-93.
+- Co-authored-by: devin-ai-keycard <devin-ai@keycard.ai>
+Co-authored-by: Larry Osakwe <larry@keycard.ai>
+
 ## 0.6.0-keycardai-oauth (2026-10-09)
 
 

data/LICENSE

@@ -1,6 +1,6 @@
 MIT LICENSE
 
-Copyright © 2026 Keycard Labs, inc.
+Copyright (c) 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:
 

data/README.md

@@ -11,7 +11,7 @@ OAuth 2.0 primitives for the Keycard platform. The foundation gem of the
 bundle add keycardai-oauth
 ```
 
-Capabilities (per [keycard-sdk-spec](https://github.com/keycardai/keycard-sdk-spec)):
+Capabilities:
 
 - Token exchange and impersonation (RFC 8693)
 - Client credentials grant (RFC 6749 §4.4)

data/lib/keycardai/oauth/http.rb

@@ -41,9 +41,9 @@ module Keycardai
       # module-level function defaults, keeps its sessions until it is garbage
       # collected, which closes the underlying sockets.
       class NetHTTPClient
-        DEFAULT_OPEN_TIMEOUT = Net::HTTP.new("localhost").open_timeout
-        DEFAULT_READ_TIMEOUT = Net::HTTP.new("localhost").read_timeout
-        private_constant :DEFAULT_OPEN_TIMEOUT, :DEFAULT_READ_TIMEOUT
+        # Open and read timeout for a request whose caller passed no timeout:
+        # 10 seconds, so a request to the zone cannot wait for Net::HTTP's 60.
+        DEFAULT_TIMEOUT = 10
 
         def initialize
           @registry = {}
@@ -107,10 +107,10 @@ module Keycardai
 
         def perform(uri, request, timeout)
           http = session_for(uri)
-          # Timeouts are per request; a request without one gets Net::HTTP's
-          # defaults back rather than the previous request's values.
-          http.open_timeout = timeout || DEFAULT_OPEN_TIMEOUT
-          http.read_timeout = timeout || DEFAULT_READ_TIMEOUT
+          # Timeouts are per request; a request without one gets the default
+          # back rather than the previous request's values.
+          http.open_timeout = timeout || DEFAULT_TIMEOUT
+          http.read_timeout = timeout || DEFAULT_TIMEOUT
           http.start unless http.started?
           response = http.request(request)
           Response.new(status: response.code.to_i, headers: response.to_hash, body: response.body.to_s)

data/lib/keycardai/oauth/jwks_keyring.rb

@@ -21,23 +21,31 @@ module Keycardai
       DEFAULT_KEY_TTL = 300
       DEFAULT_DISCOVERY_TTL = 3600
       DEFAULT_FETCH_TIMEOUT = 10
+      # Shortest interval between two JWKS fetches for one jwks_uri caused by a
+      # kid the cached key set does not hold. The checks before the key lookup
+      # read the unsigned token, so a forged token can name any kid.
+      DEFAULT_REFETCH_COOLDOWN = 30
       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 refetch_cooldown [Numeric] seconds before a kid missing from the
+      #   cached key set triggers another fetch; 0 fetches on every miss
       # @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 })
+                     refetch_cooldown: DEFAULT_REFETCH_COOLDOWN, clock: -> { Time.now })
         @http_client = http_client
         @key_ttl = key_ttl
         @discovery_ttl = discovery_ttl
         @fetch_timeout = fetch_timeout
+        @refetch_cooldown = refetch_cooldown
         @clock = clock
         @keys = {}
         @discovery = {}
+        @key_sets = {} # jwks_uri => { keys:, fetched_at: }
         @issuer_locks = {}
         @mutex = Mutex.new
       end
@@ -69,10 +77,12 @@ module Keycardai
         @mutex.synchronize do
           if issuer
             @keys.delete_if { |(cached_issuer, _), _| cached_issuer == issuer }
-            @discovery.delete(issuer)
+            entry = @discovery.delete(issuer)
+            @key_sets.delete(entry[:jwks_uri]) if entry
           else
             @keys.clear
             @discovery.clear
+            @key_sets.clear
           end
         end
       end
@@ -93,14 +103,41 @@ module Keycardai
 
       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
+        jwk = key_from_set(issuer, kid, jwks_uri)
 
         key = import_key(jwk)
         cache_key(issuer, kid, key)
         key
       end
 
+      # The cached key set first: a kid it holds imports with no fetch, and a kid
+      # it lacks refetches at most once per cooldown, so a rotated-in key is found
+      # once the cooldown has passed.
+      def key_from_set(issuer, kid, jwks_uri)
+        cached = fresh_key_set(jwks_uri)
+        if cached
+          jwk = cached[:keys].find { |candidate| candidate["kid"] == kid }
+          return jwk if jwk
+
+          raise_not_found(issuer, kid) if now - cached[:fetched_at] < @refetch_cooldown
+        end
+
+        keys = fetch_jwks(jwks_uri)
+        @mutex.synchronize { @key_sets[jwks_uri] = { keys: keys, fetched_at: now } }
+        keys.find { |candidate| candidate["kid"] == kid } || raise_not_found(issuer, kid)
+      end
+
+      def fresh_key_set(jwks_uri)
+        @mutex.synchronize do
+          entry = @key_sets[jwks_uri]
+          entry if entry && now - entry[:fetched_at] <= @key_ttl
+        end
+      end
+
+      def raise_not_found(issuer, kid)
+        raise JWKSKeyNotFoundError, "kid #{kid.inspect} not found in JWKS for #{issuer}"
+      end
+
       def resolve_jwks_uri(issuer)
         cached = @mutex.synchronize do
           entry = @discovery[issuer]

data/lib/keycardai/oauth/version.rb

@@ -2,6 +2,6 @@
 
 module Keycardai
   module OAuth
-    VERSION = "0.6.0"
+    VERSION = "0.6.1"
   end
 end

data/lib/keycardai/oauth.rb

@@ -33,8 +33,6 @@ module Keycardai
   # (RFC 7591), authorization server discovery (RFC 8414), UserInfo (OIDC Core
   # 1.0 §5.3), JWT/JWKS verification, application credentials, and
   # AccessContext.
-  #
-  # Contract: https://github.com/keycardai/keycard-sdk-spec
   module OAuth
   end
 end

metadata

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