jwt_auth_cognito 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd002e4c7b2a20d24633f29af47544d8fe6b15eeba7e35fbe52b8152a09228ad
+  data.tar.gz: 38f681ce7fe3d9d9d7b6a7c95384ec2637f88f56b0cb9d794b6e945705b75dbb
+SHA512:
+  metadata.gz: 226064e684251b7e740d1c016ddd6f751d53bc3a99b6c4ae28d12faae19e91a53042cf6d4e8413d5fc79f3c3783bd83078e8eda7d8236755227379e276b1b8dc
+  data.tar.gz: b94a68ee2b52cbffb93e95d73a56c46743954edb006de458366d0bc826e9e82b5dc684deab7b26567781992f3054287cbfa5c972cbc928511f1e6fa9d1c44862

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-06-16
+
+### Added
+- Initial release of jwt_auth_cognito gem
+- JWT token validation with AWS Cognito JWKS support
+- Redis-based token blacklisting functionality
+- Support for both secure (JWKS) and basic (development) validation modes
+- Access token and ID token specific validation
+- Batch token validation
+- User token management and invalidation
+- Comprehensive error handling with specific error types
+- Configurable JWKS caching
+- Graceful degradation when Redis is unavailable
+- Full test suite with RSpec
+- Comprehensive documentation and usage examples
+
+### Features
+- Offline JWT validation without AWS API calls
+- Automatic public key retrieval and caching
+- Token revocation and blacklist management
+- Multi-token validation support
+- Custom claim validation options
+- Rails integration examples
+- Production-ready with security best practices

data/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Commands
+
+### Development and Testing
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linting
+bundle exec rubocop
+
+# Run both tests and linting (default)
+bundle exec rake
+
+# Run a specific test file
+bundle exec rspec spec/jwt_auth_cognito/configuration_spec.rb
+
+# Test basic functionality
+ruby examples/simple_test.rb
+```
+
+### Gem Management
+```bash
+# Build the gem
+gem build jwt_auth_cognito.gemspec
+
+# Install locally for testing
+bundle exec rake install
+
+# Test gem packaging
+gem contents jwt_auth_cognito-0.1.0.gem
+```
+
+### Configuration Generation
+```bash
+# Rails generator (creates initializer and .env.example)
+rails generate jwt_auth_cognito:install
+
+# Rake tasks for configuration management
+rake jwt_auth_cognito:install    # Install configuration
+rake jwt_auth_cognito:config     # View current config
+rake jwt_auth_cognito:test_redis # Test Redis connection
+rake jwt_auth_cognito:test_cognito # Test Cognito connection
+```
+
+## Architecture Overview
+
+### Core Components
+- **JwtValidator**: Main validation orchestrator that coordinates JWKS validation and blacklist checking
+- **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
+- **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.
+
+**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.
+
+**Compatibility Layer**: Designed to match the API and behavior of the Node.js auth package, ensuring consistent functionality across language implementations.
+
+### Redis Architecture
+- **Connection Management**: Single connection with comprehensive TLS support including certificate validation
+- **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
+
+### 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
+
+### Client Secret Support
+- **Optional Enhancement**: HMAC-SHA256 secret hash calculation matching AWS Cognito requirements
+- **Backward Compatibility**: All functionality works without client secret configuration
+- **Security Integration**: Secret hash automatically included in blacklist operations when configured
+
+## Environment Configuration
+
+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
+- Automatic Rails environment detection for validation mode selection
+
+## Rails Integration
+
+### Generator System
+- **Install Generator**: Creates optimized initializer and environment templates
+- **Configuration Detection**: Automatically detects existing Redis configuration
+- **Environment Setup**: Generates appropriate .env.example with all required variables
+
+### Service Integration
+- **Railtie Integration**: Automatic Rails integration with proper loading order
+- **Middleware Ready**: Designed for easy integration into authentication middleware
+- **Error Handling**: Rails-compatible error types and responses
+
+## Testing Strategy
+
+### Test Structure
+- **Unit Tests**: Individual service testing with mocked dependencies
+- **Integration Tests**: Full validation flow testing with WebMock for external calls
+- **Configuration Tests**: Environment variable handling and validation
+- **Error Handling Tests**: Comprehensive error scenario coverage
+
+### Test Helpers
+- **Configuration Reset**: Automatic test isolation with `reset_configuration!`
+- **WebMock Integration**: Disabled external calls with localhost exceptions
+- **Redis Mocking**: Isolated Redis testing without external dependencies
+
+## Version Compatibility
+
+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) 
+- **Redis**: >= 4.2.5 (matches llegando-neo Redis version constraints)
+
+## Publishing and Distribution
+
+The gem is prepared for RubyGems.org publication with:
+- Complete gemspec with metadata
+- Proper file inclusion patterns
+- Version compatibility constraints
+- MIT license and documentation

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 The Optimal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PUBLISH_GUIDE.md

@@ -0,0 +1,187 @@
+# 📦 Guía para Publicar jwt_auth_cognito en RubyGems
+
+Esta guía te llevará paso a paso para publicar tu gema en RubyGems.org y poder usarla de forma remota.
+
+## 🛠️ **Prerequisitos**
+
+### 1. Cuenta en RubyGems.org
+- Ve a [rubygems.org](https://rubygems.org) y crea una cuenta
+- Confirma tu email
+
+### 2. Configurar credenciales locales
+```bash
+# Configurar tu API key (se te pedirá email y password)
+gem signin
+```
+
+## 🚀 **Proceso de Publicación**
+
+### **Paso 1: Verificar la gema**
+
+```bash
+# Asegúrate de estar en el directorio de la gema
+cd /jwt-auth-cognito-gem
+
+# Verificar que todos los tests pasen
+bundle exec rspec
+
+# Verificar que no haya problemas de código
+bundle exec rubocop
+
+# Verificar la estructura de la gema
+gem build jwt_auth_cognito.gemspec
+```
+
+### **Paso 2: Construir la gema**
+
+```bash
+# Limpiar gemas anteriores
+rm -f *.gem
+
+# Construir la gema final
+gem build jwt_auth_cognito.gemspec
+```
+
+### **Paso 3: Verificar antes de publicar**
+
+```bash
+# Verificar el contenido de la gema
+gem contents jwt_auth_cognito-0.1.0.gem
+
+# Verificar metadatos
+gem specification jwt_auth_cognito-0.1.0.gem
+```
+
+### **Paso 4: Publicar en RubyGems**
+
+```bash
+# Publicar la gema (¡CUIDADO! Esto es irreversible)
+gem push jwt_auth_cognito-0.1.0.gem
+```
+
+## ✅ **Verificación de Publicación**
+
+### 1. Verificar en la web
+- Ve a: https://rubygems.org/gems/jwt_auth_cognito
+- Debería aparecer tu gema con toda la información
+
+### 2. Probar instalación
+```bash
+# En otro directorio, probar instalar
+gem install jwt_auth_cognito
+
+# O en un proyecto Rails
+echo 'gem "jwt_auth_cognito", "~> 0.1.0"' >> Gemfile
+bundle install
+```
+
+## 🔄 **Para Actualizaciones Futuras**
+
+### **Paso 1: Actualizar versión**
+```ruby
+# En lib/jwt_auth_cognito/version.rb
+module JwtAuthCognito
+  VERSION = "0.1.1"  # Incrementar versión
+end
+```
+
+### **Paso 2: Actualizar CHANGELOG**
+```markdown
+# En CHANGELOG.md
+## [0.1.1] - 2024-06-17
+### Added
+- Nueva funcionalidad X
+### Fixed
+- Bug corregido Y
+```
+
+### **Paso 3: Publicar nueva versión**
+```bash
+gem build jwt_auth_cognito.gemspec
+gem push jwt_auth_cognito-0.1.1.gem
+```
+
+## 🏷️ **Versionado Semántico**
+
+Sigue estas reglas para versiones:
+
+- **MAJOR** (1.0.0): Cambios incompatibles
+- **MINOR** (0.1.0): Nuevas funcionalidades compatibles
+- **PATCH** (0.1.1): Correcciones de bugs
+
+## 🛡️ **Consideraciones de Seguridad**
+
+### ⚠️ **IMPORTANTE: Una vez publicado, NO se puede borrar**
+- Las versiones de gemas son permanentes en RubyGems
+- Solo se puede "yankar" (ocultar) pero sigue existiendo
+- Revisa muy bien antes de publicar
+
+### 🔐 **Proteger tu cuenta**
+```bash
+# Habilitar MFA (Multi-Factor Authentication)
+gem owner --add your_email@domain.com --otp YOUR_OTP_CODE jwt_auth_cognito
+
+# Ver owners de tu gema
+gem owner jwt_auth_cognito
+```
+
+## 📋 **Checklist de Pre-publicación**
+
+- [ ] ✅ Tests pasando (`bundle exec rspec`)
+- [ ] ✅ Código limpio (`bundle exec rubocop`)
+- [ ] ✅ Versión actualizada
+- [ ] ✅ CHANGELOG actualizado
+- [ ] ✅ README.md completo
+- [ ] ✅ Licencia correcta
+- [ ] ✅ Metadatos del gemspec correctos
+- [ ] ✅ Archivos innecesarios excluidos (.gitignore)
+- [ ] ✅ Gema construida exitosamente
+- [ ] ✅ Contenido de la gema verificado
+
+## 🎯 **Después de Publicar**
+
+### 1. Actualizar documentación
+- Actualiza el README con instrucciones de instalación desde RubyGems
+- Actualiza ejemplos para usar la versión publicada
+
+### 2. Comunicar el lanzamiento
+- Anuncia en tu equipo/empresa
+- Actualiza documentación interna
+- Considera crear un release en GitHub
+
+### 3. Monitorear uso
+- Revisa estadísticas en rubygems.org
+- Monitorea issues/feedback de usuarios
+
+## 🆘 **Si algo sale mal**
+
+### Yankar una versión (ocultar)
+```bash
+gem yank jwt_auth_cognito -v 0.1.0
+```
+
+### Restaurar una versión yankeada
+```bash
+gem unyank jwt_auth_cognito -v 0.1.0
+```
+
+## 📞 **Soporte**
+
+- **RubyGems Help**: https://guides.rubygems.org/
+- **Documentación oficial**: https://guides.rubygems.org/publishing/
+- **Soporte RubyGems**: https://help.rubygems.org/
+
+---
+
+## 🚀 **Comandos Rápidos de Publicación**
+
+```bash
+# Flujo completo de publicación
+bundle exec rspec                    # Tests
+bundle exec rubocop                  # Linting  
+rm -f *.gem                         # Limpiar
+gem build jwt_auth_cognito.gemspec  # Construir
+gem push jwt_auth_cognito-0.1.0.gem # Publicar
+```
+
+¡Ya tienes todo listo para publicar tu gema en RubyGems! 🎉