rack_jwt_aegis 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e776985ff922d83b9ac75821698125a565dce342be61bd4bf6012fc97dfd82c
-  data.tar.gz: 7bbb4006689d39ea9ec47ad869b01468bbfbddfb0ecbaa430d28ac96f1fd33b7
+  metadata.gz: b5246ed44e15045cae4b9ec776d95b29e3f30f40008b41081c44acc61105e3de
+  data.tar.gz: 0d72626e7d23203a12ff37dbbf1516664f2043a52423404a9fdd43cd9ddc85ee
 SHA512:
-  metadata.gz: 64eb785ccd161bf7f7a7e0ce2b9840007885778b47d35a5528fe586ebcc160aa2f3d356e92868f8931c0789603a78fbc1feef56d6141dbeb322611330404b77a
-  data.tar.gz: 84f45c9c58aed4eadbcfd8a1d78d1a3e0cdd47c9f602ae9047e847738c671c0513dacfc9298207456fa969a44045ec6b8b8ff29fea3e0c29f76357aa4933ddaf
+  metadata.gz: b2ac0d480d1e060e36e114fccfb373c6c6602913f49f227c94d24feb112590f877146e903c3dfdc726c2dc2c130ae9f1c183a968febba522e1607e2483cfba09
+  data.tar.gz: 2c349695ae61b01a65fd87f8de710d85f356e29b0328a639ea5aef5548c40140aaa4395a5245fb0374caabdaa9dd11abf14c88a161275f4f4bd3b0f233bda621

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,103 @@
 # 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.2.0] - 2026-08-24
+
+### Added
+
+- Added `skip_options_requests` to bypass JWT authentication for CORS preflight
+  requests while leaving ordinary requests protected.
+- Documented the intended middleware ordering: `Rack::Cors` must run before
+  `RackJwtAegis::Middleware`.
+
+## [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
 
@@ -71,11 +165,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### 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. 
+"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
 
@@ -96,6 +192,7 @@ Expected format: {\"role-id\": [\"resource:method\", ...]}, but got: Array"
 #### Updating RBAC Cache Format
 
 **Before (v1.0.x):**
+
 ```ruby
 Rails.cache.write("permissions", {
   'last_update' => Time.now.to_i,
@@ -107,6 +204,7 @@ Rails.cache.write("permissions", {
 ```
 
 **After (v1.1.0+):**
+
 ```ruby
 Rails.cache.write("permissions", {
   'last_update' => Time.now.to_i,
@@ -294,8 +392,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 },
@@ -369,6 +467,7 @@ 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

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.
@@ -15,7 +15,8 @@ JWT authentication and authorization middleware for hierarchical multi-tenant Ra
 - 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
+- Configurable route exclusions for public endpoints
+- Optional automatic bypass for browser CORS preflight requests
 - **Flexible payload mapping** for custom JWT claim names
 - Custom payload validation
 - Debug mode for development
@@ -79,15 +80,36 @@ Rack JWT Aegis includes a command-line tool for generating secure JWT secrets:
 ### Rails Application
 
 ```ruby
-  # config/application.rb
-  config.middleware.insert_before 0, RackJwtAegis::Middleware, {
+# config/initializers/cors.rb
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+  allow do
+    origins 'https://app.example.com'
+    resource '*', headers: :any,
+      methods: %i[get post put patch delete options head]
+  end
+end
+
+# config/initializers/rack_jwt_aegis.rb
+Rails.application.config.middleware.insert_after Rack::Cors, RackJwtAegis::Middleware, {
     jwt_secret: ENV['JWT_SECRET'],
     validate_tenant_id: true,
     tenant_id_header_name: 'X-Tenant-Id',
-    skip_paths: ['/api/v1/login', '/health']
+    # Browser OPTIONS preflight requests do not carry bearer credentials.
+    skip_options_requests: true,
+    skip_routes: [
+      { path: '/api/v1/login', verbs: [:post] },
+      { path: '/health' }
+    ]
   }
 ```
 
+`Rack::Cors` should run before `RackJwtAegis::Middleware` in the Rack stack.
+It can then validate the request origin, requested method, and requested
+headers and handle valid preflight requests before JWT authentication runs.
+`skip_options_requests: true` is an additional middleware-level safeguard: it
+skips JWT authentication for `OPTIONS` requests only. It does not make any
+non-`OPTIONS` request public, and it does not replace CORS validation.
+
 ### Sinatra Application
 
 ```ruby
@@ -97,7 +119,10 @@ Rack JWT Aegis includes a command-line tool for generating secure JWT secrets:
     jwt_secret: ENV['JWT_SECRET'],
     validate_tenant_id: true,
     tenant_id_header_name: 'X-Tenant-Id',
-    skip_paths: ['/login', '/health']
+    skip_routes: [
+      { path: '/login', verbs: [:post] },
+      { path: '/health' }
+    ]
   }
 ```
 
@@ -142,33 +167,33 @@ RackJwtAegis::Middleware.new(app, {
     role_ids: :role_ids,
   },
 
-  # Path Configuration
-  skip_paths: ['/health', '/api/v1/login'],
+  # Route Configuration
+  skip_options_requests: false, # Set true when Rack::Cors handles browser preflight requests
+  skip_routes: [
+    { path: '/health' },
+    { path: '/api/v1/login', verbs: [:post] }
+  ],
   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
 })
 ```
 
@@ -404,18 +429,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 +451,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
@@ -506,7 +532,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