authproto 0.3.0.beta1

data/lib/authproto/pkce.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'securerandom'
+
+require_relative 'errors'
+
+module AuthProto
+
+  #
+  # 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 < AuthProto::Error; end
+
+    # Minimum PKCE verifier length in characters.
+    # @return [Integer]
+    MIN_VERIFIER_LENGTH = 43
+
+    # Maximum PKCE verifier length in characters.
+    # @return [Integer]
+    MAX_VERIFIER_LENGTH = 128
+
+    # Allowed PKCE verifier characters from RFC 7636.
+    # @return [Regexp]
+    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/authproto/serialization/base.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+require_relative '../encryption'
+require_relative '../errors'
+
+module AuthProto
+
+  #
+  # Versioned JSON serialization with encryption of sensitive OAuth fields.
+  #
+
+  module Serialization
+
+    # Base class for malformed serialized data and serializer validation errors.
+    class Error < AuthProto::Error; end
+
+    # Raised when a serialized envelope uses an invalid or unsupported version.
+    class VersionError < Error; end
+
+    # Raised when an envelope type does not match the selected serializer.
+    class TypeMismatchError < Error; end
+
+    # Raised when a serializer receives an object of the wrong type.
+    class ValidationError < Error; end
+
+    #
+    # Base serializer that all type-specific serializers inherit from
+    #
+
+    class Base
+
+      # Current JSON envelope schema version.
+      # @return [Integer]
+      CURRENT_VERSION = 1
+
+      # Field names encrypted recursively before JSON serialization.
+      # @return [Array<String>]
+      SENSITIVE_FIELDS = [
+        "access_token",
+        "refresh_token",
+        "private_key",
+        "d", # EC private key component
+        "pkce_verifier"
+      ].freeze
+
+      class << self
+
+        # Serializes an object into a versioned JSON envelope, encrypting sensitive fields.
+        #
+        # Concrete subclasses validate the input type and provide the data representation.
+        #
+        # @param obj [Object] object supported by the concrete serializer
+        # @return [String] JSON with `version`, `type`, timestamps and `data` fields
+        # @raise [ValidationError] if the concrete serializer rejects the object
+        # @raise [Encryption::EncryptionError] if a sensitive value cannot be encrypted
+        # @raise [NotImplementedError] if used without implementing the abstract serializer hooks
+        #
+        def serialize(obj)
+          new.serialize(obj)
+        end
+
+        # Restores an object from a versioned JSON envelope, decrypting sensitive fields.
+        #
+        # The concrete serializer determines the returned object class.
+        #
+        # @param data [String] JSON previously produced by the matching serializer
+        # @return [Object] reconstructed object
+        # @raise [Error] if JSON or the envelope format is invalid
+        # @raise [TypeMismatchError] if the envelope has a different type identifier
+        # @raise [VersionError] if the format version is invalid or unsupported
+        # @raise [Encryption::DecryptionError] if sensitive data cannot be authenticated/decrypted
+        # @raise [ArgumentError] if reconstructed fields fail validation or date/time parsing
+        # @raise [NotImplementedError] if used without implementing the abstract serializer hooks
+        #
+        def deserialize(data)
+          new.deserialize(data)
+        end
+      end
+
+      # Creates a serializer with a context-aware encryption service.
+      # @raise [ArgumentError] if `ATPROTO_MASTER_KEY` is not valid Base64
+      #
+      def initialize
+        @encryption = Encryption::Service.new
+      end
+
+      # Serializes an object into a versioned JSON envelope, encrypting sensitive fields.
+      #
+      # Concrete subclasses validate the input type and provide the data representation.
+      #
+      # @param obj [Object] object supported by the concrete serializer
+      # @return [String] JSON with `version`, `type`, timestamps and `data` fields
+      # @raise [ValidationError] if the concrete serializer rejects the object
+      # @raise [Encryption::EncryptionError] if a sensitive value cannot be encrypted
+      # @raise [NotImplementedError] if used without implementing the abstract serializer hooks
+      #
+      def serialize(obj)
+        validate_object(obj)
+
+        # First serialize the object
+        data = {
+          version: CURRENT_VERSION,
+          type: type_identifier,
+          created_at: Time.now.utc.iso8601,
+          updated_at: Time.now.utc.iso8601,
+          data: serialize_data(obj)
+        }
+
+        # Then encrypt sensitive fields
+        encrypt_sensitive_fields(data)
+
+        # Finally convert to JSON
+        JSON.generate(data)
+      end
+
+      # Restores an object from a versioned JSON envelope, decrypting sensitive fields.
+      #
+      # The concrete serializer determines the returned object class.
+      #
+      # @param data [String] JSON previously produced by the matching serializer
+      # @return [Object] reconstructed object
+      # @raise [Error] if JSON or the envelope format is invalid
+      # @raise [TypeMismatchError] if the envelope has a different type identifier
+      # @raise [VersionError] if the format version is invalid or unsupported
+      # @raise [Encryption::DecryptionError] if sensitive data cannot be authenticated/decrypted
+      # @raise [ArgumentError] if reconstructed fields fail validation or date/time parsing
+      # @raise [NotImplementedError] if used without implementing the abstract serializer hooks
+      #
+      def deserialize(data)
+        parsed = parse_json(data)
+        validate_serialized_data(parsed)
+
+        # Decrypt sensitive fields
+        decrypt_sensitive_fields(parsed)
+
+        # Deserialize according to version
+        deserialize_version(parsed)
+      end
+
+      private
+
+      def encrypt_sensitive_fields(data, path: [])
+        return unless data.is_a?(Hash)
+
+        data.each do |key, value|
+          current_path = path + [key]
+
+          if sensitive_field?(key)
+            data[key] = @encryption.encrypt(
+              value.to_s,
+              context: current_path.join(".")
+            )
+          elsif value.is_a?(Hash)
+            encrypt_sensitive_fields(value, path: current_path)
+          elsif value.is_a?(Array)
+            value.each_with_index do |v, i|
+              encrypt_sensitive_fields(v, path: current_path + [i.to_s]) if v.is_a?(Hash)
+            end
+          end
+        end
+      end
+
+      def decrypt_sensitive_fields(data, path: [])
+        return unless data.is_a?(Hash)
+
+        data.each do |key, value|
+          current_path = path + [key]
+          if sensitive_field?(key)
+            data[key] = @encryption.decrypt(
+              value.transform_keys(&:to_sym),
+              context: current_path.join(".")
+            )
+          elsif value.is_a?(Hash)
+            decrypt_sensitive_fields(value, path: current_path)
+          elsif value.is_a?(Array)
+            value.each_with_index do |v, i|
+              decrypt_sensitive_fields(v, path: current_path + [i.to_s]) if v.is_a?(Hash)
+            end
+          end
+        end
+      end
+
+      def sensitive_field?(field)
+        SENSITIVE_FIELDS.any? do |sensitive_field|
+          field.to_s == sensitive_field
+        end
+      end
+
+      # Type identifier for serialized data
+      # @return [String]
+      def type_identifier
+        raise NotImplementedError
+      end
+
+      # Serialize object to hash
+      #
+      # @param obj [Object] Object to serialize
+      # @return [Hash] Serialized data
+      #
+      def serialize_data(obj)
+        raise NotImplementedError
+      end
+
+      # Deserialize object from hash
+      #
+      # @param data [Hash] Serialized data
+      # @return [Object] Deserialized object
+      #
+      def deserialize_data(data)
+        raise NotImplementedError
+      end
+
+      # Validate object before serialization
+      #
+      # @param obj [Object] Object to validate
+      # @raise [ValidationError] if object is invalid
+      #
+      def validate_object(obj)
+        raise NotImplementedError
+      end
+
+      def parse_json(data)
+        JSON.parse(data)
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON data: #{e.message}"
+      end
+
+      def validate_serialized_data(data)
+        raise Error, "Invalid serialized data format" unless data.is_a?(Hash)
+
+        unless data["type"] == type_identifier
+          raise TypeMismatchError,
+                "Expected type #{type_identifier}, got #{data["type"]}"
+        end
+
+        raise VersionError, "Invalid version format" unless data["version"].is_a?(Integer)
+
+        return unless data["version"] > CURRENT_VERSION
+
+        raise VersionError,
+              "Version #{data["version"]} not supported"
+      end
+
+      def deserialize_version(data)
+        case data["version"]
+        when 1
+          deserialize_data(data["data"])
+        else
+          raise VersionError,
+                "Unknown version: #{data["version"]}"
+        end
+      end
+    end
+  end
+end

data/lib/authproto/serialization/dpop_key.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../dpop/key_manager'
+require_relative 'base'
+
+module AuthProto
+  module Serialization
+
+    #
+    # Handles serialization of DPoP keys
+    #
+
+    class DPoPKey < Base
+
+      # Returns the envelope type used by this serializer.
+      # @return [String] `DPoPKey`
+      def type_identifier
+        "DPoPKey"
+      end
+
+      private
+
+      def validate_object(obj)
+        return if obj.is_a?(AuthProto::DPoP::KeyManager)
+
+        raise ValidationError, "Expected KeyManager object, got #{obj.class}"
+      end
+
+      def serialize_data(obj)
+        obj.to_jwk(include_private: true).to_h
+      end
+
+      def deserialize_data(data)
+        AuthProto::DPoP::KeyManager.from_jwk(data)
+      end
+    end
+  end
+end

data/lib/authproto/serialization/session.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative '../server_metadata/authorization_server'
+require_relative '../state/session'
+require_relative 'base'
+require_relative 'token_set'
+
+module AuthProto
+  module Serialization
+
+    #
+    # Handles serialization of Session objects
+    #
+
+    class Session < Base
+
+      # Returns the envelope type used by this serializer.
+      # @return [String] `Session`
+      def type_identifier
+        "Session"
+      end
+
+      private
+
+      def validate_object(obj)
+        return if obj.is_a?(AuthProto::State::Session)
+
+        raise ValidationError, "Expected Session object, got #{obj.class}"
+      end
+
+      def serialize_data(obj)
+        {
+          session_id: obj.session_id,
+          state_token: obj.state_token,
+          client_id: obj.client_id,
+          scope: obj.scope,
+          pkce_verifier: obj.pkce_verifier,
+          pkce_challenge: obj.pkce_challenge,
+          did: obj.did,
+          tokens: serialize_token_set(obj.tokens),
+          auth_server: serialize_auth_server(obj.auth_server)
+        }
+      end
+
+      def deserialize_data(data)
+        AuthProto::State::Session.new(
+          client_id: data["client_id"],
+          scope: data["scope"],
+          did: data["did"],
+          auth_server: deserialize_auth_server(data["auth_server"])
+        ).tap do |session|
+          # Set readonly attributes
+          session.instance_variable_set(:@session_id, data["session_id"])
+          session.instance_variable_set(:@state_token, data["state_token"])
+          session.instance_variable_set(:@pkce_verifier, data["pkce_verifier"])
+          session.instance_variable_set(:@pkce_challenge, data["pkce_challenge"])
+
+          # Set tokens if present
+          session.tokens = deserialize_token_set(data["tokens"]) if data["tokens"]
+        end
+      end
+
+      def serialize_token_set(tokens)
+        return nil unless tokens
+
+        TokenSet.new.serialize(tokens)
+      end
+
+      def deserialize_token_set(data)
+        return nil unless data
+
+        TokenSet.new.deserialize(data)
+      end
+
+      def serialize_auth_server(server)
+        return nil unless server
+
+        server.to_h
+      end
+
+      def deserialize_auth_server(data)
+        return nil unless data
+
+        AuthProto::ServerMetadata::AuthorizationServer.new(data)
+      end
+    end
+  end
+end

data/lib/authproto/serialization/stored_nonce.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative '../dpop/stored_nonce'
+require_relative 'base'
+
+module AuthProto
+  module Serialization
+
+    #
+    # Handles serialization of StoredNonce objects
+    #
+
+    class StoredNonce < Base
+
+      # Returns the envelope type used by this serializer.
+      # @return [String] `StoredNonce`
+      def type_identifier
+        "StoredNonce"
+      end
+
+      private
+
+      def validate_object(obj)
+        return if obj.is_a?(AuthProto::DPoP::StoredNonce)
+
+        raise ValidationError, "Expected StoredNonce object, got #{obj.class}"
+      end
+
+      def serialize_data(obj)
+        {
+          value: obj.value,
+          server_url: obj.server_url,
+          timestamp: obj.timestamp
+        }
+      end
+
+      def deserialize_data(data)
+        AuthProto::DPoP::StoredNonce.new(
+          data["value"],
+          data["server_url"],
+          timestamp: Time.at(data["timestamp"])
+        )
+      end
+    end
+  end
+end

data/lib/authproto/serialization/token_set.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'time'
+
+require_relative '../state/token_set'
+require_relative 'base'
+
+module AuthProto
+  module Serialization
+
+    #
+    # Handles serialization of TokenSet objects
+    #
+
+    class TokenSet < Base
+
+      # Returns the envelope type used by this serializer.
+      # @return [String] `TokenSet`
+      def type_identifier
+        "TokenSet"
+      end
+
+      private
+
+      def validate_object(obj)
+        return if obj.is_a?(AuthProto::State::TokenSet)
+
+        raise ValidationError, "Expected TokenSet object, got #{obj.class}"
+      end
+
+      def serialize_data(obj)
+        {
+          access_token: obj.access_token,
+          refresh_token: obj.refresh_token,
+          token_type: obj.token_type,
+          expires_at: obj.expires_at.utc.iso8601,
+          scope: obj.scope,
+          sub: obj.sub
+        }
+      end
+
+      def deserialize_data(data)
+        AuthProto::State::TokenSet.new(
+          access_token: data["access_token"],
+          refresh_token: data["refresh_token"],
+          token_type: data["token_type"],
+          expires_in: (Time.parse(data["expires_at"]) - Time.now).to_i,
+          scope: data["scope"],
+          sub: data["sub"]
+        )
+      end
+    end
+  end
+end