masks-client 0.2.0__py3-none-any.whl

masks/__init__.py

@@ -0,0 +1,116 @@
+from .auth import Auth
+from .client import AsyncClient, Client
+from .dpop import DPOP, proof
+from .errors import (
+    DelegationRefused,
+    DelegationUnavailable,
+    Error,
+    ForeignOrigin,
+    InsecureURL,
+    InvalidToken,
+    MasksError,
+    Unavailable,
+    has_code,
+)
+from .flows import adiscover, adiscover_resource, discover, discover_resource
+from .handshake import Handshake, HandshakeRequest
+from .keys import Key
+from .models import (
+    ACCESS_TOKEN_TYPE,
+    CLIENT_SECRET_BASIC,
+    CLIENT_SECRET_POST,
+    GRANT_CLIENT_CREDENTIALS,
+    GRANT_DEVICE_CODE,
+    GRANT_REFRESH_TOKEN,
+    GRANT_TOKEN_EXCHANGE,
+    ID_TOKEN_TYPE,
+    NO_AUTH,
+    PRIVATE_KEY_JWT,
+    UPSTREAM_ACCESS_TOKEN_TYPE,
+    AuthMethod,
+    ClientMetadata,
+    DeviceAuthorization,
+    Enrollment,
+    Introspection,
+    Issuer,
+    Metadata,
+    Registration,
+    ResourceMetadata,
+    Tenant,
+    Token,
+)
+from .oidc import (
+    DEFAULT_SCOPE,
+    AuthorizationRequest,
+    HeldConnection,
+    Logout,
+    SignIn,
+    Upstream,
+    organization_key,
+)
+from .replay import AsyncReplayStore, MemoryReplayStore, ReplayStore
+from .sources import AsyncCachedTokenSource, AsyncTokenSource, CachedTokenSource, TokenSource
+from .verifier import AsyncVerifier, Claims, Verifier
+
+__all__ = [
+    "ACCESS_TOKEN_TYPE",
+    "CLIENT_SECRET_BASIC",
+    "CLIENT_SECRET_POST",
+    "DEFAULT_SCOPE",
+    "DPOP",
+    "GRANT_CLIENT_CREDENTIALS",
+    "GRANT_DEVICE_CODE",
+    "GRANT_REFRESH_TOKEN",
+    "GRANT_TOKEN_EXCHANGE",
+    "ID_TOKEN_TYPE",
+    "NO_AUTH",
+    "PRIVATE_KEY_JWT",
+    "UPSTREAM_ACCESS_TOKEN_TYPE",
+    "AsyncCachedTokenSource",
+    "AsyncClient",
+    "AsyncReplayStore",
+    "AsyncTokenSource",
+    "AsyncVerifier",
+    "Auth",
+    "AuthMethod",
+    "AuthorizationRequest",
+    "CachedTokenSource",
+    "Claims",
+    "Client",
+    "ClientMetadata",
+    "DelegationRefused",
+    "DelegationUnavailable",
+    "DeviceAuthorization",
+    "Enrollment",
+    "Error",
+    "ForeignOrigin",
+    "Handshake",
+    "HandshakeRequest",
+    "HeldConnection",
+    "InsecureURL",
+    "Introspection",
+    "InvalidToken",
+    "Issuer",
+    "Key",
+    "Logout",
+    "MasksError",
+    "MemoryReplayStore",
+    "Metadata",
+    "Registration",
+    "ReplayStore",
+    "ResourceMetadata",
+    "SignIn",
+    "Tenant",
+    "Token",
+    "TokenSource",
+    "Unavailable",
+    "Upstream",
+    "Verifier",
+    "adiscover",
+    "adiscover_resource",
+    "discover",
+    "discover_resource",
+    "has_code",
+    "organization_key",
+    "proof",
+]

masks/asgi.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any
+
+from .dpop import DPOP
+from .errors import InvalidToken, Unavailable
+from .verifier import PROOF_ALGORITHMS, AsyncVerifier
+
+Scope = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
+Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
+App = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+CLAIMS = "masks.claims"
+
+
+def challenges(description: str) -> list[tuple[bytes, bytes]]:
+    quoted = description.replace("\\", "\\\\").replace('"', '\\"')
+    challenge = f'error="invalid_token", error_description="{quoted}"'
+
+    return [
+        (b"www-authenticate", f"Bearer {challenge}".encode()),
+        (b"www-authenticate", f'{DPOP} {challenge}, algs="{" ".join(PROOF_ALGORITHMS)}"'.encode()),
+    ]
+
+
+def requested_url(scope: Scope) -> str:
+    headers = dict(scope.get("headers") or [])
+    host = headers.get(b"host", b"").decode("latin-1")
+
+    if not host and scope.get("server"):
+        server_host, server_port = scope["server"]
+        host = f"{server_host}:{server_port}"
+
+    scheme = {"ws": "http", "wss": "https"}.get(scope.get("scheme", "http"), scope.get("scheme", "http"))
+    path = scope.get("raw_path") or scope.get("path", "/").encode()
+    query = scope.get("query_string") or b""
+    target = f"{scheme}://{host}{path.decode('latin-1')}"
+
+    return f"{target}?{query.decode('latin-1')}" if query else target
+
+
+class Middleware:
+    def __init__(self, app: App, verifier: AsyncVerifier) -> None:
+        self.app = app
+        self.verifier = verifier
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        headers = [(name.decode("latin-1"), value.decode("latin-1")) for name, value in scope.get("headers") or []]
+        method = scope.get("method", "GET")
+
+        try:
+            claims = await self.verifier.authenticate(method, requested_url(scope), headers)
+        except InvalidToken as error:
+            await self._refuse(scope, send, str(error).removeprefix("masks: "))
+            return
+        except Unavailable:
+            await self._unavailable(scope, send)
+            return
+
+        scope[CLAIMS] = claims
+        scope.setdefault("state", {})["masks_claims"] = claims
+
+        await self.app(scope, receive, send)
+
+    async def _unavailable(self, scope: Scope, send: Send) -> None:
+        if scope["type"] == "websocket":
+            await send({"type": "websocket.close", "code": 1013})
+            return
+
+        body = json.dumps(
+            {"error": "temporarily_unavailable", "error_description": "the token could not be checked just now"}
+        ).encode()
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 503,
+                "headers": [(b"content-type", b"application/json"), (b"retry-after", b"5")],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    async def _refuse(self, scope: Scope, send: Send, description: str) -> None:
+        if scope["type"] == "websocket":
+            await send({"type": "websocket.close", "code": 1008})
+            return
+
+        body = json.dumps({"error": "invalid_token", "error_description": description}).encode()
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 401,
+                "headers": [(b"content-type", b"application/json"), *challenges(description)],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})

masks/auth.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncGenerator, Generator
+from typing import Any
+
+import httpx
+
+from .dpop import DPOP, proof
+from .errors import ForeignOrigin
+from .flows import origin
+from .keys import Key
+from .models import Token
+
+
+class Auth(httpx.Auth):
+    requires_request_body = True
+
+    def __init__(self, source: Any, *origins: str, key: Key | None = None) -> None:
+        self.source = source
+        self.key = key
+        self.origins = frozenset(origin(held) for held in origins)
+        self._nonces: dict[str, str] = {}
+
+    def sync_auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        self._allowed(request)
+
+        if inspect.iscoroutinefunction(self.source.token):
+            raise TypeError("masks: an httpx.Client needs a token source that is not async")
+
+        yield from self._signed(request, self.source.token())
+
+    async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        self._allowed(request)
+
+        token = self.source.token()
+
+        if inspect.isawaitable(token):
+            token = await token
+
+        flow = self._signed(request, token)
+        outgoing = next(flow)
+
+        while True:
+            response = yield outgoing
+
+            try:
+                outgoing = flow.send(response)
+            except StopIteration:
+                return
+
+    def _allowed(self, request: httpx.Request) -> None:
+        if origin(request.url) not in self.origins:
+            named = ", ".join(sorted(self.origins)) or "no origin"
+            raise ForeignOrigin(f"masks: this auth holds tokens only for {named}, not {origin(request.url)}")
+
+    def _signed(self, request: httpx.Request, token: Token) -> Generator[httpx.Request, httpx.Response, None]:
+        held = origin(request.url)
+        self._sign(request, token, self._nonces.get(held, ""))
+
+        response = yield request
+
+        if not token.bound:
+            return
+
+        wanted = response.headers.get("DPoP-Nonce", "")
+
+        if not wanted:
+            return
+
+        self._nonces[held] = wanted
+
+        if response.status_code != 401 or "use_dpop_nonce" not in response.headers.get("WWW-Authenticate", ""):
+            return
+
+        self._sign(request, token, wanted)
+
+        yield request
+
+    def _sign(self, request: httpx.Request, token: Token, nonce: str) -> None:
+        if not token.bound:
+            request.headers["Authorization"] = f"Bearer {token.access_token}"
+            return
+
+        if self.key is None:
+            raise ValueError("masks: a DPoP token needs the key it is held to")
+
+        request.headers["Authorization"] = f"{DPOP} {token.access_token}"
+        request.headers["DPoP"] = proof(self.key, request.method, str(request.url), token.access_token, nonce)