atproto_auth 0.0.1

data/lib/atproto_auth/pkce.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "base64"
+require "openssl"
+
+module AtprotoAuth
+  # Implementation of Proof Key for Code Exchange (PKCE) for OAuth 2.0 / AT Protocol
+  # as specified in RFC 7636.
+  #
+  # This module provides functionality to:
+  # - Generate cryptographically secure code verifiers
+  # - Create SHA-256 code challenges from verifiers
+  # - Verify challenge/verifier pairs
+  #
+  # Only the S256 challenge method is supported, as required by AT Protocol OAuth.
+  module PKCE
+    # Error raised for PKCE-related failures
+    class Error < AtprotoAuth::Error; end
+
+    # Minimum and maximum lengths for code verifier as per RFC 7636
+    MIN_VERIFIER_LENGTH = 43
+    MAX_VERIFIER_LENGTH = 128
+
+    # PKCE code verifier charset as per RFC 7636 Section 4.1
+    ALLOWED_VERIFIER_CHARS = /^[A-Za-z0-9\-\._~]+$/
+
+    class << self
+      # Generates a cryptographically secure random code verifier
+      # @param length [Integer] Length of verifier to generate
+      # @return [String] The generated code verifier
+      # @raise [Error] if length is invalid
+      def generate_verifier(length = MAX_VERIFIER_LENGTH)
+        validate_verifier_length!(length)
+
+        # Generate random bytes and encode as URL-safe base64
+        random_bytes = SecureRandom.random_bytes(length * 3 / 4)
+        Base64.urlsafe_encode64(random_bytes, padding: false)[0...length]
+      rescue StandardError => e
+        raise Error, "Failed to generate verifier: #{e.message}"
+      end
+
+      # Creates a code challenge from a verifier using SHA-256
+      # @param verifier [String] The code verifier to create challenge from
+      # @return [String] Base64URL-encoded SHA-256 hash of the verifier
+      # @raise [Error] if verifier is invalid or hashing fails
+      def generate_challenge(verifier)
+        validate_verifier!(verifier)
+
+        # Hash with SHA-256 and encode as URL-safe base64
+        digest = OpenSSL::Digest::SHA256.digest(verifier)
+        Base64.urlsafe_encode64(digest, padding: false)
+      rescue StandardError => e
+        raise Error, "Failed to generate challenge: #{e.message}"
+      end
+
+      # Verifies that a challenge matches a verifier
+      # @param challenge [String] The code challenge to verify
+      # @param verifier [String] The code verifier to check against
+      # @return [Boolean] true if challenge matches verifier
+      # @raise [Error] if inputs are invalid
+      def verify(challenge, verifier)
+        # Generate challenge from verifier and compare
+        calculated = generate_challenge(verifier)
+        secure_compare(calculated, challenge)
+      rescue Error
+        # Re-raise PKCE errors
+        raise
+      rescue StandardError => e
+        raise Error, "Challenge verification failed: #{e.message}"
+      end
+
+      private
+
+      def validate_verifier_length!(length)
+        return if length.is_a?(Integer) && length.between?(MIN_VERIFIER_LENGTH, MAX_VERIFIER_LENGTH)
+
+        raise Error, "Verifier length must be between #{MIN_VERIFIER_LENGTH} and #{MAX_VERIFIER_LENGTH}"
+      end
+
+      def validate_verifier!(verifier)
+        raise Error, "Verifier cannot be nil" if verifier.nil?
+        raise Error, "Verifier cannot be empty" if verifier.empty?
+
+        length = verifier.length
+        validate_verifier_length!(length)
+
+        return if verifier.match?(ALLOWED_VERIFIER_CHARS)
+
+        raise Error, "Verifier contains invalid characters"
+      end
+
+      # Constant-time string comparison to prevent timing attacks
+      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

data/lib/atproto_auth/server_metadata/authorization_server.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  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 = AtprotoAuth::ServerMetadata::AuthorizationServer.from_issuer("https://auth.example.com")
+    #     puts "Authorization endpoint: #{auth_server.authorization_endpoint}"
+    #     puts "Supported scopes: #{auth_server.scopes_supported}"
+    #   rescue AtprotoAuth::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
+      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
+
+      attr_reader :issuer, :authorization_endpoint, :token_endpoint,
+                  :pushed_authorization_request_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
+
+      def initialize(metadata)
+        validate_and_set_metadata!(metadata)
+      end
+
+      # Fetches and validates Authorization Server metadata from an issuer URL
+      # @param issuer [String] Authorization Server issuer URL
+      # @return [AuthorizationServer] new instance with fetched metadata
+      # @raise [InvalidAuthorizationServer] if metadata is invalid
+      def self.from_issuer(issuer)
+        response = fetch_metadata(issuer)
+        metadata = parse_metadata(response[:body])
+        validate_issuer!(metadata["issuer"], issuer)
+        new(metadata)
+      end
+
+      private
+
+      def validate_and_set_metadata!(metadata) # rubocop:disable Metrics/AbcSize
+        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")
+          AtprotoAuth.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/atproto_auth/server_metadata/origin_url.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  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
+      attr_reader :url, :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/atproto_auth/server_metadata/resource_server.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  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
+      attr_reader :authorization_servers
+
+      def initialize(metadata)
+        @authorization_servers = validate_authorization_servers!(metadata["authorization_servers"])
+      end
+
+      # Fetches and validates Resource Server metadata from a URL
+      # @param url [String] PDS URL to fetch metadata from
+      # @return [ResourceServer] new instance with fetched metadata
+      # @raise [InvalidAuthorizationServer] if metadata is invalid
+      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")
+          AtprotoAuth.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/atproto_auth/server_metadata.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  # 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 = AtprotoAuth::ServerMetadata::ResourceServer.from_url("https://pds.example.com")
+  #   auth_server_url = resource_server.authorization_servers.first
+  #   auth_server = AtprotoAuth::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/atproto_auth/state/session.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require "monitor"
+
+module AtprotoAuth
+  module State
+    # Tracks state for an OAuth authorization flow session
+    class Session
+      include MonitorMixin
+
+      attr_reader :session_id, :state_token, :client_id, :scope,
+                  :pkce_verifier, :pkce_challenge, :auth_server,
+                  :did, :tokens
+
+      # Creates a new OAuth session
+      # @param client_id [String] OAuth client ID
+      # @param scope [String] Requested scope
+      # @param auth_server [AuthorizationServer, nil] Optional pre-resolved auth server
+      # @param did [String, nil] Optional pre-resolved DID
+      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
+
+      # Updates the authorization server for this session
+      # @param server [AuthorizationServer] The resolved auth server
+      # @return [void]
+      # @raise [SessionError] if session is already bound to different server
+      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
+
+      # Updates the user's DID for this session
+      # @param did [String] The resolved DID
+      # @return [void]
+      # @raise [SessionError] if session already has different DID
+      def did=(did)
+        synchronize do
+          raise SessionError, "Session already bound to different DID" if @did && @did != did
+
+          @did = did
+        end
+      end
+
+      # Updates tokens for this session
+      # @param tokens [TokenSet] New token set
+      # @return [void]
+      # @raise [SessionError] if tokens don't match 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
+
+      # Validates a state token against this session
+      # @param state [String] State token to validate
+      # @return [Boolean]
+      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

data/lib/atproto_auth/state/session_manager.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require "monitor"
+
+module AtprotoAuth
+  module State
+    # Manages active OAuth sessions
+    class SessionManager
+      include MonitorMixin
+
+      def initialize
+        super # Initialize MonitorMixin
+        @sessions = {}
+      end
+
+      # Creates and stores a new session
+      # @param client_id [String] OAuth client ID
+      # @param scope [String] Requested scope
+      # @param auth_server [AuthorizationServer, nil] Optional pre-resolved auth server
+      # @param did [String, nil] Optional pre-resolved DID
+      # @return [Session] The created session
+      def create_session(client_id:, scope:, auth_server: nil, did: nil)
+        session = Session.new(
+          client_id: client_id,
+          scope: scope,
+          auth_server: auth_server,
+          did: did
+        )
+
+        synchronize do
+          @sessions[session.session_id] = session
+        end
+
+        session
+      end
+
+      # Retrieves a session by ID
+      # @param session_id [String] Session ID to look up
+      # @return [Session, nil] The session if found
+      def get_session(session_id)
+        synchronize do
+          @sessions[session_id]
+        end
+      end
+
+      # Finds a session by state token
+      # @param state [String] State token to look up
+      # @return [Session, nil] The session if found
+      def get_session_by_state(state)
+        synchronize do
+          @sessions.values.find { |session| session.validate_state(state) }
+        end
+      end
+
+      # Removes a session
+      # @param session_id [String] Session ID to remove
+      # @return [void]
+      def remove_session(session_id)
+        synchronize do
+          @sessions.delete(session_id)
+        end
+      end
+
+      # Removes all expired sessions
+      # @return [void]
+      def cleanup_expired
+        synchronize do
+          @sessions.delete_if { |_, session| !session.renewable? && session.tokens&.expired? }
+        end
+      end
+    end
+  end
+end

data/lib/atproto_auth/state/token_set.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  module State
+    # Represents a set of OAuth tokens and their associated metadata
+    class TokenSet
+      attr_reader :access_token, :refresh_token, :token_type,
+                  :scope, :expires_at, :sub
+
+      # Creates a new TokenSet from a token response
+      # @param access_token [String] The access token
+      # @param token_type [String] Token type (must be "DPoP")
+      # @param expires_in [Integer] Token lifetime in seconds
+      # @param refresh_token [String, nil] Optional refresh token
+      # @param scope [String] Space-separated list of granted scopes
+      # @param sub [String] DID of the authenticated user
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        access_token:,
+        token_type:,
+        expires_in:,
+        scope:,
+        sub:,
+        refresh_token: nil
+      )
+        validate_token_type!(token_type)
+        validate_required!("access_token", access_token)
+        validate_required!("scope", scope)
+        validate_required!("sub", sub)
+        validate_expires_in!(expires_in)
+
+        @access_token = access_token
+        @refresh_token = refresh_token
+        @token_type = token_type
+        @scope = scope
+        @sub = sub
+        @expires_at = Time.now + expires_in
+      end
+
+      # Whether this token set includes a refresh token
+      # @return [Boolean]
+      def renewable?
+        !@refresh_token.nil?
+      end
+
+      # Whether the access token has expired
+      # @return [Boolean]
+      def expired?(buffer = 30)
+        Time.now >= (@expires_at - buffer)
+      end
+
+      private
+
+      def validate_token_type!(type)
+        raise ArgumentError, "token_type must be DPoP" unless type == "DPoP"
+      end
+
+      def validate_required!(name, value)
+        raise ArgumentError, "#{name} is required" if value.nil? || value.empty?
+      end
+
+      def validate_expires_in!(expires_in)
+        return if expires_in.is_a?(Integer) && expires_in.positive?
+
+        raise ArgumentError, "expires_in must be positive integer"
+      end
+    end
+  end
+end