rack_jwt_aegis 0.0.0 → 1.0.1

data/exe/rack_jwt_aegis

@@ -0,0 +1,235 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'securerandom'
+require 'base64'
+
+# CLI for rack_jwt_aegis gem
+class RackJwtAegisCLI
+  def initialize
+    @options = {
+      length: 64,
+      format: :hex,
+      count: 1,
+    }
+  end
+
+  def run(args = ARGV)
+    parse_options(args)
+
+    case @command
+    when :generate_secret
+      generate_secrets
+    when :version
+      show_version
+    else
+      show_help
+    end
+  end
+
+  private
+
+  def parse_options(args)
+    @command = :generate_secret # default command
+
+    OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+      opts.banner = 'Usage: rack-jwt-aegis [command] [options]'
+      opts.separator ''
+      opts.separator 'Commands:'
+      opts.separator '    secret          Generate JWT secret(s) (default)'
+      opts.separator '    version         Show version'
+      opts.separator '    help            Show this help'
+      opts.separator ''
+      opts.separator 'Secret generation options:'
+
+      opts.on('-l', '--length LENGTH', Integer, 'Secret length in bytes (default: 64)') do |length|
+        @options[:length] = length
+      end
+
+      opts.on('-f', '--format FORMAT', [:hex, :base64, :raw], # rubocop:disable Naming/VariableNumber
+              'Output format: hex, base64, raw (default: hex)') do |format|
+        @options[:format] = format
+      end
+
+      opts.on('-c', '--count COUNT', Integer, 'Number of secrets to generate (default: 1)') do |count|
+        @options[:count] = count
+      end
+
+      opts.on('-e', '--env', 'Output in environment variable format') do
+        @options[:env_format] = true
+      end
+
+      opts.on('-q', '--quiet', 'Quiet mode - only output the secret(s)') do
+        @options[:quiet] = true
+      end
+
+      opts.on('-h', '--help', 'Show this help') do
+        @command = :help
+      end
+
+      opts.on('-v', '--version', 'Show version') do
+        @command = :version
+      end
+
+      opts.separator ''
+      opts.separator 'Examples:'
+      opts.separator '    rack-jwt-aegis secret                    # Generate hex secret'
+      opts.separator '    rack-jwt-aegis secret -f base64          # Generate base64 secret'
+      opts.separator '    rack-jwt-aegis secret -l 32 -c 3         # Generate 3 secrets, 32 bytes each'
+      opts.separator '    rack-jwt-aegis secret -e                 # Output as JWT_SECRET=...'
+      opts.separator '    rack-jwt-aegis secret -q                 # Quiet mode'
+      opts.separator ''
+    end.parse!(args)
+
+    # Handle command from remaining args
+    return unless args.length.positive?
+
+    case args[0].downcase
+    when 'secret', 'generate'
+      @command = :generate_secret
+    when 'version'
+      @command = :version
+    when 'help'
+      @command = :help
+    else
+      # Invalid command - show help
+      @command = :help
+      @invalid_command = args[0]
+    end
+  end
+
+  def generate_secrets
+    unless @options[:quiet]
+      puts '🛡️  Rack JWT Aegis - Secret Generator'
+      puts '=' * 50
+      puts
+    end
+
+    @options[:count].times do |i|
+      secret = SecureRandom.random_bytes(@options[:length])
+      formatted_secret = format_secret(secret)
+
+      if @options[:env_format]
+        puts "JWT_SECRET=#{formatted_secret}"
+      elsif @options[:quiet]
+        puts formatted_secret
+      else
+        puts "Secret #{i + 1}:" if @options[:count] > 1
+        puts formatted_secret
+        unless @options[:quiet]
+          puts "Length: #{@options[:length]} bytes (#{formatted_secret.length} characters)"
+          puts "Format: #{@options[:format]}"
+          puts "Entropy: ~#{(@options[:length] * 8).to_f} bits"
+          puts
+        end
+      end
+    end
+
+    return if @options[:quiet]
+
+    puts '💡 Usage in your application:'
+    puts "   export JWT_SECRET=\"#{format_secret(SecureRandom.random_bytes(@options[:length]))}\""
+    puts '   # or add to your .env file'
+    puts
+    puts '⚠️  Security reminders:'
+    puts '   - Store secrets securely (environment variables, not in code)'
+    puts '   - Use different secrets for different environments'
+    puts '   - Rotate secrets periodically'
+    puts '   - Never commit secrets to version control'
+  end
+
+  def format_secret(secret)
+    case @options[:format]
+    when :hex
+      secret.unpack1('H*')
+    when :base64 # rubocop:disable Naming/VariableNumber
+      Base64.strict_encode64(secret)
+    when :raw
+      secret
+    end
+  end
+
+  def show_version
+    # Try to load the version from the gem
+
+    require_relative '../lib/rack_jwt_aegis/version'
+    puts "rack_jwt_aegis #{RackJwtAegis::VERSION}"
+  rescue LoadError
+    puts 'rack_jwt_aegis (version unknown)'
+  end
+
+  def show_help
+    if @invalid_command
+      puts "❌ Unknown command: #{@invalid_command}"
+      puts
+    end
+
+    puts <<~HELP
+      🛡️  Rack JWT Aegis CLI
+
+      A command-line tool for generating secure JWT secrets and managing
+      rack_jwt_aegis configurations.
+
+      USAGE:
+          rack-jwt-aegis [command] [options]
+
+      COMMANDS:
+          secret          Generate secure JWT secret(s)
+          version         Show gem version
+          help            Show this help message
+
+      SECRET GENERATION:
+          The secret command generates cryptographically secure random
+          secrets suitable for JWT signing.
+
+      EXAMPLES:
+          # Generate a 64-byte hex secret (default)
+          rack-jwt-aegis secret
+
+          # Generate a base64-encoded secret
+          rack-jwt-aegis secret --format base64
+
+          # Generate 3 secrets at once
+          rack-jwt-aegis secret --count 3
+
+          # Generate secret for environment variable
+          rack-jwt-aegis secret --env
+
+          # Quiet mode (only output secret)
+          rack-jwt-aegis secret --quiet
+
+          # Custom length (32 bytes)
+          rack-jwt-aegis secret --length 32
+
+      SECURITY NOTES:
+          - Generated secrets use SecureRandom for cryptographic security
+          - Default 64-byte secrets provide ~512 bits of entropy
+          - Always store secrets securely (environment variables, secret managers)
+          - Use different secrets for different environments
+          - Rotate secrets periodically
+
+      For more information, visit:
+      https://github.com/kanutocd/rack_jwt_aegis
+    HELP
+  end
+end
+
+# Run CLI if this file is executed directly
+if $PROGRAM_NAME == __FILE__
+  exit_status = 1
+  cli = RackJwtAegisCLI.new
+  begin
+    cli.run
+    exit_status = 0
+  rescue Interrupt
+    puts "\n\n⚠️  Operation cancelled."
+  rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
+    warn "❌ Error: #{e.message}"
+    puts
+    puts "Use 'rack-jwt-aegis --help' for usage information."
+  rescue StandardError => e
+    warn "❌ Error: #{e.message}"
+  end
+  exit exit_status
+end

data/lib/rack_jwt_aegis/configuration.rb

@@ -1,32 +1,176 @@
 # frozen_string_literal: true
 
 module RackJwtAegis
+  # Configuration class for RackJwtAegis middleware
+  #
+  # Manages all configuration options for JWT authentication, multi-tenant validation,
+  # RBAC authorization, and caching behavior.
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 0.1.0
+  #
+  # @example Basic configuration
+  #   config = Configuration.new(jwt_secret: 'your-secret')
+  #
+  # @example Full configuration
+  #   config = Configuration.new(
+  #     jwt_secret: ENV['JWT_SECRET'],
+  #     jwt_algorithm: 'HS256',
+  #     validate_subdomain: true,
+  #     validate_pathname_slug: true,
+  #     rbac_enabled: true,
+  #     cache_store: :redis,
+  #     cache_write_enabled: true,
+  #     skip_paths: ['/health', '/api/public/*'],
+  #     debug_mode: Rails.env.development?
+  #   )
   class Configuration
-    # Core JWT settings
-    attr_accessor :jwt_secret, :jwt_algorithm
+    # @!group Core JWT Settings
 
-    # Feature toggles
-    attr_accessor :validate_subdomain, :validate_company_slug, :rbac_enabled
+    # The secret key used for JWT signature verification
+    # @return [String] the JWT secret key
+    # @note This is required and must not be empty
+    attr_accessor :jwt_secret
 
-    # Multi-tenant settings
-    attr_accessor :company_header_name, :company_slug_pattern, :payload_mapping
+    # The JWT algorithm to use for token verification
+    # @return [String] the JWT algorithm (default: 'HS256')
+    # @note Supported algorithms: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512
+    attr_accessor :jwt_algorithm
 
-    # Path management
+    # @!endgroup
+
+    # @!group Feature Toggles
+
+    # Whether to validate subdomain-based multi-tenancy
+    # @return [Boolean] true if subdomain validation is enabled
+    attr_accessor :validate_subdomain
+
+    # Whether to validate pathname slug-based multi-tenancy
+    # @return [Boolean] true if pathname slug validation is enabled
+    attr_accessor :validate_pathname_slug
+
+    # Whether RBAC (Role-Based Access Control) is enabled
+    # @return [Boolean] true if RBAC is enabled
+    attr_accessor :rbac_enabled
+
+    # @!endgroup
+
+    # @!group Multi-tenant Settings
+
+    # The HTTP header name containing the tenant ID
+    # @return [String] the tenant ID header name (default: 'X-Tenant-Id')
+    attr_accessor :tenant_id_header_name
+
+    # The regular expression pattern to extract pathname slugs
+    # @return [Regexp] the pathname slug pattern (default: /^\/api\/v1\/([^\/]+)\//)
+    attr_accessor :pathname_slug_pattern
+
+    # Mapping of standard payload keys to custom JWT claim names
+    # @return [Hash] the payload mapping configuration
+    # @example
+    #   { user_id: :sub, tenant_id: :company_id, subdomain: :domain }
+    attr_accessor :payload_mapping
+
+    # @!endgroup
+
+    # @!group Path Management
+
+    # Array of paths that should skip JWT authentication
+    # @return [Array<String, Regexp>] paths to skip authentication for
+    # @example
+    #   ['/health', '/api/public', /^\/assets/]
     attr_accessor :skip_paths
 
-    # Cache configuration
-    attr_accessor :cache_store, :cache_options, :cache_write_enabled
-    attr_accessor :rbac_cache_store, :rbac_cache_options, :permission_cache_store, :permission_cache_options
+    # @!endgroup
+
+    # @!group Cache Configuration
+
+    # The primary cache store adapter type
+    # @return [Symbol] the cache store type (:memory, :redis, :memcached, :solid_cache)
+    attr_accessor :cache_store
+
+    # Options passed to the cache store adapter
+    # @return [Hash] cache store configuration options
+    attr_accessor :cache_options
+
+    # Whether the middleware can write to cache stores
+    # @return [Boolean] true if cache writing is enabled
+    attr_accessor :cache_write_enabled
+
+    # The RBAC cache store adapter type (separate from main cache)
+    # @return [Symbol] the RBAC cache store type
+    attr_accessor :rbac_cache_store
+
+    # Options for the RBAC cache store
+    # @return [Hash] RBAC cache configuration options
+    attr_accessor :rbac_cache_options
+
+    # The permission cache store adapter type
+    # @return [Symbol] the permission cache store type
+    attr_accessor :permission_cache_store
 
-    # Custom validators
+    # Options for the permission cache store
+    # @return [Hash] permission cache configuration options
+    attr_accessor :permission_cache_options
+
+    # Time-to-live for user permissions cache in seconds
+    # @return [Integer] TTL in seconds (default: 1800 - 30 minutes)
+    attr_accessor :user_permissions_ttl
+
+    # @!endgroup
+
+    # @!group Custom Validators
+
+    # Custom payload validation proc
+    # @return [Proc] a callable that receives (payload, request) and returns boolean
+    # @example
+    #   ->(payload, request) { payload['role'] == 'admin' }
     attr_accessor :custom_payload_validator
 
-    # Response customization
-    attr_accessor :unauthorized_response, :forbidden_response
+    # @!endgroup
+
+    # @!group Response Customization
 
-    # Development settings
+    # Custom response for unauthorized requests (401)
+    # @return [Hash] the unauthorized response body
+    # @example
+    #   { error: 'Authentication required', code: 'AUTH_001' }
+    attr_accessor :unauthorized_response
+
+    # Custom response for forbidden requests (403)
+    # @return [Hash] the forbidden response body
+    # @example
+    #   { error: 'Access denied', code: 'AUTH_002' }
+    attr_accessor :forbidden_response
+
+    # @!endgroup
+
+    # @!group Development Settings
+
+    # Whether debug mode is enabled for additional logging
+    # @return [Boolean] true if debug mode is enabled
     attr_accessor :debug_mode
 
+    # @!endgroup
+
+    # Initialize a new Configuration instance
+    #
+    # @param options [Hash] configuration options
+    # @option options [String] :jwt_secret (required) JWT secret key for signature verification
+    # @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] :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
+    # @option options [Hash] :payload_mapping mapping of JWT claim names
+    # @option options [Array<String, Regexp>] :skip_paths ([]) paths to skip authentication
+    # @option options [Symbol] :cache_store cache adapter type
+    # @option options [Hash] :cache_options cache configuration options
+    # @option options [Boolean] :cache_write_enabled (false) enable cache writing
+    # @option options [Integer] :user_permissions_ttl (1800) user permissions cache TTL in seconds
+    # @option options [Boolean] :debug_mode (false) enable debug logging
+    # @raise [ConfigurationError] if jwt_secret is missing or configuration is invalid
     def initialize(options = {})
       # Set defaults
       set_defaults
@@ -42,27 +186,39 @@ module RackJwtAegis
       validate!
     end
 
+    # Check if RBAC is enabled
+    # @return [Boolean] true if RBAC is enabled
     def rbac_enabled?
-      config_boolean(rbac_enabled)
+      config_boolean?(rbac_enabled)
     end
 
+    # Check if subdomain validation is enabled
+    # @return [Boolean] true if subdomain validation is enabled
     def validate_subdomain?
-      config_boolean(validate_subdomain)
+      config_boolean?(validate_subdomain)
     end
 
-    def validate_company_slug?
-      config_boolean(validate_company_slug)
+    # Check if pathname slug validation is enabled
+    # @return [Boolean] true if pathname slug validation is enabled
+    def validate_pathname_slug?
+      config_boolean?(validate_pathname_slug)
     end
 
+    # Check if debug mode is enabled
+    # @return [Boolean] true if debug mode is enabled
     def debug_mode?
-      config_boolean(debug_mode)
+      config_boolean?(debug_mode)
     end
 
+    # Check if cache write access is enabled
+    # @return [Boolean] true if cache writing is enabled
     def cache_write_enabled?
-      config_boolean(cache_write_enabled)
+      config_boolean?(cache_write_enabled)
     end
 
-    # Check if path should be skipped
+    # Check if the given path should skip JWT authentication
+    # @param path [String] the request path to check
+    # @return [Boolean] true if the path should be skipped
     def skip_path?(path)
       return false if skip_paths.nil? || skip_paths.empty?
 
@@ -78,7 +234,12 @@ module RackJwtAegis
       end
     end
 
-    # Get mapped payload key
+    # Get the mapped payload key for a standard key
+    # @param standard_key [Symbol] the standard key to map
+    # @return [Symbol] the mapped key from payload_mapping, or the original key if no mapping exists
+    # @example
+    #   config.payload_key(:user_id) #=> :sub (if mapped)
+    #   config.payload_key(:user_id) #=> :user_id (if not mapped)
     def payload_key(standard_key)
       payload_mapping&.fetch(standard_key, standard_key) || standard_key
     end
@@ -86,13 +247,12 @@ module RackJwtAegis
     private
 
     # Convert various falsy/truthy values to proper boolean for configuration
-    def config_boolean(value)
-      return false if value.nil?
-      return false if value == false
-      return false if value == 0
-      return false if value == ''
-      return false if value.is_a?(String) && value.downcase.strip == 'false'
-      
+    def config_boolean?(value)
+      if (value.is_a?(Numeric) && value.zero?) ||
+         (value.is_a?(String) && ['false', '0', '', 'no'].include?(value.downcase.strip))
+        return false
+      end
+
       # Everything else is truthy
       !!value
     end
@@ -100,18 +260,20 @@ module RackJwtAegis
     def set_defaults
       @jwt_algorithm = 'HS256'
       @validate_subdomain = false
-      @validate_company_slug = false
+      @validate_pathname_slug = false
       @rbac_enabled = false
-      @company_header_name = 'X-Company-Group-Id'
-      @company_slug_pattern = %r{^/api/v1/([^/]+)/}
+      @tenant_id_header_name = 'X-Tenant-Id'
+      @pathname_slug_pattern = %r{^/api/v1/([^/]+)/}
       @skip_paths = []
       @cache_write_enabled = false
+      @user_permissions_ttl = 1800 # 30 minutes default
       @debug_mode = false
       @payload_mapping = {
         user_id: :user_id,
-        company_group_id: :company_group_id,
-        company_group_domain: :company_group_domain,
-        company_slugs: :company_slugs,
+        tenant_id: :tenant_id,
+        subdomain: :subdomain,
+        pathname_slugs: :pathname_slugs,
+        role_ids: :role_ids,
       }
       @unauthorized_response = { error: 'Authentication required' }
       @forbidden_response = { error: 'Access denied' }
@@ -119,6 +281,7 @@ module RackJwtAegis
 
     def validate!
       validate_jwt_settings!
+      validate_payload_mapping!
       validate_cache_settings!
       validate_multi_tenant_settings!
     end
@@ -132,6 +295,24 @@ module RackJwtAegis
       raise ConfigurationError, "Unsupported JWT algorithm: #{jwt_algorithm}"
     end
 
+    def validate_payload_mapping!
+      # Allow nil payload_mapping (will use defaults)
+      return if payload_mapping.nil?
+
+      raise ConfigurationError, 'payload_mapping must be a Hash' unless payload_mapping.is_a?(Hash)
+
+      # Validate all values are symbols
+      invalid_values = payload_mapping.reject { |_key, value| value.is_a?(Symbol) }
+      return if invalid_values.empty?
+
+      raise ConfigurationError, "payload_mapping values must be symbols, invalid: #{invalid_values.inspect}"
+
+      # NOTE: We don't validate required keys because users may provide
+      # partial mappings that are intended to override defaults. The payload_key method
+      # handles missing keys by returning the standard key as fallback.
+      # This includes RBAC keys - if :role_ids is not mapped, it falls back to 'role_ids'.
+    end
+
     def validate_cache_settings!
       return unless rbac_enabled?
 
@@ -151,23 +332,23 @@ module RackJwtAegis
       end
 
       # Set default fallback for permission_cache_store when rbac_cache_store is provided
-      if !rbac_cache_store.nil? && permission_cache_store.nil?
-        @permission_cache_store = :memory # Default fallback
-      end
+      return unless !rbac_cache_store.nil? && permission_cache_store.nil?
+
+      @permission_cache_store = :memory # Default fallback
     end
 
     def validate_multi_tenant_settings!
-      if validate_company_slug? && company_slug_pattern.nil?
-        raise ConfigurationError, 'company_slug_pattern is required when validate_company_slug is true'
+      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?(:company_group_domain)
-        raise ConfigurationError, 'payload_mapping must include :company_group_domain when validate_subdomain is true'
+      if validate_subdomain? && !payload_mapping.key?(:subdomain)
+        raise ConfigurationError, 'payload_mapping must include :subdomain when validate_subdomain is true'
       end
 
-      return unless validate_company_slug? && !payload_mapping.key?(:company_slugs)
+      return unless validate_pathname_slug? && !payload_mapping.key?(:pathname_slugs)
 
-      raise ConfigurationError, 'payload_mapping must include :company_slugs when validate_company_slug is true'
+      raise ConfigurationError, 'payload_mapping must include :pathname_slugs when validate_pathname_slug is true'
     end
   end
 end

data/lib/rack_jwt_aegis/debug_logger.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RackJwtAegis
+  # Shared debug logging functionality
+  #
+  # Provides consistent debug logging across all RackJwtAegis components
+  # with configurable log levels and automatic timestamp formatting.
+  #
+  # @author Ken Camajalan Demanawa
+  # @since 1.0.0
+  module DebugLogger
+    # Log debug message if debug mode is enabled
+    #
+    # @param message [String] the message to log
+    # @param level [Symbol] the log level (:info, :warn, :error) (default: :info)
+    # @param component [String] the component name for log prefixing (optional)
+    def debug_log(message, level = :info, component = nil)
+      return unless @config.debug_mode?
+
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+
+      # Determine component name for log prefix
+      component_name = component || infer_component_name
+
+      formatted_message = "[#{timestamp}] #{component_name}: #{message}"
+
+      case level
+      when :error, :warn
+        warn formatted_message
+      else
+        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