authproto 0.3.0.beta1

data/lib/authproto/server_metadata/authorization_server.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+require_relative '../configuration'
+require_relative '../errors'
+require_relative '../http_client'
+require_relative '../server_metadata'
+require_relative 'origin_url'
+
+module AuthProto
+  module ServerMetadata
+
+    #
+    # Handles fetching and validation of AT Protocol OAuth Authorization Server metadata.
+    # An Authorization Server in atproto can be either a PDS instance or a separate "entryway" server
+    # that handles authentication for multiple PDS instances.
+    #
+    # The Authorization Server metadata is fetched from the well-known endpoint
+    # /.well-known/oauth-authorization-server and must conform to RFC 8414 plus additional
+    # requirements specific to the AT Protocol OAuth profile.
+    #
+    # @example Fetching and validating Authorization Server metadata
+    #   begin
+    #     auth_server = AuthProto::ServerMetadata::AuthorizationServer.from_issuer("https://auth.example.com")
+    #     puts "Authorization endpoint: #{auth_server.authorization_endpoint}"
+    #     puts "Supported scopes: #{auth_server.scopes_supported}"
+    #   rescue AuthProto::InvalidAuthorizationServer => e
+    #     puts "Failed to validate authorization server: #{e.message}"
+    #   end
+    #
+    # @see https://atproto.com/specs/oauth#authorization-servers Documentation of Authorization Server requirements
+    #
+
+    class AuthorizationServer
+
+      # Metadata keys that must be present before capability validation.
+      # @return [Array<String>]
+      REQUIRED_FIELDS = %w[
+        issuer
+        authorization_endpoint
+        token_endpoint
+        response_types_supported
+        grant_types_supported
+        code_challenge_methods_supported
+        token_endpoint_auth_methods_supported
+        token_endpoint_auth_signing_alg_values_supported
+        scopes_supported
+        dpop_signing_alg_values_supported
+        pushed_authorization_request_endpoint
+      ].freeze
+
+      # Authorization server issuer origin.
+      # @return [String]
+      attr_reader :issuer
+
+      # HTTPS browser authorization endpoint.
+      # @return [String]
+      attr_reader :authorization_endpoint
+
+      # HTTPS token exchange and refresh endpoint.
+      # @return [String]
+      attr_reader :token_endpoint
+
+      # HTTPS PAR endpoint.
+      # @return [String]
+      attr_reader :pushed_authorization_request_endpoint
+
+      # Supported response types, including `code`.
+      # @return [Array<String>]
+      attr_reader :response_types_supported
+
+      # Supported grant types, including authorization code and refresh token.
+      # @return [Array<String>]
+      attr_reader :grant_types_supported
+
+      # Supported PKCE methods, including `S256`.
+      # @return [Array<String>]
+      attr_reader :code_challenge_methods_supported
+
+      # Supported client authentication methods.
+      # @return [Array<String>]
+      attr_reader :token_endpoint_auth_methods_supported
+
+      # Supported client assertion algorithms.
+      # @return [Array<String>]
+      attr_reader :token_endpoint_auth_signing_alg_values_supported
+
+      # Supported scopes, including `atproto`.
+      # @return [Array<String>]
+      attr_reader :scopes_supported
+
+      # Supported DPoP algorithms, including `ES256`.
+      # @return [Array<String>]
+      attr_reader :dpop_signing_alg_values_supported
+
+      # Validates an authorization server's OAuth metadata.
+      #
+      # @param metadata [Hash{String => Object}] parsed discovery document with the fields in {REQUIRED_FIELDS} and required Boolean capabilities
+      # @raise [InvalidAuthorizationServer] if required capabilities, issuer or endpoint schemes are invalid
+      # @raise [URI::InvalidURIError] if a metadata URL cannot be parsed
+      #
+      def initialize(metadata)
+        validate_and_set_metadata(metadata)
+      end
+
+      # Fetches `/.well-known/oauth-authorization-server` using the configured transport.
+      #
+      # The document's issuer must exactly match the requested issuer.
+      #
+      # @param issuer [String] authorization server issuer origin
+      # @return [AuthorizationServer] validated discovery metadata
+      # @raise [InvalidAuthorizationServer] if HTTP transport fails, JSON is invalid, or metadata/issuer validation fails
+      # @raise [HTTPClient::SSRFError] if the transport rejects the initial destination
+      # @raise [URI::InvalidURIError] if the issuer or a metadata URI cannot be parsed
+      #
+      def self.from_issuer(issuer)
+        response = fetch_metadata(issuer)
+        metadata = parse_metadata(response[:body])
+        validate_issuer(metadata["issuer"], issuer)
+        new(metadata)
+      end
+
+      # Exports metadata for serialization using symbol keys.
+      #
+      # Includes issuer/endpoints (String), capability lists (Array<String>), and the
+      # three required Boolean flags set to `true`. Use JSON serialization to obtain
+      # string keys suitable for passing back to {#initialize}.
+      #
+      # @return [Hash{Symbol => String, Array<String>, Boolean}] authorization server metadata
+      #
+      def to_h
+        {
+          issuer: issuer,
+          authorization_endpoint: authorization_endpoint,
+          token_endpoint: token_endpoint,
+          pushed_authorization_request_endpoint: pushed_authorization_request_endpoint,
+          response_types_supported: response_types_supported,
+          grant_types_supported: grant_types_supported,
+          code_challenge_methods_supported: code_challenge_methods_supported,
+          token_endpoint_auth_methods_supported: token_endpoint_auth_methods_supported,
+          token_endpoint_auth_signing_alg_values_supported: token_endpoint_auth_signing_alg_values_supported,
+          scopes_supported: scopes_supported,
+          dpop_signing_alg_values_supported: dpop_signing_alg_values_supported,
+          authorization_response_iss_parameter_supported: true,
+          require_pushed_authorization_requests: true,
+          client_id_metadata_document_supported: true
+        }
+      end
+
+      private
+
+      def validate_and_set_metadata(metadata)
+        REQUIRED_FIELDS.each do |field|
+          raise InvalidAuthorizationServer, "#{field} is required" unless metadata[field]
+        end
+
+        @issuer = validate_issuer(metadata["issuer"])
+        @authorization_endpoint = validate_https_url(metadata["authorization_endpoint"])
+        @token_endpoint = validate_https_url(metadata["token_endpoint"])
+        @pushed_authorization_request_endpoint = validate_https_url(metadata["pushed_authorization_request_endpoint"])
+
+        validate_response_types(metadata["response_types_supported"])
+        validate_grant_types(metadata["grant_types_supported"])
+        validate_code_challenge_methods(metadata["code_challenge_methods_supported"])
+        validate_token_endpoint_auth_methods(metadata["token_endpoint_auth_methods_supported"])
+        validate_token_endpoint_auth_signing_algs(metadata["token_endpoint_auth_signing_alg_values_supported"])
+        validate_dpop_signing_algs(metadata["dpop_signing_alg_values_supported"])
+        validate_scopes(metadata["scopes_supported"])
+
+        # Store validated values
+        @response_types_supported = metadata["response_types_supported"]
+        @grant_types_supported = metadata["grant_types_supported"]
+        @code_challenge_methods_supported = metadata["code_challenge_methods_supported"]
+        @token_endpoint_auth_methods_supported = metadata["token_endpoint_auth_methods_supported"]
+        @token_endpoint_auth_signing_alg_values_supported = metadata["token_endpoint_auth_signing_alg_values_supported"]
+        @scopes_supported = metadata["scopes_supported"]
+        @dpop_signing_alg_values_supported = metadata["dpop_signing_alg_values_supported"]
+
+        # Required boolean fields
+        validate_boolean_field(metadata, "authorization_response_iss_parameter_supported", true)
+        validate_boolean_field(metadata, "require_pushed_authorization_requests", true)
+        validate_boolean_field(metadata, "client_id_metadata_document_supported", true)
+      end
+
+      def validate_issuer(issuer)
+        is_valid = OriginURL.new(issuer).valid?
+        raise InvalidAuthorizationServer, "invalid issuer URL format" unless is_valid
+
+        issuer
+      end
+
+      def validate_https_url(url)
+        uri = URI(url)
+        raise InvalidAuthorizationServer, "URL must use HTTPS" unless uri.scheme == "https"
+
+        url
+      end
+
+      def validate_response_types(types)
+        raise InvalidAuthorizationServer, "must support 'code' response type" unless types.include?("code")
+      end
+
+      def validate_grant_types(types)
+        required = %w[authorization_code refresh_token]
+        missing = required - types
+        raise InvalidAuthorizationServer, "missing grant types: #{missing.join(", ")}" if missing.any?
+      end
+
+      def validate_code_challenge_methods(methods)
+        raise InvalidAuthorizationServer, "must support S256 PKCE" unless methods.include?("S256")
+      end
+
+      def validate_token_endpoint_auth_methods(methods)
+        required = %w[private_key_jwt none]
+        missing = required - methods
+        raise InvalidAuthorizationServer, "missing auth methods: #{missing.join(", ")}" if missing.any?
+      end
+
+      def validate_token_endpoint_auth_signing_algs(algs)
+        raise InvalidAuthorizationServer, "must support ES256" unless algs.include?("ES256")
+        raise InvalidAuthorizationServer, "must not allow 'none'" if algs.include?("none")
+      end
+
+      def validate_dpop_signing_algs(algs)
+        raise InvalidAuthorizationServer, "must support ES256 for DPoP" unless algs.include?("ES256")
+      end
+
+      def validate_scopes(scopes)
+        required = %w[atproto]
+        missing = required - scopes
+        raise InvalidAuthorizationServer, "missing scopes: #{missing.join(", ")}" if missing.any?
+      end
+
+      def validate_boolean_field(metadata, field, required_value)
+        actual = metadata[field]
+        return if actual == required_value
+
+        raise InvalidAuthorizationServer, "#{field} must be #{required_value}"
+      end
+
+      class << self
+        private
+
+        def fetch_metadata(issuer)
+          metadata_url = URI.join(issuer, "/.well-known/oauth-authorization-server")
+          AuthProto.configuration.http_client.get(metadata_url.to_s)
+        rescue HTTPClient::HTTPError => e
+          raise InvalidAuthorizationServer, "Failed to fetch authorization server metadata: #{e.message}"
+        end
+
+        def parse_metadata(body)
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise InvalidAuthorizationServer, "Invalid JSON in authorization server metadata: #{e.message}"
+        end
+
+        def validate_issuer(metadata_issuer, request_issuer)
+          return if metadata_issuer == request_issuer
+
+          raise InvalidAuthorizationServer, "issuer mismatch: #{metadata_issuer} != #{request_issuer}"
+        end
+      end
+    end
+  end
+end

data/lib/authproto/server_metadata/origin_url.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative '../server_metadata'
+
+module AuthProto
+  module ServerMetadata
+
+    #
+    # The `OriginURL` class provides validation logic for URLs that must conform
+    # to the AT Protocol OAuth "simple origin URL" requirements. These requirements
+    # are common between Resource and Authorization Servers and ensure that the URL
+    # is valid and secure for use in the protocol. This class validates that the URL:
+    # - Uses the HTTPS scheme.
+    # - Points to the root path (either an empty path or "/").
+    # - Does not include a query string or fragment.
+    # - Does not include user or password credentials.
+    # - May include a non-default port but disallows the default HTTPS port (443).
+    #
+    # This model centralizes the URL validation logic to promote reusability and
+    # consistency between different server classes.
+    #
+
+    class OriginURL
+
+      # Original URL string supplied by the caller.
+      # @return [String]
+      attr_reader :url
+
+      # Parsed URI used for origin validation.
+      # @return [URI::Generic]
+      attr_reader :uri
+
+      # Parses a candidate server origin; call {#valid?} to check origin restrictions.
+      #
+      # @param url [String] origin URL to parse
+      # @raise [URI::InvalidURIError] if the input cannot be parsed as a URI
+      #
+      def initialize(url)
+        @url = url
+        @uri = URI(url)
+      end
+
+      # Determines if a URL conforms to AT Protocol OAuth "simple origin URL" requirements
+      # @return [Boolean] true if the URL is a valid origin URL
+      def valid?
+        https_scheme? &&
+          root_path? &&
+          !uri.query &&
+          !uri.fragment &&
+          !uri.userinfo &&
+          (!explicit_port? || uri.port != 443)
+      end
+
+      private
+
+      def https_scheme?
+        uri.scheme == "https"
+      end
+
+      def root_path?
+        uri.path.empty? || uri.path == "/"
+      end
+
+      def explicit_port?
+        url.match?(/:\d+/)
+      end
+    end
+  end
+end

data/lib/authproto/server_metadata/resource_server.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+require_relative '../configuration'
+require_relative '../errors'
+require_relative '../http_client'
+require_relative '../server_metadata'
+require_relative 'origin_url'
+
+module AuthProto
+  module ServerMetadata
+
+    #
+    # This class represents a Resource Server (PDS) and is responsible for
+    # validating and managing its metadata. It ensures that the authorization
+    # server URLs provided are valid and compliant with expected standards.
+    # The class also includes functionality to fetch and parse metadata from a
+    # remote URL, raising specific errors for invalid or malformed metadata.
+    #
+
+    class ResourceServer
+
+      # Authorization server origins; validation requires exactly one entry.
+      # @return [Array<String>]
+      attr_reader :authorization_servers
+
+      # Validates resource server metadata and its single authorization server origin.
+      #
+      # @param metadata [Hash{String => Object}] discovery document containing `authorization_servers`
+      # @raise [InvalidAuthorizationServer] if the list is missing or does not contain one valid origin
+      # @raise [URI::InvalidURIError] if the authorization server URI cannot be parsed
+      #
+      def initialize(metadata)
+        @authorization_servers = validate_authorization_servers(metadata["authorization_servers"])
+      end
+
+      # Fetches `/.well-known/oauth-protected-resource` using the configured transport.
+      #
+      # @param url [String] resource server/PDS base URL
+      # @return [ResourceServer] validated resource server metadata
+      # @raise [InvalidAuthorizationServer] if HTTP transport, JSON parsing or metadata validation fails
+      # @raise [HTTPClient::SSRFError] if the transport rejects the initial destination
+      # @raise [URI::InvalidURIError] if the PDS or authorization server URL cannot be parsed
+      #
+      def self.from_url(url)
+        response = fetch_metadata(url)
+        new(parse_metadata(response[:body]))
+      end
+
+
+      private
+
+      def validate_authorization_servers(servers)
+        ensure_servers_exist(servers)
+        ensure_exactly_one_server(servers)
+        validate_server_url_format(servers.first)
+        servers
+      end
+
+      def ensure_servers_exist(servers)
+        return if servers.is_a?(Array)
+
+        raise InvalidAuthorizationServer, "authorization_servers missing"
+      end
+
+      def ensure_exactly_one_server(servers)
+        return if servers.size == 1
+
+        raise InvalidAuthorizationServer, "must have exactly one authorization server"
+      end
+
+      def validate_server_url_format(server_url)
+        return if OriginURL.new(server_url).valid?
+
+        raise InvalidAuthorizationServer, "invalid authorization server URL format for #{server_url}"
+      end
+
+      class << self
+        private
+
+        def fetch_metadata(url)
+          metadata_url = URI.join(url, "/.well-known/oauth-protected-resource")
+          AuthProto.configuration.http_client.get(metadata_url.to_s)
+        rescue HTTPClient::HTTPError => e
+          raise InvalidAuthorizationServer, "Failed to fetch resource server metadata: #{e.message}"
+        end
+
+        def parse_metadata(body)
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise InvalidAuthorizationServer, "Invalid JSON in resource server metadata: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/authproto/server_metadata.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AuthProto
+
+  #
+  # Provides functionality for fetching and validating AT Protocol OAuth server metadata
+  # from both Resource Servers (PDS instances) and Authorization Servers (PDS/entryway).
+  #
+  # The flow for resolving an account's authorization server is:
+  # 1. Start with PDS URL
+  # 2. Fetch Resource Server metadata from /.well-known/oauth-protected-resource
+  # 3. Get Authorization Server URL from authorization_servers array
+  # 4. Fetch Authorization Server metadata from /.well-known/oauth-authorization-server
+  #
+  # @example Resolving authorization server from PDS URL
+  #   resource_server = AuthProto::ServerMetadata::ResourceServer.from_url("https://pds.example.com")
+  #   auth_server_url = resource_server.authorization_servers.first
+  #   auth_server = AuthProto::ServerMetadata::AuthorizationServer.from_issuer(auth_server_url)
+  #
+  # The module includes three main classes:
+  # - {ResourceServer} - Handles PDS metadata validation and authorization server discovery
+  # - {AuthorizationServer} - Handles authorization server metadata validation
+  # - {OriginURL} - Validates URLs conform to AT Protocol's "simple origin URL" requirements
+  #
+
+  module ServerMetadata
+  end
+end

data/lib/authproto/state/session.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'monitor'
+require 'securerandom'
+
+require_relative '../pkce'
+require_relative '../state'
+
+module AuthProto
+  module State
+
+    #
+    # Tracks state for an OAuth authorization flow session
+    #
+
+    class Session
+      include MonitorMixin
+
+      # Unique identifier used to retrieve this session.
+      # @return [String]
+      attr_reader :session_id
+
+      # Random OAuth state token for callback validation.
+      # @return [String]
+      attr_reader :state_token
+
+      # OAuth client identifier.
+      # @return [String]
+      attr_reader :client_id
+
+      # Space-separated requested scopes.
+      # @return [String]
+      attr_reader :scope
+
+      # Secret PKCE verifier used for code exchange.
+      # @return [String]
+      attr_reader :pkce_verifier
+
+      # S256 PKCE challenge sent in PAR.
+      # @return [String]
+      attr_reader :pkce_challenge
+
+      # Bound authorization server, once discovered.
+      # @return [ServerMetadata::AuthorizationServer, nil]
+      attr_reader :auth_server
+
+      # Bound account DID, once resolved.
+      # @return [String, nil]
+      attr_reader :did
+
+      # Most recently assigned tokens, if any.
+      # @return [TokenSet, nil]
+      attr_reader :tokens
+
+      # Creates session identifiers, a state token, and a PKCE verifier/challenge pair.
+      #
+      # @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 did [String, nil] pre-resolved account DID
+      # @raise [PKCE::Error] if PKCE generation fails
+      #
+      def initialize(client_id:, scope:, auth_server: nil, did: nil)
+        super() # Initialize MonitorMixin
+
+        @session_id = SecureRandom.uuid
+        @state_token = SecureRandom.urlsafe_base64(32)
+        @client_id = client_id
+        @scope = scope
+        @auth_server = auth_server
+        @did = did
+
+        # Generate PKCE values
+        @pkce_verifier = PKCE.generate_verifier
+        @pkce_challenge = PKCE.generate_challenge(@pkce_verifier)
+
+        @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
+      # @raise [SessionError] if already bound to a server with a different issuer
+      #
+      def authorization_server=(server)
+        synchronize do
+          if @auth_server && @auth_server.issuer != server.issuer
+            raise SessionError, "Session already bound to different authorization server"
+          end
+
+          @auth_server = server
+        end
+      end
+
+      # Binds this session to an account DID.
+      #
+      # @param did [String] resolved DID
+      # @return [String] assigned DID
+      # @raise [SessionError] if already bound to a different DID
+      #
+      def did=(did)
+        synchronize do
+          raise SessionError, "Session already bound to different DID" if @did && @did != did
+
+          @did = did
+        end
+      end
+
+      # Stores tokens in this session object and binds an unbound session to their subject.
+      #
+      # Call {SessionManager#update_session} to persist the changed session.
+      #
+      # @param tokens [TokenSet] replacement token set
+      # @return [String] existing or newly bound session DID when called as a method
+      # @raise [SessionError] if token subject conflicts with the existing session DID
+      #
+      def tokens=(tokens)
+        synchronize do
+          raise SessionError, "Token subject doesn't match session DID" if @did && tokens.sub != @did
+
+          @tokens = tokens
+          @did ||= tokens.sub
+        end
+      end
+
+      # Whether this session has valid access tokens
+      # @return [Boolean]
+      def authorized?
+        synchronize do
+          !@tokens.nil? && !@tokens.expired?
+        end
+      end
+
+      # Whether this session can refresh its tokens
+      # @return [Boolean]
+      def renewable?
+        synchronize do
+          !@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