clavis 0.7.2 → 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.2"
+  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/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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: clavis
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Clayton Lengel-Zigich
 bindir: exe
 cert_chain: []
-date: 2025-03-20 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -197,6 +197,7 @@ files:
 - lib/clavis/providers/github.rb
 - lib/clavis/providers/google.rb
 - lib/clavis/providers/microsoft.rb
+- lib/clavis/providers/token_exchange_handler.rb
 - lib/clavis/security/csrf_protection.rb
 - lib/clavis/security/https_enforcer.rb
 - lib/clavis/security/input_validator.rb