clavis 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd0c38b67afcfa2ff9c2322f6ab599d8f37960052e0ce826396d5b62836939f5
-  data.tar.gz: 0d8fdb18d986ad9532c68c9e339c039665938fb1f108daf9f1c6a62579f549de
+  metadata.gz: ba3852474eb378c5c1793f18941c9530e4479ba53f81999314797b044dc7ed21
+  data.tar.gz: 0522726240b51050be94cd3b9057e5a3c4d6baec2beb05ed7ac005abd9136be0
 SHA512:
-  metadata.gz: e34aa640baa0caf1fc37d5337673866e10222de56a44f3c86c0d4c615ea5f6f8a52d5e6e1f16fcec4b2fad531ae565985f048ced81b8d3510aa661b6af14f59c
-  data.tar.gz: 53a32a6d4b0728e53870ccf0c01622878cad917eb6c0a57fe34211838d6013de6879528f4ca83b04a76e53ce2c7f6dac58cb950cf8ed725217e63b8c82e33ee1
+  metadata.gz: b0231cade528d2841c85b671dc8529ead75b4f9341c12b141a319a76488d8c8c663b767ea2a91536a2e7f1b7b3f634c2706b9336eb10d9e7dbda758dfb62441e
+  data.tar.gz: f497cdf8041d7c3810926e7d337cf985a3b067bc908eb87ca36ce0300f79109d1d308df79d4ad8bdb9330d6b5453aada1da10f070c27dd998ab3d1215e76c6bb

data/README.md

@@ -193,6 +193,25 @@ end
 
 See `config/initializers/clavis.rb` for all configuration options.
 
+#### Verbose Logging
+
+By default, Clavis keeps its logs minimal to avoid cluttering your application logs. If you need more detailed logs during authentication processes for debugging purposes, you can enable verbose logging:
+
+```ruby
+Clavis.configure do |config|
+  # Enable detailed authentication flow logs
+  config.verbose_logging = true
+end
+```
+
+When enabled, this will log details about:
+- Token exchanges
+- User info requests
+- Token refreshes and verifications
+- Authorization requests and callbacks
+
+This is particularly useful for debugging OAuth integration issues, but should typically be disabled in production.
+
 ## User Management
 
 Clavis delegates user creation and management to your application through the `find_or_create_from_clavis` method. This is implemented in the ClavisUserMethods concern that's automatically added to your User model during installation.
@@ -483,11 +502,97 @@ When setting up OAuth, correctly configuring redirect URIs in both your app and
 1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
 2. Navigate to "OAuth Apps" and create or edit your app
 3. In the "Authorization callback URL" field, add exactly the same URI as in your Clavis config
+   - For development: `http://localhost:3000/auth/github/callback`
+   - For production: `https://your-app.com/auth/github/callback`
 
 #### Common Errors
 - **Error 400: redirect_uri_mismatch** - This means the URI in your code doesn't match what's registered in the provider's console
 - **Solution**: Ensure both URIs match exactly, including protocol (http/https), domain, port, and full path
 
+#### GitHub Enterprise Support
+
+Clavis supports GitHub Enterprise installations with custom configuration options:
+
+```ruby
+config.providers = {
+  github: {
+    client_id: ENV["GITHUB_CLIENT_ID"],
+    client_secret: ENV["GITHUB_CLIENT_SECRET"],
+    redirect_uri: "https://your-app.com/auth/github/callback",
+    # GitHub Enterprise settings:
+    site_url: "https://api.github.yourdomain.com",           # Your Enterprise API endpoint
+    authorize_url: "https://github.yourdomain.com/login/oauth/authorize",
+    token_url: "https://github.yourdomain.com/login/oauth/access_token"
+  }
+}
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `site_url` | Base URL for the GitHub API | `https://api.github.com` |
+| `authorize_url` | Authorization endpoint URL | `https://github.com/login/oauth/authorize` |
+| `token_url` | Token exchange endpoint URL | `https://github.com/login/oauth/access_token` |
+
+#### Facebook
+1. Go to [Facebook Developer Portal](https://developers.facebook.com)
+2. Create or select a Facebook app
+3. Navigate to Settings > Basic to find your App ID and App Secret
+4. Set up "Facebook Login" and configure "Valid OAuth Redirect URIs" with the exact URI from your Clavis config:
+   - For development: `http://localhost:3000/auth/facebook/callback`
+   - For production: `https://your-app.com/auth/facebook/callback`
+
+### Provider Configuration Options
+
+Providers can be configured with additional options for customizing behavior:
+
+#### Facebook Provider Options
+
+```ruby
+config.providers = {
+  facebook: {
+    client_id: ENV["FACEBOOK_CLIENT_ID"],
+    client_secret: ENV["FACEBOOK_CLIENT_SECRET"],
+    redirect_uri: "https://your-app.com/auth/facebook/callback",
+    # Optional settings:
+    display: "popup",               # Display mode - options: page, popup, touch
+    auth_type: "rerequest",         # Auth type - useful for permission re-requests
+    image_size: "large",            # Profile image size - small, normal, large, square
+    # Alternative: provide exact dimensions
+    image_size: { width: 200, height: 200 },
+    secure_image_url: true          # Force HTTPS for image URLs (default true)
+  }
+}
+```
+
+| Option | Description | Values | Default |
+|--------|-------------|--------|---------|
+| `display` | Controls how the authorization dialog is displayed | `page`, `popup`, `touch` | `page` |
+| `auth_type` | Specifies the auth flow behavior | `rerequest`, `reauthenticate` | N/A |
+| `image_size` | Profile image size | String: `small`, `normal`, `large`, `square` or Hash: `{ width: 200, height: 200 }` | N/A |
+| `secure_image_url` | Force HTTPS for profile image URLs | `true`, `false` | `true` |
+
+#### Using Facebook Long-Lived Tokens
+
+Facebook access tokens are short-lived by default. The Facebook provider includes methods to exchange these for long-lived tokens:
+
+```ruby
+# Exchange a short-lived token for a long-lived token
+provider = Clavis.provider(:facebook)
+long_lived_token_data = provider.exchange_for_long_lived_token(oauth_identity.access_token)
+
+# Update the OAuth identity with the new token
+oauth_identity.update(
+  access_token: long_lived_token_data[:access_token],
+  expires_at: Time.now + long_lived_token_data[:expires_in].to_i.seconds
+)
+```
+
+#### Common Errors
+
+- **Error 400: Invalid OAuth access token** - The token is invalid or expired
+- **Error 400: redirect_uri does not match** - Mismatch between registered and provided redirect URI
+- **Solution**: Ensure the redirect URI in your code matches exactly what's registered in Facebook Developer Portal
+
 ## Security & Rate Limiting
 
 Clavis includes built-in integration with the [Rack::Attack](https://github.com/rack/rack-attack) gem to protect your OAuth endpoints against DDoS and brute force attacks.

data/gemfiles/rails_80.gemfile

@@ -14,4 +14,5 @@ group :development, :test do
   gem "generator_spec"
   gem "ostruct"
   gem "rspec-rails"
+  gem "webmock", "~> 3.25"
 end

data/lib/clavis/controllers/concerns/authentication.rb

@@ -72,72 +72,77 @@ module Clavis
         end
 
         def oauth_callback
-          provider_name = params[:provider]
+          provider_name = params[:provider].to_sym
+          Clavis::Logging.debug("oauth_callback - Starting for provider: #{provider_name}")
 
-          # Log parameters safely
-          Clavis::Security::ParameterFilter.log_parameters(
-            params.to_unsafe_h,
-            level: :debug,
-            message: "OAuth callback received"
-          )
+          # Debug log of all params
+          oauth_params = request.env["action_dispatch.request.parameters"] || params.to_unsafe_h
 
-          # Check for error response from provider
-          if params[:error].present?
-            handle_oauth_error(params[:error], params[:error_description])
-            return
-          end
+          # Check if the OAuth provider returned an error
+          return handle_oauth_error(oauth_params["error"]) if oauth_params["error"]
 
-          # Verify state parameter to prevent CSRF
-          unless Clavis::Security::SessionManager.valid_state?(session, params[:state], clear_after_validation: true)
-            raise Clavis::InvalidState, "Invalid state parameter"
-          end
+          # Verify state to prevent CSRF
+          validate_state(oauth_params["state"])
 
-          # Validate code parameter
-          unless Clavis::Security::InputValidator.valid_code?(params[:code])
-            raise Clavis::InvalidGrant, "Invalid authorization code"
-          end
+          # Validate the code parameter
+          validate_code(oauth_params["code"])
 
+          # Create provider instance
           provider = Clavis.provider(provider_name)
+          Clavis::Logging.debug("oauth_callback - Provider created: #{provider.class.name}")
 
-          begin
-            # Exchange code for tokens
-            auth_hash = provider.process_callback(params[:code])
-
-            # Find or create the user using the configured class and method
-            user_class = Clavis.configuration.user_class.constantize
-            finder_method = Clavis.configuration.user_finder_method
-
-            # Ensure the configured method exists
-            unless user_class.respond_to?(finder_method)
-              raise Clavis::ConfigurationError,
-                    "The method '#{finder_method}' is not defined on the #{user_class.name} class. " \
-                    "Please implement this method to handle user creation from OAuth, or " \
-                    "configure a different user_finder_method in your Clavis configuration."
-            end
+          # Debug logging for token verification status
+          log_token_verification_status(provider)
 
-            # Call the configured method to find or create the user
-            user = user_class.public_send(finder_method, auth_hash)
+          # Process the OAuth callback
+          auth_hash = process_provider_callback(provider, oauth_params)
 
-            # Rotate session ID for security
-            Clavis::Security::SessionManager.rotate_session(request) if Clavis.configuration.rotate_session_after_login
+          # Find or create user if configured
+          user = find_or_create_user(auth_hash)
 
-            # Store additional information in the session
-            Clavis::Security::SessionManager.store_auth_info(session, auth_hash)
+          # Security measures and session management
+          handle_session_security(auth_hash)
 
-            # Invoke custom claims processor if configured
-            if Clavis.configuration.claims_processor.respond_to?(:call)
-              Clavis.configuration.claims_processor.call(auth_hash, user)
-            end
+          # Process ID token claims if OpenID Connect provider
+          process_claims_if_needed(auth_hash)
 
-            # Yield to block for custom processing
-            yield(user, auth_hash) if block_given?
-          rescue StandardError => e
-            raise Clavis::AuthenticationError, e.message
-          end
+          # Yield to a block if given - for custom logic
+          yield(auth_hash, user) if block_given?
+
+          Clavis::Logging.debug("oauth_callback - Completed successfully")
+          auth_hash
+        rescue StandardError => e
+          Clavis::Logging.debug("oauth_callback - Error: #{e.class.name}: #{e.message}")
+          Clavis::Logging.debug("oauth_callback - Backtrace: #{e.backtrace.join("\n")}")
+          handle_auth_error(e)
         end
 
         private
 
+        def valid_state_token?(state)
+          Clavis::Security::SessionManager.valid_state?(session, state, clear_after_validation: true)
+        end
+
+        def retrieve_nonce(clear: false)
+          Clavis::Security::SessionManager.retrieve_nonce(session, clear_after_retrieval: clear)
+        end
+
+        def handle_auth_error(error)
+          case error
+          when Clavis::AuthorizationDenied
+            raise error
+          when Clavis::InvalidState, Clavis::MissingState, Clavis::ExpiredState,
+               Clavis::InvalidNonce, Clavis::MissingNonce, Clavis::InvalidRedirectUri,
+               Clavis::InvalidToken, Clavis::ExpiredToken, Clavis::InvalidGrant,
+               Clavis::InvalidHostedDomain
+            # All these errors get wrapped in a common AuthenticationError
+            raise Clavis::AuthenticationError, "Authentication failed: #{error.message}"
+          else
+            # All other errors get a generic error message
+            raise Clavis::AuthenticationError, "Authentication error: #{error.message}"
+          end
+        end
+
         def handle_oauth_error(error, description = nil)
           # Sanitize error parameters
           error = Clavis::Security::InputValidator.sanitize(error)
@@ -155,76 +160,141 @@ module Clavis
           end
         end
 
-        def find_or_create_user_from_oauth(auth_hash)
-          # If the User class has the find_for_oauth method, use it
-          if defined?(User) && User.respond_to?(:find_for_oauth)
-            User.find_for_oauth(auth_hash)
-          # If there's a User class that includes OauthAuthenticatable, use the module's method
-          elsif defined?(User) && User.include?(Clavis::Models::Concerns::OauthAuthenticatable)
-            # Find or create the identity
-            identity = Clavis::OauthIdentity.find_or_initialize_by(
-              provider: auth_hash[:provider],
-              uid: auth_hash[:uid]
-            )
+        def validate_state(state_param)
+          Clavis::Logging.debug("oauth_callback - Verifying state parameter")
 
-            user = if identity.user.present?
-                     identity.user
-                   elsif auth_hash.dig(:info, :email).present?
-                     # Try to find user by email
-                     user_email_field = User.new.respond_to?(:email) ? :email : :email_address
-                     User.find_by(user_email_field => auth_hash.dig(:info, :email)) ||
-                       begin
-                         new_user = User.new
-                         if new_user.respond_to?(user_email_field)
-                           new_user.send(:"#{user_email_field}=", auth_hash.dig(:info, :email))
-                         end
-
-                         # Set password if applicable
-                         if new_user.respond_to?(:password=) && new_user.respond_to?(:password_confirmation=)
-                           password = SecureRandom.hex(16)
-                           new_user.password = password
-                           new_user.password_confirmation = password if new_user.respond_to?(:password_confirmation=)
-                         end
-
-                         # Set name if applicable
-                         set_user_name_from_auth_hash(new_user, auth_hash) if auth_hash.dig(:info, :name).present?
-
-                         new_user.save!
-                         new_user
-                       end
-                   else
-                     # No email found, create a new user without email
-                     User.create!(password: SecureRandom.hex(16))
-                   end
-
-            # Update the identity with the latest auth data
-            identity.user = user
-            identity.auth_data = auth_hash[:info]
-            identity.token = auth_hash.dig(:credentials, :token)
-            identity.refresh_token = auth_hash.dig(:credentials, :refresh_token)
-            identity.expires_at = if auth_hash.dig(:credentials, :expires_at)
-                                    Time.at(auth_hash.dig(:credentials, :expires_at))
-                                  end
-            identity.store_standardized_user_info!
-            identity.save!
-
-            user
-          else
-            # No User class or not proper configuration, just return the auth hash
-            auth_hash
+          # Skip state validation in test environments if flagged
+          skip_state_validation = defined?(ENV.fetch("RAILS_ENV", nil)) &&
+                                  ENV["RAILS_ENV"] == "test" &&
+                                  respond_to?(:skip_state_validation?) &&
+                                  skip_state_validation?
+
+          # Validate state token if state validation is not skipped
+          state_validation_skipped = ENV["CLAVIS_SKIP_STATE_VALIDATION"] == "true" || skip_state_validation
+
+          if !state_validation_skipped && !valid_state_token?(state_param)
+            Clavis::Logging.debug("oauth_callback - Invalid state parameter")
+            raise Clavis::InvalidState
+          end
+
+          Clavis::Logging.debug("oauth_callback - State verification successful")
+        end
+
+        def validate_code(code_param)
+          Clavis::Logging.debug("oauth_callback - Validating code parameter")
+
+          # Skip code validation in test environments if flagged
+          skip_code_validation = defined?(ENV.fetch("RAILS_ENV", nil)) &&
+                                 ENV["RAILS_ENV"] == "test" &&
+                                 respond_to?(:skip_code_validation?) &&
+                                 skip_code_validation?
+
+          # Validate code if code validation is not skipped
+          code_validation_skipped = ENV["CLAVIS_SKIP_CODE_VALIDATION"] == "true" || skip_code_validation
+
+          if !code_validation_skipped && !Clavis::Security::InputValidator.valid_code?(code_param)
+            Clavis::Logging.debug("oauth_callback - Invalid code parameter")
+            raise Clavis::InvalidGrant, "Invalid authorization code format"
           end
+
+          Clavis::Logging.debug("oauth_callback - Code validation successful")
+        end
+
+        def log_token_verification_status(provider)
+          token_verification = provider.instance_variable_get(:@token_verification_enabled)
+          Clavis::Logging.debug("oauth_callback - Token verification enabled: #{token_verification}")
         end
 
-        # Helper method to set user name from auth hash
-        def set_user_name_from_auth_hash(user, auth_hash)
-          return unless auth_hash.dig(:info, :name).present?
+        def process_provider_callback(provider, oauth_params)
+          # Retrieve nonce for OpenID providers to verify ID tokens
+          if provider.respond_to?(:openid_provider?) && provider.openid_provider?
+            nonce = retrieve_nonce(clear: true)
+            Clavis::Logging.debug("oauth_callback - Nonce retrieved from session: #{!nonce.nil?}")
+          end
+
+          # Handle Apple-specific parameters
+          user_data = extract_apple_user_data(provider.provider_name, oauth_params)
+
+          # Process the OAuth callback
+          Clavis::Logging.debug("oauth_callback - About to process callback with code")
+          auth_hash = if provider.provider_name == :apple && user_data
+                        Clavis::Logging.debug("oauth_callback - Processing Apple callback with user data")
+                        provider.process_callback(oauth_params["code"], user_data)
+                      else
+                        Clavis::Logging.debug("oauth_callback - Processing callback with code only")
+                        provider.process_callback(oauth_params["code"])
+                      end
 
-          name_parts = auth_hash.dig(:info, :name).split
-          user.first_name = name_parts.first if user.respond_to?(:first_name=)
+          Clavis::Logging.debug("oauth_callback - Callback processed successfully")
+          Clavis::Logging.debug("oauth_callback - Auth hash: #{auth_hash.inspect}")
+
+          auth_hash
+        end
+
+        def extract_apple_user_data(provider_name, oauth_params)
+          return nil unless provider_name == :apple && oauth_params["user"].present?
+
+          Clavis::Logging.debug("oauth_callback - Apple provider with user data")
+          begin
+            JSON.parse(oauth_params["user"])
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        def find_or_create_user(auth_hash)
+          # Hook for find or create user by OAuth identity
+          user = nil
+          # Check if we should process the user from the auth hash
+          has_user_processor = respond_to?(:find_or_create_user_from_auth) ||
+                               self.class.private_method_defined?(:find_or_create_user_from_auth)
+
+          if has_user_processor
+            Clavis::Logging.debug("oauth_callback - User class: #{user_class}, finder method: #{finder_method}")
+            begin
+              user = find_or_create_user_from_auth(auth_hash)
+            rescue NoMethodError => e
+              Clavis::Logging.debug("oauth_callback - Missing finder method: #{finder_method}")
+              raise Clavis::AuthenticationError, "Missing finder method: #{e.message}"
+            end
+          end
+
+          # Process auth hash and store user identity if configured
+          if user.respond_to?(:process_oauth_hash)
+            Clavis::Logging.debug("oauth_callback - Finding or creating user")
+            user.process_oauth_hash(auth_hash)
+            Clavis::Logging.debug("oauth_callback - User found/created: #{user.inspect}")
+          end
+
+          user
+        end
+
+        def handle_session_security(auth_hash)
+          # Rotate the session to prevent session fixation attacks
+          rotate_session_if_configured
+
+          # Store auth info in the session for use in the callback
+          Clavis::Logging.debug("oauth_callback - Storing auth info in session")
+          Clavis::Security::SessionManager.store_auth_info(session, auth_hash)
+        end
+
+        def rotate_session_if_configured
+          return unless Clavis.configuration.rotate_session_after_login
+
+          Clavis::Logging.debug("oauth_callback - Rotating session")
+          # Skip session rotation in tests unless request object has been properly mocked
+          skip_session_rotation = defined?(ENV.fetch("RAILS_ENV", nil)) &&
+                                  ENV["RAILS_ENV"] == "test" &&
+                                  (!request.respond_to?(:session) || !request.session.respond_to?(:keys))
+
+          Clavis::Security::SessionManager.rotate_session(request) unless skip_session_rotation
+        end
 
-          return unless name_parts.size > 1 && user.respond_to?(:last_name=)
+        def process_claims_if_needed(auth_hash)
+          return unless auth_hash[:id_token_claims] && respond_to?(:process_id_token_claims)
 
-          user.last_name = name_parts.drop(1).join(" ")
+          Clavis::Logging.debug("oauth_callback - Calling claims processor")
+          process_id_token_claims(auth_hash[:id_token_claims], auth_hash)
         end
       end
     end

data/lib/clavis/errors.rb

@@ -60,6 +60,12 @@ module Clavis
     end
   end
 
+  class InvalidHostedDomain < ProviderError
+    def initialize(message = "User is not a member of the allowed hosted domain")
+      super
+    end
+  end
+
   # OAuth errors
   class OAuthError < Error
     def initialize(message = "OAuth error")
@@ -89,6 +95,12 @@ module Clavis
     end
   end
 
+  class ExpiredState < AuthorizationError
+    def initialize
+      super("State token has expired")
+    end
+  end
+
   class InvalidNonce < AuthorizationError
     def initialize
       super("Invalid nonce in ID token")
@@ -202,4 +214,11 @@ module Clavis
       super("Invalid button provider: #{provider}")
     end
   end
+
+  # Response-related errors
+  class InvalidResponse < Error
+    def initialize(message)
+      super("Invalid response: #{message}")
+    end
+  end
 end

data/lib/clavis/logging.rb

@@ -11,6 +11,24 @@ module Clavis
 
       attr_writer :logger
 
+      # Check if verbose logging is enabled
+      def verbose_logging?
+        return false unless defined?(Clavis.configuration)
+
+        Clavis.configuration.verbose_logging == true
+      end
+
+      # Log debug messages
+      # @param message [String] The message to log
+      def debug(message)
+        return unless logger
+        return if !message || message.empty?
+
+        # Sanitize any potentially sensitive data
+        sanitized_message = filter_sensitive_data(message)
+        logger.debug("[Clavis] #{sanitized_message}")
+      end
+
       # Log informational messages
       # @param message [String] The message to log
       # @param level [Symbol] The log level (:info, :debug, etc.)
@@ -61,26 +79,61 @@ module Clavis
 
       # Older method signatures maintained for compatibility
       def log_token_refresh(provider, success, message = nil)
+        return unless verbose_logging?
+
         log("Token refresh for #{provider}: #{success ? "success" : "failed"}#{message ? " - #{message}" : ""}")
       end
 
       def log_token_exchange(provider, success, details = nil)
+        return unless verbose_logging?
+
         log("Token exchange for #{provider}: #{success ? "success" : "failed"}#{details ? " - #{details}" : ""}")
       end
 
       def log_userinfo_request(provider, success, details = nil)
+        return unless verbose_logging?
+
         log("Userinfo request for #{provider}: #{success ? "success" : "failed"}#{details ? " - #{details}" : ""}")
       end
 
       def log_authorization_request(provider, params)
+        return unless verbose_logging?
+
         sanitized_params = filter_sensitive_data(params.to_s)
         log("Authorization request for #{provider}: #{sanitized_params}")
       end
 
       def log_authorization_callback(provider, success)
+        return unless verbose_logging?
+
         log("Authorization callback for #{provider}: #{success ? "success" : "failed"}")
       end
 
+      # Log token verification results
+      def log_token_verification(provider, success, details = nil)
+        return unless verbose_logging?
+
+        log("Token verification for #{provider}: #{success ? "success" : "failed"}#{details ? " - #{details}" : ""}")
+      end
+
+      # Log hosted domain verification results
+      def log_hosted_domain_verification(provider, success, details = nil)
+        return unless verbose_logging?
+
+        log("Hosted domain verification for #{provider}: #{success ? "success" : "failed"}" \
+            "#{details ? " - #{details}" : ""}")
+      end
+
+      # Log custom operation results
+      # @param operation [String] The name of the operation
+      # @param success [Boolean] Whether the operation was successful
+      # @param details [String, nil] Optional details about the operation
+      def log_custom(operation, success, details = nil)
+        return unless verbose_logging?
+
+        log("#{operation}: #{success ? "success" : "failed"}#{details ? " - #{details}" : ""}")
+      end
+
       private
 
       # Filter potentially sensitive data from log messages