jwt_auth_cognito 1.0.0.pre.beta.12 → 1.0.0.pre.beta.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b17cfc63543d51251188fa8645cf7f9235d741851fc33087bf781cb26ba21c07
-  data.tar.gz: c51dd33e95f2346794ad4d50578982e09ed0395b22e192d8a69e4a196ef8c687
+  metadata.gz: 77eed5e47f35c5f0a7e693bab6c09e70cf2ea950670273d203ff3611d94b8a70
+  data.tar.gz: 21a499f3e1ad917bf9587cd8695e2dc44cceb7fb77f3ada93185ae2ed855c0d7
 SHA512:
-  metadata.gz: eb6034d5dcb76d9523e4dcf68e488899b2ee50eba313aba072b069a4a552d8cc331175d72dca2577b7f85b9e3b63720dbafe98a21d7cf10107da457cab281436
-  data.tar.gz: 7e5e07f954ca37e0ece2cfed27763426903623aafb3a2f37dd9fecf9c54a876ace20ec7e9e0fea7e8ea8117bc34af28ecd730af22c387a196b43b704a4a40925
+  metadata.gz: 2fb3defb3e11e9cc318ac1d387cf58c99fa6b1b3152bc34841db21645fb6a6fa67ab99af956fb4fd539aeaa44132df9994bc55256f9bb4412e30ebd112801c6a
+  data.tar.gz: cba58be12f1fd5dfe1d199a83e27e60fa851bedfd1b39a2d7b8a0f6c2669c99c9f4459fbe6390977aef177c1c797abecd83ffb447e966615d6556ac8192acf3c

data/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0-beta.14] - 2026-06-18
+
+### Changed
+
+- **`create_cognito_validator` enables identity enrichment by default.** The
+  convenience constructor always receives the region, so
+  `validate(token, enrich_user_data: true)` now returns `payload['email']`
+  without extra setup. Pass `enable_user_identity_enrichment: false` to opt out.
+  The `configure` + `JwtValidator.new` path stays opt-in (gated on
+  `config.enable_user_identity_enrichment`), since it may run without Cognito
+  network access. Mirrors the npm package's `createCognitoValidatorAsync` default.
+
+### Fixed
+
+- **`RedisService#set` hardened against `SETEX key 0`**: `0` is truthy in Ruby, so
+  `set(key, value, 0)` would have issued `SETEX key 0` (rejected by Redis with
+  "ERR invalid expire time"). `set` now attaches an expiry only for a positive TTL;
+  a nil/non-positive ttl persists the key with a plain `SET`. Current callers were
+  unaffected (`update_last_used` passes no TTL); this prevents the footgun and
+  matches the npm package's `RedisService.set` behavior.
+
+## [1.0.0-beta.13] - 2026-06-17
+
+### Added
+
+- **Cognito identity enrichment** (populate `payload['email']` on ACCESS tokens):
+  - Cognito **access tokens do not carry `email`** (only ID tokens do). New opt-in
+    enrichment fetches the user's standard identity attributes via Cognito `GetUser`
+    — authorized by the access token's own `aws.cognito.signin.user.admin` scope, so
+    **no AWS IAM credentials are required** — and merges them into the decoded payload.
+  - Enable with `config.enable_user_identity_enrichment = true` (env
+    `ENABLE_USER_IDENTITY_ENRICHMENT=true`), or pass
+    `enable_user_identity_enrichment: true` to `create_cognito_validator`.
+  - Runs only for `token_use == 'access'` tokens that don't already have `email`,
+    and only when `enrich_user_data` is requested (default in `validate`).
+  - Results are cached per `sub` (default 300s, `IDENTITY_CACHE_TIMEOUT`). Any failure
+    is non-fatal: the token still validates, just without identity enrichment.
+  - Default merged attributes: `email`, `email_verified`, `name`, `given_name`,
+    `family_name`, `phone_number`, `phone_number_verified`, `preferred_username`
+    (`*_verified` normalized to boolean). `custom:*` attributes are NOT merged.
+  - New `JwtAuthCognito::CognitoIdentityService` class.
+  - New dependency: `aws-sdk-cognitoidentityprovider`.
+
 ## [1.0.0-beta.11] - 2025-01-23
 
 ### Improved

data/CLAUDE.md

@@ -69,6 +69,7 @@ rake jwt_auth_cognito:test_cognito # Test Cognito connection
 - **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
+- **CognitoIdentityService**: Fetches identity attributes (email, name, ...) via Cognito `GetUser` to enrich ACCESS tokens, which don't carry `email`. `GetUser` is authorized by the access token's own `aws.cognito.signin.user.admin` scope — **no AWS IAM credentials required**. Opt-in via `enable_user_identity_enrichment`; merges into `payload` in `validate` only for `token_use == 'access'` tokens missing `email` when `enrich_user_data` is on; per-`sub` cache (default 300s); failures are non-fatal; `custom:*` excluded; `*_verified` normalized to boolean. Dependency: `aws-sdk-cognitoidentityprovider`.
 - **ApiKeyValidator**: API key validation with system and app-level access control
 - **ErrorUtils**: Centralized error handling and categorization system
 - **SSMService**: AWS Parameter Store integration for secure certificate management (auth-service compatible)

data/README.md

@@ -102,6 +102,8 @@ AWS_SSM_ENDPOINT=https://ssm.us-east-1.amazonaws.com  # Opcional, para VPC endpo
 # Habilitar funcionalidades específicas
 ENABLE_API_KEY_VALIDATION=true          # Validación de API keys
 ENABLE_USER_DATA_RETRIEVAL=true         # Enriquecimiento de datos de usuario
+ENABLE_USER_IDENTITY_ENRICHMENT=true    # Enriquecimiento de identidad (email en access tokens)
+IDENTITY_CACHE_TIMEOUT=300              # TTL de caché de identidad por sub (segundos)
 ```
 
 ### Opciones de Configuración Boolean
@@ -110,9 +112,34 @@ La gema soporta las siguientes opciones boolean para habilitar funcionalidades e
 
 - **`enable_api_key_validation`** - Habilita la validación de API keys para control de acceso a nivel de sistema y aplicación (default: false)
 - **`enable_user_data_retrieval`** - Habilita el enriquecimiento de datos de usuario con permisos, organizaciones y aplicaciones (default: false)
+- **`enable_user_identity_enrichment`** - Habilita el enriquecimiento de identidad: pobla `payload['email']` (y otros atributos estándar) en **access tokens** vía Cognito `GetUser` (default: false)
 
 Estas opciones permiten control granular sobre qué características están activas, optimizando el rendimiento habilitando solo la funcionalidad necesaria.
 
+### Enriquecimiento de Identidad — `email` en Access Tokens
+
+Los **access tokens de Cognito NO incluyen `email`** (solo los ID tokens lo traen). Si tu backend valida el access token y necesita el email (p. ej. para trazabilidad/logging), habilita `enable_user_identity_enrichment`. La gema obtiene los atributos del usuario con `GetUser` —autorizado por el propio scope `aws.cognito.signin.user.admin` del access token, **sin credenciales AWS IAM**— y los fusiona en el `payload`.
+
+> **Con `create_cognito_validator(...)` está activado por defecto** (ese constructor siempre recibe la región): `validate(token, enrich_user_data: true)` ya trae `payload['email']`. Para desactivarlo pasa `enable_user_identity_enrichment: false`. El path `configure` + `JwtValidator.new` de abajo sí requiere el flag explícito (puede correr sin acceso de red a Cognito).
+
+```ruby
+JwtAuthCognito.configure do |config|
+  config.cognito_region = 'us-east-1'
+  config.enable_user_identity_enrichment = true
+  config.identity_cache_timeout = 300   # TTL de caché por sub (segundos)
+end
+
+result = validator.validate(access_token, api_key: api_key, enrich_user_data: true)
+result[:payload]['email'] # ✅ ahora disponible
+```
+
+**Comportamiento:**
+- Solo actúa sobre tokens `token_use == 'access'` que aún no traen `email`. Los ID tokens se omiten (ya lo traen).
+- Solo se ejecuta cuando `enrich_user_data` está activo (default en `validate`).
+- Resultados cacheados por `sub` (default 300s) para no llamar a Cognito en cada request.
+- Tolerante a fallos: si `GetUser` falla, el token sigue siendo válido (solo no se enriquece).
+- Los `*_verified` se normalizan a boolean. Los atributos `custom:*` **no** se fusionan.
+
 ## Configuración AWS para Development
 
 ### Desarrollo Local

data/jwt_auth_cognito.gemspec

@@ -42,6 +42,7 @@ Gem::Specification.new do |spec|
   spec.extra_rdoc_files = ['README.md', 'CHANGELOG.md', 'LICENSE.txt']
 
   # Dependencies - compatible with llegando-neo (Ruby 2.7.5, Rails 5.2.6)
+  spec.add_dependency 'aws-sdk-cognitoidentityprovider', '~> 1.0' # For GetUser identity enrichment
   spec.add_dependency 'aws-sdk-ssm', '~> 1.0' # For AWS Parameter Store support
   spec.add_dependency 'json', '~> 2.0'
   spec.add_dependency 'jwt', '~> 2.0'

data/lib/jwt_auth_cognito/cognito_identity_service.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-cognitoidentityprovider'
+
+module JwtAuthCognito
+  # Fetches a user's Cognito identity attributes (email, name, ...) using the
+  # caller's OWN access token. Cognito access tokens do not carry `email`; only
+  # ID tokens do. The access token scope `aws.cognito.signin.user.admin`
+  # authorizes the GetUser operation, so NO AWS IAM credentials are required —
+  # the token itself is the authorization.
+  #
+  # Results are cached per-user (sub) so we don't hit Cognito on every single
+  # validation. Any failure returns nil (never raises) so token validation is
+  # never blocked by an identity-enrichment problem.
+  class CognitoIdentityService
+    # Curated STANDARD identity attributes merged into the decoded token.
+    # Intentionally excludes custom:* attributes to avoid leaking arbitrary data.
+    DEFAULT_IDENTITY_ATTRIBUTES = %w[
+      email email_verified name given_name family_name
+      phone_number phone_number_verified preferred_username
+    ].freeze
+
+    def initialize(config = JwtAuthCognito.configuration)
+      @region = config.cognito_region
+      @cache_ttl = config.identity_cache_timeout || 300
+      configured = config.identity_attributes
+      @attributes = configured && !configured.empty? ? configured : DEFAULT_IDENTITY_ATTRIBUTES
+      @cache = {}
+      @mutex = Mutex.new
+    end
+
+    # Returns a hash of identity attribute name => value for the user owning the
+    # access token, or nil on any failure (never raises).
+    def get_identity_attributes(access_token, sub = nil)
+      cache_key = sub || "token:#{access_token[-24..] || access_token}"
+
+      cached = read_cache(cache_key)
+      return cached if cached
+
+      response = client.get_user(access_token: access_token)
+
+      all = {}
+      response.user_attributes.each { |attr| all[attr.name] = attr.value }
+
+      filtered = {}
+      @attributes.each { |name| filtered[name] = all[name] if all.key?(name) }
+
+      write_cache(cache_key, filtered)
+      filtered
+    rescue StandardError => e
+      ErrorUtils.log_error(e, 'CognitoIdentityService.get_identity_attributes failed')
+      nil
+    end
+
+    def clear_cache
+      @mutex.synchronize { @cache = {} }
+    end
+
+    private
+
+    def client
+      @client ||= Aws::CognitoIdentityProvider::Client.new(region: @region)
+    end
+
+    def read_cache(key)
+      @mutex.synchronize do
+        entry = @cache[key]
+        next nil unless entry
+        next nil if entry[:expires_at] < Time.now.to_i
+
+        entry[:value]
+      end
+    end
+
+    def write_cache(key, value)
+      @mutex.synchronize do
+        @cache[key] = { value: value, expires_at: Time.now.to_i + @cache_ttl }
+      end
+    end
+  end
+end

data/lib/jwt_auth_cognito/configuration.rb

@@ -7,7 +7,8 @@ module JwtAuthCognito
                   :redis_ssl, :redis_timeout, :redis_connect_timeout, :redis_read_timeout,
                   :redis_ca_cert_path, :redis_ca_cert_name, :redis_verify_mode,
                   :jwks_cache_ttl, :validation_mode, :environment,
-                  :enable_api_key_validation, :enable_user_data_retrieval
+                  :enable_api_key_validation, :enable_user_data_retrieval,
+                  :enable_user_identity_enrichment, :identity_cache_timeout, :identity_attributes
 
     def initialize
       @cognito_region = ENV['COGNITO_REGION'] || ENV['AWS_REGION'] || 'us-east-1'
@@ -35,6 +36,12 @@ module JwtAuthCognito
       @validation_mode = production? ? :secure : :basic
       @enable_api_key_validation = ENV['ENABLE_API_KEY_VALIDATION'] == 'true'
       @enable_user_data_retrieval = ENV['ENABLE_USER_DATA_RETRIEVAL'] == 'true'
+
+      # Cognito identity enrichment: populate payload['email'] (and other identity
+      # attributes) for ACCESS tokens via GetUser, since access tokens don't carry them.
+      @enable_user_identity_enrichment = ENV['ENABLE_USER_IDENTITY_ENRICHMENT'] == 'true'
+      @identity_cache_timeout = (ENV['IDENTITY_CACHE_TIMEOUT'] || 300).to_i
+      @identity_attributes = nil
     end
 
     def production?

data/lib/jwt_auth_cognito/jwt_validator.rb

@@ -10,6 +10,7 @@ module JwtAuthCognito
       @blacklist_service = TokenBlacklistService.new(config)
       @api_key_validator = config.enable_api_key_validation ? ApiKeyValidator.new(config) : nil
       @user_data_service = config.enable_user_data_retrieval ? UserDataService.new(nil, config.user_data_config) : nil
+      @cognito_identity_service = config.enable_user_identity_enrichment ? CognitoIdentityService.new(config) : nil
       @initialized = false
     end
 
@@ -94,6 +95,18 @@ module JwtAuthCognito
         end
       end
 
+      # Step 6: Enrich token claims with Cognito identity attributes (email, name, ...)
+      # Cognito ACCESS tokens do NOT carry email (only ID tokens do). Fetch the user's
+      # attributes via GetUser (authorized by the access token's own scope) and merge
+      # them into the payload so consumers get payload['email'] transparently.
+      if enrich_user_data && @config.enable_user_identity_enrichment && @cognito_identity_service
+        payload = enriched_result[:payload]
+        if payload && payload['token_use'] == 'access' && payload['email'].nil?
+          attrs = @cognito_identity_service.get_identity_attributes(token, payload['sub'])
+          apply_identity_attributes(payload, attrs) if attrs
+        end
+      end
+
       enriched_result
     end
 
@@ -445,5 +458,15 @@ module JwtAuthCognito
         { valid: true } # Continue with basic validation if user data service fails
       end
     end
+
+    # Merge fetched Cognito identity attributes into the decoded payload without
+    # overriding existing claims. `*_verified` attributes are normalized to booleans.
+    def apply_identity_attributes(payload, attrs)
+      attrs.each do |name, value|
+        next unless payload[name].nil?
+
+        payload[name] = name.end_with?('_verified') ? value == 'true' : value
+      end
+    end
   end
 end

data/lib/jwt_auth_cognito/redis_service.rb

@@ -105,7 +105,10 @@ module JwtAuthCognito
 
     def set(key, value, ttl = nil)
       connect_redis
-      if ttl
+      # Only attach an expiry for a positive TTL. A nil or non-positive ttl (note:
+      # 0 is truthy in Ruby) means a persistent key — `SETEX key 0` is rejected by
+      # Redis with "ERR invalid expire time", so fall back to a plain SET.
+      if ttl&.positive?
         @redis.setex(key, ttl, value)
       else
         @redis.set(key, value)

data/lib/jwt_auth_cognito/version.rb

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

data/lib/jwt_auth_cognito.rb

@@ -8,6 +8,7 @@ require_relative 'jwt_auth_cognito/redis_service'
 require_relative 'jwt_auth_cognito/token_blacklist_service'
 require_relative 'jwt_auth_cognito/api_key_validator'
 require_relative 'jwt_auth_cognito/user_data_service'
+require_relative 'jwt_auth_cognito/cognito_identity_service'
 require_relative 'jwt_auth_cognito/error_utils'
 require_relative 'jwt_auth_cognito/permission_checker'
 require_relative 'jwt_auth_cognito/jwt_validator'
@@ -41,8 +42,13 @@ module JwtAuthCognito
   end
 
   # Convenience factory method to create a Cognito validator
+  # Convenience constructor. Identity enrichment (email on access tokens) is ON
+  # by default here because the region is always provided; pass
+  # enable_user_identity_enrichment: false to opt out. (The configure +
+  # JwtValidator.new path keeps it opt-in, gated on config.enable_user_identity_enrichment.)
   def self.create_cognito_validator(region:, user_pool_id:, client_id: nil, client_secret: nil, redis_config: {},
-                                    enable_api_key_validation: false, enable_user_data_retrieval: false)
+                                    enable_api_key_validation: false, enable_user_data_retrieval: false,
+                                    enable_user_identity_enrichment: true)
     old_config = configuration.dup
 
     configure do |config|
@@ -52,6 +58,7 @@ module JwtAuthCognito
       config.cognito_client_secret = client_secret if client_secret
       config.enable_api_key_validation = enable_api_key_validation
       config.enable_user_data_retrieval = enable_user_data_retrieval
+      config.enable_user_identity_enrichment = enable_user_identity_enrichment
 
       # Apply Redis configuration
       config.redis_host = redis_config[:host] if redis_config[:host]

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: jwt_auth_cognito
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta.12
+  version: 1.0.0.pre.beta.14
 platform: ruby
 authors:
 - The Optimal
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-06-18 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-cognitoidentityprovider
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: aws-sdk-ssm
   requirement: !ruby/object:Gem::Requirement
@@ -190,6 +204,7 @@ files:
 - lib/jwt_auth_cognito.rb
 - lib/jwt_auth_cognito/api_key_validator.rb
 - lib/jwt_auth_cognito/authorization_concern.rb
+- lib/jwt_auth_cognito/cognito_identity_service.rb
 - lib/jwt_auth_cognito/configuration.rb
 - lib/jwt_auth_cognito/error_utils.rb
 - lib/jwt_auth_cognito/jwks_service.rb