fastapi-multiauth 0.3.0__tar.gz → 0.4.1__tar.gz

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-multiauth
-Version: 0.3.0
+Version: 0.4.1
 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
@@ -25,7 +25,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Dist: anyio>=3.7
 Requires-Dist: async-lru>=2.0
-Requires-Dist: fastapi>=0.100.0
+Requires-Dist: fastapi>=0.108.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: itsdangerous>=2.1
 Requires-Dist: pyjwt[crypto]>=2.13.0 ; extra == 'jwt'
@@ -45,6 +45,7 @@ Composable authentication sources for FastAPI: bring your own validator, combine
 
 [![CI](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml/badge.svg)](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/d3vyce/fastapi-multiauth/graph/badge.svg)](https://codecov.io/gh/d3vyce/fastapi-multiauth)
+[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://app.codspeed.io//badge.json)](https://app.codspeed.io//d3vyce/fastapi-multiauth?utm_source=badge)
 [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
@@ -118,7 +119,7 @@ async def me(user=Security(auth)):
 - **`MultiAuth`**: try several sources in order on a single route (e.g. web session cookie + API bearer token), with all schemes documented in OpenAPI.
 - **Built-in sources**: covering the standard `fastapi.security` schemes:
     - **`HTTPBearerAuth`**: bearer tokens with optional Stripe-style `user_`/`org_` prefixes to route different token types to different validators, plus `generate_token()` for secure token creation.
-    - **`APIKeyCookieAuth`**: cookie sessions with optional HMAC-SHA256 signing (via [itsdangerous](https://itsdangerous.palletsprojects.com/)), embedded expiry, and key rotation.
+    - **`APIKeyCookieAuth`**: cookie sessions with optional HMAC-SHA256 signing (via [itsdangerous](https://itsdangerous.palletsprojects.com/)), embedded expiry, key rotation, and optional per-session ids so your app can list and revoke sessions individually.
     - **`APIKeyHeaderAuth`**: `X-API-Key`-style schemes, with **`APIKeyQueryAuth`** for legacy clients that can only pass a query parameter.
     - **`HTTPBasicAuth`**: `validator(username, password)` with `WWW-Authenticate` realm support.
 - **Token hashing helpers**: `hash_token`/`verify_token_hash` package the "store the hash, never the token" pattern with constant-time comparison.

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/README.md

@@ -4,6 +4,7 @@ Composable authentication sources for FastAPI: bring your own validator, combine
 
 [![CI](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml/badge.svg)](https://github.com/d3vyce/fastapi-multiauth/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/d3vyce/fastapi-multiauth/graph/badge.svg)](https://codecov.io/gh/d3vyce/fastapi-multiauth)
+[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://app.codspeed.io//badge.json)](https://app.codspeed.io//d3vyce/fastapi-multiauth?utm_source=badge)
 [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
@@ -77,7 +78,7 @@ async def me(user=Security(auth)):
 - **`MultiAuth`**: try several sources in order on a single route (e.g. web session cookie + API bearer token), with all schemes documented in OpenAPI.
 - **Built-in sources**: covering the standard `fastapi.security` schemes:
     - **`HTTPBearerAuth`**: bearer tokens with optional Stripe-style `user_`/`org_` prefixes to route different token types to different validators, plus `generate_token()` for secure token creation.
-    - **`APIKeyCookieAuth`**: cookie sessions with optional HMAC-SHA256 signing (via [itsdangerous](https://itsdangerous.palletsprojects.com/)), embedded expiry, and key rotation.
+    - **`APIKeyCookieAuth`**: cookie sessions with optional HMAC-SHA256 signing (via [itsdangerous](https://itsdangerous.palletsprojects.com/)), embedded expiry, key rotation, and optional per-session ids so your app can list and revoke sessions individually.
     - **`APIKeyHeaderAuth`**: `X-API-Key`-style schemes, with **`APIKeyQueryAuth`** for legacy clients that can only pass a query parameter.
     - **`HTTPBasicAuth`**: `validator(username, password)` with `WWW-Authenticate` realm support.
 - **Token hashing helpers**: `hash_token`/`verify_token_hash` package the "store the hash, never the token" pattern with constant-time comparison.

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.3.0"
+version = "0.4.1"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -36,7 +36,7 @@ classifiers = [
 dependencies = [
     "anyio>=3.7",
     "async-lru>=2.0",
-    "fastapi>=0.100.0",
+    "fastapi>=0.108.0",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",
 ]
@@ -67,6 +67,7 @@ dev = [
 tests = [
     "coverage>=7.0.0",
     "pytest-anyio>=0.0.0",
+    "pytest-codspeed>=5.0",
     "pytest-cov>=4.0.0",
     "pytest>=8.0.0",
     "respx>=0.22",
@@ -88,6 +89,10 @@ extend-select = ["S"]
     "S",
     "B008",
 ]
+"benchmarks/**" = [
+    "S",
+    "B008",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-multiauth"
-version = "0.3.0"
+version = "0.4.1"
 description = "Composable authentication sources for FastAPI: bring your own validator, combine multiple schemes, correct OpenAPI by construction"
 readme = "README.md"
 license = "MIT"
@@ -31,7 +31,7 @@ classifiers = [
 dependencies = [
     "anyio>=3.7",
     "async-lru>=2.0",
-    "fastapi>=0.100.0",
+    "fastapi>=0.108.0",
     "httpx>=0.25.0",
     "itsdangerous>=2.1",
 ]
@@ -62,6 +62,7 @@ dev = [
 tests = [
     "coverage>=7.0.0",
     "pytest-anyio>=0.0.0",
+    "pytest-codspeed>=5.0",
     "pytest-cov>=4.0.0",
     "pytest>=8.0.0",
     "respx>=0.22",
@@ -81,6 +82,7 @@ extend-select = ["S"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["S", "B008"]
+"benchmarks/**" = ["S", "B008"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/__init__.py

@@ -23,7 +23,7 @@ from .sources import (
 )
 from .utils import hash_token, verify_token_hash
 
-__version__ = "0.3.0"
+__version__ = "0.4.1"
 
 __all__ = [
     "APIKeyCookieAuth",

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/abc.py

@@ -4,9 +4,9 @@ import copy
 import inspect
 from abc import ABC, abstractmethod
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Annotated, Any
+from typing import TYPE_CHECKING, Any
 
-from fastapi import Depends, HTTPException, Request
+from fastapi import HTTPException, Request
 from fastapi.security import SecurityScopes
 from fastapi.security.base import SecurityBase
 
@@ -17,23 +17,29 @@ if TYPE_CHECKING:
     from typing_extensions import Self
 
 
-def _reject_scopes_kwarg(kwargs: dict[str, Any]) -> None:
-    """Reject ``scopes`` as a validator kwarg."""
-    if "scopes" in kwargs:
-        raise ValueError(
-            "'scopes' is a reserved validator kwarg: security scopes declared "
-            "on the route via Security(..., scopes=[...]) are injected "
-            "automatically. Use a different keyword name."
-        )
+_RESERVED_KWARGS = {
+    "scopes": "injected from the route by Security(..., scopes=[...])",
+    "session_id": "injected by APIKeyCookieAuth(session_id=True)",
+}
+
 
+def _reject_reserved_kwargs(kwargs: dict[str, Any]) -> None:
+    """Reject validator kwargs the library injects itself."""
+    for name, injected in _RESERVED_KWARGS.items():
+        if name in kwargs:
+            raise ValueError(
+                f"'{name}' is a reserved validator kwarg ({injected}): "
+                "the library sets it. Use a different keyword name."
+            )
 
-def _accepts_scopes(fn: Callable[..., Any]) -> bool:
-    """Return whether *fn* declares a ``scopes`` parameter."""
+
+def _accepts_kwarg(fn: Callable[..., Any], name: str) -> bool:
+    """Return whether *fn* declares a *name* parameter."""
     try:
         parameters = inspect.signature(fn).parameters
     except (TypeError, ValueError):
         return False
-    param = parameters.get("scopes")
+    param = parameters.get(name)
     return param is not None and param.kind in (
         inspect.Parameter.POSITIONAL_OR_KEYWORD,
         inspect.Parameter.KEYWORD_ONLY,
@@ -51,17 +57,6 @@ def _unenforceable_scopes_error(owner: object, scopes: list[str]) -> RuntimeErro
     )
 
 
-def _scope_kwargs(
-    owner: object, accepts_scopes: bool, scopes: list[str]
-) -> dict[str, Any]:
-    """Return the ``scopes`` kwarg for a validator, failing closed when unsupported."""
-    if accepts_scopes:
-        return {"scopes": scopes}
-    if scopes:
-        raise _unenforceable_scopes_error(owner, scopes)
-    return {}
-
-
 class _DocOnlyScheme(SecurityBase):
     """Inert stand-in for a ``fastapi.security`` scheme.
 
@@ -77,6 +72,24 @@ class _DocOnlyScheme(SecurityBase):
         return None
 
 
+_SCHEME_CLASSES: dict[type, type] = {}
+
+
+def _carry_scheme(dependency: Any, scheme: SecurityBase) -> None:
+    """Make *dependency* itself the security scheme FastAPI puts in OpenAPI."""
+    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__},
+        )
+    dependency.__class__ = promoted
+    dependency.model = scheme.model
+    dependency.scheme_name = scheme.scheme_name
+
+
 class AuthSource(ABC):
     """Abstract base class for authentication sources.
 
@@ -95,6 +108,8 @@ class AuthSource(ABC):
                 metadata is used, extraction always goes through :meth:`extract`.
         """
         self.scheme = _DocOnlyScheme(scheme) if scheme is not None else None
+        if self.scheme is not None:
+            _carry_scheme(self, self.scheme)
 
         parameters = [
             inspect.Parameter(
@@ -108,17 +123,6 @@ class AuthSource(ABC):
                 annotation=SecurityScopes,
             ),
         ]
-        if self.scheme is not None:
-            # Declared only so the scheme is registered in OpenAPI; the
-            # extracted value is ignored in favor of extract().
-            parameters.append(
-                inspect.Parameter(
-                    "credentials",
-                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                    annotation=Annotated[Any, Depends(self.scheme)],
-                    default=None,
-                )
-            )
         self.__signature__ = inspect.Signature(parameters, return_annotation=Any)
 
     @abstractmethod
@@ -193,18 +197,24 @@ class ValidatedAuthSource(AuthSource):
             validator: Sync or async callable returning the identity.
             scheme: Optional ``fastapi.security`` scheme for OpenAPI.
             **kwargs: Extra keyword arguments forwarded to the validator on
-                every call. ``scopes`` is reserved (injected from the route).
+                every call. Names the library injects itself are reserved:
+                ``scopes`` and ``session_id``.
         """
-        _reject_scopes_kwarg(kwargs)
+        _reject_reserved_kwargs(kwargs)
         self._validator = ensure_async(validator)
-        self._accepts_scopes = _accepts_scopes(validator)
+        self._accepts_scopes = _accepts_kwarg(validator, "scopes")
         self._kwargs = kwargs
         super().__init__(scheme)
 
-    async def _call_validator(self, *args: Any, scopes: list[str]) -> Any:
+    async def _call_validator(
+        self, *args: Any, scopes: list[str], **injected: Any
+    ) -> Any:
         """Invoke the validator with scope and configured kwargs forwarding."""
-        extra = _scope_kwargs(self, self._accepts_scopes, scopes)
-        return await self._validator(*args, **extra, **self._kwargs)
+        if self._accepts_scopes:
+            injected["scopes"] = scopes
+        elif scopes:  # fail closed: the validator cannot check them
+            raise _unenforceable_scopes_error(self, scopes)
+        return await self._validator(*args, **self._kwargs, **injected)
 
     async def authenticate(self, credential: str) -> Any:
         """Validate a credential and return the identity (no route scopes)."""
@@ -215,8 +225,11 @@ class ValidatedAuthSource(AuthSource):
         return await self._call_validator(credential, scopes=scopes)
 
     def require(self, **kwargs: Any) -> "Self":
-        """Return a copy of this source with additional (or overriding) validator kwargs."""
-        _reject_scopes_kwarg(kwargs)
+        """Return a copy of this source with additional (or overriding) validator kwargs.
+
+        Reserved names (``scopes``, ``session_id``) are rejected here too.
+        """
+        _reject_reserved_kwargs(kwargs)
         clone = copy.copy(self)
         clone._kwargs = {**self._kwargs, **kwargs}
         return clone

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/jwt.py

@@ -256,5 +256,10 @@ class JWTValidator:
                 # provider's JWKS must not take down every login.
                 continue
             keys[entry.get("kid") or ""] = key
+        if not keys:
+            raise _JWKSFetchError(
+                f"JWKS document has no usable signing key "
+                f"({len(document['keys'])} entries)"
+            )
         self._keys = keys
         self._fetched_at = time.monotonic()

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/oauth/client.py

@@ -3,6 +3,7 @@
 import contextlib
 import functools
 from typing import Any, Literal, NamedTuple
+from urllib.parse import urlsplit
 
 import httpx
 from async_lru import alru_cache
@@ -41,13 +42,25 @@ class OIDCEndpoints(NamedTuple):
 
 def _validate_issuer(discovery_url: str, issuer: Any) -> None:
     """Check the discovery document claims the issuer it was fetched from."""
-    if not discovery_url.endswith(_DISCOVERY_SUFFIX):
-        return
-    expected = discovery_url.removesuffix(_DISCOVERY_SUFFIX).rstrip("/")
-    if not isinstance(issuer, str) or issuer.rstrip("/") != expected:
+    if not isinstance(issuer, str) or not issuer:
         raise OAuthDiscoveryError(
-            f"discovery document issuer {issuer!r} does not match the "
-            f"expected issuer {expected!r} derived from the discovery URL"
+            f"discovery document has no usable 'issuer' (got {issuer!r})"
+        )
+    claimed = issuer.rstrip("/")
+    parts = urlsplit(discovery_url)
+    origin = f"{parts.scheme}://{parts.netloc}"
+    path = parts.path.rstrip("/")
+    if path.endswith(_DISCOVERY_SUFFIX):
+        expected = (origin + path.removesuffix(_DISCOVERY_SUFFIX)).rstrip("/")
+        if claimed != expected:
+            raise OAuthDiscoveryError(
+                f"discovery document issuer {issuer!r} does not match the "
+                f"expected issuer {expected!r} derived from the discovery URL"
+            )
+    elif claimed != origin and not claimed.startswith(f"{origin}/"):
+        raise OAuthDiscoveryError(
+            f"discovery document issuer {issuer!r} is not served by "
+            f"{origin!r}, the origin the document was fetched from"
         )
 
 

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/sources/basic.py

@@ -13,6 +13,20 @@ from ..abc import ValidatedAuthSource
 from ..utils import authorization_credential
 
 
+def _basic_challenge(realm: str | None) -> str:
+    """Build the ``WWW-Authenticate`` challenge, escaping *realm* (RFC 7230 §3.2.6)."""
+    if realm is None:
+        return "Basic"
+    if not (realm.isascii() and realm.isprintable()):
+        raise ValueError(
+            f"realm must be printable US-ASCII (RFC 7617 §2.1), got {realm!r}: "
+            "control characters have no escaped form in a quoted-string, and "
+            "non-ASCII cannot be carried in a header value"
+        )
+    escaped = realm.replace("\\", "\\\\").replace('"', '\\"')
+    return f'Basic realm="{escaped}"'
+
+
 class HTTPBasicAuth(ValidatedAuthSource):
     """HTTP Basic authentication source (wraps ``HTTPBasic`` for OpenAPI, RFC 7617).
 
@@ -23,7 +37,7 @@ class HTTPBasicAuth(ValidatedAuthSource):
         validator: Sync or async callable receiving ``(username, password)`` and
             returning the identity; raises
             :class:`~fastapi_multiauth.exceptions.UnauthorizedError` on failure.
-        realm: Optional protection-space name for the ``WWW-Authenticate`` challenge.
+        realm: Optional protection-space name for the ``WWW-Authenticate``.
         scheme_name: OpenAPI security scheme name (default ``HTTPBasic``).
         **kwargs: Extra keyword arguments forwarded to the validator on every call.
     """
@@ -36,7 +50,7 @@ class HTTPBasicAuth(ValidatedAuthSource):
         scheme_name: str | None = None,
         **kwargs: Any,
     ) -> None:
-        self._realm = realm
+        self._challenge = _basic_challenge(realm)
         super().__init__(
             validator,
             HTTPBasic(auto_error=False, scheme_name=scheme_name),
@@ -45,9 +59,7 @@ class HTTPBasicAuth(ValidatedAuthSource):
 
     def www_authenticate(self) -> str:
         """``Basic`` challenge, with the realm when configured (RFC 7617 §2)."""
-        if self._realm is not None:
-            return f'Basic realm="{self._realm}"'
-        return "Basic"
+        return self._challenge
 
     async def extract(self, request: Request) -> str | None:
         """Return the base64 credentials blob, or ``None`` when absent or empty.

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/sources/cookie.py

@@ -1,6 +1,7 @@
 """Cookie-based authentication source."""
 
 import hashlib
+import secrets
 from collections.abc import Callable, Sequence
 from typing import Any, Literal
 
@@ -10,7 +11,7 @@ from itsdangerous import BadSignature, TimestampSigner
 
 from fastapi_multiauth.exceptions import UnauthorizedError
 
-from ..abc import ValidatedAuthSource
+from ..abc import ValidatedAuthSource, _accepts_kwarg
 
 _MIN_SECRET_KEY_BYTES = 32
 _SALT_PREFIX = "fastapi-multiauth.cookie."
@@ -35,6 +36,16 @@ def _normalize_secret_keys(secret_key: str | Sequence[str] | None) -> list[str]:
     return keys
 
 
+def _precomputed_signer(keys: list[str], salt: str) -> TimestampSigner:
+    """A ``TimestampSigner`` deriving its keys once here instead of per ``unsign``."""
+    probe = TimestampSigner(keys, salt=salt, digest_method=hashlib.sha256)
+    return TimestampSigner(
+        [probe.derive_key(key) for key in keys],
+        digest_method=hashlib.sha256,
+        key_derivation="none",
+    )
+
+
 class APIKeyCookieAuth(ValidatedAuthSource):
     """Cookie-based authentication source (wraps ``APIKeyCookie`` for OpenAPI).
 
@@ -48,6 +59,10 @@ class APIKeyCookieAuth(ValidatedAuthSource):
             after signature verification when signed) and returning the identity.
         secret_key: One key or a sequence to rotate (first signs, all verify);
             each at least 32 bytes. When ``None``, the cookie is not signed.
+        session_id: Mint a random id per :meth:`set_cookie` and inject it into
+            the validator as ``session_id``. Requires ``secret_key`` and a
+            validator declaring that parameter; changing it invalidates
+            existing cookies.
         ttl: Cookie lifetime in seconds (default 24 h); also enforced
             server-side when the cookie is signed.
         secure: Set the ``Secure`` flag (default ``True``); disable only in local dev.
@@ -64,6 +79,7 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         validator: Callable[..., Any],
         *,
         secret_key: str | Sequence[str] | None = None,
+        session_id: bool = False,
         ttl: int = 86400,
         secure: bool = True,
         samesite: SameSite = "lax",
@@ -76,13 +92,25 @@ class APIKeyCookieAuth(ValidatedAuthSource):
             raise ValueError("ttl must be a positive number of seconds")
         self._name = name
         self._secret_keys = _normalize_secret_keys(secret_key)
+        if session_id:
+            if not self._secret_keys:
+                raise ValueError(
+                    "session_id requires secret_key: without a signature the "
+                    "client could forge or swap the session id"
+                )
+            if not _accepts_kwarg(validator, "session_id"):
+                raise ValueError(
+                    "session_id requires a validator declaring a 'session_id' "
+                    "parameter: the minted id is injected on every call"
+                )
+        self._session_id = session_id
         # itsdangerous verifies against every key in the list but signs with
         # the last one — reverse so the first configured key is the signer.
+        # The salt also separates the two payload layouts.
         self._signer = (
-            TimestampSigner(
+            _precomputed_signer(
                 list(reversed(self._secret_keys)),
-                salt=f"{_SALT_PREFIX}{name}",
-                digest_method=hashlib.sha256,
+                f"{_SALT_PREFIX}{name}{'.sid' if session_id else ''}",
             )
             if self._secret_keys
             else None
@@ -118,17 +146,53 @@ class APIKeyCookieAuth(ValidatedAuthSource):
         except BadSignature:
             raise UnauthorizedError() from None
 
+    @property
+    def name(self) -> str:
+        """Cookie name. Read-only: the signing salt is derived from it."""
+        return self._name
+
+    @property
+    def ttl(self) -> int:
+        """Cookie lifetime in seconds: use it to derive your session's expiry."""
+        return self._ttl
+
     async def extract(self, request: Request) -> str | None:
         """Return the raw cookie value, or ``None`` when absent or empty."""
         return request.cookies.get(self._name) or None
 
+    def session_id_of(self, request: Request) -> str | None:
+        """Return *request*'s session id without running the validator.
+
+        ``None`` when ``session_id`` is off, or the cookie is absent, expired
+        or forged.
+        """
+        if not self._session_id:
+            return None
+        cookie_value = request.cookies.get(self._name)
+        if not cookie_value:
+            return None
+        try:
+            return self._verify(cookie_value).partition(".")[0]
+        except UnauthorizedError:
+            return None
+
     async def authenticate_scoped(self, credential: str, scopes: list[str]) -> Any:
         """Verify the cookie, forwarding route-declared scopes to the validator."""
         plain = self._verify(credential)
-        return await self._call_validator(plain, scopes=scopes)
-
-    def set_cookie(self, response: Response, value: str) -> None:
-        """Attach the cookie to *response*, signing it when ``secret_key`` is set."""
+        if not self._session_id:
+            return await self._call_validator(plain, scopes=scopes)
+        sid, _, value = plain.partition(".")
+        return await self._call_validator(value, scopes=scopes, session_id=sid)
+
+    def set_cookie(self, response: Response, value: str) -> str | None:
+        """Attach the cookie to *response*, signing it when ``secret_key`` is set.
+
+        Returns the minted session id: always a ``str`` when ``session_id`` is
+        on, always ``None`` when it is off.
+        """
+        sid = secrets.token_urlsafe(16) if self._session_id else None
+        if sid is not None:
+            value = f"{sid}.{value}"
         cookie_value = self._sign(value) if self._signer else value
         response.set_cookie(
             self._name,
@@ -140,9 +204,16 @@ class APIKeyCookieAuth(ValidatedAuthSource):
             domain=self._domain,
             path=self._path,
         )
+        return sid
+
+    def delete_cookie(
+        self, response: Response, request: Request | None = None
+    ) -> str | None:
+        """Clear the session cookie (logout) from this client only.
 
-    def delete_cookie(self, response: Response) -> None:
-        """Clear the session cookie (logout) from this client only."""
+        Returns *request*'s session id when it verifies (revoke it server-side
+        for a hard logout), ``None`` otherwise.
+        """
         response.delete_cookie(
             self._name,
             httponly=True,
@@ -151,3 +222,4 @@ class APIKeyCookieAuth(ValidatedAuthSource):
             domain=self._domain,
             path=self._path,
         )
+        return self.session_id_of(request) if request is not None else None

{fastapi_multiauth-0.3.0 → fastapi_multiauth-0.4.1}/src/fastapi_multiauth/sources/multi.py

@@ -1,14 +1,14 @@
 """MultiAuth: combine multiple authentication sources into a single callable."""
 
 import inspect
-from typing import Any, cast
+from typing import Annotated, Any, cast
 
-from fastapi import Request
+from fastapi import Depends, Request
 from fastapi.security import SecurityScopes
 
 from fastapi_multiauth.exceptions import UnauthorizedError
 
-from ..abc import AuthSource
+from ..abc import AuthSource, _carry_scheme
 from ..utils import challenge_headers
 
 
@@ -39,10 +39,6 @@ class MultiAuth:
                 )
         self._sources = sources
 
-        # Build a merged signature that includes the security-scheme Depends()
-        # parameters from every source so FastAPI registers them in OpenAPI
-        # docs. Parameters are renamed `_s{i}_{name}` — unique per source
-        # index — so two sources of the same type both keep their scheme.
         merged: list[inspect.Parameter] = [
             inspect.Parameter(
                 "request",
@@ -55,11 +51,20 @@ class MultiAuth:
                 annotation=SecurityScopes,
             ),
         ]
+        carried = sources[0].scheme if sources else None
+        if carried is not None:
+            _carry_scheme(self, carried)
         for i, source in enumerate(sources):
-            for name, param in inspect.signature(source).parameters.items():
-                if name in ("request", "security_scopes"):
-                    continue
-                merged.append(param.replace(name=f"_s{i}_{name}"))
+            if source.scheme is None or (i == 0 and carried is not None):
+                continue
+            merged.append(
+                inspect.Parameter(
+                    f"_s{i}_credentials",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Any, Depends(cast(Any, source.scheme))],
+                    default=None,
+                )
+            )
         self.__signature__ = inspect.Signature(merged, return_annotation=Any)
 
         # The combined challenge is fixed once the sources are known; build it