authproto 0.3.0.beta2 → 0.3.0.beta3

data/lib/authproto/par/client.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'uri'
 
 require_relative '../configuration'
+require_relative '../http_helpers'
 require_relative '../par'
 require_relative 'response'
 
@@ -37,7 +38,8 @@ module AuthProto
     #     config.scope = 'atproto'
     #   end
     #
-    #   response = client.submit(request)
+    #   session = AuthProto::State::Session.new(client_id: client_id, scope: 'atproto')
+    #   response = client.submit(request, session: session)
     #
     #   # Build authorization URL using response
     #   auth_url = client.build_authorization_url(
@@ -57,6 +59,7 @@ module AuthProto
     #
 
     class Client
+      include HTTPHelpers
 
       # Authorization server supplying endpoints and the client assertion audience.
       # @return [Metadata::AuthorizationServer]
@@ -79,54 +82,31 @@ module AuthProto
         @authorization_server = authorization_server
         @par_endpoint = authorization_server.pushed_authorization_request_endpoint
         @dpop_client = dpop_client
-        @nonce_manager = dpop_client.nonce_manager
       end
 
       # Submits a PAR request, handling DPoP nonce requirements
       #
       # @param request [Request] The request to submit
+      # @param session [State::Session] session whose key signs PAR and any retries
       # @return [Response] The PAR response
       # @raise [Error] if request fails
       #
-      def submit(request)
+      def submit(request, session:)
         raise Error, "Expected a PAR::Request" unless request.is_a?(PAR::Request)
 
-        # Try the initial request
-        response = make_request(request)
-
-        return process_response(response) if response[:status] == 201
-
-        # Handle DPoP nonce requirement
-        if requires_nonce?(response)
-          nonce = extract_nonce(response)
-          store_nonce(nonce)
-
-          # Get stored nonce to verify
-          @nonce_manager.get(server_origin)
-
-          # Generate new proof with nonce and retry
-          response = make_request(request)
-          return process_response(response) if response[:status] == 201
+        response = dpop_client.with_nonce_handling(session, @par_endpoint) do
+          make_request(request, session: session)
         end
 
-        handle_error_response(response)
+        if response[:status] == 201
+          handle_success_response(response)
+        else
+          handle_error_response(response)
+        end
       rescue StandardError => e
         raise Error, "PAR request failed: #{e.message}"
       end
 
-      # Reads a nonce from a transport response hash.
-      #
-      # @param response [Hash{Symbol => Object}] response containing a `:headers` hash with a `DPoP-Nonce` header
-      # @return [String] server-provided nonce
-      # @raise [Error] if no supported nonce header is present
-      #
-      def extract_nonce(response)
-        nonce = response[:headers].find { |k, v| k.downcase == 'dpop-nonce' }&.last
-        raise Error, "No DPoP nonce provided in response" unless nonce
-
-        nonce
-      end
-
       # Builds the browser URL using the client ID and returned PAR request URI.
       #
       # Retains existing query parameters.
@@ -155,48 +135,19 @@ module AuthProto
 
       private
 
-      def make_request(request)
-        # Generate DPoP proof for this request
-        proof = dpop_client.generate_proof(
-          method: 'POST',
-          uri: @par_endpoint,
-          nonce: @nonce_manager.get(server_origin)
-        )
-
-        # Build headers including DPoP proof
-        headers = build_headers(request, proof)
+      def make_request(request, session:)
+        dpop_proof = dpop_client.generate_proof(session: session, method: 'POST', uri: @par_endpoint)
 
-        # Make the request
         AuthProto.configuration.http_client.post(
           @par_endpoint,
           body: request.to_form(audience: @authorization_server.issuer),
-          headers: headers
+          headers: {
+            "Content-Type" => "application/x-www-form-urlencoded",
+            "DPoP" => dpop_proof
+          }
         )
       end
 
-      def build_headers(request, dpop_proof)
-        {
-          "Content-Type" => "application/x-www-form-urlencoded",
-          "DPoP" => dpop_proof
-        }
-      end
-
-      def requires_nonce?(response)
-        body = JSON.parse(response[:body])
-        body['error'] == DPoP::ERROR_USE_NONCE
-      rescue JSON::ParserError
-        false
-      end
-
-      def store_nonce(nonce)
-        @nonce_manager.update(nonce: nonce, server_url: server_origin)
-      end
-
-      def server_origin
-        uri = URI(@par_endpoint)
-        "#{uri.scheme}://#{uri.host}#{":#{uri.port}" if uri.port != uri.default_port}"
-      end
-
       def handle_error_response(response)
         begin
           error_data = JSON.parse(response[:body])
@@ -208,12 +159,10 @@ module AuthProto
         raise Error, "PAR request failed: #{error_message} (status: #{response[:status]})"
       end
 
-      def process_response(response)
-        raise Error, "unexpected response status: #{response[:status]}" unless response[:status] == 201
-
-        content_type = (response[:headers] || {}).find { |key, _| key.downcase == 'content-type' }&.last
+      def handle_success_response(response)
+        content_type = response_header(response, 'Content-Type', strip_parameters: true)
 
-        unless content_type.to_s.split(';', 2).first.to_s.strip.casecmp?('application/json')
+        unless content_type.to_s.casecmp?('application/json')
           raise Error, "PAR response must use application/json"
         end
 

data/lib/authproto/par/client_assertion.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
-require 'jwt'
 require 'jose'
+require 'jwt'
 require 'securerandom'
 
+require_relative '../configuration'
 require_relative '../errors'
 
 module AuthProto
@@ -20,6 +21,12 @@ module AuthProto
       # Raised when client assertion key import or JWT signing fails.
       class Error < AuthProto::Error; end
 
+      # JWS signing algorithm used for client assertions.
+      # @return [String]
+      ALGORITHM = "ES256"
+
+      # Validated private EC P-256 key used by this reusable assertion signer.
+      # @return [JOSE::JWK]
       attr_reader :signing_key
 
       # Creates an ES256 client assertion signer.
@@ -27,9 +34,15 @@ module AuthProto
       # @param client_id [String] client ID used in `iss` and `sub`
       # @param signing_key [Hash, JOSE::JWK] private EC P-256 signing key, including its `kid`
       # @raise [Error] if the key cannot sign with ES256 or its usage is incompatible
+      #   (`key_ops`, when present, must contain `sign` and optionally `verify`, without duplicates)
+      # @raise [Error] if the client ID is not a nonblank string
       #
       def initialize(client_id:, signing_key:)
-        @client_id = client_id
+        unless client_id.is_a?(String) && !client_id.strip.empty?
+          raise Error, "client_id must be a nonblank string"
+        end
+
+        @client_id = client_id.dup.freeze
         @signing_key = validate_signing_key(signing_key)
       rescue ClientAssertion::Error
         raise
@@ -37,16 +50,24 @@ module AuthProto
         raise Error, "Invalid signing_key: #{e.message}"
       end
 
-      # Signs a short-lived client authentication JWT with ES256.
+      # Signs a fresh, short-lived client authentication JWT with the cached ES256 key.
       #
       # Includes `iss`, `sub`, `aud`, a unique `jti`, and `iat`/`exp` times.
       #
       # @param audience [String] authorization server issuer URL used as the assertion audience
-      # @param lifetime [Integer] validity in seconds; defaults to five minutes
+      # @param lifetime [Integer] positive validity in seconds; defaults to {Configuration#client_assertion_lifetime}
       # @return [String] compact signed client assertion JWT
-      # @raise [Error] if JWK import or JWT signing fails
+      # @raise [Error] if the audience is not a nonblank string, lifetime is not a positive integer, or signing fails
       #
-      def generate_jwt(audience:, lifetime: 300)
+      def generate_jwt(audience:, lifetime: AuthProto.configuration.client_assertion_lifetime)
+        unless audience.is_a?(String) && !audience.strip.empty?
+          raise Error, "audience must be a nonblank string"
+        end
+
+        unless lifetime.is_a?(Integer) && lifetime.positive?
+          raise Error, "lifetime must be a positive integer"
+        end
+
         now = Time.now.to_i
 
         payload = {
@@ -59,13 +80,12 @@ module AuthProto
         }
 
         header = {
-          alg: 'ES256',
+          alg: ALGORITHM,
           typ: 'JWT',
           kid: @signing_key.fields['kid']
         }
 
-        key = JWT::JWK.import(@signing_key.to_map.to_h)
-        JWT.encode(payload, key, 'ES256', header)
+        JWT.encode(payload, @jwt_signing_key, ALGORITHM, header)
       rescue JWT::Error, ArgumentError => e
         raise Error, "Failed to generate client assertion: #{e.message}"
       end
@@ -93,17 +113,28 @@ module AuthProto
           end
         end
 
-        if (data.key?('alg') && data['alg'] != 'ES256') ||
-           (data.key?('use') && data['use'] != 'sig') ||
-           (data.key?('key_ops') && (!data['key_ops'].is_a?(Array) || !data['key_ops'].include?('sign')))
-          raise Error, "signing_key must be active and permit ES256 signing"
+        if (data.key?('alg') && data['alg'] != ALGORITHM) ||
+           (data.key?('use') && data['use'] != 'sig')
+          raise Error, "signing_key must be active and permit #{ALGORITHM} signing"
+        end
+
+        if data.key?('key_ops')
+          raise Error, "signing_key.key_ops is not an array" unless data['key_ops'].is_a?(Array)
+
+          ops = data['key_ops'].sort_by(&:to_s)
+
+          unless ops == ['sign'] || ops == ['sign', 'verify']
+            raise Error, "signing_key.key_ops must contain sign and optionally verify, without duplicates"
+          end
         end
 
         signing_key = JOSE::JWK.from_map(data)
 
-        imported = JWT::JWK.import(data)
-        proof = JWT.encode({}, imported, 'ES256')
-        JWT.decode(proof, imported.public_key, true, algorithms: ['ES256'])
+        imported_key = JWT::JWK.import(data)
+        proof = JWT.encode({}, imported_key, ALGORITHM)
+        JWT.decode(proof, imported_key.public_key, true, algorithms: [ALGORITHM])
+
+        @jwt_signing_key = imported_key
 
         signing_key
       end

data/lib/authproto/par/request.rb

@@ -41,7 +41,7 @@ module AuthProto
         # @return [String]
         attr_reader :scope
 
-        # Account handle to prefill at the authorization server.
+        # Account handle or DID to prefill at the authorization server.
         # @return [String, nil]
         attr_reader :login_hint
 
@@ -49,17 +49,13 @@ module AuthProto
         # @return [String, nil]
         attr_reader :nonce
 
-        # Optional proof value retained on the request; {Client#submit} generates its own HTTP proof.
-        # @return [String, nil]
-        attr_reader :dpop_proof
-
         # Client authentication signer; a fresh JWT is generated for each form encoding.
         # @return [ClientAssertion, nil]
         attr_reader :client_assertion
       end
 
       #
-      # A draft PAR request with writable fields, configured inside the block passed to {Request.build}).
+      # A draft PAR request with writable fields, configured inside the block passed to {Request.build}.
       #
 
       class Configuration
@@ -77,7 +73,7 @@ module AuthProto
       # @yieldparam config [Configuration] mutable request settings
       # @yieldreturn [Object] ignored
       # @return [Request] validated pushed authorization request
-      # @raise [Error] if required parameters, PKCE, scope or client authentication are invalid
+      # @raise [Error] if required parameters are missing, `atproto` scope is absent or the signer has an invalid type
       #
       def self.build
         config = Configuration.new
@@ -88,7 +84,7 @@ module AuthProto
       # Copies and validates a PAR parameter configuration.
       #
       # @param config [Configuration] populated request settings
-      # @raise [Error] if required values are missing or authentication/PKCE/scope values are invalid
+      # @raise [Error] if required values are missing, `atproto` scope is absent or the signer has an invalid type
       #
       def initialize(config)
         Fields.instance_methods(false).each do |field|

data/lib/authproto/par.rb

@@ -27,7 +27,8 @@ module AuthProto
   #     config.scope = 'atproto'
   #   end
   #
-  #   response = par.submit(request)
+  #   session = AuthProto::State::Session.new(client_id: client_id, scope: 'atproto')
+  #   response = par.submit(request, session: session)
   #   auth_url = par.build_authorization_url(
   #     request_uri: response.request_uri,
   #     client_id: request.client_id

data/lib/authproto/serialization/session.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 require_relative '../metadata/authorization_server'
 require_relative '../state/session'
 require_relative 'base'
@@ -29,10 +31,10 @@ module AuthProto
       end
 
       def serialize_data(obj)
-        {
+        data = {
           session_id: obj.session_id,
-          state_token: obj.state_token,
           client_id: obj.client_id,
+          dpop_key: obj.dpop_key.private_jwk,
           scope: obj.scope,
           pkce_verifier: obj.pkce_verifier,
           pkce_challenge: obj.pkce_challenge,
@@ -40,24 +42,40 @@ module AuthProto
           tokens: serialize_token_set(obj.tokens),
           auth_server: serialize_auth_server(obj.auth_server)
         }
+
+        data[:state_token] = obj.state_token if obj.state_token
+        data[:signing_key_id] = obj.signing_key_id if obj.signing_key_id
+        data[:signing_key_thumbprint] = obj.signing_key_thumbprint if obj.signing_key_thumbprint
+        data[:authorization_expires_at] = obj.authorization_expires_at.utc.iso8601(9) if obj.authorization_expires_at
+        data
       end
 
       def deserialize_data(data)
-        AuthProto::State::Session.new(
+        unless data['dpop_key'].is_a?(Hash)
+          raise ValidationError, "Session is missing its private DPoP key; authorize again"
+        end
+
+        session = AuthProto::State::Session.new(
           client_id: data['client_id'],
+          dpop_key: AuthProto::DPoP::KeySet.from_jwk(data.fetch('dpop_key')),
           scope: data['scope'],
           did: data['did'],
+          signing_key_id: data['signing_key_id'],
+          signing_key_thumbprint: data['signing_key_thumbprint'],
+          authorization_expires_at: data['authorization_expires_at'] && Time.iso8601(data['authorization_expires_at']),
           auth_server: deserialize_auth_server(data['auth_server'])
-        ).tap do |session|
-          # Set readonly attributes
-          session.instance_variable_set(:@session_id, data['session_id'])
-          session.instance_variable_set(:@state_token, data['state_token'])
-          session.instance_variable_set(:@pkce_verifier, data['pkce_verifier'])
-          session.instance_variable_set(:@pkce_challenge, data['pkce_challenge'])
-
-          # Set tokens if present
-          session.tokens = deserialize_token_set(data['tokens']) if data['tokens']
-        end
+        )
+
+        # Set readonly attributes
+        session.instance_variable_set(:@session_id, data['session_id'])
+        session.instance_variable_set(:@state_token, data['state_token'])
+        session.instance_variable_set(:@pkce_verifier, data['pkce_verifier'])
+        session.instance_variable_set(:@pkce_challenge, data['pkce_challenge'])
+
+        # Set tokens if present
+        session.tokens = deserialize_token_set(data['tokens']) if data['tokens']
+
+        session
       end
 
       def serialize_token_set(tokens)

data/lib/authproto/serialization/token_set.rb

@@ -32,7 +32,6 @@ module AuthProto
         {
           access_token: obj.access_token,
           refresh_token: obj.refresh_token,
-          token_type: obj.token_type,
           expires_at: obj.expires_at.utc.iso8601,
           scope: obj.scope,
           sub: obj.sub
@@ -43,7 +42,7 @@ module AuthProto
         AuthProto::State::TokenSet.new(
           access_token: data['access_token'],
           refresh_token: data['refresh_token'],
-          token_type: data['token_type'],
+          token_type: 'DPoP',
           expires_in: (Time.parse(data['expires_at']) - Time.now).to_i,
           scope: data['scope'],
           sub: data['sub']

data/lib/authproto/state/session.rb

@@ -3,6 +3,7 @@
 require 'monitor'
 require 'securerandom'
 
+require_relative '../dpop/key_set'
 require_relative '../pkce'
 require_relative '../state'
 
@@ -20,14 +21,30 @@ module AuthProto
       # @return [String]
       attr_reader :session_id
 
-      # Random OAuth state token for callback validation.
-      # @return [String]
+      # Random OAuth state token for callback validation, cleared after authorization completes.
+      # @return [String, nil]
       attr_reader :state_token
 
+      # Deadline for completing pending authorization, cleared after authorization completes.
+      # @return [Time, nil]
+      attr_reader :authorization_expires_at
+
       # OAuth client identifier.
       # @return [String]
       attr_reader :client_id
 
+      # Client-authentication key ID, or nil for public clients.
+      # @return [String, nil]
+      attr_reader :signing_key_id
+
+      # RFC 7638 SHA-256 thumbprint of the client-authentication public key.
+      # @return [String, nil]
+      attr_reader :signing_key_thumbprint
+
+      # Private DPoP key belonging to this authorization session.
+      # @return [DPoP::KeySet]
+      attr_reader :dpop_key
+
       # Space-separated requested scopes.
       # @return [String]
       attr_reader :scope
@@ -58,17 +75,39 @@ module AuthProto
       # @param scope [String] requested space-separated scopes
       # @param auth_server [Metadata::AuthorizationServer, nil] pre-resolved authorization server
       # @param did [String, nil] pre-resolved account DID
+      # @param signing_key_id [String, nil] client-authentication key ID selected before PAR
+      # @param signing_key_thumbprint [String, nil] RFC 7638 SHA-256 thumbprint of that key
+      # @param dpop_key [DPoP::KeySet] session key; a fresh key is generated for new sessions by default
+      # @param authorization_expires_at [Time, nil] deadline for completing pending authorization
+      # @raise [ArgumentError] if the signing key ID, thumbprint or DPoP key is invalid
+      # @raise [DPoP::KeySet::KeyError] if DPoP key generation fails
       # @raise [PKCE::Error] if PKCE generation fails
       #
-      def initialize(client_id:, scope:, auth_server: nil, did: nil)
+      def initialize(client_id:, scope:, auth_server: nil, did: nil, signing_key_id: nil, signing_key_thumbprint: nil,
+                     dpop_key: DPoP::KeySet.new, authorization_expires_at: nil)
         super() # Initialize MonitorMixin
 
-        @session_id = SecureRandom.uuid
-        @state_token = SecureRandom.urlsafe_base64(32)
+        unless signing_key_id.nil? || (signing_key_id.is_a?(String) && !signing_key_id.empty?)
+          raise ArgumentError, "signing_key_id must be a nonempty string or nil"
+        end
+
+        unless signing_key_thumbprint.nil? || (signing_key_thumbprint.is_a?(String) && !signing_key_thumbprint.empty?)
+          raise ArgumentError, "signing_key_thumbprint must be a nonempty string or nil"
+        end
+
+        raise ArgumentError, "dpop_key must be a DPoP::KeySet" unless dpop_key.is_a?(DPoP::KeySet)
+
+        @dpop_key = dpop_key
         @client_id = client_id
+        @signing_key_id = signing_key_id&.dup&.freeze
+        @signing_key_thumbprint = signing_key_thumbprint&.dup&.freeze
         @scope = scope
         @auth_server = auth_server
         @did = did
+        @authorization_expires_at = authorization_expires_at
+
+        @session_id = SecureRandom.uuid
+        @state_token = SecureRandom.urlsafe_base64(32)
 
         pkce = PKCE.new
         @pkce_verifier = pkce.verifier
@@ -77,6 +116,17 @@ module AuthProto
         @tokens = nil
       end
 
+      # Clears the OAuth state token and pending authorization deadline after successful authorization.
+      #
+      # @return [nil]
+      #
+      def clear_state_token
+        synchronize do
+          @state_token = nil
+          @authorization_expires_at = nil
+        end
+      end
+
       # Binds this session to an authorization server.
       #
       # @param server [Metadata::AuthorizationServer] resolved authorization server
@@ -144,14 +194,24 @@ module AuthProto
         end
       end
 
+      # Returns true if this session has not completed authorization yet and doesn't contain tokens.
+      # @return [Boolean]
+      def pending?
+        synchronize do
+          @tokens.nil?
+        end
+      end
+
       # Whether this session has valid access tokens
       # @return [Boolean]
-      def authorized?
+      def tokens_valid?
         synchronize do
           !@tokens.nil? && !@tokens.expired?
         end
       end
 
+      alias authorized? tokens_valid?
+
       # Whether this session can refresh its tokens
       # @return [Boolean]
       def renewable?