jwt_auth_cognito 1.0.0.pre.beta.11 → 1.0.0.pre.beta.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8069ccdfaed845402cd9053a2db66b2bc74359649de17ca2ce7ad010a939722
-  data.tar.gz: 3ba1441f8016d8e2d5b1bca7913fd7700f0ae51c8470ab1e6f06a2e1a9640697
+  metadata.gz: 21369d98a11f9f2dc8a1539f4f4db6071822ae94901f15e0c4eb3496d4d74585
+  data.tar.gz: 7bcdd497bcb3ebb395a43ccb54c803efb525e739d1425670f488f675bb4d4d86
 SHA512:
-  metadata.gz: 897a6f309d17ba4f312e5b9b86a8daf4ab76050a6b5cd17543eaaf728c3ba242bc1ec34a8efb25f17395095cccf5225bf918850fb4f373ba0132311c3c0e84c7
-  data.tar.gz: 785494e60e28e09a5b3343eaf9b2dfc0d9a70343cf8f56ddd81768b172c0753696a3b03df84f24510ba50687d9d7cb6af8a3bce72fad2331e88bc195d9dc73b5
+  metadata.gz: 2d68c23981b7efd4d919bda74cc2f67f15326b46d27a02103daf04bba9f76ed3de9c9b7b07de4d30d36a6a78660e9d07ac73d272767e76e765b2a8900a29d153
+  data.tar.gz: d50fc1f4f3fe447543cf0f7dfeff79de88082ec0d5aecf9cd602654349387a50100e6e7c4e8adcbfeb8af2f6962e060bac06d8a38a9b5362314e0e623351f241

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,32 @@ 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`.
+
+```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/authorization_concern.rb

@@ -59,6 +59,24 @@ module JwtAuthCognito
       @current_user_permissions ||= fetch_current_user_permissions
     end
 
+    # Raises ForbiddenError unless the user has the given permission over a specific resource.
+    # By convention reads the resource ID from params[:id]; override with resource_id: keyword arg.
+    #
+    #   before_action -> { authorize_resource_permission!('fleet:vehicles:write') }, only: [:update]
+    #   before_action -> { authorize_resource_permission!('fleet:vehicles:write', resource_id: params[:vehicle_id]) }
+    def authorize_resource_permission!(permission, resource_id: params[:id])
+      uid = jwt_user_id
+      aid = jwt_app_id
+      oid = jwt_org_id
+
+      raise JwtAuthCognito::ForbiddenError, 'Access denied' unless uid && aid && oid && resource_id
+
+      return if jwt_validator.check_resource_permission?(uid, aid, oid, resource_id.to_s, permission)
+
+      log_resource_permission_denied(permission, resource_id)
+      raise JwtAuthCognito::ForbiddenError, 'Access denied'
+    end
+
     private
 
     def fetch_current_user_permissions
@@ -114,5 +132,15 @@ module JwtAuthCognito
         "app_id=#{jwt_app_id} org_id=#{jwt_org_id}"
       )
     end
+
+    def log_resource_permission_denied(permission, resource_id)
+      return unless defined?(Rails)
+
+      Rails.logger.warn(
+        "[RESOURCE_PERMISSION_DENIED] user_id=#{jwt_user_id} " \
+        "permission=#{permission} resource_id=#{resource_id} " \
+        "app_id=#{jwt_app_id} org_id=#{jwt_org_id}"
+      )
+    end
   end
 end

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
 
@@ -270,6 +283,28 @@ module JwtAuthCognito
       @user_data_service.resolve_effective_permissions(user_id, app_id, org_id)
     end
 
+    # Get the permissions the user has over a specific resource instance (ReBAC).
+    # Returns { resource_type:, resource_id:, permissions:, mode: } or nil.
+    def get_resource_permissions(user_id, app_id, org_id, resource_type, resource_id)
+      return nil unless @user_data_service
+
+      result = @user_data_service.resolve_resource_permissions(user_id, app_id, org_id, resource_id)
+      return nil unless result
+
+      { resource_type: resource_type, resource_id: resource_id,
+        permissions: result[:permissions], mode: result[:mode] }
+    end
+
+    # Verify if the user has a specific permission over a concrete resource instance.
+    def check_resource_permission?(user_id, app_id, org_id, resource_id, permission)
+      return false unless @user_data_service
+
+      result = @user_data_service.resolve_resource_permissions(user_id, app_id, org_id, resource_id)
+      return false unless result
+
+      PermissionChecker.permission_in_list?(permission, result[:permissions])
+    end
+
     def is_token_expired?(token)
       payload = decode_token(token)
       return true if payload.is_a?(Hash) && payload[:error]
@@ -423,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/user_data_service.rb

@@ -372,6 +372,35 @@ module JwtAuthCognito
       @cache_timestamps[key] = Time.now.to_i
     end
 
+    # Resolve permissions the user has over a specific resource instance (ReBAC).
+    # Applies resourceRestrictions per-permission: open mode if none configured.
+    # Returns nil if the user has no active membership in that org.
+    def resolve_resource_permissions(user_id, app_id, organization_id, resource_id)
+      effective = resolve_effective_permissions(user_id, app_id, organization_id)
+      return nil unless effective
+
+      raw = @redis_service.get("user:permissions:#{user_id}")
+      return nil unless raw
+
+      data = JSON.parse(raw)
+      restrictions = data.dig('permissions', app_id, organization_id, 'resourceRestrictions')
+      has_any_restriction = restrictions.is_a?(Hash) && !restrictions.empty?
+      mode = has_any_restriction ? 'restricted' : 'open'
+
+      allowed = effective.select do |perm|
+        if !restrictions.is_a?(Hash) || !restrictions.key?(perm)
+          true
+        else
+          restrictions[perm].is_a?(Array) && restrictions[perm].include?(resource_id)
+        end
+      end
+
+      { permissions: allowed, mode: mode }
+    rescue StandardError => e
+      puts "Error resolving resource permissions for #{user_id}:#{resource_id}: #{e.message}"
+      nil
+    end
+
     def compute_permissions_from_roles(app_id, organization_id, role_names)
       roles_data = get_app_roles(app_id, organization_id)
       return [] unless roles_data.is_a?(Hash)

data/lib/jwt_auth_cognito/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JwtAuthCognito
-  VERSION = '1.0.0-beta.11'
+  VERSION = '1.0.0-beta.13'
 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'
@@ -42,7 +43,8 @@ module JwtAuthCognito
 
   # Convenience factory method to create a Cognito validator
   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: false)
     old_config = configuration.dup
 
     configure do |config|
@@ -52,6 +54,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.11
+  version: 1.0.0.pre.beta.13
 platform: ruby
 authors:
 - The Optimal
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-06-17 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