rack_jwt_aegis 0.0.0

data/lib/rack_jwt_aegis/multi_tenant_validator.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  class MultiTenantValidator
+    def initialize(config)
+      @config = config
+    end
+
+    def validate(request, payload)
+      validate_subdomain(request, payload) if @config.validate_subdomain?
+      validate_company_slug(request, payload) if @config.validate_company_slug?
+      validate_company_header(request, payload) if @config.company_header_name
+    end
+
+    private
+
+    # Level 1 Multi-Tenant: Top-level tenant (Company-Group) validation via subdomain
+    def validate_subdomain(request, payload)
+      request_host = request.host
+      return if request_host.nil? || request_host.empty?
+
+      # Extract subdomain from request host
+      request_subdomain = extract_subdomain(request_host)
+
+      # Get JWT domain claim
+      jwt_domain_key = @config.payload_key(:company_group_domain).to_s
+      jwt_domain = payload[jwt_domain_key]
+
+      if jwt_domain.nil? || jwt_domain.empty?
+        raise AuthorizationError, 'JWT payload missing company_group_domain for subdomain validation'
+      end
+
+      # Extract subdomain from JWT domain
+      jwt_subdomain = extract_subdomain(jwt_domain)
+
+      # Compare subdomains
+      return if subdomains_match?(request_subdomain, jwt_subdomain)
+
+      raise AuthorizationError,
+            "Subdomain access denied: request subdomain '#{request_subdomain}' does not match JWT subdomain '#{jwt_subdomain}'"
+    end
+
+    # Level 2 Multi-Tenant: Sub-level tenant (Company) validation via URL path
+    def validate_company_slug(request, payload)
+      # Extract company slug from URL path
+      company_slug = extract_company_slug_from_path(request.path)
+
+      return if company_slug.nil? # No company slug in path
+
+      # Get accessible company slugs from JWT
+      jwt_slugs_key = @config.payload_key(:company_slugs).to_s
+      accessible_slugs = payload[jwt_slugs_key]
+
+      if accessible_slugs.nil? || !accessible_slugs.is_a?(Array) || accessible_slugs.empty?
+        raise AuthorizationError, 'JWT payload missing or invalid company_slugs for company access validation'
+      end
+
+      # Check if requested company slug is in user's accessible list
+      return if accessible_slugs.include?(company_slug)
+
+      raise AuthorizationError,
+            "Company access denied: '#{company_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.company_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(:company_group_id).to_s
+      jwt_company_group_id = payload[jwt_company_group_key]
+
+      if jwt_company_group_id.nil?
+        raise AuthorizationError, 'JWT payload missing company_group_id for header validation'
+      end
+
+      # Normalize values for comparison (both as strings)
+      header_value_str = header_value.to_s
+      jwt_value_str = jwt_company_group_id.to_s
+
+      return if header_value_str == jwt_value_str
+
+      raise AuthorizationError,
+            "Company group header mismatch: header '#{header_value_str}' does not match JWT '#{jwt_value_str}'"
+    end
+
+    def extract_subdomain(host)
+      return nil if host.nil? || host.empty?
+
+      # Handle different host formats:
+      # - subdomain.domain.com -> subdomain
+      # - subdomain.domain.co.uk -> subdomain
+      # - domain.com -> nil (no subdomain)
+      # - localhost:3000 -> nil (no subdomain)
+
+      parts = host.split('.')
+
+      # Need at least 3 parts for subdomain (subdomain.domain.tld)
+      # or 4 parts for country domains (subdomain.domain.co.uk)
+      return nil if parts.length < 3
+
+      # Return first part as subdomain
+      parts.first
+    end
+
+    def extract_company_slug_from_path(path)
+      return nil if path.nil? || path.empty?
+
+      # Use configured pattern to extract company slug
+      match = @config.company_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
+    end
+  end
+end

data/lib/rack_jwt_aegis/rbac_manager.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  class RbacManager
+    CACHE_TTL = 300 # 5 minutes default cache TTL
+    LAST_UPDATE_KEY = 'last-update'
+
+    def initialize(config)
+      @config = config
+      setup_cache_adapters
+    end
+
+    def authorize(request, payload)
+      user_id = payload[@config.payload_key(:user_id).to_s]
+      raise AuthorizationError, 'User ID missing from JWT payload' if user_id.nil?
+
+      # Build permission key
+      permission_key = build_permission_key(user_id, request)
+
+      # Check cached permission first (if middleware can write to cache)
+      if @permission_cache && @config.cache_write_enabled?
+        cached_permission = check_cached_permission(permission_key)
+        return if cached_permission == true
+
+        raise AuthorizationError, 'Access denied - cached permission' if cached_permission == false
+      end
+
+      # Permission not cached or cache miss - check RBAC store
+      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?
+
+      return if has_permission
+
+      raise AuthorizationError, 'Access denied - insufficient permissions'
+    end
+
+    private
+
+    def setup_cache_adapters
+      if @config.cache_write_enabled? && @config.cache_store
+        # Shared cache mode - both RBAC and permission cache use same store
+        @rbac_cache = CacheAdapter.build(@config.cache_store, @config.cache_options || {})
+        @permission_cache = @rbac_cache
+      else
+        # Separate cache mode - different stores for RBAC and permissions
+        if @config.rbac_cache_store
+          @rbac_cache = CacheAdapter.build(@config.rbac_cache_store, @config.rbac_cache_options || {})
+        end
+
+        if @config.permission_cache_store
+          @permission_cache = CacheAdapter.build(@config.permission_cache_store, @config.permission_cache_options || {})
+        end
+      end
+
+      # Ensure we have at least RBAC cache for permission lookups
+      return if @rbac_cache
+
+      raise ConfigurationError, 'RBAC cache store not configured'
+    end
+
+    def build_permission_key(user_id, request)
+      "#{user_id}:#{request.host}:#{request.path}:#{request.request_method}"
+    end
+
+    def check_cached_permission(permission_key)
+      return nil unless @permission_cache
+
+      begin
+        # Get cached permission entry
+        cached_entry = @permission_cache.read(permission_key)
+        return nil if cached_entry.nil?
+
+        # Check if cached entry is still valid based on last-update timestamp
+        if cached_entry.is_a?(Hash) && cached_entry['timestamp'] && cached_entry['permission']
+          last_update_time = last_update_timestamp
+
+          return cached_entry['permission'] if last_update_time && cached_entry['timestamp'] >= last_update_time
+
+          # Cached entry is stale, remove it
+          @permission_cache.delete(permission_key)
+          return nil
+
+        end
+
+        # Invalid cached entry format
+        @permission_cache.delete(permission_key)
+        nil
+      rescue CacheError => e
+        # Log cache error but don't fail the request
+        warn "RbacManager cache read error: #{e.message}" if @config.debug_mode?
+        nil
+      end
+    end
+
+    def check_rbac_permission(user_id, request)
+      # Build RBAC lookup key
+      rbac_key = build_rbac_key(user_id, request.host, request.path, request.request_method)
+
+      # Check RBAC cache store for permission
+      permission_data = @rbac_cache.read(rbac_key)
+
+      if permission_data.nil?
+        # No explicit permission found - default to deny
+        false
+      else
+        # Permission data found - check if it grants access
+        case permission_data
+        when true, 'true', 1, '1'
+          true
+        when false, 'false', 0, '0'
+          false
+        else
+          # Complex permission data - delegate to custom logic if available
+          evaluate_complex_permission?(permission_data, user_id, request)
+        end
+      end
+    rescue CacheError => e
+      # Cache error - fail secure (deny access)
+      warn "RbacManager RBAC cache error: #{e.message}" if @config.debug_mode?
+      false
+    end
+
+    def cache_permission_result(permission_key, has_permission)
+      return unless @permission_cache
+
+      begin
+        current_time = Time.now.to_i
+        cache_entry = {
+          'permission' => has_permission,
+          'timestamp' => current_time,
+        }
+
+        @permission_cache.write(permission_key, cache_entry, expires_in: CACHE_TTL)
+      rescue CacheError => e
+        # Log cache error but don't fail the request
+        warn "RbacManager permission cache write error: #{e.message}" if @config.debug_mode?
+      end
+    end
+
+    def last_update_timestamp
+      @rbac_cache.read(LAST_UPDATE_KEY)
+    rescue CacheError => e
+      warn "RbacManager last-update read error: #{e.message}" if @config.debug_mode?
+      nil
+    end
+
+    def build_rbac_key(user_id, host, path, method)
+      # Standard RBAC key format as defined in architecture
+      "#{user_id}:#{host}:#{path}:#{method}"
+    end
+
+    def evaluate_complex_permission?(permission_data, user_id, request)
+      # Handle complex permission data structures
+      case permission_data
+      when Hash
+        # Permission data is a hash - could contain role-based rules
+        evaluate_hash_permission?(permission_data, user_id, request)
+      when Array
+        # Permission data is an array - could be list of allowed actions
+        evaluate_array_permission?(permission_data, request.request_method)
+      else
+        # Unknown format - default to deny
+        false
+      end
+    end
+
+    def evaluate_hash_permission?(permission_hash, _user_id, request)
+      # Example: {"allowed_methods": ["GET", "POST"], "roles": ["admin"]}
+
+      # Check allowed methods
+      if permission_hash['allowed_methods']
+        allowed_methods = Array(permission_hash['allowed_methods'])
+        return allowed_methods.include?(request.request_method)
+      end
+
+      # Check roles (would need role information from JWT payload)
+      if permission_hash['roles']
+        # This would require additional JWT payload inspection
+        # For now, default to allowing if roles are specified
+        return true
+      end
+
+      # Check boolean permission field
+      return !!permission_hash['allowed'] if permission_hash.key?('allowed')
+
+      # Default deny for unknown hash structure
+      false
+    end
+
+    def evaluate_array_permission?(permission_array, request_method)
+      # Array of allowed HTTP methods
+      permission_array.include?(request_method)
+    end
+  end
+end

data/lib/rack_jwt_aegis/request_context.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  class RequestContext
+    # Standard environment keys for JWT data
+    JWT_PAYLOAD_KEY = 'rack_jwt_aegis.payload'
+    USER_ID_KEY = 'rack_jwt_aegis.user_id'
+    COMPANY_GROUP_ID_KEY = 'rack_jwt_aegis.company_group_id'
+    COMPANY_GROUP_DOMAIN_KEY = 'rack_jwt_aegis.company_group_domain'
+    COMPANY_SLUGS_KEY = 'rack_jwt_aegis.company_slugs'
+    AUTHENTICATED_KEY = 'rack_jwt_aegis.authenticated'
+
+    def initialize(config)
+      @config = config
+    end
+
+    def set_context(env, payload)
+      # Set the full payload
+      env[JWT_PAYLOAD_KEY] = payload
+
+      # Set authentication flag
+      env[AUTHENTICATED_KEY] = true
+
+      # Extract and set commonly used values for easy access
+      set_user_context(env, payload)
+      set_tenant_context(env, payload)
+    end
+
+    # Class methods for easy access from application code
+    def self.authenticated?(env)
+      !!env[AUTHENTICATED_KEY]
+    end
+
+    def self.payload(env)
+      env[JWT_PAYLOAD_KEY]
+    end
+
+    def self.user_id(env)
+      env[USER_ID_KEY]
+    end
+
+    def self.company_group_id(env)
+      env[COMPANY_GROUP_ID_KEY]
+    end
+
+    def self.company_group_domain(env)
+      env[COMPANY_GROUP_DOMAIN_KEY]
+    end
+
+    def self.company_slugs(env)
+      env[COMPANY_SLUGS_KEY] || []
+    end
+
+    def self.current_user_id(request)
+      user_id(request.env)
+    end
+
+    def self.current_company_group_id(request)
+      company_group_id(request.env)
+    end
+
+    def self.has_company_access?(env, company_slug)
+      company_slugs(env).include?(company_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
+    end
+
+    def set_tenant_context(env, payload)
+      # Set company group information
+      if @config.validate_subdomain? || @config.payload_mapping.key?(:company_group_id)
+        company_group_id_key = @config.payload_key(:company_group_id).to_s
+        company_group_id = payload[company_group_id_key]
+        env[COMPANY_GROUP_ID_KEY] = company_group_id
+      end
+
+      if @config.validate_subdomain?
+        company_domain_key = @config.payload_key(:company_group_domain).to_s
+        company_domain = payload[company_domain_key]
+        env[COMPANY_GROUP_DOMAIN_KEY] = company_domain
+      end
+
+      # Set company slugs for sub-level tenant access
+      return unless @config.validate_company_slug? || @config.payload_mapping.key?(:company_slugs)
+
+      company_slugs_key = @config.payload_key(:company_slugs).to_s
+      company_slugs = payload[company_slugs_key]
+
+      # Ensure it's an array
+      company_slugs = Array(company_slugs) if company_slugs
+      env[COMPANY_SLUGS_KEY] = company_slugs || []
+    end
+  end
+end

data/lib/rack_jwt_aegis/response_builder.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RackJwtAegis
+  class ResponseBuilder
+    def initialize(config)
+      @config = config
+    end
+
+    def unauthorized_response(message = nil)
+      error_response(
+        message || @config.unauthorized_response[:error] || 'Authentication required',
+        401,
+      )
+    end
+
+    def forbidden_response(message = nil)
+      error_response(
+        message || @config.forbidden_response[:error] || 'Access denied',
+        403,
+      )
+    end
+
+    def error_response(message, status_code)
+      response_body = build_error_body(message, status_code)
+
+      [
+        status_code,
+        {
+          'Content-Type' => 'application/json',
+          'Content-Length' => response_body.bytesize.to_s,
+          'Cache-Control' => 'no-cache, no-store, must-revalidate',
+          'Pragma' => 'no-cache',
+          'Expires' => '0',
+        },
+        [response_body],
+      ]
+    end
+
+    private
+
+    def build_error_body(message, status_code)
+      error_data = {
+        error: message,
+        status: status_code,
+        timestamp: Time.now.iso8601,
+      }
+
+      # Add additional context in debug mode
+      if @config.debug_mode?
+        error_data[:middleware] = 'rack_jwt_aegis'
+        error_data[:version] = RackJwtAegis::VERSION
+      end
+
+      JSON.generate(error_data)
+    end
+  end
+end

data/lib/rack_jwt_aegis/version.rb

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

data/lib/rack_jwt_aegis.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'rack_jwt_aegis/version'
+require_relative 'rack_jwt_aegis/configuration'
+require_relative 'rack_jwt_aegis/middleware'
+require_relative 'rack_jwt_aegis/jwt_validator'
+require_relative 'rack_jwt_aegis/multi_tenant_validator'
+require_relative 'rack_jwt_aegis/rbac_manager'
+require_relative 'rack_jwt_aegis/cache_adapter'
+require_relative 'rack_jwt_aegis/request_context'
+require_relative 'rack_jwt_aegis/response_builder'
+
+module RackJwtAegis
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class AuthorizationError < Error; end
+  class CacheError < Error; end
+end

data/sig/rack_jwt_bastion.rbs

@@ -0,0 +1,4 @@
+module RackJwtAegis
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: rack_jwt_aegis
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Ken C. Demanawa
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-08-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: JWT authentication middleware with multi-tenant support, company validation,
+  and subdomain isolation.
+email:
+- kenneth.c.demanawa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/basic_usage.rb
+- lib/rack_jwt_aegis.rb
+- lib/rack_jwt_aegis/cache_adapter.rb
+- lib/rack_jwt_aegis/configuration.rb
+- lib/rack_jwt_aegis/jwt_validator.rb
+- lib/rack_jwt_aegis/middleware.rb
+- lib/rack_jwt_aegis/multi_tenant_validator.rb
+- lib/rack_jwt_aegis/rbac_manager.rb
+- lib/rack_jwt_aegis/request_context.rb
+- lib/rack_jwt_aegis/response_builder.rb
+- lib/rack_jwt_aegis/version.rb
+- sig/rack_jwt_bastion.rbs
+homepage: https://github.com/kanutocd/rack_jwt_aegis
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kanutocd/rack_jwt_aegis
+  source_code_uri: https://github.com/kanutocd/rack_jwt_aegis
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key: 
+specification_version: 4
+summary: JWT authentication middleware for multi-tenant Rack applications
+test_files: []