authproto 0.3.0.beta1 → 0.3.0.beta2

data/lib/authproto/par/request.rb

@@ -1,116 +1,75 @@
 # frozen_string_literal: true
 
-require 'cgi'
+require 'uri'
 
 require_relative '../par'
+require_relative 'client_assertion'
 
 module AuthProto
   module PAR
 
     #
-    # Represents a pushed authorization request
+    # Represents a pushed authorization request.
     #
 
     class Request
 
       #
-      # Configuration for request parameters
+      # Shared set of fields between {Request} (a read-only, validated request) and {Configuration} (a draft request
+      # with writable fields configured in the block passed to {Request.build}).
       #
 
-      class Configuration
+      module Fields
 
         # OAuth client identifier.
-        # @return [String, nil]
-        attr_accessor :client_id
+        # @return [String]
+        attr_reader :client_id
 
         # Registered OAuth callback URI.
-        # @return [String, nil]
-        attr_accessor :redirect_uri
+        # @return [String]
+        attr_reader :redirect_uri
 
         # S256 PKCE challenge.
-        # @return [String, nil]
-        attr_accessor :code_challenge
-
-        # PKCE method; must be `S256`.
-        # @return [String, nil]
-        attr_accessor :code_challenge_method
+        # @return [String]
+        attr_reader :code_challenge
 
         # Random state token to validate the callback.
-        # @return [String, nil]
-        attr_accessor :state
+        # @return [String]
+        attr_reader :state
 
         # Space-separated scopes including `atproto`.
-        # @return [String, nil]
-        attr_accessor :scope
+        # @return [String]
+        attr_reader :scope
 
         # Account handle to prefill at the authorization server.
         # @return [String, nil]
-        attr_accessor :login_hint
+        attr_reader :login_hint
 
         # Optional authorization nonce parameter.
         # @return [String, nil]
-        attr_accessor :nonce
+        attr_reader :nonce
 
         # Optional proof value retained on the request; {Client#submit} generates its own HTTP proof.
         # @return [String, nil]
-        attr_accessor :dpop_proof
+        attr_reader :dpop_proof
 
-        # JWT bearer assertion type for confidential clients.
-        # @return [String, nil]
-        attr_accessor :client_assertion_type
-
-        # Signed client authentication JWT for confidential clients.
-        # @return [String, nil]
-        attr_accessor :client_assertion
+        # Client authentication signer; a fresh JWT is generated for each form encoding.
+        # @return [ClientAssertion, nil]
+        attr_reader :client_assertion
       end
 
-      # OAuth response type; always `code`.
-      # @return [String]
-      attr_reader :response_type
-
-      # OAuth client identifier.
-      # @return [String]
-      attr_reader :client_id
-
-      # Registered OAuth callback URI.
-      # @return [String]
-      attr_reader :redirect_uri
-
-      # S256 PKCE challenge.
-      # @return [String]
-      attr_reader :code_challenge
-
-      # PKCE method; must be `S256`.
-      # @return [String]
-      attr_reader :code_challenge_method
-
-      # Random state token to validate the callback.
-      # @return [String]
-      attr_reader :state
-
-      # Space-separated scopes including `atproto`.
-      # @return [String]
-      attr_reader :scope
-
-      # Account handle to prefill at the authorization server.
-      # @return [String, nil]
-      attr_reader :login_hint
+      #
+      # A draft PAR request with writable fields, configured inside the block passed to {Request.build}).
+      #
 
-      # Optional authorization nonce parameter.
-      # @return [String, nil]
-      attr_reader :nonce
+      class Configuration
+        include Fields
 
-      # Optional proof value retained on the request; {Client#submit} generates its own HTTP proof.
-      # @return [String, nil]
-      attr_reader :dpop_proof
+        send(:attr_writer, *Fields.instance_methods(false))
+      end
 
-      # JWT bearer assertion type for confidential clients.
-      # @return [String, nil]
-      attr_reader :client_assertion_type
+      include Fields
 
-      # Signed client authentication JWT for confidential clients.
-      # @return [String, nil]
-      attr_reader :client_assertion
 
       # Builds a validated PAR request by yielding a mutable parameter configuration.
       #
@@ -132,111 +91,70 @@ module AuthProto
       # @raise [Error] if required values are missing or authentication/PKCE/scope values are invalid
       #
       def initialize(config)
-        # Required parameters
-        @response_type = "code" # Always "code" for AT Protocol OAuth
-        @client_id = config.client_id
-        @redirect_uri = config.redirect_uri
-        @code_challenge = config.code_challenge
-        @code_challenge_method = config.code_challenge_method
-        @state = config.state
-        @scope = config.scope
-
-        # Optional parameters
-        @login_hint = config.login_hint
-        @nonce = config.nonce
-        @dpop_proof = config.dpop_proof
-
-        # Client authentication
-        @client_assertion_type = config.client_assertion_type
-        @client_assertion = config.client_assertion
+        Fields.instance_methods(false).each do |field|
+          self.instance_variable_set("@#{field}", config.send(field))
+        end
 
         validate_request
       end
 
-      # Converts request to form-encoded parameters
+      # Converts request to form-encoded parameters, generating a fresh client assertion when configured.
+      # @param audience [String, nil] authorization server issuer; required for confidential clients
       # @return [String] Form-encoded request body
-      def to_form
-        encode_params(build_params)
+      #
+      def to_form(audience: nil)
+        URI.encode_www_form(build_params(audience: audience))
       end
 
+
       private
 
-      def build_params
+      def build_params(audience:)
         params = {
-          "response_type" => response_type,
+          "response_type" => 'code',
           "client_id" => client_id,
           "redirect_uri" => redirect_uri,
           "code_challenge" => code_challenge,
-          "code_challenge_method" => code_challenge_method,
+          "code_challenge_method" => PKCE::CHALLENGE_METHOD_S256,
           "state" => state,
           "scope" => scope
         }
 
-        add_optional_params(params)
-        add_client_auth_params(params)
-        params
-      end
+        params['login_hint'] = login_hint if login_hint
+        params['nonce'] = nonce if nonce
 
-      def add_optional_params(params)
-        params["login_hint"] = login_hint if login_hint
-        params["nonce"] = nonce if nonce
-      end
+        if client_assertion
+          unless audience.is_a?(String) && !audience.empty?
+            raise Error, "audience is required with client_assertion"
+          end
 
-      def add_client_auth_params(params)
-        return unless client_assertion
+          params['client_assertion_type'] = CLIENT_ASSERTION_TYPE
+          params['client_assertion'] = client_assertion.generate_jwt(audience: audience)
+        end
 
-        params["client_assertion_type"] = CLIENT_ASSERTION_TYPE
-        params["client_assertion"] = client_assertion
+        params
       end
 
       def validate_request
         validate_required_params
-        validate_response_type
-        validate_code_challenge_method
-        validate_scope
         validate_client_auth
+
+        raise Error, "atproto scope is required" unless scope.split.include?('atproto')
       end
 
       def validate_required_params
-        %i[client_id redirect_uri code_challenge code_challenge_method state scope].each do |param|
+        %i[client_id redirect_uri code_challenge state scope].each do |param|
           value = send(param)
           raise Error, "#{param} is required" if value.nil? || value.empty?
         end
       end
 
-      def validate_response_type
-        return if response_type == "code"
-
-        raise Error, "response_type must be 'code'"
-      end
-
-      def validate_code_challenge_method
-        return if code_challenge_method == "S256"
-
-        raise Error, "code_challenge_method must be 'S256'"
-      end
-
-      def validate_scope
-        scopes = scope.split
-        raise Error, "atproto scope is required" unless scopes.include?("atproto")
-      end
-
       def validate_client_auth
-        # If either auth parameter is present, both must be present and valid
-        has_assertion = !client_assertion.nil?
-        has_type = !client_assertion_type.nil?
+        return if client_assertion.nil?
 
-        return unless has_assertion || has_type
-        unless client_assertion_type == CLIENT_ASSERTION_TYPE
-          raise Error, "client_assertion_type must be #{CLIENT_ASSERTION_TYPE}"
+        unless client_assertion.is_a?(ClientAssertion)
+          raise Error, "client_assertion must be a PAR::ClientAssertion"
         end
-
-        raise Error, "client_assertion required with client_assertion_type" if client_assertion.nil?
-        raise Error, "client_assertion_type required with client_assertion" if client_assertion_type.nil?
-      end
-
-      def encode_params(params)
-        params.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v.to_s)}" }.join("&")
       end
     end
   end

data/lib/authproto/par/response.rb

@@ -22,21 +22,20 @@ module AuthProto
       # Creates and validates a PAR response.
       #
       # @param request_uri [String] nonempty request URI issued by the authorization server
-      # @param expires_in [Integer, String] positive lifetime in seconds; converted with `to_i`
-      # @raise [Error] if the URI is empty or expiry is not positive
+      # @param expires_in [Integer] positive lifetime in seconds
+      # @raise [Error] if the URI is not a nonempty string or expiry is not a positive integer
       #
       def initialize(request_uri:, expires_in:)
         @request_uri = request_uri
-        @expires_in = expires_in.to_i
-        validate_response
-      end
-
+        @expires_in = expires_in
 
-      private
+        unless @request_uri.is_a?(String) && !@request_uri.empty?
+          raise Error, "request_uri must be a nonempty string"
+        end
 
-      def validate_response
-        raise Error, "request_uri is required" if request_uri.nil? || request_uri.empty?
-        raise Error, "expires_in must be positive" unless expires_in.positive?
+        unless @expires_in.is_a?(Integer) && @expires_in.positive?
+          raise Error, "expires_in must be a positive integer"
+        end
       end
     end
   end

data/lib/authproto/par.rb

@@ -15,7 +15,7 @@ module AuthProto
   #
   # @example Basic PAR request
   #   par = AuthProto::PAR::Client.new(
-  #     endpoint: "https://auth.example.com/par",
+  #     authorization_server: authorization_server,
   #     dpop_client: AuthProto::DPoP::Client.new
   #   )
   #
@@ -23,14 +23,12 @@ module AuthProto
   #     config.client_id = "https://app.example.com/oauth-client-metadata.json"
   #     config.redirect_uri = "https://app.example.com/callback"
   #     config.code_challenge = "abc123..."
-  #     config.code_challenge_method = "S256"
   #     config.state = "xyz789..."
-  #     config.scope = "atproto"
+  #     config.scope = 'atproto'
   #   end
   #
   #   response = par.submit(request)
-  #   auth_url = par.authorization_url(
-  #     authorize_endpoint: "https://auth.example.com/authorize",
+  #   auth_url = par.build_authorization_url(
   #     request_uri: response.request_uri,
   #     client_id: request.client_id
   #   )

data/lib/authproto/pkce.rb

@@ -9,117 +9,40 @@ require_relative 'errors'
 module AuthProto
 
   #
-  # Implementation of Proof Key for Code Exchange (PKCE) for OAuth 2.0 / AT Protocol
-  # as specified in RFC 7636.
-  #
-  # This module provides functionality to:
-  # - Generate cryptographically secure code verifiers
-  # - Create SHA-256 code challenges from verifiers
-  # - Verify challenge/verifier pairs
-  #
-  # Only the S256 challenge method is supported, as required by AT Protocol OAuth.
+  # Generates a matching PKCE verifier and S256 challenge for an OAuth authorization flow.
   #
 
-  module PKCE
+  class PKCE
 
-    # Error raised for PKCE-related failures
+    # Error raised when generating a verifier/challenge pair fails.
     class Error < AuthProto::Error; end
 
-    # Minimum PKCE verifier length in characters.
-    # @return [Integer]
-    MIN_VERIFIER_LENGTH = 43
-
-    # Maximum PKCE verifier length in characters.
-    # @return [Integer]
-    MAX_VERIFIER_LENGTH = 128
-
-    # Allowed PKCE verifier characters from RFC 7636.
-    # @return [Regexp]
-    ALLOWED_VERIFIER_CHARS = /^[A-Za-z0-9\-\._~]+$/
-
-    class << self
-
-      # Generates a cryptographically secure random code verifier
-      #
-      # @param length [Integer] Length of verifier to generate
-      # @return [String] The generated code verifier
-      # @raise [Error] if length is invalid
-      #
-      def generate_verifier(length = MAX_VERIFIER_LENGTH)
-        validate_verifier_length(length)
-
-        # Generate random bytes and encode as URL-safe base64
-        random_bytes = SecureRandom.random_bytes(length * 3 / 4)
-        Base64.urlsafe_encode64(random_bytes, padding: false)[0...length]
-      rescue StandardError => e
-        raise Error, "Failed to generate verifier: #{e.message}"
-      end
-
-      # Creates a code challenge from a verifier using SHA-256
-      #
-      # @param verifier [String] The code verifier to create challenge from
-      # @return [String] Base64URL-encoded SHA-256 hash of the verifier
-      # @raise [Error] if verifier is invalid or hashing fails
-      #
-      def generate_challenge(verifier)
-        validate_verifier(verifier)
-
-        # Hash with SHA-256 and encode as URL-safe base64
-        digest = OpenSSL::Digest::SHA256.digest(verifier)
-        Base64.urlsafe_encode64(digest, padding: false)
-      rescue StandardError => e
-        raise Error, "Failed to generate challenge: #{e.message}"
-      end
-
-      # Verifies that a challenge matches a verifier
-      #
-      # @param challenge [String] The code challenge to verify
-      # @param verifier [String] The code verifier to check against
-      # @return [Boolean] true if challenge matches verifier
-      # @raise [Error] if inputs are invalid
-      #
-      def verify(challenge, verifier)
-        # Generate challenge from verifier and compare
-        calculated = generate_challenge(verifier)
-        secure_compare(calculated, challenge)
-      rescue Error
-        # Re-raise PKCE errors
-        raise
-      rescue StandardError => e
-        raise Error, "Challenge verification failed: #{e.message}"
-      end
-
-
-      private
-
-      def validate_verifier_length(length)
-        return if length.is_a?(Integer) && length.between?(MIN_VERIFIER_LENGTH, MAX_VERIFIER_LENGTH)
-
-        raise Error, "Verifier length must be between #{MIN_VERIFIER_LENGTH} and #{MAX_VERIFIER_LENGTH}"
-      end
-
-      def validate_verifier(verifier)
-        raise Error, "Verifier cannot be nil" if verifier.nil?
-        raise Error, "Verifier cannot be empty" if verifier.empty?
-
-        length = verifier.length
-        validate_verifier_length(length)
-
-        return if verifier.match?(ALLOWED_VERIFIER_CHARS)
-
-        raise Error, "Verifier contains invalid characters"
-      end
-
-      # Constant-time string comparison to prevent timing attacks
-      def secure_compare(str1, str2)
-        return false unless str1.bytesize == str2.bytesize
-
-        left = str1.unpack("C*")
-        right = str2.unpack("C*")
-        result = 0
-        left.zip(right) { |x, y| result |= x ^ y }
-        result.zero?
-      end
+    # Challenge method required by AT Protocol OAuth.
+    CHALLENGE_METHOD_S256 = 'S256'
+
+    # Random bytes providing 256 bits of entropy, encoded as a 43-character verifier without padding.
+    VERIFIER_BYTES = 32
+
+    # Cryptographically random, URL-safe code verifier.
+    # @return [String]
+    attr_reader :verifier
+
+    # Base64URL-encoded SHA-256 digest of the verifier, without padding.
+    # @return [String]
+    attr_reader :challenge
+
+    # Generates a verifier and its matching S256 challenge.
+    #
+    # Both strings are frozen so the pair cannot be changed after generation.
+    #
+    # @raise [Error] if random generation or hashing fails
+    #
+    def initialize
+      @verifier = SecureRandom.urlsafe_base64(VERIFIER_BYTES, false).freeze
+      digest = OpenSSL::Digest::SHA256.digest(@verifier)
+      @challenge = Base64.urlsafe_encode64(digest, padding: false).freeze
+    rescue StandardError => e
+      raise Error, "Failed to generate PKCE: #{e.message}"
     end
   end
 end

data/lib/authproto/serialization/session.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../server_metadata/authorization_server'
+require_relative '../metadata/authorization_server'
 require_relative '../state/session'
 require_relative 'base'
 require_relative 'token_set'
@@ -44,19 +44,19 @@ module AuthProto
 
       def deserialize_data(data)
         AuthProto::State::Session.new(
-          client_id: data["client_id"],
-          scope: data["scope"],
-          did: data["did"],
-          auth_server: deserialize_auth_server(data["auth_server"])
+          client_id: data['client_id'],
+          scope: data['scope'],
+          did: data['did'],
+          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"])
+          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.tokens = deserialize_token_set(data['tokens']) if data['tokens']
         end
       end
 
@@ -81,7 +81,7 @@ module AuthProto
       def deserialize_auth_server(data)
         return nil unless data
 
-        AuthProto::ServerMetadata::AuthorizationServer.new(data)
+        AuthProto::Metadata::AuthorizationServer.new(data)
       end
     end
   end

data/lib/authproto/serialization/token_set.rb

@@ -41,12 +41,12 @@ module AuthProto
 
       def deserialize_data(data)
         AuthProto::State::TokenSet.new(
-          access_token: data["access_token"],
-          refresh_token: data["refresh_token"],
-          token_type: data["token_type"],
-          expires_in: (Time.parse(data["expires_at"]) - Time.now).to_i,
-          scope: data["scope"],
-          sub: data["sub"]
+          access_token: data['access_token'],
+          refresh_token: data['refresh_token'],
+          token_type: data['token_type'],
+          expires_in: (Time.parse(data['expires_at']) - Time.now).to_i,
+          scope: data['scope'],
+          sub: data['sub']
         )
       end
     end

data/lib/authproto/state/session.rb

@@ -41,7 +41,7 @@ module AuthProto
       attr_reader :pkce_challenge
 
       # Bound authorization server, once discovered.
-      # @return [ServerMetadata::AuthorizationServer, nil]
+      # @return [Metadata::AuthorizationServer, nil]
       attr_reader :auth_server
 
       # Bound account DID, once resolved.
@@ -56,7 +56,7 @@ module AuthProto
       #
       # @param client_id [String] OAuth client ID
       # @param scope [String] requested space-separated scopes
-      # @param auth_server [ServerMetadata::AuthorizationServer, nil] pre-resolved authorization server
+      # @param auth_server [Metadata::AuthorizationServer, nil] pre-resolved authorization server
       # @param did [String, nil] pre-resolved account DID
       # @raise [PKCE::Error] if PKCE generation fails
       #
@@ -70,17 +70,17 @@ module AuthProto
         @auth_server = auth_server
         @did = did
 
-        # Generate PKCE values
-        @pkce_verifier = PKCE.generate_verifier
-        @pkce_challenge = PKCE.generate_challenge(@pkce_verifier)
+        pkce = PKCE.new
+        @pkce_verifier = pkce.verifier
+        @pkce_challenge = pkce.challenge
 
         @tokens = nil
       end
 
       # Binds this session to an authorization server.
       #
-      # @param server [ServerMetadata::AuthorizationServer] resolved authorization server
-      # @return [ServerMetadata::AuthorizationServer] assigned server when called as a method
+      # @param server [Metadata::AuthorizationServer] resolved authorization server
+      # @return [Metadata::AuthorizationServer] assigned server when called as a method
       # @raise [SessionError] if already bound to a server with a different issuer
       #
       def authorization_server=(server)
@@ -124,6 +124,26 @@ module AuthProto
         end
       end
 
+      # Returns the current tokens and session identifiers, with expiry in seconds from now.
+      #
+      # @return [Hash{Symbol => String, Integer, nil}, nil] session data, or `nil` before tokens are assigned
+      #
+      def session_data
+        synchronize do
+          return nil unless @tokens
+
+          {
+            access_token: @tokens.access_token,
+            token_type: @tokens.token_type,
+            expires_in: (@tokens.expires_at - Time.now).to_i,
+            refresh_token: @tokens.refresh_token,
+            scope: @tokens.scope,
+            session_id: @session_id,
+            did: @did
+          }
+        end
+      end
+
       # Whether this session has valid access tokens
       # @return [Boolean]
       def authorized?
@@ -139,30 +159,6 @@ module AuthProto
           !@tokens.nil? && @tokens.renewable?
         end
       end
-
-      # Compares a supplied state token with the session token in constant time.
-      #
-      # @param state [String, nil] callback state token
-      # @return [Boolean] whether it matches; `false` for `nil` or a different length
-      #
-      def validate_state(state)
-        return false unless state
-
-        # Use secure comparison to prevent timing attacks
-        secure_compare(@state_token, state)
-      end
-
-      private
-
-      def secure_compare(str1, str2)
-        return false unless str1.bytesize == str2.bytesize
-
-        left = str1.unpack("C*")
-        right = str2.unpack("C*")
-        result = 0
-        left.zip(right) { |x, y| result |= x ^ y }
-        result.zero?
-      end
     end
   end
 end

data/lib/authproto/state/session_manager.rb

@@ -25,7 +25,7 @@ module AuthProto
       #
       # @param client_id [String] OAuth client ID
       # @param scope [String] requested space-separated scopes
-      # @param auth_server [ServerMetadata::AuthorizationServer, nil] pre-resolved authorization server
+      # @param auth_server [Metadata::AuthorizationServer, nil] pre-resolved authorization server
       # @param did [String, nil] pre-resolved account DID
       #
       # @return [Session] newly created session
@@ -136,7 +136,7 @@ module AuthProto
       # @return [void]
       # @raise [Storage::StorageError] if deletion or locking fails
       #
-      def remove_session(session_id)
+      def delete_session(session_id)
         session = get_session(session_id)
         return unless session