xtr-security-http 3.0.0__tar.gz → 4.0.2__tar.gz

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 xterr
+Copyright (c) 2004-present Fabien Potencier
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-security-http
-Version: 3.0.0
+Version: 4.0.2
 Summary: The HTTP edge of xtr security: firewalls, authenticators, bearer access tokens and the request surface.
 Keywords: security,authentication,firewall,fastapi,oauth2
 Author: Xterr
@@ -14,11 +14,13 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Dist: xtr-security-core>=3.0,<4
-Requires-Dist: xtr-http-kernel>=3.0,<4
-Requires-Dist: xtr-event-dispatcher-contracts>=3.0,<4
-Requires-Dist: xtr-logging-contracts>=3.0,<4
-Requires-Dist: xtr-password-hasher>=3.0,<4
+Requires-Dist: xtr-security-core>=4.0,<5
+Requires-Dist: xtr-http-kernel>=4.0,<5
+Requires-Dist: xtr-dependency-injection[fastapi]>=4.0,<5
+Requires-Dist: xtr-event-dispatcher>=4.0,<5
+Requires-Dist: xtr-event-dispatcher-contracts>=4.0,<5
+Requires-Dist: xtr-logging-contracts>=4.0,<5
+Requires-Dist: xtr-password-hasher>=4.0,<5
 Requires-Dist: fastapi>=0.123
 Requires-Dist: starlette>=0.40
 Requires-Dist: anyio>=4.0
@@ -182,7 +184,7 @@ routes. See [xtr-security's Quick start](../xtr-security#quick-start) for the wh
 ### Firewalls and the map
 
 A **`FirewallContextInterface`** is one firewall's runtime pieces: its `name`, its
-`authenticator_manager`, its `access_listener`, its own event `dispatcher`, the FastAPI `scheme`
+`authenticator_manager`, its `access_listener`, the FastAPI `scheme`
 it shows in OpenAPI, whether it has `security` at all, and the optional `entry_point`,
 `access_denied_handler` and `scope_denied_handler` that answer a failure. A **`FirewallMap`**
 holds those contexts: `match(request)` returns the first whose matcher claims the request,
@@ -363,9 +365,10 @@ answers a denied scope with a `403` carrying the RFC 6750 `insufficient_scope` c
 
 ### Security events
 
-The event name constants a dispatcher keys on live in `security_events.py`: `CHECK_PASSPORT`,
-`AUTHENTICATION_TOKEN_CREATED`, `LOGIN_SUCCESS`, `LOGIN_FAILURE`. A listener names the constant
-rather than importing the event class, so a listener chosen at runtime stays in step.
+Four events are raised around a request's authentication — `CheckPassportEvent`,
+`AuthenticationTokenCreatedEvent`, `LoginSuccessEvent`, `LoginFailureEvent`. A subscriber listens
+to the event class itself (the dispatcher derives each event's name from its class), so there is no
+separate table of name constants to keep in step.
 
 ## Errors
 
@@ -394,10 +397,9 @@ xtr_security_http/
 ├── access_map.py               the ordered access-control rules
 ├── request_matcher/            path, host, method, ip, chain, callable
 ├── authorization/              OAuth2ScopeVoter, oauth2_scope, the scope-denied handler
-├── decorator/                  Firewall, IsGranted, CurrentUser, IsGrantedContext
+├── decorator/                  IsGranted, CurrentUser, IsGrantedContext
 ├── entry_point/                AuthenticationEntryPointInterface
 ├── event/                      the four firewall events
-├── security_events.py          the name each is dispatched under
 ├── event_listener/             the listeners the bundle registers (incl. the timing guard)
 └── exception/                  the errors this package adds
 ```

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/README.md

@@ -151,7 +151,7 @@ routes. See [xtr-security's Quick start](../xtr-security#quick-start) for the wh
 ### Firewalls and the map
 
 A **`FirewallContextInterface`** is one firewall's runtime pieces: its `name`, its
-`authenticator_manager`, its `access_listener`, its own event `dispatcher`, the FastAPI `scheme`
+`authenticator_manager`, its `access_listener`, the FastAPI `scheme`
 it shows in OpenAPI, whether it has `security` at all, and the optional `entry_point`,
 `access_denied_handler` and `scope_denied_handler` that answer a failure. A **`FirewallMap`**
 holds those contexts: `match(request)` returns the first whose matcher claims the request,
@@ -332,9 +332,10 @@ answers a denied scope with a `403` carrying the RFC 6750 `insufficient_scope` c
 
 ### Security events
 
-The event name constants a dispatcher keys on live in `security_events.py`: `CHECK_PASSPORT`,
-`AUTHENTICATION_TOKEN_CREATED`, `LOGIN_SUCCESS`, `LOGIN_FAILURE`. A listener names the constant
-rather than importing the event class, so a listener chosen at runtime stays in step.
+Four events are raised around a request's authentication — `CheckPassportEvent`,
+`AuthenticationTokenCreatedEvent`, `LoginSuccessEvent`, `LoginFailureEvent`. A subscriber listens
+to the event class itself (the dispatcher derives each event's name from its class), so there is no
+separate table of name constants to keep in step.
 
 ## Errors
 
@@ -363,10 +364,9 @@ xtr_security_http/
 ├── access_map.py               the ordered access-control rules
 ├── request_matcher/            path, host, method, ip, chain, callable
 ├── authorization/              OAuth2ScopeVoter, oauth2_scope, the scope-denied handler
-├── decorator/                  Firewall, IsGranted, CurrentUser, IsGrantedContext
+├── decorator/                  IsGranted, CurrentUser, IsGrantedContext
 ├── entry_point/                AuthenticationEntryPointInterface
 ├── event/                      the four firewall events
-├── security_events.py          the name each is dispatched under
 ├── event_listener/             the listeners the bundle registers (incl. the timing guard)
 └── exception/                  the errors this package adds
 ```

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-security-http"
-version = "3.0.0"
+version = "4.0.2"
 description = "The HTTP edge of xtr security: firewalls, authenticators, bearer access tokens and the request surface."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,11 +23,13 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "xtr-security-core>=3.0,<4",
-    "xtr-http-kernel>=3.0,<4",
-    "xtr-event-dispatcher-contracts>=3.0,<4",
-    "xtr-logging-contracts>=3.0,<4",
-    "xtr-password-hasher>=3.0,<4",
+    "xtr-security-core>=4.0,<5",
+    "xtr-http-kernel>=4.0,<5",
+    "xtr-dependency-injection[fastapi]>=4.0,<5",
+    "xtr-event-dispatcher>=4.0,<5",
+    "xtr-event-dispatcher-contracts>=4.0,<5",
+    "xtr-logging-contracts>=4.0,<5",
+    "xtr-password-hasher>=4.0,<5",
     "fastapi>=0.123",
     "starlette>=0.40",
     "anyio>=4.0",
@@ -52,8 +54,6 @@ dev = [
     "pytest-cov>=5",
     "anyio>=4.0",
     "ty>=0.0.83",
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-event-dispatcher>=3.0,<4",
     "httpx>=0.27",
     "joserfc>=1.7",
 ]

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-security-http"
-version = "3.0.0"
+version = "4.0.2"
 description = "The HTTP edge of xtr security: firewalls, authenticators, bearer access tokens and the request surface."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,11 +20,13 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "xtr-security-core>=3.0,<4",
-    "xtr-http-kernel>=3.0,<4",
-    "xtr-event-dispatcher-contracts>=3.0,<4",
-    "xtr-logging-contracts>=3.0,<4",
-    "xtr-password-hasher>=3.0,<4",
+    "xtr-security-core>=4.0,<5",
+    "xtr-http-kernel>=4.0,<5",
+    "xtr-dependency-injection[fastapi]>=4.0,<5",
+    "xtr-event-dispatcher>=4.0,<5",
+    "xtr-event-dispatcher-contracts>=4.0,<5",
+    "xtr-logging-contracts>=4.0,<5",
+    "xtr-password-hasher>=4.0,<5",
     "fastapi>=0.123",
     "starlette>=0.40",
     "anyio>=4.0",
@@ -45,8 +47,6 @@ dev = [
     "pytest-cov>=5",
     "anyio>=4.0",
     "ty>=0.0.83",
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-event-dispatcher>=3.0,<4",
     "httpx>=0.27",
     "joserfc>=1.7",
 ]

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/src/xtr_security_http/__init__.py

@@ -9,6 +9,8 @@ and xtr-http-kernel.
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
+
 from .access_map import AccessMap
 from .access_map_interface import AccessMapInterface
 from .access_token import (
@@ -40,6 +42,7 @@ from .authenticator.passport.badge import (
     PreAuthenticatedUserBadge,
     UserBadge,
 )
+from .authenticator.passport.badge.user_badge import MAX_USERNAME_LENGTH
 from .authenticator.passport.credentials import (
     CredentialsInterface,
     CustomCredentials,
@@ -51,6 +54,7 @@ from .authorization import (
     InsufficientScopeAccessDeniedHandler,
     OAuth2ScopeVoter,
     oauth2_scope,
+    parse_oauth2_scope,
 )
 from .decorator.current_user import CurrentUser
 from .decorator.is_granted import IsGranted
@@ -82,8 +86,18 @@ from .firewall_scheme_registry import (
     FirewallSchemeRegistry,
     active_firewall_schemes,
 )
+from .request_matcher import (
+    CallableRequestMatcher,
+    ChainRequestMatcher,
+    HostRequestMatcher,
+    IpRequestMatcher,
+    MethodRequestMatcher,
+    PathRequestMatcher,
+    RequestMatcherInterface,
+)
 
 __all__ = [
+    "MAX_USERNAME_LENGTH",
     "AbstractAuthenticator",
     "AccessDeniedHandlerInterface",
     "AccessListener",
@@ -100,7 +114,9 @@ __all__ = [
     "AuthenticatorManager",
     "AuthenticatorManagerInterface",
     "BadgeInterface",
+    "CallableRequestMatcher",
     "ChainAccessTokenExtractor",
+    "ChainRequestMatcher",
     "CheckCredentialsListener",
     "CheckPassportEvent",
     "CredentialsInterface",
@@ -117,27 +133,41 @@ __all__ = [
     "FirewallSchemeRegistry",
     "FormEncodedBodyExtractor",
     "HeaderAccessTokenExtractor",
+    "HostRequestMatcher",
     "InsufficientScopeAccessDeniedHandler",
     "InvalidAccessTokenError",
+    "IpRequestMatcher",
     "IsGranted",
     "IsGrantedContext",
     "LoginFailureEvent",
     "LoginSuccessEvent",
+    "MethodRequestMatcher",
     "OAuth2ScopeVoter",
     "Passport",
     "PasswordCredentials",
     "PasswordMigratingListener",
     "PasswordUpgradeBadge",
+    "PathRequestMatcher",
     "PostAuthenticationToken",
     "PreAuthenticatedUserBadge",
     "QueryAccessTokenExtractor",
+    "RequestMatcherInterface",
     "SelfValidatingPassport",
     "UnknownFirewallError",
     "UserBadge",
     "UserCheckerListener",
     "UserProviderListener",
+    "__version__",
     "active_firewall_schemes",
     "is_sensitive",
     "mask",
     "oauth2_scope",
+    "parse_oauth2_scope",
 ]
+
+try:
+    __version__ = version("xtr-security-http")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read; having no
+    # version is better than refusing to import.
+    __version__ = "0+unknown"

xtr_security_http-4.0.2/src/xtr_security_http/_challenge.py

@@ -0,0 +1,64 @@
+r"""Writing a ``WWW-Authenticate`` challenge: quoting and cache headers.
+
+A challenge's ``realm``, ``error_description`` and ``scope`` are written as
+RFC 7235 ``quoted-string`` values; a ``\`` or a ``"`` inside one must be
+backslash-escaped or the header is malformed. Both the access-token
+authenticator's challenge and the insufficient-scope handler's challenge quote
+their values through here, so the escaping is written once.
+
+Every challenge response also carries the no-store cache directives
+:func:`no_store_headers` adds, so a ``401`` or ``403`` is never kept by a shared
+cache or a browser and replayed.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from xtr_security_core.exception import InvalidArgumentError
+
+__all__ = ["no_store_headers", "quote_auth_param"]
+
+#: The control characters a ``quoted-string`` cannot carry. Its ``qdtext``
+#: admits HTAB and SP; every other character below ``%x20``, and ``%x7f``, has
+#: no spelling in the grammar — not even as a ``quoted-pair``.
+_REFUSED_CONTROLS: Final = re.compile(r"[\x00-\x08\x0a-\x1f\x7f]")
+
+#: The cache directives a challenge response carries, so neither a shared cache
+#: nor a browser keeps a ``401``/``403`` and replays it to another caller or
+#: after the credential changed. ``no-store`` is the HTTP/1.1 directive;
+#: ``Pragma: no-cache`` is the HTTP/1.0 belt-and-braces an old intermediary
+#: still reads.
+_NO_STORE: Final = {"Cache-Control": "no-store", "Pragma": "no-cache"}
+
+
+def quote_auth_param(value: str) -> str:
+    r"""Return ``value`` as an RFC 7235 ``quoted-string``, escaping ``\`` and ``"``.
+
+    Raises:
+        InvalidArgumentError: When ``value`` carries a control character. A
+            ``quoted-string`` has no way to write one, so the challenge would be
+            malformed — and a CR or an LF would split the header. Every value
+            quoted here is declared by the application, so this is a mistake to
+            report where it is made, not a request to answer.
+    """
+    refused = _REFUSED_CONTROLS.search(value)
+    if refused is not None:
+        raise InvalidArgumentError(
+            f"An auth-param value cannot carry the control character {refused.group()!r}.",
+        )
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def no_store_headers(**headers: str) -> dict[str, str]:
+    """Return ``headers`` with the no-store cache directives a challenge needs.
+
+    A challenge response must not be cached: a shared cache that kept a ``401``
+    would answer another caller's request with it, and a browser that kept one
+    would replay it after the credential changed. Every challenge this package
+    writes merges its own headers — a ``WWW-Authenticate`` — through here so the
+    directives are set in one place.
+    """
+    return {**_NO_STORE, **headers}

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/src/xtr_security_http/_runner.py

@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING
 
 from xtr_security_core.authentication.token.null_token import NullToken
 from xtr_security_core.authorization.access_decision import AccessDecision
-from xtr_security_core.exception import AccessDeniedError, AuthenticationError
+from xtr_security_core.exception import AccessDeniedError
 
 from ._state import (
     AUTHENTICATED_FIREWALLS_KEY,
@@ -63,6 +63,10 @@ async def run_firewall(  # noqa: PLR0913 -- the firewall's request, scopes and i
     """
     context = _resolve(firewall_map, name, request)
     if context is None or not context.security:
+        if scopes:
+            raise AccessDeniedError(
+                "A scoped resource was reached with no firewall to authenticate the caller.",
+            )
         return
 
     setattr(request.state, FIREWALL_CONTEXT_KEY, context)
@@ -86,25 +90,38 @@ def _resolve(
 async def _authenticate_once(context: FirewallContextInterface, request: Request) -> None:
     """Authenticate the request under ``context`` at most once, memoised by name.
 
+    Only a settled outcome is memoised: ``None`` for a pass that authenticated,
+    the exception for one that did not. Recording a crash as a pass would let a
+    later call over the same request skip authentication and go on with a null
+    token, so whatever the authenticators raised — a failure the handlers own or
+    a bug they do not — is recorded and raised again by every later call. A later
+    call raises a fresh instance of the recorded error's type and message rather
+    than the stored instance itself, so re-raising it does not splice this
+    request's traceback onto the one the first call already unwound, nor let a
+    caller that mutates the caught exception change what a later call raises.
+
     Raises:
         AuthenticationError: When authentication fails, on this call and every
             later one this request.
+        BaseException: Whatever else authentication raised, re-raised by every
+            later call this request rather than passing it off as authenticated.
         CarriedResponse: When a handler produced a response to send.
     """
     memo: dict[str, BaseException | None] = getattr(request.state, AUTHENTICATED_FIREWALLS_KEY, {})
     if not memo:
         setattr(request.state, AUTHENTICATED_FIREWALLS_KEY, memo)
     if context.name in memo:
-        outcome = memo[context.name]
-        if isinstance(outcome, BaseException):
-            raise outcome
+        recorded = memo[context.name]
+        if recorded is not None:
+            raise type(recorded)(str(recorded))
         return
     try:
         response = await context.authenticator_manager.authenticate_request(request)
-    except AuthenticationError as error:
+    except BaseException as error:
         memo[context.name] = error
         raise
-    memo[context.name] = None
+    else:
+        memo[context.name] = None
     if response is not None:
         raise CarriedResponse(response)
 

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/src/xtr_security_http/_state.py

@@ -22,9 +22,10 @@ __all__ = [
 
 _PREFIX: Final = "_xtr_security_"
 
-#: Maps a firewall name to the outcome of authenticating this request under it —
-#: the error authentication raised, or ``None`` for a plain success — so
-#: authentication stays one pass per firewall.
+#: Maps a firewall name to the settled outcome of authenticating this request
+#: under it — the exception authentication raised, or ``None`` for a pass that
+#: authenticated — so authentication stays one pass per firewall. A name is
+#: absent until an outcome settles, so no unfinished pass reads as authenticated.
 AUTHENTICATED_FIREWALLS_KEY: Final = f"{_PREFIX}authenticated_firewalls"
 
 #: The firewall context in charge of the request, stashed by the firewall so the

xtr_security_http-4.0.2/src/xtr_security_http/access_token/form_encoded_body_extractor.py

@@ -0,0 +1,120 @@
+"""An extractor that reads a bearer token from a form-encoded body."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+from urllib.parse import parse_qs
+
+from fastapi.security import HTTPBearer
+from typing_extensions import override
+
+from .access_token_extractor_interface import AccessTokenExtractorInterface
+
+if TYPE_CHECKING:
+    from fastapi.security.base import SecurityBase
+    from starlette.requests import Request
+
+__all__ = ["FormEncodedBodyExtractor"]
+
+_FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+
+#: The largest form body read, so a bearer token in a body cannot be a memory
+#: exhaustion vector; a larger declared or streamed body yields no token.
+_MAX_BODY_SIZE = 64 * 1024
+
+
+@final
+class FormEncodedBodyExtractor(AccessTokenExtractorInterface):
+    """Reads a token from a form field of an ``x-www-form-urlencoded`` body.
+
+    RFC 6750 allows a bearer token in a form body; this reads the
+    ``access_token`` field of one, when the request carries that content type.
+    The body is parsed directly, so no form-parsing dependency is needed. There
+    is no dedicated OpenAPI scheme for a body-carried token, so it documents
+    itself as the standard bearer scheme.
+
+    Attributes:
+        field_name: The form field the token is read from.
+    """
+
+    __slots__ = ("_bearer", "_field_name")
+
+    def __init__(self, field_name: str = "access_token") -> None:
+        """Build the extractor for the ``field_name`` form field."""
+        self._field_name = field_name
+        self._bearer = HTTPBearer(auto_error=False, bearerFormat="JWT", scheme_name="Bearer")
+
+    @override
+    async def extract_access_token(self, request: Request) -> str | None:
+        """Return the token in the form body, or ``None`` when it is absent.
+
+        A body whose ``content-length`` is above the 64 KiB cap — or, with no
+        usable ``content-length``, one that streams past the cap — yields
+        ``None``, as does a body that is not valid UTF-8; an endpoint behind the
+        firewall then challenges rather than failing on the oversize or
+        undecodable body.
+        """
+        content_type = request.headers.get("content-type", "")
+        if not content_type.lower().startswith(_FORM_CONTENT_TYPE):
+            return None
+        body = await _read_capped(request)
+        if body is None:
+            return None
+        try:
+            text = body.decode("utf-8", errors="strict")
+        except UnicodeDecodeError:
+            return None
+        fields = parse_qs(text)
+        values = fields.get(self._field_name)
+        return values[0] if values else None
+
+    @override
+    def scheme(self) -> SecurityBase:
+        """Return the bearer scheme this extractor documents by."""
+        return self._bearer
+
+
+async def _read_capped(request: Request) -> bytes | None:
+    """Read the body of ``request`` up to the cap, or ``None`` when it is exceeded.
+
+    A ``content-length`` the sender declares is only believed when it is a run
+    of ASCII digits, which is all RFC 9110 allows: ``int`` would also take
+    ``-1``, ``+5`` or a padded ``" 10 "``, and reading the body on the strength
+    of such a header would leave the cap unenforced. A header is decoded as
+    latin-1, so it can even carry a superscript ``²``, which counts as a digit
+    yet is no number ``int`` can read. Anything else — absent, padded, signed or
+    not a number — is read by streaming, which caps on what actually arrives
+    rather than on what was promised. A body read by streaming is cached back on
+    the request through :func:`_cache_body`, so an endpoint behind the firewall
+    can still read its own body — ``await request.body()`` or a form parse —
+    after the extractor has looked for a token.
+    """
+    declared = request.headers.get("content-length")
+    if declared is not None and declared.isascii() and declared.isdigit():
+        if int(declared) > _MAX_BODY_SIZE:
+            return None
+        return await request.body()
+    collected = bytearray()
+    async for chunk in request.stream():
+        collected.extend(chunk)
+        if len(collected) > _MAX_BODY_SIZE:
+            return None
+    body = bytes(collected)
+    _cache_body(request, body)
+    return body
+
+
+def _cache_body(request: Request, body: bytes) -> None:
+    """Hand the streamed ``body`` back to Starlette as the request's cached body.
+
+    ``request.stream()`` consumes the body once; without this, a later
+    ``await request.body()`` from the endpoint raises ``RuntimeError: Stream
+    consumed``. Starlette's own ``body()`` caches into the ``_body`` attribute
+    and every later ``stream()``/``body()`` serves from it, so setting that
+    attribute is how a value read ahead of the route is made available to it.
+    This is the one private attribute that mechanism exposes; it is set in this
+    single documented place.
+    """
+    # SLF001/reportPrivateUsage: Starlette's own body() caches into this same
+    # attribute; setting it is the supported re-read path. See the docstring.
+    request._body = body  # noqa: SLF001 # pyright: ignore[reportPrivateUsage]

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/src/xtr_security_http/access_token/oidc/oidc_token_handler.py

@@ -50,7 +50,8 @@ class OidcTokenHandler:
 
     The identifier is read from ``claim`` (``sub`` by default). With no provider
     the claims are the user — an
-    :class:`~xtr_security_core.user.oidc_user.OidcUser`; with one, its
+    :class:`~xtr_security_core.user.oidc_user.OidcUser` built from every claim,
+    so a ``roles`` claim grants the roles it holds; with one, its
     identifier loads the user, the claims handed alongside to a provider that
     reads them. The badge carries the granted ``scope`` (from the ``scope``
     string or the ``scp`` list), the ``client_id``, the ``jti`` and every claim.
@@ -158,8 +159,8 @@ class OidcTokenHandler:
             "iss": {"essential": True, "values": list(self._issuers)},
             "aud": {"essential": True, "value": self._audience},
             "exp": {"essential": True},
-            self._claim: {"essential": True},
         }
+        options[self._claim] = {**options.get(self._claim, {}), "essential": True}
         registry = JWTClaimsRegistry(now=self._clock(), leeway=self._leeway, **options)
         try:
             registry.validate(dict(claims))
@@ -192,12 +193,11 @@ class OidcTokenHandler:
         the claims travel to it; with a plain one only the identifier does.
         """
         provider = self._user_provider
-        claim = self._claim
         if provider is None:
 
             def load_from_claims(identifier: str) -> UserInterface:
                 del identifier
-                return OidcUser(claims, identifier_claim=claim)
+                return OidcUser.from_claims(claims)
 
             return load_from_claims
         if AttributesBasedUserProviderInterface in type(provider).__mro__:

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/src/xtr_security_http/authenticator/access_token_authenticator.py

@@ -8,6 +8,7 @@ from starlette.responses import JSONResponse
 from typing_extensions import override
 from xtr_security_core.exception import AuthenticationError, BadCredentialsError
 
+from xtr_security_http._challenge import no_store_headers, quote_auth_param
 from xtr_security_http.authenticator.passport.self_validating_passport import SelfValidatingPassport
 from xtr_security_http.authorization.oauth2_scope_voter import OAuth2ScopeVoter
 from xtr_security_http.entry_point.authentication_entry_point_interface import (
@@ -95,6 +96,11 @@ class AccessTokenAuthenticator(AbstractAuthenticator, AuthenticationEntryPointIn
         self._failure_handler = failure_handler
         self._realm = realm
 
+    @property
+    def extractor(self) -> AccessTokenExtractorInterface:
+        """Return the extractor that reads the token out of a request."""
+        return self._extractor
+
     @override
     def supports(self, request: Request) -> bool | None:
         """Handle the request only when it carries a token this extractor reads.
@@ -180,14 +186,18 @@ class AccessTokenAuthenticator(AbstractAuthenticator, AuthenticationEntryPointIn
         del request
         parts = ["Bearer"]
         if self._realm is not None:
-            parts.append(f'realm="{self._realm}"')
+            parts.append(f"realm={quote_auth_param(self._realm)}")
         body: dict[str, str] = {}
         if isinstance(error, InvalidAccessTokenError):
             parts.append('error="invalid_token"')
-            parts.append(f'error_description="{error.get_message_key()}"')
+            parts.append(f"error_description={quote_auth_param(error.get_message_key())}")
             body = {"error": "invalid_token"}
         challenge = parts[0] + (" " + ", ".join(parts[1:]) if len(parts) > 1 else "")
-        return JSONResponse(body, status_code=401, headers={"WWW-Authenticate": challenge})
+        return JSONResponse(
+            body,
+            status_code=401,
+            headers=no_store_headers(**{"WWW-Authenticate": challenge}),
+        )
 
     def _normalize_scope(self, scope: object) -> list[str]:
         """Turn a scope list or space-separated string into a list of scopes."""

{xtr_security_http-3.0.0 → xtr_security_http-4.0.2}/src/xtr_security_http/authenticator/passport/passport.py

@@ -50,7 +50,12 @@ class Passport:
         self._attributes: dict[str, object] = dict(attributes) if attributes is not None else {}
 
     def add_badge(self, badge: BadgeInterface) -> Passport:
-        """Attach ``badge``, replacing any badge of its class, and return self."""
+        """Attach ``badge``, replacing any badge of its exact class, and return self.
+
+        Badges are keyed by ``type(badge)`` — the exact runtime class, not a base
+        class — so a subclass of a badge does not replace, and is not found by,
+        the base class it derives from.
+        """
         self._badges[type(badge)] = badge
         return self
 
@@ -59,7 +64,11 @@ class Passport:
         return badge_class in self._badges
 
     def get_badge(self, badge_class: type[_BadgeT]) -> _BadgeT | None:
-        """Return the badge of ``badge_class``, or ``None`` when none is attached."""
+        """Return the badge of ``badge_class``, or ``None`` when none is attached.
+
+        The lookup is by exact class: a badge is found only under the class it was
+        attached as, never under a base class of it.
+        """
         badge = self._badges.get(badge_class)
         return badge if isinstance(badge, badge_class) else None