jwt_auth_cognito 0.3.0 → 1.0.0.pre.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f8b72ffb2724513f2e4080cf6d3eef3282b860267763833c3d4f3e230168c80
-  data.tar.gz: 5f396ae6b180d33d720f59f51ef99d7cf5e42496d10d49a9a38b7a413071ee43
+  metadata.gz: 9296db47172be874a7d6204b54c3e5fc8de7f77a77a7e02f4b1d8d4b70bc9b8d
+  data.tar.gz: 55a4df3b1c9077b9803508ac925715510af9974ef79c40ed097cc0a86eb5b7a3
 SHA512:
-  metadata.gz: 81919186799b227f0816a4087a2bd879e4eceda071f985a26cf58954d0b80e15a546b907ca0b94e1f9ad0ce4f24f74b9ef7b10cd34599b5990f1bc3bd44b550d
-  data.tar.gz: 8aae5fbc4429541677ef8cd37437db596674d882841b1f09fe2b0130d9550945ab0293495a36be839ad4c3aee277fb97cb69e19e66fc9bb4e1845e9c8f3aedbf
+  metadata.gz: 19b0aa21809ac6d94c74e358d48d30b4246836610eff67121f41368552a6c385696952aec47a5bb8291c9141e6e0c1de398a028679f1fb05c8a3c71904d58446
+  data.tar.gz: 4cff441b707184fab34cc16f8368ae67334b8aad174f28b2c1649292a7d2b0b99ad66d60920ef9d503c95a162cd01e2ae621081e0129f38f3dc11c95f40c810c

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Improved
+
+- **Documentation Enhancement**: Added Redis configuration documentation to main usage patterns
+  - Updated README.md with complete Redis connection setup in factory method
+  - Enhanced CLAUDE.md with Redis configuration in the main usage pattern
+  - Improved clarity on how to connect Redis for token blacklisting and user data enrichment
+
 ## [0.3.0] - 2024-01-15
 
 ### Added

data/CLAUDE.md

@@ -145,6 +145,50 @@ ENV['REDIS_CA_CERT'] = "-----BEGIN CERTIFICATE-----..."
 - **Backward Compatibility**: All functionality works without client secret configuration
 - **Security Integration**: Secret hash automatically included in blacklist operations when configured
 
+## 🚀 Main Usage Pattern with Redis Connection
+
+### ✨ Complete Setup with Redis Connection
+
+```ruby
+# Create validator with Redis connection for blacklist and user data
+validator = JwtAuthCognito.create_cognito_validator(
+  region: 'us-east-1',
+  user_pool_id: 'us-east-1_ExamplePool',
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret', # Optional
+  redis_config: {
+    # Redis configuration for token blacklisting and user data enrichment
+    host: ENV['REDIS_HOST'] || 'localhost',
+    port: ENV['REDIS_PORT']&.to_i || 6379,
+    password: ENV['REDIS_PASSWORD'],
+    db: ENV['REDIS_DB']&.to_i || 0,
+
+    # TLS configuration for secure connections
+    tls: ENV['REDIS_TLS'] == 'true',
+    ca_cert_path: ENV['REDIS_CA_CERT_PATH'],
+    ca_cert_name: ENV['REDIS_CA_CERT_NAME'],
+    verify_mode: ENV['REDIS_VERIFY_MODE'] || 'peer'
+  },
+  enable_user_data_retrieval: true
+)
+
+# Initialize Redis connection and services
+validator.initialize!
+
+# 🌟 Main validation method with complete functionality
+result = validator.validate_token_enriched(token)
+
+if result[:valid]
+  puts "✅ Valid token:"
+  puts "User: #{result[:sub]}"
+  puts "Permissions: #{result[:user_permissions]}"
+  puts "Organizations: #{result[:user_organizations]}"
+  puts "Applications: #{result[:applications]}"
+else
+  puts "❌ Invalid token: #{result[:error]}"
+end
+```
+
 ## Environment Configuration
 
 The gem supports extensive environment variable configuration for deployment flexibility:
@@ -152,7 +196,7 @@ The gem supports extensive environment variable configuration for deployment fle
 ### AWS Cognito Configuration
 ```bash
 COGNITO_REGION=us-east-1
-COGNITO_USER_POOL_ID=us-east-1_AbCdEfGhI  
+COGNITO_USER_POOL_ID=us-east-1_AbCdEfGhI
 COGNITO_CLIENT_ID=your-client-id
 COGNITO_CLIENT_SECRET=your-client-secret  # Optional for enhanced security
 ```

data/README.md

@@ -162,21 +162,41 @@ end
 ### Factory Method para Configuración Simplificada (Nuevo v0.3.0)
 
 ```ruby
-# Crear validador con una línea
+# Crear validador con conexión Redis completa
 validator = JwtAuthCognito.create_cognito_validator(
   region: 'us-east-1',
   user_pool_id: 'us-east-1_ExamplePool',
   client_id: 'your-client-id',
   redis_config: {
-    host: 'localhost',
-    port: 6379,
-    tls: true
+    # Configuración básica de Redis
+    host: ENV['REDIS_HOST'] || 'localhost',
+    port: ENV['REDIS_PORT']&.to_i || 6379,
+    password: ENV['REDIS_PASSWORD'],
+    db: ENV['REDIS_DB']&.to_i || 0,
+
+    # Configuración TLS para conexiones seguras
+    tls: ENV['REDIS_TLS'] == 'true',
+    ca_cert_path: ENV['REDIS_CA_CERT_PATH'],
+    ca_cert_name: ENV['REDIS_CA_CERT_NAME']
   },
   enable_user_data_retrieval: true
 )
 
-# Usar inmediatamente
+# Inicializar conexiones (incluye Redis)
+validator.initialize!
+
+# Usar inmediatamente con validación enriquecida
 result = validator.validate_token_enriched(token)
+
+if result[:valid]
+  puts "✅ Token válido con datos enriquecidos:"
+  puts "Usuario: #{result[:sub]}"
+  puts "Permisos: #{result[:user_permissions]}"
+  puts "Organizaciones: #{result[:user_organizations]}"
+  puts "Aplicaciones: #{result[:applications]}"
+else
+  puts "❌ Token inválido: #{result[:error]}"
+end
 ```
 
 ### Manejo Mejorado de Errores (Nuevo v0.3.0)

data/bitbucket-pipelines.yml

@@ -125,12 +125,11 @@ pipelines:
     # Tags stable (X.Y.Z)
     "v[0-9]*.[0-9]*.[0-9]*":
       - step:
-          name: Deploy Estable a RubyGems
-          trigger: manual  # Requiere confirmación manual
+          name: Tests y Build para Deploy Estable
           caches:
             - bundler
           script:
-            - echo "🚨 DEPLOY DE PRODUCCIÓN - Versión estable"
+            - echo "🚨 Preparando versión estable para deploy"
             - bundle install
             - echo "Tests completos y exhaustivos..."
             - bundle exec rspec
@@ -140,6 +139,16 @@ pipelines:
             - bundle audit check --update || echo "Bundle audit no disponible, continuando..."
             - echo "Building gem final..."
             - gem build jwt_auth_cognito.gemspec
+            - echo "Build completado - Listo para deploy manual"
+          artifacts:
+            - "*.gem"
+      - step:
+          name: Deploy Estable a RubyGems
+          trigger: manual  # Requiere confirmación manual para el deploy
+          caches:
+            - bundler
+          script:
+            - echo "🚨 DEPLOY DE PRODUCCIÓN - Versión estable"
             - echo "Configurando credenciales RubyGems..."
             - mkdir -p ~/.gem
             - 'echo ":rubygems_api_key: $RUBYGEMS_API_KEY" > ~/.gem/credentials'
@@ -147,8 +156,6 @@ pipelines:
             - echo "Publicando version ESTABLE a RubyGems..."
             - gem push *.gem
             - echo "VERSION ESTABLE PUBLICADA EXITOSAMENTE"
-          artifacts:
-            - "*.gem"
 
     # Tags alpha (X.Y.Z-alpha.N) - Solo para testing
     "v*-alpha.*":

data/lib/jwt_auth_cognito/jwt_validator.rb

@@ -27,14 +27,24 @@ module JwtAuthCognito
       end
     end
 
-    def validate_token(token, options = {})
-      validate_token_with_api_key(token, nil, options)
-    end
-
-    def validate_token_with_api_key(token, api_key = nil, options = {})
+    # ========== 🚀 MAIN VALIDATION METHOD ==========
+
+    # Main validation method - use this for most cases
+    # Intelligently validates tokens with all features:
+    # - JWT validation (basic or secure)
+    # - API key validation (if provided)
+    # - Blacklist checking
+    # - Automatic appId verification
+    # - User data enrichment (if enabled)
+    def validate(token, options = {})
       @config.validate!
 
-      # Validate API key if provided and enabled
+      api_key = options[:api_key]
+      force_secure = options[:force_secure] || false
+      enrich_user_data = options.fetch(:enrich_user_data, true)
+      require_app_access = options[:require_app_access] || false
+
+      # Step 1: Validate API key if provided
       api_key_data = nil
       if api_key && @config.enable_api_key_validation && @api_key_validator
         api_key_result = @api_key_validator.validate_api_key(api_key)
@@ -43,26 +53,129 @@ module JwtAuthCognito
         api_key_data = api_key_result[:key_data]
       end
 
-      # Check blacklist first
+      # Step 2: Check blacklist first
       return { valid: false, error: 'Token has been revoked' } if @blacklist_service.is_blacklisted?(token)
 
-      # Choose validation method based on configuration
-      result = case @config.validation_mode
-               when :secure
-                 validate_token_secure(token, options)
-               when :basic
-                 validate_token_basic(token, options)
-               else
-                 raise ConfigurationError, "Invalid validation_mode: #{@config.validation_mode}"
-               end
+      # Step 3: Validate JWT token
+      validation_mode = force_secure ? :secure : @config.validation_mode
+      token_result = case validation_mode
+                     when :secure
+                       validate_token_secure(token, options)
+                     when :basic
+                       validate_token_basic(token, options)
+                     else
+                       raise ConfigurationError, "Invalid validation_mode: #{validation_mode}"
+                     end
+
+      return token_result unless token_result[:valid] && token_result[:payload]
+
+      # Step 4: Verify appId access if API key has one
+      if api_key_data
+        app_validation = verify_app_access(api_key_data, token_result[:payload], require_app_access)
+        return app_validation unless app_validation[:valid]
+      end
 
-      # Add API key data to result if validation succeeded
-      result[:api_key] = api_key_data if result[:valid] && api_key_data
+      # Step 5: Enrich with user data if requested
+      enriched_result = token_result.dup
+      enriched_result[:api_key] = api_key_data if api_key_data
+
+      if enrich_user_data && @config.enable_user_data_retrieval && @user_data_service
+        user_id = token_result[:payload]['sub']
+        if user_id
+          begin
+            user_data = @user_data_service.get_comprehensive_user_data(user_id)
+            enriched_result[:user_permissions] = user_data['permissions']
+            enriched_result[:user_organizations] = user_data['organizations']
+            enriched_result[:applications] = user_data['applications']
+          rescue StandardError => e
+            ErrorUtils.log_error(e, 'User data retrieval failed')
+            # Continue with basic validation if user data service fails
+          end
+        end
+      end
 
-      result
+      enriched_result
+    end
+
+    # ========== SIMPLIFIED PUBLIC API ==========
+
+    # Quick validation for simple use cases
+    # Just validates the JWT token (includes blacklist check)
+    def validate_token(token, options = {})
+      result = validate(token, options.merge(enrich_user_data: false))
+      {
+        valid: result[:valid],
+        payload: result[:payload],
+        sub: result[:sub],
+        username: result[:username],
+        token_use: result[:token_use],
+        error: result[:error]
+      }
+    end
+
+    # Validate with API key (automatic appId verification)
+    # Use this when you have an API key and want automatic security
+    def validate_with_api_key(token, api_key, options = {})
+      validate(token, options.merge(api_key: api_key))
+    end
+
+    # Validate with strict appId requirement
+    # Use this when you MUST ensure user has access to a specific app
+    def validate_with_app_access(token, api_key, options = {})
+      validate(token, options.merge(api_key: api_key, require_app_access: true))
+    end
+
+    # Get enriched validation (user data included)
+    # Use this when you need user permissions, organizations, apps
+    def validate_enriched(token, api_key = nil, options = {})
+      validate(token, options.merge(api_key: api_key, enrich_user_data: true))
+    end
+
+    # ========== LEGACY METHODS (DEPRECATED) ==========
+
+    # @deprecated Use validate() or validate_with_api_key() instead
+    def validate_token_with_api_key(token, api_key = nil, options = {})
+      puts 'WARNING: validate_token_with_api_key is deprecated. Use validate() or validate_with_api_key() instead.'
+      result = validate(token, options.merge(api_key: api_key, enrich_user_data: false))
+      {
+        valid: result[:valid],
+        payload: result[:payload],
+        sub: result[:sub],
+        username: result[:username],
+        token_use: result[:token_use],
+        api_key: result[:api_key],
+        error: result[:error]
+      }
     end
 
+    # @deprecated Use validate_with_app_access() instead
+    def validate_token_with_app_id(token, api_key, options = {})
+      puts 'WARNING: validate_token_with_app_id is deprecated. Use validate_with_app_access() instead.'
+      validate_with_app_access(token, api_key, options.merge(enrich_user_data: false))
+    end
+
+    # @deprecated Use validate() instead
+    def validate_token_enhanced(token, api_key = nil, options = {})
+      puts 'WARNING: validate_token_enhanced is deprecated. Use validate() instead.'
+      result = validate(token, options.merge(api_key: api_key, enrich_user_data: false))
+      {
+        valid: result[:valid],
+        payload: result[:payload],
+        sub: result[:sub],
+        username: result[:username],
+        token_use: result[:token_use],
+        api_key: result[:api_key],
+        error: result[:error]
+      }
+    end
+
+    # @deprecated Use validate_enriched() instead
     def validate_token_enriched(token, api_key = nil, options = {})
+      puts 'WARNING: validate_token_enriched is deprecated. Use validate_enriched() instead.'
+      validate_enriched(token, api_key, options)
+    end
+
+    def old_validate_token_enriched(token, api_key = nil, options = {})
       # First, perform standard token validation
       basic_result = validate_token_with_api_key(token, api_key, options)
 
@@ -299,5 +412,41 @@ module JwtAuthCognito
 
       raise ValidationError, "Token missing required scopes: #{missing_scopes.join(', ')}"
     end
+
+    def verify_app_access(api_key_data, payload, require_app_access)
+      app_id = api_key_data['appId'] || api_key_data['metadata']&.[]('appId')
+
+      return { valid: false, error: 'API key is not associated with an application' } if !app_id && require_app_access
+
+      return { valid: true } unless app_id
+
+      user_id = payload['sub']
+      return { valid: false, error: 'Token missing user ID (sub claim)' } unless user_id
+
+      verify_user_app_access(user_id, app_id, require_app_access)
+    end
+
+    def verify_user_app_access(user_id, app_id, require_app_access)
+      if require_app_access && (!@config.enable_user_data_retrieval || !@user_data_service)
+        return { valid: false,
+                 error: 'User data service not available for application access verification' }
+      end
+
+      return { valid: true } unless @config.enable_user_data_retrieval && @user_data_service
+
+      begin
+        user_applications = @user_data_service.get_user_applications(user_id)
+        has_access = user_applications.any? { |app| app['appId'] == app_id }
+
+        return { valid: false, error: "User does not have access to application #{app_id}" } unless has_access
+
+        { valid: true }
+      rescue StandardError => e
+        return { valid: false, error: 'Could not verify application access' } if require_app_access
+
+        ErrorUtils.log_error(e, 'User application access verification failed')
+        { valid: true } # Continue with basic validation if user data service fails
+      end
+    end
   end
 end

data/lib/jwt_auth_cognito/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JwtAuthCognito
-  VERSION = '0.3.0'
+  VERSION = '1.0.0-beta.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jwt_auth_cognito
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0.pre.beta.2
 platform: ruby
 authors:
 - The Optimal
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-12 00:00:00.000000000 Z
+date: 2025-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-ssm
@@ -237,9 +237,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.27
 signing_key: