clavis 0.7.1

data/lib/clavis/security/parameter_filter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Clavis
+  module Security
+    module ParameterFilter
+      SENSITIVE_PARAMETERS = [
+        :code,           # Authorization code
+        :token,          # Access token
+        :access_token,   # Access token
+        :refresh_token,  # Refresh token
+        :id_token,       # ID token
+        :client_secret,  # Client secret
+        :state,          # CSRF state token
+        :nonce,          # OIDC nonce
+        :password,       # Just in case
+        :secret          # Generic secret
+      ].freeze
+
+      class << self
+        # Filters sensitive parameters from a hash
+        # @param params [Hash] The parameters to filter
+        # @return [Hash] The filtered parameters
+        def filter_parameters(params)
+          return params unless Clavis.configuration.parameter_filter_enabled
+          return params if params.nil? || !params.is_a?(Hash)
+
+          filtered_params = params.dup
+          SENSITIVE_PARAMETERS.each do |param|
+            filtered_params[param] = "[FILTERED]" if filtered_params.key?(param)
+
+            # Also check for string keys
+            string_param = param.to_s
+            filtered_params[string_param] = "[FILTERED]" if filtered_params.key?(string_param)
+          end
+
+          filtered_params
+        end
+
+        # Alias for filter_parameters for backward compatibility
+        alias filter_params filter_parameters
+
+        # Installs the parameter filter in Rails if available
+        # This should be called during initialization
+        def install_rails_filter
+          return unless defined?(Rails) && Rails.application&.config.respond_to?(:filter_parameters)
+
+          Rails.application.config.filter_parameters.concat(SENSITIVE_PARAMETERS)
+          Clavis.logger.info("Installed Clavis parameter filters in Rails")
+        end
+
+        # Logs parameters safely by filtering sensitive values
+        # @param params [Hash] The parameters to log
+        # @param level [Symbol] The log level (:info, :debug, etc.)
+        # @param message [String] The message to log
+        def log_parameters(params, level: :debug, message: "Parameters")
+          return unless Clavis.logger
+
+          filtered = filter_parameters(params)
+          Clavis.logger.send(level, "#{message}: #{filtered.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/clavis/security/rate_limiter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Clavis
+  module Security
+    # RateLimiter provides integration with Rack::Attack for protecting Clavis endpoints
+    # against DDoS and brute force attacks.
+    module RateLimiter
+      class << self
+        # Configures Rack::Attack with default throttling rules for Clavis
+        # @param app [Rails::Application] The Rails application
+        def configure(_app)
+          return unless defined?(Rack::Attack)
+
+          # Skip if rate limiting is disabled
+          return unless Clavis.configuration.rate_limiting_enabled
+
+          Clavis.logger.info("Configuring Rack::Attack for Clavis endpoints")
+
+          configure_throttles
+          configure_blocklist
+          configure_response
+        end
+
+        # Configures throttling rules for Clavis endpoints
+        def configure_throttles
+          return unless defined?(Rack::Attack)
+
+          # Throttle login attempts for a given email parameter
+          Rack::Attack.throttle("clavis/auth/callback/email", limit: 5, period: 20.seconds) do |req|
+            if req.path =~ %r{/auth/\w+/callback} && req.params["email"].present?
+              # Throttle by normalized email
+              req.params["email"].to_s.downcase.gsub(/\s+/, "")
+            end
+          end
+
+          # Throttle OAuth callback attempts by IP address
+          Rack::Attack.throttle("clavis/auth/callback/ip", limit: 15, period: 60.seconds) do |req|
+            req.ip if req.path =~ %r{/auth/\w+/callback}
+          end
+
+          # Throttle OAuth authorize endpoints
+          Rack::Attack.throttle("clavis/auth/authorize/ip", limit: 20, period: 60.seconds) do |req|
+            req.ip if req.path =~ %r{/auth/\w+} && !req.path.include?("/callback")
+          end
+
+          # Allow custom throttles to be defined via configuration
+          Clavis.configuration.custom_throttles.each do |name, config|
+            Rack::Attack.throttle("clavis/#{name}", limit: config[:limit], period: config[:period].seconds) do |req|
+              instance_exec(req, &config[:block]) if config[:block].respond_to?(:call)
+            end
+          end
+        end
+
+        # Configures blocklist rules
+        def configure_blocklist
+          return unless defined?(Rack::Attack)
+
+          # Block failed login attempts
+          Rack::Attack.blocklist("clavis/fail2ban") do |req|
+            Rack::Attack::Fail2Ban.filter("clavis-pentesters-#{req.ip}", maxretry: 5, findtime: 10.minutes,
+                                                                         bantime: 30.minutes) do
+              req.path =~ %r{/auth/\w+/callback} && req.env["rack.attack.match_data"]
+            end
+          end
+        end
+
+        # Configures Rack::Attack response
+        def configure_response
+          return unless defined?(Rack::Attack)
+
+          Rack::Attack.throttled_responder = lambda do |_req|
+            [
+              429, # status
+              { "Content-Type" => "application/json" }, # headers
+              [{ error: "Rate limit exceeded. Please retry later." }.to_json] # body
+            ]
+          end
+        end
+
+        # Installs Rack::Attack in the Rails application
+        # @param app [Rails::Application] The Rails application
+        def install(app)
+          return unless defined?(Rack::Attack)
+
+          # Skip if rate limiting is disabled
+          return unless Clavis.configuration.rate_limiting_enabled
+
+          # Add Rack::Attack as middleware if not already included
+          # Check if Rack::Attack is already in the middleware stack
+          rack_attack_included = false
+
+          if app.middleware.respond_to?(:each)
+            app.middleware.each do |middleware|
+              if middleware.klass == Rack::Attack
+                rack_attack_included = true
+                break
+              end
+            end
+          end
+
+          # Add Rack::Attack if not already included
+          app.middleware.use(Rack::Attack) unless rack_attack_included
+
+          configure(app)
+        end
+      end
+    end
+  end
+end

data/lib/clavis/security/redirect_uri_validator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Clavis
+  module Security
+    module RedirectUriValidator
+      class << self
+        # Validates a URI against the configured allowed hosts
+        # @param uri [String] The URI to validate
+        # @return [Boolean] Whether the URI is valid
+        def valid_uri?(uri)
+          return false if uri.nil? || uri.empty?
+
+          begin
+            parsed_uri = URI.parse(uri)
+
+            # Check if localhost is allowed in development
+            return allow_localhost_in_development? if localhost?(parsed_uri.host)
+
+            # Check against allowed hosts
+            return true if host_allowed?(parsed_uri.host)
+
+            false
+          rescue URI::InvalidURIError
+            false
+          end
+        end
+
+        # Validates a URI for a specific provider
+        # @param provider_name [Symbol] The provider name
+        # @param uri [String] The URI to validate
+        # @return [Boolean] Whether the URI is valid for the provider
+        def valid_provider_uri?(provider_name, uri)
+          return false if uri.nil? || uri.empty?
+
+          begin
+            # First check if the URI is valid against allowed hosts
+            return false unless valid_uri?(uri)
+
+            # Get the configured redirect URI for the provider
+            provider_config = Clavis.configuration.provider_config(provider_name)
+            configured_uri = provider_config[:redirect_uri]
+
+            return true if configured_uri.nil? # No specific URI configured
+
+            parsed_uri = URI.parse(uri)
+            parsed_configured_uri = URI.parse(configured_uri)
+
+            # Check if exact matching is required
+            return uri == configured_uri if Clavis.configuration.exact_redirect_uri_matching
+
+            # Check if the host and path match
+            parsed_uri.host == parsed_configured_uri.host &&
+              parsed_uri.path == parsed_configured_uri.path
+          rescue URI::InvalidURIError, Clavis::ProviderNotConfigured
+            false
+          end
+        end
+
+        # Validates a URI and raises an exception if invalid
+        # @param uri [String] The URI to validate
+        # @return [Boolean] Whether the URI is valid
+        # @raise [Clavis::InvalidRedirectUri] If the URI is invalid and raise_on_invalid_redirect is true
+        def validate_uri!(uri)
+          is_valid = valid_uri?(uri)
+
+          raise Clavis::InvalidRedirectUri, uri if !is_valid && Clavis.configuration.raise_on_invalid_redirect
+
+          is_valid
+        end
+
+        # Validates a URI for a specific provider and raises an exception if invalid
+        # @param provider_name [Symbol] The provider name
+        # @param uri [String] The URI to validate
+        # @return [Boolean] Whether the URI is valid for the provider
+        # @raise [Clavis::InvalidRedirectUri] If the URI is invalid and raise_on_invalid_redirect is true
+        def validate_provider_uri!(provider_name, uri)
+          is_valid = valid_provider_uri?(provider_name, uri)
+
+          raise Clavis::InvalidRedirectUri, uri if !is_valid && Clavis.configuration.raise_on_invalid_redirect
+
+          is_valid
+        end
+
+        private
+
+        # Checks if a host is localhost
+        # @param host [String] The host to check
+        # @return [Boolean] Whether the host is localhost
+        def localhost?(host)
+          ["localhost", "127.0.0.1"].include?(host)
+        end
+
+        # Checks if localhost is allowed in the current environment
+        # @return [Boolean] Whether localhost is allowed
+        def allow_localhost_in_development?
+          return false unless Clavis.configuration.allow_localhost_in_development
+
+          # If Rails is not defined, allow localhost in development mode
+          return true unless defined?(Rails)
+
+          # Allow localhost in development or test environments
+          Rails.env.development? || Rails.env.test?
+        end
+
+        # Checks if a host is in the allowed hosts list
+        # @param host [String] The host to check
+        # @return [Boolean] Whether the host is allowed
+        def host_allowed?(host)
+          return false if host.nil?
+
+          allowed_hosts = Clavis.configuration.allowed_redirect_hosts
+          return false if allowed_hosts.empty?
+
+          # Check if the host matches any allowed host or is a subdomain of an allowed host
+          allowed_hosts.any? do |allowed_host|
+            host == allowed_host || host.end_with?(".#{allowed_host}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clavis/security/session_manager.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Clavis
+  module Security
+    module SessionManager
+      class << self
+        # Store a value in the session with a namespaced key
+        # @param session [Hash] The session hash
+        # @param key [Symbol] The key to store the value under
+        # @param value [Object] The value to store
+        def store(session, key, value)
+          session[namespaced_key(key)] = value
+        end
+
+        # Retrieve a value from the session
+        # @param session [Hash] The session hash
+        # @param key [Symbol] The key to retrieve the value from
+        # @return [Object, nil] The value or nil if not found
+        def retrieve(session, key)
+          session[namespaced_key(key)]
+        end
+
+        # Delete a value from the session
+        # @param session [Hash] The session hash
+        # @param key [Symbol] The key to delete
+        # @return [Object, nil] The deleted value or nil if not found
+        def delete(session, key)
+          session.delete(namespaced_key(key))
+        end
+
+        # Generate a secure random state parameter and store it in the session
+        # @param session [Hash] The session hash
+        # @return [String] The generated state
+        def generate_and_store_state(session)
+          state = SecureRandom.hex(32)
+          store(session, :oauth_state, state)
+          state
+        end
+
+        # Check if a state parameter is valid
+        # @param session [Hash] The session hash
+        # @param state [String] The state parameter to validate
+        # @param clear_after_validation [Boolean] Whether to clear the state after validation
+        # @return [Boolean] Whether the state is valid
+        def valid_state?(session, state, clear_after_validation: false)
+          stored_state = retrieve(session, :oauth_state)
+
+          # Clear the state if requested
+          delete(session, :oauth_state) if clear_after_validation
+
+          # Validate the state
+          return false if stored_state.nil? || state.nil?
+
+          # Validate the state format if input validation is enabled
+          return false if Clavis.configuration.validate_inputs && !Clavis::Security::InputValidator.valid_state?(state)
+
+          stored_state == state
+        end
+
+        # Generate a secure random nonce and store it in the session
+        # @param session [Hash] The session hash
+        # @return [String] The generated nonce
+        def generate_and_store_nonce(session)
+          nonce = SecureRandom.hex(32)
+          store(session, :oauth_nonce, nonce)
+          nonce
+        end
+
+        # Check if a nonce is valid
+        # @param session [Hash] The session hash
+        # @param nonce [String] The nonce to validate
+        # @param clear_after_validation [Boolean] Whether to clear the nonce after validation
+        # @return [Boolean] Whether the nonce is valid
+        def valid_nonce?(session, nonce, clear_after_validation: false)
+          stored_nonce = retrieve(session, :oauth_nonce)
+
+          # Clear the nonce if requested
+          delete(session, :oauth_nonce) if clear_after_validation
+
+          # Validate the nonce
+          return false if stored_nonce.nil? || nonce.nil?
+
+          # Validate the nonce format if input validation is enabled
+          return false if Clavis.configuration.validate_inputs && !Clavis::Security::InputValidator.valid_state?(nonce)
+
+          stored_nonce == nonce
+        end
+
+        # Store a redirect URI in the session
+        # @param session [Hash] The session hash
+        # @param redirect_uri [String] The redirect URI to store
+        def store_redirect_uri(session, redirect_uri)
+          # Validate the redirect URI before storing
+          return unless redirect_uri && !redirect_uri.empty?
+
+          # Sanitize the redirect URI if input sanitization is enabled
+          redirect_uri = Clavis::Security::InputValidator.sanitize(redirect_uri) if Clavis.configuration.sanitize_inputs
+
+          Clavis::Security::RedirectUriValidator.validate_uri!(redirect_uri)
+          store(session, :oauth_redirect_uri, redirect_uri)
+        end
+
+        # Retrieve a redirect URI from the session
+        # @param session [Hash] The session hash
+        # @return [String, nil] The redirect URI or nil if not found
+        def retrieve_redirect_uri(session)
+          retrieve(session, :oauth_redirect_uri)
+        end
+
+        # Validate and retrieve a redirect URI from the session
+        # @param session [Hash] The session hash
+        # @param default [String] The default redirect URI to use if none is stored
+        # @return [String] The validated redirect URI or the default
+        def validate_and_retrieve_redirect_uri(session, default: "/")
+          redirect_uri = retrieve_redirect_uri(session)
+          delete(session, :oauth_redirect_uri)
+
+          if redirect_uri && !redirect_uri.empty?
+            # Sanitize the redirect URI if input sanitization is enabled
+            if Clavis.configuration.sanitize_inputs
+              redirect_uri = Clavis::Security::InputValidator.sanitize(redirect_uri)
+            end
+
+            # Validate the redirect URI
+            Clavis::Security::RedirectUriValidator.validate_uri!(redirect_uri)
+            redirect_uri
+          else
+            default
+          end
+        end
+
+        # Rotate the session ID after authentication
+        # @param session [Hash] The session hash
+        # @param new_session_id [String] The new session ID
+        # @param preserve_keys [Array<Symbol>] Keys to preserve during rotation
+        def rotate_session_id(session, new_session_id, preserve_keys: [])
+          # Skip rotation if disabled in configuration
+          return unless Clavis.configuration.rotate_session_after_login
+
+          # Store values to preserve
+          preserved_values = {}
+          preserve_keys.each do |key|
+            preserved_values[key] = session[key] if session.key?(key)
+          end
+
+          # Clear the session
+          session.clear
+
+          # Set the new session ID
+          session[:id] = new_session_id
+
+          # Restore preserved values
+          preserved_values.each do |key, value|
+            session[key] = value
+          end
+        end
+
+        # Rotate session to improve security after login
+        # @param request [ActionDispatch::Request] The current request
+        def rotate_session(request)
+          return unless Clavis.configuration.rotate_session_after_login
+          return unless request.respond_to?(:session)
+
+          if defined?(Rails) && Rails.version.to_f >= 6.0
+            # For Rails 6.0+, use the built-in reset_session functionality
+            # but preserve all session data
+            old_session_data = {}
+
+            # Copy all session data
+            request.session.each do |key, value|
+              old_session_data[key] = value
+            end
+
+            # Reset the session
+            request.env["rack.session.options"][:renew] = true
+            request.reset_session
+
+            # Restore session data
+            old_session_data.each do |key, value|
+              request.session[key] = value
+            end
+          else
+            # For older Rails versions or non-Rails apps, use our custom implementation
+            keys_to_preserve = request.session.respond_to?(:keys) ? request.session.keys.map(&:to_sym) : []
+            new_session_id = SecureRandom.hex(32)
+            rotate_session_id(request.session, new_session_id, preserve_keys: keys_to_preserve)
+          end
+        end
+
+        # Store authentication information in the session
+        # @param session [Hash] The session hash
+        # @param auth_hash [Hash] The authentication hash
+        def store_auth_info(session, auth_hash)
+          return unless auth_hash
+
+          # Store minimal information in the session
+          store(session, :provider, auth_hash[:provider])
+          store(session, :uid, auth_hash[:uid])
+
+          # Store email if available
+          store(session, :email, auth_hash.dig(:info, :email)) if auth_hash.dig(:info, :email)
+
+          # Store name if available
+          store(session, :name, auth_hash.dig(:info, :name)) if auth_hash.dig(:info, :name)
+        end
+
+        private
+
+        # Create a namespaced key for session storage
+        # @param key [Symbol] The key to namespace
+        # @return [Symbol] The namespaced key
+        def namespaced_key(key)
+          :"#{Clavis.configuration.session_key_prefix}_#{key}"
+        end
+      end
+    end
+  end
+end

data/lib/clavis/security/token_storage.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module Clavis
+  module Security
+    module TokenStorage
+      class << self
+        # Encrypts a token if encryption is enabled in configuration
+        # @param token [String, Hash] The token to encrypt
+        # @return [String, Hash] The encrypted token or the original token if encryption is disabled
+        def encrypt(token)
+          return token unless Clavis.configuration.encrypt_tokens
+          return token if token.nil?
+
+          key = Clavis.configuration.effective_encryption_key
+          return token if key.nil?
+
+          # Convert hash to JSON string if token is a hash
+          token_str = token.is_a?(Hash) ? JSON.generate(token) : token.to_s
+
+          cipher = OpenSSL::Cipher.new("AES-256-CBC")
+          cipher.encrypt
+          cipher.key = normalize_key(key)
+          iv = cipher.random_iv
+
+          encrypted = cipher.update(token_str) + cipher.final
+          Base64.strict_encode64("#{Base64.strict_encode64(iv)}--#{Base64.strict_encode64(encrypted)}")
+        end
+
+        # Decrypts a token if encryption is enabled in configuration
+        # @param encrypted_token [String] The encrypted token to decrypt
+        # @return [String, Hash] The decrypted token or the original token if encryption is disabled
+        def decrypt(encrypted_token)
+          return encrypted_token unless Clavis.configuration.encrypt_tokens
+          return encrypted_token if encrypted_token.nil?
+
+          key = Clavis.configuration.effective_encryption_key
+          return encrypted_token if key.nil?
+
+          begin
+            decoded = Base64.strict_decode64(encrypted_token)
+            iv_b64, data_b64 = decoded.split("--", 2)
+
+            iv = Base64.strict_decode64(iv_b64)
+            data = Base64.strict_decode64(data_b64)
+
+            decipher = OpenSSL::Cipher.new("AES-256-CBC")
+            decipher.decrypt
+            decipher.key = normalize_key(key)
+            decipher.iv = iv
+
+            decrypted = decipher.update(data) + decipher.final
+
+            # Try to parse as JSON in case it's a hash
+            begin
+              JSON.parse(decrypted, symbolize_names: true)
+            rescue JSON::ParserError
+              decrypted
+            end
+          rescue StandardError => e
+            Clavis.logger.error("Failed to decrypt token: #{e.message}")
+            encrypted_token
+          end
+        end
+
+        # Returns a serializer for use with ActiveRecord::Encryption
+        # This allows tokens to be automatically encrypted when stored in the database
+        # @return [Object] A serializer object with serialize and deserialize methods
+        def active_record_serializer
+          Serializer.new
+        end
+
+        private
+
+        # Ensures the encryption key is the correct length for AES-256
+        def normalize_key(key)
+          if key.bytesize < 32
+            # Pad the key if it's too short
+            key.ljust(32, "0")
+          elsif key.bytesize > 32
+            # Use a digest if the key is too long
+            Digest::SHA256.digest(key)
+          else
+            key
+          end
+        end
+      end
+
+      # Serializer class for ActiveRecord::Encryption
+      class Serializer
+        # Serialize and encrypt a token
+        # @param token [String, Hash] The token to serialize
+        # @return [String] The serialized and encrypted token
+        def dump(token)
+          TokenStorage.encrypt(token)
+        end
+
+        # Deserialize and decrypt a token
+        # @param encrypted_token [String] The encrypted token to deserialize
+        # @return [String, Hash] The deserialized and decrypted token
+        def load(encrypted_token)
+          TokenStorage.decrypt(encrypted_token)
+        end
+
+        # Alias methods for compatibility with different ActiveRecord versions
+        alias serialize dump
+        alias deserialize load
+      end
+    end
+  end
+end