rack_jwt_aegis 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 775e606ab0475ef440f8d5e0b0cf4fa7834fdcadb9565c6123197437103b2e1f
-  data.tar.gz: 8dbf8f35c54e16ee86cc31b07a24d8ced023d7aa7684a3f1841cc811ceeb7c97
+  metadata.gz: 85f1445f011d0e42c075e3777164d61b215aa04b6f78e535db987c3f0e239c6f
+  data.tar.gz: 94fa6e5dd9041709d394e1c42dc5cc938aeb4fb9325218a94cab6352a4a7cf47
 SHA512:
-  metadata.gz: 758002b6d87d06d508eb2a548970ef81a16690db287362054927d4833c1200ded1f179fd573f505201d0d10204a9345bbc9f97c83af4c557757a3b39ed6eee8a
-  data.tar.gz: cfa522bc3373b26e1180507d04808132e4a3ea8aabfb4ac2a1661b62ec4953fc5014b93a89df9ae2d46f9c4af5b89893c298db7c37a9680d1f82bae1608e75ac
+  metadata.gz: 0e3e83285e30c8b86efb2977aba6cfeccf728539b689fb80fb658e29ac91e61c455ab48c5793b689293154d3fe985ad6fee71d3b2381261f34b481370c89e8a1
+  data.tar.gz: f42e6cdb32d72f06ef14d7c016cbb7970ad5b04f9626b16cc1bf7a4062cdb6b68a899548e80259bac934622b2adc3080121c2b7e82daa84ab93f2df30ad34e63

data/.yardopts

@@ -1,16 +1,14 @@
 --output-dir doc
 --readme README.md
---markup-provider=kramdown
---markup=markdown
 --main README.md
+--markup=markdown
 --protected
 --private
 --no-private
---title "RackJwtAegis API Documentation"
+--title "RackJwtAegis Rack Middleware API Documentation"
 --charset utf-8
 lib/**/*.rb
 -
 README.md
 LICENSE.txt
 CODE_OF_CONDUCT.md
-adrs/architecture.md

data/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] - 2025-08-13
+
+### 🔧 Fixed
+
+- Add :validate_tenant_id configuration and incorporate this to the MultiTenantValidator#validate_tenant_id_header
+
+#### Code Quality & Maintenance
+
+- Refactor the Configuration and MultiTenantValidator
+
+## [1.0.1] - 2025-08-13
+
+### 🔧 Fixed
+
+#### Code Quality & Maintenance
+
+- **DRY Refactoring**: Eliminated duplicate `debug_log` method implementations by creating a shared `DebugLogger` module
+  - Created `lib/rack_jwt_aegis/debug_logger.rb` with consistent debug logging functionality
+  - Updated `Middleware` and `RbacManager` classes to include the shared module
+  - Improved code maintainability by centralizing debug logging logic
+  - Maintains all existing functionality and logging behavior
+- **RBAC Cache Validation**: Enhanced wildcard permission validation in `validate_rbac_cache_format` to support `admin/*` patterns
+- **JWT Payload Resolution**: Fixed JWT payload key resolution to handle string keys consistently across components
+- **Test Coverage**: Maintained high test coverage (98.17% line coverage) after refactoring
+
+#### Developer Experience
+
+- **Consistent Logging**: Unified debug log format across all components with automatic timestamp formatting
+- **Component Identification**: Automatic component name inference for better log traceability
+- **Configurable Log Levels**: Support for info, warn, and error log levels with appropriate output streams
+
+### 🏗️ Technical Details
+
+#### Architecture Improvements
+
+- **Shared Module Pattern**: Introduced consistent module inclusion pattern for cross-cutting concerns
+- **Code Organization**: Better separation of concerns with dedicated debug logging module
+- **Maintainability**: Reduced code duplication from ~40 lines to a single shared implementation
+
+#### Testing & Quality
+
+- **Test Suite**: All 340 tests pass with 975 assertions
+- **Coverage Maintained**: 98.17% line coverage, 92.83% branch coverage
+- **RBAC Integration**: Verified all role-based authorization tests pass after refactoring
+- **Zero Regression**: No functional changes, only structural improvements
+
+---
+
 ## [1.0.0] - 2025-08-13
 
 ### 🎉 Initial Release
@@ -201,4 +249,5 @@ This 1.0.0 release represents a production-ready JWT authentication middleware w
 
 **Deprecations**: None (initial release).
 
+[1.0.1]: https://github.com/kanutocd/rack_jwt_aegis/releases/tag/v1.0.1
 [1.0.0]: https://github.com/kanutocd/rack_jwt_aegis/releases/tag/v1.0.0

data/README.md

@@ -6,7 +6,7 @@
 [![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-JWT authentication middleware for hierarchical multi-tenant Rack applications with 2-level tenant support.
+JWT authentication and authorization middleware for hierarchical multi-tenant Rack applications with 2-level tenant support.
 
 ## Features
 
@@ -14,7 +14,9 @@ JWT authentication middleware for hierarchical multi-tenant Rack applications wi
 - 2-level multi-tenant support (Example: Company-Group → Company, Organization → Department, etc.)
 - Subdomain-based tenant isolation for top-level tenants
 - URL pathname slug access control for sub-level tenants
+- **RBAC (Role-Based Access Control)** with flexible role extraction from JWT payloads
 - Configurable path exclusions for public endpoints
+- **Flexible payload mapping** for custom JWT claim names
 - Custom payload validation
 - Debug mode for development
 
@@ -44,25 +46,25 @@ Rack JWT Aegis includes a command-line tool for generating secure JWT secrets:
 
 ```bash
   # Generate a secure JWT secret
-  rack-jwt-aegis secret
+  rack_jwt_aegis secret
 
   # Generate base64-encoded secret
-  rack-jwt-aegis secret --format base64
+  rack_jwt_aegis secret --format base64
 
   # Generate secret in environment variable format
-  rack-jwt-aegis secret --env
+  rack_jwt_aegis secret --env
 
   # Generate multiple secrets
-  rack-jwt-aegis secret --count 3
+  rack_jwt_aegis secret --count 3
 
   # Quiet mode (secret only)
-  rack-jwt-aegis secret --quiet
+  rack_jwt_aegis secret --quiet
 
   # Custom length (32 bytes)
-  rack-jwt-aegis secret --length 32
+  rack_jwt_aegis secret --length 32
 
   # Show help
-  rack-jwt-aegis --help
+  rack_jwt_aegis --help
 ```
 
 ### Security Features
@@ -80,6 +82,7 @@ Rack JWT Aegis includes a command-line tool for generating secure JWT secrets:
   # config/application.rb
   config.middleware.insert_before 0, RackJwtAegis::Middleware, {
     jwt_secret: ENV['JWT_SECRET'],
+    validate_tenant_id: true,
     tenant_id_header_name: 'X-Tenant-Id',
     skip_paths: ['/api/v1/login', '/health']
   }
@@ -92,6 +95,7 @@ Rack JWT Aegis includes a command-line tool for generating secure JWT secrets:
 
   use RackJwtAegis::Middleware, {
     jwt_secret: ENV['JWT_SECRET'],
+    validate_tenant_id: true,
     tenant_id_header_name: 'X-Tenant-Id',
     skip_paths: ['/login', '/health']
   }
@@ -124,10 +128,20 @@ RackJwtAegis::Middleware.new(app, {
   jwt_algorithm: 'HS256',  # Default: 'HS256'
 
   # Multi-Tenant Settings
+  validate_tenant_id: true, # Default: false
   tenant_id_header_name: 'X-Tenant-Id',  # Default: 'X-Tenant-Id'
   validate_subdomain: true,     # Default: false
   validate_pathname_slug: true,  # Default: false
 
+  # Default Payload Mapping:
+  payload_mapping: {
+    user_id: :user_id,
+    tenant_id: :tenant_id,
+    subdomain: :subdomain,
+    pathname_slugs: :pathname_slugs,
+    role_ids: :role_ids,
+  },
+
   # Path Configuration
   skip_paths: ['/health', '/api/v1/login'],
   pathname_slug_pattern: /^\/api\/v1\/([^\/]+)\//,  # Default pattern
@@ -170,19 +184,22 @@ RackJwtAegis::Middleware.new(app, {
     payload['role'] == 'admin' || payload['permissions'].include?('read')
   },
 
-  # Flexible Payload Mapping
+  # Payload Mapping defaults:
+  # payload_mapping = {
+  #   user_id: :user_id,
+  #   tenant_id: :tenant_id,
+  #   subdomain: :subdomain,
+  #   pathname_slugs: :pathname_slugs,
+  #   role_ids: :role_ids,
+  # }
+
+  # Flexible Payload Mapping can be customized into:
   payload_mapping: {
     user_id: :sub,                    # Map 'sub' claim to user_id
     tenant_id: :company_group_id,    # Map 'company_group_id' claim
     subdomain: :company_group_domain_name,    # Map 'company_group_domain_name' claim
-    pathname_slugs: :accessible_company_slugs  # Map array of accessible companies
-  },
-
-  # Custom Tenant Extraction
-  tenant_strategy: :custom,
-  tenant_extractor: ->(request) {
-    # Extract tenant from custom header or logic
-    request.get_header('HTTP_X_TENANT_ID')
+    pathname_slugs: :accessible_company_slugs, # Map array of accessible companies
+    role_ids: :user_roles            # Map 'user_roles' claim for RBAC authorization
   }
 })
 ```
@@ -194,7 +211,7 @@ Rack JWT Aegis provides multiple strategies for multi-tenant authentication:
 ### Subdomain Validation
 
 ```ruby
-# Validates that the JWT's domain matches the request subdomain
+# Validates that the JWT's subdomain claim matches the request's host subdomain
 config.validate_subdomain = true
 ```
 
@@ -210,6 +227,7 @@ config.pathname_slug_pattern = /^\/api\/v1\/([^\/]+)\//
 
 ```ruby
 # Validates the X-Tenant-Id header against JWT payload
+config.validate_tenant_id = true
 config.tenant_id_header_name = 'X-Tenant-Id'
 ```
 
@@ -285,7 +303,8 @@ The middleware expects JWT payloads with the following structure:
   "tenant_id": 67890,
   "subdomain": "acme-group-of-companies", # the subdomain part of the host of the request url, e.g. `http://acme-group-of-companies.example.com`
   "pathname_slugs": ["an-acme-company-subsidiary", "another-acme-company-the-user-has-access"], # the user has access to these kind of request urls: https://acme-group-of-companies.example.com/api/v1/an-acme-company-subsidiary/* or https://acme-group-of-companies.example.com/api/v1/another-acme-company-the-user-has-access/
-  "roles": ["admin", "user"],
+  "role_ids": ["123", "456"], # Role IDs for RBAC authorization (can also be integers)
+  "roles": ["admin", "user"], # Legacy role names (kept for backward compatibility)
   "exp": 1640995200,
   "iat": 1640991600
 }
@@ -293,6 +312,69 @@ The middleware expects JWT payloads with the following structure:
 
 You can customize the payload mapping using the `payload_mapping` configuration option.
 
+### RBAC Role Extraction
+
+When RBAC is enabled, the middleware extracts user roles from the JWT payload for authorization. The default payload mapping includes:
+
+```ruby
+payload_mapping: {
+  user_id: :user_id,
+  tenant_id: :tenant_id,
+  subdomain: :subdomain,
+  pathname_slugs: :pathname_slugs,
+  role_ids: :role_ids    # Default field for user roles
+}
+```
+
+#### Role Field Resolution
+
+The middleware looks for roles in the following priority order:
+
+1. **Configured Field**: Uses the `role_ids` mapping (e.g., if mapped to `:user_roles`, looks for `user_roles` field)
+2. **Fallback Fields**: If the mapped field is not found, tries these common alternatives:
+   - `roles` - Array of role identifiers
+   - `role` - Single role identifier
+   - `user_roles` - Array of user role identifiers
+   - `role_ids` - Array of role IDs (numeric or string)
+
+#### Custom Role Field Mapping
+
+You can customize the role field using payload mapping:
+
+```ruby
+# Use a custom field name for roles
+payload_mapping: {
+  role_ids: :user_permissions  # Look for roles in 'user_permissions' field
+}
+
+# JWT payload would contain:
+{
+  "user_id": 123,
+  "user_permissions": ["admin", "manager"],
+  ...
+}
+```
+
+#### Role Format Support
+
+The middleware supports flexible role formats:
+
+```ruby
+# Array of strings (recommended)
+"role_ids": ["123", "456", "admin"]
+
+# Array of integers
+"role_ids": [123, 456]
+
+# Single string
+"role_ids": "admin"
+
+# Single integer
+"role_ids": 123
+```
+
+All role values are normalized to strings internally for consistent matching against RBAC cache permissions.
+
 ## Security Features
 
 - JWT signature verification
@@ -410,7 +492,8 @@ When RBAC is enabled, the middleware expects permissions to be stored in the cac
 
 2. **RBAC Permissions Validation**: Full permission evaluation
 
-   - Extract user roles from JWT payload (`roles`, `role`, `user_roles`, or `role_ids` field)
+   - Extract user roles from JWT payload using configurable field mapping (default: `role_ids`)
+   - Fallback to common fields: `roles`, `role`, `user_roles`, or `role_ids` if mapped field not found
    - Load RBAC permissions collection and validate format
    - For each user role, check if any permission matches:
      - Extract resource path from request URL (removes subdomain/pathname slug)
@@ -491,8 +574,8 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 This project maintains high test coverage:
 
-- **Line Coverage**: 97.8% (668/683 lines)
-- **Branch Coverage**: 86.62% (259/299 branches)
+- **Line Coverage**: 97.81% (670/685 lines)
+- **Branch Coverage**: 87.13% (264/303 branches)
 
 Run tests with coverage: `bundle exec rake test`
 

data/Rakefile

@@ -14,19 +14,11 @@ begin
   require 'yard'
   require 'yard/rake/yardoc_task'
 
-  # Load custom GFM configuration if available
-  begin
-    require_relative '.yard/yard_gfm_config'
-  rescue LoadError
-    # GFM config not available, use default markdown processing
-  end
-
   YARD::Rake::YardocTask.new do |t|
     t.files = ['lib/**/*.rb']
     t.options = [
       '--output-dir', 'doc',
       '--readme', 'README.md',
-      '--markup-provider', 'kramdown',
       '--markup', 'markdown'
     ]
     t.stats_options = ['--list-undoc']

data/lib/rack_jwt_aegis/configuration.rb

@@ -49,6 +49,10 @@ module RackJwtAegis
     # @return [Boolean] true if pathname slug validation is enabled
     attr_accessor :validate_pathname_slug
 
+    # Whether to validate tenant id from request header against the tenant id from JWT payload
+    # @return [Boolean] true if tenant id validation is enabled
+    attr_accessor :validate_tenant_id
+
     # Whether RBAC (Role-Based Access Control) is enabled
     # @return [Boolean] true if RBAC is enabled
     attr_accessor :rbac_enabled
@@ -204,6 +208,12 @@ module RackJwtAegis
       config_boolean?(validate_pathname_slug)
     end
 
+    # Check if tenant id validation is enabled
+    # @return [Boolean] true if tenant id validation is enabled
+    def validate_tenant_id?
+      config_boolean?(validate_tenant_id)
+    end
+
     # Check if debug mode is enabled
     # @return [Boolean] true if debug mode is enabled
     def debug_mode?
@@ -261,6 +271,7 @@ module RackJwtAegis
       @jwt_algorithm = 'HS256'
       @validate_subdomain = false
       @validate_pathname_slug = false
+      @validate_tenant_id = false
       @rbac_enabled = false
       @tenant_id_header_name = 'X-Tenant-Id'
       @pathname_slug_pattern = %r{^/api/v1/([^/]+)/}
@@ -273,6 +284,7 @@ module RackJwtAegis
         tenant_id: :tenant_id,
         subdomain: :subdomain,
         pathname_slugs: :pathname_slugs,
+        role_ids: :role_ids,
       }
       @unauthorized_response = { error: 'Authentication required' }
       @forbidden_response = { error: 'Access denied' }
@@ -280,12 +292,13 @@ module RackJwtAegis
 
     def validate!
       validate_jwt_settings!
+      validate_payload_mapping!
       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?
+      raise ConfigurationError, 'jwt_secret is required' if jwt_secret.to_s.strip.empty?
 
       valid_algorithms = ['HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512']
       return if valid_algorithms.include?(jwt_algorithm)
@@ -293,6 +306,24 @@ module RackJwtAegis
       raise ConfigurationError, "Unsupported JWT algorithm: #{jwt_algorithm}"
     end
 
+    def validate_payload_mapping!
+      # Allow nil payload_mapping (will use defaults)
+      return if payload_mapping.nil?
+
+      raise ConfigurationError, 'payload_mapping must be a Hash' unless payload_mapping.is_a?(Hash)
+
+      # Validate all values are symbols
+      invalid_values = payload_mapping.reject { |_key, value| value.is_a?(Symbol) }
+      return if invalid_values.empty?
+
+      raise ConfigurationError, "payload_mapping values must be symbols, invalid: #{invalid_values.inspect}"
+
+      # NOTE: We don't validate required keys because users may provide
+      # partial mappings that are intended to override defaults. The payload_key method
+      # handles missing keys by returning the standard key as fallback.
+      # This includes RBAC keys - if :role_ids is not mapped, it falls back to 'role_ids'.
+    end
+
     def validate_cache_settings!
       return unless rbac_enabled?
 
@@ -318,17 +349,23 @@ module RackJwtAegis
     end
 
     def validate_multi_tenant_settings!
-      if validate_pathname_slug? && pathname_slug_pattern.nil?
-        raise ConfigurationError, 'pathname_slug_pattern is required when validate_pathname_slug is true'
-      end
-
       if validate_subdomain? && !payload_mapping.key?(:subdomain)
         raise ConfigurationError, 'payload_mapping must include :subdomain when validate_subdomain is true'
       end
 
-      return unless validate_pathname_slug? && !payload_mapping.key?(:pathname_slugs)
+      if validate_tenant_id?
+        error_msg = []
+        error_msg << 'payload_mapping must include :tenant_id' unless payload_mapping.key?(:tenant_id)
+        error_msg << 'tenant_id_header_name is required' if tenant_id_header_name.to_s.strip.empty?
+        raise ConfigurationError, "#{error_msg.join(' and ')} when validate_tenant_id is true" if error_msg.any?
+      end
+
+      return unless validate_pathname_slug?
 
-      raise ConfigurationError, 'payload_mapping must include :pathname_slugs when validate_pathname_slug is true'
+      error_msg = []
+      error_msg << 'payload_mapping must include :pathname_slugs' unless payload_mapping.key?(:pathname_slugs)
+      error_msg << 'pathname_slug_pattern is required' if pathname_slug_pattern.to_s.empty?
+      raise ConfigurationError, "#{error_msg.join(' and ')} when validate_pathname_slug is true" if error_msg.any?
     end
   end
 end

data/lib/rack_jwt_aegis/debug_logger.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  # Shared debug logging functionality
+  #
+  # Provides consistent debug logging across all RackJwtAegis components
+  # with configurable log levels and automatic timestamp formatting.
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 1.0.0
+  module DebugLogger
+    # Log debug message if debug mode is enabled
+    #
+    # @param message [String] the message to log
+    # @param level [Symbol] the log level (:info, :warn, :error) (default: :info)
+    # @param component [String] the component name for log prefixing (optional)
+    def debug_log(message, level = :info, component = nil)
+      return unless @config.debug_mode?
+
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+
+      # Determine component name for log prefix
+      component_name = component || infer_component_name
+
+      formatted_message = "[#{timestamp}] #{component_name}: #{message}"
+
+      case level
+      when :error, :warn
+        warn formatted_message
+      else
+        puts formatted_message
+      end
+    end
+
+    private
+
+    # Infer component name from class name
+    #
+    # @return [String] the inferred component name
+    def infer_component_name
+      case self.class.name
+      when /Middleware/
+        'RackJwtAegis'
+      when /RbacManager/
+        'RbacManager'
+      else
+        self.class.name.split('::').last || 'RackJwtAegis'
+      end
+    end
+  end
+end

data/lib/rack_jwt_aegis/middleware.rb

@@ -25,6 +25,8 @@ module RackJwtAegis
   #     skip_paths: ['/health', '/api/public/*']
   #   }
   class Middleware
+    include DebugLogger
+
     # Initialize the middleware
     #
     # @param app [#call] the Rack application
@@ -65,7 +67,7 @@ module RackJwtAegis
         token = extract_jwt_token(request)
         payload = @jwt_validator.validate(token)
 
-        debug_log("JWT validation successful for user: #{payload[@config.payload_key(:user_id)]}")
+        debug_log("JWT validation successful for user: #{payload[@config.payload_key(:user_id).to_s]}")
 
         # Step 3: Multi-tenant validation (if enabled)
         if multi_tenant_enabled?
@@ -159,8 +161,12 @@ module RackJwtAegis
     # @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']
+      # Use configured payload mapping for role_ids, with fallback to common field names
+      role_key = @config.payload_key(:role_ids).to_s
+      roles = payload[role_key]
+
+      # If mapped key doesn't exist, try common fallback field names
+      roles = payload['roles'] || payload['role'] || payload['user_roles'] || payload['role_ids'] if roles.nil?
 
       case roles
       when Array
@@ -168,19 +174,10 @@ module RackJwtAegis
       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}")
+        debug_log("Warning: No valid roles found in JWT payload. Looking for '#{role_key}' field. \
+                   Available fields: #{payload.keys}".squeeze)
         []
       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?
-
-      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
-      puts "[#{timestamp}] RackJwtAegis: #{message}"
-    end
   end
 end

data/lib/rack_jwt_aegis/multi_tenant_validator.rb

@@ -33,83 +33,72 @@ module RackJwtAegis
     # @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_pathname_slug(request, payload) if @config.validate_pathname_slug?
-      validate_company_header(request, payload) if @config.tenant_id_header_name
+      validate_subdomain(request, payload)
+      validate_pathname_slug(request, payload)
+      validate_tenant_id_header(request, payload)
     end
 
     private
 
     # Level 1 Multi-Tenant: Top-level tenant (Company-Group) validation via subdomain
     def validate_subdomain(request, payload)
+      return unless @config.validate_subdomain?
+
       request_host = request.host
-      return if request_host.nil? || request_host.empty?
+      return if request_host.to_s.empty?
 
       # Extract subdomain from request host
-      req_subdomain = extract_subdomain(request_host)
+      req_subdomain = extract_subdomain(request_host).to_s.downcase
 
       # Get JWT domain claim
-      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 subdomain for subdomain validation'
-      end
-
-      # Extract subdomain from JWT domain
-      jwt_subdomain = extract_subdomain(jwt_domain)
+      jwt_claim = payload[@config.payload_key(:subdomain).to_s].to_s.strip.downcase
+      raise AuthorizationError, 'JWT payload missing subdomain for subdomain validation' if jwt_claim.empty?
 
       # Compare subdomains
-      return if subdomains_match?(req_subdomain, jwt_subdomain)
+      return if req_subdomain.eql?(jwt_claim)
 
       raise AuthorizationError,
             "Subdomain access denied: request subdomain '#{req_subdomain}' " \
-            "does not match JWT subdomain '#{jwt_subdomain}'"
+            "does not match JWT subdomain '#{jwt_claim}'"
     end
 
     # Level 2 Multi-Tenant: Sub-level tenant (Company) validation via URL path
     def validate_pathname_slug(request, payload)
+      return unless @config.validate_pathname_slug?
+
       # Extract company slug from URL path
-      company_slug = extract_company_slug_from_path(request.path)
+      pathname_slug = extract_slug_from_path(request.path)
 
-      return if company_slug.nil? # No company slug in path
+      return if pathname_slug.nil? # No company slug in path
 
       # Get accessible company slugs from JWT
-      jwt_slugs_key = @config.payload_key(:pathname_slugs).to_s
-      accessible_slugs = payload[jwt_slugs_key]
+      accessible_slugs = payload[@config.payload_key(:pathname_slugs).to_s]
 
       if accessible_slugs.nil? || !accessible_slugs.is_a?(Array) || accessible_slugs.empty?
         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
-      return if accessible_slugs.include?(company_slug)
+      return if accessible_slugs.map(&:downcase).include?(pathname_slug)
 
       raise AuthorizationError,
-            "Company access denied: '#{company_slug}' not in accessible companies #{accessible_slugs}"
+            "Company access denied: '#{pathname_slug}' not in accessible companies #{accessible_slugs}"
     end
 
     # Company Group header validation (additional security layer)
-    def validate_company_header(request, payload)
-      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(:tenant_id).to_s
-      jwt_tenant_id = payload[jwt_company_group_key]
+    def validate_tenant_id_header(request, payload)
+      return unless @config.validate_tenant_id?
 
-      raise AuthorizationError, 'JWT payload missing tenant_id for header validation' if jwt_tenant_id.nil?
+      # Get tenant id from request header
+      header_value = request.get_header("HTTP_#{@config.tenant_id_header_name.upcase.tr('-', '_')}").to_s.downcase
+      # Get tenant id from JWT payload
+      jwt_claim = payload[@config.payload_key(:tenant_id).to_s].to_s.strip.downcase
+      raise AuthorizationError, 'JWT payload missing tenant_id for header validation' if jwt_claim.empty?
 
-      # Normalize values for comparison (both as strings)
-      header_value_str = header_value.to_s
-      jwt_value_str = jwt_tenant_id.to_s
-
-      return if header_value_str == jwt_value_str
+      return if !header_value.empty? && header_value.eql?(jwt_claim)
 
       raise AuthorizationError,
-            "Company group header mismatch: header '#{header_value_str}' does not match JWT '#{jwt_value_str}'"
+            "Tenant id header mismatch: header '#{header_value}' does not match JWT '#{jwt_claim}'"
     end
 
     def extract_subdomain(host)
@@ -131,24 +120,9 @@ module RackJwtAegis
       parts.first
     end
 
-    def extract_company_slug_from_path(path)
-      return nil if path.nil? || path.empty?
-
+    def extract_slug_from_path(path)
       # Use configured pattern to extract company slug
-      match = @config.pathname_slug_pattern.match(path)
-      return nil unless match && match[1]
-
-      # Return captured group (company slug)
-      match[1]
-    end
-
-    def subdomains_match?(first_subdomain, second_subdomain)
-      # Handle nil cases
-      return true if first_subdomain.nil? && second_subdomain.nil?
-      return false if first_subdomain.nil? || second_subdomain.nil?
-
-      # Case-insensitive comparison
-      first_subdomain.downcase == second_subdomain.downcase
+      @config.pathname_slug_pattern.match(path.to_s.strip.downcase)&.to_a&.last
     end
   end
 end

data/lib/rack_jwt_aegis/rbac_manager.rb

@@ -15,6 +15,8 @@ module RackJwtAegis
   #   manager = RbacManager.new(config)
   #   manager.authorize(request, jwt_payload)
   class RbacManager
+    include DebugLogger
+
     CACHE_TTL = 300 # 5 minutes default cache TTL
 
     # Initialize the RBAC manager
@@ -122,14 +124,12 @@ module RackJwtAegis
         end
 
         # Permission is fresh
-        if @config.debug_mode?
-          debug_log("Cache hit: #{permission_key} (permission age: \
-                    #{permission_age}s, RBAC age: #{rbac_update_age || 'unknown'}s)".squeeze)
-        end
+        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
@@ -146,7 +146,7 @@ module RackJwtAegis
       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
 
@@ -166,10 +166,10 @@ module RackJwtAegis
         # Write back to cache
         @permission_cache.write('user_permissions', user_permissions, expires_in: CACHE_TTL)
 
-        debug_log("Cached permission: #{permission_key} => #{current_time}") if @config.debug_mode?
+        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
 
@@ -177,7 +177,7 @@ module RackJwtAegis
       # Extract user roles from JWT payload
       user_roles = extract_user_roles_from_request(request)
       if user_roles.nil? || user_roles.empty?
-        warn 'RbacManager: No user roles found in request context' if @config.debug_mode?
+        debug_log('RbacManager: No user roles found in request context', :warn)
         return false
       end
 
@@ -214,7 +214,7 @@ module RackJwtAegis
 
         nil
       rescue CacheError => e
-        warn "RbacManager RBAC last-update read error: #{e.message}" if @config.debug_mode?
+        debug_log("RbacManager RBAC last-update read error: #{e.message}", :warn)
         nil
       end
     end
@@ -233,14 +233,14 @@ module RackJwtAegis
         # 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}") if @config.debug_mode?
+          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}") if @config.debug_mode?
+          debug_log("Removed stale permission #{permission_key}: #{reason}")
         end
       rescue CacheError => e
-        warn "RbacManager stale permission removal error: #{e.message}" if @config.debug_mode?
+        debug_log("RbacManager stale permission removal error: #{e.message}", :warn)
       end
     end
 
@@ -250,9 +250,9 @@ module RackJwtAegis
 
       begin
         @permission_cache.delete('user_permissions')
-        debug_log("Nuked user permissions cache: #{reason}") if @config.debug_mode?
+        debug_log("Nuked user permissions cache: #{reason}")
       rescue CacheError => e
-        warn "RbacManager cache nuke error: #{e.message}" if @config.debug_mode?
+        debug_log("RbacManager cache nuke error: #{e.message}", :warn)
       end
     end
 
@@ -313,10 +313,10 @@ module RackJwtAegis
         # Write back to cache
         @permission_cache.write('user_permissions', user_permissions, expires_in: CACHE_TTL)
 
-        debug_log("Cached user permission: #{permission_key} => #{current_time}") if @config.debug_mode?
+        debug_log("Cached user 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
 
@@ -380,7 +380,7 @@ module RackJwtAegis
           regex = Regexp.new(regex_pattern)
           return regex.match?(resource_path)
         rescue RegexpError => e
-          warn "RbacManager: Invalid regex pattern '#{regex_pattern}': #{e.message}" if @config.debug_mode?
+          debug_log("RbacManager: Invalid regex pattern '#{regex_pattern}': #{e.message}", :warn)
           return false
         end
       end
@@ -422,6 +422,7 @@ module RackJwtAegis
           # 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
@@ -429,16 +430,8 @@ module RackJwtAegis
 
       true
     rescue StandardError => e
-      warn "RbacManager: Cache format validation error: #{e.message}" if @config.debug_mode?
+      debug_log("RbacManager: Cache format validation error: #{e.message}", :warn)
       false
     end
-
-    # Log debug message if debug mode is enabled
-    def debug_log(message)
-      return unless @config.debug_mode?
-
-      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
-      puts "[#{timestamp}] RbacManager: #{message}"
-    end
   end
 end

data/lib/rack_jwt_aegis/version.rb

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

data/lib/rack_jwt_aegis.rb

@@ -2,6 +2,7 @@
 
 require_relative 'rack_jwt_aegis/version'
 require_relative 'rack_jwt_aegis/configuration'
+require_relative 'rack_jwt_aegis/debug_logger'
 require_relative 'rack_jwt_aegis/middleware'
 require_relative 'rack_jwt_aegis/jwt_validator'
 require_relative 'rack_jwt_aegis/multi_tenant_validator'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack_jwt_aegis
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -44,7 +44,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.2'
 description: |-
-  JWT authentication midleware with multi-tenant suport,\
+  JWT authentication and authorization midleware with multi-tenant suport,\
    company validation, and subdomain isolation.
 email:
 - kenneth.c.demanawa@gmail.com
@@ -54,7 +54,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
-- ".yard/yard_gfm_config.rb"
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -68,6 +67,7 @@ files:
 - lib/rack_jwt_aegis.rb
 - lib/rack_jwt_aegis/cache_adapter.rb
 - lib/rack_jwt_aegis/configuration.rb
+- lib/rack_jwt_aegis/debug_logger.rb
 - lib/rack_jwt_aegis/jwt_validator.rb
 - lib/rack_jwt_aegis/middleware.rb
 - lib/rack_jwt_aegis/multi_tenant_validator.rb
@@ -100,5 +100,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: JWT authentication middleware for multi-tenant Rack applications
+summary: JWT authentication and authorization middleware for multi-tenant Rack applications
 test_files: []

data/.yard/yard_gfm_config.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-# Custom YARD configuration for GitHub Flavored Markdown support
-#
-# This configuration ensures the kramdown-parser-gfm gem is available for
-# proper rendering of fenced code blocks (```language) in YARD documentation.
-#
-# The actual GFM parsing integration is handled by YARD when kramdown is
-# configured with the GFM input parser.
-
-begin
-  require 'kramdown'
-  require 'kramdown-parser-gfm'
-  
-  # Ensure GFM parser is available - YARD will use it automatically
-  # when kramdown processes markdown with input: 'GFM'
-  
-rescue LoadError => e
-  # Fallback gracefully if GFM parser is not available
-  puts "Warning: kramdown-parser-gfm not available, fenced code blocks may not render properly: #{e.message}"
-end