rack_jwt_aegis 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85f1445f011d0e42c075e3777164d61b215aa04b6f78e535db987c3f0e239c6f
-  data.tar.gz: 94fa6e5dd9041709d394e1c42dc5cc938aeb4fb9325218a94cab6352a4a7cf47
+  metadata.gz: 355b1a9e875355d5a3c5c7ca9c83dd24af066e1c69e89c9030fab8bb2c5a3f71
+  data.tar.gz: e151caf3879396e067aaf2c7f5ba0228fece3de07c5bdf41ac3df3e37d271ab9
 SHA512:
-  metadata.gz: 0e3e83285e30c8b86efb2977aba6cfeccf728539b689fb80fb658e29ac91e61c455ab48c5793b689293154d3fe985ad6fee71d3b2381261f34b481370c89e8a1
-  data.tar.gz: f42e6cdb32d72f06ef14d7c016cbb7970ad5b04f9626b16cc1bf7a4062cdb6b68a899548e80259bac934622b2adc3080121c2b7e82daa84ab93f2df30ad34e63
+  metadata.gz: e9709c05464dade807e95a135d6c5fe7d4e301127c4ea23209086298bc3078882cd1c5454262b1bc1759d1b48b27ac7cd630690e735a210f354bbb20fea808e8
+  data.tar.gz: 505983dd1f954880f7ad1a9a6e33beaf3ff83734c5034f90f5515d1ac0d48bac7c6b4e75842aeb7860695bf10efd7aba24c012cafd97b7e1089270d853c0bb23

data/.ruby-version

@@ -0,0 +1 @@
+3.2

data/.yardopts

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

data/CHANGELOG.md

@@ -1,9 +1,218 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## Unreleased
 
-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.1] - 2026-06-13
+
+### 🚀 Added
+
+#### Method-Aware Skip Routes
+
+- Added `skip_routes` to support request-aware public route matching by path and HTTP verb.
+- Kept `skip_paths` as a backward-compatible alias for all-method skips.
+- Normalizes route rules once at configuration time so middleware checks stay fast per request.
+
+#### Route Skipping Behavior
+
+- Middleware now evaluates `METHOD + path` for skip decisions, so `POST /login` can be public while `GET /login` remains protected.
+- Added support for blank verb lists to mean all methods on a route entry.
+- Updated the Pink House API initializer to use the new `skip_routes` shape.
+
+### 🔧 Fixed
+
+#### Simplified RBAC Cache Strategy
+
+- **Streamlined Configuration**: Removed legacy cache configuration options to eliminate confusion
+  - **Removed**: `cache_store`, `cache_options`, and `cache_write_enabled` (deprecated in favor of dedicated RBAC cache stores)
+  - **Required**: When `rbac_enabled: true`, both `rbac_cache_store` and `permissions_cache_store` must be explicitly configured
+  - **Simplified**: Consistent naming with `rbac_cache_store_options` and `permissions_cache_store_options`
+
+#### Cache Store Validation
+
+- **Mandatory Configuration**: RBAC cache stores are now required when RBAC is enabled
+  - Prevents runtime errors from missing cache configuration
+  - Provides clear error messages during initialization: "rbac_cache_store and permissions_cache_store are required when RBAC is enabled"
+  - Ensures production deployments are properly configured for performance
+
+#### Code Cleanup
+
+- **Removed Complexity**: Eliminated dual cache mode logic and fallback mechanisms
+  - Simplified `RbacManager#setup_cache_adapters` method
+  - Removed conditional cache write logic that added complexity
+  - Cleaner permission checking flow with consistent cache behavior
+
+#### Developer Experience
+
+- **Clear Configuration**: Explicit cache store requirements eliminate guesswork
+- **Better Error Messages**: Configuration validation happens at startup, not at runtime
+- **Consistent Naming**: Standardized cache option parameter names across all adapters
+
+### 🏗️ Technical Details
+
+#### Breaking Changes (Minor - Configuration Only)
+
+- **Removed Configuration Options**:
+  - `cache_store` → Use `rbac_cache_store` and `permissions_cache_store` instead
+  - `cache_options` → Use `rbac_cache_store_options` and `permissions_cache_store_options` instead
+  - `cache_write_enabled` → Cache writing is now always enabled when RBAC is active
+
+#### Migration Guide
+
+**Before (v1.1.0):**
+```ruby
+use RackJwtAegis::Middleware, {
+  jwt_secret: ENV['JWT_SECRET'],
+  rbac_enabled: true,
+  cache_store: :redis,
+  cache_options: { url: ENV['REDIS_URL'] },
+  cache_write_enabled: true
+}
+```
+
+**After (v1.1.1):**
+```ruby
+use RackJwtAegis::Middleware, {
+  jwt_secret: ENV['JWT_SECRET'],
+  rbac_enabled: true,
+  rbac_cache_store: :redis,
+  rbac_cache_store_options: { url: ENV['REDIS_URL'] },
+  permissions_cache_store: :redis,
+  permissions_cache_store_options: { url: ENV['REDIS_URL'] }
+}
+```
+
+#### Benefits
+
+- **🚀 Simpler Configuration**: No more dual cache modes or conditional logic
+- **🛡️ Fail-Fast Validation**: Configuration errors caught at startup
+- **📈 Better Performance**: Dedicated cache stores optimized for their specific use cases
+- **🧹 Cleaner Code**: Reduced complexity in cache management logic
+
+---
+
+## [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
 
@@ -174,8 +383,8 @@ use RackJwtAegis::Middleware, {
   pathname_slug_pattern: /^\/api\/v1\/([^\/]+)\//,
   rbac_enabled: true,
   rbac_cache_store: :redis,
-  permission_cache_store: :memory,
-  user_permissions_ttl: 300,
+  permissions_cache_store: :memory,
+  cached_permissions_ttl: 300,
   cache_write_enabled: true,
   skip_paths: [/^\/health/, /^\/metrics/, /^\/api\/public/],
   custom_payload_validation: ->(payload) { payload['active'] == true },
@@ -249,5 +458,8 @@ This 1.0.0 release represents a production-ready JWT authentication middleware w
 
 **Deprecations**: None (initial release).
 
+[1.1.1]: https://github.com/kanutocd/rack_jwt_aegis/releases/tag/v1.1.1
+[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

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/rack_jwt_aegis.svg)](https://badge.fury.io/rb/rack_jwt_aegis)
 [![CI](https://github.com/kanutocd/rack_jwt_aegis/workflows/CI/badge.svg)](https://github.com/kanutocd/rack_jwt_aegis/actions)
 [![Coverage Status](https://codecov.io/gh/kanutocd/rack_jwt_aegis/branch/main/graph/badge.svg)](https://codecov.io/gh/kanutocd/rack_jwt_aegis)
-[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2.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 and authorization middleware for hierarchical multi-tenant Rack applications with 2-level tenant support.
@@ -147,28 +147,24 @@ RackJwtAegis::Middleware.new(app, {
   pathname_slug_pattern: /^\/api\/v1\/([^\/]+)\//,  # Default pattern
 
   # RBAC Configuration
-  rbac_enabled: true,               # Default: false
-  rbac_cache_store: :redis,         # Required when RBAC enabled
-  rbac_cache_options: { url: ENV['REDIS_URL'] },
-  user_permissions_ttl: 3600,       # Default: 1800 (30 minutes) - TTL for cached user permissions
-
-  # Cache Store Configuration (choose one approach)
-  # Option 1: Shared cache for both RBAC and permissions
-  cache_store: :memory,             # :memory, :redis, :memcached, :solid_cache
-  cache_options: { url: ENV['REDIS_URL'] },
-
-  # Option 2: Separate cache stores for RBAC and permissions
-  rbac_cache_store: :redis,         # For RBAC permissions data
-  rbac_cache_options: { url: ENV['REDIS_URL'] },
-  permission_cache_store: :memory,  # For cached user permissions
-  permission_cache_options: {},
+  rbac_enabled: true,                 # Default: false
+  rbac_cache_store: :redis,           # Required when RBAC enabled. Default: :memory
+  rbac_cache_store_options: { url: ENV['REDIS_URL'] }, # Cache Store specific options. Default: {}
+
+  cached_permissions_ttl: 3600,            # Default: 1800 (30 minutes) - TTL for cached user permissions
+  permissions_cache_store: :solid_cache,   # Required when RBAC enabled. Default: :memory
+  permissions_cache_store_options: {},     # Cache Store specific options. Default: {}
+
+  # Or can also be the same Redis instance
+  # permissions_cache_store: :redis,   # Required when RBAC enabled. Default: :memory
+  # permissions_cache_store_options: { url: ENV['REDIS_URL'] },
 
   # Response Customization
   unauthorized_response: { error: 'Authentication required' },
   forbidden_response: { error: 'Access denied' },
 
   # Debugging
-  debug_mode: Rails.env.development?  # Default: false
+  debug_mode: Rails.env.development?  # Default: when in Rails, Rails.env.development? otherwise false
 })
 ```
 
@@ -273,7 +269,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
@@ -291,7 +287,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
 
@@ -404,18 +400,19 @@ All role values are normalized to strings internally for consistent matching aga
 
 ```ruby
 # Memory cache (development/testing)
-config.cache_store = :memory
+config.rbac_cache_store = :memory         # Default. When in Rails, it will default to Rails.application.config.cache_store
+config.permissions_cache_store = :memory  # Default. When in Rails, it will default to Rails.application.config.cache_store
 
 # Redis cache
-config.cache_store = :redis
-config.cache_options = { url: ENV['REDIS_URL'] }
+config.rbac_cache_store = :redis
+config.rbac_cache_store_options = { url: ENV['REDIS_URL'] }
 
 # Memcached cache
-config.cache_store = :memcached
-config.cache_options = { servers: ['localhost:11211'] }
+config.rbac_cache_store = :memcached
+config.rbac_cache_store_options = { servers: ['localhost:11211'] }
 
 # Solid Cache (Rails 8+)
-config.cache_store = :solid_cache
+config.rbac_cache_store = :solid_cache
 ```
 
 #### Separate Cache Stores
@@ -425,11 +422,11 @@ You can configure separate cache stores for RBAC permissions data and cached use
 ```ruby
 # Use Redis for RBAC data (shared across instances)
 config.rbac_cache_store = :redis
-config.rbac_cache_options = { url: ENV['REDIS_URL'] }
+config.rbac_cache_store_options = { url: ENV['REDIS_URL'] }
 
 # Use memory for user permission cache (faster local access)
-config.permission_cache_store = :memory
-config.permission_cache_options = {}
+config.permissions_cache_store = :memory
+config.permissions_cache_store_options = {}
 ```
 
 ## RBAC Cache Format
@@ -439,31 +436,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
 
@@ -509,7 +503,7 @@ When RBAC is enabled, the middleware expects permissions to be stored in the cac
      "12345:acme-group.localhost.local/api/v1/company/sales/invoices:post": 1640995200
    }
    ```
-   TTL configurable via `user_permissions_ttl` option (default: 30 minutes)
+   TTL configurable via `cached_permissions_ttl` option (default: 30 minutes)
 
 ### Cache Invalidation Strategy
 

data/lib/rack_jwt_aegis/cache_adapter.rb

@@ -4,13 +4,13 @@ module RackJwtAegis
   class CacheAdapter
     def self.build(store_type, options = {})
       case store_type
-      when :memory
+      when :memory, :memory_store
         MemoryAdapter.new(options)
-      when :redis
+      when :redis, :redis_cache_store
         RedisAdapter.new(options)
-      when :memcached
+      when :memcached, :mem_cache_store
         MemcachedAdapter.new(options)
-      when :solid_cache
+      when :solid_cache, :solid_cache_store
         SolidCacheAdapter.new(options)
       else
         raise ConfigurationError, "Unsupported cache store: #{store_type}"

data/lib/rack_jwt_aegis/circuit_breaker.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'ratomic'
+
+module RackJwtAegis
+  class CircuitBreaker
+    STATE_FAILURE_COUNT = 'failure_count'
+    STATE_OPENED_AT = 'opened_at'
+
+    def initialize(failure_threshold:, cooldown_seconds:)
+      @failure_threshold = failure_threshold.to_i
+      @cooldown_seconds = cooldown_seconds.to_i
+      @state = Ratomic::Map.new
+      reset
+    end
+
+    def allow_request?
+      return true unless open?
+      return false unless cooldown_elapsed?
+
+      reset
+      true
+    end
+
+    def record_success
+      reset
+    end
+
+    def record_failure
+      failures = @state.increment(STATE_FAILURE_COUNT)
+      @state[STATE_OPENED_AT] = Time.now.to_f if failures >= @failure_threshold
+      failures
+    end
+
+    def open?
+      !@state[STATE_OPENED_AT].nil?
+    end
+
+    private
+
+    def reset
+      @state[STATE_FAILURE_COUNT] = 0
+      @state.delete(STATE_OPENED_AT)
+    end
+
+    def cooldown_elapsed?
+      opened_at = @state[STATE_OPENED_AT]
+      opened_at && (Time.now.to_f - opened_at) >= @cooldown_seconds
+    end
+  end
+end