easyssf-receiver 0.7.0__py3-none-any.whl

easyssf/receiver/__init__.py

@@ -0,0 +1,437 @@
+"""An SSF receiver, framework independent and asyncio based: SET verification, de-duplication,
+push and poll delivery, stream management, typed CAEP, RISC and SCIM handlers, token revocation,
+session termination and metrics. The port of ``easyssf-receiver`` of the Java library.
+
+The modules follow the Go package: ``errors`` (the exception classes and the ``Clock``), ``event``
+(``EventContext`` and the handlers), ``dedup``, ``metrics``, ``config`` (``ReceiverConfig``),
+``jwks``, ``verifier``, ``processor``, ``push``, ``authorizer``, ``transmitter``, ``stream``,
+``poll``, ``receiver`` (``Receiver``, which assembles everything from a ``ReceiverConfig``), the
+typed handlers ``caep``, ``risc`` and ``scim``, ``revocation`` and ``session``; ``asgi`` and
+``wsgi`` mount the push endpoint on any web framework.
+"""
+
+from .authorizer import (
+    DEFAULT_RETRYABLE_STATUSES,
+    ENDPOINT_EXTENSION,
+    Authorizer,
+    AuthorizerCallable,
+    AuthorizerFunc,
+    Authorizers,
+    BearerToken,
+    Endpoint,
+    EndpointHeaders,
+    NoAuthorization,
+    RetryOptions,
+    StaticHeaders,
+    TokenInvalidator,
+    default_retry_options,
+    endpoint_of,
+    invalidate_token,
+    retry_after,
+    retrying,
+    with_endpoint,
+)
+from .caep import (
+    CaepEventHandler,
+    CaepHandler,
+    caep_handler,
+    dispatch_caep_event,
+)
+from .config import (
+    CONFIGURATION_SECTION,
+    DEFAULT_SCIM_ATTRIBUTE_CLAIMS,
+    DEFAULT_TRANSMITTER_NAME,
+    SCHEMA_ALWAYS,
+    SCHEMA_EMBEDDED,
+    SCHEMA_NEVER,
+    STREAM_MANAGEMENT_NONE,
+    STREAM_MANAGEMENT_RECEIVER,
+    DataConfig,
+    DataSize,
+    DedupConfig,
+    HttpConfig,
+    OAuth2Config,
+    PollConfig,
+    PushConfig,
+    RateLimitConfig,
+    ReceiverConfig,
+    RetryConfig,
+    RevocationConfig,
+    SessionTerminationConfig,
+    SetValidationConfig,
+    StreamConfig,
+    TransmitterConfig,
+    default_receiver_config,
+    default_transmitter_config,
+    format_data_size,
+    format_duration,
+    parse_data_size,
+    parse_duration,
+    valid_table_prefix,
+)
+from .dedup import (
+    DEFAULT_DEDUP_LEASE,
+    InMemoryJtiDedupStore,
+    JtiClaim,
+    JtiClaimState,
+    JtiDedupStore,
+)
+from .errors import (
+    Clock,
+    ConfigurationError,
+    EasyssfError,
+    ErrorCode,
+    HandlingError,
+    InProgressError,
+    RejectedError,
+    StoreError,
+    TransmitterUnavailableError,
+    system_clock,
+)
+from .event import (
+    EventContext,
+    Handler,
+    HandlerCallable,
+    HandlerFunc,
+    as_handler,
+    for_event,
+    handler_name,
+)
+from .jwks import (
+    DEFAULT_CACHE_LIFETIME,
+    DEFAULT_FETCH_TIMEOUT,
+    DEFAULT_REFRESH_RATE_LIMIT,
+    JWK_SET_ACCEPT,
+    HttpJwkSetSource,
+    JwkSetFetch,
+    JwkSetSource,
+    JwkSetUrlResolver,
+    StaticJwkSet,
+    parse_jwk_set,
+)
+from .metrics import (
+    Metrics,
+    NoopMetrics,
+    SetOutcome,
+)
+from .poll import (
+    InMemoryPollAckStore,
+    PendingAck,
+    PollAckStore,
+    PollEndpoint,
+    Poller,
+    PollerOptions,
+    PollError,
+    default_poller_options,
+    fixed_poll_endpoint,
+)
+from .processor import (
+    CriticalSubjectMembers,
+    ProcessingOutcome,
+    ProcessingResult,
+    Processor,
+    ProcessorOptions,
+    StreamVerificationCheck,
+)
+from .push import (
+    AUTHENTICATION_FAILED,
+    PUSH_CONTENT_LANGUAGE,
+    PUSH_CONTENT_TYPE,
+    ExpectedAuthorizationHeaders,
+    PushHandler,
+    PushResponse,
+)
+from .receiver import (
+    Receiver,
+    ReceiverDisabledError,
+    ReceiverHealth,
+    TransmitterCustomizer,
+)
+from .revocation import (
+    DEFAULT_REVOCATION_TTL,
+    DEFAULT_SESSION_EVENT_TYPES,
+    REVOKED_WWW_AUTHENTICATE,
+    InMemoryTokenRevocationStore,
+    RevocationMiddleware,
+    TokenClaims,
+    TokenClaimsExtractor,
+    TokenRevocationHandler,
+    TokenRevocationStore,
+    is_revoked,
+    reject_if_revoked,
+    resolve_event_types,
+)
+from .risc import (
+    RiscEventHandler,
+    RiscHandler,
+    dispatch_risc_event,
+    risc_handler,
+)
+from .scim import (
+    ScimEventHandler,
+    ScimHandler,
+    dispatch_scim_event,
+    scim_handler,
+)
+from .session import (
+    DEFAULT_SESSION_TERMINATION_USER_EVENT_TYPES,
+    SessionTerminationHandler,
+    SessionTerminator,
+    SessionTerminatorCallable,
+    SessionTerminatorFunc,
+    as_session_terminator,
+    describe_subject,
+    subject_matches,
+    subject_matches_with,
+)
+from .stream import (
+    MAX_STREAM_RETRY_DELAY,
+    IssuerMismatchError,
+    ReceiverStream,
+    StreamClient,
+    StreamError,
+    StreamListener,
+    StreamRegistrar,
+    StreamRegistrarState,
+    StreamVerification,
+    changes_for,
+    has_desired_delivery,
+    has_desired_events,
+    stream_status_of,
+)
+from .transmitter import (
+    DEFAULT_HTTP_TIMEOUT,
+    LONG_POLL_MARGIN,
+    MAX_REDIRECTS,
+    MAX_RESPONSE_SIZE,
+    WELL_KNOWN_PATH,
+    ClientCredentialsOptions,
+    ClientCredentialsTokenProvider,
+    FixedToken,
+    HealthStatus,
+    HttpResponse,
+    MetadataResolver,
+    NoToken,
+    ResponseTooLargeError,
+    TokenProvider,
+    Transmitter,
+    TransmitterHealth,
+    UriPolicy,
+    UriPolicyError,
+    default_client_credentials_options,
+    derive_metadata_urls,
+    exchange,
+    get_json,
+    parse_absolute,
+    send,
+)
+from .verifier import (
+    MAX_SET_SIZE,
+    SECEVENT_JWT_TYPE,
+    SUPPORTED_ALGORITHMS,
+    ExpectedAudiencesProvider,
+    IssuerRoutingVerifier,
+    JwtVerifier,
+    Verifier,
+    VerifierOptions,
+    default_verifier_options,
+    rsa_key_bits,
+    supported_algorithm,
+    unverified_issuer,
+    unverified_payload,
+)
+
+__all__ = [
+    "AUTHENTICATION_FAILED",
+    "CONFIGURATION_SECTION",
+    "DEFAULT_CACHE_LIFETIME",
+    "DEFAULT_DEDUP_LEASE",
+    "DEFAULT_FETCH_TIMEOUT",
+    "DEFAULT_HTTP_TIMEOUT",
+    "DEFAULT_REFRESH_RATE_LIMIT",
+    "DEFAULT_RETRYABLE_STATUSES",
+    "DEFAULT_REVOCATION_TTL",
+    "DEFAULT_SCIM_ATTRIBUTE_CLAIMS",
+    "DEFAULT_SESSION_EVENT_TYPES",
+    "DEFAULT_SESSION_TERMINATION_USER_EVENT_TYPES",
+    "DEFAULT_TRANSMITTER_NAME",
+    "ENDPOINT_EXTENSION",
+    "JWK_SET_ACCEPT",
+    "LONG_POLL_MARGIN",
+    "MAX_REDIRECTS",
+    "MAX_RESPONSE_SIZE",
+    "MAX_SET_SIZE",
+    "MAX_STREAM_RETRY_DELAY",
+    "PUSH_CONTENT_LANGUAGE",
+    "PUSH_CONTENT_TYPE",
+    "REVOKED_WWW_AUTHENTICATE",
+    "SCHEMA_ALWAYS",
+    "SCHEMA_EMBEDDED",
+    "SCHEMA_NEVER",
+    "SECEVENT_JWT_TYPE",
+    "STREAM_MANAGEMENT_NONE",
+    "STREAM_MANAGEMENT_RECEIVER",
+    "SUPPORTED_ALGORITHMS",
+    "WELL_KNOWN_PATH",
+    "Authorizer",
+    "AuthorizerCallable",
+    "AuthorizerFunc",
+    "Authorizers",
+    "BearerToken",
+    "CaepEventHandler",
+    "CaepHandler",
+    "ClientCredentialsOptions",
+    "ClientCredentialsTokenProvider",
+    "Clock",
+    "ConfigurationError",
+    "CriticalSubjectMembers",
+    "DataConfig",
+    "DataSize",
+    "DedupConfig",
+    "EasyssfError",
+    "Endpoint",
+    "EndpointHeaders",
+    "ErrorCode",
+    "EventContext",
+    "ExpectedAudiencesProvider",
+    "ExpectedAuthorizationHeaders",
+    "FixedToken",
+    "Handler",
+    "HandlerCallable",
+    "HandlerFunc",
+    "HandlingError",
+    "HealthStatus",
+    "HttpConfig",
+    "HttpJwkSetSource",
+    "HttpResponse",
+    "InMemoryJtiDedupStore",
+    "InMemoryPollAckStore",
+    "InMemoryTokenRevocationStore",
+    "InProgressError",
+    "IssuerMismatchError",
+    "IssuerRoutingVerifier",
+    "JtiClaim",
+    "JtiClaimState",
+    "JtiDedupStore",
+    "JwkSetFetch",
+    "JwkSetSource",
+    "JwkSetUrlResolver",
+    "JwtVerifier",
+    "MetadataResolver",
+    "Metrics",
+    "NoAuthorization",
+    "NoToken",
+    "NoopMetrics",
+    "OAuth2Config",
+    "PendingAck",
+    "PollAckStore",
+    "PollConfig",
+    "PollEndpoint",
+    "PollError",
+    "Poller",
+    "PollerOptions",
+    "ProcessingOutcome",
+    "ProcessingResult",
+    "Processor",
+    "ProcessorOptions",
+    "PushConfig",
+    "PushHandler",
+    "PushResponse",
+    "RateLimitConfig",
+    "Receiver",
+    "ReceiverConfig",
+    "ReceiverDisabledError",
+    "ReceiverHealth",
+    "ReceiverStream",
+    "RejectedError",
+    "ResponseTooLargeError",
+    "RetryConfig",
+    "RetryOptions",
+    "RevocationConfig",
+    "RevocationMiddleware",
+    "RiscEventHandler",
+    "RiscHandler",
+    "ScimEventHandler",
+    "ScimHandler",
+    "SessionTerminationConfig",
+    "SessionTerminationHandler",
+    "SessionTerminator",
+    "SessionTerminatorCallable",
+    "SessionTerminatorFunc",
+    "SetOutcome",
+    "SetValidationConfig",
+    "StaticHeaders",
+    "StaticJwkSet",
+    "StoreError",
+    "StreamClient",
+    "StreamConfig",
+    "StreamError",
+    "StreamListener",
+    "StreamRegistrar",
+    "StreamRegistrarState",
+    "StreamVerification",
+    "StreamVerificationCheck",
+    "TokenClaims",
+    "TokenClaimsExtractor",
+    "TokenInvalidator",
+    "TokenProvider",
+    "TokenRevocationHandler",
+    "TokenRevocationStore",
+    "Transmitter",
+    "TransmitterConfig",
+    "TransmitterCustomizer",
+    "TransmitterHealth",
+    "TransmitterUnavailableError",
+    "UriPolicy",
+    "UriPolicyError",
+    "Verifier",
+    "VerifierOptions",
+    "as_handler",
+    "as_session_terminator",
+    "caep_handler",
+    "changes_for",
+    "default_client_credentials_options",
+    "default_poller_options",
+    "default_receiver_config",
+    "default_retry_options",
+    "default_transmitter_config",
+    "default_verifier_options",
+    "derive_metadata_urls",
+    "describe_subject",
+    "dispatch_caep_event",
+    "dispatch_risc_event",
+    "dispatch_scim_event",
+    "endpoint_of",
+    "exchange",
+    "fixed_poll_endpoint",
+    "for_event",
+    "format_data_size",
+    "format_duration",
+    "get_json",
+    "handler_name",
+    "has_desired_delivery",
+    "has_desired_events",
+    "invalidate_token",
+    "is_revoked",
+    "parse_absolute",
+    "parse_data_size",
+    "parse_duration",
+    "parse_jwk_set",
+    "reject_if_revoked",
+    "resolve_event_types",
+    "retry_after",
+    "retrying",
+    "risc_handler",
+    "rsa_key_bits",
+    "scim_handler",
+    "send",
+    "stream_status_of",
+    "subject_matches",
+    "subject_matches_with",
+    "supported_algorithm",
+    "system_clock",
+    "unverified_issuer",
+    "unverified_payload",
+    "valid_table_prefix",
+    "with_endpoint",
+]

easyssf/receiver/asgi.py

@@ -0,0 +1,84 @@
+"""The push endpoint as an ASGI 3 application, for any ASGI server or framework: mount
+:func:`push_app` at the push endpoint path (``/ssf/push`` by default). No framework is needed;
+the FastAPI and Litestar distributions add the idiomatic pieces."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any, TypeAlias
+
+from .push import MAX_SET_SIZE, PUSH_CONTENT_LANGUAGE, PUSH_CONTENT_TYPE, PushHandler
+
+__all__ = ["AsgiApp", "push_app"]
+
+Scope: TypeAlias = MutableMapping[str, Any]
+Receive: TypeAlias = Callable[[], Awaitable[MutableMapping[str, Any]]]
+Send: TypeAlias = Callable[[MutableMapping[str, Any]], Awaitable[None]]
+AsgiApp: TypeAlias = Callable[[Scope, Receive, Send], Awaitable[None]]
+"""An ASGI 3 application."""
+
+_METHOD_NOT_ALLOWED = 405
+
+
+def push_app(push_handler: PushHandler) -> AsgiApp:
+    """An ASGI 3 application serving the push endpoint: ``POST`` with the SET as body
+    (``application/secevent+jwt``), any other method is answered with 405. The body is read up to
+    one byte beyond :data:`~easyssf.receiver.push.MAX_SET_SIZE`; 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. Lifespan events are
+    acknowledged, so the app can be served on its own.
+
+    Example:
+        >>> app = push_app(receiver.push_handler)   # uvicorn.run(app, port=8080)
+        >>> fastapi_app.mount("/ssf/push", app)     # or under a framework
+    """
+
+    async def app(scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            while True:
+                message = await receive()
+                await send({"type": message["type"] + ".complete"})
+                if message["type"] == "lifespan.shutdown":
+                    return
+        if scope["type"] != "http":
+            raise RuntimeError(f"the push endpoint serves HTTP, not {scope['type']}")
+        if scope["method"] != "POST":
+            await _respond(send, _METHOD_NOT_ALLOWED, [(b"allow", b"POST")], b"")
+            return
+        # read up to one byte beyond the limit, 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""
+        while len(body) <= MAX_SET_SIZE:
+            message = await receive()
+            if message["type"] == "http.disconnect":
+                return
+            body += message.get("body", b"")[: MAX_SET_SIZE + 1 - len(body)]
+            if not message.get("more_body", False):
+                break
+        authorization = next(
+            (value.decode("latin-1") for name, value in scope.get("headers", []) if name.lower() == b"authorization"),
+            None,
+        )
+        response = await push_handler.handle(authorization, body)
+        content = response.body_bytes
+        headers: list[tuple[bytes, bytes]] = []
+        if content is not None:
+            headers = [
+                (b"content-type", PUSH_CONTENT_TYPE.encode()),
+                (b"content-language", PUSH_CONTENT_LANGUAGE.encode()),
+            ]
+        await _respond(send, response.status, headers, content or b"")
+
+    return app
+
+
+async def _respond(send: Send, status: int, headers: list[tuple[bytes, bytes]], body: bytes) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [*headers, (b"content-length", str(len(body)).encode())],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})