jwt_auth_cognito 1.0.0.pre.beta.9 → 1.0.0.pre.beta.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ec0550d58a587e152aa1a4c41cfce13691bb016f0b12e4525a671bc7fda153b
-  data.tar.gz: 77a05aeb998b6bdeb8df90ffc93a78a3ad1c3565aeda43d4bdcf069713bb6295
+  metadata.gz: e8069ccdfaed845402cd9053a2db66b2bc74359649de17ca2ce7ad010a939722
+  data.tar.gz: 3ba1441f8016d8e2d5b1bca7913fd7700f0ae51c8470ab1e6f06a2e1a9640697
 SHA512:
-  metadata.gz: 5a5f6a72cfebb9e1f805ba53b3561c544b2afc18f993af0759da596c02401e6bda2725a58837e2b5db1b818a5f44ae730c8b9057aa0a481530e8f3c035b70ae1
-  data.tar.gz: 21e84bde860ae1d70dce2ecf5d32a40bcd6fb18af8eb815de9c6079de7996a9a488871c3b91eca0fd649c41d900863c155948e9c96caff507c75b3de3b9110b1
+  metadata.gz: 897a6f309d17ba4f312e5b9b86a8daf4ab76050a6b5cd17543eaaf728c3ba242bc1ec34a8efb25f17395095cccf5225bf918850fb4f373ba0132311c3c0e84c7
+  data.tar.gz: 785494e60e28e09a5b3343eaf9b2dfc0d9a70343cf8f56ddd81768b172c0753696a3b03df84f24510ba50687d9d7cb6af8a3bce72fad2331e88bc195d9dc73b5

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0-beta.11] - 2025-01-23
+
+### Improved
+
+- **Documentation Enhancement**: Comprehensive documentation of token structure and validation responses
+  - Added detailed structure documentation for decoded token hash with all JWT claims
+  - Documented complete validation result structure including `api_key_data` field
+  - Added comprehensive `api_key_data` structure documentation with all fields explained
+  - Included real-world examples of Access Token and ID Token decoded structures in Ruby format
+  - Added comparison table showing differences between Access and ID tokens
+  - Documented API Key scopes (`system`, `app`, `client`) with usage patterns
+  - Added 4 practical examples: basic validation, scope-based authorization, metadata usage, and usage tracking
+  - Included documentation for enriched validation results with user data fields
+  - Enhanced error handling documentation with common error messages
+
+### Documentation
+
+- **Token Structure**: Complete guide to JWT claims (standard, optional, and Cognito-specific)
+- **Response Structure**: Detailed documentation of validation response hash format
+- **API Key Details**: Full explanation of API key data including permissions, scope, and metadata
+- **Practical Examples**: Real-world Ruby code examples for common use cases
+- **Ruby Idioms**: Documentation adapted to Ruby conventions and patterns
+
+## [1.0.0-beta.10] - 2025-01-23
+
+### Fixed
+
+- **Audience Validation**: Fixed overly strict audience validation for AWS Cognito access tokens
+  - Access tokens from Cognito typically don't include 'aud' claim, only ID tokens do
+  - Modified JWKS validation to only enforce audience checking for ID tokens (`token_use: 'id'`)
+  - Access tokens (`token_use: 'access'`) now skip audience validation as per AWS Cognito standards
+  - Resolves "Invalid audience. Expected [client_id], received <none>" error for access tokens
+  - Maintains proper security validation for ID tokens
+
+### Improved
+
+- **JWT Standards Compliance**: Enhanced compatibility with AWS Cognito token specifications
+  - Pre-decodes tokens to determine type before applying validation rules
+  - Follows AWS Cognito best practices for token type-specific validation
+  - Maintains backward compatibility with existing ID token validation
+
 ## [1.0.0-beta.9] - 2025-01-22
 
 ### Fixed

data/CLAUDE.md

@@ -304,7 +304,7 @@ JWKS_CACHE_TTL=3600  # 1 hour
 
 ## Version Compatibility
 
-### ✅ **Updated January 2025 - Version 1.0.0-beta.6**
+### ✅ **Updated January 2025 - Version 1.0.0-beta.10**
 
 **Stable production-ready beta with complete pipeline compatibility**
 

data/README.md

@@ -519,6 +519,459 @@ rescue JwtAuthCognito::BlacklistError => e
 end
 ```
 
+## 📋 Estructura del Token Decodificado
+
+Después de una validación exitosa, el hash de resultado contiene los claims del JWT con la siguiente estructura:
+
+### Claims Principales
+
+```ruby
+# Resultado de validación
+{
+  # ============ Claims Obligatorios JWT Standard (RFC 7519) ============
+
+  # Subject - Identificador único del usuario (UUID)
+  sub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+
+  # Audience - Cliente/aplicación para la cual el token fue emitido
+  aud: "1234567890abcdefghijklmnop",
+
+  # Issuer - URL del User Pool de Cognito que emitió el token
+  iss: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX",
+
+  # Expiration Time - Timestamp Unix (segundos) de expiración
+  exp: 1735689600,  # Equivale a 2025-01-01 00:00:00 UTC
+
+  # Issued At - Timestamp Unix (segundos) de emisión
+  iat: 1735603200,  # Equivale a 2024-12-31 00:00:00 UTC
+
+  # Token Use - Tipo de token Cognito
+  token_use: "access",  # 'access' para Access Tokens, 'id' para ID Tokens
+
+  # ============ Claims Opcionales de Usuario ============
+
+  # Email del usuario (opcional)
+  email: "usuario@ejemplo.com",
+
+  # Verificación de email (opcional)
+  email_verified: true,
+
+  # Número de teléfono (opcional)
+  phone_number: "+12025551234",
+
+  # Verificación de teléfono (opcional)
+  phone_number_verified: true,
+
+  # Nombre de usuario (opcional)
+  username: "john.doe",
+
+  # ============ Claims Específicos de AWS Cognito ============
+
+  # Username en formato Cognito (opcional)
+  "cognito:username": "john.doe",
+
+  # Grupos de Cognito (opcional)
+  "cognito:groups": ["admin", "users"],
+
+  # Scope OAuth2 - Solo en Access Tokens
+  scope: "openid email profile",
+
+  # Authentication Time - Timestamp Unix (opcional)
+  auth_time: 1735603200,
+
+  # JWT ID - Identificador único del token (opcional)
+  jti: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+
+  # ============ Custom Attributes ============
+  # Cualquier atributo custom definido en Cognito
+  "custom:tenant_id": "company-123"
+}
+```
+
+### Ejemplos Reales de Tokens Decodificados
+
+#### Access Token (token_use: "access")
+
+```ruby
+result = validator.validate_access_token(token)
+
+# Resultado:
+{
+  valid: true,
+  sub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  iss: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX",
+  client_id: "1234567890abcdefghijklmnop",
+  aud: "1234567890abcdefghijklmnop",
+  token_use: "access",
+  scope: "openid email profile",
+  auth_time: 1735603200,
+  exp: 1735689600,
+  iat: 1735603200,
+  jti: "xyz-789-def-456",
+  username: "john.doe",
+  "cognito:username": "john.doe",
+  "cognito:groups": ["admin", "users"]
+}
+```
+
+#### ID Token (token_use: "id")
+
+```ruby
+result = validator.validate_id_token(token)
+
+# Resultado:
+{
+  valid: true,
+  sub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  iss: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX",
+  aud: "1234567890abcdefghijklmnop",
+  token_use: "id",
+  auth_time: 1735603200,
+  exp: 1735689600,
+  iat: 1735603200,
+  email: "john.doe@example.com",
+  email_verified: true,
+  phone_number: "+12025551234",
+  phone_number_verified: true,
+  "cognito:username": "john.doe",
+  "cognito:groups": ["admin"],
+  "custom:department": "engineering",
+  "custom:employee_id": "EMP-12345"
+}
+```
+
+### Uso del Token Decodificado en tu Aplicación
+
+```ruby
+result = validator.validate_token(token)
+
+if result[:valid]
+  # ✅ Identificación del usuario
+  puts "User ID: #{result[:sub]}"
+  puts "Username: #{result['cognito:username'] || result[:username]}"
+
+  # ✅ Información de contacto
+  if result[:email]
+    puts "Email: #{result[:email]}"
+    puts "Email verificado: #{result[:email_verified]}"
+  end
+
+  # ✅ Autorización basada en grupos
+  if result['cognito:groups']&.include?('admin')
+    puts "Usuario es administrador"
+  end
+
+  # ✅ Validación de tiempo
+  expires_at = Time.at(result[:exp])
+  puts "Token expira: #{expires_at}"
+
+  issued_at = Time.at(result[:iat])
+  puts "Token emitido: #{issued_at}"
+
+  # ✅ Atributos custom
+  if result['custom:tenant_id']
+    puts "Tenant ID: #{result['custom:tenant_id']}"
+  end
+
+  # ✅ Scope OAuth2 (solo Access Tokens)
+  if result[:token_use] == 'access' && result[:scope]
+    scopes = result[:scope].split(' ')
+    puts "Permisos OAuth2: #{scopes}"
+  end
+end
+```
+
+### Diferencias entre Access Token e ID Token
+
+| Campo | Access Token | ID Token |
+|-------|-------------|----------|
+| **`token_use`** | `"access"` | `"id"` |
+| **`scope`** | ✅ Incluido | ❌ No incluido |
+| **`client_id`** | ✅ Incluido | ❌ No incluido |
+| **`email`** | ❌ No incluido | ✅ Incluido |
+| **`email_verified`** | ❌ No incluido | ✅ Incluido |
+| **`phone_number`** | ❌ No incluido | ✅ Incluido |
+| **Custom Attributes** | ❌ No incluido | ✅ Incluido |
+| **Uso Principal** | Autorización en APIs | Información del usuario |
+
+### Notas Importantes
+
+- **Claims opcionales**: La disponibilidad de campos como `email`, `phone_number`, y `custom:*` depende de tu configuración de Cognito
+- **Token Use**: Usa `result[:token_use]` para determinar el tipo de token y qué campos esperar
+- **Timestamps**: Los campos `exp`, `iat`, y `auth_time` están en formato Unix timestamp (segundos desde 1970-01-01)
+- **Custom Attributes**: Los atributos custom de Cognito tienen el prefijo `custom:` en sus nombres
+- **Grupos Cognito**: Los grupos se almacenan en el array `cognito:groups` cuando están configurados
+
+## 📦 Estructura de la Respuesta de Validación
+
+### Respuesta Básica de Validación
+
+```ruby
+result = validator.validate_token(token)
+
+# Estructura del resultado:
+{
+  valid: true,          # Boolean - Indica si el token es válido
+  sub: "user-id",       # String - ID del usuario
+  username: "john.doe", # String - Nombre de usuario
+  token_use: "access",  # String - Tipo de token
+  # ... más claims del token ...
+  error: nil            # String - Mensaje de error (solo si valid: false)
+}
+```
+
+### Respuesta con API Key
+
+Cuando se valida con un API Key, el resultado incluye información adicional:
+
+```ruby
+result = validator.validate(token, api_key: api_key)
+
+# Resultado completo:
+{
+  valid: true,
+  sub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  username: "john.doe",
+  token_use: "access",
+  # ... otros claims del token ...
+
+  # Información del API Key
+  api_key_data: {
+    name: "production-api-key",
+    permissions: ["auth:access", "users:read"],
+    app_id: "my-application",
+    scope: "client",
+    created_at: 1735603200000,
+    last_used: 1735689600000,
+    is_active: true,
+    metadata: {
+      created_for: "Integration Team",
+      description: "API Key for production integration",
+      environment: "production"
+    }
+  }
+}
+```
+
+### Estructura de api_key_data
+
+```ruby
+{
+  # Nombre identificador del API Key
+  name: "production-api-key",
+
+  # Lista de permisos asignados
+  permissions: ["auth:access", "users:read"],
+
+  # ID de la aplicación asociada (opcional para scope 'system')
+  app_id: "my-application",
+
+  # Alcance del API Key
+  scope: "client",  # Valores: 'app', 'system', 'client'
+
+  # Timestamp de creación (milisegundos)
+  created_at: 1735603200000,
+
+  # Timestamp del último uso (nil si nunca usado)
+  last_used: 1735689600000,
+
+  # Estado del API Key
+  is_active: true,
+
+  # Metadatos personalizados
+  metadata: {
+    created_for: "Integration Team",
+    environment: "production"
+  }
+}
+```
+
+### Diferencias entre Scopes de API Keys
+
+| Scope | Descripción | Restricciones | Uso Típico |
+|-------|-------------|---------------|------------|
+| **`system`** | Acceso transversal a todas las aplicaciones | Ninguna - acceso completo | Administración, integraciones de sistema |
+| **`app`** | Acceso limitado a una aplicación específica | Solo puede acceder al `app_id` asociado | Integraciones de aplicaciones específicas |
+| **`client`** | Acceso de cliente/frontend | Restricciones según permisos asignados | Aplicaciones frontend, móviles |
+
+### Ejemplos de Uso con API Key
+
+#### 1. Validación Básica con API Key
+
+```ruby
+result = validator.validate(token, api_key: api_key)
+
+if result[:valid]
+  puts "✅ Token válido"
+  puts "Usuario: #{result[:username]}"
+
+  # Información del API Key
+  if result[:api_key_data]
+    key_data = result[:api_key_data]
+    puts "API Key: #{key_data[:name]}"
+    puts "Scope: #{key_data[:scope]}"
+    puts "Permisos: #{key_data[:permissions].join(', ')}"
+    puts "App ID: #{key_data[:app_id]}" if key_data[:app_id]
+  end
+else
+  puts "❌ Token inválido: #{result[:error]}"
+end
+```
+
+#### 2. Autorización basada en API Key Scope
+
+```ruby
+result = validator.validate(token, api_key: api_key)
+
+if result[:valid] && result[:api_key_data]
+  key_data = result[:api_key_data]
+
+  # Verificar si tiene acceso system (transversal)
+  if key_data[:scope] == 'system'
+    puts "✅ Acceso system - puede acceder a todas las apps"
+  end
+
+  # Verificar si tiene acceso a app específica
+  if key_data[:scope] == 'app' && key_data[:app_id] == 'my-target-app'
+    puts "✅ Acceso autorizado a my-target-app"
+  end
+
+  # Verificar permisos específicos
+  if key_data[:permissions].include?('users:write')
+    puts "✅ Puede modificar usuarios"
+  end
+end
+```
+
+#### 3. Usar Metadata del API Key
+
+```ruby
+result = validator.validate(token, api_key: api_key)
+
+if result[:valid] && result[:api_key_data]
+  metadata = result[:api_key_data][:metadata]
+
+  # Acceder a información personalizada
+  puts "Creado para: #{metadata[:created_for]}"
+  puts "Descripción: #{metadata[:description]}"
+  puts "Ambiente: #{metadata[:environment]}"
+
+  # Control de acceso basado en ambiente
+  if metadata[:environment] == 'production'
+    Rails.logger.info "⚠️ API Key de producción - logging extra habilitado"
+  end
+end
+```
+
+#### 4. Tracking de Último Uso
+
+```ruby
+result = validator.validate(token, api_key: api_key)
+
+if result[:valid] && result[:api_key_data]
+  key_data = result[:api_key_data]
+
+  # Verificar última vez usado
+  if key_data[:last_used]
+    last_used_date = Time.at(key_data[:last_used] / 1000)
+    puts "Última vez usado: #{last_used_date}"
+
+    # Detectar API Keys inactivos (más de 30 días sin uso)
+    days_since_last_use = (Time.now - last_used_date) / (60 * 60 * 24)
+    if days_since_last_use > 30
+      puts "⚠️ API Key inactivo por más de 30 días"
+    end
+  else
+    puts "ℹ️ API Key nunca usado antes"
+  end
+
+  # Antigüedad del API Key
+  created_date = Time.at(key_data[:created_at] / 1000)
+  puts "Creado el: #{created_date}"
+end
+```
+
+### Respuesta con Datos Enriquecidos
+
+Cuando usas `validate_enriched()`, obtienes campos adicionales:
+
+```ruby
+result = validator.validate_enriched(token, api_key)
+
+# Resultado completo con datos enriquecidos:
+{
+  valid: true,
+  sub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  username: "john.doe",
+  email: "john.doe@example.com",
+  # ... otros campos del token ...
+
+  api_key_data: {
+    name: "production-api-key",
+    permissions: ["auth:access", "users:read"],
+    app_id: "my-application",
+    scope: "client",
+    created_at: 1735603200000,
+    last_used: 1735689600000,
+    is_active: true,
+    metadata: { environment: "production" }
+  },
+
+  user_permissions: {
+    "userId" => "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "permissions" => {
+      "my-app" => {
+        "org-123" => {
+          "roles" => ["admin", "user"],
+          "effectivePermissions" => ["users:read", "users:write"],
+          "status" => "active"
+        }
+      }
+    }
+  },
+
+  user_organizations: [
+    {
+      "appId" => "my-app",
+      "organizationId" => "org-123",
+      "roles" => ["admin"],
+      "status" => "active",
+      "effectivePermissions" => ["users:read", "users:write"]
+    }
+  ],
+
+  applications: [
+    {
+      "appId" => "my-app",
+      "name" => "My Application",
+      "isActive" => true,
+      "createdAt" => 1735603200000,
+      "updatedAt" => 1735689600000
+    }
+  ]
+}
+```
+
+### Manejo de Errores
+
+Cuando la validación falla, obtienes un mensaje de error claro:
+
+```ruby
+result = validator.validate_token(token)
+
+unless result[:valid]
+  puts "❌ Error: #{result[:error]}"
+
+  # Ejemplos de errores comunes:
+  # - "Token has expired"
+  # - "Invalid token signature"
+  # - "Invalid audience"
+  # - "Token has been revoked"
+  # - "API key is inactive"
+  # - "No access to application"
+end
+```
+
 ## Integración con Rails
 
 ### Ejemplo de Middleware

data/lib/jwt_auth_cognito/api_key_validator.rb

@@ -45,7 +45,7 @@ module JwtAuthCognito
     end
 
     def has_permission?(key_data, permission)
-      key_data[:permissions]&.include?(permission) || false
+      PermissionChecker.permission_in_list?(permission, key_data[:permissions] || [])
     end
 
     def system_api_key?(key_data)

data/lib/jwt_auth_cognito/authorization_concern.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module JwtAuthCognito
+  # Rails Concern that adds granular permission enforcement to controllers.
+  #
+  # Usage in ApplicationController (or any controller):
+  #
+  #   include JwtAuthCognito::AuthorizationConcern
+  #
+  #   # Provide the validator instance (required):
+  #   def jwt_validator
+  #     @jwt_validator ||= JwtAuthCognito::JwtValidator.new
+  #   end
+  #
+  #   # Provide the current user's Cognito sub (required):
+  #   # Override jwt_user_id — typically populated by your auth before_action.
+  #   def jwt_user_id
+  #     @jwt_user_id ||= request.env['jwt.payload']&.dig('sub')
+  #   end
+  #
+  # Then in any action or before_action:
+  #
+  #   before_action -> { authorize_permission!('fleet:vehicles:read') }
+  #
+  #   # OR require at least one of several permissions:
+  #   before_action -> { authorize_any_permission!('fleet:read', 'fleet:vehicles:read') }
+  #
+  # appId and orgId are resolved from X-App-Id / X-Organization-Id headers,
+  # falling back to params[:appId] / params[:organizationId].
+  module AuthorizationConcern
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :current_user_permissions if respond_to?(:helper_method)
+    end
+
+    # Raises ForbiddenError unless the current user has ALL of the given permissions.
+    def authorize_permission!(*permissions)
+      permissions.flatten.each do |permission|
+        next if current_user_has_permission?(permission)
+
+        log_permission_denied(permissions)
+        raise JwtAuthCognito::ForbiddenError, 'Access denied'
+      end
+    end
+
+    # Raises ForbiddenError unless the current user has AT LEAST ONE of the given permissions.
+    def authorize_any_permission!(*permissions)
+      return if permissions.flatten.any? { |p| current_user_has_permission?(p) }
+
+      log_permission_denied(permissions)
+      raise JwtAuthCognito::ForbiddenError, 'Access denied'
+    end
+
+    # Returns the full list of effective permissions for the current user/app/org context.
+    def current_user_permissions
+      @current_user_permissions ||= fetch_current_user_permissions
+    end
+
+    private
+
+    def fetch_current_user_permissions
+      uid = jwt_user_id
+      aid = jwt_app_id
+      oid = jwt_org_id
+      return [] unless uid && aid && oid
+
+      jwt_validator.resolve_effective_permissions_for(uid, aid, oid) || []
+    rescue StandardError
+      []
+    end
+
+    def current_user_has_permission?(permission)
+      PermissionChecker.permission_in_list?(permission, current_user_permissions)
+    end
+
+    # Override in your ApplicationController to provide the Cognito sub.
+    # Typically populated by a JWT authentication before_action.
+    def jwt_user_id
+      @jwt_user_id
+    end
+
+    # Resolves appId from X-App-Id header → params[:appId].
+    def jwt_app_id
+      @jwt_app_id ||=
+        request.headers['X-App-Id'] ||
+        request.headers['x-app-id'] ||
+        params[:appId]
+    end
+
+    # Resolves orgId from X-Organization-Id header → params[:organizationId].
+    def jwt_org_id
+      @jwt_org_id ||=
+        request.headers['X-Organization-Id'] ||
+        request.headers['x-organization-id'] ||
+        params[:organizationId]
+    end
+
+    # Override in your ApplicationController to provide the JwtValidator instance.
+    def jwt_validator
+      raise NotImplementedError,
+            'You must implement `jwt_validator` in your controller. ' \
+            'Example: def jwt_validator; @jwt_validator ||= JwtAuthCognito::JwtValidator.new; end'
+    end
+
+    def log_permission_denied(permissions)
+      return unless defined?(Rails)
+
+      Rails.logger.warn(
+        "[PERMISSION_DENIED] user_id=#{jwt_user_id} " \
+        "permissions=#{Array(permissions).flatten.join(',')} " \
+        "app_id=#{jwt_app_id} org_id=#{jwt_org_id}"
+      )
+    end
+  end
+end

data/lib/jwt_auth_cognito/jwks_service.rb

@@ -23,6 +23,13 @@ module JwtAuthCognito
       raise ValidationError, 'Token missing key ID (kid)' unless kid
 
       public_key = get_public_key(kid)
+      # First decode to check token type before audience validation
+      payload_preview = JWT.decode(token, nil, false).first
+
+      # Only verify audience for ID tokens, not access tokens
+      # Access tokens from Cognito might not have 'aud' claim
+      should_verify_aud = @config.cognito_client_id && payload_preview['token_use'] == 'id'
+
       decoded_token = JWT.decode(
         token,
         public_key,
@@ -31,8 +38,8 @@ module JwtAuthCognito
           algorithm: 'RS256',
           iss: @config.cognito_issuer,
           verify_iss: true,
-          aud: @config.cognito_client_id,
-          verify_aud: @config.cognito_client_id ? true : false
+          aud: should_verify_aud ? @config.cognito_client_id : nil,
+          verify_aud: should_verify_aud
         }
       )
 

data/lib/jwt_auth_cognito/jwt_validator.rb

@@ -224,6 +224,52 @@ module JwtAuthCognito
       @config.has_client_secret?
     end
 
+    # ========== PERMISSION CHECKING ==========
+
+    # Returns true if the user has the given permission in the specified app/org context.
+    def has_permission?(user_id, app_id, org_id, permission)
+      permissions = resolve_effective_permissions_for(user_id, app_id, org_id)
+      return false unless permissions
+
+      PermissionChecker.permission_in_list?(permission, permissions)
+    end
+
+    # Bulk permission check. Returns a hash with :allowed, :denied, :has_all, :has_any.
+    def check_permissions(user_id, app_id, org_id, permissions_to_check)
+      effective = resolve_effective_permissions_for(user_id, app_id, org_id) || []
+
+      allowed = []
+      denied  = []
+
+      Array(permissions_to_check).each do |perm|
+        if PermissionChecker.permission_in_list?(perm, effective)
+          allowed << perm
+        else
+          denied << perm
+        end
+      end
+
+      { allowed: allowed, denied: denied, has_all: denied.empty?, has_any: allowed.any? }
+    end
+
+    # Validates a Bearer token and checks a single permission in one call.
+    def has_permission_from_token?(token, app_id, org_id, permission)
+      result = validate_token(token)
+      return false unless result[:valid]
+
+      user_id = result[:payload]&.dig('sub')
+      return false unless user_id
+
+      has_permission?(user_id, app_id, org_id, permission)
+    end
+
+    # Exposes effective permissions via the user data service.
+    def resolve_effective_permissions_for(user_id, app_id, org_id)
+      return nil unless @user_data_service
+
+      @user_data_service.resolve_effective_permissions(user_id, app_id, org_id)
+    end
+
     def is_token_expired?(token)
       payload = decode_token(token)
       return true if payload.is_a?(Hash) && payload[:error]

data/lib/jwt_auth_cognito/permission_checker.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JwtAuthCognito
+  module PermissionChecker
+    # Checks whether a permission string is satisfied by any entry in permission_list.
+    # Supports wildcard patterns:
+    #   *                  — global wildcard (matches everything)
+    #   module:*           — prefix wildcard (matches module:action AND module:sub:action)
+    #   module:submodule:* — narrow prefix wildcard
+    #   *.action           — suffix wildcard (matches last segment across any depth)
+    def self.permission_in_list?(permission, permission_list)
+      return false if permission_list.nil? || permission_list.empty?
+      return true if permission_list.include?(permission)
+      return true if permission_list.include?('*')
+
+      permission_list.each do |p|
+        if p.end_with?(':*')
+          prefix = p[0..-3]
+          return true if permission.start_with?("#{prefix}:")
+        end
+
+        if p.end_with?('.*')
+          prefix = p[0..-3]
+          return true if permission.start_with?("#{prefix}.")
+        end
+
+        next unless p.start_with?('*.')
+
+        action = p[2..]
+        return true if permission.end_with?(":#{action}") || permission.end_with?(".#{action}")
+      end
+
+      false
+    end
+  end
+end

data/lib/jwt_auth_cognito/user_data_service.rb

@@ -192,6 +192,49 @@ module JwtAuthCognito
       end
     end
 
+    # Resolves effective permissions for a user in a specific app/org context.
+    # Fallback chain:
+    #   1. permissions:cache:{userId}:{appId}:{orgId} (handles both plain [] and { permissions: [] })
+    #   2. user:permissions:{userId} → permissions[appId][orgId].effectivePermissions
+    #   3. Compute from roles using app:roles:{appId}:{orgId}
+    # Returns nil if the user has no active membership in that org.
+    def resolve_effective_permissions(user_id, app_id, organization_id)
+      # Step 1: permissions cache
+      begin
+        raw = @redis_service.get("permissions:cache:#{user_id}:#{app_id}:#{organization_id}")
+        if raw
+          parsed = JSON.parse(raw)
+          return parsed if parsed.is_a?(Array)
+          return parsed['permissions'] if parsed.is_a?(Hash) && parsed['permissions'].is_a?(Array)
+        end
+      rescue StandardError => e
+        puts "Error reading permissions cache for #{user_id}: #{e.message}"
+      end
+
+      # Steps 2 & 3: user:permissions
+      begin
+        raw = @redis_service.get("user:permissions:#{user_id}")
+        return nil unless raw
+
+        data = JSON.parse(raw)
+        org_data = data.dig('permissions', app_id, organization_id)
+        return nil unless org_data
+        return nil unless org_data['status'] == 'active'
+
+        effective = org_data['effectivePermissions']
+        return effective if effective.is_a?(Array)
+
+        # Step 3: compute from role definitions
+        roles = org_data['roles']
+        return [] unless roles.is_a?(Array) && !roles.empty?
+
+        compute_permissions_from_roles(app_id, organization_id, roles)
+      rescue StandardError => e
+        puts "Error resolving effective permissions for #{user_id}: #{e.message}"
+        nil
+      end
+    end
+
     def get_effective_permissions(user_id, app_id, organization_id)
       return nil unless @config[:include_effective_permissions]
 
@@ -328,5 +371,24 @@ module JwtAuthCognito
       @cache[key] = value
       @cache_timestamps[key] = Time.now.to_i
     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)
+
+      permissions = []
+      role_names.each do |role_name|
+        role = roles_data[role_name]
+        next unless role.is_a?(Hash)
+
+        role_permissions = role['permissions']
+        permissions.concat(role_permissions) if role_permissions.is_a?(Array)
+      end
+
+      permissions.uniq
+    rescue StandardError => e
+      puts "Error computing permissions from roles: #{e.message}"
+      []
+    end
   end
 end

data/lib/jwt_auth_cognito/version.rb

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

data/lib/jwt_auth_cognito.rb

@@ -9,6 +9,7 @@ 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/error_utils'
+require_relative 'jwt_auth_cognito/permission_checker'
 require_relative 'jwt_auth_cognito/jwt_validator'
 
 module JwtAuthCognito
@@ -16,6 +17,7 @@ module JwtAuthCognito
   class ValidationError < Error; end
   class BlacklistError < Error; end
   class ConfigurationError < Error; end
+  class ForbiddenError < Error; end
 
   # Specific JWT error types (matching Node.js implementation)
   class TokenExpiredError < ValidationError; end
@@ -71,3 +73,6 @@ end
 
 # Cargar tareas Rake si estamos en Rails
 require_relative 'jwt_auth_cognito/railtie' if defined?(Rails::Railtie)
+
+# AuthorizationConcern requires ActiveSupport (available in Rails apps)
+require_relative 'jwt_auth_cognito/authorization_concern' if defined?(ActiveSupport::Concern)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jwt_auth_cognito
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta.9
+  version: 1.0.0.pre.beta.11
 platform: ruby
 authors:
 - The Optimal
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-22 00:00:00.000000000 Z
+date: 2026-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-ssm
@@ -189,10 +189,12 @@ files:
 - lib/generators/jwt_auth_cognito/templates/jwt_auth_cognito.rb.erb
 - lib/jwt_auth_cognito.rb
 - lib/jwt_auth_cognito/api_key_validator.rb
+- lib/jwt_auth_cognito/authorization_concern.rb
 - lib/jwt_auth_cognito/configuration.rb
 - lib/jwt_auth_cognito/error_utils.rb
 - lib/jwt_auth_cognito/jwks_service.rb
 - lib/jwt_auth_cognito/jwt_validator.rb
+- lib/jwt_auth_cognito/permission_checker.rb
 - lib/jwt_auth_cognito/railtie.rb
 - lib/jwt_auth_cognito/redis_service.rb
 - lib/jwt_auth_cognito/ssm_service.rb