rack_jwt_aegis 0.0.0 → 1.0.0

data/lib/rack_jwt_aegis/jwt_validator.rb

@@ -3,11 +3,41 @@
 require 'jwt'
 
 module RackJwtAegis
+  # JWT token validation and payload verification
+  #
+  # Handles JWT token decoding, signature verification, and payload validation
+  # including claims verification and type checking based on configuration.
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 0.1.0
+  #
+  # @example Basic usage
+  #   config = Configuration.new(jwt_secret: 'your-secret')
+  #   validator = JwtValidator.new(config)
+  #   payload = validator.validate(jwt_token)
+  #
+  # @example With multi-tenant validation
+  #   config = Configuration.new(
+  #     jwt_secret: 'your-secret',
+  #     validate_subdomain: true,
+  #     validate_pathname_slug: true
+  #   )
+  #   validator = JwtValidator.new(config)
+  #   payload = validator.validate(jwt_token) # Will validate tenant claims
   class JwtValidator
+    # Initialize the JWT validator
+    #
+    # @param config [Configuration] the configuration instance
     def initialize(config)
       @config = config
     end
 
+    # Validate and decode a JWT token
+    #
+    # @param token [String] the JWT token to validate
+    # @return [Hash] the decoded JWT payload
+    # @raise [AuthenticationError] if token is invalid, expired, or malformed
+    # @raise [AuthenticationError] if required claims are missing or invalid
     def validate(token)
       # Decode JWT with verification
       payload, _header = JWT.decode(
@@ -35,16 +65,20 @@ module RackJwtAegis
       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 JWT::DecodeError => e
+      raise AuthenticationError, "Invalid JWT token: #{e.message}"
     rescue StandardError => e
       raise AuthenticationError, "JWT validation error: #{e.message}"
     end
 
     private
 
+    # Validate the structure and content of the JWT payload
+    #
+    # @param payload [Object] the decoded payload from JWT
+    # @raise [AuthenticationError] if payload structure is invalid
     def validate_payload_structure(payload)
       # Ensure payload is a hash
       raise AuthenticationError, 'Invalid JWT payload structure' unless payload.is_a?(Hash)
@@ -56,6 +90,10 @@ module RackJwtAegis
       validate_claim_types(payload)
     end
 
+    # Validate that all required claims are present in the payload
+    #
+    # @param payload [Hash] the JWT payload to validate
+    # @raise [AuthenticationError] if required claims are missing
     def validate_required_claims(payload)
       required_claims = []
 
@@ -64,11 +102,11 @@ module RackJwtAegis
 
       # Multi-tenant validation requirements
       if @config.validate_subdomain?
-        required_claims << @config.payload_key(:company_group_id)
-        required_claims << @config.payload_key(:company_group_domain)
+        required_claims << @config.payload_key(:tenant_id)
+        required_claims << @config.payload_key(:subdomain)
       end
 
-      required_claims << @config.payload_key(:company_slugs) if @config.validate_company_slug?
+      required_claims << @config.payload_key(:pathname_slugs) if @config.validate_pathname_slug?
 
       missing_claims = required_claims.select { |claim| payload[claim.to_s].nil? }
 
@@ -77,6 +115,10 @@ module RackJwtAegis
       raise AuthenticationError, "JWT payload missing required claims: #{missing_claims.join(', ')}"
     end
 
+    # Validate the data types of specific claims in the payload
+    #
+    # @param payload [Hash] the JWT payload to validate
+    # @raise [AuthenticationError] if claim types are invalid
     def validate_claim_types(payload)
       user_id_key = @config.payload_key(:user_id).to_s
 
@@ -87,27 +129,27 @@ module RackJwtAegis
 
       # 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'
+        tenant_id_key = @config.payload_key(:tenant_id).to_s
+        if payload[tenant_id_key] && !payload[tenant_id_key].is_a?(Numeric) && !payload[tenant_id_key].is_a?(String)
+          raise AuthenticationError, 'Invalid tenant_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
+        company_domain_key = @config.payload_key(:subdomain).to_s
         if payload[company_domain_key] && !payload[company_domain_key].is_a?(String)
-          raise AuthenticationError, 'Invalid company_group_domain format in JWT payload'
+          raise AuthenticationError, 'Invalid subdomain format in JWT payload'
         end
       end
 
       # Company slugs should be array (if present)
-      return unless @config.validate_company_slug?
+      return unless @config.validate_pathname_slug?
 
-      company_slugs_key = @config.payload_key(:company_slugs).to_s
-      return unless payload[company_slugs_key] && !payload[company_slugs_key].is_a?(Array)
+      pathname_slugs_key = @config.payload_key(:pathname_slugs).to_s
+      return unless payload[pathname_slugs_key] && !payload[pathname_slugs_key].is_a?(Array)
 
-      raise AuthenticationError, 'Invalid company_slugs format in JWT payload - must be array'
+      raise AuthenticationError, 'Invalid pathname_slugs format in JWT payload - must be array'
     end
   end
 end

data/lib/rack_jwt_aegis/middleware.rb

@@ -1,7 +1,34 @@
 # frozen_string_literal: true
 
 module RackJwtAegis
+  # Main Rack middleware for JWT authentication and authorization
+  #
+  # This middleware handles the complete JWT authentication flow including:
+  # - JWT token extraction and validation
+  # - Multi-tenant validation (subdomain/pathname slug)
+  # - RBAC permission checking
+  # - Custom payload validation
+  # - Request context setting
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 0.1.0
+  #
+  # @example Basic usage
+  #   use RackJwtAegis::Middleware, jwt_secret: ENV['JWT_SECRET']
+  #
+  # @example Advanced usage
+  #   use RackJwtAegis::Middleware, {
+  #     jwt_secret: ENV['JWT_SECRET'],
+  #     validate_subdomain: true,
+  #     rbac_enabled: true,
+  #     cache_store: :redis,
+  #     skip_paths: ['/health', '/api/public/*']
+  #   }
   class Middleware
+    # Initialize the middleware
+    #
+    # @param app [#call] the Rack application
+    # @param options [Hash] configuration options (see Configuration#initialize)
     def initialize(app, options = {})
       @app = app
       @config = Configuration.new(options)
@@ -16,6 +43,12 @@ module RackJwtAegis
       debug_log("Middleware initialized with features: #{enabled_features}")
     end
 
+    # Process the Rack request
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Array] Rack response array [status, headers, body]
+    # @raise [AuthenticationError] if JWT authentication fails
+    # @raise [AuthorizationError] if authorization checks fail
     def call(env)
       request = Rack::Request.new(env)
 
@@ -42,6 +75,10 @@ module RackJwtAegis
 
         # Step 4: RBAC permission check (if enabled)
         if @config.rbac_enabled?
+          # Extract and store user roles in request environment for RBAC manager
+          user_roles = extract_user_roles(payload)
+          request.env['rack_jwt_aegis.user_roles'] = user_roles
+
           @rbac_manager.authorize(request, payload)
           debug_log('RBAC authorization successful')
         end
@@ -79,6 +116,11 @@ module RackJwtAegis
 
     private
 
+    # Extract JWT token from the Authorization header
+    #
+    # @param request [Rack::Request] the Rack request object
+    # @return [String] the extracted JWT token
+    # @raise [AuthenticationError] if authorization header is missing or invalid
     def extract_jwt_token(request)
       auth_header = request.get_header('HTTP_AUTHORIZATION')
 
@@ -94,18 +136,46 @@ module RackJwtAegis
       token
     end
 
+    # Check if multi-tenant validation is enabled
+    #
+    # @return [Boolean] true if subdomain or pathname slug validation is enabled
     def multi_tenant_enabled?
-      @config.validate_subdomain? || @config.validate_company_slug?
+      @config.validate_subdomain? || @config.validate_pathname_slug?
     end
 
+    # Generate a string describing enabled features for logging
+    #
+    # @return [String] comma-separated list of enabled features
     def enabled_features
       features = ['JWT']
       features << 'Subdomain' if @config.validate_subdomain?
-      features << 'CompanySlug' if @config.validate_company_slug?
+      features << 'CompanySlug' if @config.validate_pathname_slug?
       features << 'RBAC' if @config.rbac_enabled?
       features.join(', ')
     end
 
+    # Extract user roles from JWT payload for RBAC authorization
+    #
+    # @param payload [Hash] the JWT payload
+    # @return [Array] array of user role IDs
+    def extract_user_roles(payload)
+      # Try multiple common role field names
+      roles = payload['roles'] || payload['role'] || payload['user_roles'] || payload['role_ids']
+
+      case roles
+      when Array
+        roles.map(&:to_s) # Ensure all roles are strings for consistent lookup
+      when String, Integer
+        [roles.to_s] # Single role as array
+      else
+        debug_log("Warning: No valid roles found in JWT payload. Available fields: #{payload.keys}")
+        []
+      end
+    end
+
+    # Log debug message if debug mode is enabled
+    #
+    # @param message [String] the message to log
     def debug_log(message)
       return unless @config.debug_mode?
 

data/lib/rack_jwt_aegis/multi_tenant_validator.rb

@@ -1,15 +1,41 @@
 # frozen_string_literal: true
 
 module RackJwtAegis
+  # Multi-tenant validation for subdomain and pathname slug access control
+  #
+  # Validates that users can only access resources within their permitted
+  # tenant boundaries. Supports two levels of tenant validation:
+  # 1. Subdomain-based (Level 1) - Company-Group level isolation
+  # 2. Pathname slug-based (Level 2) - Company level isolation within groups
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 0.1.0
+  #
+  # @example Usage
+  #   config = Configuration.new(
+  #     jwt_secret: 'secret',
+  #     validate_subdomain: true,
+  #     validate_pathname_slug: true
+  #   )
+  #   validator = MultiTenantValidator.new(config)
+  #   validator.validate(request, jwt_payload)
   class MultiTenantValidator
+    # Initialize the multi-tenant validator
+    #
+    # @param config [Configuration] the configuration instance
     def initialize(config)
       @config = config
     end
 
+    # Validate multi-tenant access permissions for the request
+    #
+    # @param request [Rack::Request] the incoming request
+    # @param payload [Hash] the JWT payload containing tenant information
+    # @raise [AuthorizationError] if tenant validation fails
     def validate(request, payload)
       validate_subdomain(request, payload) if @config.validate_subdomain?
-      validate_company_slug(request, payload) if @config.validate_company_slug?
-      validate_company_header(request, payload) if @config.company_header_name
+      validate_pathname_slug(request, payload) if @config.validate_pathname_slug?
+      validate_company_header(request, payload) if @config.tenant_id_header_name
     end
 
     private
@@ -20,39 +46,40 @@ module RackJwtAegis
       return if request_host.nil? || request_host.empty?
 
       # Extract subdomain from request host
-      request_subdomain = extract_subdomain(request_host)
+      req_subdomain = extract_subdomain(request_host)
 
       # Get JWT domain claim
-      jwt_domain_key = @config.payload_key(:company_group_domain).to_s
+      jwt_domain_key = @config.payload_key(:subdomain).to_s
       jwt_domain = payload[jwt_domain_key]
 
       if jwt_domain.nil? || jwt_domain.empty?
-        raise AuthorizationError, 'JWT payload missing company_group_domain for subdomain validation'
+        raise AuthorizationError, 'JWT payload missing subdomain for subdomain validation'
       end
 
       # Extract subdomain from JWT domain
       jwt_subdomain = extract_subdomain(jwt_domain)
 
       # Compare subdomains
-      return if subdomains_match?(request_subdomain, jwt_subdomain)
+      return if subdomains_match?(req_subdomain, jwt_subdomain)
 
       raise AuthorizationError,
-            "Subdomain access denied: request subdomain '#{request_subdomain}' does not match JWT subdomain '#{jwt_subdomain}'"
+            "Subdomain access denied: request subdomain '#{req_subdomain}' " \
+            "does not match JWT subdomain '#{jwt_subdomain}'"
     end
 
     # Level 2 Multi-Tenant: Sub-level tenant (Company) validation via URL path
-    def validate_company_slug(request, payload)
+    def validate_pathname_slug(request, payload)
       # Extract company slug from URL path
       company_slug = extract_company_slug_from_path(request.path)
 
       return if company_slug.nil? # No company slug in path
 
       # Get accessible company slugs from JWT
-      jwt_slugs_key = @config.payload_key(:company_slugs).to_s
+      jwt_slugs_key = @config.payload_key(:pathname_slugs).to_s
       accessible_slugs = payload[jwt_slugs_key]
 
       if accessible_slugs.nil? || !accessible_slugs.is_a?(Array) || accessible_slugs.empty?
-        raise AuthorizationError, 'JWT payload missing or invalid company_slugs for company access validation'
+        raise AuthorizationError, 'JWT payload missing or invalid pathname_slugs for company access validation'
       end
 
       # Check if requested company slug is in user's accessible list
@@ -64,22 +91,20 @@ module RackJwtAegis
 
     # Company Group header validation (additional security layer)
     def validate_company_header(request, payload)
-      header_name = "HTTP_#{@config.company_header_name.upcase.tr('-', '_')}"
+      header_name = "HTTP_#{@config.tenant_id_header_name.upcase.tr('-', '_')}"
       header_value = request.get_header(header_name)
 
       return if header_value.nil? # Header not present, skip validation
 
       # Get company group ID from JWT
-      jwt_company_group_key = @config.payload_key(:company_group_id).to_s
-      jwt_company_group_id = payload[jwt_company_group_key]
+      jwt_company_group_key = @config.payload_key(:tenant_id).to_s
+      jwt_tenant_id = payload[jwt_company_group_key]
 
-      if jwt_company_group_id.nil?
-        raise AuthorizationError, 'JWT payload missing company_group_id for header validation'
-      end
+      raise AuthorizationError, 'JWT payload missing tenant_id for header validation' if jwt_tenant_id.nil?
 
       # Normalize values for comparison (both as strings)
       header_value_str = header_value.to_s
-      jwt_value_str = jwt_company_group_id.to_s
+      jwt_value_str = jwt_tenant_id.to_s
 
       return if header_value_str == jwt_value_str
 
@@ -110,7 +135,7 @@ module RackJwtAegis
       return nil if path.nil? || path.empty?
 
       # Use configured pattern to extract company slug
-      match = @config.company_slug_pattern.match(path)
+      match = @config.pathname_slug_pattern.match(path)
       return nil unless match && match[1]
 
       # Return captured group (company slug)