rack_jwt_aegis 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bc9e89c08947641810cb3c0a5aef91c56554dcf44e593abc10cb7b75ebe6478
-  data.tar.gz: bcbd0711caf2bd74d65ede714cf4cf24eb016146fc69e20bfdf76a165d8a009c
+  metadata.gz: 0e776985ff922d83b9ac75821698125a565dce342be61bd4bf6012fc97dfd82c
+  data.tar.gz: 7bbb4006689d39ea9ec47ad869b01468bbfbddfb0ecbaa430d28ac96f1fd33b7
 SHA512:
-  metadata.gz: 7d279d25565397a64e45be0b157a01e63ca7c8e688fd1bb3592649cef8a2037380f5c9c1ddad645ad46f2326d5cd8cc279661207371825d26fe0c6cc036dd272
-  data.tar.gz: fe7e42dc37a5dca3a4fe443fc14e0a64178994b20406471ab6139be4e0b8917a663bcc45d29a819749875a9ef4cecd7d85cd8e13ef9cf5b6054ace0be090d540
+  metadata.gz: 64eb785ccd161bf7f7a7e0ce2b9840007885778b47d35a5528fe586ebcc160aa2f3d356e92868f8931c0789603a78fbc1feef56d6141dbeb322611330404b77a
+  data.tar.gz: 84f45c9c58aed4eadbcfd8a1d78d1a3e0cdd47c9f602ae9047e847738c671c0513dacfc9298207456fa969a44045ec6b8b8ff29fea3e0c29f76357aa4933ddaf

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,136 @@ 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.1.0] - 2025-08-14
+
+### 🚀 Added
+
+#### Enhanced RBAC Cache Format
+
+- **Improved Performance**: Changed RBAC cache format from array-based to flat object structure for O(1) role lookup
+  - **Before**: `"permissions": [{ "role-id": ["resource:method"] }]` (O(n) array iteration)
+  - **After**: `"permissions": { "role-id": ["resource:method"] }` (O(1) direct access)
+- **Developer Experience**: Enhanced error detection with descriptive ConfigurationError exceptions
+  - Catches common migration mistakes when upgrading from array to object format
+  - Provides clear error messages with expected format examples
+  - Helps developers quickly identify and fix RBAC configuration issues
+
+#### Documentation Improvements
+
+- **Clean Documentation**: Fixed YARD documentation rendering issues with improved Markdown processing
+  - Added Redcarpet gem for better Markdown parsing in YARD
+  - Removed complex Jekyll integration that was causing rendering issues
+  - Maintained YARD for comprehensive API documentation with cleaner output
+- **API Documentation**: Enhanced code comments for better YARD rendering
+  - Updated key method documentation with clearer parameter descriptions
+  - Improved examples and usage patterns in documentation
+  - Better integration with YARD's HTML generation
+
+### 🔧 Fixed
+
+#### RBAC System Improvements
+
+- **Cache Format Validation**: Added explicit validation for RBAC permissions format
+  - Raises `ConfigurationError` when permissions is not a Hash
+  - Provides helpful error messages for developers
+  - Maintains backward compatibility for other validation scenarios
+- **Role Lookup Logic**: Optimized role permission checking with direct hash access
+  - Eliminated unnecessary array iteration in permission validation
+  - Improved performance for applications with many roles
+  - Maintains support for both string and integer role keys
+
+#### Bug Fixes
+
+- **Test Coverage**: Fixed `test_check_rbac_format?` test that was using old array format
+- **Key Resolution**: Fixed JWT payload key resolution bug in `rbac_last_update_timestamp` method
+- **Validation Logic**: Updated all validation tests to use new flat object format
+
+### 🏗️ Technical Details
+
+#### Architecture Changes
+
+- **RBAC Manager**: Updated `validate_rbac_cache_format` and `check_rbac_format?` methods
+  - Direct hash lookup: `permissions_data[role_id]` instead of array iteration
+  - Improved error handling with specific ConfigurationError exceptions
+  - Enhanced validation with clear developer feedback
+- **Exception Handling**: Re-raises ConfigurationError while preserving other error handling
+  - Developer errors bubble up for immediate attention
+  - Runtime errors (cache issues) are still handled gracefully
+  - Maintains existing debug logging for troubleshooting
+
+#### Performance Improvements
+
+- **O(1) Role Lookup**: Direct hash access for role permissions
+- **Reduced Memory**: Eliminated nested array structures
+- **Faster Validation**: Simplified permission checking logic
+
+#### Developer Experience
+
+- **Better Error Messages**: Clear configuration error descriptions
+```ruby
+# Example error message:
+"RBAC permissions must be a Hash with role-id keys, not Array. 
+Expected format: {\"role-id\": [\"resource:method\", ...]}, but got: Array"
+```
+- **Migration Support**: Catches common mistakes when upgrading cache format
+- **Improved Documentation**: Cleaner YARD output with better Markdown rendering
+
+### 📚 Documentation Updates
+
+- **README.md**: Updated RBAC cache format examples and specifications
+- **YARD Integration**: Fixed documentation rendering with Redcarpet Markdown processor
+- **Code Examples**: Updated all examples to use new flat object format
+
+### 🧪 Testing
+
+- **Test Coverage Maintained**: All tests updated to use new cache format
+- **Enhanced Validation**: Added tests for new configuration error scenarios
+- **Comprehensive Coverage**: Validated migration scenarios and edge cases
+
+### ⚠️ Migration Guide
+
+#### Updating RBAC Cache Format
+
+**Before (v1.0.x):**
+```ruby
+Rails.cache.write("permissions", {
+  'last_update' => Time.now.to_i,
+  'permissions' => [
+    { '123' => ['sales/invoices:get', 'sales/invoices:post'] },
+    { '456' => ['admin/*:*'] }
+  ]
+})
+```
+
+**After (v1.1.0+):**
+```ruby
+Rails.cache.write("permissions", {
+  'last_update' => Time.now.to_i,
+  'permissions' => {
+    '123' => ['sales/invoices:get', 'sales/invoices:post'],
+    '456' => ['admin/*:*']
+  }
+})
+```
+
+#### Benefits of Migration
+
+- **🚀 Better Performance**: O(1) role lookup instead of O(n) iteration
+- **🛠️ Easier Management**: Direct role access for permission updates
+- **📝 Cleaner Code**: Simpler data structure that's easier to understand and maintain
+
+---
+
+## [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
@@ -23,7 +153,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### 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  
+- **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
@@ -37,7 +167,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Testing & Quality
 
 - **Test Suite**: All 340 tests pass with 975 assertions
-- **Coverage Maintained**: 98.17% line coverage, 92.83% branch coverage  
+- **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
 
@@ -239,5 +369,7 @@ This 1.0.0 release represents a production-ready JWT authentication middleware w
 
 **Deprecations**: None (initial release).
 
+[1.1.0]: https://github.com/kanutocd/rack_jwt_aegis/releases/tag/v1.1.0
+[1.0.2]: https://github.com/kanutocd/rack_jwt_aegis/releases/tag/v1.0.2
 [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
 
@@ -46,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
@@ -82,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']
   }
@@ -94,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']
   }
@@ -126,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
@@ -172,7 +184,16 @@ 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
@@ -190,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
 ```
 
@@ -206,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'
 ```
 
@@ -251,7 +273,7 @@ accessible_companies = RackJwtAegis::RequestContext.pathname_slugs(request.env)
 # => ["company-a", "company-b"]
 
 # Check if user has access to specific company
-has_access = RackJwtAegis::RequestContext.has_company_access?(request.env, "company-a")
+has_access = RackJwtAegis::RequestContext.has_pathname_slug_access?(request.env, "company-a")
 # => true
 
 # Helper methods for request objects
@@ -269,7 +291,7 @@ tenant_id = RackJwtAegis::RequestContext.current_tenant_id(request)
 - `pathname_slugs(env)` - Get array of accessible company slugs
 - `current_user_id(request)` - Helper for request objects
 - `current_tenant_id(request)` - Helper for request objects
-- `has_company_access?(env, slug)` - Check company access
+- `has_pathname_slug_access?(env, slug)` - Check company access
 
 ## JWT Payload Structure
 
@@ -297,7 +319,7 @@ When RBAC is enabled, the middleware extracts user roles from the JWT payload fo
 ```ruby
 payload_mapping: {
   user_id: :user_id,
-  tenant_id: :tenant_id, 
+  tenant_id: :tenant_id,
   subdomain: :subdomain,
   pathname_slugs: :pathname_slugs,
   role_ids: :role_ids    # Default field for user roles
@@ -311,7 +333,7 @@ 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  
+   - `role` - Single role identifier
    - `user_roles` - Array of user role identifiers
    - `role_ids` - Array of role IDs (numeric or string)
 
@@ -341,7 +363,7 @@ The middleware supports flexible role formats:
 # Array of strings (recommended)
 "role_ids": ["123", "456", "admin"]
 
-# Array of integers  
+# Array of integers
 "role_ids": [123, 456]
 
 # Single string
@@ -417,31 +439,28 @@ When RBAC is enabled, the middleware expects permissions to be stored in the cac
 ```json
 {
   "last_update": 1640995200,
-  "permissions": [
-    {
-      "123": [
-        "sales/invoices:get",
-        "sales/invoices:post",
-        "%r{sales/invoices/\\d+}:get",
-        "%r{sales/invoices/\\d+}:put",
-        "users/*:get"
-      ]
-    },
-    {
-      "456": ["admin/*:*", "reports:get"]
-    }
-  ]
+  "permissions": {
+    "123": [
+      "sales/invoices:get",
+      "sales/invoices:post",
+      "%r{sales/invoices/\\d+}:get",
+      "%r{sales/invoices/\\d+}:put",
+      "users/*:get"
+    ],
+    "456": ["admin/*:*", "reports:get"]
+  }
 }
 ```
 
 ### Format Specification
 
 - **last_update**: Timestamp for cache invalidation
-- **permissions**: Array of role permission objects
-- **Role ID**: String or numeric identifier for user roles
-- **Permission Format**: `"resource-endpoint:http-method"`
-  - **resource-endpoint**: API path (literal string or regex pattern)
-  - **http-method**: `get`, `post`, `put`, `delete`, or `*` (wildcard)
+- **permissions**: Object containing direct role-to-permissions mapping:
+  - **Role ID** (key): String or numeric identifier
+  - **Permissions** (value): Array of permission strings
+  - **Permission Format**: `"resource-endpoint:http-method"`
+    - **resource-endpoint**: API path (literal string or regex pattern)
+    - **http-method**: `get`, `post`, `put`, `delete`, or `*` (wildcard)
 
 ### Permission Examples
 

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/([^/]+)/}
@@ -287,7 +298,7 @@ module RackJwtAegis
     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)
@@ -338,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

@@ -20,7 +20,7 @@ module RackJwtAegis
       timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
 
       # Determine component name for log prefix
-      component_name = component || infer_component_name
+      component_name = component || self.class.name.split('::').last || 'RackJwtAegis'
 
       formatted_message = "[#{timestamp}] #{component_name}: #{message}"
 
@@ -31,21 +31,5 @@ module RackJwtAegis
         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/jwt_validator.rb

@@ -19,6 +19,7 @@ module RackJwtAegis
   # @example With multi-tenant validation
   #   config = Configuration.new(
   #     jwt_secret: 'your-secret',
+  #     validate_tenant_id: true,
   #     validate_subdomain: true,
   #     validate_pathname_slug: true
   #   )
@@ -95,21 +96,14 @@ module RackJwtAegis
     # @param payload [Hash] the JWT payload to validate
     # @raise [AuthenticationError] if required claims are missing
     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(:tenant_id)
-        required_claims << @config.payload_key(:subdomain)
-      end
-
+      required_claims = [@config.payload_key(:user_id)]
+      required_claims << @config.payload_key(:subdomain) if @config.validate_subdomain?
+      required_claims << @config.payload_key(:tenant_id) if @config.validate_tenant_id?
       required_claims << @config.payload_key(:pathname_slugs) if @config.validate_pathname_slug?
+      required_claims << @config.payload_key(:role_ids) if @config.rbac_enabled?
 
-      missing_claims = required_claims.select { |claim| payload[claim.to_s].nil? }
-
+      missing_claims = required_claims.select { |claim| payload[claim.to_s].to_s.empty? }
       return if missing_claims.empty?
 
       raise AuthenticationError, "JWT payload missing required claims: #{missing_claims.join(', ')}"
@@ -120,25 +114,24 @@ module RackJwtAegis
     # @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
-
+      user_id = payload[@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)
+      if user_id.to_s.empty? || (!user_id.is_a?(Numeric) && !user_id.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?
-        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)
+      # Tenant ID should be numeric or string (if present)
+      if @config.validate_tenant_id?
+        tenant_id = payload[@config.payload_key(:tenant_id).to_s]
+        if tenant_id.to_s.empty? || (!tenant_id.is_a?(Numeric) && !tenant_id.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(:subdomain).to_s
-        if payload[company_domain_key] && !payload[company_domain_key].is_a?(String)
+        subdomain = payload[@config.payload_key(:subdomain).to_s]
+        if subdomain.to_s.empty? || !subdomain.is_a?(String)
           raise AuthenticationError, 'Invalid subdomain format in JWT payload'
         end
       end
@@ -146,8 +139,8 @@ module RackJwtAegis
       # Company slugs should be array (if present)
       return unless @config.validate_pathname_slug?
 
-      pathname_slugs_key = @config.payload_key(:pathname_slugs).to_s
-      return unless payload[pathname_slugs_key] && !payload[pathname_slugs_key].is_a?(Array)
+      pathname_slugs = payload[@config.payload_key(:pathname_slugs).to_s]
+      return unless pathname_slugs && !pathname_slugs.is_a?(Array)
 
       raise AuthenticationError, 'Invalid pathname_slugs format in JWT payload - must be array'
     end

data/lib/rack_jwt_aegis/middleware.rb

@@ -19,6 +19,8 @@ module RackJwtAegis
   # @example Advanced usage
   #   use RackJwtAegis::Middleware, {
   #     jwt_secret: ENV['JWT_SECRET'],
+  #     validate_tenant_id: true,
+  #     validate_pathname_slug: true,
   #     validate_subdomain: true,
   #     rbac_enabled: true,
   #     cache_store: :redis,
@@ -142,7 +144,7 @@ module RackJwtAegis
     #
     # @return [Boolean] true if subdomain or pathname slug validation is enabled
     def multi_tenant_enabled?
-      @config.validate_subdomain? || @config.validate_pathname_slug?
+      @config.validate_tenant_id? || @config.validate_subdomain? || @config.validate_pathname_slug?
     end
 
     # Generate a string describing enabled features for logging
@@ -150,8 +152,9 @@ module RackJwtAegis
     # @return [String] comma-separated list of enabled features
     def enabled_features
       features = ['JWT']
+      features << 'TenantId' if @config.validate_tenant_id?
       features << 'Subdomain' if @config.validate_subdomain?
-      features << 'CompanySlug' if @config.validate_pathname_slug?
+      features << 'PathnameSlug' if @config.validate_pathname_slug?
       features << 'RBAC' if @config.rbac_enabled?
       features.join(', ')
     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

@@ -51,7 +51,7 @@ module RackJwtAegis
       has_permission = check_rbac_permission(user_id, request)
 
       # Cache the result if middleware has write access
-      cache_permission_result(permission_key, has_permission) if @permission_cache && @config.cache_write_enabled?
+      cache_permission_result(permission_key, has_permission)
 
       return if has_permission
 
@@ -83,23 +83,21 @@ module RackJwtAegis
     end
 
     def build_permission_key(user_id, request)
-      full_url = "#{request.host}#{request.path}"
-      "#{user_id}:#{full_url}:#{request.request_method.downcase}"
+      "#{user_id}:#{request.host}#{request.path}:#{request.request_method.downcase}"
     end
 
     def check_cached_permission(permission_key)
       return nil unless @permission_cache
 
       begin
-        # Get the user permissions cache using new format
+        # Get the cached user permissions
         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
+          rbac_update_age = Time.now.to_i - rbac_last_update
 
           # If RBAC was updated within the TTL period, all cached permissions are invalid
           if rbac_update_age <= @config.user_permissions_ttl
@@ -108,12 +106,11 @@ module RackJwtAegis
           end
         end
 
-        # Check if permission exists in new format: {"user_id:full_url:method" => timestamp}
+        # Check if permission exists in this format: {"user_id:full_url:method" => timestamp}
         cached_timestamp = user_permissions[permission_key]
         return nil unless cached_timestamp.is_a?(Integer)
 
-        current_time = Time.now.to_i
-        permission_age = current_time - cached_timestamp
+        permission_age = Time.now.to_i - cached_timestamp
 
         # Second check: TTL expiration
         if permission_age > @config.user_permissions_ttl
@@ -181,22 +178,23 @@ module RackJwtAegis
         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)
+      # Get permissions object for direct lookup
+      permissions_data = rbac_data['permissions'] || rbac_data[:permissions]
 
-          permissions = role_permissions[role_id.to_s] || role_permissions[role_id.to_i]
-          matched_permission = find_matching_permission(permissions, request)
+      # Check permissions for each user role using direct lookup
+      user_roles.each do |role_id|
+        # Try both string and integer keys for role lookup
+        role_permissions = permissions_data[role_id.to_s] || permissions_data[role_id.to_i]
+        next unless role_permissions
 
-          next unless matched_permission
+        matched_permission = find_matching_permission(role_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
+        # 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
 
       false
@@ -208,7 +206,7 @@ module RackJwtAegis
 
       begin
         rbac_data = @rbac_cache.read('permissions')
-        if rbac_data.is_a?(Hash) && (rbac_data['last_update'] || rbac_data[:last_update])
+        if rbac_data.is_a?(Hash) && (rbac_data.key?('last_update') || rbac_data.key?(:last_update))
           return rbac_data['last_update'] || rbac_data[:last_update]
         end
 
@@ -393,9 +391,9 @@ module RackJwtAegis
     # Expected format:
     # {
     #   last_update: timestamp,
-    #   permissions: [
-    #     {role-id: ["{resource-endpoint}:{http-method}"]}
-    #   ]
+    #   permissions: {
+    #     "role-id": ["{resource-endpoint}:{http-method}"]
+    #   }
     # }
     def validate_rbac_cache_format(rbac_data)
       return false unless rbac_data.is_a?(Hash)
@@ -404,31 +402,35 @@ module RackJwtAegis
       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
+      # Get permissions object (now expecting a Hash, not 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)
+      # If permissions is present but not a Hash, raise an exception to help developers
+      if !permissions.nil? && !permissions.is_a?(Hash)
+        raise ConfigurationError, "RBAC permissions must be a Hash with role-id keys, not #{permissions.class}. " \
+                                  "Expected format: {\"role-id\": [\"resource:method\", ...]}, " \
+                                  "but got: #{permissions.class}"
+      end
 
-        # Each entry should have at least one role-id key
-        return false if permission_entry.empty?
+      # Return false if permissions is nil (should not happen given the key check above, but defensive)
+      return false if permissions.nil?
 
-        # Validate permission values are arrays of strings
-        permission_entry.each_value do |role_permissions|
-          return false unless role_permissions.is_a?(Array)
+      # Validate each role's permissions
+      permissions.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
+        # 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) or '*' (wildcard)
+          return false unless permission.include?(':') || permission.include?('*')
         end
       end
 
       true
+    rescue ConfigurationError
+      # Re-raise configuration errors so developers see them
+      raise
     rescue StandardError => e
       debug_log("RbacManager: Cache format validation error: #{e.message}", :warn)
       false

data/lib/rack_jwt_aegis/request_context.rb

@@ -100,42 +100,23 @@ module RackJwtAegis
       tenant_id(request.env)
     end
 
-    def self.has_company_access?(env, company_slug)
-      pathname_slugs(env).include?(company_slug)
+    def self.has_pathname_slug_access?(env, pathname_slug)
+      pathname_slugs(env).include?(pathname_slug)
     end
 
     private
 
     def set_user_context(env, payload)
-      user_id_key = @config.payload_key(:user_id).to_s
-      user_id = payload[user_id_key]
-
-      env[USER_ID_KEY] = user_id
+      env[USER_ID_KEY] = payload[@config.payload_key(:user_id).to_s]
     end
 
     def set_tenant_context(env, payload)
-      # Set company group information
-      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(:subdomain).to_s
-        company_domain = payload[company_domain_key]
-        env[SUBDOMAIN_KEY] = company_domain
-      end
-
-      # Set company slugs for sub-level tenant access
+      # Set multi-tenant information
+      env[TENANT_ID_KEY] = payload[@config.payload_key(:tenant_id).to_s] if @config.validate_tenant_id?
+      env[SUBDOMAIN_KEY] = payload[@config.payload_key(:subdomain).to_s] if @config.validate_subdomain?
       return unless @config.validate_pathname_slug? || @config.payload_mapping.key?(:pathname_slugs)
 
-      pathname_slugs_key = @config.payload_key(:pathname_slugs).to_s
-      pathname_slugs = payload[pathname_slugs_key]
-
-      # Ensure it's an array
-      pathname_slugs = Array(pathname_slugs) if pathname_slugs
-      env[PATHNAME_SLUGS_KEY] = pathname_slugs || []
+      env[PATHNAME_SLUGS_KEY] = Array(payload[@config.payload_key(:pathname_slugs).to_s]).flatten
     end
   end
 end

data/lib/rack_jwt_aegis/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack_jwt_aegis
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 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
@@ -101,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