atproto_auth 0.0.1

data/lib/atproto_auth/dpop/nonce_manager.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module AtprotoAuth
+  module DPoP
+    # Manages DPoP nonces provided by servers during the OAuth flow.
+    # Tracks separate nonces for Resource Server and Authorization Server.
+    # Thread-safe to handle concurrent requests.
+    class NonceManager
+      # Error for nonce-related issues
+      class NonceError < AtprotoAuth::Error; end
+
+      # Represents a stored nonce with its timestamp
+      class StoredNonce
+        attr_reader :value, :timestamp, :server_url
+
+        def initialize(value, server_url)
+          @value = value
+          @server_url = server_url
+          @timestamp = Time.now.to_i
+        end
+
+        def expired?(ttl = nil)
+          return false unless ttl
+
+          (Time.now.to_i - @timestamp) > ttl
+        end
+      end
+
+      # Maximum time in seconds a nonce is considered valid
+      DEFAULT_TTL = 300 # 5 minutes
+
+      def initialize(ttl: nil)
+        @ttl = ttl || DEFAULT_TTL
+        @nonces = {}
+        @monitor = Monitor.new
+      end
+
+      # Updates the stored nonce for a server
+      # @param nonce [String] The new nonce value
+      # @param server_url [String] The server's URL
+      # @raise [NonceError] if inputs are invalid
+      def update(nonce:, server_url:)
+        validate_inputs!(nonce, server_url)
+        origin = normalize_server_url(server_url)
+
+        @monitor.synchronize do
+          @nonces[origin] = StoredNonce.new(nonce, origin)
+        end
+      end
+
+      # Gets the current nonce for a server
+      # @param server_url [String] The server's URL
+      # @return [String, nil] The current nonce or nil if none exists/expired
+      # @raise [NonceError] if server_url is invalid
+      def get(server_url)
+        validate_server_url!(server_url)
+        origin = normalize_server_url(server_url)
+
+        @monitor.synchronize do
+          stored = @nonces[origin]
+          return nil if stored.nil? || stored.expired?(@ttl)
+
+          stored.value
+        end
+      end
+
+      # Clears an expired nonce for a server
+      # @param server_url [String] The server's URL
+      def clear(server_url)
+        @monitor.synchronize do
+          @nonces.delete(server_url)
+        end
+      end
+
+      # Clears all stored nonces
+      def clear_all
+        @monitor.synchronize do
+          @nonces.clear
+        end
+      end
+
+      # Get all currently stored server URLs
+      # @return [Array<String>] Array of server URLs with stored nonces
+      def server_urls
+        @monitor.synchronize do
+          @nonces.keys
+        end
+      end
+
+      # Check if a server has a valid nonce
+      # @param server_url [String] The server's URL
+      # @return [Boolean] true if server has a valid nonce
+      def valid_nonce?(server_url)
+        validate_server_url!(server_url)
+
+        @monitor.synchronize do
+          stored = @nonces[server_url]
+          !stored.nil? && !stored.expired?(@ttl)
+        end
+      end
+
+      private
+
+      def normalize_server_url(url)
+        uri = URI(url)
+        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
+
+      def validate_inputs!(nonce, server_url)
+        raise NonceError, "nonce is required" if nonce.nil? || nonce.empty?
+
+        validate_server_url!(server_url)
+      end
+
+      def validate_server_url!(server_url)
+        raise NonceError, "server_url is required" if server_url.nil? || server_url.empty?
+
+        uri = URI(server_url)
+        raise NonceError, "server_url must be HTTP(S)" unless uri.is_a?(URI::HTTP)
+
+        # Allow HTTP for localhost only
+        if uri.host != "localhost" && uri.scheme != "https"
+          raise NonceError, "server_url must be HTTPS (except for localhost)"
+        end
+      rescue URI::InvalidURIError => e
+        raise NonceError, "invalid server_url: #{e.message}"
+      end
+    end
+  end
+end

data/lib/atproto_auth/dpop/proof_generator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module AtprotoAuth
+  module DPoP
+    # Creates and manages DPoP proof JWTs according to RFC 9449.
+    # DPoP proofs are used to prove possession of a key when making
+    # HTTP requests. Each proof is a JWT that includes details about
+    # the request and is signed by the DPoP key.
+    class ProofGenerator
+      # Error raised for proof generation/validation issues
+      class ProofError < AtprotoAuth::Error; end
+
+      # @return [KeyManager] The key manager used for signing proofs
+      attr_reader :key_manager
+
+      # Creates a new ProofGenerator instance
+      # @param key_manager [KeyManager] Key manager to use for signing proofs
+      # @raise [ProofError] if key_manager is invalid
+      def initialize(key_manager)
+        raise ProofError, "key_manager is required" unless key_manager
+        raise ProofError, "invalid key_manager type" unless key_manager.is_a?(KeyManager)
+
+        @key_manager = key_manager
+      end
+
+      # Generates a new DPoP proof JWT for an HTTP request
+      # @param http_method [String] HTTP method (e.g. "POST")
+      # @param http_uri [String] Full HTTP URI for the request
+      # @param nonce [String, nil] Server-provided nonce (required if available)
+      # @param access_token [String, nil] Access token being used (if any)
+      # @param ath [Boolean] Whether to include access token hash (default: true if token provided)
+      # @return [String] The signed DPoP proof JWT
+      # @raise [ProofError] if generation fails or parameters are invalid
+      def generate(http_method:, http_uri:, nonce: nil, access_token: nil, ath: nil)
+        validate_inputs!(http_method, http_uri)
+        ath = !access_token.nil? if ath.nil?
+
+        header = build_header
+        payload = build_payload(
+          http_method: http_method,
+          http_uri: http_uri,
+          nonce: nonce,
+          access_token: access_token,
+          include_ath: ath
+        )
+
+        key_manager.sign_segments(header, payload)
+      rescue StandardError => e
+        raise ProofError, "Failed to generate proof: #{e.message}"
+      end
+
+      private
+
+      def validate_inputs!(http_method, http_uri)
+        raise ProofError, "http_method is required" if http_method.nil? || http_method.empty?
+        raise ProofError, "http_uri is required" if http_uri.nil? || http_uri.empty?
+
+        uri = URI(http_uri)
+        raise ProofError, "invalid http_uri" unless uri.is_a?(URI::HTTP)
+      rescue URI::InvalidURIError => e
+        raise ProofError, "invalid http_uri: #{e.message}"
+      end
+
+      def build_header
+        {
+          typ: "dpop+jwt",
+          alg: "ES256",
+          jwk: key_manager.public_jwk.to_h
+        }
+      end
+
+      def build_payload(http_method:, http_uri:, nonce: nil, access_token: nil, include_ath: nil)
+        payload = {
+          "jti" => SecureRandom.uuid,
+          "htm" => http_method.upcase,
+          "htu" => normalize_uri(http_uri),
+          "iat" => Time.now.to_i
+        }
+
+        # Add the nonce if provided
+        payload["nonce"] = nonce if nonce
+
+        # Add access token hash if needed
+        payload["ath"] = generate_access_token_hash(access_token) if access_token && include_ath
+
+        payload
+      end
+
+      def normalize_uri(uri)
+        uri = URI(uri)
+        # Remove default ports
+        uri.port = nil if (uri.scheme == "https" && uri.port == 443) || (uri.scheme == "http" && uri.port == 80)
+        uri.fragment = nil
+        uri.to_s
+      end
+
+      def generate_access_token_hash(access_token)
+        digest = OpenSSL::Digest::SHA256.digest(access_token)
+        Base64.urlsafe_encode64(digest[0...(digest.length / 2)], padding: false)
+      end
+
+      def encode_jwt_segments(header, payload)
+        encoded_header = Base64.urlsafe_encode64(JSON.generate(header), padding: false)
+        encoded_payload = Base64.urlsafe_encode64(JSON.generate(payload), padding: false)
+        "#{encoded_header}.#{encoded_payload}"
+      end
+    end
+  end
+end

data/lib/atproto_auth/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  class Error < StandardError; end
+
+  # Base class for AT Protocol OAuth errors
+  class OAuthError < Error
+    attr_reader :error_code
+
+    def initialize(message, error_code)
+      @error_code = error_code
+      # @type-ignore
+      super(message)
+    end
+  end
+
+  # Error raised when client metadata is invalid or cannot be retrieved.
+  # This can occur during client metadata fetching, parsing, or validation.
+  #
+  # @example Handling client metadata errors
+  #   begin
+  #     client = AtprotoAuth::Client.new(client_id: "https://myapp.com/metadata.json")
+  #   rescue AtprotoAuth::InvalidClientMetadata => e
+  #     puts "Failed to validate client metadata: #{e.message}"
+  #   end
+  class InvalidClientMetadata < OAuthError
+    def initialize(message)
+      super(message, "invalid_client_metadata")
+    end
+  end
+
+  # Error raised when authorization server metadata is invalid or cannot be retrieved.
+  # This includes issues with server metadata fetching, parsing, or validation against
+  # the AT Protocol OAuth requirements.
+  #
+  # @example Handling authorization server errors
+  #   begin
+  #     server = AtprotoAuth::AuthorizationServer.new(issuer: "https://auth.example.com")
+  #   rescue AtprotoAuth::InvalidAuthorizationServer => e
+  #     puts "Failed to validate authorization server: #{e.message}"
+  #   end
+  class InvalidAuthorizationServer < OAuthError
+    def initialize(message)
+      super(message, "invalid_authorization_server")
+    end
+  end
+end

data/lib/atproto_auth/http_client.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "ipaddr"
+
+module AtprotoAuth
+  # A secure HTTP client for making OAuth-related requests.
+  # Implements protections against SSRF attacks and enforces security headers.
+  class HttpClient
+    FORBIDDEN_IP_RANGES = [
+      IPAddr.new("0.0.0.0/8"),      # Current network
+      IPAddr.new("10.0.0.0/8"),     # Private network
+      IPAddr.new("127.0.0.0/8"),    # Loopback
+      IPAddr.new("169.254.0.0/16"), # Link-local
+      IPAddr.new("172.16.0.0/12"),  # Private network
+      IPAddr.new("192.168.0.0/16"), # Private network
+      IPAddr.new("fc00::/7"),       # Unique local address
+      IPAddr.new("fe80::/10")       # Link-local address
+    ].freeze
+
+    ALLOWED_SCHEMES = ["https"].freeze
+    DEFAULT_TIMEOUT = 10 # seconds
+    MAX_REDIRECTS = 5
+    MAX_RESPONSE_SIZE = 10 * 1024 * 1024 # 10MB
+
+    # Error raised when a request is blocked due to SSRF protection
+    class SSRFError < Error; end
+
+    # Error raised when an HTTP request fails
+    class HttpError < Error
+      attr_reader :response
+
+      def initialize(message, response)
+        @response = response
+        super(message)
+      end
+    end
+
+    RedirectHandlerOptions = Data.define(:original_uri, :method, :response, :headers, :redirect_count, :body)
+
+    # @param timeout [Integer] Request timeout in seconds
+    # @param verify_ssl [Boolean] Whether to verify SSL certificates
+    def initialize(timeout: DEFAULT_TIMEOUT, verify_ssl: true)
+      @timeout = timeout
+      @verify_ssl = verify_ssl
+    end
+
+    # Makes a secure HTTP GET request
+    # @param url [String] URL to request
+    # @param headers [Hash] Additional headers to send
+    # @return [Hash] Response with :status, :headers, and :body
+    # @raise [SSRFError] If the request would be unsafe
+    # @raise [HttpError] If the request fails
+    def get(url, headers = {})
+      uri = validate_uri!(url)
+      validate_ip!(uri)
+
+      response = make_request(uri, headers)
+      validate_response!(response)
+
+      {
+        status: response.code.to_i,
+        headers: response.each_header.to_h,
+        body: response.body
+      }
+    end
+
+    # Makes a secure HTTP POST request
+    # @param url [String] URL to request
+    # @param body [String] Request body
+    # @param headers [Hash] Additional headers to send
+    # @return [Hash] Response with :status, :headers, and :body
+    # @raise [SSRFError] If the request would be unsafe
+    # @raise [HttpError] If the request fails
+    def post(url, body: nil, headers: {})
+      uri = validate_uri!(url)
+      validate_ip!(uri)
+
+      response = make_post_request(uri, body, headers)
+      validate_response!(response)
+
+      {
+        status: response.code.to_i,
+        headers: response.each_header.to_h,
+        body: response.body
+      }
+    end
+
+    private
+
+    def validate_uri!(url)
+      uri = URI(url)
+      unless ALLOWED_SCHEMES.include?(uri.scheme)
+        raise SSRFError, "URL scheme must be one of: #{ALLOWED_SCHEMES.join(", ")}"
+      end
+      raise SSRFError, "URL must include host" unless uri.host
+      raise SSRFError, "URL must not include fragment" if uri.fragment
+
+      uri
+    end
+
+    def validate_ip!(uri)
+      ip = resolve_ip(uri.host)
+      return unless forbidden_ip?(ip)
+
+      raise SSRFError, "Request to forbidden IP address"
+    end
+
+    def resolve_ip(hostname)
+      IPAddr.new(Addrinfo.ip(hostname).ip_address)
+    rescue SocketError => e
+      raise SSRFError, "Failed to resolve hostname: #{e.message}"
+    end
+
+    def forbidden_ip?(ip)
+      FORBIDDEN_IP_RANGES.any? { |range| range.include?(ip) }
+    end
+
+    def make_request(uri, headers = {}, redirect_count = 0)
+      http = Net::HTTP.new(uri.host, uri.port)
+      configure_http_client!(http)
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      add_security_headers!(request, headers)
+      response = http.request(request)
+      handle_redirect(
+        original_uri: uri,
+        response: response,
+        headers: headers,
+        redirect_count: redirect_count
+      )
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise HttpError.new("Request timeout: #{e.message}", nil)
+    rescue StandardError => e
+      raise HttpError.new("Request failed: #{e.message}", nil)
+    end
+
+    def make_post_request(uri, body, headers = {}, redirect_count = 0) # rubocop:disable Metrics/AbcSize
+      http = Net::HTTP.new(uri.host, uri.port)
+      configure_http_client!(http)
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      add_security_headers!(request, headers)
+      request.body = body.is_a?(Hash) ? URI.encode_www_form(body) : body if body
+
+      response = http.request(request)
+      handle_redirect(
+        original_uri: uri,
+        body: body,
+        method: :post,
+        response: response,
+        headers: headers,
+        redirect_count: redirect_count
+      )
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise HttpError.new("Request timeout: #{e.message}", nil)
+    rescue StandardError => e
+      raise HttpError.new("Request failed: #{e.message}", nil)
+    end
+
+    def configure_http_client!(http)
+      http.use_ssl = true
+      http.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+    end
+
+    def add_security_headers!(request, headers)
+      # Prevent caching of sensitive data
+      request["Cache-Control"] = "no-store"
+
+      # Add user-provided headers
+      headers.each { |k, v| request[k] = v }
+    end
+
+    # Handle HTTP redirects
+    # kwargs can include:
+    # - original_uri: URI of the original request
+    # - method: HTTP method of the original request (:get or :post)
+    # - response: Net::HTTPResponse object
+    # - headers: Hash of headers from the original request
+    # - redirect_count: Number of redirects so far
+    # - body: Request body for POST requests
+    def handle_redirect(**kwargs) # rubocop:disable Metrics/AbcSize
+      response = kwargs[:response]
+      redirect_count = kwargs[:redirect_count]
+
+      return response unless response.is_a?(Net::HTTPRedirection)
+      raise HttpError.new("Too many redirects", response) if redirect_count >= MAX_REDIRECTS
+
+      location = URI(response["location"])
+      location = kwargs[:original_uri] + location if location.relative?
+
+      validate_uri!(location.to_s)
+      validate_ip!(location)
+
+      # Increment redirect count for the next request
+      redirect_count += 1
+
+      # Recursive call to handle the next redirect
+      if kwargs[:method] == :post
+        make_post_request(location, kwargs[:body], kwargs[:headers], redirect_count)
+      else
+        make_request(location, kwargs[:headers], redirect_count)
+      end
+    end
+
+    def validate_response!(response)
+      # check_success_status!(response)
+      check_content_length!(response)
+    end
+
+    def check_success_status!(response)
+      return if response.is_a?(Net::HTTPSuccess)
+
+      raise HttpError.new("HTTP request failed: #{response.code} #{response.message}", response)
+    end
+
+    def check_content_length!(response)
+      content_length = response["content-length"]&.to_i || response.body&.bytesize || 0
+      return unless content_length > MAX_RESPONSE_SIZE
+
+      raise HttpError.new("Response too large: #{content_length} bytes", response)
+    end
+  end
+end

data/lib/atproto_auth/identity/document.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  module Identity
+    # Represents and validates a DID Document in the AT Protocol.
+    #
+    # DID Documents contain critical service information about user accounts, including:
+    # - The Personal Data Server (PDS) hosting the account
+    # - Associated handles for the account
+    # - Key material for identity verification
+    # - Service endpoints for various protocols
+    #
+    # This class handles both current and legacy DID document formats, providing
+    # a consistent interface for accessing and validating document data.
+    #
+    # @example Creating a document from JSON
+    #   data = {
+    #     "id" => "did:plc:abc123",
+    #     "alsoKnownAs" => ["at://alice.example.com"],
+    #     "pds" => "https://pds.example.com"
+    #   }
+    #   doc = AtprotoAuth::Identity::Document.new(data)
+    #
+    #   puts doc.pds                    # => "https://pds.example.com"
+    #   puts doc.has_handle?("alice.example.com")  # => true
+    #
+    # @example Handling legacy format
+    #   legacy_data = {
+    #     "id" => "did:plc:abc123",
+    #     "service" => [{
+    #       "id" => "#atproto_pds",
+    #       "type" => "AtprotoPersonalDataServer",
+    #       "serviceEndpoint" => "https://pds.example.com"
+    #     }]
+    #   }
+    #   doc = AtprotoAuth::Identity::Document.new(legacy_data)
+    #   puts doc.pds  # => "https://pds.example.com"
+    class Document
+      attr_reader :did, :rotation_keys, :also_known_as, :services, :pds
+
+      # Creates a new Document from parsed JSON
+      # @param data [Hash] Parsed DID document data
+      # @raise [DocumentError] if document is invalid
+      def initialize(data)
+        validate_document!(data)
+
+        @did = data["id"]
+        @rotation_keys = data["verificationMethod"]&.map { |m| m["publicKeyMultibase"] } || []
+        @also_known_as = data["alsoKnownAs"] || []
+        @services = data["service"] || []
+        @pds = extract_pds!(data)
+      end
+
+      # Checks if this document contains a specific handle
+      # @param handle [String] Handle to check (with or without @ prefix)
+      # @return [Boolean] true if handle is listed in alsoKnownAs
+      def has_handle?(handle) # rubocop:disable Naming/PredicateName
+        normalized = handle.start_with?("@") ? handle[1..] : handle
+        @also_known_as.any? do |aka|
+          aka.start_with?("at://") && aka.delete_prefix("at://") == normalized
+        end
+      end
+
+      private
+
+      def validate_document!(data)
+        raise DocumentError, "Document cannot be nil" if data.nil?
+        raise DocumentError, "Document must be a Hash" unless data.is_a?(Hash)
+        raise DocumentError, "Document must have id" unless data["id"]
+
+        validate_did!(data["id"])
+        validate_services!(data["service"])
+      end
+
+      def validate_did!(did)
+        return if did.start_with?("did:plc:")
+
+        raise DocumentError, "Invalid DID format (must be did:plc:): #{did}"
+      end
+
+      def validate_services!(services) # rubocop:disable Metrics/CyclomaticComplexity
+        return if services.nil?
+        raise DocumentError, "services must be an array" unless services.is_a?(Array)
+
+        services.each do |svc|
+          unless svc.is_a?(Hash) && svc["id"] && svc["type"] && svc["serviceEndpoint"]
+            raise DocumentError, "Invalid service entry format"
+          end
+        end
+      end
+
+      def extract_pds!(data)
+        pds = data["pds"] # New format
+        return pds if pds
+
+        # Legacy format - look through services
+        service = @services.find { |s| s["type"] == "AtprotoPersonalDataServer" }
+        raise DocumentError, "No PDS location found in document" unless service
+
+        service["serviceEndpoint"]
+      end
+    end
+  end
+end