authproto 0.3.0.beta1

data/lib/authproto/client_metadata.rb

@@ -0,0 +1,478 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+require_relative 'configuration'
+require_relative 'errors'
+
+module AuthProto
+
+  #
+  # Supported OAuth application types used by {ClientMetadata}.
+  #
+
+  module ApplicationType
+
+    # Application type for browser-based OAuth client applications
+    WEB = "web"
+
+    # Application type for native desktop or mobile OAuth client applications
+    NATIVE = "native"
+
+    # Supported application type values.
+    # @return [Array<String>]
+    ALL = [WEB, 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
+
+    # Client authentication method for confidential clients
+    AUTH_METHOD_PRIVATE_KEY_JWT = "private_key_jwt"
+
+    # Client authentication method value for public clients
+    AUTH_METHOD_NONE = "none"
+
+    # RFC 6749 scope-token characters, separated by single ASCII spaces.
+    SCOPE_PATTERN = /\A[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*\z/
+
+
+    # -- required fields --
+
+    # Client metadata URL or localhost client identifier. **Required**.
+    # @return [String]
+    attr_reader :client_id
+
+    # List of allowed grant types. ATProto requires `authorization_code` and supports `refresh_token`. **Required**.
+    # @return [Array<String>]
+    attr_reader :grant_types
+
+    # List of supported response types. In ATProto, it must include `code`. **Required**.
+    # @return [Array<String>]
+    attr_reader :response_types
+
+    # List of registered OAuth callback URIs. **Required**.
+    # @return [Array<String>]
+    attr_reader :redirect_uris
+
+    # Space-separated list of supported OAuth scopes. Must include at least `atproto`. **Required**.
+    # @return [String]
+    attr_reader :scope
+
+    # Client authentication method: `none` for public clients, or `private_key_jwt` for confidential ones.
+    # Not technically required, but the reference PDS sets it to `client_secret_basic` if not set,
+    # which we don't support.
+    # @return [String]
+    attr_reader :token_endpoint_auth_method
+
+
+    # -- optional fields --
+
+    # Application type: `web` (default) or `native`.
+    # @return [String]
+    attr_reader :application_type
+
+    # Public name of the client application that is presented to the user, if supplied.
+    # @return [String, nil]
+    attr_reader :client_name
+
+    # URL of the client application's home page, if supplied.
+    # @return [String, nil]
+    attr_reader :client_uri
+
+    # URL to the client application's logo image, if supplied.
+    # @return [String, nil]
+    attr_reader :logo_uri
+
+    # URL to human-readable terms of service of the client, if supplied.
+    # @return [String, nil]
+    attr_reader :tos_uri
+
+    # URL to human-readable privacy policy of the client, if supplied.
+    # @return [String, nil]
+    attr_reader :policy_uri
+
+    # Inline set of JWK keys for confidential clients, if supplied.
+    # @return [Hash{String => Object}, nil]
+    attr_reader :jwks
+
+    # HTTPS URL to a set of JWK keys for confidential clients, if supplied.
+    # @return [String, nil]
+    attr_reader :jwks_uri
+
+
+    # Validates string-keyed client metadata and exposes its fields.
+    #
+    # Requires `client_id`, `grant_types`, `response_types`, `redirect_uris`, `scope`,
+    # `token_endpoint_auth_method`, and `dpop_bound_access_tokens: true`.
+    # `application_type` defaults to `web`.
+    # Confidential clients using `private_key_jwt` require `ES256` and a JWK set or URI.
+    #
+    # @param metadata [Hash{String => Object}] parsed OAuth client metadata
+    # @raise [InvalidClientMetadata] if a required field or supported value is invalid
+    # @raise [URI::InvalidURIError] if a metadata URI cannot be parsed
+    #
+    def initialize(metadata)
+      validate_and_set_metadata(metadata)
+    end
+
+    # Fetches and validates a client metadata document using the configured transport.
+    #
+    # Requires HTTP 200 and application/json, without following redirects.
+    # The document's `client_id` must equal the requested URL.
+    #
+    # @param url [String] HTTPS metadata URL, or localhost URL for development
+    # @return [ClientMetadata] validated metadata
+    # @raise [InvalidClientMetadata] if metadata is missing, invalid/mismatched, not JSON, or transport isn't configured
+    # @raise [HTTPClient::HTTPError, HTTPClient::SSRFError] if the transport rejects/fails the request
+    # @raise [URI::InvalidURIError] if a URL cannot be parsed
+    #
+    def self.from_url(url)
+      uri = URI(url)
+
+      unless uri.scheme == 'https' || (uri.scheme == 'http' && uri.host == 'localhost')
+        raise InvalidClientMetadata, "client_id must use HTTPS except for localhost"
+      end
+
+      raise InvalidClientMetadata, "HTTP client not configured" unless AuthProto.configuration.http_client
+
+      response = AuthProto.configuration.http_client.get(url, follow_redirects: false)
+
+      unless response[:status] == 200
+        raise InvalidClientMetadata, "expected HTTP 200 response for client metadata request, got #{response[:status]}"
+      end
+
+      content_type = (response[:headers] || {}).find { |name, _| name.downcase == 'content-type' }&.last
+
+      unless content_type.to_s.split(';', 2).first.to_s.strip.downcase == 'application/json'
+        raise InvalidClientMetadata, "client metadata Content-Type must be application/json"
+      end
+
+      raise InvalidClientMetadata, "client metadata request returned response with no body" if response[:body].nil?
+
+      metadata = JSON.parse(response[:body])
+      raise InvalidClientMetadata, "metadata must be a hash" unless metadata.is_a?(Hash)
+
+      if metadata['client_id'] != url
+        raise InvalidClientMetadata, "client_id mismatch: #{metadata['client_id']} != #{url}"
+      end
+
+      self.new(metadata)
+    rescue JSON::ParserError => e
+      raise InvalidClientMetadata, "Invalid JSON in client metadata: #{e.message}"
+    end
+
+    # Determines if the client is confidential (has authentication keys).
+    # @return [Boolean] true if client is confidential.
+    #
+    def confidential?
+      token_endpoint_auth_method == AUTH_METHOD_PRIVATE_KEY_JWT
+    end
+
+
+    private
+
+    def validate_and_set_metadata(metadata)
+      raise InvalidClientMetadata, "metadata must be a hash" unless metadata.is_a?(Hash)
+
+      # Optional (defaults to "web"), but must be set before validating redirect URIs
+      @application_type = validate_application_type(metadata["application_type"])
+
+      # Required fields
+      @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"])
+
+      # Check dpop_bound_access_tokens
+      validate_dpop(metadata)
+
+      # Optional fields
+      @client_name = validate_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"])
+
+      # Check token_endpoint_auth_method and jwks
+      validate_auth_methods(metadata)
+    end
+
+
+    # -- Required field validations --
+
+    def validate_client_id(client_id)
+      raise InvalidClientMetadata, "client_id is required" unless client_id
+      raise InvalidClientMetadata, "client_id must be a string" unless client_id.is_a?(String)
+
+      unless valid_https_client_id?(client_id) || valid_localhost_client_id?(client_id)
+        raise InvalidClientMetadata, "client_id must be HTTPS or localhost HTTP URL"
+      end
+
+      client_id
+    end
+
+    def valid_https_client_id?(client_id)
+      uri = URI(client_id)
+      userinfo, port = URI.split(client_id).values_at(1, 3)
+
+      uri.scheme == 'https' && uri.host.to_s != '' && port.nil? && userinfo.nil? && !uri.fragment
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def valid_localhost_client_id?(client_id)
+      uri = URI(client_id)
+      userinfo, port = URI.split(client_id).values_at(1, 3)
+
+      uri.scheme == 'http' && uri.host == 'localhost' && port.nil? && userinfo.nil? && !uri.fragment &&
+        uri.path.to_s.chomp('/').empty?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def validate_grant_types(grant_types)
+      raise InvalidClientMetadata, "grant_types is required" unless grant_types
+      raise InvalidClientMetadata, "grant_types must be an array" unless grant_types.is_a?(Array)
+
+      unless grant_types.include?('authorization_code')
+        raise InvalidClientMetadata, "grant_types must include authorization_code"
+      end
+
+      valid_types = %w[authorization_code refresh_token]
+
+      grant_types.each do |grant|
+        raise InvalidClientMetadata, "unsupported grant type" unless valid_types.include?(grant)
+      end
+
+      grant_types
+    end
+
+    def validate_response_types(response_types)
+      raise InvalidClientMetadata, "response_types is required" unless response_types
+      raise InvalidClientMetadata, "response_types must be an array" unless response_types.is_a?(Array)
+      raise InvalidClientMetadata, "response_types must include 'code'" unless response_types.include?("code")
+
+      unless response_types.all? { |type| type.is_a?(String) }
+        raise InvalidClientMetadata, "response_types must contain only strings"
+      end
+
+      response_types
+    end
+
+    def validate_redirect_uris(uris)
+      raise InvalidClientMetadata, "redirect_uris is required" unless uris
+      raise InvalidClientMetadata, "redirect_uris must be an array" unless uris.is_a?(Array)
+      raise InvalidClientMetadata, "redirect_uris must not be empty" if uris.empty?
+
+      uris.each { |uri| validate_redirect_uri(uri) }
+      uris
+    end
+
+    def validate_redirect_uri(value)
+      raise InvalidClientMetadata, "redirect_uris entries must be strings" unless value.is_a?(String)
+
+      uri = URI(value)
+      userinfo, port = URI.split(value).values_at(1, 3)
+
+      raise InvalidClientMetadata, "redirect URI must be absolute" unless uri.absolute?
+      raise InvalidClientMetadata, "redirect URI must not contain credentials" unless userinfo.nil?
+      raise InvalidClientMetadata, "redirect URI must not contain a fragment" unless uri.fragment.nil?
+
+      case application_type
+      when ApplicationType::WEB
+        validate_https_redirect_uri(uri, port)
+      when ApplicationType::NATIVE
+        validate_native_redirect_uri(uri, port)
+      end
+    rescue URI::InvalidURIError => e
+      raise InvalidClientMetadata, "Invalid redirect URI: #{e.message}"
+    end
+
+    def validate_https_redirect_uri(uri, port)
+      unless uri.scheme == 'https' && !uri.host.to_s.empty?
+        raise InvalidClientMetadata, "redirect URI must use HTTPS with a hostname"
+      end
+
+      if port && uri.port == 443
+        raise InvalidClientMetadata, "HTTPS redirect URI must not specify the default port"
+      end
+    end
+
+    def validate_redirect_uri_origin(uri)
+      client_uri = URI(@client_id)
+
+      unless uri.origin.downcase == client_uri.origin.downcase
+        raise InvalidClientMetadata, "redirect URI must match client_id origin"
+      end
+    end
+
+    def validate_native_redirect_uri(uri, port)
+      case uri.scheme
+      when 'https'
+        validate_https_redirect_uri(uri, port)
+        validate_redirect_uri_origin(uri)
+      when '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.downcase.split('.').reverse.join('.')
+
+      unless uri.scheme.include?('.') && uri.scheme == reversed_host
+        raise InvalidClientMetadata, "custom scheme must match reversed client_id domain"
+      end
+
+      unless uri.host.nil? && uri.path && uri.path.start_with?('/')
+        raise InvalidClientMetadata, "custom scheme redirect URI must use a single slash after the scheme"
+      end
+    end
+
+    def validate_scope(scope)
+      raise InvalidClientMetadata, "scope is required" unless scope
+      raise InvalidClientMetadata, "scope must be a string" unless scope.is_a?(String)
+      raise InvalidClientMetadata, "scope must contain valid tokens separated by single spaces" unless SCOPE_PATTERN.match?(scope)
+
+      scope_values = scope.split(' ')
+      raise InvalidClientMetadata, "atproto scope is required" unless scope_values.include?("atproto")
+
+      scope
+    end
+
+    def validate_dpop(metadata)
+      unless metadata["dpop_bound_access_tokens"] == true
+        raise InvalidClientMetadata, "dpop_bound_access_tokens must be true"
+      end
+    end
+
+
+    # -- Optional field validations --
+
+    def validate_application_type(type)
+      if ApplicationType::ALL.include?(type)
+        type
+      elsif type.nil?
+        ApplicationType::WEB
+      else
+        raise InvalidClientMetadata, "application_type must be 'web' or 'native'"
+      end
+    end
+
+    def validate_client_name(name)
+      return if name.nil?
+      raise InvalidClientMetadata, "client_name must be a string, if provided" unless name.is_a?(String)
+
+      name
+    end
+
+    def validate_client_uri(uri)
+      return if uri.nil?
+      raise InvalidClientMetadata, "client_uri must be a string" unless uri.is_a?(String)
+
+      parsed = URI(uri)
+
+      unless %w[http https].include?(parsed.scheme)
+        raise InvalidClientMetadata, "client_uri must use HTTP or HTTPS"
+      end
+
+      unless URI(uri).origin == URI(@client_id).origin
+        raise InvalidClientMetadata, "client_uri must have the same hostname as client_id"
+      end
+
+      uri
+    end
+
+    def validate_https_uri(uri)
+      return if uri.nil?
+
+      raise InvalidClientMetadata, "URI must be a string" unless uri.is_a?(String)
+
+      parsed = URI(uri)
+      raise InvalidClientMetadata, "URI must use HTTPS" unless parsed.scheme == "https" && !parsed.host.to_s.empty?
+
+      uri
+    end
+
+    def validate_jwks(jwks)
+      raise InvalidClientMetadata, "jwks must be a hash" unless jwks.is_a?(Hash)
+      raise InvalidClientMetadata, "jwks must have a 'keys' array" unless jwks['keys'].is_a?(Array)
+
+      jwks['keys'].each_with_index do |key, index|
+        raise InvalidClientMetadata, "jwks.keys.#{index} must be a hash" unless key.is_a?(Hash)
+
+        if key.key?('key_ops') && !key['key_ops'].is_a?(Array)
+          raise InvalidClientMetadata, "jwks.keys.#{index}.key_ops must be an array"
+        end
+
+        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 a 'kid' field" unless key['kid']
+      end
+    end
+
+
+    # -- Auth fields validations --
+
+    def validate_auth_methods(metadata)
+      @token_endpoint_auth_method = metadata["token_endpoint_auth_method"]
+      @token_endpoint_auth_signing_alg = metadata["token_endpoint_auth_signing_alg"]
+
+      raise InvalidClientMetadata, "token_endpoint_auth_method is required" if @token_endpoint_auth_method.nil?
+
+      case @token_endpoint_auth_method
+      when AUTH_METHOD_NONE
+        validate_auth_public(metadata)
+      when AUTH_METHOD_PRIVATE_KEY_JWT
+        validate_auth_confidential(metadata)
+      else
+        raise InvalidClientMetadata, "unsupported token_endpoint_auth_method"
+      end
+    end
+
+    def validate_auth_public(metadata)
+      unless @token_endpoint_auth_signing_alg.nil?
+        raise InvalidClientMetadata, "token_endpoint_auth_signing_alg must be unset for public clients"
+      end
+    end
+
+    def validate_auth_confidential(metadata)
+      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
+  end
+end

data/lib/authproto/configuration.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+require_relative 'errors'
+require_relative 'storage/interface'
+
+module AuthProto
+  class << self
+
+    # Global settings object, replaced without validation.
+    #
+    # @param value [Configuration] replacement global settings
+    # @return [Configuration]
+    #
+    attr_writer :configuration
+
+    # Returns the process-wide configuration, creating defaults on first access.
+    #
+    # The default storage is in memory; `http_client` is initially `nil` and must be
+    # configured before discovery or OAuth requests.
+    #
+    # @return [Configuration] current global settings
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the global configuration, validates it, and returns it.
+    #
+    # Changes remain on the global object even if validation fails.
+    #
+    # @yield [config] block that changes settings
+    # @yieldparam config [Configuration] mutable global settings
+    # @yieldreturn [Object] ignored
+    # @return [Configuration] validated global settings
+    # @raise [ConfigurationError] if the storage or HTTP client is invalid
+    # @example Configure the default transport
+    #   AuthProto.configure do |config|
+    #     config.http_client = AuthProto::HTTPClient.new
+    #   end
+    #
+    def configure
+      yield(configuration)
+      configuration.validate
+      configuration
+    end
+
+    # Gets the configured storage backend
+    # @return [Storage::Interface] The configured storage implementation
+    def storage
+      configuration.storage
+    end
+
+    # Replaces the global configuration with a fresh set of defaults.
+    # Existing client instances and their dependencies are not rebuilt.
+    #
+    # @return [Configuration] new global settings
+    #
+    def reset_configuration
+      @configuration = Configuration.new
+    end
+  end
+
+  # Raised when global storage or HTTP transport settings are invalid.
+  class ConfigurationError < Error; end
+
+  #
+  # Configuration class for global AuthProto settings
+  #
+
+  class Configuration
+
+    # Configured default token lifetime in seconds (300); currently unused by token exchange.
+    # @return [Integer]
+    attr_accessor :default_token_lifetime
+
+    # Configured default nonce lifetime in seconds (300); nonce managers currently use their own TTL.
+    # @return [Integer]
+    attr_accessor :dpop_nonce_lifetime
+
+    # Reserved encryption setting; serializers currently create their own service.
+    # @return [Object, nil]
+    attr_accessor :encryption
+
+    # Transport used for discovery, PAR and token requests; initially `nil`.
+    # @return [#get, #post, nil]
+    attr_accessor :http_client
+
+    # Logger used for diagnostics; defaults to standard output.
+    # @return [Logger]
+    attr_accessor :logger
+
+    # Storage backend; defaults to a new {Storage::Memory}.
+    # @return [Storage::Interface]
+    attr_accessor :storage
+
+    # Creates default settings with in-memory storage and no HTTP transport.
+    #
+    def initialize
+      @default_token_lifetime = 300 # 5 minutes in seconds
+      @dpop_nonce_lifetime = 300 # 5 minutes in seconds
+      @encryption = nil
+      @http_client = nil
+      @logger = Logger.new($stdout)
+      @storage = AuthProto::Storage::Memory.new
+    end
+
+    # Checks that storage implements the interface and the transport supports GET/POST.
+    #
+    # A `nil` HTTP client is accepted, but cannot perform OAuth or discovery requests.
+    #
+    # @return [true] if validation succeeds
+    # @raise [ConfigurationError] if storage is absent/invalid or transport methods are missing
+    #
+    def validate
+      validate_storage
+      validate_http_client
+      true
+    end
+
+
+    private
+
+    def validate_storage
+      raise ConfigurationError, "Storage must be configured" if @storage.nil?
+      return if @storage.is_a?(AuthProto::Storage::Interface)
+
+      raise ConfigurationError, "Storage must implement Storage::Interface"
+    end
+
+    def validate_http_client
+      return if @http_client.nil? # Allow nil for testing
+      return if @http_client.respond_to?(:get) && @http_client.respond_to?(:post)
+
+      raise ConfigurationError, "HTTP client must implement get and post methods"
+    end
+  end
+end