jwks-multi 0.3.1__py3-none-any.whl

jwks_multi/__init__.py

@@ -0,0 +1,6 @@
+from .jwks_multi_verifier import decode_token, get_public_keys
+
+__all__ = [
+    'decode_token',
+    'get_public_keys',
+]

jwks_multi/extentions/jwt_clains.py

@@ -0,0 +1,29 @@
+import time
+
+from authlib.jose import JWTClaims
+
+
+class ExtendedJWTClaims(JWTClaims):
+    def __init__(self, *args: list, **kwargs: dict) -> None:
+        super().__init__(*args, **kwargs)
+        self.claims_with_expiration = ['exp', 'nbf', 'iat']
+
+    def validate(
+        self,
+        now: float | None = None,
+        leeway: float = 0,
+    ) -> None:
+        if now is None:
+            now = float(time.time())
+        self._validate_essential_claims()
+        for key, values in self.options.items():
+            if key not in self.REGISTERED_CLAIMS:
+                self._validate_claim_value(key)
+                continue
+            if values.get('verify') is False:
+                continue
+            validation = getattr(self, f'validate_{key}')
+            if key in self.claims_with_expiration:
+                validation(now, leeway)
+            else:
+                validation()

jwks_multi/jwks_multi_verifier.py

@@ -0,0 +1,174 @@
+import asyncio
+import logging
+import time
+from typing import Any
+
+import httpx
+from authlib.common.errors import AuthlibBaseError
+from authlib.jose import JsonWebKey, JWTClaims, KeySet, jwt
+
+from jwks_multi.extentions.jwt_clains import ExtendedJWTClaims
+
+logger = logging.getLogger('jwks_multi')
+
+_jwk_set: dict[str, dict[str, list[Any] | float]] = {}
+_jwk_locks: dict[str, asyncio.Lock] = {}
+
+
+async def get_public_keys(
+    jwks_urls: list[str],
+    pre_public_keys: dict[str, Any],
+    *,
+    cache_jwk_set: bool = True,
+    jwks_ttl: float | None = None,
+    jwks_timeout: float = 5.0,
+) -> KeySet:
+    if pre_public_keys:
+        _add_keys_from_jwks(
+            uri='localhost',
+            jwks=pre_public_keys,
+        )
+    await _get_remote_jwks(
+        jwks_urls,
+        jwks_timeout,
+        jwks_ttl,
+        cache_jwk_set=cache_jwk_set,
+    )
+    return _get_jwks_set()
+
+
+async def decode_token(
+    token: str,
+    key: KeySet,
+    options: dict[str, bool] | None = None,
+    issuers: list[str] | None = None,
+    audiences: list[str] | None = None,
+) -> JWTClaims:
+    if not options:
+        options = {}
+    claims = jwt.decode(
+        s=token,
+        key=key,
+        claims_cls=ExtendedJWTClaims,
+        claims_options={
+            'iss': {
+                'essential': True,
+                'verify': bool(issuers),
+                'values': issuers,
+            },
+            'aud': {
+                'essential': True,
+                'verify': bool(audiences),
+                'values': audiences,
+            },
+            'sub': {
+                'essential': True,
+                'verify': options.get('verify_sub', True),
+            },
+            'exp': {
+                'essential': False,
+                'verify': options.get('verify_exp', True),
+            },
+            'nbf': {
+                'essential': False,
+                'verify': options.get('verify_nbf', True),
+            },
+            'iat': {
+                'essential': True,
+                'verify': options.get('verify_iat', True),
+            },
+            'jti': {
+                'essential': True,
+                'verify': options.get('verify_jti', True),
+            },
+        },
+    )
+    claims.validate(leeway=options.get('leeway') or 0)
+    return claims
+
+
+def _get_jwks_set() -> KeySet:
+    jwks_set = []
+    for jwk in _jwk_set.values():
+        jwks_set.extend(jwk['keys'])
+    if not jwks_set:
+        raise AuthlibBaseError(
+            error='missing_keys',
+            description=(
+                'No JWKS keys available. '
+                'Verify the provided URLs and pre_public_keys.'
+            ),
+        )
+    return KeySet(jwks_set)
+
+
+def _add_keys_from_jwks(
+    uri: str,
+    jwks: dict[str, list[dict[str, Any]]],
+    expires_at: float = -1,
+) -> None:
+    if jwks and 'keys' in jwks:
+        key_set = JsonWebKey.import_key_set(jwks)
+        _jwk_set[uri] = {'keys': key_set.keys, 'expires_at': expires_at}
+
+
+def _is_cached(now: float, uri: str, *, cache_jwk_set: bool) -> bool:
+    if not cache_jwk_set:
+        return False
+    jwks_data = _jwk_set.get(uri)
+    if not jwks_data:
+        return False
+    expires = jwks_data.get('expires_at') or -1
+    return expires == -1 or now < expires
+
+
+def _get_uri_lock(uri: str) -> asyncio.Lock:
+    lock = _jwk_locks.get(uri)
+    if lock is None:
+        lock = asyncio.Lock()
+        _jwk_locks[uri] = lock
+    return lock
+
+
+async def _get_remote_jwks(
+    jwks_urls: list[str],
+    jwks_timeout: float = 5.0,
+    jwks_ttl: float | None = None,
+    *,
+    cache_jwk_set: bool = True,
+) -> dict[str, dict[str, list[Any] | float]]:
+    try:
+        async with httpx.AsyncClient(timeout=jwks_timeout) as client:
+            for uri in jwks_urls:
+                if uri == 'localhost':
+                    continue
+                if _is_cached(time.time(), uri, cache_jwk_set=cache_jwk_set):
+                    continue
+                async with _get_uri_lock(uri):
+                    if _is_cached(
+                        time.time(),
+                        uri,
+                        cache_jwk_set=cache_jwk_set,
+                    ):
+                        continue
+                    logger.info(
+                        '[ExtendedPyJWKClient] Fetching data from %s',
+                        uri,
+                    )
+                    response = await client.get(uri)
+                    response.raise_for_status()
+                    jwks_data = response.json()
+
+                    expires_at = -1
+                    if jwks_ttl:
+                        expires_at = time.time() + jwks_ttl
+                    _add_keys_from_jwks(
+                        uri=uri,
+                        jwks=jwks_data,
+                        expires_at=expires_at,
+                    )
+
+    except httpx.HTTPError:
+        logger.exception('Fail to fetch data from the url %s', uri)
+
+    return _jwk_set

jwks_multi-0.3.1.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: jwks-multi
+Version: 0.3.1
+Summary: JWT verifier with support for multiple JWKS endpoints and local fallback keys
+Author: Squad Risco Transacional
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.luizalabs.com/luizalabs/risco-360/libs/jwks-multi
+Project-URL: Issues, https://gitlab.luizalabs.com/luizalabs/risco-360/libs/jwks-multi/-/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: authlib>=1.6.9
+Requires-Dist: httpx>=0.28.1
+Dynamic: license-file
+
+# JWKs Multi Verifier
+
+Biblioteca Python para validacao de JWT com suporte a multiplas fontes JWKS, cache e chaves locais de fallback.
+
+API publica principal:
+
+- `from jwks_multi import get_public_keys, decode_token`
+
+## Instalacao via URL (Git)
+
+### pip
+
+```bash
+pip install "git+ssh://git@<repo>/jwks-multi.git"
+pip install "git+ssh://git@<repo>/jwks-multi.git@main"
+pip install "git+ssh://git@<repo>/jwks-multi.git@v<tag>"
+pip install "git+ssh://git@<repo>/jwks-multi.git@<commit_sha>"
+```
+
+## Uso
+
+### Fluxo basico
+
+```python
+import asyncio
+
+from jwks_multi import get_public_keys, decode_token
+
+
+async def main() -> None:
+	key_set = await get_public_keys(
+		jwks_urls=["https://idp.exemplo.com/.well-known/jwks.json"],
+		pre_public_keys={},
+	)
+
+	claims = await decode_token(
+		token="<jwt>",
+		key=key_set,
+		options={},
+		issuers=["https://idp.exemplo.com/"],
+		audiences=["minha-api"],
+	)
+
+	print(claims)
+
+
+asyncio.run(main())
+```
+
+### Parametros disponiveis
+
+#### `get_public_keys(...)`
+
+Retorna um `KeySet` com a uniao de chaves locais (`pre_public_keys`) e chaves remotas (`jwks_urls`).
+
+| Parametro | Tipo | Padrao | Descricao |
+| --- | --- | --- | --- |
+| `jwks_urls` | `list[str]` | obrigatorio | Lista de endpoints JWKS remotos. |
+| `pre_public_keys` | `dict[str, Any]` | obrigatorio | JWKS local no formato `{"keys": [...]}` para fallback. |
+| `cache_jwk_set` | `bool` | `True` | Habilita/desabilita cache em memoria por URI. |
+| `jwks_ttl` | `int \| float \| None` | `None` | Tempo de vida (segundos) do cache remoto. `None` significa sem expiracao. |
+| `jwks_timeout` | `int \| float` | `5.0` | Timeout (segundos) das requisicoes HTTP para JWKS remoto. |
+
+#### `decode_token(...)`
+
+Decodifica e valida o token com `ExtendedJWTClaims`.
+
+| Parametro | Tipo | Padrao | Descricao |
+| --- | --- | --- | --- |
+| `token` | `str` | obrigatorio | JWT serializado. |
+| `key` | `KeySet` | obrigatorio | Chaves retornadas por `get_public_keys(...)`. |
+| `options` | `dict[str, bool \| float] \| None` | `None` | Controle fino das validacoes (`verify_sub`, `verify_exp`, `verify_nbf`, `verify_iat`, `verify_jti`). Inclui `leeway` (folga em segundos para validacao temporal). |
+| `issuers` | `list[str] \| None` | `None` | Lista de emissores aceitos para claim `iss`. |
+| `audiences` | `list[str] \| None` | `None` | Lista de audiencias aceitas para claim `aud`. |
+
+### Exemplo avancado
+
+```python
+import asyncio
+
+from jwks_multi import get_public_keys, decode_token
+
+
+async def validate(token: str) -> dict:
+	key_set = await get_public_keys(
+		jwks_urls=[
+			"https://idp-a.exemplo.com/.well-known/jwks.json",
+			"https://idp-b.exemplo.com/.well-known/jwks.json",
+		],
+		pre_public_keys={
+			"keys": [
+				{
+					"kty": "RSA",
+					"kid": "local-fallback-kid",
+					"use": "sig",
+					"alg": "RS256",
+					"n": "<modulus>",
+					"e": "AQAB",
+				}
+			]
+		},
+		cache_jwk_set=True,
+		jwks_ttl=300,
+		jwks_timeout=2.5,
+	)
+
+	claims = await decode_token(
+		token=token,
+		key=key_set,
+		options={
+			"verify_sub": True,
+			"verify_exp": True,
+			"verify_nbf": True,
+			"verify_iat": True,
+			"verify_jti": True,
+			"leeway": 5,
+		},
+		issuers=["https://idp-a.exemplo.com/", "https://idp-b.exemplo.com/"],
+		audiences=["api-interna"],
+	)
+
+	return dict(claims)
+
+
+# asyncio.run(validate("<jwt>"))
+```
+
+### Observacoes importantes
+
+- O cache e mantido em memoria no processo e separado por URI de JWKS.
+- Quando `jwks_ttl=None`, as chaves remotas nao expiram (ate reinicio do processo).
+- URLs com valor literal `"localhost"` sao tratadas como pseudo-origem local e nao geram chamada HTTP.
+
+## Desenvolvimento local
+
+```bash
+pip install -e .
+python -c "from jwks_multi import get_public_keys, decode_token; print('API loaded successfully')"
+```
+
+## Changelog
+
+O Changelog é gerado pela ferramenta [towncrier](https://github.com/twisted/towncrier).
+
+Para criar o changelog da sua alteração, é necessário criar um arquivo em `changelog.d` com o sufixo desejado:
+
+- ``.feature``: para nova funcionalidade
+- ``.bugfix``: para correção de bug.
+- ``.doc``: para uma melhoria na documentação.
+- ``.removal``: para uma suspensão de uso ou remoção de API pública.
+- ``.misc``: para uma alteração que não é de interesse do usuário.
+- ``.health``: para refatoração, atualização de dependências.
+- ``.security``: para correção de vulnerabilidade de segurança.
+
+É recomendado como uso do prefixo o código do card referente ao MR.
+Ex: ```TST123-xablau.feature```
+
+Cada entrada do changelog deve estar em um arquivo separado.
+
+### Categorias do changelog
+
+As categorias do changelog seguem o padrão [Keep a Changelog](https://keepachangelog.com/en/1.1.0/):
+
+- **Added**: Nova funcionalidade.
+- **Changed**: Alteração em funcionalidade existente (refatoração, atualização de dependências, melhorias internas).
+- **Fixed**: Correção de bug.
+- **Removed**: Remoção de funcionalidade.
+- **Deprecated**: Funcionalidade que será removida em breve.
+- **Security**: Correção de vulnerabilidade de segurança.

jwks_multi-0.3.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+jwks_multi/__init__.py,sha256=5mOd-u1gE3Y7aEsatFLgbB1hxoEHwqNanGFmk_L362k,121
+jwks_multi/jwks_multi_verifier.py,sha256=D2n8NG2GZSyR_V2eaO1qVVPs4LMYA69Xn3AmZCbBlDo,4908
+jwks_multi/extentions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jwks_multi/extentions/jwt_clains.py,sha256=FPSwIoBsStrkwb-wyHrV9gEzOwDB8yyCxWSVdcSKta8,900
+jwks_multi-0.3.1.dist-info/licenses/LICENSE,sha256=ndtLWpaVLOp3HXS3jMqO8WXCDMMDg_fTwG13Eb-Iy5c,1067
+jwks_multi-0.3.1.dist-info/METADATA,sha256=cNLpDlEuOamk_77v_Z5eNuq2ewRnZ2ZCQcz4I_715A4,5756
+jwks_multi-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+jwks_multi-0.3.1.dist-info/top_level.txt,sha256=anTetxy9IaTup2gZ0NR3uQ-n31loTEg9JhDkYWCwajk,11
+jwks_multi-0.3.1.dist-info/RECORD,,

jwks_multi-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jwks_multi-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Luizalabs
+
+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.
+

jwks_multi-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+jwks_multi