clavis 0.7.1

data/lib/clavis/errors.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Clavis
+  # Base error class for all Clavis errors
+  class Error < StandardError; end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+
+  class MissingConfiguration < ConfigurationError
+    def initialize(missing_config)
+      super("Missing configuration: #{missing_config}")
+    end
+  end
+
+  class InvalidConfiguration < ConfigurationError
+    def initialize(config_name, message)
+      super("Invalid configuration for #{config_name}: #{message}")
+    end
+  end
+
+  # Provider errors
+  class ProviderError < Error; end
+
+  class UnsupportedProvider < ProviderError
+    def initialize(provider)
+      super("Unsupported provider: #{provider}")
+    end
+  end
+
+  class ProviderAPIError < ProviderError
+    def initialize(provider, message)
+      super("API error from #{provider}: #{message}")
+    end
+  end
+
+  class ProviderNotConfigured < ProviderError
+    def initialize(provider_or_message)
+      if provider_or_message.is_a?(String) && provider_or_message.include?("not configured")
+        # Already a detailed message
+        super
+      else
+        # Just a provider name, create a detailed message
+        provider = provider_or_message.to_s
+        message = "Provider '#{provider}' is not properly configured. " \
+                  "Please check your configuration in config/initializers/clavis.rb.\n" \
+                  "Required fields for #{provider} provider: client_id, client_secret, and redirect_uri.\n" \
+                  "Example configuration:\n" \
+                  "Clavis.configure do |config|\n  " \
+                  "config.providers = {\n    " \
+                  "#{provider}: {\n      " \
+                  "client_id: 'your_client_id',\n      " \
+                  "client_secret: 'your_client_secret',\n      " \
+                  "redirect_uri: 'https://your-app.com/auth/#{provider}/callback'\n    " \
+                  "}\n  " \
+                  "}\n" \
+                  "end"
+        super(message)
+      end
+    end
+  end
+
+  # OAuth errors
+  class OAuthError < Error
+    def initialize(message = "OAuth error")
+      super
+    end
+  end
+
+  # Authorization errors
+  class AuthorizationError < Error; end
+
+  class AuthorizationDenied < AuthorizationError
+    def initialize(provider = nil)
+      message = provider ? "User denied authorization for #{provider}" : "User denied authorization"
+      super(message)
+    end
+  end
+
+  class InvalidState < AuthorizationError
+    def initialize
+      super("Invalid state parameter in callback")
+    end
+  end
+
+  class MissingState < AuthorizationError
+    def initialize
+      super("Missing state parameter in callback")
+    end
+  end
+
+  class InvalidNonce < AuthorizationError
+    def initialize
+      super("Invalid nonce in ID token")
+    end
+  end
+
+  class MissingNonce < AuthorizationError
+    def initialize
+      super("Missing nonce in ID token or session")
+    end
+  end
+
+  class InvalidRedirectUri < AuthorizationError
+    def initialize(uri)
+      super("Invalid redirect URI: #{uri}")
+    end
+  end
+
+  # Authentication errors
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super
+    end
+  end
+
+  # Token errors
+  class TokenError < Error; end
+
+  class InvalidToken < TokenError
+    def initialize(message = "Invalid token")
+      super
+    end
+  end
+
+  class InvalidAccessToken < TokenError
+    def initialize
+      super("Invalid access token")
+    end
+  end
+
+  class InvalidGrant < TokenError
+    def initialize(message = "Invalid grant")
+      super
+    end
+  end
+
+  class ExpiredToken < TokenError
+    def initialize
+      super("Token has expired")
+    end
+  end
+
+  # Client errors
+  class InvalidClient < TokenError
+    def initialize(message = "Invalid client credentials")
+      super
+    end
+  end
+
+  class UnauthorizedClient < TokenError
+    def initialize(message = "The client is not authorized to use this grant type")
+      super
+    end
+  end
+
+  class UnsupportedGrantType < TokenError
+    def initialize(message = "The grant type is not supported by the authorization server")
+      super
+    end
+  end
+
+  class InvalidScope < TokenError
+    def initialize(message = "The requested scope is invalid or unknown")
+      super
+    end
+  end
+
+  class InsufficientScope < TokenError
+    def initialize(message = "The token does not have the required scopes")
+      super
+    end
+  end
+
+  # Operation errors
+  class UnsupportedOperation < Error
+    def initialize(message)
+      super("Unsupported operation: #{message}")
+    end
+  end
+
+  # User errors
+  class UserError < Error; end
+
+  class UserCreationFailed < UserError
+    def initialize(message = "Failed to create user")
+      super
+    end
+  end
+
+  class UserNotFound < UserError
+    def initialize
+      super("User not found")
+    end
+  end
+
+  # View errors
+  class ViewError < Error; end
+
+  class InvalidButton < ViewError
+    def initialize(provider)
+      super("Invalid button provider: #{provider}")
+    end
+  end
+end

data/lib/clavis/logging.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Clavis
+  module Logging
+    class << self
+      def logger
+        @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      end
+
+      attr_writer :logger
+
+      # Log informational messages
+      # @param message [String] The message to log
+      # @param level [Symbol] The log level (:info, :debug, etc.)
+      def log_info(message)
+        return unless logger
+        return if !message || message.empty?
+
+        # Sanitize any potentially sensitive data
+        sanitized_message = filter_sensitive_data(message)
+        logger.info("[Clavis] #{sanitized_message}")
+      end
+
+      # Log error messages
+      # @param error [Exception, String] The error to log
+      def log_error(error)
+        return unless logger
+
+        case error
+        when Exception
+          logger.error("[Clavis] #{error.class.name}: #{error.message}")
+          logger.debug("[Clavis] #{error.backtrace.join("\n")}") if error.backtrace
+        when String
+          logger.error("[Clavis] Error: #{error}")
+        end
+      end
+
+      # Log security warnings - always logged at WARN level
+      # @param message [String] The message to log
+      def security_warning(message)
+        return unless logger
+        return if !message || message.empty?
+
+        # Sanitize any potentially sensitive data
+        sanitized_message = filter_sensitive_data(message)
+        logger.warn("[Clavis Security Warning] #{sanitized_message}")
+      end
+
+      # The following methods are provided as aliases or for backwards compatibility
+
+      def log(message, level = :info)
+        return unless logger
+        return if !message || message.empty?
+
+        # Sanitize any potentially sensitive data
+        sanitized_message = filter_sensitive_data(message)
+        logger.send(level, "[Clavis] #{sanitized_message}")
+      end
+
+      # Older method signatures maintained for compatibility
+      def log_token_refresh(provider, success, message = nil)
+        log("Token refresh for #{provider}: #{success ? "success" : "failed"}#{message ? " - #{message}" : ""}")
+      end
+
+      def log_token_exchange(provider, success, details = nil)
+        log("Token exchange for #{provider}: #{success ? "success" : "failed"}#{details ? " - #{details}" : ""}")
+      end
+
+      def log_userinfo_request(provider, success, details = nil)
+        log("Userinfo request for #{provider}: #{success ? "success" : "failed"}#{details ? " - #{details}" : ""}")
+      end
+
+      def log_authorization_request(provider, params)
+        sanitized_params = filter_sensitive_data(params.to_s)
+        log("Authorization request for #{provider}: #{sanitized_params}")
+      end
+
+      def log_authorization_callback(provider, success)
+        log("Authorization callback for #{provider}: #{success ? "success" : "failed"}")
+      end
+
+      private
+
+      # Filter potentially sensitive data from log messages
+      def filter_sensitive_data(message)
+        return message unless message.is_a?(String)
+
+        # List of patterns to filter out
+        patterns = [
+          /client_secret=([^&\s]+)/i,
+          /access_token=([^&\s]+)/i,
+          /refresh_token=([^&\s]+)/i,
+          /id_token=([^&\s]+)/i,
+          /code=([^&\s]+)/i,
+          /password=([^&\s]+)/i,
+          /secret=([^&\s]+)/i,
+          /api_key=([^&\s]+)/i,
+          /key=([^&\s]+)/i,
+          /"token":\s*"([^"]+)"/i,
+          /"refresh_token":\s*"([^"]+)"/i,
+          /"id_token":\s*"([^"]+)"/i,
+          /"code":\s*"([^"]+)"/i
+        ]
+
+        filtered_message = message.dup
+        patterns.each do |pattern|
+          filtered_message.gsub!(pattern, '\0=[FILTERED]')
+        end
+
+        filtered_message
+      end
+    end
+  end
+end

data/lib/clavis/models/concerns/oauth_authenticatable.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Clavis
+  module Models
+    module Concerns
+      # This module adds OAuth authentication capabilities to a model
+      # It's typically included in the User model
+      module OauthAuthenticatable
+        extend ActiveSupport::Concern
+
+        included do
+          # Setup relationships
+          has_many :oauth_identities,
+                   class_name: "Clavis::OauthIdentity",
+                   as: :authenticatable,
+                   dependent: :destroy
+        end
+
+        # Get the primary OAuth identity for this user
+        #
+        # @return [Clavis::OauthIdentity, nil] The primary OAuth identity
+        def oauth_identity
+          oauth_identities.first
+        end
+
+        # Determines if this user was created via OAuth
+        #
+        # @return [Boolean] True if the user has any OAuth identities or oauth_user flag is true
+        def oauth_user?
+          return true if respond_to?(:oauth_user) && oauth_user
+
+          # Handle both Array and ActiveRecord collection
+          if oauth_identities.respond_to?(:exists?)
+            oauth_identities.exists?
+          else
+            oauth_identities.any?
+          end
+        end
+
+        # Get the identity for a specific provider
+        #
+        # @param provider [String, Symbol] The provider name
+        # @return [Clavis::OauthIdentity, nil] The OAuth identity for the provider or nil
+        def oauth_identity_for(provider)
+          oauth_identities.find_by(provider: provider)
+        end
+
+        # Get the email from the OAuth identity
+        #
+        # @return [String, nil] The email from the OAuth identity or nil
+        def oauth_email
+          return nil unless oauth_identity&.auth_data
+
+          # First check standardized data
+          email = extract_standardized_value(oauth_identity.auth_data, "email")
+
+          # Fall back to raw auth data
+          email ||= oauth_identity.auth_data["email"] || oauth_identity.auth_data[:email]
+          email
+        end
+
+        # Get the name from the OAuth identity
+        #
+        # @return [String, nil] The name from the OAuth identity or nil
+        def oauth_name
+          return nil unless oauth_identity&.auth_data
+
+          # First check standardized data
+          name = extract_standardized_value(oauth_identity.auth_data, "name")
+
+          # Fall back to raw auth data
+          name ||= oauth_identity.auth_data["name"] || oauth_identity.auth_data[:name]
+          name
+        end
+
+        # Get the profile picture URL from the OAuth identity
+        #
+        # @return [String, nil] The profile picture URL from the OAuth identity or nil
+        def oauth_avatar_url
+          return nil unless oauth_identity&.auth_data
+
+          # First check standardized data
+          avatar = extract_standardized_value(oauth_identity.auth_data, "avatar_url")
+
+          # Fall back to various possible fields in raw auth data
+          avatar ||= oauth_identity.auth_data["image"] || oauth_identity.auth_data[:image]
+          avatar ||= oauth_identity.auth_data["picture"] || oauth_identity.auth_data[:picture]
+          avatar ||= oauth_identity.auth_data["avatar_url"] || oauth_identity.auth_data[:avatar_url]
+
+          avatar
+        end
+
+        # Get the access token for the primary identity
+        #
+        # @return [String, nil] The access token or nil
+        def oauth_token
+          oauth_identity&.token
+        end
+
+        # Get the refresh token for the primary identity
+        #
+        # @return [String, nil] The refresh token or nil
+        def oauth_refresh_token
+          oauth_identity&.refresh_token
+        end
+
+        # Check if the token for the primary identity has expired
+        #
+        # @return [Boolean] True if the token has expired, false otherwise or if expires_at is nil
+        def oauth_token_expired?
+          return false unless oauth_identity&.expires_at
+
+          # Convert to Time object if it's an Integer
+          expires_at = if oauth_identity.expires_at.is_a?(Integer)
+                         Time.at(oauth_identity.expires_at)
+                       else
+                         oauth_identity.expires_at
+                       end
+          expires_at < Time.now
+        end
+
+        # Refresh the access token for the primary identity
+        #
+        # @return [String, nil] The new access token or nil if refresh failed or not supported
+        def refresh_oauth_token
+          return nil unless oauth_identity&.refresh_token.present?
+
+          provider = oauth_identity.provider
+          provider_instance = Clavis.provider(provider)
+          return nil unless provider_instance.respond_to?(:refresh_token)
+
+          # Refresh the token
+          new_tokens = provider_instance.refresh_token(oauth_identity.refresh_token)
+
+          # Update the identity with the new tokens
+          oauth_identity.token = new_tokens[:access_token] || new_tokens[:token]
+          oauth_identity.refresh_token = new_tokens[:refresh_token] if new_tokens[:refresh_token].present?
+          oauth_identity.expires_at = new_tokens[:expires_at] if new_tokens[:expires_at].present?
+          oauth_identity.save!
+
+          # Return the new token
+          oauth_identity.token
+        end
+
+        private
+
+        # Extract a value from standardized data, supporting both string and symbol keys
+        def extract_standardized_value(auth_data, key)
+          # Try string keys first
+          if auth_data.key?("standardized") && auth_data["standardized"].is_a?(Hash)
+            value = auth_data["standardized"][key]
+            return value if value
+          end
+
+          # Then try symbol keys
+          if auth_data.key?(:standardized) && auth_data[:standardized].is_a?(Hash)
+            value = auth_data[:standardized][key.to_sym]
+            return value if value
+          end
+
+          # No standardized value found
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/clavis/oauth_identity.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Clavis
+  if defined?(ActiveRecord::Base)
+    class OauthIdentity < defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+      belongs_to :authenticatable, polymorphic: true
+
+      validates :provider, presence: true
+      validates :uid, presence: true
+      validates :uid, uniqueness: { scope: :provider }
+
+      # Rails 8.0+ serialization
+      serialize :auth_data
+
+      # Alias for authenticatable to support User model assignment
+      def user
+        authenticatable
+      end
+
+      # Alias for authenticatable= to support User model assignment
+      def user=(user)
+        self.authenticatable = user
+        self.authenticatable_type = user.class.name
+      end
+
+      # Override token getter to decrypt the token
+      def token
+        Clavis::Security::TokenStorage.decrypt(self[:token])
+      end
+
+      # Override token setter to encrypt the token
+      def token=(value)
+        encrypted_token = Clavis::Security::TokenStorage.encrypt(value)
+        self[:token] = encrypted_token
+      end
+
+      # Override refresh_token getter to decrypt the token
+      def refresh_token
+        Clavis::Security::TokenStorage.decrypt(self[:refresh_token])
+      end
+
+      # Override refresh_token setter to encrypt the token
+      def refresh_token=(value)
+        encrypted_token = Clavis::Security::TokenStorage.encrypt(value)
+        self[:refresh_token] = encrypted_token
+      end
+
+      def token_expired?
+        expires_at.present? && expires_at < Time.current
+      end
+
+      def token_valid?
+        token.present? && !token_expired?
+      end
+
+      def ensure_fresh_token
+        return token unless token_expired?
+        return nil unless refresh_token && !refresh_token.empty?
+
+        begin
+          provider_instance = Clavis.provider(
+            provider.to_sym,
+            redirect_uri: Clavis.configuration.providers.dig(provider.to_sym, :redirect_uri)
+          )
+
+          new_tokens = provider_instance.refresh_token(refresh_token)
+
+          self.token = new_tokens[:access_token]
+          self.refresh_token = new_tokens[:refresh_token] || refresh_token
+          self.expires_at = new_tokens[:expires_at] ? Time.at(new_tokens[:expires_at]) : nil
+
+          token
+        rescue Clavis::UnsupportedOperation => e
+          Clavis::Logging.log_token_refresh(provider, false, e.message)
+          token
+        rescue Clavis::Error => e
+          Clavis::Logging.log_error(e)
+          nil
+        end
+      end
+
+      # Store standardized user info in the auth_data field
+      def store_standardized_user_info!
+        return unless auth_data.present?
+
+        normalized = Clavis::UserInfoNormalizer.normalize(provider, auth_data)
+
+        # Store the normalized data in auth_data under a standardized key
+        self.auth_data = auth_data.merge("standardized" => normalized)
+        save! if persisted?
+      end
+    end
+  else
+    # Stub class for environments where ActiveRecord is not available
+    class OauthIdentity
+      attr_accessor :provider, :uid, :token, :refresh_token, :expires_at, :authenticatable, :updated_at
+
+      # Custom accessor for auth_data to ensure it's always initialized as a hash
+      def auth_data
+        @auth_data ||= {}
+      end
+
+      def auth_data=(value)
+        @auth_data = value || {}
+      end
+
+      def initialize(attributes = {})
+        @provider = attributes[:provider]
+        @uid = attributes[:uid]
+        @token = attributes[:token]
+        @refresh_token = attributes[:refresh_token]
+        @expires_at = attributes[:expires_at]
+        self.auth_data = attributes[:auth_data]
+        @authenticatable = attributes[:authenticatable]
+        @persisted = attributes[:persisted] || false
+        @updated_at = attributes[:updated_at] || Time.now
+      end
+
+      def token_expired?
+        !expires_at.nil? && expires_at < Time.now
+      end
+
+      def token_valid?
+        !token.nil? && !token.empty? && !token_expired?
+      end
+
+      def persisted?
+        @persisted
+      end
+
+      def save!
+        @persisted = true
+        self
+      end
+
+      def ensure_fresh_token
+        return token unless token_expired?
+        return nil unless refresh_token && !refresh_token.empty?
+
+        begin
+          provider_instance = Clavis.provider(
+            provider.to_sym,
+            redirect_uri: Clavis.configuration.providers.dig(provider.to_sym, :redirect_uri)
+          )
+
+          new_tokens = provider_instance.refresh_token(refresh_token)
+
+          self.token = new_tokens[:access_token]
+          self.refresh_token = new_tokens[:refresh_token] || refresh_token
+          self.expires_at = new_tokens[:expires_at] ? Time.at(new_tokens[:expires_at]) : nil
+
+          token
+        rescue Clavis::UnsupportedOperation => e
+          Clavis::Logging.log_token_refresh(provider, false, e.message)
+          token
+        rescue Clavis::Error => e
+          Clavis::Logging.log_error(e)
+          nil
+        end
+      end
+
+      # Store standardized user info in the auth_data field
+      def store_standardized_user_info!
+        return unless auth_data.present?
+
+        normalized = Clavis::UserInfoNormalizer.normalize(provider, auth_data)
+
+        # Store the normalized data in auth_data under a standardized key
+        self.auth_data = auth_data.merge("standardized" => normalized)
+        save! if persisted?
+      end
+    end
+  end
+end