authproto 0.3.0.beta1

data/lib/authproto/par/client.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'uri'
+
+require_relative '../configuration'
+require_relative '../par'
+require_relative 'response'
+
+module AuthProto
+  module PAR
+
+    #
+    # Client for making Pushed Authorization Requests (PAR) according to RFC 9126.
+    # Handles submitting authorization parameters to the PAR endpoint and building
+    # the subsequent authorization URL.
+    #
+    # In AT Protocol OAuth, all authorization requests must first go through PAR.
+    # This means instead of sending authorization parameters directly to the
+    # authorization endpoint, clients:
+    # 1. Submit parameters to the PAR endpoint via POST
+    # 2. Receive a request_uri in response
+    # 3. Use only the request_uri and client_id in the authorization redirect
+    #
+    # @example Basic PAR flow
+    #   client = AuthProto::PAR::Client.new(
+    #     endpoint: "https://auth.example.com/par",
+    #     dpop_client: AuthProto::DPoP::Client.new
+    #   )
+    #
+    #   # Create and submit PAR request using builder pattern
+    #   request = AuthProto::PAR::Request.build do |config|
+    #     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"
+    #   end
+    #
+    #   response = client.submit(request)
+    #
+    #   # Build authorization URL using response
+    #   auth_url = client.authorization_url(
+    #     authorize_endpoint: "https://auth.example.com/authorize",
+    #     request_uri: response.request_uri,
+    #     client_id: request.client_id
+    #   )
+    #
+    # @example With client authentication (confidential clients)
+    #   request = AuthProto::PAR::Request.build do |config|
+    #     # ... basic parameters ...
+    #     config.client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+    #     config.client_assertion = jwt_token
+    #   end
+    #
+    # All requests use HTTPS and include a fresh DPoP proof from the supplied
+    # DPoP client. Nonce challenges are retried once with a new proof. The client
+    # validates PAR responses before returning a request URI.
+    #
+
+    class Client
+
+      # HTTPS pushed authorization request endpoint.
+      # @return [String]
+      attr_reader :endpoint
+
+      # DPoP client used to sign requests.
+      # @return [DPoP::Client]
+      attr_reader :dpop_client
+
+      # Nonce manager belonging to the DPoP client.
+      # @return [DPoP::NonceManager]
+      attr_reader :nonce_manager
+
+      # Creates a PAR transport using the global HTTP client and supplied DPoP client.
+      #
+      # @param endpoint [String] HTTPS PAR endpoint
+      # @param dpop_client [DPoP::Client] proof generator and nonce tracker
+      # @raise [Error] if the endpoint is malformed or does not use HTTPS
+      #
+      def initialize(endpoint:, dpop_client:)
+        @endpoint = endpoint
+        @dpop_client = dpop_client
+        @nonce_manager = dpop_client.nonce_manager
+        validate_endpoint
+      end
+
+      # Submits a PAR request, handling DPoP nonce requirements
+      #
+      # @param request [Request] The request to submit
+      # @return [Response] The PAR response
+      # @raise [Error] if request fails
+      #
+      def submit(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
+        end
+
+        handle_error_response(response)
+      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)
+        # Try all possible header key formats
+        headers = response[:headers]
+        nonce = headers["DPoP-Nonce"] ||
+                headers["dpop-nonce"] ||
+                headers["Dpop-Nonce"]
+
+        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.
+      #
+      # The endpoint's existing query is replaced by these two parameters.
+      #
+      # @param authorize_endpoint [String] authorization endpoint URL
+      # @param request_uri [String] request URI from {Response#request_uri}
+      # @param client_id [String] OAuth client ID
+      # @return [String] browser authorization URL
+      # @raise [URI::InvalidURIError] if the authorization endpoint cannot be parsed
+      #
+      def authorization_url(authorize_endpoint:, request_uri:, client_id:)
+        uri = URI(authorize_endpoint)
+        uri.query = encode_params(
+          "request_uri" => request_uri,
+          "client_id" => client_id
+        )
+        uri.to_s
+      end
+
+      private
+
+      def validate_endpoint
+        uri = URI(@endpoint)
+        raise Error, "endpoint must be HTTPS" unless uri.scheme == "https"
+      rescue URI::InvalidURIError => e
+        raise Error, "invalid endpoint URL: #{e.message}"
+      end
+
+      def make_request(request)
+        # Generate DPoP proof for this request
+        proof = dpop_client.generate_proof(
+          http_method: "POST",
+          http_uri: endpoint,
+          nonce: nonce_manager.get(server_origin)
+        )
+
+        # Build headers including DPoP proof
+        headers = build_headers(request, proof)
+
+        # Make the request
+        AuthProto.configuration.http_client.post(
+          endpoint,
+          body: request.to_form,
+          headers: headers
+        )
+      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"] == "use_dpop_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(@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])
+          error_message = error_data["error_description"] || error_data["error"] || "Unknown error"
+        rescue JSON::ParserError
+          error_message = "Invalid response from server"
+        end
+
+        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
+
+        begin
+          data = JSON.parse(response[:body])
+          Response.new(
+            request_uri: data["request_uri"],
+            expires_in: data["expires_in"]
+          )
+        rescue JSON::ParserError => e
+          raise Error, "invalid JSON response: #{e.message}"
+        rescue StandardError => e
+          raise Error, "failed to process response: #{e.message}"
+        end
+      end
+
+      def encode_params(params)
+        params.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v.to_s)}" }.join("&")
+      end
+    end
+  end
+end

data/lib/authproto/par/client_assertion.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'securerandom'
+
+require_relative '../errors'
+
+module AuthProto
+  module PAR
+
+    #
+    # Generates client authentication JWTs according to RFC 7523 for AT Protocol OAuth.
+    # Creates signed assertions using ES256 with required claims including iss/sub (client_id),
+    # aud (authorization server issuer), jti (unique ID), and iat/exp (timing claims).
+    #
+
+    class ClientAssertion
+
+      # Raised when client assertion key import or JWT signing fails.
+      class Error < AuthProto::Error; end
+
+      # Creates an ES256 client assertion signer.
+      #
+      # @param client_id [String] client ID used in `iss` and `sub`
+      # @param signing_key [JOSE::JWK] private EC P-256 signing key, including its `kid`
+      #
+      def initialize(client_id:, signing_key:)
+        @client_id = client_id
+        @signing_key = signing_key
+      end
+
+      # Signs a short-lived client authentication JWT with ES256.
+      #
+      # 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
+      # @return [String] compact signed client assertion JWT
+      # @raise [Error] if JWK import or JWT signing fails
+      #
+      def generate_jwt(audience:, lifetime: 300)
+        now = Time.now.to_i
+
+        payload = {
+          # Required claims
+          iss: @client_id, # Issuer is client_id
+          sub: @client_id, # Subject is client_id
+          aud: audience, # Audience is the authorization server issuer
+          jti: SecureRandom.uuid, # Unique identifier
+          exp: now + lifetime, # Expiration time
+          iat: now # Issued at time
+        }
+
+        # Header specifying ES256 algorithm for signing
+        header = {
+          alg: "ES256",
+          typ: "JWT",
+          kid: @signing_key.fields["kid"]
+        }
+
+        # Sign and return the JWT
+        key = JWT::JWK.import(@signing_key.to_map.to_h)
+        JWT.encode(payload, key, "ES256", header)
+      rescue JWT::Error, ArgumentError => e
+        raise Error, "Failed to generate client assertion: #{e.message}"
+      end
+    end
+  end
+end

data/lib/authproto/par/request.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+require_relative '../par'
+
+module AuthProto
+  module PAR
+
+    #
+    # Represents a pushed authorization request
+    #
+
+    class Request
+
+      #
+      # Configuration for request parameters
+      #
+
+      class Configuration
+
+        # OAuth client identifier.
+        # @return [String, nil]
+        attr_accessor :client_id
+
+        # Registered OAuth callback URI.
+        # @return [String, nil]
+        attr_accessor :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
+
+        # Random state token to validate the callback.
+        # @return [String, nil]
+        attr_accessor :state
+
+        # Space-separated scopes including `atproto`.
+        # @return [String, nil]
+        attr_accessor :scope
+
+        # Account handle to prefill at the authorization server.
+        # @return [String, nil]
+        attr_accessor :login_hint
+
+        # Optional authorization nonce parameter.
+        # @return [String, nil]
+        attr_accessor :nonce
+
+        # Optional proof value retained on the request; {Client#submit} generates its own HTTP proof.
+        # @return [String, nil]
+        attr_accessor :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
+      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
+
+      # Optional authorization nonce parameter.
+      # @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
+
+      # JWT bearer assertion type for confidential clients.
+      # @return [String, nil]
+      attr_reader :client_assertion_type
+
+      # 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.
+      #
+      # @yield [config] block that sets the request parameters
+      # @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
+      #
+      def self.build
+        config = Configuration.new
+        yield(config)
+        new(config)
+      end
+
+      # 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
+      #
+      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
+
+        validate_request
+      end
+
+      # Converts request to form-encoded parameters
+      # @return [String] Form-encoded request body
+      def to_form
+        encode_params(build_params)
+      end
+
+      private
+
+      def build_params
+        params = {
+          "response_type" => response_type,
+          "client_id" => client_id,
+          "redirect_uri" => redirect_uri,
+          "code_challenge" => code_challenge,
+          "code_challenge_method" => code_challenge_method,
+          "state" => state,
+          "scope" => scope
+        }
+
+        add_optional_params(params)
+        add_client_auth_params(params)
+        params
+      end
+
+      def add_optional_params(params)
+        params["login_hint"] = login_hint if login_hint
+        params["nonce"] = nonce if nonce
+      end
+
+      def add_client_auth_params(params)
+        return unless client_assertion
+
+        params["client_assertion_type"] = CLIENT_ASSERTION_TYPE
+        params["client_assertion"] = client_assertion
+      end
+
+      def validate_request
+        validate_required_params
+        validate_response_type
+        validate_code_challenge_method
+        validate_scope
+        validate_client_auth
+      end
+
+      def validate_required_params
+        %i[client_id redirect_uri code_challenge code_challenge_method 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 unless has_assertion || has_type
+        unless client_assertion_type == CLIENT_ASSERTION_TYPE
+          raise Error, "client_assertion_type must be #{CLIENT_ASSERTION_TYPE}"
+        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
+end

data/lib/authproto/par/response.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../par'
+
+module AuthProto
+  module PAR
+
+    #
+    # Represents a PAR response
+    #
+
+    class Response
+
+      # Opaque PAR request URI used in the browser authorization URL.
+      # @return [String]
+      attr_reader :request_uri
+
+      # Lifetime of the request URI in seconds.
+      # @return [Integer]
+      attr_reader :expires_in
+
+      # 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
+      #
+      def initialize(request_uri:, expires_in:)
+        @request_uri = request_uri
+        @expires_in = expires_in.to_i
+        validate_response
+      end
+
+
+      private
+
+      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?
+      end
+    end
+  end
+end

data/lib/authproto/par.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module AuthProto
+
+  #
+  # Handles creation and processing of Pushed Authorization Requests (PAR)
+  # according to RFC 9126 and AT Protocol OAuth requirements.
+  #
+  # PAR is mandatory in AT Protocol OAuth. Before redirecting a user to the
+  # authorization endpoint, clients must first submit all authorization parameters
+  # via HTTP POST to the PAR endpoint. Only the returned request_uri and client_id
+  # are then included in the authorization redirect.
+  #
+  # @example Basic PAR request
+  #   par = AuthProto::PAR::Client.new(
+  #     endpoint: "https://auth.example.com/par",
+  #     dpop_client: AuthProto::DPoP::Client.new
+  #   )
+  #
+  #   request = AuthProto::PAR::Request.build do |config|
+  #     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"
+  #   end
+  #
+  #   response = par.submit(request)
+  #   auth_url = par.authorization_url(
+  #     authorize_endpoint: "https://auth.example.com/authorize",
+  #     request_uri: response.request_uri,
+  #     client_id: request.client_id
+  #   )
+  #
+
+  module PAR
+
+    # Error raised for PAR-related issues
+    class Error < AuthProto::Error; end
+
+    # OAuth JWT bearer client assertion type URN.
+    # @return [String]
+    CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+  end
+end