jwt_auth_cognito 0.1.0 → 0.3.0

data/CLAUDE.md

@@ -23,9 +23,12 @@ bundle exec rspec spec/jwt_auth_cognito/configuration_spec.rb
 
 # Test basic functionality
 ruby examples/simple_test.rb
+
+# Test SSM certificate functionality
+ruby examples/test_installation.rb
 ```
 
-### Gem Management
+### Gem Management and Versioning
 ```bash
 # Build the gem
 gem build jwt_auth_cognito.gemspec
@@ -34,7 +37,22 @@ gem build jwt_auth_cognito.gemspec
 bundle exec rake install
 
 # Test gem packaging
-gem contents jwt_auth_cognito-0.1.0.gem
+gem contents jwt_auth_cognito-0.2.0.gem
+
+# Version management (Git Flow compatible)
+rake version:alpha    # Create alpha version from feature branches
+rake version:beta     # Create beta version from develop branch
+rake version:rc       # Create release candidate from release branches
+
+# Full release process
+rake release:develop  # Beta release (develop branch)
+rake release:rc       # Release candidate
+rake release:stable   # Stable release (requires confirmation)
+
+# Direct publishing
+rake publish:beta     # Build and publish beta version
+rake publish:rc       # Build and publish RC version
+rake publish:stable   # Build and publish stable (requires confirmation)
 ```
 
 ### Configuration Generation
@@ -52,33 +70,75 @@ rake jwt_auth_cognito:test_cognito # Test Cognito connection
 ## Architecture Overview
 
 ### Core Components
-- **JwtValidator**: Main validation orchestrator that coordinates JWKS validation and blacklist checking
+- **JwtValidator**: Main validation orchestrator that coordinates JWKS validation, blacklist checking, and user data retrieval
 - **JwksService**: Handles AWS Cognito JWKS fetching, caching, and signature validation
 - **RedisService**: Low-level Redis operations with comprehensive TLS support and retry logic
 - **TokenBlacklistService**: High-level token revocation and blacklist management
+- **UserDataService**: User data retrieval from Redis with caching and auth-service compatibility
+- **ErrorUtils**: Centralized error handling and categorization system
+- **SSMService**: AWS Parameter Store integration for secure certificate management (auth-service compatible)
 - **Configuration**: Centralized configuration with environment variable fallbacks
 
 ### Key Design Patterns
 
-**Service Layer Architecture**: Each major functionality (JWT validation, JWKS handling, Redis operations, blacklisting) is isolated into dedicated service classes that can be used independently or orchestrated through JwtValidator.
+**Service Layer Architecture**: Each major functionality (JWT validation, JWKS handling, Redis operations, blacklisting, user data retrieval) is isolated into dedicated service classes that can be used independently or orchestrated through JwtValidator.
 
 **Configuration Management**: Dual configuration approach supporting both programmatic configuration and environment variables, with automatic fallback chain for maximum flexibility.
 
-**Error Hierarchy**: Comprehensive error types that mirror the Node.js implementation for consistency across implementations.
+**Error Hierarchy**: Comprehensive error types with centralized ErrorUtils for consistent error handling and user-friendly messages.
 
 **Compatibility Layer**: Designed to match the API and behavior of the Node.js auth package, ensuring consistent functionality across language implementations.
 
+**Caching Strategy**: Multi-layer caching (JWKS cache + UserData cache) with configurable TTL and intelligent cache invalidation.
+
 ### Redis Architecture
 - **Connection Management**: Single connection with comprehensive TLS support including certificate validation
+- **Certificate Loading**: Multi-source certificate loading (SSM → File → Environment) for maximum flexibility
 - **Retry Logic**: Exponential backoff for failed operations
 - **Blacklist Strategy**: Uses Redis sets with automatic TTL management for token revocation
 - **User Token Tracking**: Maintains user-to-tokens mapping for bulk revocation capabilities
 
+### ✅ **SSM Parameter Store Integration** - NEW December 2024
+
+**Complete auth-service compatibility for certificate management:**
+
+```ruby
+# Priority order for certificate loading:
+# 1. AWS SSM Parameter Store (for auth-service compatibility)
+# 2. Local file system
+# 3. Environment variable
+
+# SSM configuration (matching auth-service pattern)
+config.redis_ca_cert_ssm_path = "certificates"     # SSM path segment
+config.redis_ca_cert_ssm_name = "redis-ca.pem"     # Certificate name
+# Results in SSM parameter: /certificates/redis-ca.pem
+
+# Automatic fallback to file system
+config.redis_ca_cert_path = "/path/to/certs"
+config.redis_ca_cert_name = "ca.pem"
+
+# Environment variable fallback
+ENV['REDIS_CA_CERT'] = "-----BEGIN CERTIFICATE-----..."
+```
+
 ### JWT Validation Flow
 1. **Structure Validation**: Basic JWT format and claims validation
 2. **Blacklist Check**: Fast Redis lookup for revoked tokens
 3. **JWKS Validation**: Signature verification against Cognito public keys (secure mode only)
 4. **Claims Validation**: Audience, issuer, expiration, and custom claims validation
+5. **User Data Enrichment** (optional): Retrieval of user permissions, organizations, and applications
+
+### UserDataService Architecture
+- **Redis Key Patterns**: Compatible with auth-service patterns
+  - `user:permissions:{userId}` - User permission data
+  - `app:{appId}` - Application metadata
+  - `org:{appId}:{organizationId}` - Organization data
+  - `app:roles:{appId}:{organizationId}` - Role definitions
+  - `app-schemas` - Application schema definitions
+  - `permissions:cache:{userId}:{appId}:{orgId}` - Effective permissions cache
+- **Caching Strategy**: In-memory cache with configurable TTL per data type
+- **Data Composition**: Intelligent composition of user organizations with role and permission data
+- **Graceful Degradation**: Service continues operation even if user data retrieval fails
 
 ### Client Secret Support
 - **Optional Enhancement**: HMAC-SHA256 secret hash calculation matching AWS Cognito requirements
@@ -89,9 +149,69 @@ rake jwt_auth_cognito:test_cognito # Test Cognito connection
 
 The gem supports extensive environment variable configuration for deployment flexibility:
 
-- `COGNITO_*` variables for AWS Cognito settings
-- `REDIS_*` variables for Redis connection and TLS configuration  
-- `JWKS_CACHE_TTL` for caching behavior
+### AWS Cognito Configuration
+```bash
+COGNITO_REGION=us-east-1
+COGNITO_USER_POOL_ID=us-east-1_AbCdEfGhI  
+COGNITO_CLIENT_ID=your-client-id
+COGNITO_CLIENT_SECRET=your-client-secret  # Optional for enhanced security
+```
+
+### Redis Configuration
+```bash
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=your-password
+REDIS_DB=0
+REDIS_TLS=true  # Enable TLS connection
+REDIS_TIMEOUT=5
+REDIS_CONNECT_TIMEOUT=10
+REDIS_READ_TIMEOUT=10
+```
+
+### TLS/SSL Certificate Configuration
+```bash
+# AWS SSM Parameter Store (recommended for auth-service compatibility)
+REDIS_CA_CERT_SSM_PATH=certificates
+REDIS_CA_CERT_SSM_NAME=redis-ca.pem
+
+# Local file system fallback
+REDIS_CA_CERT_PATH=/path/to/certs
+REDIS_CA_CERT_NAME=ca.pem
+
+# Direct certificate content fallback
+REDIS_CA_CERT="-----BEGIN CERTIFICATE-----..."
+
+# TLS settings
+REDIS_VERIFY_MODE=peer  # 'peer' or 'none'
+REDIS_TLS_MIN_VERSION=TLSv1.2
+REDIS_TLS_MAX_VERSION=TLSv1.3
+```
+
+### AWS Configuration (for SSM)
+```bash
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+# Or use IAM roles/instance profiles
+```
+
+### User Data Service Configuration
+```bash
+# User data retrieval settings
+ENABLE_USER_DATA_RETRIEVAL=true
+INCLUDE_APPLICATIONS=true
+INCLUDE_ORGANIZATIONS=true
+INCLUDE_ROLES=true
+INCLUDE_EFFECTIVE_PERMISSIONS=false
+USER_DATA_CACHE_TIMEOUT=300  # 5 minutes
+```
+
+### Caching and Performance
+```bash
+JWKS_CACHE_TTL=3600  # 1 hour
+```
+
 - Automatic Rails environment detection for validation mode selection
 
 ## Rails Integration
@@ -121,6 +241,17 @@ The gem supports extensive environment variable configuration for deployment fle
 
 ## Version Compatibility
 
+### ✅ **Updated January 2025 - Version 0.3.0**
+
+**Major feature expansion with UserDataService and deployment automation**
+
+- ✅ UserDataService with auth-service compatibility
+- ✅ Enhanced error handling with ErrorUtils
+- ✅ Enriched token validation with user context
+- ✅ Automated CI/CD pipeline with Bitbucket
+- ✅ Synchronized feature set with Node.js package (maintaining independent versioning)
+- ✅ Maintains consistent API across language implementations
+
 Designed for compatibility with legacy Rails applications:
 - **Ruby**: >= 2.7.0 (compatible with llegando-neo Ruby 2.7.5)
 - **Rails**: >= 5.0 (compatible with llegando-neo Rails 5.2.6) 
@@ -128,8 +259,57 @@ Designed for compatibility with legacy Rails applications:
 
 ## Publishing and Distribution
 
+### Automated CI/CD Pipeline
+
+The gem uses Bitbucket Pipelines for automated deployment to RubyGems.org:
+
+#### Pipeline Configuration
+- **Beta releases** (`v*-beta.*`): Automatic deployment
+- **RC releases** (`v*-rc.*`): Automatic deployment  
+- **Stable releases** (`v[0-9]*.*`): Manual deployment with confirmation
+- **Testing**: Automated on all branches with comprehensive test suite
+
+#### Deployment Commands
+
+#### Automatic Beta Deployment (Recommended)
+```bash
+# Simply merge/push to develop - automatic beta deployment
+git checkout develop
+git merge feature/your-feature
+git push origin develop
+# → Pipeline automatically creates and publishes beta version
+```
+
+#### Manual Tag Deployment (Alternative)
+```bash
+# Beta release
+git tag v0.3.0-beta.1 && git push origin v0.3.0-beta.1
+
+# RC release
+git tag v0.3.0-rc.1 && git push origin v0.3.0-rc.1
+
+# Stable release
+git tag v0.3.0 && git push origin v0.3.0
+```
+
+#### Helper Scripts
+- `scripts/generate_rubygems_token.rb`: Generate RubyGems API key instructions
+- `scripts/test_rubygems_token.rb`: Validate local token configuration
+- `scripts/deployment_helper.rb`: Complete deployment assistant
+- `scripts/setup_rubygems_deployment.md`: Detailed deployment documentation
+
+#### Manual Pipelines (Bitbucket)
+- `full-release-beta`: Complete beta release with versioning
+- `full-release-rc`: Complete RC release with versioning
+- `full-release-stable`: Complete stable release (requires confirmation)
+- `test-build`: Build testing without deployment
+
+### Gem Metadata
 The gem is prepared for RubyGems.org publication with:
 - Complete gemspec with metadata
 - Proper file inclusion patterns
 - Version compatibility constraints
-- MIT license and documentation
+- MIT license and comprehensive documentation
+- Automated deployment pipeline
+- Security best practices for token management
+- actualiza los archivos de documentación cada vez que se haga un cambio si es necesario

data/Gemfile

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
-gem "rubocop", "~> 1.21"
-gem "webmock", "~> 3.0"
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.21'
+gem 'webmock', '~> 3.0'

data/README.md

@@ -10,7 +10,9 @@ Una gema Ruby para validar tokens JWT de AWS Cognito de forma offline con funcio
 - **Configuración Flexible**: Soporte para modos de validación seguro (producción) y básico (desarrollo)
 - **Gestión de Tokens de Usuario**: Rastrear e invalidar todos los tokens de un usuario específico
 - **Múltiples Tipos de Token**: Soporte para access tokens e ID tokens
-- **Manejo Integral de Errores**: Degradación elegante cuando Redis no está disponible
+- **UserDataService**: Recuperación de datos de usuario, permisos y organizaciones desde Redis
+- **Validación Enriquecida**: Validación de tokens con datos contextuales del usuario
+- **Manejo Integral de Errores**: Degradación elegante y manejo consistente de errores
 - **Soporte TLS Avanzado**: Configuración completa de TLS para Redis con certificados CA
 
 ## Instalación
@@ -120,6 +122,81 @@ result = validator.validate_access_token(jwt_token)
 result = validator.validate_id_token(jwt_token)
 ```
 
+### Validación Enriquecida con UserDataService (Nuevo v0.3.0)
+
+```ruby
+# Configurar UserDataService
+JwtAuthCognito.configure do |config|
+  # ... configuración básica ...
+  config.enable_user_data_retrieval = true
+end
+
+validator = JwtAuthCognito::JwtValidator.new
+validator.initialize! # Inicializar servicios
+
+# Validación enriquecida con datos de usuario desde Redis
+result = validator.validate_token_enriched(jwt_token)
+
+if result[:valid]
+  puts "Token válido!"
+  puts "Usuario: #{result[:sub]}"
+  
+  # Datos adicionales del usuario
+  if result[:user_permissions]
+    puts "Apps con permisos: #{result[:user_permissions]['permissions'].keys}"
+  end
+  
+  if result[:user_organizations]&.any?
+    puts "Organizaciones activas:"
+    result[:user_organizations].each do |org|
+      puts "  - #{org['organizationId']} (roles: #{org['roles'].join(', ')})"
+    end
+  end
+  
+  if result[:applications]&.any?
+    puts "Aplicaciones disponibles: #{result[:applications].map { |app| app['name'] }.join(', ')}"
+  end
+end
+```
+
+### Factory Method para Configuración Simplificada (Nuevo v0.3.0)
+
+```ruby
+# Crear validador con una línea
+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
+  },
+  enable_user_data_retrieval: true
+)
+
+# Usar inmediatamente
+result = validator.validate_token_enriched(token)
+```
+
+### Manejo Mejorado de Errores (Nuevo v0.3.0)
+
+```ruby
+begin
+  result = validator.validate_token(token)
+rescue => error
+  # ErrorUtils proporciona mensajes consistentes
+  error_details = JwtAuthCognito::ErrorUtils.extract_error_details(error)
+  
+  puts "Error: #{error_details[:message]}"
+  puts "Código: #{error_details[:code]}" if error_details[:code]
+  
+  # Para APIs - respuesta estandarizada
+  api_response = JwtAuthCognito::ErrorUtils.format_validation_error(error)
+  # Retorna: { valid: false, error: "mensaje", error_code: "CODIGO" }
+end
+```
+
 ### Opciones Avanzadas de Validación
 
 ```ruby
@@ -382,3 +459,72 @@ Esto generará automáticamente:
 - `config/initializers/jwt_auth_cognito.rb` - Archivo de configuración
 - `.env.example` - Variables de entorno de ejemplo
 - Configuración optimizada para tu proyecto Rails
+
+## Deployment y CI/CD
+
+### Configuración de Deployment Automático
+
+Este gem utiliza Bitbucket Pipelines para deployment automático a RubyGems.org:
+
+#### 1. Configurar Token de RubyGems
+
+```bash
+# Obtener instrucciones para el token
+ruby scripts/generate_rubygems_token.rb
+
+# Probar configuración local (opcional)
+export RUBYGEMS_API_KEY='tu_token_aqui'
+ruby scripts/test_rubygems_token.rb
+```
+
+#### 2. Variables de Bitbucket
+
+En tu repositorio de Bitbucket:
+- Settings → Repository variables
+- Añadir variable: `RUBYGEMS_API_KEY` (marcada como secured)
+
+#### 3. Comandos de Release
+
+```bash
+# Release Beta
+git tag v0.3.0-beta.1
+git push origin v0.3.0-beta.1
+
+# Release RC  
+git tag v0.3.0-rc.1
+git push origin v0.3.0-rc.1
+
+# Release Estable (requiere confirmación manual)
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+#### 4. Pipelines Manuales
+
+En Bitbucket Pipelines → Run custom pipeline:
+- `full-release-beta` - Release completo beta
+- `full-release-rc` - Release completo RC
+- `full-release-stable` - Release completo estable (requiere confirmación)
+- `test-build` - Solo testing del build
+
+#### 5. Helper de Deployment
+
+```bash
+# Ver estado y comandos disponibles
+ruby scripts/deployment_helper.rb
+
+# Ver comandos específicos
+ruby scripts/deployment_helper.rb commands
+
+# Ver configuración necesaria  
+ruby scripts/deployment_helper.rb setup
+```
+
+### Flujo de Trabajo Recomendado
+
+1. **Desarrollo**: Trabajo en feature branches
+2. **Beta**: Merge a `develop` → Tag beta → Deploy automático
+3. **RC**: Release branch → Tag RC → Deploy automático  
+4. **Producción**: Merge a `main` → Tag estable → Deploy manual
+
+Para más detalles, ver: `scripts/setup_rubygems_deployment.md`

data/Rakefile

@@ -1,11 +1,114 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-desc "Run tests"
-task default: %i[spec rubocop]
+desc 'Run tests'
+task default: %i[spec rubocop]
+
+# Version management tasks (Git Flow compatible)
+namespace :version do
+  desc 'Create alpha version from feature branches'
+  task :alpha do
+    system('ruby scripts/version_manager.rb alpha')
+  end
+
+  desc 'Create beta version from develop branch'
+  task :beta do
+    system('ruby scripts/version_manager.rb beta')
+  end
+
+  desc 'Create release candidate from release/ branches'
+  task :rc do
+    system('ruby scripts/version_manager.rb rc')
+  end
+end
+
+# Release tasks
+namespace :release do
+  desc 'Release development beta version (versioning + build + publish)'
+  task develop: ['version:beta'] do
+    Rake::Task['build'].invoke
+    puts '📦 Gema construida exitosamente'
+    puts ''
+    puts '🚀 Para publicar en RubyGems:'
+    version = get_current_version
+    puts "   gem push jwt_auth_cognito-#{version}.gem"
+  end
+
+  desc 'Release candidate version (versioning + build + publish)'
+  task rc: ['version:rc'] do
+    Rake::Task['build'].invoke
+    puts '📦 Gema construida exitosamente'
+    puts ''
+    puts '🚀 Para publicar en RubyGems:'
+    version = get_current_version
+    puts "   gem push jwt_auth_cognito-#{version}.gem"
+  end
+
+  desc 'Release stable version (versioning + build + confirm + publish)'
+  task :stable do
+    puts '⚠️  Esta es una release estable. ¿Continuar? (y/N)'
+    response = $stdin.gets.chomp
+
+    if %w[y yes].include?(response.downcase)
+      system('ruby scripts/version_manager.rb stable')
+      Rake::Task['build'].invoke
+      puts '📦 Gema construida exitosamente'
+      puts ''
+      puts '🚀 Para publicar en RubyGems:'
+      version = get_current_version
+      puts "   gem push jwt_auth_cognito-#{version}.gem"
+    else
+      puts '❌ Release cancelada'
+    end
+  end
+end
+
+# Build and publish tasks
+namespace :publish do
+  desc 'Build and publish beta version'
+  task :beta do
+    Rake::Task['build'].invoke
+    version = get_current_version
+    system("gem push jwt_auth_cognito-#{version}.gem")
+  end
+
+  desc 'Build and publish RC version'
+  task :rc do
+    Rake::Task['build'].invoke
+    version = get_current_version
+    system("gem push jwt_auth_cognito-#{version}.gem")
+  end
+
+  desc 'Build and publish alpha version'
+  task :alpha do
+    Rake::Task['build'].invoke
+    version = get_current_version
+    system("gem push jwt_auth_cognito-#{version}.gem")
+  end
+
+  desc 'Build and publish stable version'
+  task :stable do
+    puts '⚠️  Esta es una publicación estable. ¿Continuar? (y/N)'
+    response = $stdin.gets.chomp
+
+    if %w[y yes].include?(response.downcase)
+      Rake::Task['build'].invoke
+      version = get_current_version
+      system("gem push jwt_auth_cognito-#{version}.gem")
+    else
+      puts '❌ Publicación cancelada'
+    end
+  end
+end
+
+# Helper method to get current version
+def get_current_version
+  require_relative 'lib/jwt_auth_cognito/version'
+  JwtAuthCognito::VERSION
+end