rack_jwt_aegis 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 355b1a9e875355d5a3c5c7ca9c83dd24af066e1c69e89c9030fab8bb2c5a3f71
-  data.tar.gz: e151caf3879396e067aaf2c7f5ba0228fece3de07c5bdf41ac3df3e37d271ab9
+  metadata.gz: b5246ed44e15045cae4b9ec776d95b29e3f30f40008b41081c44acc61105e3de
+  data.tar.gz: 0d72626e7d23203a12ff37dbbf1516664f2043a52423404a9fdd43cd9ddc85ee
 SHA512:
-  metadata.gz: e9709c05464dade807e95a135d6c5fe7d4e301127c4ea23209086298bc3078882cd1c5454262b1bc1759d1b48b27ac7cd630690e735a210f354bbb20fea808e8
-  data.tar.gz: 505983dd1f954880f7ad1a9a6e33beaf3ff83734c5034f90f5515d1ac0d48bac7c6b4e75842aeb7860695bf10efd7aba24c012cafd97b7e1089270d853c0bb23
+  metadata.gz: b2ac0d480d1e060e36e114fccfb373c6c6602913f49f227c94d24feb112590f877146e903c3dfdc726c2dc2c130ae9f1c183a968febba522e1607e2483cfba09
+  data.tar.gz: 2c349695ae61b01a65fd87f8de710d85f356e29b0328a639ea5aef5548c40140aaa4395a5245fb0374caabdaa9dd11abf14c88a161275f4f4bd3b0f233bda621

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## [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

data/README.md

@@ -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,8 +167,12 @@ 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

data/lib/rack_jwt_aegis/configuration.rb

@@ -55,6 +55,10 @@ module RackJwtAegis
     # @return [Boolean] true if strict authenticated request headers are required
     attr_accessor :require_authentication_headers
 
+    # Whether HTTP OPTIONS preflight requests should bypass JWT authentication
+    # @return [Boolean] true if OPTIONS requests are treated as CORS preflight
+    attr_accessor :skip_options_requests
+
     # Whether JWTs must include expiration-related claims
     # @return [Boolean] true if exp and iat claims are required
     attr_accessor :require_expiration_claims
@@ -178,6 +182,7 @@ module RackJwtAegis
     # @option options [String] :jwt_algorithm ('HS256') JWT algorithm to use
     # @option options [Boolean] :validate_subdomain (false) enable subdomain validation
     # @option options [Boolean] :validate_pathname_slug (false) enable pathname slug validation
+    # @option options [Boolean] :skip_options_requests (false) bypass JWT authentication for OPTIONS requests
     # @option options [Boolean] :rbac_enabled (false) enable RBAC authorization
     # @option options [String] :tenant_id_header_name ('X-Tenant-Id') tenant ID header name
     # @option options [Regexp] :pathname_slug_pattern default pattern for pathname slugs
@@ -242,6 +247,12 @@ module RackJwtAegis
       config_boolean?(require_authentication_headers)
     end
 
+    # Check if OPTIONS requests bypass JWT authentication
+    # @return [Boolean] true if CORS preflight requests are skipped
+    def skip_options_requests?
+      config_boolean?(skip_options_requests)
+    end
+
     # Check if exp and iat claims are required
     # @return [Boolean] true if expiration claims are required
     def require_expiration_claims?
@@ -312,6 +323,7 @@ module RackJwtAegis
       @validate_pathname_slug = false
       @validate_tenant_id = false
       @require_authentication_headers = false
+      @skip_options_requests = false
       @require_expiration_claims = false
       @tenant_id_header_name = 'X-Tenant-Id'
       @tenant_slug_header_name = 'X-Tenant-Slug'

data/lib/rack_jwt_aegis/middleware.rb

@@ -65,7 +65,7 @@ module RackJwtAegis
       end
 
       # Step 1: Check if route should be skipped
-      if @config.skip_request?(request.path, request.request_method)
+      if preflight_request?(request) || @config.skip_request?(request.path, request.request_method)
         debug_log("Skipping authentication for route: #{request.request_method} #{request.path}")
         return call_app(env)
       end
@@ -155,6 +155,10 @@ module RackJwtAegis
         @config.require_authentication_headers?
     end
 
+    def preflight_request?(request)
+      @config.skip_options_requests? && request.request_method == 'OPTIONS'
+    end
+
     def build_circuit_breaker
       return nil unless @config.circuit_breaker_enabled?
 

data/lib/rack_jwt_aegis/version.rb

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

data/lib/rack_jwt_aegis.rb

@@ -25,6 +25,7 @@ require_relative 'rack_jwt_aegis/response_builder'
 # - Multiple cache adapter support (Memory, Redis, Memcached, SolidCache)
 # - Request context management
 # - Configurable skip routes and custom validators
+# - Optional automatic bypass for CORS preflight requests
 #
 # @example Basic usage
 #   use RackJwtAegis::Middleware, jwt_secret: ENV['JWT_SECRET']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack_jwt_aegis
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -120,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: JWT authentication and authorization middleware for multi-tenant Rack applications
 test_files: []