keycardai-oauth 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40a3e00e3c9bea5de74c7dfec6f5daccb2f90bc7cf778bb792ea737e7e34dead
-  data.tar.gz: 29be50e3ae28e46aeb2c20f2c93680e4aaf9206e4fa39a092360b5239f7ee1af
+  metadata.gz: df6d3bc89be61e489dd76756c9c07f3239a7dd5d512f8569a85ab2ade99dbdca
+  data.tar.gz: c977ddd06c80a631b36e61c728a77bb097f7ce69d553c338bde680cd8d06abce
 SHA512:
-  metadata.gz: 2b7b2d4fedab4c89db633147d98151dcfb36e2bd84da817025c9ae10be11c39291bebae71d7549063c52371738a8c417c1ba87a1622964dabcac03ff4f36e386
-  data.tar.gz: bc08654b809ca7863b9a60de9518b65255d303d115819d85620daca16d5bb5f5a5e2ae3ec35b0b34f1173d526413a10faf1bd5b0681fa9d62395895037b2dc1e
+  metadata.gz: '0112832ebca175689a4ef54071d1720178884a869af1835297a8ef777b069f83dced903f0626a9aa8be2a5e5efd466e65756260111894ea770299eaef68452fa'
+  data.tar.gz: e5b5c1a8d5d973570cb6049baa8109f4e0495a71f83ac38683d4741569f00a44cd01c3621d0c688e8da343d50febc601aa69bbfeab522ab9a97da776b95f1be0

data/CHANGELOG.md

@@ -15,6 +15,20 @@ 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)
+
+
+- feat(keycardai-oauth): refresh a grant from the authorization-code flow (SDK-15) (#42)
+- Adds Keycardai::OAuth.refresh_authorization(issuer, refresh_token:, client_id:, client_secret:, resources:, scopes:), the refresh step from authorization-code-pkce.md spec-version 4. Client authentication follows exchange_authorization_code: HTTP Basic with no body client_id for a confidential client, body client_id for a public one. A rotated refresh_token comes back on the TokenResponse for the caller to store; invalid_grant raises OAuthError and means the user must authorize again.
+
 ## 0.5.1-keycardai-oauth (2026-09-17)
 
 

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)
@@ -104,6 +104,26 @@ issuer's `userinfo_endpoint` rather than in the token. Pass `metadata:` to reuse
 metadata you already discovered; nothing is cached, because group membership can
 change server-side.
 
+### Refresh a stored grant
+
+A token response from the authorization-code flow may carry a `refresh_token`.
+Redeem it with `refresh_authorization`, which authenticates the client the way
+`exchange_authorization_code` does. The gem keeps no state: when the response
+carries a new `refresh_token`, the server rotated it and you store it in place
+of the old one. `OAuthError` with `error == "invalid_grant"` means the user must
+authorize again.
+
+```ruby
+token = Keycardai::OAuth.refresh_authorization(
+  "https://your-zone.keycard.cloud",
+  refresh_token: stored_refresh_token,
+  client_id: ENV.fetch("KEYCARD_CLIENT_ID"),
+  client_secret: ENV["KEYCARD_CLIENT_SECRET"], # omit for a public client
+  resources: ["https://api.acme.test"],
+)
+stored_refresh_token = token.refresh_token if token.refresh_token
+```
+
 ### Act as a named user
 
 ```ruby

data/lib/keycardai/oauth/authorization_code.rb

@@ -75,5 +75,46 @@ module Keycardai
 
       TokenRequests.parse_response(http_client.post_form(endpoint, params, headers: headers, timeout: timeout))
     end
+
+    # Redeem a refresh token for a new access token (RFC 6749 §6). Client
+    # authentication follows the code exchange: a confidential client
+    # authenticates with HTTP Basic and omits client_id from the body, a public
+    # client carries client_id in the body. The gem keeps no state: when the
+    # response carries a refresh_token the server rotated it, and the caller
+    # stores it in place of the old one.
+    #
+    # @param issuer [String] the zone's issuer URL; supplies the token endpoint
+    # @param refresh_token [String] the refresh token from an earlier token response
+    # @param client_id [String]
+    # @param client_secret [String, nil] confidential-client secret
+    # @param resources [Array<String>] RFC 8707 resource indicators, one resource
+    #   parameter per entry
+    # @param scopes [Array<String>] scopes to request, space-joined into scope
+    # @param http_client [#get, #post_form] pluggable transport
+    # @param timeout [Numeric, nil]
+    # @return [TokenResponse]
+    # @raise [OAuthError] an RFC 6749 §5.2 error response; error == "invalid_grant"
+    #   means the refresh token is expired, revoked, or unknown and the user must
+    #   authorize again
+    # @raise [HTTPError] a non-2xx response with no OAuth error body (5xx, 429)
+    # @raise [NetworkError, ProtocolError]
+    def self.refresh_authorization(issuer, refresh_token:, client_id:, client_secret: nil, resources: [],
+                                   scopes: [], http_client: HTTP::NetHTTPClient.new, timeout: 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"))
+
+      params = {
+        "grant_type" => GrantType::REFRESH_TOKEN,
+        "refresh_token" => refresh_token,
+        "client_id" => client_secret ? nil : client_id,
+        "scope" => Array(scopes).empty? ? nil : Array(scopes).join(" ")
+      }.compact
+      params = params.to_a + Array(resources).map { |resource| ["resource", resource] }
+      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/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/token_types.rb

@@ -15,6 +15,7 @@ module Keycardai
     module GrantType
       CLIENT_CREDENTIALS = "client_credentials"
       AUTHORIZATION_CODE = "authorization_code"
+      REFRESH_TOKEN = "refresh_token"
       TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange"
     end
 

data/lib/keycardai/oauth/version.rb

@@ -2,6 +2,6 @@
 
 module Keycardai
   module OAuth
-    VERSION = "0.5.1"
+    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.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Keycard