clavis 0.7.1 → 0.8.0

data/lib/clavis/security/csrf_protection.rb

@@ -6,10 +6,14 @@ module Clavis
   module Security
     module CsrfProtection
       class << self
+        # Delimiter used to separate state from HMAC
+        STATE_HMAC_DELIMITER = "::"
+
         # Generates a secure random state token for CSRF protection
+        # @param length [Integer] The byte length for the token (resulting hex string will be twice this length)
         # @return [String] A secure random state token
-        def generate_state
-          SecureRandom.hex(24)
+        def generate_state(length = 24)
+          SecureRandom.hex(length)
         end
 
         # Validates that the actual state matches the expected state
@@ -24,10 +28,19 @@ module Clavis
 
         # Stores a state token in the Rails session
         # @param controller [ActionController::Base] The controller instance
+        # @param expiry [Time, Integer] Optional expiration time (Time object or seconds from now)
+        # @param length [Integer] Optional byte length for the token
         # @return [String] The generated state token
-        def store_state_in_session(controller)
-          state = generate_state
+        def store_state_in_session(controller, expiry = nil, length = 24)
+          state = generate_state(length)
           controller.session[:oauth_state] = state
+
+          # Store expiration if provided
+          if expiry
+            expiry_time = expiry.is_a?(Integer) ? Time.now.to_i + expiry : expiry.to_i
+            controller.session[:oauth_state_expiry] = expiry_time
+          end
+
           state
         end
 
@@ -36,26 +49,48 @@ module Clavis
         # @param actual_state [String] The state received from the OAuth provider
         # @raise [Clavis::MissingState] If either state is nil
         # @raise [Clavis::InvalidState] If the states don't match
+        # @raise [Clavis::ExpiredState] If the state token has expired
         def validate_state_from_session!(controller, actual_state)
           expected_state = controller.session[:oauth_state]
+          expiry = controller.session[:oauth_state_expiry]
+
+          # Check for expiration if an expiry was set
+          if expiry && Time.now.to_i > expiry
+            # Clear expired state from session
+            controller.session.delete(:oauth_state)
+            controller.session.delete(:oauth_state_expiry)
+            raise Clavis::ExpiredState
+          end
+
           validate_state!(actual_state, expected_state)
 
           # Clear the state from the session after validation
           controller.session.delete(:oauth_state)
+          controller.session.delete(:oauth_state_expiry)
         end
 
         # Generates a nonce for OIDC requests
+        # @param length [Integer] The byte length for the nonce (resulting hex string will be twice this length)
         # @return [String] A secure random nonce
-        def generate_nonce
-          SecureRandom.hex(16)
+        def generate_nonce(length = 16)
+          SecureRandom.hex(length)
         end
 
         # Stores a nonce in the Rails session
         # @param controller [ActionController::Base] The controller instance
+        # @param expiry [Time, Integer] Optional expiration time (Time object or seconds from now)
+        # @param length [Integer] Optional byte length for the nonce
         # @return [String] The generated nonce
-        def store_nonce_in_session(controller)
-          nonce = generate_nonce
+        def store_nonce_in_session(controller, expiry = nil, length = 16)
+          nonce = generate_nonce(length)
           controller.session[:oauth_nonce] = nonce
+
+          # Store expiration if provided
+          if expiry
+            expiry_time = expiry.is_a?(Integer) ? Time.now.to_i + expiry : expiry.to_i
+            controller.session[:oauth_nonce_expiry] = expiry_time
+          end
+
           nonce
         end
 
@@ -64,14 +99,63 @@ module Clavis
         # @param id_token_nonce [String] The nonce from the ID token
         # @raise [Clavis::MissingNonce] If either nonce is nil
         # @raise [Clavis::InvalidNonce] If the nonces don't match
+        # @raise [Clavis::ExpiredState] If the nonce has expired
         def validate_nonce_from_session!(controller, id_token_nonce)
           expected_nonce = controller.session[:oauth_nonce]
+          expiry = controller.session[:oauth_nonce_expiry]
+
+          # Check for expiration if an expiry was set
+          if expiry && Time.now.to_i > expiry
+            # Clear expired nonce from session
+            controller.session.delete(:oauth_nonce)
+            controller.session.delete(:oauth_nonce_expiry)
+            raise Clavis::ExpiredState
+          end
 
           raise Clavis::MissingNonce if id_token_nonce.nil? || expected_nonce.nil?
           raise Clavis::InvalidNonce unless id_token_nonce == expected_nonce
 
           # Clear the nonce from the session after validation
           controller.session.delete(:oauth_nonce)
+          controller.session.delete(:oauth_nonce_expiry)
+        end
+
+        # Binds a state token to the session context for extra security
+        # @param controller [ActionController::Base] The controller instance
+        # @param state [String] The state token to bind
+        # @return [String] The bound state token (state::hmac format)
+        def bind_state_to_session(controller, state)
+          session_id = controller.request.session.id
+          hmac = OpenSSL::HMAC.hexdigest("SHA256", session_id, state)
+          "#{state}#{STATE_HMAC_DELIMITER}#{hmac}"
+        end
+
+        # Validates a state token that was bound to the session
+        # @param controller [ActionController::Base] The controller instance
+        # @param bound_state [String] The bound state token (state::hmac format)
+        # @return [String] The original state if valid
+        # @raise [Clavis::InvalidState] If the state is invalid or HMAC doesn't match
+        def validate_bound_state(controller, bound_state)
+          # Split using the delimiter - allows state to contain hyphens
+          parts = bound_state.to_s.split(STATE_HMAC_DELIMITER)
+
+          # We expect exactly 2 parts: state and hmac
+          raise Clavis::InvalidState if parts.length != 2
+
+          state = parts[0]
+          received_hmac = parts[1]
+
+          # Basic validation
+          raise Clavis::InvalidState if state.nil? || received_hmac.nil? || state.empty? || received_hmac.empty?
+
+          # Verify HMAC
+          session_id = controller.request.session.id
+          expected_hmac = OpenSSL::HMAC.hexdigest("SHA256", session_id, state)
+
+          raise Clavis::InvalidState unless received_hmac == expected_hmac
+
+          # Return the original state if valid
+          state
         end
       end
     end

data/lib/clavis/security/session_manager.rb

@@ -68,6 +68,16 @@ module Clavis
           nonce
         end
 
+        # Retrieve the stored nonce from the session
+        # @param session [Hash] The session hash
+        # @param clear_after_retrieval [Boolean] Whether to clear the nonce after retrieval
+        # @return [String, nil] The stored nonce or nil if not found
+        def retrieve_nonce(session, clear_after_retrieval: false)
+          nonce = retrieve(session, :oauth_nonce)
+          delete(session, :oauth_nonce) if clear_after_retrieval
+          nonce
+        end
+
         # Check if a nonce is valid
         # @param session [Hash] The session hash
         # @param nonce [String] The nonce to validate

data/lib/clavis/version.rb

@@ -2,5 +2,5 @@
 
 module Clavis
   # The current version of Clavis.
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/lib/clavis.rb

@@ -16,6 +16,11 @@ require_relative "clavis/security/session_manager"
 require_relative "clavis/security/rate_limiter"
 require "clavis/user_info_normalizer"
 
+# Load required gems
+require "jwt"
+require "json"
+require "faraday"
+
 # Only load provider classes if they're not already defined (for testing)
 unless defined?(Clavis::Providers::Base)
   require_relative "clavis/providers/base"

data/lib/generators/clavis/install_generator.rb

@@ -103,32 +103,49 @@ module Clavis
       end
 
       def show_post_install_message
-        say "\nClavis has been installed successfully!"
-
-        # Next steps
-        say "\nNext steps:"
-
+        say "\nClavis has been installed successfully! 🔑"
+
+        # What was done section
+        say "\n=== What Was Done ==="
+        say "✅ Generated migration for OAuth identities"
+        say "✅ Added OAuth fields to your User model"
+        say "✅ Created ClavisUserMethods concern for your User model"
+        say "✅ Mounted Clavis engine at '/auth' in routes.rb"
+        say "✅ Generated configuration initializer"
+
+        # Required steps section
+        say "\n=== Required Steps ==="
         steps = []
 
-        if @provide_css_instructions
-          steps << "Include the Clavis styles in your layout:\n   <%= stylesheet_link_tag 'clavis_styles' %>"
-        end
-
-        steps << "Configure your providers in config/initializers/clavis.rb"
-        steps << "Run migrations: rails db:migrate"
-        steps << "⚠️ Customize the user creation code in app/models/concerns/clavis_user_methods.rb"
-        steps << "Add OAuth buttons to your views:\n   <%= clavis_oauth_button :google %>"
+        steps << "Run migrations:\n   $ rails db:migrate"
+        steps << "Configure your providers in config/initializers/clavis.rb:\n   • Add your client_id and client_secret\n   • Set correct redirect_uri values" # rubocop:disable Layout/LineLength
+        steps << "⚠️ IMPORTANT: Customize user creation in app/models/concerns/clavis_user_methods.rb\n   • The default only sets the email field, which is likely insufficient\n   • Add all required fields for your User model" # rubocop:disable Layout/LineLength
 
         # Output numbered steps
         steps.each_with_index do |step, index|
           say "#{index + 1}. #{step}"
         end
 
-        say "\nClavis has configured your User model with OAuth support via the ClavisUserMethods concern."
-        say "IMPORTANT: The default implementation only sets the email field when creating users."
-        say "You MUST customize this to include all required fields for your User model."
+        # Password validation section
+        say "\n=== For Password-Protected Users ==="
+        say "If your User model uses has_secure_password:"
+        say "• Uncomment the password validation section in app/models/concerns/clavis_user_methods.rb"
+        say "• Choose one of the approaches described there"
+
+        # View integration section
+        say "\n=== Using In Your Views ==="
+        say "Add OAuth buttons to your login page:"
+        say "<%= clavis_oauth_button :google %>"
+        say "<%= clavis_oauth_button :github %>"
+
+        # CSS styling section
+        if @provide_css_instructions
+          say "\n=== For CSS Styling ==="
+          say "Include Clavis styles in your layout:"
+          say "<%= stylesheet_link_tag 'clavis_styles' %>"
+        end
 
-        say "\nFor more information, see the documentation at https://github.com/clayton/clavis"
+        say "\nFor more information, see: https://github.com/clayton/clavis"
       end
 
       private

data/lib/generators/clavis/templates/initializer.rb

@@ -17,8 +17,10 @@ Clavis.configure do |config|
   # Default scopes to request from providers
   # config.default_scopes = "email profile"
 
-  # Enable verbose logging for debugging
-  # config.verbose_logging = true
+  # Enable verbose logging for authentication processes (disabled by default)
+  # When enabled, this will log details about token exchanges, user info requests,
+  # token refreshes, etc. for debugging purposes
+  # config.verbose_logging = false
   
   # User class and finder method
   # These settings control how Clavis finds or creates users from OAuth data

data/lib/generators/clavis/user_method/user_method_generator.rb

@@ -197,22 +197,11 @@ module Clavis
       end
 
       def show_instructions
-        say "\nThe ClavisUserMethods concern has been created and included in your User model."
-        say "This gives your User model the ability to find or create users from OAuth data."
-
-        say "\n⚠️  IMPORTANT: You must customize the user creation code to match your User model!"
-        say "The default implementation only sets the email field, which may not be sufficient."
-
-        say "\n⚠️  IMPORTANT: If your User model uses has_secure_password, you need to handle password validation!"
-        say "Look for the password validation section in app/models/concerns/clavis_user_methods.rb and"
-        say "uncomment one of the approaches described there."
-
-        say "\nTo customize:"
-        say "  1. Edit app/models/concerns/clavis_user_methods.rb"
-        say "  2. Add required fields to the user creation in find_or_create_from_clavis"
-        say "  3. Handle password validation if your model uses has_secure_password"
-
-        say "\nFor more information, see the documentation at https://github.com/clayton/clavis"
+        # The main instructions will be handled by install_generator.rb
+        # This is just a simple confirmation of what was done
+        say "\nClavis user methods have been added to your User model."
+        say "✅ Created app/models/concerns/clavis_user_methods.rb"
+        say "✅ Added 'include ClavisUserMethods' to your User model"
       end
     end
   end