keycardai-oauth 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1149d6a6597b774774ced7f36e51ee6a2df28a1bfb94ad084ef2802db9827d8
-  data.tar.gz: e32a325dc4240903863b427be6ff808dc484954bbaff4128f4a49393fa2bc508
+  metadata.gz: fda3b3f30a1e8ccdf5d8c1dad0a9bc3ef99145990b1952c3382be766bffdd753
+  data.tar.gz: e4bb93fb097bc3dfd4cf894926860c241413c21b8e1cc05aff6432a632062e68
 SHA512:
-  metadata.gz: 4af98a839e2e21cff0948d5cb2b8cfa289252152699c9ca7a9bd409abf35defb935cc61cc836ba3fd7b5b30e3cfedafd1128232e4d8f6929b4608cc14282471f
-  data.tar.gz: 44ca0ff23a101c3c4e9f3a4527da545e2faa77af2a49354249602df6d0f7d936b14b3b1b9f9d104c6796b272f1ae85d3507fc43e57a28d41baecaf2bbadbe1d2
+  metadata.gz: 1a48955a16091ebec04bc7bef9b7effa8e1036a8dd273a9c351724bd86c729cf60f305c2d396dad3bbd50ff8b34af34bf6d8db7db6ccbd9c4d1e4fd91f058b1e
+  data.tar.gz: 8ed634c0e436e8a6ea9603bce24a7e861a56ac22df7caff2971e089ed641fc698d998c8b5750a2d1c746162c1437243fa0c8524bd31e617096ae00be9a5710f4

data/CHANGELOG.md

@@ -15,6 +15,41 @@ 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.3.0-keycardai-oauth (2026-09-01)
+
+
+- feat(keycardai-oauth): UserInfo, typed OIDC discovery fields, multi-resource authorize (#29)
+- * feat(keycardai-oauth): UserInfo, typed OIDC discovery fields, multi-resource authorize
+- Three capabilities from the specs of record, at their current spec versions:
+authorization-server-discovery v2, userinfo, authorization-code-pkce v3.
+- Changed signatures, all in Keycardai::OAuth:
+-   build_authorize_url(..., resource: nil)  ->  build_authorize_url(..., resources: [])
+  exchange_authorization_code(..., resource: nil)  ->  resource removed outright
+  authenticate(..., resource: nil)  ->  authenticate(..., resources: [])
+  AuthorizationServerMetadata gains userinfo_endpoint and end_session_endpoint
+- The single-resource arguments are removed, not deprecated, per spec-version 3.
+Each entry of resources becomes its own RFC 8707 resource parameter on the
+authorize URL; the authorization server binds them into the code at authorize
+time, so the code exchange sends no resource at all.
+- fetch_userinfo GETs the discovered userinfo_endpoint with a Bearer credential
+and Accept: application/json, fails with a configuration error before any
+request when metadata advertises no endpoint, rejects application/jwt bodies,
+requires a non-empty sub, and parses the RFC 6750 WWW-Authenticate challenge on
+a 401 into a typed OAuthError, defaulting to invalid_token when the challenge
+carries no error.
+- No version or changelog edits: the version pipeline is dormant until ECO-291
+and per-gem breaking-change scoping is unaudited, so this carries no
+breaking-change marker despite the changed signatures.
+- Co-Authored-By: Larry Osakwe <larry@keycard.ai>
+- * test(keycardai-oauth): pin the no-resources case, report the web-app gap
+- Row 3 now asserts a resource-less authorize URL carries no resource
+parameter, and the conformance report summary names the unshipped
+web-app begin/complete rows the way it names the as-itself gap.
+- ---------
+- Co-authored-by: devin-ai-keycard <devin-ai@keycard.ai>
+Co-authored-by: Larry Osakwe <larry@keycard.ai>
+Co-authored-by: Larry-Osakwe <larryosak@gmail.com>
+
 ## 0.2.0-keycardai-oauth (2026-08-19)
 
 

data/README.md

@@ -4,7 +4,6 @@ OAuth 2.0 primitives for the Keycard platform. The foundation gem of the
 [Keycard Ruby SDK](https://github.com/keycardai/ruby-sdk); `keycardai-mcp` and
 `keycardai-a2a` build on it.
 
-> **Preview.** APIs may change between minor versions while the surface settles.
 > Conformance against the cross-SDK contract is tracked in the
 > [conformance report](https://github.com/keycardai/ruby-sdk/blob/main/docs/conformance-report.md).
 
@@ -18,7 +17,8 @@ Capabilities (per [keycard-sdk-spec](https://github.com/keycardai/keycard-sdk-sp
 - Client credentials grant (RFC 6749 §4.4)
 - Authorization code + PKCE, including the challenge-driven loopback flow (RFC 8252)
 - Dynamic client registration (RFC 7591)
-- Authorization server discovery (RFC 8414)
+- Authorization server discovery (RFC 8414), including the OIDC Discovery 1.0 §3 endpoints
+- UserInfo: the signed-in user's identity claims (OIDC Core 1.0 §5.3)
 - JWT signing and verification, JWKS keyring with caching
 - Application credentials: ClientSecret (incl. multi-zone), WebIdentity (RFC 7523),
   WorkloadIdentity with pluggable identity token sources
@@ -86,6 +86,24 @@ context.failed_resources
 One resource failing never takes down the others; the failure lands on the
 context rather than raising, and `access` is where you choose to raise.
 
+### Read the signed-in user's claims
+
+```ruby
+user = Keycardai::OAuth.fetch_userinfo(
+  "https://your-zone.keycard.cloud",
+  access_token: user_access_token,
+)
+
+user.sub
+user["email"]
+user["groups"]
+```
+
+Zone access tokens are authorization-only, so identity claims live behind the
+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.
+
 ### Act as a named user
 
 ```ruby

data/lib/keycardai/oauth/authenticate.rb

@@ -20,7 +20,8 @@ module Keycardai
     # @param issuer [String] the zone's issuer URL
     # @param client_id [String]
     # @param scope [String, nil] space-separated scopes
-    # @param resource [String, nil] RFC 8707 resource indicator
+    # @param resources [Array<String>] RFC 8707 resource indicators requested
+    #   at authorize time, one resource parameter per entry
     # @param port [Integer] loopback port; 0 binds an ephemeral port
     # @param callback_timeout [Numeric] seconds to wait for the redirect
     # @param client_secret [String, nil] confidential clients only
@@ -33,7 +34,7 @@ module Keycardai
     # @raise [InteractionTimeoutError] the user did not complete the redirect
     # @raise [OAuthError] the authorization server denied the request
     # @raise [ProtocolError] the redirect's state did not match (code state_mismatch)
-    def self.authenticate(issuer:, client_id:, scope: nil, resource: nil, port: DEFAULT_CALLBACK_PORT,
+    def self.authenticate(issuer:, client_id:, scope: nil, resources: [], port: DEFAULT_CALLBACK_PORT,
                           callback_timeout: DEFAULT_CALLBACK_TIMEOUT, client_secret: nil,
                           verifier_length: PKCE::DEFAULT_VERIFIER_LENGTH,
                           http_client: HTTP::NetHTTPClient.new, browser_opener: nil, timeout: nil)
@@ -43,13 +44,13 @@ module Keycardai
 
       Loopback::CallbackServer.open(port: port) do |server|
         open_authorize_page(server, authorization_endpoint, pair, state,
-                            client_id: client_id, scope: scope, resource: resource,
+                            client_id: client_id, scope: scope, resources: resources,
                             browser_opener: browser_opener)
         code = server.wait_for_code(state: state, timeout: callback_timeout)
         exchange_authorization_code(
           issuer,
           code: code, code_verifier: pair.code_verifier, redirect_uri: server.redirect_uri,
-          client_id: client_id, client_secret: client_secret, resource: resource,
+          client_id: client_id, client_secret: client_secret,
           http_client: http_client, timeout: timeout
         )
       end
@@ -62,11 +63,11 @@ module Keycardai
     end
     private_class_method :authorization_endpoint_for
 
-    def self.open_authorize_page(server, endpoint, pair, state, client_id:, scope:, resource:, browser_opener:)
+    def self.open_authorize_page(server, endpoint, pair, state, client_id:, scope:, resources:, browser_opener:)
       url = build_authorize_url(
         endpoint,
         client_id: client_id, redirect_uri: server.redirect_uri, code_challenge: pair.code_challenge,
-        code_challenge_method: pair.code_challenge_method, scope: scope, state: state, resource: resource
+        code_challenge_method: pair.code_challenge_method, scope: scope, state: state, resources: resources
       )
       (browser_opener || Loopback.method(:open_browser)).call(url)
     end

data/lib/keycardai/oauth/authorization_code.rb

@@ -15,10 +15,12 @@ module Keycardai
     # @param code_challenge_method [String] the method the challenge was derived with
     # @param scope [String, nil] space-separated scopes
     # @param state [String, nil] CSRF state value
-    # @param resource [String, nil] RFC 8707 resource indicator
+    # @param resources [Array<String>] RFC 8707 resource indicators; each entry
+    #   becomes its own resource parameter, and the authorization server binds
+    #   them into the authorization code at authorize time
     # @return [String] the authorize URL
     def self.build_authorize_url(authorization_endpoint, client_id:, redirect_uri:, code_challenge:,
-                                 code_challenge_method: "S256", scope: nil, state: nil, resource: nil)
+                                 code_challenge_method: "S256", scope: nil, state: nil, resources: [])
       params = {
         "response_type" => "code",
         "client_id" => client_id,
@@ -26,12 +28,11 @@ module Keycardai
         "code_challenge" => code_challenge,
         "code_challenge_method" => code_challenge_method,
         "scope" => scope,
-        "state" => state,
-        "resource" => resource
+        "state" => state
       }.compact
 
       uri = URI(authorization_endpoint)
-      query = URI.encode_www_form(params)
+      query = URI.encode_www_form(params.to_a + Array(resources).map { |resource| ["resource", resource] })
       uri.query = uri.query.nil? || uri.query.empty? ? query : "#{uri.query}&#{query}"
       uri.to_s
     end
@@ -46,14 +47,13 @@ module Keycardai
     # @param redirect_uri [String] must match the authorization request
     # @param client_id [String, nil] public-client identifier
     # @param client_secret [String, nil] confidential-client secret; requires client_id
-    # @param resource [String, nil] RFC 8707 resource indicator
     # @param http_client [#get, #post_form] pluggable transport
     # @param timeout [Numeric, nil]
     # @return [TokenResponse]
     # @raise [OAuthError] an RFC 6749 §5.2 error response (invalid_grant, ...)
     # @raise [HTTPError, ProtocolError, NetworkError, ConfigurationError]
     def self.exchange_authorization_code(issuer, code:, code_verifier:, redirect_uri:, client_id: nil,
-                                         client_secret: nil, resource: nil,
+                                         client_secret: nil,
                                          http_client: HTTP::NetHTTPClient.new, timeout: nil)
       raise ConfigurationError, "client_secret requires client_id" if client_secret && client_id.nil?
 
@@ -68,8 +68,7 @@ module Keycardai
         "code" => code,
         "code_verifier" => code_verifier,
         "redirect_uri" => redirect_uri,
-        "client_id" => client_secret ? nil : client_id,
-        "resource" => resource
+        "client_id" => client_secret ? nil : client_id
       }.compact
       headers = { "Accept" => "application/json" }
       headers["Authorization"] = HTTP.basic_authorization(client_id, client_secret) if client_secret

data/lib/keycardai/oauth/discovery.rb

@@ -7,11 +7,15 @@ module Keycardai
   # Authorization-server discovery (RFC 8414): the operation, its metadata
   # type, and the URL/parsing internals shared with JWKSKeyring.
   module OAuth
-    # OAuth 2.0 authorization-server metadata (RFC 8414). Standard fields are
-    # first-class members; the complete document, including unknown fields, is
-    # preserved in +raw+ and reachable through +[]+.
+    # OAuth 2.0 authorization-server metadata (RFC 8414), including the OpenID
+    # Connect Discovery 1.0 §3 members Keycard zones serve from the same
+    # document. Standard fields are first-class members; the complete
+    # document, including unknown fields, is preserved in +raw+ and reachable
+    # through +[]+. Every field but +issuer+ is optional and nil when the
+    # document omits it.
     AuthorizationServerMetadata = Data.define(
       :issuer, :token_endpoint, :authorization_endpoint, :jwks_uri, :registration_endpoint,
+      :userinfo_endpoint, :end_session_endpoint,
       :grant_types_supported, :token_endpoint_auth_methods_supported, :response_types_supported, :raw
     ) do
       # @param field [String] a metadata field name
@@ -68,17 +72,8 @@ module Keycardai
         document = parse_document(issuer, body)
         validate_issuer(issuer, document)
 
-        AuthorizationServerMetadata.new(
-          issuer: document["issuer"],
-          token_endpoint: document["token_endpoint"],
-          authorization_endpoint: document["authorization_endpoint"],
-          jwks_uri: document["jwks_uri"],
-          registration_endpoint: document["registration_endpoint"],
-          grant_types_supported: document["grant_types_supported"],
-          token_endpoint_auth_methods_supported: document["token_endpoint_auth_methods_supported"],
-          response_types_supported: document["response_types_supported"],
-          raw: document
-        )
+        fields = (AuthorizationServerMetadata.members - [:raw]).to_h { |name| [name, document[name.to_s]] }
+        AuthorizationServerMetadata.new(**fields, raw: document)
       end
 
       def parse_document(issuer, body)

data/lib/keycardai/oauth/userinfo.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Keycardai
+  # The OpenID Connect UserInfo call (OIDC Core 1.0 §5.3): the operation, its
+  # response type, and the response-parsing internals.
+  module OAuth
+    # The signed-in user's identity claims (OIDC Core 1.0 §5.3). +sub+ is the
+    # only claim OIDC requires and is validated present; the claims document is
+    # returned exactly as the issuer sent it, nothing filtered to a known set,
+    # and reachable through +[]+.
+    UserInfoResponse = Data.define(:sub, :claims) do
+      # @param claim [String] a claim name
+      # @return [Object, nil] the claim's value from the full document
+      def [](claim)
+        claims[claim]
+      end
+    end
+
+    # Fetch the signed-in user's identity claims from the issuer's UserInfo
+    # endpoint (OIDC Core 1.0 §5.3).
+    #
+    # Keycard zone access tokens are authorization-only, so claims such as
+    # +email+ or +groups+ live behind the issuer's +userinfo_endpoint+ rather
+    # than in the token. The endpoint comes from discovery unless +metadata+ is
+    # supplied, in which case the caller owns caching and refreshing it.
+    #
+    # The access token is presented as a Bearer credential and the request
+    # carries no client authentication: UserInfo authenticates the user, not
+    # the client. Signed (+application/jwt+) responses are not supported.
+    # Nothing is cached; claims can change server-side, so caching per token is
+    # the caller's concern.
+    #
+    # @param issuer [String] the zone's issuer URL
+    # @param access_token [String] the user's access token
+    # @param metadata [AuthorizationServerMetadata, nil] pre-discovered
+    #   metadata; when given, no discovery request is made
+    # @param http_client [#get] pluggable transport
+    # @param timeout [Numeric, nil]
+    # @return [UserInfoResponse]
+    # @raise [ConfigurationError] the metadata advertises no userinfo_endpoint,
+    #   raised before any request
+    # @raise [OAuthError] the endpoint rejected the token (HTTP 401), carrying
+    #   the error code from the WWW-Authenticate challenge
+    # @raise [HTTPError] any other non-2xx response
+    # @raise [ProtocolError] a signed or non-JSON body, or claims without sub
+    # @raise [NetworkError] transport failure
+    def self.fetch_userinfo(issuer, access_token:, metadata: nil,
+                            http_client: HTTP::NetHTTPClient.new, timeout: nil)
+      metadata ||= fetch_authorization_server_metadata(issuer, http_client: http_client, timeout: timeout)
+      endpoint = metadata.userinfo_endpoint
+      if endpoint.nil? || endpoint.empty?
+        raise ConfigurationError,
+              "authorization server #{metadata.issuer} advertises no userinfo_endpoint"
+      end
+
+      headers = { "Accept" => "application/json", "Authorization" => "Bearer #{access_token}" }
+      UserInfo.parse_response(http_client.get(endpoint, headers: headers, timeout: timeout))
+    end
+
+    # Internals of the UserInfo call. Not public API.
+    module UserInfo
+      module_function
+
+      # @param response [HTTP::Response]
+      # @return [UserInfoResponse]
+      def parse_response(response)
+        raise error_for(response) unless response.success?
+
+        content_type = header(response, "content-type").to_s
+        if content_type.downcase.include?("application/jwt")
+          raise ProtocolError.new("userinfo response content type #{content_type} is not supported",
+                                  code: "invalid_response")
+        end
+
+        claims = parse_claims(response.body)
+        sub = claims["sub"]
+        unless sub.is_a?(String) && !sub.empty?
+          raise ProtocolError.new("userinfo response has no sub claim", code: "invalid_response")
+        end
+
+        UserInfoResponse.new(sub: sub, claims: claims)
+      end
+
+      def parse_claims(body)
+        claims = JSON.parse(body)
+        unless claims.is_a?(Hash)
+          raise ProtocolError.new("userinfo response is not a JSON object", code: "invalid_response")
+        end
+
+        claims
+      rescue JSON::ParserError
+        raise ProtocolError.new("userinfo response is not valid JSON", code: "invalid_response")
+      end
+
+      # RFC 6750 §3: a 401 carries the reason in the WWW-Authenticate
+      # challenge. Anything else non-2xx is a plain HTTP error.
+      #
+      # @param response [HTTP::Response]
+      # @return [OAuthError, HTTPError]
+      def error_for(response)
+        return http_error(response) unless response.status == 401
+
+        error = challenge_error(header(response, "www-authenticate"))
+        OAuthError.new("userinfo request was rejected with #{error}",
+                       error: error, status: response.status, body: response.body)
+      end
+
+      def http_error(response)
+        HTTPError.new("userinfo endpoint returned HTTP #{response.status}",
+                      status: response.status, body: response.body)
+      end
+
+      # The challenge's error code, defaulting to invalid_token when the
+      # challenge is absent or carries no error parameter.
+      def challenge_error(www_authenticate)
+        www_authenticate.to_s[/error\s*=\s*"?([^",\s]+)"?/, 1] || "invalid_token"
+      end
+
+      # Header names are case-insensitive (RFC 9110 §5.1) and Net::HTTP hands
+      # back array values.
+      def header(response, name)
+        _, value = response.headers.find { |key, _| key.to_s.downcase == name }
+        value.is_a?(Array) ? value.first : value
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/version.rb

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

data/lib/keycardai/oauth.rb

@@ -4,6 +4,7 @@ require_relative "oauth/version"
 require_relative "oauth/errors"
 require_relative "oauth/http"
 require_relative "oauth/discovery"
+require_relative "oauth/userinfo"
 require_relative "oauth/token_types"
 require_relative "oauth/token_requests"
 require_relative "oauth/substitute_user"
@@ -29,8 +30,9 @@ require_relative "oauth/jwt_verifier"
 module Keycardai
   # OAuth 2.0 primitives for the Keycard platform: token exchange (RFC 8693),
   # client credentials, authorization code + PKCE, dynamic client registration
-  # (RFC 7591), authorization server discovery (RFC 8414), JWT/JWKS
-  # verification, application credentials, and AccessContext.
+  # (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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycardai-oauth
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Keycard
@@ -25,8 +25,8 @@ dependencies:
         version: '2.7'
 description: Token exchange (RFC 8693), client credentials, authorization code + PKCE,
   dynamic client registration (RFC 7591), authorization server discovery (RFC 8414),
-  JWT/JWKS verification, application credentials, and the AccessContext delegated-access
-  container.
+  UserInfo, JWT/JWKS verification, application credentials, and the AccessContext
+  delegated-access container.
 email:
 - support@keycard.ai
 executables: []
@@ -58,6 +58,7 @@ files:
 - lib/keycardai/oauth/token_sources.rb
 - lib/keycardai/oauth/token_types.rb
 - lib/keycardai/oauth/token_verifier.rb
+- lib/keycardai/oauth/userinfo.rb
 - lib/keycardai/oauth/version.rb
 - lib/keycardai/oauth/web_identity.rb
 - lib/keycardai/oauth/workload_identity.rb