easyssf-receiver-fastapi 0.7.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+easyssf/fastapi/__init__.py,sha256=2r3WQ04bbX7YHOrW6JBaxVIR1OUJGBMxw-oAeKJbC9U,1606
+easyssf/fastapi/lifecycle.py,sha256=L2K-uJfJdB_PI96ABep22V_W7JF5wvt5agUiD0pRJhY,2706
+easyssf/fastapi/push.py,sha256=tqF2YxHvk7GJCbcpwEUD_lutG0mKAlU8uVPFvkYI0o8,4291
+easyssf/fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+easyssf/fastapi/revocation.py,sha256=8UJ9cmx-sSFScHAZmaAt_AJm9clUgdSqABPHHliu_3s,4465
+easyssf_receiver_fastapi-0.7.0.dist-info/METADATA,sha256=4ahytsFWSWJKiL_l6aBQDUUbOb-ig9zRIvqbX1gHPss,5644
+easyssf_receiver_fastapi-0.7.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+easyssf_receiver_fastapi-0.7.0.dist-info/RECORD,,

easyssf_receiver_fastapi-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any