authproto 0.3.0.beta2 → 0.3.0.beta3

data/lib/authproto/dpop/client.rb

@@ -1,84 +1,71 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'uri'
 
 require_relative '../errors'
-require_relative 'key_manager'
+require_relative '../http_helpers'
 require_relative 'nonce_manager'
 require_relative 'proof_generator'
 
 module AuthProto
 
   #
-  # Key management, per-request proofs and server-origin nonces for DPoP authentication.
+  # Shared proof generation and server-origin nonces for DPoP authentication.
   #
 
   module DPoP
 
-    ERROR_USE_NONCE = "use_dpop_nonce"
-
-    # High-level client for managing DPoP operations. Integrates key management,
-    # proof generation, and nonce tracking to provide a complete DPoP client
-    # implementation according to RFC 9449.
     #
-    # This client handles:
-    # - Key management for signing proofs
-    # - Proof generation for HTTP requests
-    # - Nonce tracking across servers
-    # - Header construction for requests
-    # - Response processing for nonce updates
+    # Shared DPoP client using session-owned signing keys and nonces scoped to
+    # each session and server origin. Generates RFC 9449 proofs, processes nonce
+    # updates, and detects nonce challenges. Response processing requires a nonce
+    # on every DPoP response, as required by the AT Protocol OAuth profile.
     #
 
     class Client
+      include HTTPHelpers
 
       # Error raised for DPoP client operations
       class Error < AuthProto::Error; end
 
-      # Key manager used to sign proofs.
-      # @return [KeyManager]
-      attr_reader :key_manager
-
       # Generator for per-request DPoP JWTs.
       # @return [ProofGenerator]
       attr_reader :proof_generator
 
-      # Persistent nonce store, indexed by server origin.
+      # Persistent nonce store, indexed by session and server origin.
       # @return [NonceManager]
       attr_reader :nonce_manager
 
-      # Creates DPoP signing, proof and nonce managers.
+      # Creates a shared proof generator and nonce storage scoped to sessions and server origins.
       #
-      # @param key_manager [KeyManager, nil] existing key manager, or `nil` to generate a keypair
-      # @param nonce_ttl [Integer, nil] stored nonce lifetime in seconds, or the nonce manager's default
-      # @raise [KeyManager::KeyError] if key generation fails
-      # @raise [ProofGenerator::ProofError] if the key manager is invalid
+      # @param nonce_ttl [Integer, nil] stored nonce lifetime in seconds; `nil` uses {Configuration#dpop_nonce_lifetime}
       # @raise [ArgumentError] if the encryption master key is not valid Base64
       #
-      def initialize(key_manager: nil, nonce_ttl: nil)
-        @key_manager = key_manager || KeyManager.new
+      def initialize(nonce_ttl: nil)
         @nonce_manager = NonceManager.new(ttl: nonce_ttl)
-        @proof_generator = ProofGenerator.new(@key_manager)
+        @proof_generator = ProofGenerator.new
       end
 
-      # Generates a fresh DPoP proof using a supplied or stored nonce for the origin.
+      # Generates a fresh DPoP proof using the stored nonce for the session and origin, if available.
       #
+      # @param session [State::Session] session whose DPoP key signs the request
       # @param method [String] HTTP method, converted to uppercase
-      # @param uri [String] absolute HTTP(S) URL; callers should omit the query and fragment
+      # @param uri [String] absolute HTTP(S) request URL; query and fragment are omitted from the signed `htu`
       # @param access_token [String, nil] token to bind with an `ath` claim
-      # @param nonce [String, nil] explicit nonce; `nil` looks up the origin's stored nonce
       # @return [JOSE::SignedBinary] compact signed DPoP JWT
       # @raise [Error] if URI parsing, nonce lookup or signing fails
       #
-      def generate_proof(method:, uri:, access_token: nil, nonce: nil)
+      def generate_proof(session:, method:, uri:, access_token: nil)
         parsed_uri = URI(uri)
 
         server_url = "#{parsed_uri.scheme}://#{parsed_uri.host}"
         server_url += ":#{parsed_uri.port}" if parsed_uri.port != parsed_uri.default_port
 
-        # Use provided nonce or get one from the manager
-        nonce ||= @nonce_manager.get(server_url)
+        nonce = @nonce_manager.get(server_url: server_url, session_id: session.session_id)
 
         @proof_generator.generate(
+          key_set: session.dpop_key,
           method: method,
           uri: uri,
           nonce: nonce,
@@ -89,25 +76,103 @@ module AuthProto
       end
 
       # Stores a `DPoP-Nonce` response header for future requests to the same origin.
-      # Header names are compared case-insensitively. Missing headers/nonces are ignored.
+      # Call after every DPoP HTTP attempt, before accepting a result or deciding to retry.
+      # Header names are case-insensitive; missing, malformed and duplicate nonces are rejected.
       #
-      # @param response_headers [Hash{String => String}, nil] response headers, or `nil`
+      # @param session_id [String] session that made the request
+      # @param response [Hash{Symbol => Object}] HTTP response with `:status`, `:headers`, and `:body`
       # @param server_url [String] request URL whose origin owns the nonce
       # @return [void]
       # @raise [Error] if nonce validation or persistence fails
       #
-      def process_response(response_headers, server_url)
-        return unless response_headers
+      def process_response(response, server_url:, session_id:)
+        raise Error, "Expected a response hash" unless response.is_a?(Hash)
+
+        response_headers = response[:headers]
+        raise Error, "Missing or invalid response headers" unless response_headers.is_a?(Hash)
 
-        # Look for DPoP-Nonce header (case insensitive)
-        nonce = response_headers.find { |k, v| k.downcase == 'dpop-nonce' }&.last
-        return unless nonce
+        if response_headers.keys.count { |name| name.casecmp?('DPoP-Nonce') } > 1
+          raise Error, "Multiple DPoP-Nonce headers"
+        end
+
+        nonce = response_header(response, 'DPoP-Nonce')
+
+        if nonce.nil? || nonce == ''
+          raise Error, "Missing DPoP-Nonce header"
+        end
 
         # Store new nonce for future requests
-        @nonce_manager.update(nonce: nonce, server_url: server_url)
+        @nonce_manager.update(nonce: nonce, server_url: server_url, session_id: session_id)
       rescue StandardError => e
         raise Error, "Failed to process response: #{e.message}"
       end
+
+      # Detects a nonce challenge without treating other errors as nonce challenges.
+      #
+      # Recognizes HTTP 400 JSON errors and an HTTP 401 DPoP authentication
+      # challenge. Header/parameter names and the scheme are case-insensitive;
+      # error values are case-sensitive. Multiple DPoP challenges are treated as ambiguous.
+      #
+      # @param response [Hash{Symbol => Object}] HTTP response with status, headers and body
+      # @return [Boolean] whether the response requests a retry with a server nonce
+      # @raise [Error] if the response or its headers have an invalid type
+      #
+      def has_nonce_error?(response)
+        raise Error, "Expected a response hash" unless response.is_a?(Hash)
+
+        headers = response[:headers]
+        raise Error, "Missing or invalid response headers" unless headers.is_a?(Hash)
+
+        case response[:status]
+        when 400
+          return false unless response[:body].is_a?(String)
+
+          begin
+            data = JSON.parse(response[:body])
+            data.is_a?(Hash) && data['error'] == DPoP::ERROR_USE_NONCE
+          rescue JSON::ParserError
+            false
+          end
+        when 401
+          challenge = response_header(response, 'WWW-Authenticate')
+          nonce_challenge?(challenge)
+        else
+          false
+        end
+      end
+
+      # Runs a DPoP request and retries once if the server requests a new nonce.
+      # Processes every response before returning it or invoking the block again.
+      # The block must build a fresh proof and send the request on each invocation;
+      # the initial proof may already include a cached nonce.
+      #
+      # @param session [State::Session] session making the request
+      # @param url [String] request URL whose origin owns the nonce
+      # @yield sends one HTTP request using a fresh DPoP proof
+      # @yieldreturn [Hash{Symbol => Object}] HTTP response with status, headers and body
+      # @return [Hash{Symbol => Object}] final response, including any remaining error
+      # @raise [Error] if a response lacks a valid nonce or nonce persistence fails
+      #
+      def with_nonce_handling(session, url)
+        response = yield
+
+        process_response(response, server_url: url, session_id: session.session_id)
+
+        if has_nonce_error?(response)
+          response = yield
+
+          process_response(response, server_url: url, session_id: session.session_id)
+        end
+
+        response
+      end
+
+
+      private
+
+      def nonce_challenge?(challenge)
+        authentication_challenge(challenge, scheme: 'DPoP')&.fetch('error', nil) == DPoP::ERROR_USE_NONCE
+      end
     end
   end
 end

data/lib/authproto/dpop/{key_manager.rb → key_set.rb}

@@ -1,22 +1,21 @@
 # frozen_string_literal: true
 
-require 'base64'
 require 'jose'
 require 'json'
-require 'openssl'
 
+require_relative '../dpop'
 require_relative '../errors'
 
 module AuthProto
   module DPoP
 
     #
-    # Manages ES256 keypair generation and storage for DPoP proofs.
-    # Provides functionality to generate new keys and store them securely.
+    # Holds an ES256 signing keypair and imports/exports JWKs for DPoP proofs.
+    # Keys are held in memory; the session serializer handles encrypted persistence.
     # Uses JOSE for cryptographic operations and key format handling.
     #
 
-    class KeyManager
+    class KeySet
 
       # Error raised when key operations fail
       class KeyError < AuthProto::Error; end
@@ -25,78 +24,31 @@ module AuthProto
       # @return [String]
       CURVE = "P-256"
 
-      # JWS signing algorithm used for DPoP proofs.
-      # @return [String]
-      ALGORITHM = "ES256"
-
       # Private EC P-256 keypair used for signing.
       # @return [JOSE::JWK]
-      attr_reader :keypair
+      attr_reader :key
 
-      # Creates a new KeyManager instance with an optional existing keypair
+      # Creates a new KeySet instance with an optional existing keypair
       #
-      # @param keypair [JOSE::JWK, nil] Optional existing keypair to use
-      # @raise [KeyError] if the provided keypair is invalid
+      # @param key [JOSE::JWK, nil] Optional existing keypair to use
+      # @raise [KeyError] if the provided key is invalid
       #
-      def initialize(keypair = nil)
-        @keypair = keypair || generate_keypair
+      def initialize(key = nil)
+        @key = key || generate_keypair
         validate_keypair
       end
 
-      # Generates a new ES256 keypair for DPoP usage
-      #
-      # @return [JOSE::JWK] The newly generated keypair
-      # @raise [KeyError] if key generation fails
-      #
-      def generate_keypair
-        # Generate base keypair
-        base_key = JOSE::JWK.generate_key([:ec, CURVE])
-        base_map = base_key.to_map
-
-        # Create new map with all required properties
-        key_map = {
-          'kty' => base_map['kty'],
-          'crv' => base_map['crv'],
-          'x' => base_map['x'],
-          'y' => base_map['y'],
-          'd' => base_map['d'],
-          'use' => 'sig',
-          'kid' => generate_kid(base_map)
-        }
-
-        # Create new JWK with all properties
-        JOSE::JWK.from_map(key_map)
-      rescue StandardError => e
-        raise KeyError, "Failed to generate keypair: #{e.message}"
-      end
-
-      # Exports the public key with `use: sig` and a key ID.
+      # Exports the public key for embedding in a DPoP proof.
       #
       # @return [Hash{String => Object}] public JWK without private key material
       # @raise [KeyError] if public-key export fails
       #
       def public_jwk
-        jwk = @keypair.to_public.to_map.to_h
-        # If somehow the properties aren't set, add them
-        jwk['use'] ||= 'sig'
-        jwk['kid'] ||= generate_kid(jwk)
-        jwk
+        @key.to_public_map.to_h
       rescue StandardError => e
         raise KeyError, "Failed to export public key: #{e.message}"
       end
 
-      # Signs bytes with this keypair and returns a compact JWS.
-      #
-      # @param data [String] payload bytes to sign
-      # @return [JOSE::SignedBinary] compact JWS (a string subclass)
-      # @raise [KeyError] if signing fails
-      #
-      def sign(data)
-        @keypair.sign(data).compact
-      rescue StandardError => e
-        raise KeyError, "Failed to sign data: #{e.message}"
-      end
-
       # Signs a JSON payload with the supplied protected JWS header and ES256.
       # Hash keys are recursively converted to strings. The algorithm is forced to `ES256`.
       #
@@ -111,7 +63,7 @@ module AuthProto
         payload = deep_stringify_keys(payload)
 
         # Configure JOSE to use ES256 for signing
-        signing_config = { 'alg' => 'ES256' }
+        signing_config = { 'alg' => ALGORITHM }
 
         # Merge our header with JOSE's required fields
         full_header = header.merge(signing_config)
@@ -120,7 +72,7 @@ module AuthProto
         payload_json = JSON.generate(payload)
 
         # Create the JWS with our header and payload
-        jws = @keypair.sign(payload_json, full_header)
+        jws = @key.sign(payload_json, full_header)
 
         # Get the compact serialization
         jws.compact
@@ -128,46 +80,13 @@ module AuthProto
         raise KeyError, "Failed to sign segments: #{e.message}"
       end
 
-      # Copies hashes and arrays recursively, converting hash keys to strings.
-      #
-      # @param obj [Object] input structure or scalar value
-      # @return [Object] transformed hash/array, or the original scalar
-      #
-      def deep_stringify_keys(obj)
-        case obj
-        when Hash
-          obj.each_with_object({}) do |(k, v), hash|
-            hash[k.to_s] = deep_stringify_keys(v)
-          end
-        when Array
-          obj.map { |v| deep_stringify_keys(v) }
-        else
-          obj
-        end
-      end
-
-      # Verifies a compact JWS using this keypair.
-      #
-      # @param signed_jws [String, JOSE::SignedBinary] complete signed JWS
-      # @return [Boolean] whether the signature is valid
-      # @raise [KeyError] if decoding or verification raises an error
-      #
-      def verify(signed_jws)
-        verified, payload, = @keypair.verify(signed_jws)
-        verified
-      rescue StandardError => e
-        raise KeyError, "Failed to verify signature: #{e.message}"
-      end
-
-      # Exports this keypair as a JOSE map.
+      # Exports this keypair including its private signing material.
       #
-      # @param include_private [Boolean] include secret `d` key material when `true`
-      # @return [JOSE::Map] JWK fields; call `to_h` for a Ruby hash
+      # @return [Hash{String => Object}] private JWK including the secret `d` component
       # @raise [KeyError] if export fails
       #
-      def to_jwk(include_private: false)
-        key = include_private ? @keypair : @keypair.to_public
-        key.to_map
+      def private_jwk
+        @key.to_map.to_h
       rescue StandardError => e
         raise KeyError, "Failed to export key: #{e.message}"
       end
@@ -175,40 +94,55 @@ module AuthProto
       # Imports an EC P-256 JWK and validates that it can sign and verify.
       #
       # @param jwk [Hash{String => Object}, JOSE::Map] JWK including private key material
-      # @return [KeyManager] imported key manager
+      # @return [KeySet] imported and validated keypair wrapper
       # @raise [KeyError] if import or key validation fails
       #
       def self.from_jwk(jwk)
-        keypair = JOSE::JWK.from_map(jwk)
-        new(keypair)
+        key = JOSE::JWK.from_map(jwk)
+        new(key)
       rescue StandardError => e
         raise KeyError, "Failed to import key: #{e.message}"
       end
 
+
       private
 
-      def generate_kid(jwk)
-        # Generate a key ID based on the key's components
-        components = [
-          jwk['kty'],
-          jwk['crv'],
-          jwk['x'],
-          jwk['y']
-        ].join(':')
-
-        # Create a SHA-256 hash and take first 8 bytes
-        digest = OpenSSL::Digest::SHA256.digest(components)
-        Base64.urlsafe_encode64(digest[0..7], padding: false)
+      def generate_keypair
+        JOSE::JWK.generate_key([:ec, CURVE])
+      rescue StandardError => e
+        raise KeyError, "Failed to generate keypair: #{e.message}"
+      end
+
+      def sign(data)
+        @key.sign(data, { 'alg' => ALGORITHM }).compact
+      rescue StandardError => e
+        raise KeyError, "Failed to sign data: #{e.message}"
+      end
+
+      def deep_stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), hash|
+            hash[k.to_s] = deep_stringify_keys(v)
+          end
+        when Array
+          obj.map { |v| deep_stringify_keys(v) }
+        else
+          obj
+        end
+      end
+
+      def verify(signed_jws)
+        verified, payload, = @key.verify(signed_jws)
+        verified
+      rescue StandardError => e
+        raise KeyError, "Failed to verify signature: #{e.message}"
       end
 
-      # Validates that the keypair meets DPoP requirements
-      # @raise [KeyError] if validation fails
       def validate_keypair
-        # Check that we have a valid EC key
-        raise KeyError, "Invalid key type: #{@keypair.kty}, must be :ec" unless @keypair.kty.is_a?(JOSE::JWK::KTY_EC)
+        raise KeyError, "Invalid key type: #{@key.kty}, must be :ec" unless @key.kty.is_a?(JOSE::JWK::KTY_EC)
 
-        # Verify the curve
-        curve = @keypair.to_map['crv']
+        curve = @key.to_map['crv']
         raise KeyError, "Invalid curve: #{curve}, must be #{CURVE}" unless curve == CURVE
 
         # Verify we can perform basic operations

data/lib/authproto/dpop/nonce_manager.rb

@@ -14,61 +14,64 @@ module AuthProto
 
     #
     # Manages DPoP nonces provided by servers during the OAuth flow.
-    # Tracks separate nonces for each server using persistent storage.
+    # Tracks separate nonces for each session and server using persistent storage.
     # Thread-safe to handle concurrent requests.
     #
 
     class NonceManager
 
+      # Regexp for checking the nonce value for invalid characters
+      NONCE_REGEXP = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/
+
       # Error for nonce-related issues
       class NonceError < AuthProto::Error; end
 
-      # Default stored nonce lifetime in seconds.
-      # @return [Integer]
-      DEFAULT_TTL = 300 # 5 minutes
-
       # Creates a nonce manager using the global storage backend.
       #
-      # @param ttl [Integer, nil] nonce lifetime in seconds; `nil` uses {DEFAULT_TTL}
+      # @param ttl [Integer, nil] nonce lifetime in seconds; `nil` uses {Configuration#dpop_nonce_lifetime}
       # @raise [ArgumentError] if the master encryption key is not valid Base64
       #
       def initialize(ttl: nil)
-        @ttl = ttl || DEFAULT_TTL
+        @ttl = ttl || AuthProto.configuration.dpop_nonce_lifetime
         @serializer = Serialization::StoredNonce.new
       end
 
-      # Stores a nonce for the URL's origin, replacing any previous value.
+      # Stores a nonce for the session and URL's origin, replacing any previous value.
       #
-      # @param nonce [String] nonempty server-provided nonce
+      # @param nonce [String] server-provided nonce using RFC 9449's `1*NQCHAR` syntax
+      # @param session_id [String] nonempty OAuth session identifier
       # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
       # @return [void]
       # @raise [NonceError] if inputs are invalid or storage reports failure
       # @raise [Storage::StorageError] if backend validation or storage fails
       #
-      def update(nonce:, server_url:)
+      def update(nonce:, server_url:, session_id:)
+        validate_session_id(session_id)
         validate_inputs(nonce, server_url)
         origin = normalize_server_url(server_url)
 
         stored_nonce = StoredNonce.new(nonce, origin)
         serialized = @serializer.serialize(stored_nonce)
 
-        key = Storage::KeyBuilder.nonce_key(origin)
+        key = Storage::KeyBuilder.nonce_key(session_id, origin)
         return if AuthProto.storage.set(key, serialized, ttl: @ttl)
 
         raise NonceError, "Failed to store nonce"
       end
 
-      # Retrieves the current nonce for a URL's origin.
+      # Retrieves the current nonce for a session and URL's origin.
       #
+      # @param session_id [String] nonempty OAuth session identifier
       # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
       # @return [String, nil] stored nonce, or `nil` when missing/expired according to storage TTL
-      # @raise [NonceError] if the URL is invalid or serialized data cannot be read
+      # @raise [NonceError] if the session ID or URL is invalid, or serialized data cannot be read
       # @raise [Storage::StorageError] if storage retrieval fails
       #
-      def get(server_url)
+      def get(server_url:, session_id:)
+        validate_session_id(session_id)
         validate_server_url(server_url)
         origin = normalize_server_url(server_url)
-        key = Storage::KeyBuilder.nonce_key(origin)
+        key = Storage::KeyBuilder.nonce_key(session_id, origin)
 
         stored = AuthProto.storage.get(key)
         return nil unless stored
@@ -81,22 +84,30 @@ module AuthProto
         end
       end
 
-      # Removes the stored nonce for a URL's origin.
+      # Removes the stored nonce for a session and URL's origin.
       #
+      # @param session_id [String] nonempty OAuth session identifier
       # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
       # @return [Boolean] backend deletion status
-      # @raise [NonceError] if the URL is invalid
+      # @raise [NonceError] if the session ID or URL is invalid
       # @raise [Storage::StorageError] if deletion fails
       #
-      def clear(server_url)
+      def clear(server_url:, session_id:)
+        validate_session_id(session_id)
         validate_server_url(server_url)
         origin = normalize_server_url(server_url)
-        key = Storage::KeyBuilder.nonce_key(origin)
+        key = Storage::KeyBuilder.nonce_key(session_id, origin)
         AuthProto.storage.delete(key)
       end
 
       private
 
+      def validate_session_id(session_id)
+        return if session_id.is_a?(String) && !session_id.empty?
+
+        raise NonceError, "session_id must be a nonempty string"
+      end
+
       def normalize_server_url(url)
         uri = URI(url)
         port = uri.port
@@ -109,7 +120,9 @@ module AuthProto
       end
 
       def validate_inputs(nonce, server_url)
-        raise NonceError, "nonce is required" if nonce.nil? || nonce.empty?
+        raise NonceError, "nonce must not be empty" if nonce.to_s == ''
+        raise NonceError, "Invalid DPoP nonce" unless nonce.is_a?(String)
+        raise NonceError, "Invalid characters in the DPoP nonce" unless nonce.ascii_only? && nonce =~ NONCE_REGEXP
 
         validate_server_url(server_url)
       end