authproto 0.3.0.beta2 → 0.3.0.beta3

data/lib/authproto/client.rb

@@ -7,7 +7,6 @@ require 'uri'
 
 require_relative 'configuration'
 require_relative 'dpop/client'
-require_relative 'dpop/key_manager'
 require_relative 'errors'
 require_relative 'metadata/authorization_server'
 require_relative 'metadata/client_metadata'
@@ -73,44 +72,51 @@ module AuthProto
     # @return [State::SessionManager]
     attr_reader :session_manager
 
-    # DPoP key, proof and nonce manager.
+    # Shared DPoP proof generator and per-server nonce manager.
     # @return [DPoP::Client]
     attr_reader :dpop_client
 
-    # Creates an OAuth client with its own DPoP key and session manager.
+    # Creates an OAuth client with shared DPoP helpers and a session manager.
     #
     # Configure {AuthProto.configure} with an HTTP transport before fetching metadata
-    # or starting authorization. Reuse `dpop_key` when restoring tokens bound to that key.
+    # or starting authorization. Session storage restores the DPoP key bound to each session.
     #
     # @param client_id [String] OAuth client ID URL
     # @param redirect_uri [String] callback URI listed in `redirect_uris`
     # @param metadata [Hash{String => Object}, nil] preloaded metadata, or `nil` to fetch `client_id`
     # @param signing_key [Hash, JOSE::JWK, nil] private ES256 client-authentication key, separate from public metadata
-    # @param dpop_key [Hash{String => Object}, nil] existing private DPoP JWK, or `nil` to generate one
     #
-    # @raise [InvalidClientMetadata] if client metadata is invalid or unavailable
+    # @raise [InvalidClientMetadata] if metadata is invalid, unavailable, has a different client ID,
+    #   or the supplied signing key is missing, unexpected or does not match inline public metadata
+    # @raise [PAR::ClientAssertion::Error] if the private assertion key is invalid or unusable
     # @raise [Error] if the redirect URI is not registered
-    # @raise [DPoP::KeyManager::KeyError] if the DPoP key cannot be imported or generated
     # @raise [HTTPClient::HTTPError, HTTPClient::SSRFError] if fetching client metadata fails
     #
-    def initialize(client_id:, redirect_uri:, metadata: nil, dpop_key: nil, signing_key: nil)
+    def initialize(client_id:, redirect_uri:, metadata: nil, signing_key: nil)
       @client_id = client_id
       @redirect_uri = redirect_uri
 
-      # Client metadata is fetched from .well-known if not provided directly
+      if metadata && metadata['client_id'] != @client_id
+        raise InvalidClientMetadata, "client_id mismatch: #{metadata['client_id']} != #{@client_id}"
+      end
+
+      # Client metadata is fetched from the client ID URL if not provided directly
       @client_metadata = load_client_metadata(metadata)
 
       validate_redirect_uri
-      @signing_key = initialize_signing_key(signing_key)
+      initialize_client_assertion(signing_key)
 
-      @session_manager = State::SessionManager.new
-      @dpop_client = initialize_dpop(dpop_key)
+      signing_keys = @client_assertion ? { @signing_key_kid => @signing_key_thumbprint } : {}
+      @session_manager = State::SessionManager.new(supported_signing_keys: signing_keys)
+
+      @dpop_client = DPoP::Client.new
     end
 
     # Starts authorization, stores a pending session, and submits a PAR request.
     #
     # Supply exactly one of `handle` or `pds`. Open the returned `:url` in a browser
-    # and pass the eventual callback parameters to {#handle_callback}.
+    # and pass the eventual callback parameters to {#handle_callback}. Retain `:session_id`
+    # in the initiating browser session or native login context for callback verification.
     #
     # @param handle [String, nil] account handle (optionally prefixed with `@`) or DID
     # @param pds [String, nil] PDS URL when no handle is supplied
@@ -124,6 +130,7 @@ module AuthProto
     # @raise [PAR::ClientAssertion::Error] if confidential-client signing fails
     # @raise [DPoP::Client::Error] if generating the PAR proof fails
     # @raise [HTTPClient::SSRFError] if server discovery rejects a destination
+    # @raise [DPoP::KeySet::KeyError] if generating the session key fails
     # @raise [Storage::StorageError] if session storage or locking fails
     # @raise [Encryption::EncryptionError] if session serialization cannot encrypt secrets
     #
@@ -138,12 +145,15 @@ module AuthProto
         raise Error, "No HTTPS PDS location found for #{did}" unless pds && URI(pds).is_a?(URI::HTTPS)
       end
 
-      authorization_server = resolve_auth_server(pds)
+      authorization_server = resolve_auth_server_info(pds)
 
-      session = session_manager.create_session(client_id: @client_id, scope: scope)
-      session.authorization_server = authorization_server
-      session.did = did&.to_s
-      session_manager.update_session(session)
+      session = session_manager.create_session(
+        client_id: @client_id,
+        scope: scope,
+        auth_server: authorization_server,
+        did: did&.to_s,
+        signing_key_id: @signing_key_kid
+      )
 
       auth_url = submit_authorization_par(authorization_server, session, login_hint: handle)
 
@@ -160,12 +170,18 @@ module AuthProto
     # and `:scope` (String).
     # It also contains `:session_id` (String) and `:did` (String).
     #
+    # Supply the session ID retained when starting authorization as `expected_session_id`.
+    # For web apps, read it from the initiating browser's session, never from callback parameters
+    # or the state-token lookup. It is checked before exchanging the authorization code.
+    # Remove the browser's pending-session association after this method succeeds.
+    #
     # @param code [String] authorization code from the callback
     # @param state [String] state token from the callback
     # @param iss [String] issuer URL from the callback
+    # @param expected_session_id [String] pending session ID retained by the caller when authorization started
     #
     # @return [Hash{Symbol => String, Integer, nil}] tokens and authenticated session details
-    # @raise [CallbackError] if state is unknown or the issuer does not match the session
+    # @raise [CallbackError] if the expected session ID is invalid, state is unknown, or session/issuer validation fails
     # @raise [TokenError] if token exchange or response validation fails
     # @raise [DPoP::Client::Error, PAR::ClientAssertion::Error] if proof/assertion generation fails
     # @raise [HTTPClient::HTTPError, HTTPClient::SSRFError] if token transport fails
@@ -174,15 +190,19 @@ module AuthProto
     # @raise [Storage::StorageError] if session storage or locking fails
     # @raise [Encryption::EncryptionError] if tokens cannot be encrypted for storage
     #
-    def handle_callback(code:, state:, iss:)
-      session = session_manager.get_session_by_state(state)
+    def handle_callback(code:, state:, iss:, expected_session_id:)
+      unless expected_session_id.is_a?(String) && !expected_session_id.empty?
+        raise CallbackError, "Expected session ID is required"
+      end
+
+      session = session_manager.get_session_by_state_token(state)
 
       raise CallbackError, "Invalid state parameter" unless session
+      raise CallbackError, "Session ID mismatch" unless session.session_id == expected_session_id
       raise CallbackError, "Issuer mismatch" unless session.auth_server && session.auth_server.issuer == iss
 
       AuthProto.storage.with_lock(Storage::KeyBuilder.lock_key("session", session.session_id), ttl: 30) do
         response = exchange_code(code: code, session: session)
-        validate_token_response(response, session)
 
         token_set = State::TokenSet.new(
           access_token: response['access_token'],
@@ -194,7 +214,7 @@ module AuthProto
         )
 
         session.tokens = token_set
-        session_manager.update_session(session)
+        session_manager.complete_authorization(session)
 
         session.session_data
       end
@@ -213,7 +233,7 @@ module AuthProto
     #
     def get_tokens(session_id)
       session = session_manager.get_session(session_id)
-      return nil unless session&.authorized?
+      return nil unless session && session.tokens_valid?
 
       session.session_data
     end
@@ -230,6 +250,7 @@ module AuthProto
     # @return [Hash{Symbol => String, Integer, nil}] replacement tokens and session identifiers
     # @raise [TokenError] if the session is missing or has no refresh token
     # @raise [Token::RefreshError] if token refresh fails or exhausts retries
+    # @raise [DPoP::Client::Error] if a refresh response lacks a valid nonce
     # @raise [State::SessionError] if replacement tokens have a different subject
     # @raise [Storage::StorageError] if session storage or locking fails
     # @raise [Encryption::EncryptionError] if replacement tokens cannot be stored
@@ -246,7 +267,7 @@ module AuthProto
           dpop_client: @dpop_client,
           auth_server: session.auth_server,
           client_metadata: @client_metadata,
-          signing_key: @signing_key
+          client_assertion: @client_assertion
         )
 
         new_tokens = refresher.perform_refresh
@@ -265,13 +286,13 @@ module AuthProto
     #
     def authorized?(session_id)
       session = session_manager.get_session(session_id)
-      session&.authorized? || false
+      session ? session.tokens_valid? : false
     end
 
     # Builds authorization headers and a fresh DPoP proof for one HTTP request.
     #
     # The caller sends the request. This method does not refresh tokens, send HTTP,
-    # or retry nonce challenges. Feed response headers to {DPoP::Client#process_response}
+    # or retry nonce challenges. Feed each full HTTP response to {DPoP::Client#process_response}
     # and call {#refresh_token} explicitly when needed. Generate new headers for each retry.
     #
     # @param session_id [String] authorized session ID
@@ -286,9 +307,11 @@ module AuthProto
       session = session_manager.get_session(session_id)
 
       raise TokenError, "Invalid session" unless session
-      raise TokenError, "Session not authorized" unless session.authorized?
+      raise TokenError, "Session not authorized" if session.pending?
+      raise TokenError, "Session has expired" unless session.tokens_valid?
 
       dpop_proof = dpop_client.generate_proof(
+        session: session,
         method: method,
         uri: url,
         access_token: session.tokens.access_token
@@ -307,9 +330,6 @@ module AuthProto
     # @raise [Storage::StorageError] if deletion or locking fails
     #
     def delete_session(session_id)
-      key = Storage::KeyBuilder.session_key(session_id)
-
-      AuthProto.storage.delete(key)
       session_manager.delete_session(session_id)
     end
 
@@ -340,7 +360,7 @@ module AuthProto
       end
     end
 
-    def initialize_signing_key(key)
+    def initialize_client_assertion(key)
       if @client_metadata.confidential?
         raise InvalidClientMetadata, "Confidential clients require a signing_key" if key.nil?
       else
@@ -352,7 +372,7 @@ module AuthProto
       private_key = assertion.signing_key
 
       if @client_metadata.jwks
-        public_key = private_key.to_public.to_map.to_h
+        public_key = private_key.to_public_map.to_h
 
         key_in_jwks = @client_metadata.jwks['keys'].any? { |candidate|
           metadata_key_matches_public_key?(candidate, public_key)
@@ -361,24 +381,20 @@ module AuthProto
         raise InvalidClientMetadata, "signing_key must match an active public key advertised in jwks" if !key_in_jwks
       end
 
-      private_key
+      @client_assertion = assertion
+      @signing_key_kid = private_key.fields.fetch('kid')
+      @signing_key_thumbprint = private_key.thumbprint('SHA256')
     end
 
     def metadata_key_matches_public_key?(candidate, public_key)
       return false if candidate['revoked']
-      return false if candidate.key?('alg') && candidate['alg'] != 'ES256'
+      return false if candidate.key?('alg') && candidate['alg'] != PAR::ClientAssertion::ALGORITHM
       return false if candidate.key?('use') && candidate['use'] != 'sig'
       return false if candidate.key?('key_ops') && !candidate['key_ops'].include?('verify')
 
       %w[kid kty crv x y].all? { |field| candidate[field] == public_key[field] }
     end
 
-    def initialize_dpop(key)
-      key_manager = key ? DPoP::KeyManager.from_jwk(key) : DPoP::KeyManager.new
-
-      DPoP::Client.new(key_manager: key_manager)
-    end
-
     def validate_auth_params(handle, pds, scope)
       unless scope.is_a?(String) && scope.valid_encoding? && Metadata::ClientMetadata::SCOPE_PATTERN.match?(scope)
         raise Error, "scope must contain valid tokens separated by single spaces"
@@ -397,7 +413,7 @@ module AuthProto
       raise Error, "cannot provide both handle and pds" if handle && pds
     end
 
-    def resolve_auth_server(pds)
+    def resolve_auth_server_info(pds)
       resource_server = Metadata::ResourceServer.from_url(pds)
       auth_server_url = resource_server.authorization_server
 
@@ -419,16 +435,11 @@ module AuthProto
         req.code_challenge = session.pkce_challenge
 
         if @client_metadata.confidential?
-          req.client_assertion = PAR::ClientAssertion.new(client_id: @client_id, signing_key: @signing_key)
+          req.client_assertion = @client_assertion
         end
-
-        req.dpop_proof = @dpop_client.generate_proof(
-          method: 'POST',
-          uri: authorization_server.pushed_authorization_request_endpoint
-        )
       end
 
-      par_response = par_client.submit(par_request)
+      par_response = par_client.submit(par_request, session: session)
 
       par_client.build_authorization_url(
         request_uri: par_response.request_uri,
@@ -437,30 +448,26 @@ module AuthProto
     end
 
     def exchange_code(code:, session:)
-      # Initial token request without nonce
-      response = make_token_request(code, session)
-
-      # Handle DPoP nonce requirement
-      if requires_dpop_nonce?(response)
-        # Extract and store nonce from error response
-        extract_dpop_nonce(response)
-        dpop_client.process_response(response[:headers], session.auth_server.issuer)
-
-        # Retry request with nonce
-        response = make_token_request(code, session)
+      response = dpop_client.with_nonce_handling(session, session.auth_server.token_endpoint) do
+        make_token_request(code, session)
       end
 
       raise TokenError, "Token request failed: #{response[:status]}" unless response[:status] == 200
 
       begin
-        JSON.parse(response[:body])
+        data = JSON.parse(response[:body])
       rescue JSON::ParserError => e
         raise TokenError, "Invalid token response: #{e.message}"
       end
+
+      validate_token_response(data, session)
+
+      data
     end
 
     def make_token_request(code, session)
       dpop_proof = dpop_client.generate_proof(
+        session: session,
         method: 'POST',
         uri: session.auth_server.token_endpoint
       )
@@ -474,14 +481,9 @@ module AuthProto
       }
 
       if @client_metadata.confidential?
-        assertion = PAR::ClientAssertion.new(
-          client_id: @client_id,
-          signing_key: @signing_key
-        )
-
         body.merge!(
           client_assertion_type: PAR::CLIENT_ASSERTION_TYPE,
-          client_assertion: assertion.generate_jwt(audience: session.auth_server.issuer)
+          client_assertion: @client_assertion.generate_jwt(audience: session.auth_server.issuer)
         )
       end
 
@@ -495,38 +497,19 @@ module AuthProto
       )
     end
 
-    def requires_dpop_nonce?(response)
-      return false unless response[:status] == 400
-
-      error_data = JSON.parse(response[:body])
-      error_data['error'] == DPoP::ERROR_USE_NONCE
-    rescue JSON::ParserError
-      false
-    end
-
-    def extract_dpop_nonce(response)
-      headers = response[:headers]
-      nonce = headers.find { |k, v| k.downcase == 'dpop-nonce' }&.last
-
-      raise TokenError, "No DPoP nonce provided in error response" unless nonce
-
-      nonce
-    end
-
     def validate_token_response(response, session)
       ['access_token', 'token_type', 'expires_in', 'scope', 'sub'].each do |field|
         raise TokenError, "Missing #{field} in token response" unless response[field]
       end
 
-      raise TokenError, "Invalid token_type: #{response['token_type']}" unless response['token_type'] == 'DPoP'
+      unless response['token_type'].is_a?(String) && response['token_type'].casecmp?('DPoP')
+        raise TokenError, "Invalid token_type: #{response['token_type']}"
+      end
+
       raise TokenError, "Missing atproto scope in token response" unless response['scope'].split.include?('atproto')
 
       # If we have a pre-resolved DID, verify that it matches
       raise TokenError, "Subject mismatch in token response" if session.did && session.did != response['sub']
-
-      if response[:headers] && response[:headers]["DPoP-Nonce"]
-        dpop_client.process_response(response[:headers], session.auth_server.issuer)
-      end
     end
   end
 end

data/lib/authproto/configuration.rb

@@ -34,7 +34,7 @@ module AuthProto
     # @yieldparam config [Configuration] mutable global settings
     # @yieldreturn [Object] ignored
     # @return [Configuration] validated global settings
-    # @raise [ConfigurationError] if the storage or HTTP client is invalid
+    # @raise [ConfigurationError] if storage, HTTP transport or lifetime settings are invalid
     # @example Configure the default transport
     #   AuthProto.configure do |config|
     #     config.http_client = AuthProto::HTTPClient.new
@@ -62,7 +62,7 @@ module AuthProto
     end
   end
 
-  # Raised when global storage or HTTP transport settings are invalid.
+  # Raised when global configuration settings are invalid.
   class ConfigurationError < Error; end
 
   #
@@ -71,18 +71,14 @@ module AuthProto
 
   class Configuration
 
-    # Configured default token lifetime in seconds (300); currently unused by token exchange.
-    # @return [Integer]
-    attr_accessor :default_token_lifetime
+    # Default client assertion validity in seconds, read when generating each assertion.
+    # @return [Integer] positive lifetime in seconds; defaults to 300
+    attr_accessor :client_assertion_lifetime
 
-    # Configured default nonce lifetime in seconds (300); nonce managers currently use their own TTL.
-    # @return [Integer]
+    # Default stored nonce lifetime in seconds; used when creating nonce managers without an explicit TTL.
+    # @return [Integer] positive lifetime in seconds; defaults to 300
     attr_accessor :dpop_nonce_lifetime
 
-    # Reserved encryption setting; serializers currently create their own service.
-    # @return [Object, nil]
-    attr_accessor :encryption
-
     # Transport used for discovery, PAR and token requests; initially `nil`.
     # @return [#get, #post, nil]
     attr_accessor :http_client
@@ -91,6 +87,10 @@ module AuthProto
     # @return [Logger]
     attr_accessor :logger
 
+    # Lifetime of pending authorization attempts in seconds; defaults to 900 (15 minutes).
+    # @return [Integer] positive lifetime in seconds
+    attr_accessor :pending_session_ttl
+
     # Storage backend; defaults to a new {Storage::Memory}.
     # @return [Storage::Interface]
     attr_accessor :storage
@@ -98,30 +98,51 @@ module AuthProto
     # Creates default settings with in-memory storage and no HTTP transport.
     #
     def initialize
-      @default_token_lifetime = 300 # 5 minutes in seconds
-      @dpop_nonce_lifetime = 300 # 5 minutes in seconds
-      @encryption = nil
+      @client_assertion_lifetime = 300  # 5 minutes
+      @dpop_nonce_lifetime = 300        # 5 minutes
+      @pending_session_ttl = 900        # 15 minutes
       @http_client = nil
       @logger = Logger.new($stdout)
       @storage = AuthProto::Storage::Memory.new
     end
 
-    # Checks that storage implements the interface and the transport supports GET/POST.
+    # Checks storage and transport interfaces and positive assertion, nonce and pending session lifetimes.
     #
     # A `nil` HTTP client is accepted, but cannot perform OAuth or discovery requests.
     #
     # @return [true] if validation succeeds
-    # @raise [ConfigurationError] if storage is absent/invalid or transport methods are missing
+    # @raise [ConfigurationError] if storage, HTTP transport or lifetime settings are invalid
     #
     def validate
       validate_storage
       validate_http_client
+      validate_client_assertion_lifetime
+      validate_dpop_nonce_lifetime
+      validate_pending_session_ttl
       true
     end
 
 
     private
 
+    def validate_client_assertion_lifetime
+      return if @client_assertion_lifetime.is_a?(Integer) && @client_assertion_lifetime.positive?
+
+      raise ConfigurationError, "Client assertion lifetime must be a positive integer"
+    end
+
+    def validate_dpop_nonce_lifetime
+      return if @dpop_nonce_lifetime.is_a?(Integer) && @dpop_nonce_lifetime.positive?
+
+      raise ConfigurationError, "DPoP nonce lifetime must be a positive integer"
+    end
+
+    def validate_pending_session_ttl
+      return if @pending_session_ttl.is_a?(Integer) && @pending_session_ttl.positive?
+
+      raise ConfigurationError, "Pending session TTL must be a positive integer"
+    end
+
     def validate_storage
       raise ConfigurationError, "Storage must be configured" if @storage.nil?
       return if @storage.is_a?(AuthProto::Storage::Interface)