keycardai-oauth 0.1.0

data/lib/keycardai/oauth/token_requests.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Keycardai
+  module OAuth
+    # Shared internals for clients that POST to the token endpoint: lazy
+    # endpoint discovery with caching, shared-secret (HTTP Basic) client
+    # authentication, and RFC 6749 §5.2 error parsing. Not public API.
+    module TokenRequests
+      # Parse a token-endpoint response: a TokenResponse on 2xx, a raised
+      # typed error otherwise.
+      #
+      # @param response [HTTP::Response]
+      # @return [TokenResponse]
+      def self.parse_response(response)
+        raise error_for(response) unless response.success?
+
+        document = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise ProtocolError.new("token response is not valid JSON", code: "invalid_response")
+        end
+        unless document.is_a?(Hash)
+          raise ProtocolError.new("token response is not a JSON object",
+                                  code: "invalid_response")
+        end
+
+        TokenResponse.from_wire(document)
+      end
+
+      # RFC 6749 §5.2: an error response carries error / error_description /
+      # error_uri. Anything else non-2xx is a plain HTTP error.
+      #
+      # @param response [HTTP::Response]
+      # @return [OAuthError, HTTPError]
+      def self.error_for(response)
+        payload = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          nil
+        end
+        unless payload.is_a?(Hash) && payload["error"].is_a?(String)
+          return HTTPError.new("token endpoint returned HTTP #{response.status}",
+                               status: response.status, body: response.body)
+        end
+
+        OAuthError.new("token endpoint returned #{payload["error"]}",
+                       error: payload["error"], error_description: payload["error_description"],
+                       error_uri: payload["error_uri"], status: response.status, body: response.body)
+      end
+
+      private
+
+      def initialize_token_client(issuer:, credential:, client_id:, client_secret:, http_client:, timeout:)
+        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
+        @token_endpoints = {}
+        @token_endpoint_mutex = Mutex.new
+      end
+
+      def validate_client_auth(credential, client_id, client_secret)
+        if credential && (client_id || client_secret)
+          raise ConfigurationError, "provide a credential or a client_id/client_secret pair, not both"
+        end
+        return unless (client_id.nil? || client_secret.nil?) && client_id != client_secret
+
+        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.
+      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
+        end
+      end
+
+      def post_token_request(params, issuer: @issuer)
+        headers = { "Accept" => "application/json" }
+        authorization = @credential&.authorization_header(issuer: issuer)
+        headers["Authorization"] = authorization if authorization
+
+        response = @http_client.post_form(token_endpoint(issuer), params.compact, headers: headers,
+                                                                                  timeout: @timeout)
+        TokenRequests.parse_response(response)
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/token_sources.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "uri"
+
+module Keycardai
+  module OAuth
+    # Reads a platform-projected identity token file, fresh on every call.
+    # Covers EKS (AWS_* env vars), AKS (AZURE_FEDERATED_TOKEN_FILE), any
+    # Kubernetes projected service-account token, and file-mode CI providers.
+    #
+    # Path discovery through the well-known env vars below is the one blessed
+    # environment read in the SDK (a deliberate platform convention). An
+    # explicit token_file_path wins; env_var_name is consulted first when
+    # given. The resolved file is validated at construction (exists,
+    # non-empty), preserving fail-fast behavior.
+    class FileTokenSource
+      DEFAULT_ENV_VARS = %w[
+        KEYCARD_EKS_WORKLOAD_IDENTITY_TOKEN_FILE
+        AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
+        AWS_WEB_IDENTITY_TOKEN_FILE
+        AZURE_FEDERATED_TOKEN_FILE
+      ].freeze
+
+      # @param token_file_path [String, nil] explicit path; skips discovery
+      # @param env_var_name [String, nil] extra env var consulted first
+      # @param env [Hash] the environment to discover from; override in tests
+      # @raise [WorkloadIdentityConfigurationError] no path resolved, or the
+      #   resolved file is missing or empty
+      def initialize(token_file_path: nil, env_var_name: nil, env: ENV)
+        @path = token_file_path || discover_path(env_var_name, env)
+        validate_file
+      end
+
+      # @return [String] the current platform token, read fresh
+      # @raise [WorkloadIdentityRuntimeError] unreadable or empty file
+      def identity_token
+        token = File.read(@path).strip
+        raise WorkloadIdentityRuntimeError.new("token file #{@path} is empty", source: "file") if token.empty?
+
+        token
+      rescue SystemCallError => e
+        raise WorkloadIdentityRuntimeError.new("token file #{@path} is unreadable: #{e.message}", source: "file")
+      end
+
+      def source_identifier
+        "file"
+      end
+
+      private
+
+      def discover_path(env_var_name, env)
+        [env_var_name, *DEFAULT_ENV_VARS].compact.each do |name|
+          value = env[name]
+          return value if value && !value.empty?
+        end
+        raise WorkloadIdentityConfigurationError.new(
+          "no token_file_path given and no discovery env var set (#{DEFAULT_ENV_VARS.join(", ")})",
+          source: "file"
+        )
+      end
+
+      def validate_file
+        return if File.file?(@path) && !File.empty?(@path)
+
+        raise WorkloadIdentityConfigurationError.new("token file #{@path} is missing or empty", source: "file")
+      end
+    end
+
+    # Fetches an identity token from the GCP metadata server. Covers GKE,
+    # GCE, and Cloud Run.
+    class GCPMetadataTokenSource
+      DEFAULT_METADATA_URL = "http://metadata.google.internal"
+      IDENTITY_PATH = "/computeMetadata/v1/instance/service-accounts/default/identity"
+
+      # @param audience [String] the aud claim the platform mints into the token
+      # @param metadata_url [String] override for testing
+      # @param timeout [Numeric, nil]
+      # @param http_client [#get] pluggable transport
+      # @raise [WorkloadIdentityConfigurationError] missing audience
+      def initialize(audience:, metadata_url: DEFAULT_METADATA_URL, timeout: nil,
+                     http_client: HTTP::NetHTTPClient.new)
+        if audience.nil? || audience.empty?
+          raise WorkloadIdentityConfigurationError.new("GCPMetadataTokenSource requires an audience",
+                                                       source: "gcp-metadata")
+        end
+
+        @audience = audience
+        @metadata_url = metadata_url
+        @timeout = timeout
+        @http_client = http_client
+      end
+
+      # @return [String] the current platform token
+      # @raise [WorkloadIdentityRuntimeError] endpoint unreachable or non-200
+      def identity_token
+        url = "#{@metadata_url}#{IDENTITY_PATH}?#{URI.encode_www_form("audience" => @audience, "format" => "full")}"
+        response = begin
+          @http_client.get(url, headers: { "Metadata-Flavor" => "Google" }, timeout: @timeout)
+        rescue NetworkError => e
+          raise WorkloadIdentityRuntimeError.new("metadata server unreachable: #{e.message}", source: "gcp-metadata")
+        end
+        unless response.success?
+          raise WorkloadIdentityRuntimeError.new("metadata server returned HTTP #{response.status}",
+                                                 source: "gcp-metadata")
+        end
+
+        response.body
+      end
+
+      def source_identifier
+        "gcp-metadata"
+      end
+    end
+
+    # Fetches an identity token from the Fly.io machines API over its local
+    # Unix socket.
+    class FlyTokenSource
+      DEFAULT_SOCKET_PATH = "/.fly/api"
+      TOKEN_PATH = "/v1/tokens/oidc"
+
+      # @param audience [String, nil] included as {"aud": audience} when set
+      # @param socket_path [String]
+      def initialize(audience: nil, socket_path: DEFAULT_SOCKET_PATH)
+        @audience = audience
+        @socket_path = socket_path
+      end
+
+      # @return [String] the current platform token
+      # @raise [WorkloadIdentityRuntimeError] socket unreachable or non-200
+      def identity_token
+        body = JSON.dump(@audience ? { "aud" => @audience } : {})
+        status, response_body = post_over_socket(body)
+        unless (200..299).cover?(status)
+          raise WorkloadIdentityRuntimeError.new("fly API returned HTTP #{status}", source: "fly")
+        end
+
+        response_body
+      end
+
+      def source_identifier
+        "fly"
+      end
+
+      private
+
+      def post_over_socket(body)
+        UNIXSocket.open(@socket_path) do |socket|
+          socket.write("POST #{TOKEN_PATH} HTTP/1.1\r\n" \
+                       "Host: localhost\r\n" \
+                       "Content-Type: application/json\r\n" \
+                       "Content-Length: #{body.bytesize}\r\n" \
+                       "Connection: close\r\n\r\n#{body}")
+          parse_http_response(socket.read)
+        end
+      rescue SystemCallError => e
+        raise WorkloadIdentityRuntimeError.new("fly API socket #{@socket_path} unreachable: #{e.message}",
+                                               source: "fly")
+      end
+
+      def parse_http_response(raw)
+        header, body = raw.split("\r\n\r\n", 2)
+        status = header[%r{\AHTTP/\d\.\d (\d{3})}, 1].to_i
+        [status, body.to_s]
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/token_types.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # RFC 8693 token-type URIs, plus the Keycard substitute-user extension.
+    module TokenType
+      ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token"
+      REFRESH_TOKEN = "urn:ietf:params:oauth:token-type:refresh_token"
+      ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token"
+      JWT = "urn:ietf:params:oauth:token-type:jwt"
+      SUBSTITUTE_USER = "urn:keycard:params:oauth:token-type:substitute-user"
+    end
+
+    # OAuth 2.0 grant-type identifiers the SDK speaks.
+    module GrantType
+      CLIENT_CREDENTIALS = "client_credentials"
+      AUTHORIZATION_CODE = "authorization_code"
+      TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange"
+    end
+
+    # A token issued by the authorization server, the shared response shape of
+    # token exchange, client credentials, and the authorization-code exchange.
+    # +scope+ is parsed from the space-separated wire value into an array;
+    # +token_type+ defaults to "Bearer" when the server omits it. The complete
+    # response body is preserved in +raw+.
+    TokenResponse = Data.define(
+      :access_token, :token_type, :expires_in, :scope, :issued_token_type, :refresh_token, :id_token, :raw
+    ) do
+      # @param payload [Hash] the parsed token-endpoint response body
+      # @return [TokenResponse]
+      # @raise [ProtocolError] when the response carries no access token
+      def self.from_wire(payload)
+        access_token = payload["access_token"]
+        unless access_token.is_a?(String) && !access_token.empty?
+          raise ProtocolError.new("token response has no access_token", code: "invalid_response")
+        end
+
+        new(
+          access_token: access_token,
+          token_type: payload["token_type"] || "Bearer",
+          expires_in: payload["expires_in"],
+          scope: payload["scope"]&.split,
+          issued_token_type: payload["issued_token_type"],
+          refresh_token: payload["refresh_token"],
+          id_token: payload["id_token"],
+          raw: payload
+        )
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/token_verifier.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # A verified bearer token: the raw compact JWT plus its verified claims,
+    # with convenience accessors for the RFC 9068 profile.
+    AccessToken = Data.define(:token, :claims) do
+      # @return [String] the token's subject
+      def subject
+        claims["sub"]
+      end
+
+      # @return [String]
+      def client_id
+        claims["client_id"]
+      end
+
+      # @return [String] the issuer that minted the token
+      def issuer
+        claims["iss"]
+      end
+
+      # @return [Array<String>] audiences the token was minted for
+      def audiences
+        Array(claims["aud"])
+      end
+
+      # @return [Array<String>] scopes granted to the token
+      def scopes
+        claims["scope"].to_s.split
+      end
+
+      # @return [Time]
+      def expires_at
+        Time.at(claims["exp"])
+      end
+    end
+
+    # Server-tier bearer-token verification: JWTVerifier over a JWKSKeyring,
+    # returning an AccessToken. Construct once per server with the trusted
+    # zone issuer(s); JWKS and discovery caches are keyed by issuer so no
+    # zone's keys are ever served for another.
+    class TokenVerifier
+      # @param issuers [String, Array<String>] trusted zone issuer URL(s)
+      # @param audiences [String, Array<String>, nil] when set, tokens must
+      #   carry an intersecting aud
+      # @param http_client [#get] pluggable transport
+      # @param key_ttl [Numeric] JWKS key cache lifetime in seconds
+      # @param discovery_ttl [Numeric] jwks_uri cache lifetime in seconds
+      # @param fetch_timeout [Numeric] discovery and JWKS fetch timeout
+      # @param clock [#call] returns the current Time; override in tests
+      # @raise [ConfigurationError] no trusted issuer
+      def initialize(issuers:, audiences: nil, http_client: HTTP::NetHTTPClient.new,
+                     key_ttl: JWKSKeyring::DEFAULT_KEY_TTL, discovery_ttl: JWKSKeyring::DEFAULT_DISCOVERY_TTL,
+                     fetch_timeout: JWKSKeyring::DEFAULT_FETCH_TIMEOUT, clock: -> { Time.now })
+        @issuers = Array(issuers).reject { |issuer| issuer.nil? || issuer.empty? }
+        raise ConfigurationError, "TokenVerifier requires at least one trusted issuer" if @issuers.empty?
+
+        @audiences = audiences
+        @clock = clock
+        @keyring = JWKSKeyring.new(http_client: http_client, key_ttl: key_ttl,
+                                   discovery_ttl: discovery_ttl, fetch_timeout: fetch_timeout, clock: clock)
+      end
+
+      # Verify a bearer token against the configured issuer allowlist.
+      #
+      # @param token [String]
+      # @return [AccessToken]
+      # @raise [InvalidTokenError, JWKSError]
+      def verify_token(token)
+        verify_against(@issuers, token)
+      end
+
+      # Verify a bearer token pinned to one zone's issuer. A token minted by
+      # any other zone is rejected before key resolution, and an issuer
+      # outside the configured allowlist fails closed.
+      #
+      # @param token [String]
+      # @param issuer [String] the zone's issuer URL
+      # @return [AccessToken]
+      # @raise [InvalidTokenError, JWKSError]
+      def verify_token_for_zone(token, issuer)
+        raise InvalidTokenError, "zone issuer is not configured on this verifier" unless @issuers.include?(issuer)
+
+        verify_against([issuer], token)
+      end
+
+      # Drop all cached keys and discovery results.
+      #
+      # @return [void]
+      def clear_cache
+        @keyring.invalidate
+      end
+
+      private
+
+      def verify_against(issuers, token)
+        claims = JWTVerifier.new(issuers: issuers, keyring: @keyring, audiences: @audiences,
+                                 clock: @clock).verify(token)
+        AccessToken.new(token: token, claims: claims)
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    VERSION = "0.1.0"
+  end
+end

data/lib/keycardai/oauth/web_identity.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Keycardai
+  module OAuth
+    # private_key_jwt credential (RFC 7523) with auto-managed asymmetric keys:
+    # generates and persists an RSA-2048 keypair on first use, signs a
+    # short-lived client assertion on every token request, and exposes the
+    # public JWKS for the authorization server to verify. The recommended
+    # credential for production workloads that can persist a keypair; the
+    # private key never leaves the workload.
+    #
+    # Holds no shared secret and contributes no Basic header. Never reads
+    # environment variables; the caller supplies storage configuration.
+    class WebIdentity
+      # @param client_id [String] the registered OAuth client id, signed as
+      #   the assertion's iss and sub
+      # @param server_name [String, nil] sanitized into the key id when no
+      #   key_id is given
+      # @param key_id [String, nil] explicit key id (the JWT kid); otherwise
+      #   derived from server_name, otherwise a generated UUID
+      # @param storage [#load, #store, nil] pluggable keypair storage
+      # @param storage_dir [String, nil] directory for the default file store
+      # @param clock [#call] returns the current Time; override in tests
+      # @raise [ConfigurationError] missing client_id
+      def initialize(client_id:, server_name: nil, key_id: nil, storage: nil, storage_dir: nil,
+                     clock: -> { Time.now })
+        raise ConfigurationError, "WebIdentity requires a client_id" if client_id.nil? || client_id.empty?
+
+        @client_id = client_id
+        storage ||= FilePrivateKeyStorage.new(dir: storage_dir || FilePrivateKeyStorage::DEFAULT_DIR)
+        @key_manager = PrivateKeyManager.new(
+          key_id: key_id || sanitize(server_name) || SecureRandom.uuid,
+          storage: storage, clock: clock
+        )
+      end
+
+      # @return [String] the key id used as the assertion's kid
+      def key_id
+        @key_manager.key_id
+      end
+
+      # Assertion-based authentication contributes no Basic header.
+      #
+      # @param issuer [String, nil] unused; part of the Credential interface
+      # @return [nil]
+      def authorization_header(issuer: nil)
+        nil
+      end
+
+      # Build the token-exchange form parameters, signing a fresh client
+      # assertion for this request.
+      #
+      # @param subject_token [String]
+      # @param token_endpoint [String] the assertion's audience
+      # @param resource [String, nil]
+      # @param audience [String, nil]
+      # @param scope [String, nil]
+      # @param issuer [String, nil] unused; part of the Credential interface
+      # @return [Hash]
+      # @raise [ConfigurationError] when token_endpoint is missing
+      def prepare_token_exchange_request(subject_token:, token_endpoint: nil, resource: nil,
+                                         audience: nil, scope: nil, issuer: nil)
+        if token_endpoint.nil? || token_endpoint.empty?
+          raise ConfigurationError, "WebIdentity requires the token_endpoint as the assertion audience"
+        end
+
+        {
+          "grant_type" => GrantType::TOKEN_EXCHANGE,
+          "subject_token" => subject_token,
+          "subject_token_type" => TokenType::ACCESS_TOKEN,
+          "resource" => resource,
+          "audience" => audience,
+          "scope" => scope,
+          "client_assertion" => @key_manager.create_client_assertion(client_id: @client_id,
+                                                                     audience: token_endpoint),
+          "client_assertion_type" => PrivateKeyManager::ASSERTION_TYPE
+        }.compact
+      end
+
+      # The public JWKS the authorization server verifies assertions against.
+      #
+      # @return [Hash] {"keys" => [...]}
+      def public_jwks
+        @key_manager.public_jwks
+      end
+
+      # The conventional URL where this workload serves its public JWKS.
+      #
+      # @param base_url [String] the workload's public base URL
+      # @return [String]
+      def client_jwks_url(base_url)
+        "#{base_url.chomp("/")}/.well-known/jwks.json"
+      end
+
+      private
+
+      def sanitize(server_name)
+        return nil if server_name.nil? || server_name.empty?
+
+        server_name.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      end
+    end
+  end
+end

data/lib/keycardai/oauth/workload_identity.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module OAuth
+    # Workload-identity credential: authenticates with a platform-signed OIDC
+    # token as its client assertion (RFC 7523 over RFC 8693). One generic
+    # credential owns the exchange contract; a pluggable identity-token source
+    # supplies the platform token, fetched fresh on every request because
+    # platforms rotate these tokens. The credential never caches the token; a
+    # source may cache internally when the platform contract makes that safe.
+    #
+    # Holds no shared secret and contributes no Basic header.
+    class WorkloadIdentity
+      # @param source [#identity_token, #call] supplies the platform-signed
+      #   OIDC token; a bare callable is accepted
+      # @param client_id [String, nil] the Keycard application credential this
+      #   workload authenticates as; sent as the client_id form parameter when
+      #   set (token-federation credentials are resolved by it)
+      # @raise [ConfigurationError] when the source is missing or has neither
+      #   an identity_token method nor call
+      def initialize(source:, client_id: nil)
+        @source = normalize_source(source)
+        @client_id = client_id
+      end
+
+      # Assertion-based authentication contributes no Basic header.
+      #
+      # @param issuer [String, nil] unused; part of the Credential interface
+      # @return [nil]
+      def authorization_header(issuer: nil)
+        nil
+      end
+
+      # Build the token-exchange form parameters, fetching a fresh platform
+      # token from the source.
+      #
+      # @param subject_token [String]
+      # @param resource [String, nil]
+      # @param audience [String, nil]
+      # @param scope [String, nil]
+      # @param token_endpoint [String, nil] unused; part of the interface
+      # @param issuer [String, nil] unused; part of the Credential interface
+      # @return [Hash]
+      # @raise [WorkloadIdentityRuntimeError] the source failed to produce a token
+      def prepare_token_exchange_request(subject_token:, resource: nil, audience: nil, scope: nil,
+                                         token_endpoint: nil, issuer: nil)
+        {
+          "grant_type" => GrantType::TOKEN_EXCHANGE,
+          "subject_token" => subject_token,
+          "subject_token_type" => TokenType::ACCESS_TOKEN,
+          "resource" => resource,
+          "audience" => audience,
+          "scope" => scope,
+          "client_id" => @client_id,
+          "client_assertion" => fetch_identity_token,
+          "client_assertion_type" => PrivateKeyManager::ASSERTION_TYPE
+        }.compact
+      end
+
+      private
+
+      def normalize_source(source)
+        return source if source.respond_to?(:identity_token)
+        return FunctionTokenSource.new(source) if source.respond_to?(:call)
+
+        raise ConfigurationError, "WorkloadIdentity source must respond to identity_token or call"
+      end
+
+      def fetch_identity_token
+        token = @source.identity_token
+        if token.nil? || token.empty?
+          raise WorkloadIdentityRuntimeError.new("identity token source returned an empty token",
+                                                 source: source_identifier)
+        end
+
+        token
+      rescue WorkloadIdentityRuntimeError, WorkloadIdentityConfigurationError
+        raise
+      rescue StandardError => e
+        raise WorkloadIdentityRuntimeError.new("identity token source failed: #{e.message}",
+                                               source: source_identifier)
+      end
+
+      def source_identifier
+        @source.respond_to?(:source_identifier) ? @source.source_identifier : "custom"
+      end
+
+      # Adapter making a bare callable usable as an identity-token source.
+      class FunctionTokenSource
+        def initialize(callable)
+          @callable = callable
+        end
+
+        def identity_token
+          @callable.call
+        end
+
+        def source_identifier
+          "custom"
+        end
+      end
+    end
+  end
+end

data/lib/keycardai/oauth.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "oauth/version"
+require_relative "oauth/errors"
+require_relative "oauth/http"
+require_relative "oauth/discovery"
+require_relative "oauth/token_types"
+require_relative "oauth/token_requests"
+require_relative "oauth/substitute_user"
+require_relative "oauth/pkce"
+require_relative "oauth/authorization_code"
+require_relative "oauth/authenticate"
+require_relative "oauth/registration"
+require_relative "oauth/client_secret"
+require_relative "oauth/private_key"
+require_relative "oauth/web_identity"
+require_relative "oauth/workload_identity"
+require_relative "oauth/token_sources"
+require_relative "oauth/access_context"
+require_relative "oauth/exchange_tokens"
+require_relative "oauth/token_verifier"
+require_relative "oauth/token_exchange_client"
+require_relative "oauth/client_credentials_client"
+require_relative "oauth/jwks_keyring"
+require_relative "oauth/jwt_signer"
+require_relative "oauth/jwt_verifier"
+
+# Root namespace shared by all Keycard gems.
+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.
+  #
+  # Contract: https://github.com/keycardai/keycard-sdk-spec
+  module OAuth
+  end
+end