authproto 0.3.0.beta1

data/lib/authproto/encryption.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'securerandom'
+
+require_relative 'errors'
+
+module AuthProto
+
+  #
+  # AES-GCM envelopes and context-specific key derivation for stored OAuth secrets.
+  #
+
+  module Encryption
+
+    # Base class for encryption and key-configuration failures.
+    class Error < AuthProto::Error; end
+
+    # Raised when a required key derivation context is missing.
+    class ConfigurationError < Error; end
+
+    # Raised when plaintext inputs are invalid or encryption fails.
+    class EncryptionError < Error; end
+
+    # Raised when an encrypted envelope cannot be decoded, authenticated or decrypted.
+    class DecryptionError < Error; end
+
+    #
+    # HKDF implementation based on RFC 5869
+    #
+
+    module HKDF
+
+      # Derives key bytes with HKDF-SHA256 (RFC 5869).
+      #
+      # @param secret [#to_s] input key material
+      # @param salt [String] extraction salt; an empty string uses 32 zero bytes
+      # @param info [String] application/context information for expansion
+      # @param length [Integer] number of output bytes to derive
+      # @return [String] derived binary key material
+      #
+      def self.derive(secret, salt:, info:, length:)
+        # 1. extract
+        prk = OpenSSL::HMAC.digest(
+          OpenSSL::Digest.new("SHA256"),
+          salt.empty? ? "\x00" * 32 : salt,
+          secret.to_s
+        )
+
+        # 2. expand
+        n = (length.to_f / 32).ceil
+        t = [""]
+        output = ""
+        1.upto(n) do |i|
+          t[i] = OpenSSL::HMAC.digest(
+            OpenSSL::Digest.new("SHA256"),
+            prk,
+            t[i - 1] + info + [i].pack("C")
+          )
+          output += t[i]
+        end
+        output[0, length]
+      end
+    end
+
+    #
+    # Core encryption service - used internally by serializers
+    #
+
+    class Service
+
+      # OpenSSL cipher name used for authenticated encryption.
+      # @return [String]
+      CIPHER = "aes-256-gcm"
+
+      # Version stored in encrypted field envelopes.
+      # @return [Integer]
+      VERSION = 1
+
+      # Creates an encryption service backed by {KeyProvider}.
+      # @raise [ArgumentError] if the configured master key is not valid Base64
+      #
+      def initialize
+        @key_provider = KeyProvider.new
+      end
+
+      # Encrypts a string representation of data using AES-256-GCM and a context-derived key.
+      #
+      # The context is also authenticated; decryption must use the same context.
+      #
+      # @param data [#to_s] non-`nil` plaintext value, converted to a string
+      # @param context [String] nonempty context used for key derivation and authentication
+      # @return [Hash{Symbol => Integer, String}] envelope with `:version` (Integer) and Base64 `:iv`, `:data`, `:tag` (String)
+      # @raise [EncryptionError] if inputs are invalid or encryption fails
+      #
+      def encrypt(data, context:)
+        validate_encryption_inputs(data, context)
+
+        iv = SecureRandom.random_bytes(12)
+
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.encrypt
+        cipher.key = @key_provider.key_for_context(context)
+        cipher.iv = iv
+        cipher.auth_data = context.to_s
+
+        encrypted = cipher.update(data.to_s) + cipher.final
+        auth_tag = cipher.auth_tag
+
+        {
+          version: VERSION,
+          iv: Base64.strict_encode64(iv),
+          data: Base64.strict_encode64(encrypted),
+          tag: Base64.strict_encode64(auth_tag)
+        }
+      rescue StandardError => e
+        raise EncryptionError, "Encryption failed: #{e.message}"
+      end
+
+      # Authenticates and decrypts an envelope returned by {#encrypt}.
+      #
+      # @param encrypted [Hash{Symbol => Integer, String}] symbol-keyed `:version`, `:iv`, `:data`, `:tag` envelope
+      # @param context [String] same nonempty context used for encryption
+      # @return [String] plaintext bytes
+      # @raise [DecryptionError] if the context, key, version, encoding or authentication tag is invalid
+      #
+      def decrypt(encrypted, context:)
+        validate_decryption_inputs(encrypted, context)
+        validate_encrypted_data(encrypted)
+
+        iv = Base64.strict_decode64(encrypted[:iv])
+        data = Base64.strict_decode64(encrypted[:data])
+        auth_tag = Base64.strict_decode64(encrypted[:tag])
+
+        cipher = OpenSSL::Cipher.new(CIPHER)
+        cipher.decrypt
+        cipher.key = @key_provider.key_for_context(context)
+        cipher.iv = iv
+        cipher.auth_tag = auth_tag
+        cipher.auth_data = context.to_s
+
+        cipher.update(data) + cipher.final
+      rescue ArgumentError => e
+        raise DecryptionError, "Invalid encrypted data format: #{e.message}"
+      rescue StandardError => e
+        raise DecryptionError, "Decryption failed: #{e.message}"
+      end
+
+
+      private
+
+      def validate_encryption_inputs(data, context)
+        raise EncryptionError, "Data cannot be nil" if data.nil?
+        raise EncryptionError, "Context cannot be nil" if context.nil?
+        raise EncryptionError, "Context must be a string" unless context.is_a?(String)
+        raise EncryptionError, "Context cannot be empty" if context.empty?
+      end
+
+      def validate_decryption_inputs(encrypted, context)
+        raise DecryptionError, "Encrypted data cannot be nil" if encrypted.nil?
+        raise DecryptionError, "Context cannot be nil" if context.nil?
+        raise DecryptionError, "Context must be a string" unless context.is_a?(String)
+        raise DecryptionError, "Context cannot be empty" if context.empty?
+      end
+
+      def validate_encrypted_data(encrypted)
+        raise DecryptionError, "Invalid encrypted data format" unless encrypted.is_a?(Hash)
+
+        unless encrypted[:version] == VERSION
+          raise DecryptionError, "Unsupported encryption version: #{encrypted[:version]}"
+        end
+
+        %i[iv data tag].each do |field|
+          raise DecryptionError, "Missing required field: #{field}" unless encrypted[field].is_a?(String)
+        end
+      end
+    end
+
+    #
+    # Handles key management and derivation
+    #
+
+    class KeyProvider
+
+      # Protects creation of the process fallback master key.
+      # @return [Mutex]
+      EPHEMERAL_KEY_MUTEX = Mutex.new
+
+      # Returns a randomly generated master key shared by this class within the process.
+      #
+      # The key is cached under a mutex and is lost when the process exits.
+      #
+      # @return [String] 32 bytes of binary key material
+      #
+      def self.ephemeral_master_key
+        EPHEMERAL_KEY_MUTEX.synchronize do
+          @ephemeral_master_key ||= SecureRandom.random_bytes(32)
+        end
+      end
+
+      # Loads the master key from `ATPROTO_MASTER_KEY` or uses the process fallback.
+      #
+      # Set the environment variable to a Base64-encoded master secret, typically
+      # 32 random bytes. Context-specific AES-256 keys are derived from that secret.
+      # Without it, a warning is emitted and {KeyProvider.ephemeral_master_key} is used;
+      # data encrypted with that fallback cannot be recovered after a restart.
+      #
+      # @raise [ArgumentError] if `ATPROTO_MASTER_KEY` is not valid Base64
+      #
+      def initialize
+        @master_key = load_master_key
+      end
+
+      # Derives a 32-byte key specific to an encryption context.
+      #
+      # @param context [String] context label, such as `data.access_token`
+      # @return [String] context-specific binary key
+      # @raise [ConfigurationError] if context is `nil`
+      #
+      def key_for_context(context)
+        raise ConfigurationError, "Context is required" if context.nil?
+
+        HKDF.derive(
+          @master_key,
+          salt: salt_for_context(context),
+          info: "atproto-#{context}",
+          length: 32
+        )
+      end
+
+
+      private
+
+      def load_master_key
+        # Try environment variable first
+        key = ENV.fetch("ATPROTO_MASTER_KEY", nil)
+        return Base64.strict_decode64(key) if key
+
+        # Generate and store a random key if not configured
+        warn "WARNING: Using randomly generated encryption key - tokens will not persist across restarts"
+        self.class.ephemeral_master_key
+      end
+
+      def salt_for_context(context)
+        OpenSSL::Digest.digest("SHA256", "atproto-salt-#{context}")
+      end
+    end
+  end
+end

data/lib/authproto/errors.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module AuthProto
+
+  # Base class for library errors, except standalone localhost callback errors.
+  class Error < StandardError; end
+
+  #
+  # Base class for AT Protocol OAuth errors
+  #
+
+  class OAuthError < Error
+
+    # OAuth error code associated with the failure.
+    # @return [String]
+    attr_reader :error_code
+
+    # Creates an OAuth failure with a human-readable message and protocol code.
+    #
+    # @param message [String] error description
+    # @param error_code [String] OAuth 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 = AuthProto::Client.new(
+  #       client_id: "https://myapp.com/metadata.json",
+  #       redirect_uri: "https://myapp.com/callback"
+  #     )
+  #   rescue AuthProto::InvalidClientMetadata => e
+  #     puts "Failed to validate client metadata: #{e.message}"
+  #   end
+  #
+
+  class InvalidClientMetadata < OAuthError
+
+    # Creates a metadata error with the `invalid_client_metadata` code.
+    # @param message [String] explanation of the validation or retrieval failure
+    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 = AuthProto::ServerMetadata::AuthorizationServer.from_issuer("https://auth.example.com")
+  #   rescue AuthProto::InvalidAuthorizationServer => e
+  #     puts "Failed to validate authorization server: #{e.message}"
+  #   end
+  #
+
+  class InvalidAuthorizationServer < OAuthError
+
+    # Creates a metadata error with the `invalid_authorization_server` code.
+    # @param message [String] explanation of the validation or retrieval failure
+    def initialize(message)
+      super(message, "invalid_authorization_server")
+    end
+  end
+end

data/lib/authproto/http_client.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'net/http'
+require 'openssl'
+require 'resolv'
+require 'uri'
+
+require_relative 'errors'
+
+module AuthProto
+
+  #
+  # A secure HTTP client for making OAuth-related requests.
+  # Implements protections against SSRF attacks and enforces security headers.
+  #
+
+  class HTTPClient
+
+    # IPv4/IPv6 destinations rejected by the secure transport.
+    # @return [Array<IPAddr>]
+    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("::/128"),         # Unspecified IPv6 address
+      IPAddr.new("::1/128"),        # IPv6 loopback
+      IPAddr.new("fc00::/7"),       # Unique local address
+      IPAddr.new("fe80::/10")       # Link-local address
+    ].freeze
+
+    # URL schemes accepted by the secure transport; HTTPS only.
+    # @return [Array<String>]
+    ALLOWED_SCHEMES = ["https"].freeze
+
+    # Default open/read timeout in seconds.
+    # @return [Integer]
+    DEFAULT_TIMEOUT = 10 # seconds
+
+    # Maximum redirects followed for a single request.
+    # @return [Integer]
+    MAX_REDIRECTS = 5
+
+    # Maximum accepted response body size in bytes.
+    # @return [Integer]
+    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
+
+      # Response associated with the failure, when retained by the transport.
+      # @return [Net::HTTPResponse, nil]
+      attr_reader :response
+
+      # Creates an HTTP transport error with an optional response.
+      #
+      # @param message [String] failure description
+      # @param response [Net::HTTPResponse, nil] response associated with the error
+      #
+      def initialize(message, response)
+        @response = response
+        super(message)
+      end
+    end
+
+    # Value object for redirect request context.
+    #
+    # Fields are `original_uri` (URI::HTTP), `method` (Symbol), `response`
+    # (Net::HTTPResponse), `headers` (a string-keyed header hash), `redirect_count`
+    # (Integer), and `body` (String, Hash or nil). Inherits construction and immutable
+    # member access from `Data`.
+    #
+    # @see Data
+    #
+    RedirectHandlerOptions = Data.define(:original_uri, :method, :response, :headers, :redirect_count, :body)
+
+    # Creates an HTTP transport with timeouts and certificate verification settings.
+    #
+    # @param timeout [Numeric] open and read timeout, each in seconds
+    # @param verify_ssl [Boolean] whether HTTPS peer certificates must be verified
+    #
+    def initialize(timeout: DEFAULT_TIMEOUT, verify_ssl: true)
+      @timeout = timeout
+      @verify_ssl = verify_ssl
+    end
+
+    # Sends an HTTP GET request with destination validation and redirect handling.
+    #
+    # Uses HTTPS and rejects private/loopback destinations by default. Subclasses may
+    # relax these rules. Follows at most {MAX_REDIRECTS} redirects and checks size
+    # against {MAX_RESPONSE_SIZE} using `Content-Length`, or body bytes when absent.
+    # Non-2xx status codes are returned for the caller to interpret; they do not
+    # themselves raise an exception.
+    #
+    # @param url [String] absolute HTTPS request URL without a fragment
+    # @param headers [Hash{String => String}] additional request headers; can override the default `Cache-Control` value
+    # @param follow_redirects [Boolean] follow redirects, or return the initial response when false
+    # @return [Hash{Symbol => Integer, Hash{String => String}, String, nil}] `:status` (Integer), lowercase `:headers` (Hash), and `:body` (String or nil)
+    # @raise [SSRFError] if initial scheme, host, fragment or resolved address is rejected
+    # @raise [HTTPError] if transport, TLS, redirect validation or response size checks fail
+    # @raise [URI::InvalidURIError] if the initial URL cannot be parsed
+    #
+    def get(url, headers = {}, follow_redirects: true)
+      uri = validate_uri(url)
+      validate_ip(uri)
+
+      response = make_request(uri, headers, follow_redirects: follow_redirects)
+      validate_response(response)
+
+      {
+        status: response.code.to_i,
+        headers: response.each_header.to_h,
+        body: response.body
+      }
+    end
+
+    # Sends an HTTP POST request with destination validation and redirect handling.
+    #
+    # Uses HTTPS and rejects private/loopback destinations by default. Subclasses may
+    # relax these rules. Follows at most {MAX_REDIRECTS} redirects and checks size
+    # against {MAX_RESPONSE_SIZE} using `Content-Length`, or body bytes when absent.
+    # Non-2xx status codes are returned for the caller to interpret; they do not
+    # themselves raise an exception.
+    #
+    # @param url [String] absolute HTTPS request URL without a fragment
+    # @param body [String, Hash, nil] raw bytes, form fields encoded with `URI.encode_www_form`, or no body
+    # @param headers [Hash{String => String}] additional request headers; can override the default `Cache-Control` value
+    # @return [Hash{Symbol => Integer, Hash{String => String}, String, nil}] `:status` (Integer), lowercase `:headers` (Hash), and `:body` (String or nil)
+    # @raise [SSRFError] if initial scheme, host, fragment or resolved address is rejected
+    # @raise [HTTPError] if transport, TLS, redirect validation or response size checks fail
+    # @raise [URI::InvalidURIError] if the initial URL cannot be parsed
+    #
+    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 self.class::ALLOWED_SCHEMES.include?(uri.scheme)
+        raise SSRFError, "URL scheme must be one of: #{self.class::ALLOWED_SCHEMES.join(", ")}"
+      end
+
+      # Extract and validate host before any network activity
+      host = uri.host.to_s.strip
+      raise SSRFError, "URL must include host" if host.empty?
+      raise SSRFError, "URL must not include fragment" if uri.fragment
+
+      uri
+    end
+
+    def validate_ip(uri)
+      # URI#hostname removes brackets from IPv6 literals.
+      begin
+        parsed_ip = IPAddr.new(uri.hostname)
+      rescue IPAddr::InvalidAddressError
+        parsed_ip = nil
+      end
+
+      if parsed_ip
+        if forbidden_ip?(parsed_ip)
+          raise SSRFError, "Request to forbidden IP address"
+        else
+          return
+        end
+      end
+
+      # Also check resolved IPs for hostnames
+      begin
+        ips = Resolv::DNS.new.getaddresses(uri.hostname)
+        raise SSRFError, "Could not resolve hostname" if ips.empty?
+
+        ips.each do |x|
+          ip_addr = IPAddr.new(x.to_s)
+          raise SSRFError, "Request to forbidden IP address" if forbidden_ip?(ip_addr)
+        rescue IPAddr::InvalidAddressError
+          next
+        end
+      rescue Resolv::ResolvError
+        raise SSRFError, "Could not resolve hostname"
+      end
+    end
+
+    def forbidden_ip?(ip)
+      ip = ip.native if ip.ipv4_mapped?
+      FORBIDDEN_IP_RANGES.any? { |range| range.include?(ip) }
+    end
+
+    def make_request(uri, headers = {}, redirect_count = 0, follow_redirects: true)
+      http = Net::HTTP.new(uri.hostname, uri.port)
+      configure_http_client(http, ssl: uri.scheme == "https")
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      add_security_headers(request, headers)
+      response = http.request(request)
+      return response unless follow_redirects
+
+      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)
+      http = Net::HTTP.new(uri.hostname, uri.port)
+      configure_http_client(http, ssl: uri.scheme == "https")
+
+      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, ssl: true)
+      http.use_ssl = ssl
+      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)
+      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/authproto/insecure_http_client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'http_client'
+
+module AuthProto
+
+  #
+  # Development transport for mixed local HTTP and remote HTTPS requests.
+  # Allows private/loopback destinations; HTTPS certificate verification is kept.
+  #
+
+  class InsecureHTTPClient < HTTPClient
+
+    # HTTP and HTTPS schemes accepted for development requests.
+    # @return [Array<String>]
+    ALLOWED_SCHEMES = %w[http https].freeze
+
+    private
+
+    def validate_ip(uri)
+      # Deliberately bypass IP restrictions for local development environments.
+    end
+  end
+end