atproto_auth 0.0.1

data/lib/atproto_auth/identity/resolver.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "resolv"
+
+module AtprotoAuth
+  module Identity
+    # Resolves and validates AT Protocol identities
+    class Resolver
+      PLC_DIRECTORY_URL = "https://plc.directory"
+      DID_PLC_PREFIX = "did:plc:"
+      HANDLE_REGEX = /^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/
+
+      # Creates a new Identity resolver
+      # @param plc_directory [String] Optional custom PLC directory URL
+      def initialize(plc_directory: nil)
+        @plc_directory = plc_directory || PLC_DIRECTORY_URL
+      end
+
+      # Resolves a handle to a DID Document
+      # @param handle [String] The handle to resolve (with or without @ prefix)
+      # @return [Hash] Resolution result with :did, :document, and :pds keys
+      # @raise [ResolutionError] if resolution fails
+      def resolve_handle(handle)
+        validate_handle!(handle)
+        normalized = normalize_handle(handle)
+
+        # First try DNS-based resolution
+        did = resolve_handle_dns(normalized)
+        return get_did_info(did) if did
+
+        # Fall back to HTTP resolution via a known PDS
+        resolve_handle_http(normalized)
+      rescue StandardError => e
+        raise ResolutionError, "Failed to resolve handle #{handle}: #{e.message}"
+      end
+
+      # Fetches and parses DID Document
+      # @param did [String] The DID to resolve
+      # @return [Hash] Resolution result with :did, :document, and :pds keys
+      # @raise [ResolutionError] if resolution fails
+      def get_did_info(did)
+        validate_did!(did)
+
+        # Fetch and parse DID document
+        doc_data = fetch_did_document(did)
+        document = Document.new(doc_data)
+
+        # Validate PDS URL format
+        validate_pds_url!(document.pds)
+
+        { did: did, document: document, pds: document.pds }
+      rescue DocumentError => e
+        raise ResolutionError, "Invalid DID document: #{e.message}"
+      rescue StandardError => e
+        raise ResolutionError, "Failed to resolve DID #{did}: #{e.message}"
+      end
+
+      # Verifies that a PDS hosts a given DID
+      # @param did [String] The DID to verify
+      # @param pds_url [String] The PDS URL to check
+      # @return [Boolean] true if verification succeeds
+      # @raise [ValidationError] if verification fails
+      def verify_pds_binding(did, pds_url)
+        info = get_did_info(did)
+        normalize_url(info[:pds]) == normalize_url(pds_url)
+      rescue StandardError => e
+        raise ValidationError, "Failed to verify PDS binding: #{e.message}"
+      end
+
+      # Verifies that an auth server (issuer) is authorized for a DID
+      # @param did [String] The DID to verify
+      # @param issuer [String] The issuer URL to verify
+      # @return [Boolean] true if verification succeeds
+      # @raise [ValidationError] if verification fails
+      def verify_issuer_binding(did, issuer)
+        # Get PDS location from DID
+        info = get_did_info(did)
+        pds_url = info[:pds]
+
+        # Fetch resource server metadata to find auth server
+        resource_server = ServerMetadata::ResourceServer.from_url(pds_url)
+        auth_server_url = resource_server.authorization_servers.first
+
+        # Compare normalized URLs
+        normalize_url(auth_server_url) == normalize_url(issuer)
+      rescue StandardError => e
+        raise ValidationError, "Failed to verify issuer binding: #{e.message}"
+      end
+
+      # Verifies that a handle belongs to a DID
+      # @param handle [String] Handle to verify
+      # @param did [String] DID to check against
+      # @return [Boolean] true if verification succeeds
+      # @raise [ValidationError] if verification fails
+      def verify_handle_binding(handle, did)
+        info = get_did_info(did)
+        info[:document].has_handle?(handle)
+      rescue StandardError => e
+        raise ValidationError, "Failed to verify handle binding: #{e.message}"
+      end
+
+      private
+
+      def validate_handle!(handle)
+        normalized = normalize_handle(handle)
+        return if normalized.match?(HANDLE_REGEX)
+
+        raise ResolutionError, "Invalid handle format: #{handle}"
+      end
+
+      def validate_did!(did)
+        return if did.start_with?(DID_PLC_PREFIX)
+
+        raise ResolutionError, "Invalid DID format (must be did:plc:): #{did}"
+      end
+
+      def normalize_handle(handle)
+        normalized = handle.start_with?("@") ? handle[1..] : handle
+        normalized.downcase
+      end
+
+      def resolve_handle_dns(handle) # rubocop:disable Metrics/CyclomaticComplexity
+        domain = extract_domain(handle)
+        return nil unless domain
+
+        txt_records = fetch_txt_records("_atproto.#{domain}")
+        return nil unless txt_records&.any?
+
+        # Look for did= entries in TXT records
+        txt_records.each do |record|
+          next unless record.start_with?("did=")
+
+          did = record.delete_prefix("did=").strip
+          return did if valid_did?(did)
+        end
+
+        nil
+      rescue Resolv::ResolvError, Resolv::ResolvTimeout => e
+        logger.debug("DNS resolution failed for #{handle}: #{e.message}")
+        nil # Gracefully fall back to HTTP resolution
+      end
+
+      def extract_domain(handle)
+        # Remove @ prefix if present
+        handle = handle[1..] if handle.start_with?("@")
+
+        # Handle could be user.domain.com or domain.com format
+        # We just need the domain portion
+        if handle.count(".") == 1
+          handle
+        else
+          handle.split(".", 2)[1]
+        end
+      end
+
+      def fetch_txt_records(domain)
+        resolver = Resolv::DNS.new
+        resolver.timeouts = 3 # 3 second timeout
+
+        records = resolver.getresources(
+          domain,
+          Resolv::DNS::Resource::IN::TXT
+        ).map { |r| r.strings.join(" ") }
+
+        resolver.close
+        records
+      end
+
+      def valid_did?(did)
+        did.start_with?(DID_PLC_PREFIX) && did.length > DID_PLC_PREFIX.length
+      end
+
+      def resolve_handle_http(handle)
+        # Build resolution URL
+        uri = URI("https://#{handle}/.well-known/atproto-did")
+
+        # Make HTTP request
+        response = AtprotoAuth.configuration.http_client.get(uri.to_s)
+        did = response[:body].strip
+
+        validate_did!(did)
+        get_did_info(did)
+      end
+
+      def fetch_did_document(did)
+        # Fetch document from PLC directory
+        uri = URI.join(@plc_directory, "/#{did}")
+        response = AtprotoAuth.configuration.http_client.get(uri.to_s)
+        JSON.parse(response[:body])
+      end
+
+      def validate_pds_url!(url)
+        uri = URI(url)
+        return if uri.is_a?(URI::HTTPS)
+
+        raise ResolutionError, "PDS URL must use HTTPS"
+      end
+
+      def normalize_url(url)
+        uri = URI(url)
+
+        # Remove default ports
+        uri.port = nil if (uri.scheme == "https" && uri.port == 443) ||
+                          (uri.scheme == "http" && uri.port == 80)
+
+        # Ensure no trailing slash
+        uri.path = uri.path.chomp("/")
+
+        # Remove any query or fragment
+        uri.query = nil
+        uri.fragment = nil
+
+        uri.to_s
+      end
+
+      def logger
+        @logger ||= AtprotoAuth.configuration.logger || Logger.new($stdout)
+      end
+    end
+  end
+end

data/lib/atproto_auth/identity.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  # Handles identity resolution, verification and management for AT Protocol OAuth.
+  # This module provides functionality to resolve handles to DIDs, verify identity
+  # documents, validate PDS locations, and verify authorization server bindings.
+  #
+  # The module consists of three main components:
+  #
+  # 1. {Document} - Represents and validates AT Protocol DID documents,
+  #    handling extraction of crucial service endpoints and verification.
+  #
+  # 2. {Resolver} - Handles resolution of handles to DIDs and fetching of
+  #    DID documents, with support for both DNS and HTTP-based resolution.
+  #
+  # 3. {Error} classes - Structured error hierarchy for handling different
+  #    types of identity-related failures.
+  module Identity
+    class Error < Error; end
+    class ResolutionError < Error; end
+    class ValidationError < Error; end
+    class DocumentError < Error; end
+  end
+end

data/lib/atproto_auth/par/client.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  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 = AtprotoAuth::PAR::Client.new(
+    #     endpoint: "https://auth.example.com/par"
+    #   )
+    #
+    #   # Create and submit PAR request using builder pattern
+    #   request = AtprotoAuth::PAR::Request.build do |config|
+    #     config.client_id = "https://app.example.com/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 = AtprotoAuth::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
+    #
+    # @example With DPoP proof
+    #   request = AtprotoAuth::PAR::Request.build do |config|
+    #     # ... basic parameters ...
+    #     config.dpop_proof = dpop_proof_jwt
+    #   end
+    #
+    # All requests are made using HTTPS and include proper content-type headers.
+    # DPoP proofs can be included for enhanced security. The client validates
+    # all responses and provides clear error messages for any failures.
+    class Client
+      attr_reader :endpoint, :dpop_client, :nonce_manager
+
+      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
+
+      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 authorization URL from PAR response
+      # @param authorize_endpoint [String] Authorization endpoint URL
+      # @param request_uri [String] PAR request_uri
+      # @param client_id [String] OAuth client_id
+      # @return [String] Authorization URL
+      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
+        AtprotoAuth.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/atproto_auth/par/client_assertion.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  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 (token endpoint), jti (unique ID), and iat/exp (timing claims).
+    class ClientAssertion
+      class Error < AtprotoAuth::Error; end
+
+      # @param client_id [String] OAuth client ID
+      # @param signing_key [JOSE::JWK] Key to sign assertion with
+      def initialize(client_id:, signing_key:)
+        @client_id = client_id
+        @signing_key = signing_key
+      end
+
+      # Generates a new client assertion JWT
+      # @param audience [String] Issuer endpoint URL
+      # @param lifetime [Integer] How long assertion is valid for in seconds
+      # @return [String] Signed JWT assertion
+      # 5 minute default lifetime
+      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 token endpoint
+          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
+        JWT.encode(payload, @signing_key.kty.key, "ES256", header)
+      rescue StandardError => e
+        raise Error, "Failed to generate client assertion: #{e.message}"
+      end
+    end
+  end
+end

data/lib/atproto_auth/par/request.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  module PAR
+    # Represents a pushed authorization request
+    class Request
+      # Configuration for request parameters
+      class Configuration
+        attr_accessor :client_id, :redirect_uri, :code_challenge,
+                      :code_challenge_method, :state, :scope, :login_hint,
+                      :nonce, :dpop_proof, :client_assertion_type,
+                      :client_assertion
+      end
+
+      # Required parameters
+      attr_reader :response_type, :client_id, :code_challenge,
+                  :code_challenge_method, :state, :redirect_uri, :scope
+
+      # Optional parameters
+      attr_reader :login_hint, :nonce, :dpop_proof
+
+      # Client authentication (for confidential clients)
+      attr_reader :client_assertion_type, :client_assertion
+
+      def self.build
+        config = Configuration.new
+        yield(config)
+        new(config)
+      end
+
+      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!
+      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!
+        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/atproto_auth/par/response.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  module PAR
+    # Represents a PAR response
+    class Response
+      attr_reader :request_uri, :expires_in
+
+      def initialize(request_uri:, expires_in:)
+        @request_uri = request_uri
+        @expires_in = expires_in.to_i
+        validate!
+      end
+
+      private
+
+      def validate!
+        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/atproto_auth/par.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "base64"
+require "openssl"
+
+module AtprotoAuth
+  # 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 = AtprotoAuth::PAR::Client.new(endpoint: "https://auth.example.com/par")
+  #
+  #   request = par.create_request(
+  #     client_id: "https://app.example.com/client-metadata.json",
+  #     redirect_uri: "https://app.example.com/callback",
+  #     code_challenge: "abc123...",
+  #     code_challenge_method: "S256",
+  #     state: "xyz789...",
+  #     scope: "atproto"
+  #   )
+  #
+  #   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 < AtprotoAuth::Error; end
+
+    CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+  end
+end