rack_jwt_aegis 0.0.0 → 1.0.1

data/lib/rack_jwt_aegis.rb

@@ -2,6 +2,7 @@
 
 require_relative 'rack_jwt_aegis/version'
 require_relative 'rack_jwt_aegis/configuration'
+require_relative 'rack_jwt_aegis/debug_logger'
 require_relative 'rack_jwt_aegis/middleware'
 require_relative 'rack_jwt_aegis/jwt_validator'
 require_relative 'rack_jwt_aegis/multi_tenant_validator'
@@ -10,10 +11,45 @@ require_relative 'rack_jwt_aegis/cache_adapter'
 require_relative 'rack_jwt_aegis/request_context'
 require_relative 'rack_jwt_aegis/response_builder'
 
+# @author Ken Camajalan Demanawa
+# @since 0.1.0
+#
+# RackJwtAegis is a comprehensive JWT authentication and authorization middleware for Rack applications.
+# It provides multi-tenant support, RBAC (Role-Based Access Control), and caching capabilities.
+#
+# Features:
+# - JWT token validation with configurable algorithms
+# - Multi-tenant validation (subdomain and pathname slug based)
+# - RBAC with flexible permission caching
+# - Multiple cache adapter support (Memory, Redis, Memcached, SolidCache)
+# - Request context management
+# - Configurable skip paths and custom validators
+#
+# @example Basic usage
+#   use RackJwtAegis::Middleware, jwt_secret: ENV['JWT_SECRET']
+#
+# @example Multi-tenant with RBAC
+#   use RackJwtAegis::Middleware, {
+#     jwt_secret: ENV['JWT_SECRET'],
+#     validate_subdomain: true,
+#     validate_pathname_slug: true,
+#     rbac_enabled: true,
+#     cache_store: :redis,
+#     cache_write_enabled: true
+#   }
 module RackJwtAegis
+  # Base error class for all RackJwtAegis exceptions
   class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing required parameters
   class ConfigurationError < Error; end
+
+  # Raised when JWT authentication fails
   class AuthenticationError < Error; end
+
+  # Raised when authorization/permission checks fail
   class AuthorizationError < Error; end
+
+  # Raised when cache operations fail
   class CacheError < Error; end
-end
+end

metadata

@@ -1,29 +1,34 @@
 --- !ruby/object:Gem::Specification
 name: rack_jwt_aegis
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Ken C. Demanawa
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-08-10 00:00:00.000000000 Z
+date: 1980-01-02 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'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -38,23 +43,32 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.2'
-description: JWT authentication middleware with multi-tenant support, company validation,
-  and subdomain isolation.
+description: |-
+  JWT authentication midleware with multi-tenant suport,\
+   company validation, and subdomain isolation.
 email:
 - kenneth.c.demanawa@gmail.com
-executables: []
+executables:
+- rack_jwt_aegis
 extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".yard/yard_gfm_config.rb"
+- ".yardopts"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- examples/basic_usage.rb
+- bin/console
+- bin/docs
+- bin/setup
+- exe/rack_jwt_aegis
 - lib/rack_jwt_aegis.rb
 - lib/rack_jwt_aegis/cache_adapter.rb
 - lib/rack_jwt_aegis/configuration.rb
+- lib/rack_jwt_aegis/debug_logger.rb
 - lib/rack_jwt_aegis/jwt_validator.rb
 - lib/rack_jwt_aegis/middleware.rb
 - lib/rack_jwt_aegis/multi_tenant_validator.rb
@@ -62,7 +76,7 @@ files:
 - 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
+- sig/rack_jwt_aegis.rbs
 homepage: https://github.com/kanutocd/rack_jwt_aegis
 licenses:
 - MIT
@@ -71,7 +85,6 @@ metadata:
   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
@@ -86,8 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: JWT authentication middleware for multi-tenant Rack applications
 test_files: []

data/examples/basic_usage.rb

@@ -1,85 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require_relative '../lib/rack_jwt_aegis'
-require 'jwt'
-require 'json'
-require 'rack'
-
-# Example: Basic JWT authentication middleware usage
-
-# 1. Create a simple Rack app
-class SimpleApp
-  def call(env)
-    # Access authenticated user data
-    if RackJwtAegis::RequestContext.authenticated?(env)
-      user_id = RackJwtAegis::RequestContext.user_id(env)
-      company_slugs = RackJwtAegis::RequestContext.company_slugs(env)
-
-      response = {
-        message: 'Hello authenticated user!',
-        user_id: user_id,
-        company_access: company_slugs,
-      }
-
-      [200, { 'Content-Type' => 'application/json' }, [JSON.generate(response)]]
-    else
-      [401, {}, ['Unauthorized']]
-    end
-  end
-end
-
-# 2. Configure the middleware
-Rack::Builder.new do
-  use RackJwtAegis::Middleware, {
-    jwt_secret: 'demo-secret-key',
-
-    # Multi-tenant features
-    validate_subdomain: true,
-    validate_company_slug: true,
-
-    # Skip authentication for health check
-    skip_paths: ['/health'],
-
-    # Debug mode for demonstration
-    debug_mode: true,
-  }
-
-  run SimpleApp.new
-end
-
-# 3. Generate a demo JWT token
-payload = {
-  'user_id' => 123,
-  'company_group_id' => 456,
-  'company_group_domain' => 'acme-corp.example.com',
-  'company_slugs' => ['widgets-division', 'services-division'],
-  'exp' => Time.now.to_i + 3600, # 1 hour from now
-}
-
-token = JWT.encode(payload, 'demo-secret-key', 'HS256')
-
-puts "\n🛡️  Rack JWT Aegis Demo"
-puts '=' * 50
-puts "\n📋 Configuration:"
-puts '- JWT Secret: demo-secret-key'
-puts '- Multi-tenant: Subdomain + Company Slug validation'
-puts '- Skip paths: /health'
-puts '- Debug mode: enabled'
-
-puts "\n🎫 Generated JWT Token:"
-puts "#{token[0..50]}..." if token.length > 50
-
-puts "\n📊 JWT Payload:"
-puts JSON.pretty_generate(payload)
-
-puts "\n✅ Middleware initialized successfully!"
-puts "\n💡 To test this middleware:"
-puts '1. Start a Rack server with this configuration'
-puts '2. Send requests with Authorization: Bearer <token>'
-puts '3. Try different subdomains and company slugs'
-puts '4. Check /health endpoint (should work without auth)'
-
-puts "\n📝 Example curl commands:"
-puts "curl -H 'Authorization: Bearer #{token}' -H 'Host: acme-corp.example.com' http://localhost:3000/api/v1/widgets-division/data"
-puts 'curl http://localhost:3000/health'