rack_jwt_aegis 0.0.0

data/lib/rack_jwt_aegis/cache_adapter.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  class CacheAdapter
+    def self.build(store_type, options = {})
+      case store_type
+      when :memory
+        MemoryAdapter.new(options)
+      when :redis
+        RedisAdapter.new(options)
+      when :memcached
+        MemcachedAdapter.new(options)
+      when :solid_cache
+        SolidCacheAdapter.new(options)
+      else
+        raise ConfigurationError, "Unsupported cache store: #{store_type}"
+      end
+    end
+
+    def initialize(options = {})
+      @options = options
+    end
+
+    # Abstract methods - must be implemented by subclasses
+    def read(key)
+      raise NotImplementedError, 'Subclass must implement #read'
+    end
+
+    def write(key, value, expires_in: nil)
+      raise NotImplementedError, 'Subclass must implement #write'
+    end
+
+    def delete(key)
+      raise NotImplementedError, 'Subclass must implement #delete'
+    end
+
+    def exist?(key)
+      !read(key).nil?
+    end
+
+    def clear
+      raise NotImplementedError, 'Subclass must implement #clear'
+    end
+
+    # Helper methods
+    protected
+
+    def serialize_value(value)
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        value
+      else
+        JSON.generate(value)
+      end
+    end
+
+    def deserialize_value(value, _original_type = nil)
+      return value if value.nil?
+      return value unless value.is_a?(String)
+
+      # Try to parse as JSON, fallback to string
+      begin
+        JSON.parse(value)
+      rescue JSON::ParserError
+        value
+      end
+    end
+  end
+
+  # Memory-based cache adapter (for development/testing)
+  class MemoryAdapter < CacheAdapter
+    def initialize(options = {})
+      super
+      @store = {}
+      @expires = {}
+      @mutex = Mutex.new
+    end
+
+    def read(key)
+      @mutex.synchronize do
+        cleanup_expired
+        value = @store[key.to_s]
+        deserialize_value(value)
+      end
+    end
+
+    def write(key, value, expires_in: nil)
+      @mutex.synchronize do
+        key_str = key.to_s
+        @store[key_str] = serialize_value(value)
+
+        if expires_in
+          @expires[key_str] = Time.now + expires_in
+        else
+          @expires.delete(key_str)
+        end
+
+        true
+      end
+    end
+
+    def delete(key)
+      @mutex.synchronize do
+        key_str = key.to_s
+        @store.delete(key_str)
+        @expires.delete(key_str)
+        true
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        @store.clear
+        @expires.clear
+        true
+      end
+    end
+
+    private
+
+    def cleanup_expired
+      return unless @expires.any?
+
+      now = Time.now
+      expired_keys = @expires.select { |_, expiry| expiry < now }.keys
+
+      expired_keys.each do |key|
+        @store.delete(key)
+        @expires.delete(key)
+      end
+    end
+  end
+
+  # Redis cache adapter
+  class RedisAdapter < CacheAdapter
+    def initialize(options = {})
+      super
+      require 'redis' unless defined?(Redis)
+
+      @redis = options[:redis_instance] || Redis.new(options)
+    rescue LoadError
+      raise CacheError, "Redis gem not found. Add 'gem \"redis\"' to your Gemfile."
+    end
+
+    def read(key)
+      value = @redis.get(key.to_s)
+      deserialize_value(value)
+    rescue StandardError => e
+      raise CacheError, "Redis read error: #{e.message}"
+    end
+
+    def write(key, value, expires_in: nil)
+      key_str = key.to_s
+      serialized_value = serialize_value(value)
+
+      if expires_in
+        @redis.setex(key_str, expires_in.to_i, serialized_value)
+      else
+        @redis.set(key_str, serialized_value)
+      end
+
+      true
+    rescue StandardError => e
+      raise CacheError, "Redis write error: #{e.message}"
+    end
+
+    def delete(key)
+      @redis.del(key.to_s).positive?
+    rescue StandardError => e
+      raise CacheError, "Redis delete error: #{e.message}"
+    end
+
+    def clear
+      @redis.flushdb
+      true
+    rescue StandardError => e
+      raise CacheError, "Redis clear error: #{e.message}"
+    end
+  end
+
+  # Memcached cache adapter
+  class MemcachedAdapter < CacheAdapter
+    def initialize(options = {})
+      super
+      require 'dalli' unless defined?(Dalli)
+
+      @memcached = Dalli::Client.new(options[:servers] || 'localhost:11211', options)
+    rescue LoadError
+      raise CacheError, "Dalli gem not found. Add 'gem \"dalli\"' to your Gemfile."
+    end
+
+    def read(key)
+      value = @memcached.get(key.to_s)
+      deserialize_value(value)
+    rescue StandardError => e
+      raise CacheError, "Memcached read error: #{e.message}"
+    end
+
+    def write(key, value, expires_in: nil)
+      serialized_value = serialize_value(value)
+      @memcached.set(key.to_s, serialized_value, expires_in&.to_i)
+      true
+    rescue StandardError => e
+      raise CacheError, "Memcached write error: #{e.message}"
+    end
+
+    def delete(key)
+      @memcached.delete(key.to_s)
+      true
+    rescue StandardError => e
+      raise CacheError, "Memcached delete error: #{e.message}"
+    end
+
+    def clear
+      @memcached.flush
+      true
+    rescue StandardError => e
+      raise CacheError, "Memcached clear error: #{e.message}"
+    end
+  end
+
+  # Solid Cache adapter (Rails 8+)
+  class SolidCacheAdapter < CacheAdapter
+    def initialize(options = {})
+      super
+
+      # Solid Cache should be available in Rails environment
+      unless defined?(SolidCache)
+        raise CacheError, "SolidCache not available. Ensure you're using Rails 8+ with Solid Cache configured."
+      end
+
+      @cache = options[:cache_instance] || SolidCache
+    end
+
+    def read(key)
+      value = @cache.read(key.to_s)
+      deserialize_value(value)
+    rescue StandardError => e
+      raise CacheError, "SolidCache read error: #{e.message}"
+    end
+
+    def write(key, value, expires_in: nil)
+      serialized_value = serialize_value(value)
+      @cache.write(key.to_s, serialized_value, expires_in: expires_in)
+      true
+    rescue StandardError => e
+      raise CacheError, "SolidCache write error: #{e.message}"
+    end
+
+    def delete(key)
+      @cache.delete(key.to_s)
+      true
+    rescue StandardError => e
+      raise CacheError, "SolidCache delete error: #{e.message}"
+    end
+
+    def clear
+      @cache.clear
+      true
+    rescue StandardError => e
+      raise CacheError, "SolidCache clear error: #{e.message}"
+    end
+  end
+end

data/lib/rack_jwt_aegis/configuration.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  class Configuration
+    # Core JWT settings
+    attr_accessor :jwt_secret, :jwt_algorithm
+
+    # Feature toggles
+    attr_accessor :validate_subdomain, :validate_company_slug, :rbac_enabled
+
+    # Multi-tenant settings
+    attr_accessor :company_header_name, :company_slug_pattern, :payload_mapping
+
+    # Path management
+    attr_accessor :skip_paths
+
+    # Cache configuration
+    attr_accessor :cache_store, :cache_options, :cache_write_enabled
+    attr_accessor :rbac_cache_store, :rbac_cache_options, :permission_cache_store, :permission_cache_options
+
+    # Custom validators
+    attr_accessor :custom_payload_validator
+
+    # Response customization
+    attr_accessor :unauthorized_response, :forbidden_response
+
+    # Development settings
+    attr_accessor :debug_mode
+
+    def initialize(options = {})
+      # Set defaults
+      set_defaults
+
+      # Merge user options
+      options.each do |key, value|
+        raise ConfigurationError, "Unknown configuration option: #{key}" unless respond_to?("#{key}=")
+
+        public_send("#{key}=", value)
+      end
+
+      # Validate configuration
+      validate!
+    end
+
+    def rbac_enabled?
+      config_boolean(rbac_enabled)
+    end
+
+    def validate_subdomain?
+      config_boolean(validate_subdomain)
+    end
+
+    def validate_company_slug?
+      config_boolean(validate_company_slug)
+    end
+
+    def debug_mode?
+      config_boolean(debug_mode)
+    end
+
+    def cache_write_enabled?
+      config_boolean(cache_write_enabled)
+    end
+
+    # Check if path should be skipped
+    def skip_path?(path)
+      return false if skip_paths.nil? || skip_paths.empty?
+
+      skip_paths.any? do |skip_path|
+        case skip_path
+        when String
+          path == skip_path
+        when Regexp
+          skip_path.match?(path)
+        else
+          false
+        end
+      end
+    end
+
+    # Get mapped payload key
+    def payload_key(standard_key)
+      payload_mapping&.fetch(standard_key, standard_key) || standard_key
+    end
+
+    private
+
+    # Convert various falsy/truthy values to proper boolean for configuration
+    def config_boolean(value)
+      return false if value.nil?
+      return false if value == false
+      return false if value == 0
+      return false if value == ''
+      return false if value.is_a?(String) && value.downcase.strip == 'false'
+      
+      # Everything else is truthy
+      !!value
+    end
+
+    def set_defaults
+      @jwt_algorithm = 'HS256'
+      @validate_subdomain = false
+      @validate_company_slug = false
+      @rbac_enabled = false
+      @company_header_name = 'X-Company-Group-Id'
+      @company_slug_pattern = %r{^/api/v1/([^/]+)/}
+      @skip_paths = []
+      @cache_write_enabled = false
+      @debug_mode = false
+      @payload_mapping = {
+        user_id: :user_id,
+        company_group_id: :company_group_id,
+        company_group_domain: :company_group_domain,
+        company_slugs: :company_slugs,
+      }
+      @unauthorized_response = { error: 'Authentication required' }
+      @forbidden_response = { error: 'Access denied' }
+    end
+
+    def validate!
+      validate_jwt_settings!
+      validate_cache_settings!
+      validate_multi_tenant_settings!
+    end
+
+    def validate_jwt_settings!
+      raise ConfigurationError, 'jwt_secret is required' if jwt_secret.nil? || jwt_secret.empty?
+
+      valid_algorithms = ['HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512']
+      return if valid_algorithms.include?(jwt_algorithm)
+
+      raise ConfigurationError, "Unsupported JWT algorithm: #{jwt_algorithm}"
+    end
+
+    def validate_cache_settings!
+      return unless rbac_enabled?
+
+      # Validate cache store configuration
+      if cache_store && !cache_write_enabled?
+        # Zero trust mode - separate caches required
+        if rbac_cache_store.nil?
+          raise ConfigurationError, 'rbac_cache_store is required when cache_write_enabled is false'
+        end
+
+        if permission_cache_store.nil?
+          @permission_cache_store = :memory # Default fallback
+        end
+      elsif cache_store.nil? && rbac_cache_store.nil?
+        # Both cache stores are missing - at least one is required for RBAC
+        raise ConfigurationError, 'cache_store or rbac_cache_store is required when RBAC is enabled'
+      end
+
+      # Set default fallback for permission_cache_store when rbac_cache_store is provided
+      if !rbac_cache_store.nil? && permission_cache_store.nil?
+        @permission_cache_store = :memory # Default fallback
+      end
+    end
+
+    def validate_multi_tenant_settings!
+      if validate_company_slug? && company_slug_pattern.nil?
+        raise ConfigurationError, 'company_slug_pattern is required when validate_company_slug is true'
+      end
+
+      if validate_subdomain? && !payload_mapping.key?(:company_group_domain)
+        raise ConfigurationError, 'payload_mapping must include :company_group_domain when validate_subdomain is true'
+      end
+
+      return unless validate_company_slug? && !payload_mapping.key?(:company_slugs)
+
+      raise ConfigurationError, 'payload_mapping must include :company_slugs when validate_company_slug is true'
+    end
+  end
+end

data/lib/rack_jwt_aegis/jwt_validator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module RackJwtAegis
+  class JwtValidator
+    def initialize(config)
+      @config = config
+    end
+
+    def validate(token)
+      # Decode JWT with verification
+      payload, _header = JWT.decode(
+        token,
+        @config.jwt_secret,
+        true, # verify signature
+        {
+          algorithm: @config.jwt_algorithm,
+          verify_expiration: true,
+          verify_not_before: true,
+          verify_iat: true,
+          verify_aud: false, # Not validating audience by default
+          verify_iss: false, # Not validating issuer by default
+          verify_sub: false, # Not validating subject by default
+        },
+      )
+
+      # Validate payload structure
+      validate_payload_structure(payload)
+
+      payload
+    rescue JWT::ExpiredSignature
+      raise AuthenticationError, 'JWT token has expired'
+    rescue JWT::ImmatureSignature
+      raise AuthenticationError, 'JWT token not yet valid'
+    rescue JWT::InvalidIatError
+      raise AuthenticationError, 'JWT token issued in the future'
+    rescue JWT::DecodeError => e
+      raise AuthenticationError, "Invalid JWT token: #{e.message}"
+    rescue JWT::VerificationError
+      raise AuthenticationError, 'JWT signature verification failed'
+    rescue StandardError => e
+      raise AuthenticationError, "JWT validation error: #{e.message}"
+    end
+
+    private
+
+    def validate_payload_structure(payload)
+      # Ensure payload is a hash
+      raise AuthenticationError, 'Invalid JWT payload structure' unless payload.is_a?(Hash)
+
+      # Validate required claims based on enabled features
+      validate_required_claims(payload)
+
+      # Validate claim types
+      validate_claim_types(payload)
+    end
+
+    def validate_required_claims(payload)
+      required_claims = []
+
+      # Always require user identification
+      required_claims << @config.payload_key(:user_id)
+
+      # Multi-tenant validation requirements
+      if @config.validate_subdomain?
+        required_claims << @config.payload_key(:company_group_id)
+        required_claims << @config.payload_key(:company_group_domain)
+      end
+
+      required_claims << @config.payload_key(:company_slugs) if @config.validate_company_slug?
+
+      missing_claims = required_claims.select { |claim| payload[claim.to_s].nil? }
+
+      return if missing_claims.empty?
+
+      raise AuthenticationError, "JWT payload missing required claims: #{missing_claims.join(', ')}"
+    end
+
+    def validate_claim_types(payload)
+      user_id_key = @config.payload_key(:user_id).to_s
+
+      # User ID should be numeric or string
+      if payload[user_id_key] && !payload[user_id_key].is_a?(Numeric) && !payload[user_id_key].is_a?(String)
+        raise AuthenticationError, 'Invalid user_id format in JWT payload'
+      end
+
+      # Company group ID should be numeric or string (if present)
+      if @config.validate_subdomain?
+        company_group_id_key = @config.payload_key(:company_group_id).to_s
+        if payload[company_group_id_key] && !payload[company_group_id_key].is_a?(Numeric) && !payload[company_group_id_key].is_a?(String)
+          raise AuthenticationError, 'Invalid company_group_id format in JWT payload'
+        end
+      end
+
+      # Company group domain should be string (if present)
+      if @config.validate_subdomain?
+        company_domain_key = @config.payload_key(:company_group_domain).to_s
+        if payload[company_domain_key] && !payload[company_domain_key].is_a?(String)
+          raise AuthenticationError, 'Invalid company_group_domain format in JWT payload'
+        end
+      end
+
+      # Company slugs should be array (if present)
+      return unless @config.validate_company_slug?
+
+      company_slugs_key = @config.payload_key(:company_slugs).to_s
+      return unless payload[company_slugs_key] && !payload[company_slugs_key].is_a?(Array)
+
+      raise AuthenticationError, 'Invalid company_slugs format in JWT payload - must be array'
+    end
+  end
+end

data/lib/rack_jwt_aegis/middleware.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  class Middleware
+    def initialize(app, options = {})
+      @app = app
+      @config = Configuration.new(options)
+
+      # Initialize components
+      @jwt_validator = JwtValidator.new(@config)
+      @multi_tenant_validator = MultiTenantValidator.new(@config) if multi_tenant_enabled?
+      @rbac_manager = RbacManager.new(@config) if @config.rbac_enabled?
+      @response_builder = ResponseBuilder.new(@config)
+      @request_context = RequestContext.new(@config)
+
+      debug_log("Middleware initialized with features: #{enabled_features}")
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+      debug_log("Processing request: #{request.request_method} #{request.path}")
+
+      # Step 1: Check if path should be skipped
+      if @config.skip_path?(request.path)
+        debug_log("Skipping authentication for path: #{request.path}")
+        return @app.call(env)
+      end
+
+      begin
+        # Step 2: Extract and validate JWT token
+        token = extract_jwt_token(request)
+        payload = @jwt_validator.validate(token)
+
+        debug_log("JWT validation successful for user: #{payload[@config.payload_key(:user_id)]}")
+
+        # Step 3: Multi-tenant validation (if enabled)
+        if multi_tenant_enabled?
+          @multi_tenant_validator.validate(request, payload)
+          debug_log('Multi-tenant validation successful')
+        end
+
+        # Step 4: RBAC permission check (if enabled)
+        if @config.rbac_enabled?
+          @rbac_manager.authorize(request, payload)
+          debug_log('RBAC authorization successful')
+        end
+
+        # Step 5: Custom payload validation (if configured)
+        if @config.custom_payload_validator
+          unless @config.custom_payload_validator.call(payload, request)
+            debug_log('Custom payload validation failed')
+            raise AuthorizationError, 'Custom validation failed'
+          end
+          debug_log('Custom payload validation successful')
+        end
+
+        # Step 6: Set request context for application
+        @request_context.set_context(env, payload)
+        debug_log('Request context set successfully')
+
+        # Continue to application
+        @app.call(env)
+      rescue AuthenticationError => e
+        debug_log("Authentication failed: #{e.message}")
+        @response_builder.unauthorized_response(e.message)
+      rescue AuthorizationError => e
+        debug_log("Authorization failed: #{e.message}")
+        @response_builder.forbidden_response(e.message)
+      rescue StandardError => e
+        debug_log("Unexpected error: #{e.message}")
+        if @config.debug_mode?
+          @response_builder.error_response("Internal error: #{e.message}", 500)
+        else
+          @response_builder.error_response('Internal server error', 500)
+        end
+      end
+    end
+
+    private
+
+    def extract_jwt_token(request)
+      auth_header = request.get_header('HTTP_AUTHORIZATION')
+
+      raise AuthenticationError, 'Authorization header missing' if auth_header.nil? || auth_header.empty?
+
+      # Extract Bearer token
+      match = auth_header.match(/\ABearer\s+(.+)\z/)
+      raise AuthenticationError, 'Invalid authorization header format' if match.nil?
+
+      token = match[1]
+      raise AuthenticationError, 'JWT token missing' if token.nil? || token.empty?
+
+      token
+    end
+
+    def multi_tenant_enabled?
+      @config.validate_subdomain? || @config.validate_company_slug?
+    end
+
+    def enabled_features
+      features = ['JWT']
+      features << 'Subdomain' if @config.validate_subdomain?
+      features << 'CompanySlug' if @config.validate_company_slug?
+      features << 'RBAC' if @config.rbac_enabled?
+      features.join(', ')
+    end
+
+    def debug_log(message)
+      return unless @config.debug_mode?
+
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+      puts "[#{timestamp}] RackJwtAegis: #{message}"
+    end
+  end
+end