keycardai-oauth 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33aa8b51bc6809128ee7546762842456ad9e204d0e60655217e879cb498a0b63
-  data.tar.gz: ee37eb4012f1bf46e01058476c6ce4abd4ba23be66c83841fb5114241ec365c4
+  metadata.gz: fda3b3f30a1e8ccdf5d8c1dad0a9bc3ef99145990b1952c3382be766bffdd753
+  data.tar.gz: e4bb93fb097bc3dfd4cf894926860c241413c21b8e1cc05aff6432a632062e68
 SHA512:
-  metadata.gz: 6f150494708f23dddb34ecdcb7bdaaac837cd9d13f6ca1e0730df19536cec26db3d497474b8484cfad13f4d640dbb1831295c5172f6203a4e8c67b6e0683adc5
-  data.tar.gz: 9edbb0dda964b5f65eb88fae046bcb68b29e0b11f447633c27d0af9178b78ed377af2d7c42a2dcfb2fb75fbcffcda0e5c194e984a6ed8fc332ec5ecdc6e021ac
+  metadata.gz: 1a48955a16091ebec04bc7bef9b7effa8e1036a8dd273a9c351724bd86c729cf60f305c2d396dad3bbd50ff8b34af34bf6d8db7db6ccbd9c4d1e4fd91f058b1e
+  data.tar.gz: 8ed634c0e436e8a6ea9603bce24a7e861a56ac22df7caff2971e089ed641fc698d998c8b5750a2d1c746162c1437243fa0c8524bd31e617096ae00be9a5710f4

data/CHANGELOG.md

@@ -14,3 +14,179 @@ dynamic client registration (RFC 7591), authorization code with PKCE including
 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)
+
+
+- feat(keycardai-oauth): expose the caller identity claims on the auth context (#24)
+- Implements keycard-sdk-spec#44, which pins the auth-context identity
+field set so the SDKs converge instead of each guessing.
+- AccessToken gains subject_profile (the sub_profile claim) and
+keycard_app_id, alongside the existing subject and client_id. The four
+answer different questions and picking the wrong one is a bug, so the
+class doc says which to key on: keycard_app_id is the stable
+application identifier, client_id names the credential and rotates,
+subject is the user on a user-present token and the application on an
+application token, and subject_profile distinguishes those two directly
+rather than leaving a consumer to infer it.
+- Both Keycard claims are absent from a non-Keycard token, so they return
+nil rather than raising, which the spec calls out as optional.
+- Named subject_profile rather than sub_profile for consistency with the
+existing subject accessor, which already reads sub. The spec treats
+casing and naming as expression, and Go reads sub as Subject.
+- Conformance row 4 in the bearer-middleware table now asserts the
+identity fields, plus an application-token case where subject equals
+keycard_app_id and a non-Keycard case where both are nil.
+
+## 0.1.0-keycardai-oauth (2026-08-19)
+
+
+- feat(keycardai-oauth): authenticate loopback flow and challenge-driven entry (#7)
+- Completes specs/oauth-client/authorization-code-pkce.md with the
+high-level convenience layer:
+- - authenticate: PKCE pair + CSRF state, authorize URL, shell-free
+  browser launch (open / xdg-open / cmd start), single-shot loopback
+  callback server (RFC 8252, converged defaults: port 8765, 300s
+  timeout, verifier length 128; port 0 binds ephemeral), state
+  validation (state_mismatch), redirect-carried OAuth errors typed,
+  InteractionTimeoutError on user inaction, then the code exchange
+- resolve_issuer_from_challenge: RFC 9728 WWW-Authenticate
+  resource_metadata fetch to the first authorization server
+- authenticate_from_challenge: challenge-driven entry to the same flow
+- Tested against a real loopback server with a fake browser driving the
+redirect (round trip, forged state, denied authorization, timeout).
+- feat(keycardai-oauth): AccessContext, exchange orchestration, TokenVerifier, multi-zone (#6)
+- Implements specs/delegated-access/access-context.md and
+specs/multi-zone-and-ops/multi-zone-support.md, completing the oauth
+core surface:
+- - AccessContext: throwing access(resource) with typed
+  ResourceAccessError (global_error / resource_error / missing_token,
+  available_resources carried), non-throwing getters, status, mutators
+  for the grant layer, thread-safe, merge
+- exchange_tokens_for_resources: non-throwing orchestration feeding an
+  AccessContext; per-resource scopes; impersonation path when
+  user_identifier is given
+- TokenVerifier (server tier): JWTVerifier over a shared JWKSKeyring
+  returning AccessToken; verify_token_for_zone pins one zone issuer and
+  fails closed on unconfigured zones; caches keyed by issuer so no
+  cross-zone leakage
+- TokenExchangeClient/ClientCredentialsClient accept an application
+  credential (exclusive with the raw pair, which now wraps into
+  ClientSecret) and a per-call issuer; token-endpoint cache is keyed by
+  issuer; credential-prepared params merge under caller overrides
+- Conformance suites cover the full 16-row AccessContext table and the
+6-row multi-zone table, plus orchestration coverage.
+- feat(keycardai-oauth): application credentials (ClientSecret, WebIdentity, WorkloadIdentity) (#5)
+- Implements specs/application-credentials/{client-secret,web-identity,
+workload-identity}.md. The Credential interface is two methods:
+authorization_header(issuer:) and prepare_token_exchange_request.
+- - ClientSecret: client_secret_basic only; single pair or issuer-keyed
+  multi-zone map; construction rejects empty ids/secrets/maps; unknown
+  zones fail closed by raising (Python shape), never falling back
+- PrivateKeyManager + FilePrivateKeyStorage: RSA-2048 generate/persist/
+  load (./server_keys default, ./mcp_keys legacy fallback), RFC 7523
+  create_client_assertion (iss=sub=client_id, aud=token_endpoint, jti,
+  iat, exp=iat+300), public JWKS export
+- WebIdentity: key-id resolution (explicit, sanitized server_name,
+  UUID), lazy key bootstrap, fresh assertion per request, no Basic
+  header, public_jwks + client_jwks_url accessors
+- WorkloadIdentity: pluggable IdentityTokenSource (bare callables
+  adapted), token fetched fresh every request, optional client_id form
+  param (KEP 108), typed WorkloadIdentity{Configuration,Runtime}Error
+  with source ids and cause chaining
+- Token sources: FileTokenSource (the one blessed env read: 4-var
+  discovery list at exact cross-SDK parity, construction-time
+  validation), GCPMetadataTokenSource, FlyTokenSource (raw HTTP over
+  the Fly Unix socket)
+- No deprecated EKS alias: Ruby is new and ships none; FileTokenSource
+covers the EKS contract. Conformance suites map to all three spec
+Testing tables (workload-identity row 10 n/a per the above).
+- feat(keycardai-oauth): DCR, PKCE primitives, authorize URL, code exchange (#4)
+- Implements specs/oauth-client/dynamic-client-registration.md and the
+primitive + building-block layers of
+specs/oauth-client/authorization-code-pkce.md:
+- - register_client: RFC 7591 registration with RFC-minimal request
+  (only caller-supplied fields), additional_metadata bag with named
+  fields winning, initial_access_token Bearer auth, typed RFC 7591
+  3.2.2 error parsing, client_id required in the response
+- PKCE module: verifier generation (43-128, unreserved charset, 128
+  default), S256/plain challenge derivation, generate_pair
+- build_authorize_url: response_type=code plus PKCE, scope, state,
+  resource parameters
+- exchange_authorization_code: public clients send client_id in the
+  body, confidential clients use HTTP Basic and omit it
+- HTTP transport gains post_json; token-response parsing extracted to
+  TokenRequests module functions shared by the standalone exchange
+- The high-level authenticate loopback flow (browser + callback server +
+state validation) is the next slice; the spec unit tables do not cover
+it. Conformance specs map one to one to both spec Testing tables.
+- feat(keycardai-oauth): discovery, client credentials, token exchange, impersonation (#3)
+- Implements specs/oauth-client/{authorization-server-discovery,
+client-credentials,token-exchange}.md and
+specs/delegated-access/impersonation.md:
+- - fetch_authorization_server_metadata: RFC 8414 discovery with issuer
+  validation (issuer_mismatch), typed protocol errors, unknown fields
+  preserved; JWKSKeyring now discovers through this operation
+- TokenResponse: shared token shape (scope parsed to array, Bearer
+  default, id_token, raw preserved), rejects a missing access_token
+- TokenExchangeClient: RFC 8693 exchange with defaults, actor tokens,
+  client_assertion pass-through, Basic client auth, lazy cached token
+  endpoint, RFC 6749 5.2 typed OAuthError parsing
+- impersonate: substitute-user exchange (vnd.kc.su+jwt unsigned subject
+  token, no actor_token, resource required client-side)
+- ClientCredentialsClient: RFC 6749 4.4 grant on the same machinery
+- Conformance specs map one to one to all four spec Testing tables.
+- feat(keycardai-oauth): JWT/JWKS layer with conformance suites (#2)
+- Implements specs/jwt-jwks/jwks-caching.md and
+specs/jwt-jwks/jwt-signing-and-verification.md plus the shared
+foundations they need:
+- - Error taxonomy rooted at Keycardai::Error (configuration, network,
+  HTTP, invalid-token, JWKS quartet)
+- Pluggable HTTP transport with a Net::HTTP default; no hidden retries
+- JWKSKeyring: (issuer, kid) resolution with discovery + key TTLs,
+  same-origin jwks_uri enforcement, bounded cache with oldest-entry
+  eviction, per-issuer in-flight de-duplication
+- JWTSigner: RS256, header {alg, kid}, default iss only when omitted,
+  temporal claims caller-managed
+- JWTVerifier: fail-closed RFC 9068 verification, policy checks before
+  key resolution, trusted-issuer allowlist, kid required, alg allowlist
+  with none always rejected, clock_skew default 0 (exact comparison,
+  the canonical behavior per the spec Divergences; the types-table 60s
+  default looks stale and will be raised upstream)
+- Conformance specs map one to one to the spec Testing tables; the two
+live-zone integration rows are deferred to the E2E phase.

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/token_verifier.rb

@@ -4,13 +4,47 @@ module Keycardai
   module OAuth
     # A verified bearer token: the raw compact JWT plus its verified claims,
     # with convenience accessors for the RFC 9068 profile.
+    #
+    # Four accessors answer distinct questions about the caller, and picking
+    # the wrong one is a real bug rather than a style choice:
+    #
+    # - #client_id is the OAuth client that authenticated, so it names the
+    #   credential. It rotates, so it does not stably identify an application.
+    # - #keycard_app_id is the stable Keycard application identifier. Key on
+    #   this to answer "which application is calling", whatever the grant type
+    #   or credential. For user agents it equals #client_id.
+    # - #subject is the user identifier on a user-present token and the
+    #   application identifier on an application token.
+    # - #subject_profile distinguishes those two cases directly, rather than
+    #   leaving a consumer to infer it from #subject against #client_id.
+    #
+    # #subject and #client_id are RFC 9068. The other two are Keycard claims
+    # and are absent from a non-Keycard token, so they return nil there.
     AccessToken = Data.define(:token, :claims) do
-      # @return [String] the token's subject
+      # @return [String] the token's subject: the user for a user-present
+      #   token, the application for an application token
       def subject
         claims["sub"]
       end
 
-      # @return [String]
+      # Whether a user authorized this access or an application is acting on
+      # its own behalf. Reads the Keycard `sub_profile` claim.
+      #
+      # @return ["user", "app", nil] nil on a non-Keycard token
+      def subject_profile
+        claims["sub_profile"]
+      end
+
+      # The stable Keycard application identifier, which is the claim to key
+      # on when identifying the calling application.
+      #
+      # @return [String, nil] nil on a non-Keycard token
+      def keycard_app_id
+        claims["keycard_app_id"]
+      end
+
+      # @return [String] the OAuth client that authenticated, meaning the
+      #   credential rather than the application
       def client_id
         claims["client_id"]
       end

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.1.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.1.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