atproto_auth 0.0.1

data/lib/atproto_auth/client_metadata.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+
+module AtprotoAuth
+  module ApplicationType
+    ALL = [
+      WEB = "web",
+      NATIVE = "native"
+    ].freeze
+  end
+
+  # Handles validation and management of AT Protocol OAuth client metadata according to
+  # the specification. This includes required fields like client_id and redirect URIs,
+  # optional metadata like client name and logo, and authentication configuration for
+  # confidential clients. Validates that all fields conform to the protocol's requirements,
+  # including:
+  # - Application type (web/native) validation and redirect URI rules
+  # - Required scopes and grant types
+  # - JWKS configuration for confidential clients
+  # - DPoP binding requirements
+  # - URI scheme and format validation
+  class ClientMetadata
+    # Required fields
+    attr_reader :application_type, :client_id, :grant_types, :response_types, :redirect_uris, :scope
+    # Optional fields
+    attr_reader :client_name, :client_uri, :logo_uri, :tos_uri, :policy_uri
+    # Authentication and key-related fields
+    attr_reader :token_endpoint_auth_method, :jwks, :jwks_uri
+
+    # Initializes a new ClientMetadata instance from metadata hash.
+    # @param metadata [Hash] Client metadata.
+    # @raise [InvalidClientMetadata] if metadata is invalid.
+    def initialize(metadata)
+      validate_and_set_metadata!(metadata)
+    end
+
+    # Fetches client metadata from a URL and creates a new instance.
+    # @param url [String] URL to fetch metadata from.
+    # @return [ClientMetadata] new instance with fetched metadata.
+    # @raise [InvalidClientMetadata] if metadata is invalid or cannot be fetched.
+    def self.from_url(url)
+      validate_url!(url)
+      response = fetch_metadata(url)
+      metadata = parse_metadata(response[:body])
+      validate_client_id!(metadata["client_id"], url)
+      new(metadata)
+    end
+
+    # Determines if the client is confidential (has authentication keys).
+    # @return [Boolean] true if client is confidential.
+    def confidential?
+      token_endpoint_auth_method == "private_key_jwt"
+    end
+
+    private
+
+    def validate_and_set_metadata!(metadata) # rubocop:disable Metrics/AbcSize
+      # Required fields
+      @application_type = validate_application_type(metadata["application_type"])
+      @client_id = validate_client_id!(metadata["client_id"])
+      @grant_types = validate_grant_types!(metadata["grant_types"])
+      @response_types = validate_response_types!(metadata["response_types"])
+      @redirect_uris = validate_redirect_uris!(metadata["redirect_uris"])
+      @scope = validate_scope!(metadata["scope"])
+
+      validate_dpop!(metadata)
+
+      # Optional fields
+      @client_name = metadata["client_name"]
+      @client_uri = validate_client_uri(metadata["client_uri"])
+      @logo_uri = validate_https_uri(metadata["logo_uri"])
+      @tos_uri = validate_https_uri(metadata["tos_uri"])
+      @policy_uri = validate_https_uri(metadata["policy_uri"])
+
+      # Authentication methods
+      validate_auth_methods!(metadata)
+    end
+
+    def validate_client_id!(client_id)
+      raise InvalidClientMetadata, "client_id is required" unless client_id
+
+      uri = URI(client_id)
+      unless uri.scheme == "https" || (uri.scheme == "http" && uri.host == "localhost")
+        raise InvalidClientMetadata, "client_id must be HTTPS or localhost HTTP URL"
+      end
+
+      client_id
+    end
+
+    def validate_grant_types!(grant_types)
+      raise InvalidClientMetadata, "grant_types is required" unless grant_types
+
+      valid_types = %w[authorization_code refresh_token]
+      unless grant_types.include?("authorization_code") && (grant_types - valid_types).empty?
+        raise InvalidClientMetadata, "grant_types must include authorization_code and optionally refresh_token"
+      end
+
+      grant_types
+    end
+
+    def validate_response_types!(response_types)
+      raise InvalidClientMetadata, "response_types is required" unless response_types
+      raise InvalidClientMetadata, "response_types must include 'code'" unless response_types.include?("code")
+
+      response_types
+    end
+
+    def validate_redirect_uris!(uris)
+      raise InvalidClientMetadata, "redirect_uris is required" if uris.nil? || uris.none?
+
+      uris.each { |uri| validate_redirect_uri!(URI(uri)) }
+      uris
+    end
+
+    def validate_redirect_uri!(uri)
+      case application_type
+      when ApplicationType::WEB
+        if uri.host != "127.0.0.1" && uri.scheme != "https"
+          raise InvalidClientMetadata, "web clients must use HTTPS redirect URIs #{uri}"
+        end
+
+        validate_redirect_uri_origin!(uri)
+      when ApplicationType::NATIVE
+        validate_native_redirect_uri!(uri)
+      end
+    end
+
+    def validate_redirect_uri_origin!(uri)
+      client_origin = URI(@client_id).host
+      valid = client_origin == "localhost" ? true : uri.host == client_origin
+      raise InvalidClientMetadata, "redirect URI must match client_id origin" unless valid
+    end
+
+    def validate_native_redirect_uri!(uri)
+      if uri.scheme == "http"
+        unless ["127.0.0.1", "[::1]"].include?(uri.host)
+          raise InvalidClientMetadata, "HTTP redirect URIs for native clients must use loopback IP"
+        end
+      else
+        validate_custom_scheme!(uri)
+      end
+    end
+
+    def validate_custom_scheme!(uri)
+      reversed_host = URI(@client_id).host.split(".").reverse
+      scheme_parts = uri.scheme.split(".")
+      unless scheme_parts == reversed_host
+        raise InvalidClientMetadata, "custom scheme must match reversed client_id domain"
+      end
+      raise InvalidClientMetadata, "custom scheme URI must have single path component" unless uri.path == "/"
+    end
+
+    def validate_scope!(scope)
+      raise InvalidClientMetadata, "scope is required" unless scope
+
+      scope_values = scope.split
+      raise InvalidClientMetadata, "atproto scope is required" unless scope_values.include?("atproto")
+
+      # validate_offline_access_scope!(scope_values)
+      scope
+    end
+
+    def validate_offline_access_scope!(scope_values)
+      has_refresh = @grant_types&.include?("refresh_token")
+      has_offline = scope_values.include?("offline_access")
+      return unless has_refresh != has_offline
+
+      raise InvalidClientMetadata, "offline_access scope must match refresh_token grant type"
+    end
+
+    def validate_application_type(type)
+      type ||= ApplicationType::WEB # Default to web
+      unless ApplicationType::ALL.include?(type)
+        raise InvalidClientMetadata,
+              "application_type must be 'web' or 'native'"
+      end
+
+      type
+    end
+
+    def validate_client_uri(uri)
+      return unless uri
+      raise InvalidClientMetadata, "client_uri must match client_id origin" unless URI(uri).host == URI(@client_id).host
+
+      uri
+    end
+
+    def validate_https_uri(uri)
+      return unless uri
+      raise InvalidClientMetadata, "URI must use HTTPS" unless URI(uri).scheme == "https"
+
+      uri
+    end
+
+    def validate_jwks!(jwks)
+      raise InvalidClientMetadata, "jwks must have keys array" unless jwks["keys"].is_a?(Array)
+
+      jwks["keys"].each_with_index do |key, index|
+        has_key_use_sig = key["use"] == "sig"
+        has_key_ops_sign = key["key_ops"]&.include?("sign")
+        if !has_key_use_sig && !has_key_ops_sign
+          raise InvalidClientMetadata, "jwks.keys.#{index} must have use='sig' or key_ops including 'sign'"
+        end
+
+        raise InvalidClientMetadata, "jwks.keys.#{index} must have kid" unless key["kid"]
+      end
+    end
+
+    def validate_auth_methods!(metadata) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      @token_endpoint_auth_method = metadata["token_endpoint_auth_method"]
+      return unless @token_endpoint_auth_method == "private_key_jwt"
+
+      # Validate auth signing algorithm
+      @token_endpoint_auth_signing_alg = metadata["token_endpoint_auth_signing_alg"]
+      unless @token_endpoint_auth_signing_alg == "ES256"
+        raise InvalidClientMetadata, "token_endpoint_auth_signing_alg must be ES256"
+      end
+
+      @jwks = metadata["jwks"]
+      @jwks_uri = metadata["jwks_uri"]
+      raise InvalidClientMetadata, "cannot use both jwks and jwks_uri" if @jwks && @jwks_uri
+      raise InvalidClientMetadata, "confidential clients must provide jwks or jwks_uri" unless @jwks || @jwks_uri
+
+      validate_jwks!(@jwks) if @jwks
+      validate_https_uri(@jwks_uri) if @jwks_uri
+    end
+
+    def validate_dpop!(metadata)
+      return if metadata["dpop_bound_access_tokens"] == true
+
+      raise InvalidClientMetadata, "dpop_bound_access_tokens must be true"
+    end
+
+    class << self
+      private
+
+      def validate_url!(url)
+        uri = URI(url)
+        return if uri.scheme == "https" || uri.host == "localhost"
+
+        raise InvalidClientMetadata, "client_id must use HTTPS except for localhost"
+      end
+
+      def fetch_metadata(url)
+        AtprotoAuth.configuration.http_client&.get(url) ||
+          raise(InvalidClientMetadata, "HTTP client not configured")
+      end
+
+      def parse_metadata(body)
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise InvalidClientMetadata, "Invalid JSON in client metadata: #{e.message}"
+      end
+
+      def validate_client_id!(metadata_client_id, url)
+        return if metadata_client_id == url
+
+        raise InvalidClientMetadata, "client_id mismatch: #{metadata_client_id} != #{url}"
+      end
+    end
+  end
+end

data/lib/atproto_auth/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module AtprotoAuth
+  # Configuration class for global AtprotoAuth settings
+  class Configuration
+    attr_accessor :default_token_lifetime, :dpop_nonce_lifetime, :http_client, :logger
+
+    def initialize
+      @default_token_lifetime = 300 # 5 minutes in seconds
+      @dpop_nonce_lifetime = 300 # 5 minutes in seconds
+      @http_client = nil
+      @logger = Logger.new($stdout)
+    end
+  end
+end

data/lib/atproto_auth/dpop/client.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  module DPoP
+    # 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
+    class Client
+      # Error raised for DPoP client operations
+      class Error < AtprotoAuth::Error; end
+
+      # @return [KeyManager] DPoP key manager instance
+      attr_reader :key_manager
+      # @return [ProofGenerator] DPoP proof generator instance
+      attr_reader :proof_generator
+      # @return [NonceManager] DPoP nonce manager instance
+      attr_reader :nonce_manager
+
+      # Creates a new DPoP client
+      # @param key_manager [KeyManager, nil] Optional existing key manager
+      # @param nonce_ttl [Integer, nil] Optional TTL for nonces in seconds
+      def initialize(key_manager: nil, nonce_ttl: nil)
+        @key_manager = key_manager || KeyManager.new
+        @nonce_manager = NonceManager.new(ttl: nonce_ttl)
+        @proof_generator = ProofGenerator.new(@key_manager)
+      end
+
+      # Generates a DPoP proof for an HTTP request
+      # @param http_method [String] HTTP method (e.g., "POST")
+      # @param http_uri [String] Full request URI
+      # @param access_token [String, nil] Optional access token to bind to proof
+      # @return [String] The DPoP proof JWT
+      # @raise [Error] if proof generation fails
+      def generate_proof(http_method:, http_uri:, access_token: nil, nonce: nil)
+        uri = URI(http_uri)
+        server_url = "#{uri.scheme}://#{uri.host}#{":#{uri.port}" if uri.port != uri.default_port}"
+
+        # Use provided nonce or get one from the manager
+        nonce ||= @nonce_manager.get(server_url)
+
+        @proof_generator.generate(
+          http_method: http_method,
+          http_uri: http_uri,
+          nonce: nonce,
+          access_token: access_token
+        )
+      rescue StandardError => e
+        raise Error, "Failed to generate proof: #{e.message}"
+      end
+
+      # Updates stored nonce from server response
+      # @param response_headers [Hash] Response headers
+      # @param server_url [String] Server's base URL
+      # @return [void]
+      # @raise [Error] if nonce update fails
+      def process_response(response_headers, server_url)
+        return unless response_headers
+
+        # Look for DPoP-Nonce header (case insensitive)
+        nonce = response_headers.find { |k, _| k.downcase == "dpop-nonce" }&.last
+        return unless nonce
+
+        # Store new nonce for future requests
+        @nonce_manager.update(nonce: nonce, server_url: server_url)
+      rescue StandardError => e
+        raise Error, "Failed to process response: #{e.message}"
+      end
+
+      # Constructs DPoP header value for a request
+      # @param proof [String] The DPoP proof JWT
+      # @return [Hash] Headers to add to request
+      def request_headers(proof)
+        {
+          "DPoP" => proof
+        }
+      end
+
+      # Gets the current public key in JWK format
+      # @return [Hash] JWK representation of public key
+      def public_key
+        @key_manager.public_jwk
+      end
+
+      # Exports the current keypair as JWK
+      # @param include_private [Boolean] Whether to include private key
+      # @return [Hash] JWK representation of keypair
+      def export_key(include_private: false)
+        @key_manager.to_jwk(include_private: include_private)
+      end
+
+      private
+
+      def extract_nonce(headers)
+        # Headers can be hash with string or symbol keys, or http headers object
+        headers = headers.to_h if headers.respond_to?(:to_h)
+
+        # Try different common header key formats
+        nonce = headers["DPoP-Nonce"] ||
+                headers["dpop-nonce"] ||
+                headers[:dpop_nonce]
+
+        nonce&.strip
+      end
+
+      def origin_for_uri(uri)
+        port = uri.port
+        port = nil if (uri.scheme == "https" && port == 443) || (uri.scheme == "http" && port == 80)
+
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin = "#{origin}:#{port}" if port
+        origin
+      end
+    end
+  end
+end

data/lib/atproto_auth/dpop/key_manager.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  module DPoP
+    # Manages ES256 keypair generation and storage for DPoP proofs.
+    # Provides functionality to generate new keys and store them securely.
+    # Uses JOSE for cryptographic operations and key format handling.
+    class KeyManager
+      # Error raised when key operations fail
+      class KeyError < AtprotoAuth::Error; end
+
+      # Default curve for ES256 key generation
+      CURVE = "P-256"
+      # Default algorithm for key usage
+      ALGORITHM = "ES256"
+
+      # @return [JOSE::JWK] The current DPoP keypair
+      attr_reader :keypair
+
+      # Creates a new KeyManager instance with an optional existing keypair
+      # @param keypair [JOSE::JWK, nil] Optional existing keypair to use
+      # @raise [KeyError] if the provided keypair is invalid
+      def initialize(keypair = nil)
+        @keypair = keypair || 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
+
+      # Returns the public key in JWK format
+      # @return [Hash] JWK representation of the public key
+      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
+      rescue StandardError => e
+        raise KeyError, "Failed to export public key: #{e.message}"
+      end
+
+      # Signs data using the private key
+      # @param data [String] Data to sign
+      # @return [String] The signature
+      # @raise [KeyError] if signing fails
+      def sign(data)
+        @keypair.sign(data).compact
+      rescue StandardError => e
+        raise KeyError, "Failed to sign data: #{e.message}"
+      end
+
+      def sign_segments(header, payload)
+        # Deep transform all keys to strings to avoid symbol comparison issues
+        header = deep_stringify_keys(header)
+        payload = deep_stringify_keys(payload)
+
+        # Configure JOSE to use ES256 for signing
+        signing_config = { "alg" => "ES256" }
+
+        # Merge our header with JOSE's required fields
+        full_header = header.merge(signing_config)
+
+        # Convert payload to JSON string before signing
+        payload_json = JSON.generate(payload)
+
+        # Create the JWS with our header and payload
+        jws = @keypair.sign(payload_json, full_header)
+
+        # Get the compact serialization
+        jws.compact
+      rescue StandardError => e
+        raise KeyError, "Failed to sign segments: #{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
+
+      # Verifies a signed JWS
+      # @param signed_jws [String] The complete signed JWS to verify
+      # @return [Boolean] True if signature is valid
+      # @raise [KeyError] if verification fails
+      def verify(signed_jws)
+        verified, _payload, = @keypair.verify(signed_jws)
+        verified
+      rescue StandardError => e
+        raise KeyError, "Failed to verify signature: #{e.message}"
+      end
+
+      # Exports the keypair in JWK format
+      # @param include_private [Boolean] Whether to include private key
+      # @return [Hash] JWK representation of the keypair
+      # @raise [KeyError] if export fails
+      def to_jwk(include_private: false)
+        key = include_private ? @keypair : @keypair.to_public
+        key.to_map
+      rescue StandardError => e
+        raise KeyError, "Failed to export key: #{e.message}"
+      end
+
+      # Creates a KeyManager instance from a JWK
+      # @param jwk [Hash] JWK representation of a keypair
+      # @return [KeyManager] New KeyManager instance
+      # @raise [KeyError] if import fails
+      def self.from_jwk(jwk)
+        keypair = JOSE::JWK.from_map(jwk)
+        new(keypair)
+      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)
+      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)
+
+        # Verify the curve
+        curve = @keypair.to_map["crv"]
+        raise KeyError, "Invalid curve: #{curve}, must be #{CURVE}" unless curve == CURVE
+
+        # Verify we can perform basic operations
+        test_data = "test"
+        signed = sign(test_data)
+        raise KeyError, "Key validation failed: signature verification error" unless verify(signed)
+      rescue StandardError => e
+        raise KeyError, "Key validation failed: #{e.message}"
+      end
+
+      def sign_message(message)
+        # Create SHA-256 digest of message
+        digest = OpenSSL::Digest::SHA256.digest(message)
+
+        # Get EC key from JOSE JWK
+        ec_key = extract_ec_key
+
+        # Sign using ECDSA
+        signature = ec_key.sign(OpenSSL::Digest.new("SHA256"), digest)
+
+        # Convert to raw r|s format required for JWTs
+        asn1_to_raw(signature)
+      end
+
+      def extract_ec_key # rubocop:disable Metrics/AbcSize
+        # Extract the raw EC key from JOSE JWK
+        key_data = @keypair.to_map
+        raise KeyError, "Private key required for signing" unless key_data["d"] # Private key component
+
+        group = OpenSSL::PKey::EC::Group.new("prime256v1")
+        key = OpenSSL::PKey::EC.new(group)
+
+        # Convert base64url to hex string for BN
+        d = bin_to_hex(Base64.urlsafe_decode64(key_data["d"]))
+        x = bin_to_hex(Base64.urlsafe_decode64(key_data["x"]))
+        y = bin_to_hex(Base64.urlsafe_decode64(key_data["y"]))
+
+        # Create BNs from hex strings
+        key.private_key = OpenSSL::BN.new(d, 16)
+
+        # Set public key point
+        point = OpenSSL::PKey::EC::Point.new(group)
+        point.set_to_keypair(x, y)
+        key.public_key = point
+
+        key
+      end
+
+      def bin_to_hex(binary)
+        binary.unpack1("H*")
+      end
+
+      def asn1_to_raw(signature)
+        # Parse ASN.1 signature
+        asn1 = OpenSSL::ASN1.decode(signature)
+        r = asn1.value[0].value.to_s(2)
+        s = asn1.value[1].value.to_s(2)
+
+        # Pad r and s to 32 bytes each
+        r = r.rjust(32, "\x00")
+        s = s.rjust(32, "\x00")
+
+        # Concatenate r|s
+        r + s
+      end
+    end
+  end
+end