Metadata-Version: 2.4
Name: aws-cognito-validation
Version: 0.1.0
Summary: Validación de JWT de Amazon Cognito contra uno o varios User Pools (multi-pool).
Author: Tristan Lino
License: MIT
Project-URL: Homepage, https://github.com/TristanLinoD
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyJWT[crypto]>=2.8

# aws-cognito-validation

Validación de JWT de Amazon Cognito contra uno o varios User Pools
(multi-pool). Útil cuando distintos frontends/servicios loguean usuarios en
distintos User Pools (ej. login nativo vs. login federado con un identity
provider externo como Google) y un mismo backend necesita aceptar tokens
de cualquiera de esos pools.

## Instalación

```bash
pip install aws-cognito-validation
```

## Uso

```python
from aws_cognito_validation import (
    parse_allowed_pools,
    pool_for_issuer,
    get_unverified_issuer,
    validate_cognito_jwt,
)

# COGNITO_ALLOWED_POOLS como variable de entorno (JSON estándar):
# COGNITO_ALLOWED_POOLS=["us-east-1_AAAAAAAAA:us-east-1", "us-east-1_BBBBBBBBB:us-east-1"]
pools = parse_allowed_pools(os.environ["COGNITO_ALLOWED_POOLS"])

def get_current_token(token: str) -> dict:
    issuer = get_unverified_issuer(token)
    pool = pool_for_issuer(issuer, pools)
    if pool is None:
        raise PermissionError("Issuer no permitido")

    is_valid, message, decoded = validate_cognito_jwt(token, pool)
    if not is_valid:
        raise PermissionError(message)

    return decoded
```

También se soporta la forma compacta separada por comas, sin JSON:

```
COGNITO_ALLOWED_POOLS=us-east-1_AAAAAAAAA:us-east-1,us-east-1_BBBBBBBBB:us-east-1
```

## Cómo funciona la validación multi-pool

1. Se lee el claim `iss` del token **sin verificar la firma todavía**
   (`get_unverified_issuer`).
2. Ese `iss` se compara contra una whitelist fija de pools conocidos por el
   backend (`pool_for_issuer`) — nunca se confía en el `iss` del token por
   sí solo para decidir con qué llave validar sin pasar por esta
   whitelist.
3. Solo si el `iss` coincide con un pool de la whitelist, se descarga (o se
   toma de caché, vía `PyJWKClient`) el JWKS de **ese** pool y se valida la
   firma real, el `iss` otra vez, `token_use` y `exp` (`validate_cognito_jwt`).

## Notas

- Los access tokens de Cognito no llevan el claim `aud` (solo los id
  tokens sí) — la librería no valida audience. Si necesitas restringir por
  `client_id`/`aud`, revísalo aparte sobre el dict decodificado que
  devuelve `validate_cognito_jwt`.
- El manejo de scopes (ej. permitir solo ciertos scopes por endpoint) no es
  parte de esta librería — queda a cargo de cada proyecto sobre el
  `decoded["scope"]` que devuelve la validación.

## Licencia

MIT
