jwks-client 0.1.0__tar.gz

jwks_client-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: jwks-client
+Version: 0.1.0
+Summary: Async JWKS client for verifying JWTs, with key caching, resilient fetching, and Litestar and FastAPI integrations
+Keywords: jwks,jwt,jwk,oidc,oauth2,authentication,asyncio,litestar,fastapi,python
+Author: Artur Shiriev
+Author-email: Artur Shiriev <me@shiriev.ru>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Typing :: Typed
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Litestar
+Requires-Dist: pyjwt[crypto]>=2.15.1
+Requires-Dist: httpware>=0.15.0,<1
+Requires-Dist: httpx2>=2.0.0,<3
+Requires-Dist: fastapi>=0.115 ; extra == 'fastapi'
+Requires-Dist: litestar>=2.19 ; extra == 'litestar'
+Requires-Python: >=3.11, <4
+Project-URL: Homepage, https://modern-python.org
+Project-URL: Repository, https://github.com/modern-python/jwks-client
+Project-URL: Issues, https://github.com/modern-python/jwks-client/issues
+Project-URL: Changelog, https://github.com/modern-python/jwks-client/releases
+Provides-Extra: fastapi
+Provides-Extra: litestar
+Description-Content-Type: text/markdown
+
+# jwks-client
+
+An async JWKS client for verifying JWTs, with key caching, resilient fetching over
+[httpware](https://github.com/modern-python/httpware), and Litestar and FastAPI integrations. It
+fetches an identity provider's JSON Web Key Set, caches it, refetches on key rotation without
+letting unknown `kid`s flood the provider, keeps serving the last good keys through an outage, and
+verifies tokens with [PyJWT](https://github.com/jpadilla/pyjwt).
+
+```python
+from jwks_client import JWKSClient, JWTVerifier
+
+
+jwks = JWKSClient("https://idp.example.com/.well-known/jwks.json")
+verifier = JWTVerifier(jwks, algorithms=["RS256"], audience="my-api", issuer="https://idp.example.com")
+
+claims = await verifier.verify(token)
+```
+
+## Install
+
+```bash
+pip install jwks-client              # core
+pip install jwks-client[litestar]    # + Litestar middleware
+pip install jwks-client[fastapi]     # + FastAPI dependency
+```
+
+## Verifying tokens
+
+`JWTVerifier` fixes the policy once (`algorithms`, `audience`, `issuer`, `leeway`, `options`), so no
+call site can forget a check. `verify()` checks the token's `alg` against `algorithms` before any
+network call, finds the key by the token's `kid`, verifies the signature, then validates `exp`,
+`nbf`, `aud`, and `iss` through `jwt.decode`. When `audience` or `issuer` is set, a token without
+that claim is rejected.
+
+For a key published without an `alg`, the key is bound to the token's `alg`, provided it is in
+`algorithms` and fits the key type, so an RSA key can verify `PS256` as well as `RS256`.
+
+The same check is available per call as `JWKSClient.decode(token, algorithms=..., ...)`. To verify
+yourself, take the key and call PyJWT directly:
+
+```python
+import jwt
+
+
+key = await jwks.get_signing_key_from_jwt(token)  # or get_signing_key(kid)
+claims = jwt.decode(token, key, algorithms=["RS256"], audience="my-api")
+```
+
+## Errors
+
+| Raised | When | Integrations answer |
+|---|---|---|
+| `jwt.InvalidTokenError` subclasses | The token is malformed, expired, badly signed, or its claims fail | 401 |
+| `KeyNotFoundError` (also a `jwt.InvalidTokenError`) | No key in the set matches the token's `kid` | 401 |
+| `JWKSFetchError` | The JWKS endpoint failed and no usable cached keys remain; `__cause__` holds the httpware error | 503 |
+
+All of the package's own errors inherit `JWKSError`.
+
+## Litestar
+
+```python
+import litestar
+from litestar.middleware import DefineMiddleware
+from litestar.openapi.config import OpenAPIConfig
+
+from jwks_client.litestar import JWKSAuthMiddleware, create_openapi_security_config
+
+
+app = litestar.Litestar(
+    route_handlers=[...],
+    middleware=[
+        DefineMiddleware(
+            JWKSAuthMiddleware,
+            verifier=verifier,
+            user_parser=lambda claims: User.model_validate(claims),  # optional
+            exclude=["/health", "/docs"],
+        ),
+    ],
+    openapi_config=OpenAPIConfig(title="my-api", version="1", **create_openapi_security_config()),
+)
+```
+
+`request.auth` holds the verified claims. `request.user` holds `user_parser(claims)`, or the claims
+when no parser is given; a parser returning `None` rejects the request with 401. `exclude`,
+`exclude_from_auth_key`, `exclude_http_methods`, and `scopes` are Litestar's own
+`AbstractAuthenticationMiddleware` options.
+
+## FastAPI
+
+```python
+import typing
+
+import fastapi
+
+from jwks_client.fastapi import JWKSBearer
+
+
+bearer = JWKSBearer(verifier, user_parser=lambda claims: User.model_validate(claims))
+
+
+@app.get("/me")
+async def me(user: typing.Annotated[User, fastapi.Security(bearer)]) -> User:
+    return user
+```
+
+The dependency returns `user_parser(claims)`, or the claims when no parser is given, and adds a
+`Bearer` security scheme to the OpenAPI schema.
+
+## OpenAPI and OpenID Connect
+
+Both integrations declare an HTTP `Bearer` scheme. Pass `openid_configuration_url`, the provider's
+discovery document at `/.well-known/openid-configuration` rather than its JWKS URL, to declare an
+`OpenIdConnect` scheme as well (Litestar) or instead (FastAPI).
+
+## Resolving the verifier lazily
+
+Both integrations take a `TokenVerifier`: anything with an async `verify(token)`. A verifier that
+lives in a DI container can be resolved on each call by a small wrapper:
+
+```python
+class ContainerVerifier:
+    async def verify(self, token: str) -> dict[str, typing.Any]:
+        return await container.resolve(JWTVerifier).verify(token)
+
+
+DefineMiddleware(JWKSAuthMiddleware, verifier=ContainerVerifier())
+```
+
+The container must hand back the same verifier every time: a new `JWKSClient` per request starts
+with no keys and fetches the key set on every request.
+
+## Caching
+
+| Parameter | Default | Effect |
+|---|---|---|
+| `ttl` | `300` s | How long a fetched key set is used before it is refetched. |
+| `refetch_cooldown` | `30` s | Minimum time between fetches triggered by an unknown `kid`, and between retries after a failed fetch. |
+| `stale_if_error` | `3600` s | How long past `ttl` the last good key set keeps being served while refetches fail. |
+
+Concurrent callers share one fetch. Call `await jwks.refresh()` at startup to fetch keys before the
+first request.
+
+## HTTP client
+
+Without `http_client=`, the client builds and owns an `httpware.AsyncClient` with a 10 s timeout, a
+1 MiB response cap, a circuit breaker, and retries, and closes it in `aclose()` (or on leaving
+`async with`). Pass your own `httpware.AsyncClient` to choose the middleware; the client never
+closes one it did not create:
+
+```python
+import httpware
+
+
+http_client = httpware.AsyncClient(
+    timeout=5.0,
+    max_response_body_bytes=1024 * 1024,
+    middleware=[httpware.AsyncCircuitBreaker(failure_threshold=3), httpware.AsyncRetry(max_attempts=2)],
+)
+jwks = JWKSClient("https://idp.example.com/.well-known/jwks.json", http_client=http_client)
+```
+
+A `JWKSClient` belongs to one event loop. Create one per process and share it across requests.
+
+## Testing
+
+`jwks_client.testing` signs real tokens, so tests exercise the same verification as production:
+
+```python
+from jwks_client.testing import FakeIdentityProvider
+
+
+idp = FakeIdentityProvider()
+verifier = JWTVerifier(idp.create_jwks_client(), algorithms=["RS256"], audience="my-api", issuer=idp.issuer)
+token = idp.issue_token({"sub": "user-1", "aud": "my-api"})
+```
+
+`StaticTokenVerifier({"dev-token": {"sub": "developer"}})` accepts fixed tokens without any
+signature, for local development only.
+
+## 📦 [PyPI](https://pypi.org/project/jwks-client) · 📝 [License](https://github.com/modern-python/jwks-client/blob/main/LICENSE)
+
+## Part of `modern-python`
+
+Browse the full list of templates and libraries in
+[`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.

jwks_client-0.1.0/README.md

@@ -0,0 +1,185 @@
+# jwks-client
+
+An async JWKS client for verifying JWTs, with key caching, resilient fetching over
+[httpware](https://github.com/modern-python/httpware), and Litestar and FastAPI integrations. It
+fetches an identity provider's JSON Web Key Set, caches it, refetches on key rotation without
+letting unknown `kid`s flood the provider, keeps serving the last good keys through an outage, and
+verifies tokens with [PyJWT](https://github.com/jpadilla/pyjwt).
+
+```python
+from jwks_client import JWKSClient, JWTVerifier
+
+
+jwks = JWKSClient("https://idp.example.com/.well-known/jwks.json")
+verifier = JWTVerifier(jwks, algorithms=["RS256"], audience="my-api", issuer="https://idp.example.com")
+
+claims = await verifier.verify(token)
+```
+
+## Install
+
+```bash
+pip install jwks-client              # core
+pip install jwks-client[litestar]    # + Litestar middleware
+pip install jwks-client[fastapi]     # + FastAPI dependency
+```
+
+## Verifying tokens
+
+`JWTVerifier` fixes the policy once (`algorithms`, `audience`, `issuer`, `leeway`, `options`), so no
+call site can forget a check. `verify()` checks the token's `alg` against `algorithms` before any
+network call, finds the key by the token's `kid`, verifies the signature, then validates `exp`,
+`nbf`, `aud`, and `iss` through `jwt.decode`. When `audience` or `issuer` is set, a token without
+that claim is rejected.
+
+For a key published without an `alg`, the key is bound to the token's `alg`, provided it is in
+`algorithms` and fits the key type, so an RSA key can verify `PS256` as well as `RS256`.
+
+The same check is available per call as `JWKSClient.decode(token, algorithms=..., ...)`. To verify
+yourself, take the key and call PyJWT directly:
+
+```python
+import jwt
+
+
+key = await jwks.get_signing_key_from_jwt(token)  # or get_signing_key(kid)
+claims = jwt.decode(token, key, algorithms=["RS256"], audience="my-api")
+```
+
+## Errors
+
+| Raised | When | Integrations answer |
+|---|---|---|
+| `jwt.InvalidTokenError` subclasses | The token is malformed, expired, badly signed, or its claims fail | 401 |
+| `KeyNotFoundError` (also a `jwt.InvalidTokenError`) | No key in the set matches the token's `kid` | 401 |
+| `JWKSFetchError` | The JWKS endpoint failed and no usable cached keys remain; `__cause__` holds the httpware error | 503 |
+
+All of the package's own errors inherit `JWKSError`.
+
+## Litestar
+
+```python
+import litestar
+from litestar.middleware import DefineMiddleware
+from litestar.openapi.config import OpenAPIConfig
+
+from jwks_client.litestar import JWKSAuthMiddleware, create_openapi_security_config
+
+
+app = litestar.Litestar(
+    route_handlers=[...],
+    middleware=[
+        DefineMiddleware(
+            JWKSAuthMiddleware,
+            verifier=verifier,
+            user_parser=lambda claims: User.model_validate(claims),  # optional
+            exclude=["/health", "/docs"],
+        ),
+    ],
+    openapi_config=OpenAPIConfig(title="my-api", version="1", **create_openapi_security_config()),
+)
+```
+
+`request.auth` holds the verified claims. `request.user` holds `user_parser(claims)`, or the claims
+when no parser is given; a parser returning `None` rejects the request with 401. `exclude`,
+`exclude_from_auth_key`, `exclude_http_methods`, and `scopes` are Litestar's own
+`AbstractAuthenticationMiddleware` options.
+
+## FastAPI
+
+```python
+import typing
+
+import fastapi
+
+from jwks_client.fastapi import JWKSBearer
+
+
+bearer = JWKSBearer(verifier, user_parser=lambda claims: User.model_validate(claims))
+
+
+@app.get("/me")
+async def me(user: typing.Annotated[User, fastapi.Security(bearer)]) -> User:
+    return user
+```
+
+The dependency returns `user_parser(claims)`, or the claims when no parser is given, and adds a
+`Bearer` security scheme to the OpenAPI schema.
+
+## OpenAPI and OpenID Connect
+
+Both integrations declare an HTTP `Bearer` scheme. Pass `openid_configuration_url`, the provider's
+discovery document at `/.well-known/openid-configuration` rather than its JWKS URL, to declare an
+`OpenIdConnect` scheme as well (Litestar) or instead (FastAPI).
+
+## Resolving the verifier lazily
+
+Both integrations take a `TokenVerifier`: anything with an async `verify(token)`. A verifier that
+lives in a DI container can be resolved on each call by a small wrapper:
+
+```python
+class ContainerVerifier:
+    async def verify(self, token: str) -> dict[str, typing.Any]:
+        return await container.resolve(JWTVerifier).verify(token)
+
+
+DefineMiddleware(JWKSAuthMiddleware, verifier=ContainerVerifier())
+```
+
+The container must hand back the same verifier every time: a new `JWKSClient` per request starts
+with no keys and fetches the key set on every request.
+
+## Caching
+
+| Parameter | Default | Effect |
+|---|---|---|
+| `ttl` | `300` s | How long a fetched key set is used before it is refetched. |
+| `refetch_cooldown` | `30` s | Minimum time between fetches triggered by an unknown `kid`, and between retries after a failed fetch. |
+| `stale_if_error` | `3600` s | How long past `ttl` the last good key set keeps being served while refetches fail. |
+
+Concurrent callers share one fetch. Call `await jwks.refresh()` at startup to fetch keys before the
+first request.
+
+## HTTP client
+
+Without `http_client=`, the client builds and owns an `httpware.AsyncClient` with a 10 s timeout, a
+1 MiB response cap, a circuit breaker, and retries, and closes it in `aclose()` (or on leaving
+`async with`). Pass your own `httpware.AsyncClient` to choose the middleware; the client never
+closes one it did not create:
+
+```python
+import httpware
+
+
+http_client = httpware.AsyncClient(
+    timeout=5.0,
+    max_response_body_bytes=1024 * 1024,
+    middleware=[httpware.AsyncCircuitBreaker(failure_threshold=3), httpware.AsyncRetry(max_attempts=2)],
+)
+jwks = JWKSClient("https://idp.example.com/.well-known/jwks.json", http_client=http_client)
+```
+
+A `JWKSClient` belongs to one event loop. Create one per process and share it across requests.
+
+## Testing
+
+`jwks_client.testing` signs real tokens, so tests exercise the same verification as production:
+
+```python
+from jwks_client.testing import FakeIdentityProvider
+
+
+idp = FakeIdentityProvider()
+verifier = JWTVerifier(idp.create_jwks_client(), algorithms=["RS256"], audience="my-api", issuer=idp.issuer)
+token = idp.issue_token({"sub": "user-1", "aud": "my-api"})
+```
+
+`StaticTokenVerifier({"dev-token": {"sub": "developer"}})` accepts fixed tokens without any
+signature, for local development only.
+
+## 📦 [PyPI](https://pypi.org/project/jwks-client) · 📝 [License](https://github.com/modern-python/jwks-client/blob/main/LICENSE)
+
+## Part of `modern-python`
+
+Browse the full list of templates and libraries in
+[`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.

jwks_client-0.1.0/jwks_client/__init__.py

@@ -0,0 +1,14 @@
+from jwks_client.client import JWKSClient
+from jwks_client.errors import JWKSError, JWKSFetchError, KeyNotFoundError
+from jwks_client.verifier import JWTVerifier, TokenVerifier, extract_bearer_token
+
+
+__all__ = [
+    "JWKSClient",
+    "JWKSError",
+    "JWKSFetchError",
+    "JWTVerifier",
+    "KeyNotFoundError",
+    "TokenVerifier",
+    "extract_bearer_token",
+]

jwks_client-0.1.0/jwks_client/client.py

@@ -0,0 +1,221 @@
+import asyncio
+import dataclasses
+import datetime
+import logging
+import math
+import time
+import typing
+import urllib.parse
+from collections.abc import Callable, Container, Iterable, Sequence
+
+import httpware
+import jwt
+from jwt.types import Options
+
+from jwks_client.errors import JWKSFetchError, KeyNotFoundError
+
+
+LOGGER: typing.Final = logging.getLogger("jwks_client")
+DEFAULT_TTL: typing.Final = 300.0
+DEFAULT_REFETCH_COOLDOWN: typing.Final = 30.0
+DEFAULT_STALE_IF_ERROR: typing.Final = 3600.0
+DEFAULT_TIMEOUT: typing.Final = 10.0
+DEFAULT_MAX_RESPONSE_BODY_BYTES: typing.Final = 1024 * 1024
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class _Key:
+    jwk: dict[str, typing.Any]
+    key: jwt.PyJWK
+
+
+def _parse_key_set(payload: object) -> dict[str, _Key]:
+    if not isinstance(payload, dict):
+        msg = "The JWKS endpoint did not return a JSON object"
+        raise JWKSFetchError(msg)
+    raw_keys: typing.Final = payload.get("keys")
+    if not isinstance(raw_keys, list):
+        msg = "The JWKS endpoint did not return a 'keys' list"
+        raise JWKSFetchError(msg)
+
+    keys: typing.Final[dict[str, _Key]] = {}
+    for jwk in raw_keys:
+        if not isinstance(jwk, dict) or not isinstance(jwk.get("kid"), str) or jwk.get("use", "sig") != "sig":
+            continue
+        try:
+            keys.setdefault(jwk["kid"], _Key(jwk=jwk, key=jwt.PyJWK(jwk)))
+        except jwt.PyJWTError:
+            LOGGER.debug("skipping unusable JWK %r", jwk["kid"], exc_info=True)
+
+    if not keys:
+        msg = "The JWKS endpoint did not contain any usable signing key"
+        raise JWKSFetchError(msg)
+    return keys
+
+
+def _require_duration(name: str, value: float, *, allow_zero: bool) -> None:
+    if not math.isfinite(value) or value < 0 or (value == 0 and not allow_zero):
+        bound: typing.Final = ">= 0" if allow_zero else "> 0"
+        msg = f"{name} must be finite and {bound}, got {value!r}"
+        raise ValueError(msg)
+
+
+def _create_default_http_client() -> httpware.AsyncClient:
+    return httpware.AsyncClient(
+        timeout=DEFAULT_TIMEOUT,
+        max_response_body_bytes=DEFAULT_MAX_RESPONSE_BODY_BYTES,
+        middleware=[httpware.AsyncCircuitBreaker(), httpware.AsyncRetry()],
+    )
+
+
+class JWKSClient:
+    def __init__(
+        self,
+        uri: str,
+        *,
+        http_client: httpware.AsyncClient | None = None,
+        ttl: float = DEFAULT_TTL,
+        refetch_cooldown: float = DEFAULT_REFETCH_COOLDOWN,
+        stale_if_error: float = DEFAULT_STALE_IF_ERROR,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if urllib.parse.urlsplit(uri).scheme.lower() not in {"http", "https"}:
+            msg = f"JWKS URI must use http or https, got {uri!r}"
+            raise ValueError(msg)
+        _require_duration("ttl", ttl, allow_zero=False)
+        _require_duration("refetch_cooldown", refetch_cooldown, allow_zero=True)
+        _require_duration("stale_if_error", stale_if_error, allow_zero=True)
+
+        self.uri: typing.Final = uri
+        self._owns_http_client: typing.Final = http_client is None
+        self._http_client: typing.Final = http_client or _create_default_http_client()
+        self._ttl: typing.Final = ttl
+        self._refetch_cooldown: typing.Final = refetch_cooldown
+        self._stale_if_error: typing.Final = stale_if_error
+        self._clock: typing.Final = clock
+        self._lock: typing.Final = asyncio.Lock()
+        self._keys: dict[str, _Key] = {}
+        self._fetched_at: float | None = None
+        self._attempted_at: float | None = None
+        self._last_error: JWKSFetchError | None = None
+
+    async def __aenter__(self) -> typing.Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http_client:
+            await self._http_client.aclose()
+
+    async def refresh(self) -> None:
+        async with self._lock:
+            await self._fetch()
+
+    async def get_signing_key(self, kid: str) -> jwt.PyJWK:
+        return (await self._find(kid)).key
+
+    async def get_signing_key_from_jwt(self, token: str | bytes) -> jwt.PyJWK:
+        return (await self._find(jwt.get_unverified_header(token).get("kid"))).key
+
+    async def decode(
+        self,
+        token: str | bytes,
+        *,
+        algorithms: Sequence[str],
+        audience: str | Iterable[str] | None = None,
+        issuer: str | Container[str] | None = None,
+        leeway: float | datetime.timedelta = 0,
+        options: Options | None = None,
+    ) -> dict[str, typing.Any]:
+        header: typing.Final = jwt.get_unverified_header(token)
+        algorithm: typing.Final = header.get("alg")
+        if not isinstance(algorithm, str) or algorithm not in algorithms:
+            msg = "The specified alg value is not allowed"
+            raise jwt.InvalidAlgorithmError(msg)
+
+        found: typing.Final = await self._find(header.get("kid"))
+        key: typing.Final = found.key if "alg" in found.jwk else self._bind_algorithm(found, algorithm)
+        return jwt.decode(
+            token,
+            key,
+            algorithms=list(algorithms),
+            audience=audience,
+            issuer=issuer,
+            leeway=leeway,
+            options=options,
+        )
+
+    @staticmethod
+    def _bind_algorithm(found: _Key, algorithm: str) -> jwt.PyJWK:
+        try:
+            return jwt.PyJWK(found.jwk, algorithm=algorithm)
+        except (jwt.PyJWTError, NotImplementedError) as exc:
+            msg = f"Algorithm {algorithm!r} cannot be used with key {found.key.key_id!r}"
+            raise jwt.InvalidAlgorithmError(msg) from exc
+
+    async def _find(self, kid: object) -> _Key:
+        if not isinstance(kid, str):
+            msg = "The token has no 'kid' header"
+            raise KeyNotFoundError(msg)
+        await self._ensure_fresh()
+        if kid not in self._keys:
+            await self._refetch_for_unknown(kid)
+        try:
+            return self._keys[kid]
+        except KeyError:
+            msg = f"Unable to find a signing key that matches: {kid!r}"
+            raise KeyNotFoundError(msg) from None
+
+    def _is_fresh(self) -> bool:
+        return self._fetched_at is not None and self._clock() - self._fetched_at < self._ttl
+
+    def _is_cooling_down(self) -> bool:
+        return self._attempted_at is not None and self._clock() - self._attempted_at < self._refetch_cooldown
+
+    def _can_serve_stale(self) -> bool:
+        return self._fetched_at is not None and self._clock() - self._fetched_at < self._ttl + self._stale_if_error
+
+    async def _ensure_fresh(self) -> None:
+        if self._is_fresh():
+            return
+        async with self._lock:
+            if self._is_fresh():
+                return
+            if self._last_error is not None and self._is_cooling_down():
+                if self._can_serve_stale():
+                    return
+                msg = "The last JWKS fetch failed; not retrying until the cooldown elapses"
+                raise JWKSFetchError(msg) from self._last_error
+            try:
+                await self._fetch()
+            except JWKSFetchError:
+                if not self._can_serve_stale():
+                    raise
+                LOGGER.warning("JWKS refresh failed, serving stale keys from %s", self.uri, exc_info=True)
+
+    async def _refetch_for_unknown(self, kid: str) -> None:
+        async with self._lock:
+            if kid in self._keys or self._is_cooling_down():
+                return
+            await self._fetch()
+
+    async def _fetch(self) -> None:
+        self._attempted_at = self._clock()
+        try:
+            keys: typing.Final = _parse_key_set(await self._download())
+        except JWKSFetchError as exc:
+            self._last_error = exc
+            raise
+        self._keys = keys
+        self._fetched_at = self._attempted_at
+        self._last_error = None
+
+    async def _download(self) -> object:
+        try:
+            response: typing.Final = await self._http_client.get(self.uri)
+            return response.json()
+        except (httpware.ClientError, ValueError) as exc:
+            msg = f"Failed to fetch JWKS from {self.uri}: {exc}"
+            raise JWKSFetchError(msg) from exc

jwks_client-0.1.0/jwks_client/errors.py

@@ -0,0 +1,13 @@
+import jwt
+
+
+class JWKSError(Exception):
+    """Base class for every error jwks-client raises."""
+
+
+class JWKSFetchError(JWKSError):
+    """The JWKS endpoint could not be fetched, or returned no usable signing key."""
+
+
+class KeyNotFoundError(JWKSError, jwt.InvalidTokenError):
+    """No signing key in the JWKS matches the token's ``kid``."""

jwks_client-0.1.0/jwks_client/fastapi.py

@@ -0,0 +1,56 @@
+import typing
+
+import jwt
+
+from jwks_client.errors import JWKSFetchError
+from jwks_client.verifier import TokenVerifier, UserParser, extract_bearer_token
+
+
+try:
+    from fastapi import HTTPException, Request, status
+    from fastapi.openapi.models import HTTPBearer, OpenIdConnect
+    from fastapi.security.base import SecurityBase
+except ImportError as exc:
+    msg = "jwks_client.fastapi requires the fastapi extra: pip install 'jwks-client[fastapi]'"
+    raise ImportError(msg) from exc
+
+
+UNAUTHORIZED_HEADERS: typing.Final = {"WWW-Authenticate": "Bearer"}
+
+
+def _create_unauthorized_error() -> HTTPException:
+    return HTTPException(status.HTTP_401_UNAUTHORIZED, detail="Not authenticated", headers=UNAUTHORIZED_HEADERS)
+
+
+class JWKSBearer(SecurityBase):
+    def __init__(
+        self,
+        verifier: TokenVerifier,
+        *,
+        user_parser: UserParser | None = None,
+        openid_configuration_url: str | None = None,
+    ) -> None:
+        self.verifier: typing.Final = verifier
+        self.user_parser: typing.Final = user_parser
+        if openid_configuration_url is None:
+            self.model = HTTPBearer(bearerFormat="JWT")
+            self.scheme_name = "Bearer"
+        else:
+            self.model = OpenIdConnect(openIdConnectUrl=openid_configuration_url)
+            self.scheme_name = "OpenIdConnect"
+
+    async def __call__(self, request: Request) -> typing.Any:  # noqa: ANN401
+        token: typing.Final = extract_bearer_token(request.headers.get("Authorization"))
+        if token is None:
+            raise _create_unauthorized_error()
+        try:
+            claims: typing.Final = await self.verifier.verify(token)
+        except jwt.InvalidTokenError as exc:
+            raise _create_unauthorized_error() from exc
+        except JWKSFetchError as exc:
+            raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, detail="Identity provider unavailable") from exc
+
+        user: typing.Final = claims if self.user_parser is None else self.user_parser(claims)
+        if user is None:
+            raise _create_unauthorized_error()
+        return user

jwks_client-0.1.0/jwks_client/litestar.py

@@ -0,0 +1,73 @@
+import typing
+from collections.abc import Sequence
+
+import jwt
+
+from jwks_client.errors import JWKSFetchError
+from jwks_client.verifier import TokenVerifier, UserParser, extract_bearer_token
+
+
+try:
+    from litestar.connection import ASGIConnection
+    from litestar.exceptions import NotAuthorizedException, ServiceUnavailableException
+    from litestar.middleware import AbstractAuthenticationMiddleware, AuthenticationResult
+    from litestar.openapi.spec import Components, SecurityRequirement, SecurityScheme
+    from litestar.types import ASGIApp, Method, Scopes
+except ImportError as exc:
+    msg = "jwks_client.litestar requires the litestar extra: pip install 'jwks-client[litestar]'"
+    raise ImportError(msg) from exc
+
+
+UNAUTHORIZED_HEADERS: typing.Final = {"WWW-Authenticate": "Bearer"}
+
+
+class JWKSAuthMiddleware(AbstractAuthenticationMiddleware):
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        verifier: TokenVerifier,
+        user_parser: UserParser | None = None,
+        exclude: str | list[str] | None = None,
+        exclude_from_auth_key: str = "exclude_from_auth",
+        exclude_http_methods: Sequence[Method] | None = None,
+        scopes: "Scopes | None" = None,
+    ) -> None:
+        super().__init__(app, exclude, exclude_from_auth_key, exclude_http_methods, scopes)
+        self.verifier: typing.Final = verifier
+        self.user_parser: typing.Final = user_parser
+
+    async def authenticate_request(
+        self, connection: ASGIConnection[typing.Any, typing.Any, typing.Any, typing.Any]
+    ) -> AuthenticationResult:
+        token: typing.Final = extract_bearer_token(connection.headers.get("Authorization"))
+        if token is None:
+            raise NotAuthorizedException(headers=UNAUTHORIZED_HEADERS)
+        try:
+            claims: typing.Final = await self.verifier.verify(token)
+        except jwt.InvalidTokenError as exc:
+            raise NotAuthorizedException(headers=UNAUTHORIZED_HEADERS) from exc
+        except JWKSFetchError as exc:
+            raise ServiceUnavailableException from exc
+
+        user: typing.Final = claims if self.user_parser is None else self.user_parser(claims)
+        if user is None:
+            raise NotAuthorizedException(headers=UNAUTHORIZED_HEADERS)
+        return AuthenticationResult(user=user, auth=claims)
+
+
+class OpenAPISecurityConfig(typing.TypedDict):
+    components: Components
+    security: list[SecurityRequirement]
+
+
+def create_openapi_security_config(openid_configuration_url: str | None = None) -> OpenAPISecurityConfig:
+    schemes: typing.Final[dict[str, SecurityScheme]] = {
+        "Bearer": SecurityScheme(type="http", scheme="bearer", bearer_format="JWT"),
+    }
+    if openid_configuration_url is not None:
+        schemes["OpenIdConnect"] = SecurityScheme(type="openIdConnect", open_id_connect_url=openid_configuration_url)
+    return {
+        "components": Components(security_schemes=dict(schemes)),
+        "security": [{name: []} for name in schemes],
+    }

jwks_client-0.1.0/jwks_client/testing.py

@@ -0,0 +1,56 @@
+import datetime
+import json
+import typing
+from collections.abc import Mapping
+
+import httpware
+import httpx2
+import jwt
+from cryptography.hazmat.primitives.asymmetric import rsa
+from jwt.algorithms import RSAAlgorithm
+
+from jwks_client.client import JWKSClient
+
+
+DEFAULT_TOKEN_LIFETIME: typing.Final = datetime.timedelta(minutes=5)
+
+
+class FakeIdentityProvider:
+    def __init__(self, *, issuer: str = "https://idp.test", kid: str = "test-key") -> None:
+        self.issuer: typing.Final = issuer
+        self.kid: typing.Final = kid
+        self.jwks_uri: typing.Final = f"{issuer}/.well-known/jwks.json"
+        self._private_key: typing.Final = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+        jwk: typing.Final = json.loads(RSAAlgorithm.to_jwk(self._private_key.public_key()))
+        self.jwks: typing.Final[dict[str, typing.Any]] = {"keys": [jwk | {"kid": kid, "use": "sig", "alg": "RS256"}]}
+
+    def issue_token(
+        self,
+        claims: Mapping[str, typing.Any] | None = None,
+        *,
+        expires_in: datetime.timedelta = DEFAULT_TOKEN_LIFETIME,
+        headers: Mapping[str, typing.Any] | None = None,
+    ) -> str:
+        now: typing.Final = datetime.datetime.now(tz=datetime.UTC)
+        payload: typing.Final = {"iss": self.issuer, "iat": now, "exp": now + expires_in} | dict(claims or {})
+        return jwt.encode(
+            payload, self._private_key, algorithm="RS256", headers={"kid": self.kid} | dict(headers or {})
+        )
+
+    def create_jwks_client(self) -> JWKSClient:
+        transport: typing.Final = httpx2.MockTransport(lambda _: httpx2.Response(200, json=self.jwks))
+        return JWKSClient(
+            self.jwks_uri, http_client=httpware.AsyncClient(httpx2_client=httpx2.AsyncClient(transport=transport))
+        )
+
+
+class StaticTokenVerifier:
+    def __init__(self, tokens: Mapping[str, Mapping[str, typing.Any]]) -> None:
+        self._tokens: typing.Final = tokens
+
+    async def verify(self, token: str) -> dict[str, typing.Any]:
+        try:
+            return dict(self._tokens[token])
+        except KeyError:
+            msg = "Unknown token"
+            raise jwt.InvalidTokenError(msg) from None

jwks_client-0.1.0/jwks_client/verifier.py

@@ -0,0 +1,57 @@
+import datetime
+import typing
+from collections.abc import Callable, Container, Iterable, Sequence
+
+from jwt.types import Options
+
+from jwks_client.client import JWKSClient
+
+
+BEARER_SCHEME: typing.Final = "bearer"
+
+
+UserParser = Callable[[dict[str, typing.Any]], typing.Any]
+
+
+class TokenVerifier(typing.Protocol):
+    async def verify(self, token: str) -> dict[str, typing.Any]: ...
+
+
+class JWTVerifier:
+    def __init__(
+        self,
+        jwks: JWKSClient,
+        *,
+        algorithms: Sequence[str],
+        audience: str | Iterable[str] | None = None,
+        issuer: str | Container[str] | None = None,
+        leeway: float | datetime.timedelta = 0,
+        options: Options | None = None,
+    ) -> None:
+        if not algorithms:
+            msg = "algorithms must name at least one signing algorithm"
+            raise ValueError(msg)
+        self.jwks: typing.Final = jwks
+        self.algorithms: typing.Final = tuple(algorithms)
+        self.audience: typing.Final = audience
+        self.issuer: typing.Final = issuer
+        self.leeway: typing.Final = leeway
+        self.options: typing.Final = options
+
+    async def verify(self, token: str) -> dict[str, typing.Any]:
+        return await self.jwks.decode(
+            token,
+            algorithms=self.algorithms,
+            audience=self.audience,
+            issuer=self.issuer,
+            leeway=self.leeway,
+            options=self.options,
+        )
+
+
+def extract_bearer_token(authorization: str | None) -> str | None:
+    scheme, _, token = (authorization or "").strip().partition(" ")
+    token = token.strip()
+    if scheme.lower() != BEARER_SCHEME or not token:
+        return None
+    return token

jwks_client-0.1.0/pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "jwks-client"
+description = "Async JWKS client for verifying JWTs, with key caching, resilient fetching, and Litestar and FastAPI integrations"
+readme = "README.md"
+requires-python = ">=3.11,<4"
+license = "MIT"
+keywords = [
+    "jwks",
+    "jwt",
+    "jwk",
+    "oidc",
+    "oauth2",
+    "authentication",
+    "asyncio",
+    "litestar",
+    "fastapi",
+    "python",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Free Threading :: 2 - Beta",
+    "Typing :: Typed",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Framework :: Litestar",
+]
+version = "0.1.0"
+dependencies = [
+    "pyjwt[crypto]>=2.15.1",
+    "httpware>=0.15.0,<1",
+    "httpx2>=2.0.0,<3",
+]
+
+[[project.authors]]
+name = "Artur Shiriev"
+email = "me@shiriev.ru"
+
+[project.optional-dependencies]
+litestar = ["litestar>=2.19"]
+fastapi = ["fastapi>=0.115"]
+
+[project.urls]
+Homepage = "https://modern-python.org"
+Repository = "https://github.com/modern-python/jwks-client"
+Issues = "https://github.com/modern-python/jwks-client/issues"
+Changelog = "https://github.com/modern-python/jwks-client/releases"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pytest-asyncio>=0.24",
+]
+lint = [
+    "ruff",
+    "ty",
+    "eof-fixer",
+]
+
+[build-system]
+requires = ["uv_build>=0.11,<1.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "jwks_client"
+module-root = ""
+
+[tool.ruff]
+fix = true
+unsafe-fixes = true
+line-length = 120
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D1",
+    "D203",
+    "D213",
+    "COM812",
+    "ISC001",
+    "CPY001",
+    "FBT",
+    "TCH",
+]
+
+[tool.ruff.lint.pylint]
+max-args = 10
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+no-lines-before = [
+    "standard-library",
+    "local-folder",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ""
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.report]
+fail_under = 100
+exclude_also = ["if typing.TYPE_CHECKING:"]

jwks_client-0.1.0/pyproject.toml.orig

@@ -0,0 +1,105 @@
+[project]
+name = "jwks-client"
+description = "Async JWKS client for verifying JWTs, with key caching, resilient fetching, and Litestar and FastAPI integrations"
+authors = [
+    { name = "Artur Shiriev", email = "me@shiriev.ru" },
+]
+readme = "README.md"
+requires-python = ">=3.11,<4"
+license = "MIT"
+keywords = ["jwks", "jwt", "jwk", "oidc", "oauth2", "authentication", "asyncio", "litestar", "fastapi", "python"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Free Threading :: 2 - Beta",
+    "Typing :: Typed",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Framework :: Litestar",
+]
+version = "0.1.0"
+dependencies = [
+    # 2.15.1 carries the fixes for the 2026 advisories and binds a PyJWK's algorithm at verify time.
+    "pyjwt[crypto]>=2.15.1",
+    # 0.15.0 introduced max_response_body_bytes.
+    "httpware>=0.15.0,<1",
+    "httpx2>=2.0.0,<3",
+]
+
+[project.optional-dependencies]
+litestar = ["litestar>=2.19"]
+fastapi = ["fastapi>=0.115"]
+
+[project.urls]
+Homepage = "https://modern-python.org"
+Repository = "https://github.com/modern-python/jwks-client"
+Issues = "https://github.com/modern-python/jwks-client/issues"
+Changelog = "https://github.com/modern-python/jwks-client/releases"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pytest-asyncio>=0.24",
+]
+lint = [
+    "ruff",
+    "ty",
+    "eof-fixer",
+]
+
+[build-system]
+requires = ["uv_build>=0.11,<1.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "jwks_client"
+module-root = ""
+
+[tool.ruff]
+fix = true
+unsafe-fixes = true
+line-length = 120
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D1",     # docstrings are not forced; a docstring exists when it says something
+    "D203",   # conflicts with D211
+    "D213",   # conflicts with D212
+    "COM812", # conflicts with the formatter
+    "ISC001", # conflicts with the formatter
+    "CPY001", # no per-file copyright header
+    "FBT",    # boolean positional arguments are fine
+    "TCH",    # imports stay real; TYPE_CHECKING-only imports break runtime introspection
+]
+pylint.max-args = 10
+isort.lines-after-imports = 2
+isort.no-lines-before = ["standard-library", "local-folder"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",    # assert is the test idiom; in library code it is a finding
+    "PLR2004", # request counts read clearer as literals than as named constants
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ""
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.report]
+fail_under = 100
+exclude_also = [
+    "if typing.TYPE_CHECKING:",
+]