easyssf-receiver-fastapi 0.7.0__tar.gz

easyssf_receiver_fastapi-0.7.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+
+# Local
+scratch/
+.DS_Store
+conformance/certs/

easyssf_receiver_fastapi-0.7.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: easyssf-receiver-fastapi
+Version: 0.7.0
+Summary: The easyssf SSF receiver for FastAPI: the push endpoint, the rejection of revoked access tokens and the receiver's lifecycle
+Project-URL: Homepage, https://easyssf.org
+Project-URL: Repository, https://github.com/easyssf/easyssf-python
+Project-URL: Changelog, https://github.com/easyssf/easyssf-python/blob/main/CHANGELOG.md
+Author: the easyssf authors
+License-Expression: Apache-2.0
+Keywords: caep,fastapi,openid,risc,security-events,ssf
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: easyssf-receiver<0.8,>=0.7
+Requires-Dist: fastapi<1,>=0.115
+Description-Content-Type: text/markdown
+
+# easyssf-receiver-fastapi
+
+The [easyssf](https://github.com/easyssf/easyssf-python) SSF receiver for FastAPI: the push
+endpoint as a router, the rejection of revoked access tokens as a dependency or middleware, and
+the receiver's lifecycle as a lifespan, with its health as a route. The Python counterpart of the
+Rust `easyssf-receiver-axum` crate. Everything else, the configuration, the handlers, the stream
+management and polling, is `easyssf-receiver`; see its [README](../README.md).
+
+```sh
+uv add easyssf-receiver-fastapi      # or: pip install easyssf-receiver-fastapi
+```
+
+## The receiver with the application
+
+`receiver_lifespan` starts the receiver when the application starts (streams are registered and
+polling begins in the background) and closes it on shutdown (the acknowledgements it owes are
+sent, the HTTP client it made for itself is closed). With a lifespan of your own, the receiver
+starts after yours entered and stops before it exits, so the handlers find what the application
+set up:
+
+```python
+from fastapi import FastAPI
+from easyssf.fastapi import receiver_lifespan
+from easyssf.receiver import Receiver, ReceiverConfig
+
+receiver = Receiver(ReceiverConfig.from_mapping(settings["easyssf"]["receiver"]), handlers=[audit])
+app = FastAPI(lifespan=receiver_lifespan(receiver))  # or receiver_lifespan(receiver, my_lifespan)
+```
+
+## The push endpoint
+
+`push_router_for` mounts `POST easyssf.receiver.push.endpoint-path` (`/ssf/push` by default),
+`push_router(handler, path)` any push handler at any path. The transmitter authenticates with its
+`Authorization` header and the SET with its signature, so the route belongs outside the
+authentication of the application; it is left out of the OpenAPI schema. The response is the
+one of RFC 8935: `202` for an accepted SET, `400` with an error document (`application/json`,
+`Content-Language: en`) for an invalid one, `401` for a transmitter that could not be
+authenticated, `413` for a body beyond 256 KiB, `503` or `500` to have the SET delivered again.
+
+```python
+from easyssf.fastapi import push_router_for
+
+app.include_router(push_router_for(receiver))
+```
+
+## Rejecting revoked access tokens
+
+The receiver's revocation handler records the sessions and users that `CaepSessionRevoked`
+events name in `receiver.token_revocation_store`. `revocation_dependency` turns the store into a
+dependency that answers `401` with `WWW-Authenticate: Bearer error="invalid_token",
+error_description="The token was revoked"` for a token of a revoked session or user, and `503`
+when the store cannot answer (it fails closed). It does not validate tokens: `extract` reads the
+claims the authentication of the application left on the request, `None` for a request without
+one.
+
+```python
+from datetime import UTC, datetime
+from fastapi import Depends, Request
+from easyssf.fastapi import revocation_dependency
+from easyssf.receiver import TokenClaims
+
+
+def token_claims(request: Request) -> TokenClaims | None:
+    token = getattr(request.state, "token", None)  # left there by your authentication dependency
+    if token is None:
+        return None
+    return TokenClaims(
+        issuer=token["iss"],
+        subject=token["sub"],
+        session_id=token.get("sid", ""),
+        issued_at=datetime.fromtimestamp(token["iat"], tz=UTC),
+    )
+
+
+reject_revoked = revocation_dependency(receiver.token_revocation_store, token_claims)
+
+
+@app.get("/api/orders", dependencies=[Depends(require_access_token), Depends(reject_revoked)])
+async def orders() -> list[str]: ...
+```
+
+For the whole application, the raw ASGI `RevocationMiddleware` of the receiver does the same from
+the scope, added after (inside) the middleware that validates the tokens:
+
+```python
+from easyssf.fastapi import RevocationMiddleware
+
+app.add_middleware(
+    RevocationMiddleware,
+    store=receiver.token_revocation_store,
+    extract=lambda scope: scope["state"].get("token_claims"),
+)
+```
+
+## Health
+
+`health_router` serves `receiver.health()` as JSON at `/health`: `200` while the receiver is
+healthy or degraded (no contact with a transmitter yet; the application starts without it),
+`503` when it is unhealthy (a poll failed, a stream cannot be used).
+
+```python
+from easyssf.fastapi import health_router
+
+app.include_router(health_router(receiver))  # or health_router(receiver, path="/ready")
+```
+
+## Example
+
+[`examples/fastapi/resource-server`](../examples/fastapi/resource-server) is an OAuth2 resource
+server on FastAPI against the Keycloak of [`examples/keycloak`](../examples/keycloak): it
+registers its stream, validates access tokens with the keys of the transmitter and rejects them
+once their session was revoked; see [`examples/README.md`](../examples/README.md).

easyssf_receiver_fastapi-0.7.0/README.md

@@ -0,0 +1,112 @@
+# easyssf-receiver-fastapi
+
+The [easyssf](https://github.com/easyssf/easyssf-python) SSF receiver for FastAPI: the push
+endpoint as a router, the rejection of revoked access tokens as a dependency or middleware, and
+the receiver's lifecycle as a lifespan, with its health as a route. The Python counterpart of the
+Rust `easyssf-receiver-axum` crate. Everything else, the configuration, the handlers, the stream
+management and polling, is `easyssf-receiver`; see its [README](../README.md).
+
+```sh
+uv add easyssf-receiver-fastapi      # or: pip install easyssf-receiver-fastapi
+```
+
+## The receiver with the application
+
+`receiver_lifespan` starts the receiver when the application starts (streams are registered and
+polling begins in the background) and closes it on shutdown (the acknowledgements it owes are
+sent, the HTTP client it made for itself is closed). With a lifespan of your own, the receiver
+starts after yours entered and stops before it exits, so the handlers find what the application
+set up:
+
+```python
+from fastapi import FastAPI
+from easyssf.fastapi import receiver_lifespan
+from easyssf.receiver import Receiver, ReceiverConfig
+
+receiver = Receiver(ReceiverConfig.from_mapping(settings["easyssf"]["receiver"]), handlers=[audit])
+app = FastAPI(lifespan=receiver_lifespan(receiver))  # or receiver_lifespan(receiver, my_lifespan)
+```
+
+## The push endpoint
+
+`push_router_for` mounts `POST easyssf.receiver.push.endpoint-path` (`/ssf/push` by default),
+`push_router(handler, path)` any push handler at any path. The transmitter authenticates with its
+`Authorization` header and the SET with its signature, so the route belongs outside the
+authentication of the application; it is left out of the OpenAPI schema. The response is the
+one of RFC 8935: `202` for an accepted SET, `400` with an error document (`application/json`,
+`Content-Language: en`) for an invalid one, `401` for a transmitter that could not be
+authenticated, `413` for a body beyond 256 KiB, `503` or `500` to have the SET delivered again.
+
+```python
+from easyssf.fastapi import push_router_for
+
+app.include_router(push_router_for(receiver))
+```
+
+## Rejecting revoked access tokens
+
+The receiver's revocation handler records the sessions and users that `CaepSessionRevoked`
+events name in `receiver.token_revocation_store`. `revocation_dependency` turns the store into a
+dependency that answers `401` with `WWW-Authenticate: Bearer error="invalid_token",
+error_description="The token was revoked"` for a token of a revoked session or user, and `503`
+when the store cannot answer (it fails closed). It does not validate tokens: `extract` reads the
+claims the authentication of the application left on the request, `None` for a request without
+one.
+
+```python
+from datetime import UTC, datetime
+from fastapi import Depends, Request
+from easyssf.fastapi import revocation_dependency
+from easyssf.receiver import TokenClaims
+
+
+def token_claims(request: Request) -> TokenClaims | None:
+    token = getattr(request.state, "token", None)  # left there by your authentication dependency
+    if token is None:
+        return None
+    return TokenClaims(
+        issuer=token["iss"],
+        subject=token["sub"],
+        session_id=token.get("sid", ""),
+        issued_at=datetime.fromtimestamp(token["iat"], tz=UTC),
+    )
+
+
+reject_revoked = revocation_dependency(receiver.token_revocation_store, token_claims)
+
+
+@app.get("/api/orders", dependencies=[Depends(require_access_token), Depends(reject_revoked)])
+async def orders() -> list[str]: ...
+```
+
+For the whole application, the raw ASGI `RevocationMiddleware` of the receiver does the same from
+the scope, added after (inside) the middleware that validates the tokens:
+
+```python
+from easyssf.fastapi import RevocationMiddleware
+
+app.add_middleware(
+    RevocationMiddleware,
+    store=receiver.token_revocation_store,
+    extract=lambda scope: scope["state"].get("token_claims"),
+)
+```
+
+## Health
+
+`health_router` serves `receiver.health()` as JSON at `/health`: `200` while the receiver is
+healthy or degraded (no contact with a transmitter yet; the application starts without it),
+`503` when it is unhealthy (a poll failed, a stream cannot be used).
+
+```python
+from easyssf.fastapi import health_router
+
+app.include_router(health_router(receiver))  # or health_router(receiver, path="/ready")
+```
+
+## Example
+
+[`examples/fastapi/resource-server`](../examples/fastapi/resource-server) is an OAuth2 resource
+server on FastAPI against the Keycloak of [`examples/keycloak`](../examples/keycloak): it
+registers its stream, validates access tokens with the keys of the transmitter and rejects them
+once their session was revoked; see [`examples/README.md`](../examples/README.md).

easyssf_receiver_fastapi-0.7.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "easyssf-receiver-fastapi"
+version = "0.7.0"
+description = "The easyssf SSF receiver for FastAPI: the push endpoint, the rejection of revoked access tokens and the receiver's lifecycle"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "the easyssf authors" }]
+keywords = ["ssf", "caep", "risc", "openid", "security-events", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Framework :: FastAPI",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "easyssf-receiver>=0.7,<0.8",
+    "fastapi>=0.115,<1",
+]
+
+[project.urls]
+Homepage = "https://easyssf.org"
+Repository = "https://github.com/easyssf/easyssf-python"
+Changelog = "https://github.com/easyssf/easyssf-python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/easyssf"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "tests"]
+
+[tool.uv.sources]
+easyssf-receiver = { workspace = true }
+easyssf-test = { workspace = true }
+
+[dependency-groups]
+dev = ["easyssf-test", "itsdangerous>=2.2"]

easyssf_receiver_fastapi-0.7.0/src/easyssf/fastapi/__init__.py

@@ -0,0 +1,39 @@
+"""The easyssf receiver for FastAPI: the push endpoint as a router, the rejection of revoked access
+tokens as a dependency or middleware, and the receiver's lifecycle as a lifespan, plus its health
+as a route. The Python counterpart of the Rust ``easyssf-receiver-axum`` crate.
+
+Example:
+    >>> from fastapi import Depends, FastAPI, Request
+    >>> from easyssf.fastapi import health_router, push_router_for, receiver_lifespan, revocation_dependency
+    >>>
+    >>> receiver = Receiver(config)
+    >>> app = FastAPI(lifespan=receiver_lifespan(receiver))
+    >>> app.include_router(push_router_for(receiver))  # POST /ssf/push, or easyssf.receiver.push.endpoint-path
+    >>> app.include_router(health_router(receiver))  # GET /health
+    >>> reject_revoked = revocation_dependency(receiver.token_revocation_store, lambda request: request.state.token)
+    >>> @app.get("/api/orders", dependencies=[Depends(require_access_token), Depends(reject_revoked)])
+    ... async def orders() -> list[str]: ...
+"""
+
+from .lifecycle import DEFAULT_HEALTH_PATH, health_router, receiver_lifespan
+from .push import DEFAULT_PUSH_PATH, into_response, push_router, push_router_for
+from .revocation import (
+    REVOKED_WWW_AUTHENTICATE,
+    RequestTokenClaimsExtractor,
+    RevocationMiddleware,
+    revocation_dependency,
+)
+
+__all__ = [
+    "DEFAULT_HEALTH_PATH",
+    "DEFAULT_PUSH_PATH",
+    "REVOKED_WWW_AUTHENTICATE",
+    "RequestTokenClaimsExtractor",
+    "RevocationMiddleware",
+    "health_router",
+    "into_response",
+    "push_router",
+    "push_router_for",
+    "receiver_lifespan",
+    "revocation_dependency",
+]

easyssf_receiver_fastapi-0.7.0/src/easyssf/fastapi/lifecycle.py

@@ -0,0 +1,68 @@
+"""The lifecycle of the receiver on FastAPI: ``receiver_lifespan`` starts and stops the receiver
+with the application, ``health_router`` serves its health."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, Final
+
+from fastapi import APIRouter, FastAPI
+from fastapi.responses import JSONResponse
+from starlette.types import Lifespan
+
+from easyssf.receiver.receiver import Receiver
+from easyssf.receiver.transmitter import HealthStatus
+
+__all__ = ["DEFAULT_HEALTH_PATH", "health_router", "receiver_lifespan"]
+
+DEFAULT_HEALTH_PATH: Final = "/health"
+"""Where :func:`health_router` mounts the endpoint by default."""
+
+_HTTP_OK: Final = 200
+_HTTP_UNAVAILABLE: Final = 503
+
+
+def receiver_lifespan(receiver: Receiver, inner: Lifespan[Any] | None = None) -> Lifespan[Any]:
+    """A lifespan for ``FastAPI(lifespan=...)`` that starts the receiver when the application
+    starts (the streams are registered and polling begins in the background) and closes it when
+    the application shuts down (the acknowledgements it owes are sent, the HTTP client it made for
+    itself is closed, a given one stays open). With ``inner``, the
+    lifespan of the application, the receiver starts after ``inner`` entered and stops before it
+    exits, so that the handlers find what the application set up, and whatever ``inner`` yields
+    becomes the state of the application.
+
+    Example:
+        >>> app = FastAPI(lifespan=receiver_lifespan(receiver))
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[Any]:
+        if inner is None:
+            async with receiver:
+                yield None
+            return
+        async with inner(app) as state, receiver:
+            yield state
+
+    return lifespan
+
+
+def health_router(receiver: Receiver, path: str = DEFAULT_HEALTH_PATH) -> APIRouter:
+    """A router with ``GET path`` answering :meth:`~easyssf.receiver.receiver.Receiver.health` as
+    JSON (:meth:`~easyssf.receiver.receiver.ReceiverHealth.to_mapping`): 200 while the receiver is
+    healthy or degraded (no contact with a transmitter yet, the application starts without it),
+    503 when it is unhealthy (a poll failed, a stream cannot be used).
+
+    Example:
+        >>> app.include_router(health_router(receiver))  # GET /health
+    """
+    router = APIRouter()
+
+    @router.get(path, name="easyssf-health")
+    async def health() -> JSONResponse:
+        current = await receiver.health()
+        status = _HTTP_UNAVAILABLE if current.status is HealthStatus.UNHEALTHY else _HTTP_OK
+        return JSONResponse(current.to_mapping(), status_code=status)
+
+    return router

easyssf_receiver_fastapi-0.7.0/src/easyssf/fastapi/push.py

@@ -0,0 +1,93 @@
+"""The push endpoint (RFC 8935) as a FastAPI router: ``push_router`` mounts a
+:class:`~easyssf.receiver.push.PushHandler` at a path, ``push_router_for`` the one of a configured
+:class:`~easyssf.receiver.receiver.Receiver` at ``easyssf.receiver.push.endpoint-path``. The
+status and header behaviour is that of :func:`easyssf.receiver.asgi.push_app`; the Rust
+``easyssf-receiver-axum`` crate is the model."""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from fastapi import APIRouter, Request, Response
+
+from easyssf.receiver.errors import ErrorCode
+from easyssf.receiver.push import MAX_SET_SIZE, PUSH_CONTENT_LANGUAGE, PUSH_CONTENT_TYPE, PushHandler, PushResponse
+from easyssf.receiver.receiver import Receiver
+
+__all__ = ["DEFAULT_PUSH_PATH", "into_response", "push_router", "push_router_for"]
+
+DEFAULT_PUSH_PATH: Final = "/ssf/push"
+"""Where :func:`push_router` mounts the endpoint by default."""
+
+_HTTP_TOO_LARGE: Final = 413
+_log: Final = logging.getLogger("easyssf.fastapi")
+
+
+def push_router(push_handler: PushHandler, path: str = DEFAULT_PUSH_PATH) -> APIRouter:
+    """A router with ``POST path`` serving the push endpoint: the SET is the body
+    (``application/secevent+jwt``), the transmitter authenticates with its ``Authorization`` header
+    and the SET with its signature, so the route belongs outside the authentication of the
+    application. The response carries the status of
+    :meth:`~easyssf.receiver.push.PushHandler.handle` and, with an error document, the
+    ``Content-Type`` and ``Content-Language`` headers of RFC 8935, section 2.3. A body beyond
+    :data:`~easyssf.receiver.push.MAX_SET_SIZE` is answered with 413 without being read in full.
+    The route is left out of the OpenAPI schema: it is for the transmitter, not for the users of
+    the API.
+
+    Example:
+        >>> app.include_router(push_router(receiver.push_handler))  # POST /ssf/push
+    """
+    router = APIRouter()
+
+    @router.post(path, include_in_schema=False, name="easyssf-push")
+    async def push(request: Request) -> Response:
+        declared = request.headers.get("content-length")
+        if declared is not None and declared.isdigit() and int(declared) > MAX_SET_SIZE:
+            return into_response(_too_large())
+        # read up to one byte beyond the limit, as the raw ASGI app does, whatever the size of the
+        # chunks the server hands over: no more is needed to reject the request, and a transmitter
+        # cannot make the endpoint buffer anything it likes
+        body = b""
+        async for chunk in request.stream():
+            body += chunk[: MAX_SET_SIZE + 1 - len(body)]
+            if len(body) > MAX_SET_SIZE:
+                break
+        response = await push_handler.handle(request.headers.get("authorization"), body)
+        return into_response(response)
+
+    return router
+
+
+def push_router_for(receiver: Receiver) -> APIRouter:
+    """A router with the push endpoint of a configured receiver, at
+    :attr:`~easyssf.receiver.receiver.Receiver.push_endpoint_path`
+    (``easyssf.receiver.push.endpoint-path``, ``/ssf/push`` by default).
+
+    Example:
+        >>> app.include_router(push_router_for(receiver))
+    """
+    path = receiver.push_endpoint_path
+    _log.info("Receiving SSF security events at %s", path, extra={"path": path})
+    return push_router(receiver.push_handler, path)
+
+
+def into_response(push_response: PushResponse) -> Response:
+    """The response of the push handler as a FastAPI response: its status and, with an error
+    document, the body as :data:`~easyssf.receiver.push.PUSH_CONTENT_TYPE` with the
+    :data:`~easyssf.receiver.push.PUSH_CONTENT_LANGUAGE` header (RFC 8935, section 2.3); no
+    headers of the two without a body."""
+    content = push_response.body_bytes
+    if content is None:
+        return Response(status_code=push_response.status)
+    return Response(
+        content=content,
+        status_code=push_response.status,
+        media_type=PUSH_CONTENT_TYPE,
+        headers={"Content-Language": PUSH_CONTENT_LANGUAGE},
+    )
+
+
+def _too_large() -> PushResponse:
+    """The response of :meth:`~easyssf.receiver.push.PushHandler.handle` to a SET beyond the limit."""
+    return PushResponse.error(_HTTP_TOO_LARGE, ErrorCode.INVALID_REQUEST, "The SET is too large")

easyssf_receiver_fastapi-0.7.0/src/easyssf/fastapi/revocation.py

@@ -0,0 +1,93 @@
+"""Rejecting the access tokens that security events revoked, for a resource server on FastAPI: a
+dependency for ``Depends`` on the routes that need it, and the ASGI
+:class:`~easyssf.receiver.revocation.RevocationMiddleware` of the receiver for the whole
+application. Neither validates tokens: ``extract`` reads the claims the authentication of the
+application left on the request, so both work with any of it (an OAuth2 dependency of your own,
+a JWT middleware, ...). A request without claims passes; whether anonymous requests are allowed
+is for the application to decide."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Final, TypeAlias
+
+from fastapi import HTTPException, Request
+
+from easyssf.receiver.revocation import (
+    REVOKED_WWW_AUTHENTICATE,
+    TokenClaims,
+    TokenRevocationStore,
+    reject_if_revoked,
+)
+from easyssf.receiver.revocation import RevocationMiddleware as _RevocationMiddleware
+
+__all__ = [
+    "REVOKED_WWW_AUTHENTICATE",
+    "RequestTokenClaimsExtractor",
+    "RevocationMiddleware",
+    "revocation_dependency",
+]
+
+_HTTP_UNAUTHORIZED: Final = 401
+_HTTP_UNAVAILABLE: Final = 503
+_log: Final = logging.getLogger("easyssf.fastapi.revocation")
+
+RequestTokenClaimsExtractor: TypeAlias = Callable[[Request], "TokenClaims | Awaitable[TokenClaims | None] | None"]
+"""Reads the :class:`~easyssf.receiver.revocation.TokenClaims` of the access token a request
+carries, as left on it (``request.state``, say) by the dependency or middleware that validated
+it; ``None`` for a request without a token. Sync or async."""
+
+
+class RevocationMiddleware(_RevocationMiddleware):
+    """The raw ASGI :class:`easyssf.receiver.revocation.RevocationMiddleware`, for the whole
+    application: it rejects requests whose access token was revoked with 401 Unauthorized and the
+    ``WWW-Authenticate`` challenge of :data:`REVOKED_WWW_AUTHENTICATE`, answers 503 when the store
+    fails, and lets everything else through. Add it with the store and the extractor as keyword
+    arguments, after (that is, inside) the middleware that validates the access token and leaves
+    its claims on the scope::
+
+        app.add_middleware(RevocationMiddleware, store=receiver.token_revocation_store, extract=token_claims)
+
+    where ``extract`` reads the :class:`~easyssf.receiver.revocation.TokenClaims` from the ASGI
+    scope (``scope["state"]`` is what ``request.state`` writes to) and is sync or async. For the
+    routes that need it only, :func:`revocation_dependency` reads the :class:`fastapi.Request`
+    instead.
+    """
+
+
+def revocation_dependency(
+    store: TokenRevocationStore, extract: RequestTokenClaimsExtractor
+) -> Callable[[Request], Awaitable[None]]:
+    """A dependency for ``Depends`` that rejects a request whose access token was revoked with
+    401 Unauthorized and the ``WWW-Authenticate`` challenge of
+    :data:`~easyssf.receiver.revocation.REVOKED_WWW_AUTHENTICATE` (RFC 6750, section 3.1), and
+    answers 503 Service Unavailable when the store fails: a store that cannot answer must not let
+    a revoked token through. Put it after the dependency that validates the token and leaves its
+    claims where ``extract`` reads them.
+
+    Args:
+        store: the revocations, :attr:`~easyssf.receiver.receiver.Receiver.token_revocation_store`.
+        extract: reads the claims of the request's token, ``None`` for a request without one.
+
+    Example:
+        >>> reject_revoked = revocation_dependency(receiver.token_revocation_store, token_claims_of)
+        >>> @app.get("/api/me", dependencies=[Depends(require_access_token), Depends(reject_revoked)])
+        ... async def me(request: Request) -> dict[str, str]: ...
+    """
+
+    async def reject_revoked(request: Request) -> None:
+        claims = extract(request)
+        if inspect.isawaitable(claims):
+            claims = await claims
+        try:
+            rejected = await reject_if_revoked(store, claims)
+        except Exception as error:
+            _log.exception("The revocation store failed, rejecting the request")
+            raise HTTPException(_HTTP_UNAVAILABLE, detail="revocation check failed") from error
+        if rejected:
+            _log.debug("Rejecting a revoked access token", extra={"subject": claims.subject if claims else ""})
+            raise HTTPException(_HTTP_UNAUTHORIZED, headers={"WWW-Authenticate": REVOKED_WWW_AUTHENTICATE})
+
+    return reject_revoked

easyssf_receiver_fastapi-0.7.0/tests/test_fastapi.py

@@ -0,0 +1,407 @@
+"""The FastAPI integration: the push router end to end against the test transmitter, the
+revocation dependency and middleware, the lifespan and the health route. The counterpart of the
+tests of the Rust easyssf-receiver-axum crate."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime, timedelta
+
+import httpx
+import pytest
+from fastapi import Depends, FastAPI, Request
+
+from easyssf.core.subjects import complex_subject, iss_sub, opaque
+from easyssf.fastapi import (
+    REVOKED_WWW_AUTHENTICATE,
+    RevocationMiddleware,
+    health_router,
+    into_response,
+    push_router,
+    push_router_for,
+    receiver_lifespan,
+    revocation_dependency,
+)
+from easyssf.receiver.config import ReceiverConfig, default_receiver_config
+from easyssf.receiver.errors import StoreError
+from easyssf.receiver.event import EventContext, for_event
+from easyssf.receiver.push import MAX_SET_SIZE, PushResponse
+from easyssf.receiver.receiver import Receiver
+from easyssf.receiver.revocation import InMemoryTokenRevocationStore, TokenClaims
+from easyssf.testing import AUDIENCE, SECEVENT_JWT_TYPE, TestTransmitter, eventually, shared_key, sign
+
+SECRET = "Bearer s3cr3t"
+PUSH_HEADERS = {"Authorization": SECRET, "Content-Type": "application/secevent+jwt"}
+
+
+class Recorder:
+    """Counts the SETs it handled."""
+
+    def __init__(self) -> None:
+        self.count = 0
+
+    async def handle(self, context: EventContext) -> None:
+        self.count += 1
+
+
+class FailingStore:
+    """A revocation store that fails every call."""
+
+    async def revoke_session(self, issuer: str, session_id: str) -> None:
+        raise StoreError(RuntimeError("down"))
+
+    async def revoke_subject(self, issuer: str, subject: str, revoked_at: datetime) -> None:
+        raise StoreError(RuntimeError("down"))
+
+    async def is_session_revoked(self, issuer: str, session_id: str) -> bool:
+        raise StoreError(RuntimeError("down"))
+
+    async def subject_revoked_at(self, issuer: str, subject: str) -> datetime | None:
+        raise StoreError(RuntimeError("down"))
+
+
+def push_config(transmitter: TestTransmitter) -> ReceiverConfig:
+    config = default_receiver_config()
+    config.transmitter_issuer = transmitter.issuer
+    config.expected_audience = AUDIENCE
+    config.push.expected_auth_header = SECRET
+    return config
+
+
+def client_of(app: FastAPI) -> httpx.AsyncClient:
+    return httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="https://app.example")
+
+
+def claims_of_request(request: Request) -> TokenClaims | None:
+    token = request.headers.get("x-token")
+    if token is None:
+        return None
+    issuer, subject, session_id = token.split("|")
+    return TokenClaims(issuer=issuer, subject=subject, session_id=session_id, issued_at=datetime.now(tz=UTC))
+
+
+def claims_of_scope(scope: dict[str, object]) -> TokenClaims | None:
+    headers = dict(scope.get("headers") or ())  # type: ignore[call-overload]
+    token = headers.get(b"x-token")
+    if token is None:
+        return None
+    issuer, subject, session_id = token.decode().split("|")
+    return TokenClaims(issuer=issuer, subject=subject, session_id=session_id, issued_at=datetime.now(tz=UTC))
+
+
+# -- the push router --------------------------------------------------------------------------------
+
+
+async def test_push_route_rejects_a_request_without_the_authorization_header():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(push_router(receiver.push_handler))
+    encoded_set = transmitter.set("CaepSessionRevoked", iss_sub(transmitter.issuer, "alice"))
+    async with client_of(app) as client:
+        response = await client.post(
+            "/ssf/push", content=encoded_set, headers={"Content-Type": "application/secevent+jwt"}
+        )
+    assert response.status_code == 401
+    assert response.headers["content-type"] == "application/json"
+    assert response.headers["content-language"] == "en"
+    assert response.json()["err"] == "authentication_failed"
+
+
+async def test_push_route_accepts_a_set_and_invokes_the_handlers():
+    transmitter = TestTransmitter()
+    recorder = Recorder()
+    receiver = Receiver(
+        push_config(transmitter), http_client=transmitter.client, handlers=[for_event("CaepSessionRevoked", recorder)]
+    )
+    app = FastAPI()
+    app.include_router(push_router(receiver.push_handler))
+    subject = complex_subject(iss_sub(transmitter.issuer, "alice"), opaque("s1"))
+    encoded_set = transmitter.set("CaepSessionRevoked", subject)
+    async with client_of(app) as client:
+        response = await client.post("/ssf/push", content=encoded_set, headers=PUSH_HEADERS)
+    assert response.status_code == 202
+    assert response.content == b""
+    assert "content-type" not in response.headers
+    assert "content-language" not in response.headers
+    assert recorder.count == 1
+    token = TokenClaims(issuer=transmitter.issuer, subject="alice", session_id="s1", issued_at=datetime.now(tz=UTC))
+    assert await receiver.token_revocation_store.is_session_revoked(token.issuer, token.session_id)
+
+
+async def test_push_route_rejects_an_invalid_set_with_an_error_document():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(push_router(receiver.push_handler))
+    claims = transmitter.set_claims("CaepSessionRevoked", iss_sub(transmitter.issuer, "alice"))
+    unknown_key = sign(shared_key().with_key_id("unknown"), SECEVENT_JWT_TYPE, claims)
+    async with client_of(app) as client:
+        garbage = await client.post("/ssf/push", content="not-a-security-event-token", headers=PUSH_HEADERS)
+        response = await client.post("/ssf/push", content=unknown_key, headers=PUSH_HEADERS)
+    # not a JWS at all: no issuer to route it by
+    assert garbage.status_code == 400
+    assert garbage.json()["err"] == "invalid_issuer"
+    assert response.status_code == 400
+    assert response.headers["content-type"] == "application/json"
+    assert response.headers["content-language"] == "en"
+    assert response.json() == {"err": "invalid_key", "description": "The SET is signed with an unknown key"}
+
+
+async def test_push_route_rejects_an_oversized_body_by_its_content_length():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(push_router(receiver.push_handler))
+    async with client_of(app) as client:
+        response = await client.post("/ssf/push", content=b"a" * (MAX_SET_SIZE + 1), headers=PUSH_HEADERS)
+    assert response.status_code == 413
+    assert response.json() == {"err": "invalid_request", "description": "The SET is too large"}
+    assert response.headers["content-language"] == "en"
+
+
+async def test_push_route_rejects_an_oversized_body_sent_in_chunks():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(push_router(receiver.push_handler))
+
+    async def chunks() -> AsyncIterator[bytes]:
+        for _ in range(MAX_SET_SIZE // 1024 + 1):
+            yield b"a" * 1024
+
+    async with client_of(app) as client:
+        response = await client.post("/ssf/push", content=chunks(), headers=PUSH_HEADERS)
+    assert response.status_code == 413
+    assert response.json()["err"] == "invalid_request"
+
+
+async def test_push_route_buffers_no_more_than_the_limit_whatever_the_chunks():
+    seen: list[int] = []
+
+    class Spy:
+        async def handle(self, authorization: str | None, body: bytes) -> PushResponse:
+            seen.append(len(body))
+            return PushResponse(413, None)
+
+    app = FastAPI()
+    app.include_router(push_router(Spy()))  # type: ignore[arg-type]
+
+    async def one_chunk() -> AsyncIterator[bytes]:
+        yield b"a" * (4 * MAX_SET_SIZE)
+
+    async with client_of(app) as client:
+        response = await client.post("/ssf/push", content=one_chunk(), headers=PUSH_HEADERS)
+    assert response.status_code == 413
+    assert seen == [MAX_SET_SIZE + 1], "one byte beyond the limit, not the chunk"
+
+
+async def test_push_route_answers_other_methods_with_405():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(push_router(receiver.push_handler))
+    async with client_of(app) as client:
+        response = await client.get("/ssf/push")
+    assert response.status_code == 405
+
+
+async def test_push_router_for_mounts_at_the_configured_path():
+    transmitter = TestTransmitter()
+    config = push_config(transmitter)
+    config.push.endpoint_path = "/events/ssf"
+    receiver = Receiver(config, http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(push_router_for(receiver))
+    encoded_set = transmitter.set("CaepSessionRevoked", iss_sub(transmitter.issuer, "alice"))
+    async with client_of(app) as client:
+        assert (await client.post("/events/ssf", content=encoded_set, headers=PUSH_HEADERS)).status_code == 202
+        assert (await client.post("/ssf/push", content=encoded_set, headers=PUSH_HEADERS)).status_code == 404
+
+
+def test_into_response_sets_the_headers_only_with_a_body():
+    accepted = into_response(PushResponse(202))
+    assert accepted.status_code == 202
+    assert accepted.body == b""
+    assert "content-type" not in accepted.headers
+    rejected = into_response(PushResponse.error(400, "invalid_key", "The signature of the SET is invalid"))
+    assert rejected.status_code == 400
+    assert rejected.headers["content-type"] == "application/json"
+    assert rejected.headers["content-language"] == "en"
+    assert rejected.body == b'{"err":"invalid_key","description":"The signature of the SET is invalid"}'
+
+
+# -- the revocation dependency and middleware -----------------------------------------------------
+
+
+def guarded_app(store: object, extract: object = claims_of_request) -> FastAPI:
+    app = FastAPI()
+    reject_revoked = revocation_dependency(store, extract)  # type: ignore[arg-type]
+
+    @app.get("/api/me", dependencies=[Depends(reject_revoked)])
+    async def me() -> dict[str, str]:
+        return {"user": "alice"}
+
+    return app
+
+
+async def test_revocation_dependency_lets_a_request_without_or_with_a_valid_token_through():
+    store = InMemoryTokenRevocationStore()
+    app = guarded_app(store)
+    async with client_of(app) as client:
+        assert (await client.get("/api/me")).status_code == 200, "no token"
+        response = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s1"})
+    assert response.status_code == 200
+    assert response.json() == {"user": "alice"}
+
+
+async def test_revocation_dependency_rejects_a_revoked_token_with_401_and_the_challenge():
+    store = InMemoryTokenRevocationStore()
+    await store.revoke_session("https://idp.example", "s1")
+    app = guarded_app(store)
+    async with client_of(app) as client:
+        response = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s1"})
+        other = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s2"})
+    assert response.status_code == 401
+    assert response.headers["www-authenticate"] == REVOKED_WWW_AUTHENTICATE
+    assert other.status_code == 200, "another session of the same user"
+
+
+async def test_revocation_dependency_accepts_an_async_extractor():
+    store = InMemoryTokenRevocationStore()
+    await store.revoke_subject("https://idp.example", "alice", datetime.now(tz=UTC) + timedelta(minutes=1))
+
+    async def extract(request: Request) -> TokenClaims | None:
+        return claims_of_request(request)
+
+    app = guarded_app(store, extract)
+    async with client_of(app) as client:
+        response = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s1"})
+    assert response.status_code == 401
+
+
+async def test_revocation_dependency_answers_503_when_the_store_fails():
+    app = guarded_app(FailingStore())
+    async with client_of(app) as client:
+        response = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s1"})
+        anonymous = await client.get("/api/me")
+    assert response.status_code == 503
+    assert anonymous.status_code == 200, "no token, no lookup"
+
+
+async def test_revocation_middleware_guards_the_application():
+    store = InMemoryTokenRevocationStore()
+    await store.revoke_session("https://idp.example", "s1")
+    app = FastAPI()
+    app.add_middleware(RevocationMiddleware, store=store, extract=claims_of_scope)
+
+    @app.get("/api/me")
+    async def me() -> dict[str, str]:
+        return {"user": "alice"}
+
+    async with client_of(app) as client:
+        allowed = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s2"})
+        revoked = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s1"})
+    assert allowed.status_code == 200
+    assert revoked.status_code == 401
+    assert revoked.headers["www-authenticate"] == REVOKED_WWW_AUTHENTICATE
+
+
+async def test_revocation_middleware_answers_503_when_the_store_fails():
+    app = FastAPI()
+    app.add_middleware(RevocationMiddleware, store=FailingStore(), extract=claims_of_scope)
+
+    @app.get("/api/me")
+    async def me() -> dict[str, str]:
+        return {"user": "alice"}
+
+    async with client_of(app) as client:
+        response = await client.get("/api/me", headers={"X-Token": "https://idp.example|alice|s1"})
+    assert response.status_code == 503
+
+
+# -- the lifespan -------------------------------------------------------------------------------------
+
+
+async def test_lifespan_starts_and_stops_the_receiver():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI(lifespan=receiver_lifespan(receiver))
+    assert not receiver.started
+    async with app.router.lifespan_context(app):
+        assert receiver.started
+    assert not receiver.started
+
+
+async def test_lifespan_wraps_the_lifespan_of_the_application():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    events: list[str] = []
+
+    @asynccontextmanager
+    async def inner(app: FastAPI) -> AsyncIterator[dict[str, str]]:
+        events.append(f"inner enter, receiver started: {receiver.started}")
+        yield {"database": "ready"}
+        events.append(f"inner exit, receiver started: {receiver.started}")
+
+    app = FastAPI(lifespan=receiver_lifespan(receiver, inner))
+    async with app.router.lifespan_context(app) as state:
+        assert receiver.started
+        assert state == {"database": "ready"}
+    assert events == ["inner enter, receiver started: False", "inner exit, receiver started: False"]
+    assert not receiver.started
+
+
+# -- the health route -----------------------------------------------------------------------------
+
+
+async def test_health_route_answers_200_while_healthy_or_degraded():
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(health_router(receiver))
+    async with client_of(app) as client:
+        degraded = await client.get("/health")
+        assert degraded.status_code == 200
+        assert degraded.json()["status"] == "degraded"
+        assert degraded.json()["transmitters"][0]["name"] == "default"
+        # a verified SET means the metadata and the keys were fetched: healthy
+        encoded_set = transmitter.set("CaepSessionRevoked", iss_sub(transmitter.issuer, "alice"))
+        assert (await receiver.push_handler.handle(SECRET, encoded_set)).status == 202
+        healthy = await client.get("/health")
+    assert healthy.status_code == 200
+    assert healthy.json()["status"] == "healthy"
+    assert healthy.json()["description"] == "In contact with the SSF transmitter(s)"
+
+
+async def test_health_route_answers_503_when_unhealthy():
+    transmitter = TestTransmitter()
+    config = default_receiver_config()
+    config.transmitter_issuer = transmitter.issuer
+    config.expected_audience = AUDIENCE
+    config.delivery_method = "poll"
+    config.poll.endpoint_url = transmitter.poll_url
+    config.poll.interval = timedelta(milliseconds=50)
+    config.transmitter_access_token = "token"
+    receiver = Receiver(config, http_client=transmitter.client)
+    transmitter.set_available(False)
+    app = FastAPI(lifespan=receiver_lifespan(receiver))
+    app.include_router(health_router(receiver, path="/ready"))
+    async with app.router.lifespan_context(app), client_of(app) as client:
+        poller = receiver.transmitters[0].poller
+        await eventually(lambda: bool(poller.last_poll_error), what="a failed poll")
+        response = await client.get("/ready")
+    assert response.status_code == 503
+    assert response.json()["status"] == "unhealthy"
+    assert response.json()["transmitters"][0]["pollError"]
+
+
+@pytest.mark.parametrize("path", ["/health", "/ready"])
+async def test_health_route_is_mounted_at_the_given_path(path: str):
+    transmitter = TestTransmitter()
+    receiver = Receiver(push_config(transmitter), http_client=transmitter.client)
+    app = FastAPI()
+    app.include_router(health_router(receiver, path=path))
+    async with client_of(app) as client:
+        assert (await client.get(path)).status_code == 200