fastapi-multiauth 1.1.0__tar.gz → 1.2.0__tar.gz

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-multiauth
-Version: 1.1.0
+Version: 1.2.0
 Summary: Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction
 Keywords: fastapi,authentication,security,oauth,api-key,bearer,cookie
 Author: d3vyce
@@ -18,13 +18,13 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: Internet :: WWW/HTTP :: Session
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Dist: anyio>=3.7
-Requires-Dist: async-lru>=2.0
 Requires-Dist: fastapi>=0.123.0,!=0.137.0,!=0.137.1
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: itsdangerous>=2.1
@@ -124,12 +124,12 @@ Set `SECRET_KEY` to at least 32 random bytes, for example the output of `python
 - **Every standard scheme**: bearer tokens with Stripe-style prefixes, signed cookie sessions, API keys, HTTP Basic, OAuth 2.0 and OpenID Connect.
 - **`MultiAuth`**: several schemes on one route, all documented in OpenAPI, plus `optional()` for routes that also serve anonymous callers.
 - **Stateless sessions**: HMAC-signed cookies with expiry, key rotation, opt-in revocable session ids, and cross-origin requests refused by default.
-- **Tokens done right**: secure generation, hash-only storage, checksums, `JWTValidator` for provider JWTs (JWKS, rotation, `aud`/`iss`), `IntrospectionValidator` for opaque ones, and `HTTPDPoPAuth` for tokens bound to the client's key.
+- **Tokens done right**: secure generation, hash-only storage, checksums, `JWTValidator` for provider JWTs (JWKS, rotation, `aud`/`iss`/`typ`), `IntrospectionValidator` for opaque ones, and `HTTPDPoPAuth` for tokens bound to the client's key.
 - **Signed webhooks**: `HMACSignatureAuth` checks the sender's signature over the raw body, with timestamp tolerance and secret rotation.
 - **Scopes and step-up**: fail-closed scope checks, and `fresh()` / `stepped_up()` with RFC 9470 challenges for sensitive routes.
 - **Second factor**: TOTP helpers that refuse a replayed code, and the login level signed into the session cookie.
 - **OAuth login helpers**: discovery, CSRF `state`, PKCE, code exchange and ID token validation.
-- **Observable**: reason-coded security logs and `auth_surface(app)` to audit what guards every route.
+- **Observable**: reason-coded security logs and `auth_surface(app)` to audit what guards every route, `dependency_overrides` included.
 
 See the [comparison](https://fastapi-multiauth.d3vyce.fr/guide/comparison/) for how it sits next to `fastapi.security`, fastapi-users, AuthX and Authlib, and the [security model](https://fastapi-multiauth.d3vyce.fr/security-model/) for what it guarantees.
 

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/README.md

@@ -83,12 +83,12 @@ Set `SECRET_KEY` to at least 32 random bytes, for example the output of `python
 - **Every standard scheme**: bearer tokens with Stripe-style prefixes, signed cookie sessions, API keys, HTTP Basic, OAuth 2.0 and OpenID Connect.
 - **`MultiAuth`**: several schemes on one route, all documented in OpenAPI, plus `optional()` for routes that also serve anonymous callers.
 - **Stateless sessions**: HMAC-signed cookies with expiry, key rotation, opt-in revocable session ids, and cross-origin requests refused by default.
-- **Tokens done right**: secure generation, hash-only storage, checksums, `JWTValidator` for provider JWTs (JWKS, rotation, `aud`/`iss`), `IntrospectionValidator` for opaque ones, and `HTTPDPoPAuth` for tokens bound to the client's key.
+- **Tokens done right**: secure generation, hash-only storage, checksums, `JWTValidator` for provider JWTs (JWKS, rotation, `aud`/`iss`/`typ`), `IntrospectionValidator` for opaque ones, and `HTTPDPoPAuth` for tokens bound to the client's key.
 - **Signed webhooks**: `HMACSignatureAuth` checks the sender's signature over the raw body, with timestamp tolerance and secret rotation.
 - **Scopes and step-up**: fail-closed scope checks, and `fresh()` / `stepped_up()` with RFC 9470 challenges for sensitive routes.
 - **Second factor**: TOTP helpers that refuse a replayed code, and the login level signed into the session cookie.
 - **OAuth login helpers**: discovery, CSRF `state`, PKCE, code exchange and ID token validation.
-- **Observable**: reason-coded security logs and `auth_surface(app)` to audit what guards every route.
+- **Observable**: reason-coded security logs and `auth_surface(app)` to audit what guards every route, `dependency_overrides` included.
 
 See the [comparison](https://fastapi-multiauth.d3vyce.fr/guide/comparison/) for how it sits next to `fastapi.security`, fastapi-users, AuthX and Authlib, and the [security model](https://fastapi-multiauth.d3vyce.fr/security-model/) for what it guarantees.
 

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "1.1.0"
+version = "1.2.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -27,6 +27,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3.15",
+    "Programming Language :: Python :: Free Threading :: 3 - Stable",
     "Topic :: Internet :: WWW/HTTP :: Session",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -35,7 +36,6 @@ classifiers = [
 ]
 dependencies = [
     "anyio>=3.7",
-    "async-lru>=2.0",
     "fastapi>=0.123.0,!=0.137.0,!=0.137.1",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "1.1.0"
+version = "1.2.0"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3.15",
+    "Programming Language :: Python :: Free Threading :: 3 - Stable",
     "Topic :: Internet :: WWW/HTTP :: Session",
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -30,7 +31,6 @@ classifiers = [
 ]
 dependencies = [
     "anyio>=3.7",
-    "async-lru>=2.0",
     "fastapi>=0.123.0,!=0.137.0,!=0.137.1",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/src/fastapi_multiauth/__init__.py

@@ -43,7 +43,7 @@ from .utils import (
     verify_token_hash,
 )
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/src/fastapi_multiauth/abc.py

@@ -6,7 +6,7 @@ import logging
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
-from typing import Any, ClassVar, Self
+from typing import Any, ClassVar, NamedTuple, Self
 
 from fastapi import HTTPException
 from fastapi.requests import HTTPConnection
@@ -208,10 +208,13 @@ def _carry_scheme(dependency: Any, scheme: SecurityBase) -> None:
     cls = type(dependency)
     promoted = _SCHEME_CLASSES.get(cls)
     if promoted is None:
-        promoted = _SCHEME_CLASSES[cls] = type(
-            cls.__name__,
-            (cls, SecurityBase),
-            {"__module__": cls.__module__, "__doc__": cls.__doc__},
+        promoted = _SCHEME_CLASSES.setdefault(
+            cls,
+            type(
+                cls.__name__,
+                (cls, SecurityBase),
+                {"__module__": cls.__module__, "__doc__": cls.__doc__},
+            ),
         )
     dependency.__class__ = promoted
     dependency.model = scheme.model
@@ -228,6 +231,28 @@ class _Freshness:
     """Caller-supplied reader of the instant, `None` to use the source's own."""
 
 
+async def _within(freshness: _Freshness, instant: Any, identity: Any) -> bool:
+    """Whether a credential proven at `instant` falls inside `freshness`.
+
+    `freshness.read`, when set, reads the instant off `identity` instead.
+    """
+    if freshness.read is not None:
+        instant = await freshness.read(identity)
+    age = credential_age(instant)
+    return age is not None and (
+        -freshness.leeway <= age <= freshness.max_age + freshness.leeway
+    )
+
+
+class _Record(NamedTuple):
+    """What a source leaves in the request scope once it authenticated it."""
+
+    source: "AuthSource"
+    authenticated_at: Any
+    """When the credential was proven, so `ensure_fresh()` never sees the credential."""
+    identity: Any
+
+
 @dataclass(frozen=True, slots=True)
 class _Assurance:
     """The levels set by `stepped_up()`."""
@@ -243,7 +268,8 @@ class AuthSource(ABC):
     Subclass it to read a credential the built-in sources do not handle.
     Implement `extract()` and `authenticate()`; override `www_authenticate()`,
     `authenticated_at()`, `authenticated_acr()` or `authenticate_scoped()`
-    when the source needs them.
+    when the source needs them, and set `authorization_scheme` on a source
+    that reads the `Authorization` header.
 
     Args:
         scheme: A `fastapi.security` scheme describing the source in OpenAPI.
@@ -251,6 +277,11 @@ class AuthSource(ABC):
     """
 
     scheme: SecurityBase | None
+    authorization_scheme: str | None = None
+    """The `Authorization` scheme this source reads, lowercased: `"*"` for any
+    scheme, `None` when it does not read the header. Under `MultiAuth`, a
+    header of a scheme a source reads, which no such source takes, is refused
+    instead of passing to a cookie or an API key."""
     _optional: bool = False
     _scope_catalogue: dict[str, str] | None = None
     """The scopes this source publishes to OpenAPI, `None` when it has none."""
@@ -346,14 +377,22 @@ class AuthSource(ABC):
     ) -> Any:
         """Authenticate, attaching this source's challenge to any 401 raised.
 
-        Freshness is checked after the credential: an invalid one is refused as
-        invalid, not as stale. Every outcome is logged.
+        A validator that returns `None` or `False` refuses the credential: a
+        lookup that found nothing, or a comparison that failed, must never
+        pass for an identity. Freshness is checked after the credential: an
+        invalid one is refused as invalid, not as stale. Every outcome is logged.
+
+        What is recorded for `ensure_fresh()` is when the credential was
+        proven, not the credential itself, so the record never holds it.
         """
         try:
             identity = await self.authenticate_scoped(
                 credential, scopes, request=request
             )
-            await self._enforce_step_up(credential, identity, request)
+            if identity is None or identity is False:
+                raise refusal(UnauthorizedError(), "no_identity")
+            instant = self._credential_authenticated_at(credential, request)
+            await self._enforce_step_up(credential, identity, request, instant)
         except HTTPException as exc:
             add_challenge(exc, self.www_authenticate())
             self._log(logging.WARNING, refusal_reason(exc), exc.status_code)
@@ -361,7 +400,7 @@ class AuthSource(ABC):
         records = request.scope.get(_AUTHENTICATED)
         if records is None:
             records = request.scope[_AUTHENTICATED] = {}
-        records[self._record_key()] = (self, credential, identity)
+        records[self._record_key()] = _Record(self, instant, identity)
         if self._logger.isEnabledFor(logging.DEBUG):
             self._log(logging.DEBUG, "authenticated")
         return identity
@@ -401,7 +440,9 @@ class AuthSource(ABC):
         """Return when a credential was proven, for `fresh()`.
 
         Override it in a source that can date its own credentials, as the
-        signed cookie does.
+        signed cookie does. It runs on every authenticated request, whether
+        or not the route asks for freshness, since `ensure_fresh()` may ask
+        later: return `None` rather than raise for a credential it cannot date.
 
         Args:
             credential: The credential returned by `extract()`.
@@ -537,15 +578,11 @@ class AuthSource(ABC):
         await self._check_record(request, record, window)
 
     async def _check_record(
-        self,
-        request: HTTPConnection,
-        record: tuple["AuthSource", str, Any],
-        window: _Freshness,
+        self, request: HTTPConnection, record: _Record, window: _Freshness
     ) -> None:
         """Refuse the recorded authentication when it falls outside `window`."""
-        source, credential, identity = record
-        if not await self._is_fresh(window, credential, identity, request):
-            assurance = source._assurance
+        if not await _within(window, record.authenticated_at, record.identity):
+            assurance = record.source._assurance
             exc = refusal(
                 self._challenge_error(
                     StaleCredentialError,
@@ -622,13 +659,18 @@ class AuthSource(ABC):
         return clone
 
     async def _enforce_step_up(
-        self, credential: str, identity: Any, request: HTTPConnection | None = None
+        self,
+        credential: str,
+        identity: Any,
+        request: HTTPConnection | None,
+        instant: Any,
     ) -> None:
-        """Refuse an identity outside the `fresh()` window or `stepped_up()` levels."""
+        """Refuse an identity outside the `fresh()` window or `stepped_up()` levels.
+
+        `instant` is what `_credential_authenticated_at()` read for the credential.
+        """
         freshness, assurance = self._freshness, self._assurance
-        if freshness is not None and not await self._is_fresh(
-            freshness, credential, identity, request
-        ):
+        if freshness is not None and not await _within(freshness, instant, identity):
             raise refusal(self._step_up_error(StaleCredentialError), "stale")
         if assurance is not None:
             if assurance.read is not None:
@@ -641,23 +683,6 @@ class AuthSource(ABC):
                     "insufficient_acr",
                 )
 
-    async def _is_fresh(
-        self,
-        freshness: _Freshness,
-        credential: str,
-        identity: Any,
-        request: HTTPConnection | None,
-    ) -> bool:
-        """Whether the credential was proven inside the window."""
-        if freshness.read is not None:
-            instant = await freshness.read(identity)
-        else:
-            instant = self._credential_authenticated_at(credential, request)
-        age = credential_age(instant)
-        return age is not None and (
-            -freshness.leeway <= age <= freshness.max_age + freshness.leeway
-        )
-
     def _credential_authenticated_at(
         self, credential: str, request: HTTPConnection | None
     ) -> Any:

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/src/fastapi_multiauth/introspection.py

@@ -4,23 +4,24 @@ import base64
 import copy
 import logging
 import time
-from collections import OrderedDict
 from collections.abc import Callable, Sequence
 from typing import Any, ClassVar
 from urllib.parse import quote_plus
 
-import anyio
 import httpx
 
 from ._http import DEFAULT_TIMEOUT, _request_json, _require_https
 from .exceptions import UnauthorizedError
 from .jwt import AnyAudience
 from .utils import (
+    SingleFlight,
+    TTLCache,
     ensure_async,
     finite_number,
     hash_token,
     record_verified_jkt,
     refusal,
+    reject_other_token_kinds,
     require_nonnegative_seconds,
     require_scopes,
     service_unavailable,
@@ -28,11 +29,6 @@ from .utils import (
 
 logger = logging.getLogger(__name__)
 
-_OTHER_TOKEN_KINDS = {
-    "typ": frozenset({"refresh", "offline", "id", "logout"}),
-    "token_use": frozenset({"refresh_token", "id_token", "refresh", "id"}),
-}
-
 
 class _IntrospectionUnavailable(Exception):
     """The introspection endpoint is unreachable or answered unusably."""
@@ -57,15 +53,6 @@ class _Answer:
         return copied
 
 
-class _Lookup:
-    """One introspection in flight, awaited by every request carrying its token."""
-
-    def __init__(self) -> None:
-        self.done = anyio.Event()
-        self.answer: _Answer | None = None
-        self.error: Exception | None = None
-
-
 def _basic_authorization(client_id: str, client_secret: str) -> str:
     """`client_secret_basic`: both halves form-encoded before base64 (RFC 6749 §2.3.1)."""
     pair = f"{quote_plus(client_id, safe='')}:{quote_plus(client_secret, safe='')}"
@@ -157,9 +144,8 @@ class IntrospectionValidator:
             ensure_async(claims_to_identity) if claims_to_identity else None
         )
         self._cache_ttl = cache_ttl
-        self._cache_size = cache_size
-        self._cache: OrderedDict[str, tuple[float, _Answer]] = OrderedDict()
-        self._lookups: dict[str, _Lookup] = {}
+        self._cache = TTLCache(cache_size)
+        self._lookups = SingleFlight()
         self._timeout = timeout
         self._client = client
 
@@ -172,7 +158,9 @@ class IntrospectionValidator:
             HTTPException: 503 if the introspection endpoint cannot be used.
         """
         key = hash_token(token)
-        answer = self._cached(key) or await self._lookup(token, key)
+        answer = self._cache.get(key) or await self._lookups.run(
+            key, lambda: self._lookup(token, key)
+        )
         claims = answer.copy()
         if scopes:
             require_scopes(claims, self._scopes_claim, scopes)
@@ -182,26 +170,11 @@ class IntrospectionValidator:
         return claims
 
     async def _lookup(self, token: str, key: str) -> _Answer:
-        """The answer for `token`, from the introspection in flight or a new one."""
-        while (lookup := self._lookups.get(key)) is not None:
-            await lookup.done.wait()
-            if lookup.error is not None:
-                raise copy.copy(lookup.error)
-            if lookup.answer is not None:
-                return lookup.answer
-        lookup = self._lookups[key] = _Lookup()
-        try:
-            claims = await self._introspect(token)
-            self._check_claims(claims)
-            answer = _Answer(claims)
-            self._store(key, answer)
-            lookup.answer = answer
-        except Exception as exc:
-            lookup.error = exc
-            raise
-        finally:
-            del self._lookups[key]
-            lookup.done.set()
+        """Introspect `token`, check its claims and cache the answer."""
+        claims = await self._introspect(token)
+        self._check_claims(claims)
+        answer = _Answer(claims)
+        self._store(key, answer)
         return answer
 
     async def _introspect(self, token: str) -> dict[str, Any]:
@@ -238,10 +211,7 @@ class IntrospectionValidator:
 
     def _check_claims(self, claims: dict[str, Any]) -> None:
         """Check the token is an access token, then `exp`, `nbf`, `aud` and `iss`."""
-        for field, kinds in _OTHER_TOKEN_KINDS.items():
-            kind = claims.get(field)
-            if isinstance(kind, str) and kind.lower() in kinds:
-                raise refusal(UnauthorizedError(), "not_access_token")
+        reject_other_token_kinds(claims)
         now = time.time()
         if "exp" in claims:
             exp = finite_number(claims["exp"])
@@ -265,27 +235,11 @@ class IntrospectionValidator:
         if self._issuer is not None and claims.get("iss") != self._issuer:
             raise refusal(UnauthorizedError(), "invalid_issuer")
 
-    def _cached(self, key: str) -> _Answer | None:
-        """A cached answer still within its lifetime, `None` otherwise."""
-        entry = self._cache.get(key)
-        if entry is None:
-            return None
-        expires_at, answer = entry
-        if time.monotonic() >= expires_at:
-            del self._cache[key]
-            return None
-        self._cache.move_to_end(key)
-        return answer
-
     def _store(self, key: str, answer: _Answer) -> None:
         """Cache an active answer for `cache_ttl`, never past the token's `exp`."""
         ttl = self._cache_ttl
         exp = finite_number(answer.claims.get("exp"))
         if exp is not None:
             ttl = min(ttl, exp - time.time())
-        if ttl <= 0:
-            return
-        self._cache[key] = (time.monotonic() + ttl, answer)
-        self._cache.move_to_end(key)
-        while len(self._cache) > self._cache_size:
-            self._cache.popitem(last=False)
+        if ttl > 0:
+            self._cache.put(key, answer, ttl)

{fastapi_multiauth-1.1.0 → fastapi_multiauth-1.2.0}/src/fastapi_multiauth/jwt.py

@@ -2,19 +2,22 @@
 
 import enum
 import logging
+import threading
 import time
 from collections.abc import Callable, Sequence
 from typing import Any, ClassVar
 
-import anyio
+from anyio.lowlevel import current_token
 
 from ._http import DEFAULT_TIMEOUT, _get_json, _require_https
 from ._imports import require_extra
 from .exceptions import UnauthorizedError
 from .utils import (
+    SingleFlight,
     ensure_async,
     record_verified_jkt,
     refusal,
+    reject_other_token_kinds,
     require_nonnegative_seconds,
     require_scopes,
     service_unavailable,
@@ -65,6 +68,11 @@ def _reject_symmetric(algorithms: Sequence[str], url_param: str) -> None:
         )
 
 
+def _normalize_typ(typ: str) -> str:
+    """A JWT header `typ`, lowercased and without the optional `application/`."""
+    return typ.lower().removeprefix("application/")
+
+
 def _import_pyjwt() -> Any:
     try:
         import jwt as pyjwt
@@ -112,9 +120,10 @@ class _JWKSKeySet:
         self._refresh_cooldown = refresh_cooldown
         self._timeout = timeout
         self._keys: dict[str, Any] = {}
-        self._fetched_at = 0.0
-        self._attempted_at = float("-inf")
-        self._refresh_lock = anyio.Lock()
+        self._fetched_at = float("-inf")
+        self._attempts: dict[Any, float] = {}
+        self._lock = threading.Lock()
+        self._refreshes = SingleFlight()
 
     async def key_for_token(self, token: str) -> Any:
         """The key that signed `token`, found by its header `kid`.
@@ -153,27 +162,42 @@ class _JWKSKeySet:
     async def _refresh(self, force: bool = False) -> None:
         """Refetch the JWKS, coalescing concurrent and repeated refreshes.
 
-        At most one attempt per `refresh_cooldown`; a failed fetch falls
+        Requests on one event loop share its refresh in flight. Each loop
+        attempts at most one fetch per `refresh_cooldown`, and none within
+        it of a fetch that succeeded on any loop; a failed fetch falls
         back on cached keys, or raises when the cache is empty.
         """
-        async with self._refresh_lock:
-            # Re-check after acquiring: another request may just have tried.
-            if time.monotonic() - self._attempted_at < self._refresh_cooldown:
-                if not self._keys:
-                    raise _JWKSUnavailable()
-                return
-            if not force and not self._cache_stale():
-                return
-            self._attempted_at = time.monotonic()
-            try:
-                await self._fetch()
-            except _JWKSFetchError as exc:
-                logger.warning("JWKS refresh failed: %s", exc)
-                if not self._keys:
-                    raise _JWKSUnavailable() from exc
-                # Stale fallback: keep validating with the cached keys.
+        loop = current_token()
+        await self._refreshes.run(None, lambda: self._attempt(loop, force))
+
+    async def _attempt(self, loop: Any, force: bool) -> None:
+        if not self._claim_attempt(loop, force):
+            if not self._keys:
+                raise _JWKSUnavailable()
+            return
+        try:
+            await self._fetch()
+        except _JWKSFetchError as exc:
+            logger.warning("JWKS refresh failed: %s", exc)
+            if not self._keys:
+                raise _JWKSUnavailable() from exc
+
+    def _claim_attempt(self, loop: Any, force: bool) -> bool:
+        """Whether `loop` may fetch now, recording the attempt when it may."""
+        now = time.monotonic()
+        cooldown = self._refresh_cooldown
+        with self._lock:
+            last = max(self._fetched_at, self._attempts.get(loop, float("-inf")))
+            if now - last < cooldown or not (force or self._cache_stale()):
+                return False
+            self._attempts = {
+                seen: at for seen, at in self._attempts.items() if now - at < cooldown
+            }
+            self._attempts[loop] = now
+            return True
 
     async def _fetch(self) -> None:
+        started = time.monotonic()
         document = await _get_json(
             self._url,
             timeout=self._timeout,
@@ -215,8 +239,10 @@ class _JWKSKeySet:
                 f"JWKS document has no usable signing key "
                 f"({len(document['keys'])} entries)"
             )
-        self._keys = keys
-        self._fetched_at = time.monotonic()
+        with self._lock:
+            if started >= self._fetched_at:
+                self._keys = keys
+                self._fetched_at = started
 
 
 class JWTValidator:
@@ -227,17 +253,28 @@ class JWTValidator:
     cached and refreshed when the provider rotates them; if the provider
     is down, cached keys keep working, and a cold start answers 503.
 
+    A token whose `typ` or `token_use` claim marks it as a refresh, ID or
+    logout token is refused (`not_access_token`), as the introspection
+    validator does. Providers that mark their access tokens in the header
+    can be held to it with `typ`.
+
     Args:
         secret: Shared HMAC key of at least 32 bytes.
         jwks_url: HTTPS URL of the provider's public keys.
         algorithms: Accepted algorithms; `["HS256"]` with a secret,
             `["RS256", "ES256"]` with a JWKS, where `HS*` is refused.
-        audience: Expected `aud`. Required with a JWKS, since a provider
-            signs every application's tokens with the same keys; pass
-            `ANY_AUDIENCE` to skip the check on purpose.
+        audience: Expected `aud`: your API's own identifier. Required with
+            a JWKS, since a provider signs every application's tokens with
+            the same keys; pass `ANY_AUDIENCE` to skip the check on purpose.
+            Do not use the client id of a front-end here: the ID tokens the
+            provider hands that front-end carry it as `aud` too.
         issuer: Expected `iss`; not checked when unset.
         leeway: Clock-skew tolerance in seconds for `exp`, `nbf` and `iat`.
         required_claims: Claims every token must carry.
+        typ: Expected JWT header `typ`, e.g. `"at+jwt"` for a provider
+            issuing [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068)
+            access tokens. Compared case-insensitively, with or without the
+            `application/` prefix. Not checked when unset.
         scopes_claim: Claim holding granted scopes: a space-separated string
             (`scope`) or a list (`scp`, `roles`). A missing route scope is a 403.
         claims_to_identity: Sync or async callable turning the verified
@@ -249,7 +286,7 @@ class JWTValidator:
     Raises:
         ValueError: On an invalid configuration, such as both or neither of
             `secret` and `jwks_url`, a short secret, a JWKS without `audience`,
-            or a negative `leeway`.
+            a negative `leeway`, or an empty `typ`.
     """
 
     ANY_AUDIENCE: ClassVar[AnyAudience] = AnyAudience.ANY
@@ -265,6 +302,7 @@ class JWTValidator:
         issuer: str | None = None,
         leeway: float = 0.0,
         required_claims: Sequence[str] = ("exp",),
+        typ: str | None = None,
         scopes_claim: str = "scope",
         claims_to_identity: Callable[[dict[str, Any]], Any] | None = None,
         jwks_cache_ttl: float = 3600.0,
@@ -275,6 +313,11 @@ class JWTValidator:
         if (secret is None) == (jwks_url is None):
             raise ValueError("provide exactly one of 'secret' or 'jwks_url'")
         require_nonnegative_seconds(leeway, "leeway")
+        if typ is not None:
+            if not typ:
+                raise ValueError("typ must be a non-empty string")
+            typ = _normalize_typ(typ)
+        self._typ = typ
         if secret is not None:
             if len(secret.encode()) < _MIN_SECRET_BYTES:
                 raise ValueError(
@@ -343,7 +386,7 @@ class JWTValidator:
         else:
             key = await self._resolve_jwks_key(self._key_set, token)
         try:
-            claims = self._jwt.decode(
+            decoded = self._jwt.decode_complete(
                 token,
                 key=key,
                 algorithms=self._algorithms,
@@ -354,6 +397,8 @@ class JWTValidator:
             )
         except (self._jwt.exceptions.PyJWTError, TypeError, ValueError) as exc:
             raise refusal(UnauthorizedError(), self._decode_reason(exc)) from None
+        claims = decoded["payload"]
+        self._reject_other_kinds(decoded["header"], claims)
         if scopes:
             require_scopes(claims, self._scopes_claim, scopes)
         record_verified_jkt(claims)
@@ -361,6 +406,16 @@ class JWTValidator:
             return await self._claims_to_identity(claims)
         return claims
 
+    def _reject_other_kinds(
+        self, header: dict[str, Any], claims: dict[str, Any]
+    ) -> None:
+        """Refuse a verified token that is not an access token."""
+        if self._typ is not None:
+            typ = header.get("typ")
+            if not isinstance(typ, str) or _normalize_typ(typ) != self._typ:
+                raise refusal(UnauthorizedError(), "not_access_token")
+        reject_other_token_kinds(claims)
+
     def _decode_reason(self, exc: Exception) -> str:
         """The reason code of a failed decode, by PyJWT exception class."""
         for error_cls, reason in self._decode_reasons: