rack_jwt_aegis 0.0.0 → 1.0.1

data/lib/rack_jwt_aegis/rbac_manager.rb

@@ -1,15 +1,37 @@
 # frozen_string_literal: true
 
 module RackJwtAegis
+  # Role-Based Access Control (RBAC) manager
+  #
+  # Handles authorization by checking user permissions against cached RBAC data.
+  # Supports both simple boolean permissions and complex permission structures.
+  # Uses a two-tier caching system for performance optimization.
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 0.1.0
+  #
+  # @example Basic usage
+  #   config = Configuration.new(jwt_secret: 'secret', rbac_enabled: true, rbac_cache_store: :memory)
+  #   manager = RbacManager.new(config)
+  #   manager.authorize(request, jwt_payload)
   class RbacManager
+    include DebugLogger
+
     CACHE_TTL = 300 # 5 minutes default cache TTL
-    LAST_UPDATE_KEY = 'last-update'
 
+    # Initialize the RBAC manager
+    #
+    # @param config [Configuration] the configuration instance
     def initialize(config)
       @config = config
       setup_cache_adapters
     end
 
+    # Authorize a request against RBAC permissions
+    #
+    # @param request [Rack::Request] the incoming request
+    # @param payload [Hash] the JWT payload containing user information
+    # @raise [AuthorizationError] if user lacks sufficient permissions
     def authorize(request, payload)
       user_id = payload[@config.payload_key(:user_id).to_s]
       raise AuthorizationError, 'User ID missing from JWT payload' if user_id.nil?
@@ -61,137 +83,355 @@ module RackJwtAegis
     end
 
     def build_permission_key(user_id, request)
-      "#{user_id}:#{request.host}:#{request.path}:#{request.request_method}"
+      full_url = "#{request.host}#{request.path}"
+      "#{user_id}:#{full_url}:#{request.request_method.downcase}"
     end
 
     def check_cached_permission(permission_key)
       return nil unless @permission_cache
 
       begin
-        # Get cached permission entry
-        cached_entry = @permission_cache.read(permission_key)
-        return nil if cached_entry.nil?
+        # Get the user permissions cache using new format
+        user_permissions = @permission_cache.read('user_permissions')
+        return nil if user_permissions.nil? || !user_permissions.is_a?(Hash)
+
+        # First check: If RBAC permissions were updated recently, nuke ALL cached permissions
+        rbac_last_update = rbac_last_update_timestamp
+        if rbac_last_update
+          current_time = Time.now.to_i
+          rbac_update_age = current_time - rbac_last_update
+
+          # If RBAC was updated within the TTL period, all cached permissions are invalid
+          if rbac_update_age <= @config.user_permissions_ttl
+            nuke_user_permissions_cache("RBAC permissions updated recently (#{rbac_update_age}s ago, within TTL)")
+            return nil
+          end
+        end
 
-        # Check if cached entry is still valid based on last-update timestamp
-        if cached_entry.is_a?(Hash) && cached_entry['timestamp'] && cached_entry['permission']
-          last_update_time = last_update_timestamp
+        # Check if permission exists in new format: {"user_id:full_url:method" => timestamp}
+        cached_timestamp = user_permissions[permission_key]
+        return nil unless cached_timestamp.is_a?(Integer)
 
-          return cached_entry['permission'] if last_update_time && cached_entry['timestamp'] >= last_update_time
+        current_time = Time.now.to_i
+        permission_age = current_time - cached_timestamp
 
-          # Cached entry is stale, remove it
-          @permission_cache.delete(permission_key)
+        # Second check: TTL expiration
+        if permission_age > @config.user_permissions_ttl
+          # This specific permission expired due to TTL
+          remove_stale_permission(permission_key,
+                                  "TTL expired (#{permission_age}s > #{@config.user_permissions_ttl}s)")
           return nil
-
         end
 
-        # Invalid cached entry format
-        @permission_cache.delete(permission_key)
-        nil
+        # Permission is fresh
+        debug_log("Cache hit: #{permission_key} (permission age: \
+                  #{permission_age}s, RBAC age: #{rbac_update_age || 'unknown'}s)".squeeze)
+        true
       rescue CacheError => e
         # Log cache error but don't fail the request
-        warn "RbacManager cache read error: #{e.message}" if @config.debug_mode?
+        debug_log("RbacManager cache read error: #{e.message}", :warn)
         nil
       end
     end
 
     def check_rbac_permission(user_id, request)
-      # Build RBAC lookup key
-      rbac_key = build_rbac_key(user_id, request.host, request.path, request.request_method)
-
-      # Check RBAC cache store for permission
-      permission_data = @rbac_cache.read(rbac_key)
+      rbac_data = @rbac_cache.read('permissions')
 
-      if permission_data.nil?
-        # No explicit permission found - default to deny
-        false
-      else
-        # Permission data found - check if it grants access
-        case permission_data
-        when true, 'true', 1, '1'
-          true
-        when false, 'false', 0, '0'
-          false
-        else
-          # Complex permission data - delegate to custom logic if available
-          evaluate_complex_permission?(permission_data, user_id, request)
-        end
+      # Check if RBAC data exists and is valid
+      if rbac_data.is_a?(Hash) && validate_rbac_cache_format(rbac_data)
+        return check_rbac_format?(user_id, request, rbac_data)
       end
+
+      # No valid RBAC data found
+      false
     rescue CacheError => e
       # Cache error - fail secure (deny access)
-      warn "RbacManager RBAC cache error: #{e.message}" if @config.debug_mode?
+      debug_log("RbacManager RBAC cache error: #{e.message}", :warn)
       false
     end
 
     def cache_permission_result(permission_key, has_permission)
       return unless @permission_cache
+      return unless has_permission # Only cache positive permissions
 
       begin
         current_time = Time.now.to_i
-        cache_entry = {
-          'permission' => has_permission,
-          'timestamp' => current_time,
-        }
 
-        @permission_cache.write(permission_key, cache_entry, expires_in: CACHE_TTL)
+        # Get existing user permissions cache or create new one
+        user_permissions = @permission_cache.read('user_permissions') || {}
+
+        # Store permission with new format: {"user_id:full_url:method" => timestamp}
+        user_permissions[permission_key] = current_time
+
+        # Write back to cache
+        @permission_cache.write('user_permissions', user_permissions, expires_in: CACHE_TTL)
+
+        debug_log("Cached permission: #{permission_key} => #{current_time}")
       rescue CacheError => e
         # Log cache error but don't fail the request
-        warn "RbacManager permission cache write error: #{e.message}" if @config.debug_mode?
+        debug_log("RbacManager permission cache write error: #{e.message}", :warn)
       end
     end
 
-    def last_update_timestamp
-      @rbac_cache.read(LAST_UPDATE_KEY)
-    rescue CacheError => e
-      warn "RbacManager last-update read error: #{e.message}" if @config.debug_mode?
-      nil
-    end
+    def check_rbac_format?(user_id, request, rbac_data)
+      # Extract user roles from JWT payload
+      user_roles = extract_user_roles_from_request(request)
+      if user_roles.nil? || user_roles.empty?
+        debug_log('RbacManager: No user roles found in request context', :warn)
+        return false
+      end
+
+      # Check permissions for each user role
+      rbac_data['permissions'].each do |role_permissions|
+        user_roles.each do |role_id|
+          next unless role_permissions.key?(role_id.to_s) || role_permissions.key?(role_id.to_i)
+
+          permissions = role_permissions[role_id.to_s] || role_permissions[role_id.to_i]
+          matched_permission = find_matching_permission(permissions, request)
+
+          next unless matched_permission
+
+          # Cache this specific permission match for faster future lookups
+          if @permission_cache && @config.cache_write_enabled?
+            cache_permission_match(user_id, request, role_id, matched_permission)
+          end
+          return true
+        end
+      end
 
-    def build_rbac_key(user_id, host, path, method)
-      # Standard RBAC key format as defined in architecture
-      "#{user_id}:#{host}:#{path}:#{method}"
+      false
     end
 
-    def evaluate_complex_permission?(permission_data, user_id, request)
-      # Handle complex permission data structures
-      case permission_data
-      when Hash
-        # Permission data is a hash - could contain role-based rules
-        evaluate_hash_permission?(permission_data, user_id, request)
-      when Array
-        # Permission data is an array - could be list of allowed actions
-        evaluate_array_permission?(permission_data, request.request_method)
-      else
-        # Unknown format - default to deny
-        false
+    # Get RBAC permissions collection last_update timestamp
+    def rbac_last_update_timestamp
+      return nil unless @rbac_cache
+
+      begin
+        rbac_data = @rbac_cache.read('permissions')
+        if rbac_data.is_a?(Hash) && (rbac_data['last_update'] || rbac_data[:last_update])
+          return rbac_data['last_update'] || rbac_data[:last_update]
+        end
+
+        nil
+      rescue CacheError => e
+        debug_log("RbacManager RBAC last-update read error: #{e.message}", :warn)
+        nil
       end
     end
 
-    def evaluate_hash_permission?(permission_hash, _user_id, request)
-      # Example: {"allowed_methods": ["GET", "POST"], "roles": ["admin"]}
+    # Remove a specific stale permission
+    def remove_stale_permission(permission_key, reason)
+      return unless @permission_cache
+
+      begin
+        user_permissions = @permission_cache.read('user_permissions')
+        return unless user_permissions.is_a?(Hash)
+
+        # Remove the specific permission key
+        user_permissions.delete(permission_key)
 
-      # Check allowed methods
-      if permission_hash['allowed_methods']
-        allowed_methods = Array(permission_hash['allowed_methods'])
-        return allowed_methods.include?(request.request_method)
+        # If no permissions remain, remove the entire cache
+        if user_permissions.empty?
+          @permission_cache.delete('user_permissions')
+          debug_log("Removed last permission, cleared entire cache: #{reason}")
+        else
+          # Update the cache with the modified permissions
+          @permission_cache.write('user_permissions', user_permissions, expires_in: CACHE_TTL)
+          debug_log("Removed stale permission #{permission_key}: #{reason}")
+        end
+      rescue CacheError => e
+        debug_log("RbacManager stale permission removal error: #{e.message}", :warn)
       end
+    end
+
+    # Nuke (delete) the entire user permissions cache
+    def nuke_user_permissions_cache(reason)
+      return unless @permission_cache
 
-      # Check roles (would need role information from JWT payload)
-      if permission_hash['roles']
-        # This would require additional JWT payload inspection
-        # For now, default to allowing if roles are specified
-        return true
+      begin
+        @permission_cache.delete('user_permissions')
+        debug_log("Nuked user permissions cache: #{reason}")
+      rescue CacheError => e
+        debug_log("RbacManager cache nuke error: #{e.message}", :warn)
       end
+    end
+
+    # Extract user roles from request context (stored by middleware)
+    def extract_user_roles_from_request(request)
+      # Check if roles are stored in request environment by middleware
+      request.env['rack_jwt_aegis.user_roles']
+    end
 
-      # Check boolean permission field
-      return !!permission_hash['allowed'] if permission_hash.key?('allowed')
+    # Check if any role permission matches the request
+    def check_role_permissions?(permissions, request)
+      return false unless permissions.is_a?(Array)
+
+      request_path = extract_api_path_from_request(request)
+      request_method = request.request_method.downcase
+
+      permissions.each do |permission|
+        return true if permission_matches?(permission, request_path, request_method)
+      end
 
-      # Default deny for unknown hash structure
       false
     end
 
-    def evaluate_array_permission?(permission_array, request_method)
-      # Array of allowed HTTP methods
-      permission_array.include?(request_method)
+    # Find the first matching permission for the request (returns the permission string or nil)
+    def find_matching_permission(permissions, request)
+      return nil unless permissions.is_a?(Array)
+
+      request_path = extract_api_path_from_request(request)
+      request_method = request.request_method.downcase
+
+      permissions.each do |permission|
+        return permission if permission_matches?(permission, request_path, request_method)
+      end
+
+      nil
+    end
+
+    # Cache the specific permission match for faster future lookups
+    # Format: {"user_id:full_url:method" => timestamp}
+    def cache_permission_match(user_id, request, _role_id, _matched_permission)
+      return unless @permission_cache
+
+      begin
+        current_time = Time.now.to_i
+
+        # Build the permission key in new format
+        host = request.host || 'localhost'
+        full_url = "#{host}#{request.path}"
+        method = request.request_method.downcase
+        permission_key = "#{user_id}:#{full_url}:#{method}"
+
+        # Get existing user permissions cache or create new one
+        user_permissions = @permission_cache.read('user_permissions') || {}
+
+        # Store permission with new format
+        user_permissions[permission_key] = current_time
+
+        # Write back to cache
+        @permission_cache.write('user_permissions', user_permissions, expires_in: CACHE_TTL)
+
+        debug_log("Cached user permission: #{permission_key} => #{current_time}")
+      rescue CacheError => e
+        # Log cache error but don't fail the request
+        debug_log("RbacManager permission cache write error: #{e.message}", :warn)
+      end
+    end
+
+    # Extract the API path portion from the full request path
+    # Removes subdomain and pathname slug parts to get the resource endpoint
+    def extract_api_path_from_request(request)
+      path = request.path
+
+      # Remove API prefix and pathname slug pattern if configured
+      if @config.pathname_slug_pattern
+        # Extract the resource path after the pathname slug
+        match = path.match(@config.pathname_slug_pattern)
+        if match&.captures&.any?
+          # Get everything after the slug pattern
+          slug_part = match[0]
+          resource_path = path.sub(slug_part, '')
+          return resource_path.start_with?('/') ? resource_path[1..] : resource_path
+        end
+      end
+
+      # Fallback: remove common API prefixes
+      path = path.sub(%r{^/api/v\d+/}, '')
+      path = path.sub(%r{^/api/}, '')
+      path.sub(%r{^/}, '')
+    end
+
+    # Check if a permission string matches the request
+    def permission_matches?(permission, resource_path, request_method)
+      return false unless permission.is_a?(String)
+
+      # Parse permission format: "resource-endpoint:http-method"
+      parts = permission.split(':')
+      return false unless parts.length == 2
+
+      permission_path, permission_method = parts
+
+      # Check if method matches
+      return false unless method_matches?(permission_method, request_method)
+
+      # Check if path matches (handle both literal and regex patterns)
+      path_matches?(permission_path, resource_path)
+    end
+
+    # Check if HTTP method matches
+    def method_matches?(permission_method, request_method)
+      permission_method = permission_method.downcase
+
+      # Wildcard method matches all
+      return true if permission_method == '*'
+
+      # Exact method match
+      permission_method == request_method
+    end
+
+    # Check if path matches (handles both literal strings and regex patterns)
+    def path_matches?(permission_path, resource_path)
+      # Handle regex pattern format: "%r{pattern}"
+      if permission_path.start_with?('%r{') && permission_path.end_with?('}')
+        regex_pattern = permission_path[3..-2] # Remove %r{ and }
+        begin
+          regex = Regexp.new(regex_pattern)
+          return regex.match?(resource_path)
+        rescue RegexpError => e
+          debug_log("RbacManager: Invalid regex pattern '#{regex_pattern}': #{e.message}", :warn)
+          return false
+        end
+      end
+
+      # Exact string match
+      permission_path == resource_path
+    end
+
+    # Validate RBAC cache format according to specification
+    # Expected format:
+    # {
+    #   last_update: timestamp,
+    #   permissions: [
+    #     {role-id: ["{resource-endpoint}:{http-method}"]}
+    #   ]
+    # }
+    def validate_rbac_cache_format(rbac_data)
+      return false unless rbac_data.is_a?(Hash)
+
+      # Check required fields
+      return false unless rbac_data.key?('last_update') || rbac_data.key?(:last_update)
+      return false unless rbac_data.key?('permissions') || rbac_data.key?(:permissions)
+
+      # Get permissions array
+      permissions = rbac_data['permissions'] || rbac_data[:permissions]
+      return false unless permissions.is_a?(Array)
+
+      # Validate each permission entry
+      permissions.each do |permission_entry|
+        return false unless permission_entry.is_a?(Hash)
+
+        # Each entry should have at least one role-id key
+        return false if permission_entry.empty?
+
+        # Validate permission values are arrays of strings
+        permission_entry.each_value do |role_permissions|
+          return false unless role_permissions.is_a?(Array)
+
+          # Each permission should be a string in format "endpoint:method"
+          role_permissions.each do |permission|
+            return false unless permission.is_a?(String)
+            # Permission must include ':' (resource:method format)
+            return false unless permission.include?(':')
+          end
+        end
+      end
+
+      true
+    rescue StandardError => e
+      debug_log("RbacManager: Cache format validation error: #{e.message}", :warn)
+      false
     end
   end
 end

data/lib/rack_jwt_aegis/request_context.rb

@@ -1,19 +1,43 @@
 # frozen_string_literal: true
 
 module RackJwtAegis
+  # Request context manager for storing JWT authentication data in Rack env
+  #
+  # Stores authenticated user and tenant information in the Rack environment
+  # hash for easy access by downstream application code. Provides both
+  # instance methods for setting context and class methods for reading.
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 0.1.0
+  #
+  # @example Setting context (done by middleware)
+  #   context = RequestContext.new(config)
+  #   context.set_context(env, jwt_payload)
+  #
+  # @example Reading context in application
+  #   user_id = RequestContext.user_id(request.env)
+  #   tenant_id = RequestContext.tenant_id(request.env)
+  #   authenticated = RequestContext.authenticated?(request.env)
   class RequestContext
     # Standard environment keys for JWT data
     JWT_PAYLOAD_KEY = 'rack_jwt_aegis.payload'
     USER_ID_KEY = 'rack_jwt_aegis.user_id'
-    COMPANY_GROUP_ID_KEY = 'rack_jwt_aegis.company_group_id'
-    COMPANY_GROUP_DOMAIN_KEY = 'rack_jwt_aegis.company_group_domain'
-    COMPANY_SLUGS_KEY = 'rack_jwt_aegis.company_slugs'
+    TENANT_ID_KEY = 'rack_jwt_aegis.tenant_id'
+    SUBDOMAIN_KEY = 'rack_jwt_aegis.subdomain'
+    PATHNAME_SLUGS_KEY = 'rack_jwt_aegis.pathname_slugs'
     AUTHENTICATED_KEY = 'rack_jwt_aegis.authenticated'
 
+    # Initialize the request context manager
+    #
+    # @param config [Configuration] the configuration instance
     def initialize(config)
       @config = config
     end
 
+    # Set JWT authentication context in the Rack environment
+    #
+    # @param env [Hash] the Rack environment hash
+    # @param payload [Hash] the validated JWT payload
     def set_context(env, payload)
       # Set the full payload
       env[JWT_PAYLOAD_KEY] = payload
@@ -27,40 +51,57 @@ module RackJwtAegis
     end
 
     # Class methods for easy access from application code
+
+    # Check if the request is authenticated
+    #
+    # @param env [Hash] the Rack environment hash
+    # @return [Boolean] true if request is authenticated
     def self.authenticated?(env)
       !!env[AUTHENTICATED_KEY]
     end
 
+    # Get the full JWT payload from the request
+    #
+    # @param env [Hash] the Rack environment hash
+    # @return [Hash, nil] the JWT payload or nil if not authenticated
     def self.payload(env)
       env[JWT_PAYLOAD_KEY]
     end
 
+    # Get the authenticated user ID
+    #
+    # @param env [Hash] the Rack environment hash
+    # @return [String, Integer, nil] the user ID or nil if not available
     def self.user_id(env)
       env[USER_ID_KEY]
     end
 
-    def self.company_group_id(env)
-      env[COMPANY_GROUP_ID_KEY]
+    # Get the tenant ID
+    #
+    # @param env [Hash] the Rack environment hash
+    # @return [String, Integer, nil] the tenant ID or nil if not available
+    def self.tenant_id(env)
+      env[TENANT_ID_KEY]
     end
 
-    def self.company_group_domain(env)
-      env[COMPANY_GROUP_DOMAIN_KEY]
+    def self.subdomain(env)
+      env[SUBDOMAIN_KEY]
     end
 
-    def self.company_slugs(env)
-      env[COMPANY_SLUGS_KEY] || []
+    def self.pathname_slugs(env)
+      env[PATHNAME_SLUGS_KEY] || []
     end
 
     def self.current_user_id(request)
       user_id(request.env)
     end
 
-    def self.current_company_group_id(request)
-      company_group_id(request.env)
+    def self.current_tenant_id(request)
+      tenant_id(request.env)
     end
 
     def self.has_company_access?(env, company_slug)
-      company_slugs(env).include?(company_slug)
+      pathname_slugs(env).include?(company_slug)
     end
 
     private
@@ -74,27 +115,27 @@ module RackJwtAegis
 
     def set_tenant_context(env, payload)
       # Set company group information
-      if @config.validate_subdomain? || @config.payload_mapping.key?(:company_group_id)
-        company_group_id_key = @config.payload_key(:company_group_id).to_s
-        company_group_id = payload[company_group_id_key]
-        env[COMPANY_GROUP_ID_KEY] = company_group_id
+      if @config.validate_subdomain? || @config.payload_mapping.key?(:tenant_id)
+        tenant_id_key = @config.payload_key(:tenant_id).to_s
+        tenant_id = payload[tenant_id_key]
+        env[TENANT_ID_KEY] = tenant_id
       end
 
       if @config.validate_subdomain?
-        company_domain_key = @config.payload_key(:company_group_domain).to_s
+        company_domain_key = @config.payload_key(:subdomain).to_s
         company_domain = payload[company_domain_key]
-        env[COMPANY_GROUP_DOMAIN_KEY] = company_domain
+        env[SUBDOMAIN_KEY] = company_domain
       end
 
       # Set company slugs for sub-level tenant access
-      return unless @config.validate_company_slug? || @config.payload_mapping.key?(:company_slugs)
+      return unless @config.validate_pathname_slug? || @config.payload_mapping.key?(:pathname_slugs)
 
-      company_slugs_key = @config.payload_key(:company_slugs).to_s
-      company_slugs = payload[company_slugs_key]
+      pathname_slugs_key = @config.payload_key(:pathname_slugs).to_s
+      pathname_slugs = payload[pathname_slugs_key]
 
       # Ensure it's an array
-      company_slugs = Array(company_slugs) if company_slugs
-      env[COMPANY_SLUGS_KEY] = company_slugs || []
+      pathname_slugs = Array(pathname_slugs) if pathname_slugs
+      env[PATHNAME_SLUGS_KEY] = pathname_slugs || []
     end
   end
 end

data/lib/rack_jwt_aegis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RackJwtAegis
-  VERSION = '0.0.0'
+  VERSION = '1.0.1'
 end