cliV1 0.1.1__py3-none-any.whl

swagger_petstore_open_api_3_0/core/auth/protocols.py

@@ -0,0 +1,103 @@
+"""Every protocol the authentication layer defines: what a scheme is, and where a token comes from.
+
+Two families, one file. :class:`AuthScheme` and its async twin are the whole contract for applying a
+credential to a request, so a scheme this runtime does not ship is a class a *caller* writes; ``apply``
+runs once per request, which is what makes rotation and just-in-time signing work.
+:class:`TokenSource` and its three relatives are the seam managed OAuth 2.0 fetches through, so a
+consumer replaces the built-in source without touching the caching scheme that calls it.
+
+Nothing here has a body, so nothing here reaches a scheme, a composite or a transport -- only the
+models its members name."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Protocol, TypeVar, runtime_checkable
+
+from .models import AuthParams, OAuthToken, OAuthTokenRefreshable
+
+CredentialsT_contra = TypeVar("CredentialsT_contra", contravariant=True)
+"""A grant's credentials, as a source accepts them.
+
+Contravariant because the protocols below take it in an *argument* position and nowhere else."""
+
+
+class AuthScheme(Protocol):
+    """A security scheme, as the synchronous client sees it.
+
+    Implementations:
+
+    - MUST be safe to call repeatedly -- ``apply`` runs once per request.
+    - SHOULD be frozen: one scheme instance serves every request a client makes.
+    - MAY block, but only if the synchronous client is the only one that will hold it."""
+
+    def apply(self) -> AuthParams: ...
+
+
+class AsyncAuthScheme(Protocol):
+    """A security scheme, as the asynchronous client sees it.
+
+    ``apply`` may return the parameters directly *or* an awaitable of them, so one synchronous method
+    satisfies this protocol **and** :class:`AuthScheme` and no async twin of a static scheme is
+    needed. A scheme that must reach the network declares ``async def apply`` and satisfies only this
+    one, which is what keeps it off the synchronous transport it could not use."""
+
+    def apply(self) -> AuthParams | Awaitable[AuthParams]: ...
+
+
+@runtime_checkable
+class RevocableAuthScheme(Protocol):
+    """A scheme whose credential can go stale before it expires.
+
+    ``invalidate`` is a **hint, not a barrier**: it runs after a 401 and must not block, so a fetch
+    already in flight may repopulate the cache immediately afterwards. ``runtime_checkable`` because
+    ``composition.invalidate`` has to ask a scheme whose type it does not know."""
+
+    def invalidate(self) -> None: ...
+
+
+class TokenSource(Protocol[CredentialsT_contra]):
+    """Where an OAuth 2.0 scheme gets its token, given that grant's credentials.
+
+    Generic because the credentials differ between grants, so a mismatch is reported at the client
+    constructor rather than at the first request. ``fetch`` always receives the validated credentials
+    model, never the mapping form.
+
+    Implementations:
+
+    - MUST be safe to call repeatedly, and MAY be called concurrently.
+    - MUST NOT issue a request that itself uses the scheme holding them -- ``fetch`` runs inside that
+      scheme's lock, so doing so deadlocks.
+    - SHOULD bound their own I/O. The built-in source inherits the client's timeout."""
+
+    def fetch(self, credentials: CredentialsT_contra) -> OAuthToken: ...
+
+
+class AsyncTokenSource(Protocol[CredentialsT_contra]):
+    """:class:`TokenSource` as the asynchronous client sees it.
+
+    ``fetch`` is a coroutine, deliberately unlike :meth:`AsyncAuthScheme.apply`'s union: nothing about
+    obtaining a token is static, so declaring it makes a synchronous source a **type** error rather
+    than a ``TypeError`` at the first request."""
+
+    async def fetch(self, credentials: CredentialsT_contra) -> OAuthToken: ...
+
+
+class RefreshableTokenSource(TokenSource[CredentialsT_contra], Protocol[CredentialsT_contra]):
+    """A :class:`TokenSource` that can also exchange a refresh token for a new access token.
+
+    Extends rather than replaces: ``fetch`` still runs when there is nothing to refresh, and again
+    when a refresh is refused. ``refresh`` returns ``None`` for a *provider* refusal rather than
+    raising; a transport failure still propagates, as does a success whose body will not decode."""
+
+    def fetch(self, credentials: CredentialsT_contra) -> OAuthTokenRefreshable: ...
+
+    def refresh(self, credentials: CredentialsT_contra, refresh_token: str) -> OAuthTokenRefreshable | None: ...
+
+
+class AsyncRefreshableTokenSource(AsyncTokenSource[CredentialsT_contra], Protocol[CredentialsT_contra]):
+    """:class:`RefreshableTokenSource` as the asynchronous client sees it: both members are awaited."""
+
+    async def fetch(self, credentials: CredentialsT_contra) -> OAuthTokenRefreshable: ...
+
+    async def refresh(self, credentials: CredentialsT_contra, refresh_token: str) -> OAuthTokenRefreshable | None: ...

swagger_petstore_open_api_3_0/core/auth/schemes/__init__.py

@@ -0,0 +1,94 @@
+"""Every scheme this runtime ships, plus the two caching tiers a managed OAuth 2.0 grant applies through.
+
+One module per scheme *type* -- together the whole of OpenAPI's ``securitySchemes`` surface:
+``http``/``basic`` and ``http``/``bearer``, ``apiKey`` in a header, a query parameter or a cookie, and
+three ``oauth2`` flows. ``openIdConnect`` and ``implicit`` need no module of their own -- both reach this
+runtime as a plain bearer token. Adding a fourth grant is one more module here and nothing anywhere else.
+
+``oauth2_schemes`` is the exception that earns its place: it names no grant, holding the two
+grant-agnostic tiers every flow's credentials and source are handed to."""
+
+from .api_key_auth import ApiKeyCookieScheme, ApiKeyHeaderScheme, ApiKeyQueryScheme
+from .basic_auth import (
+    BasicAuthCredentials,
+    BasicAuthCredentialsDict,
+    BasicAuthCredentialsOrDict,
+    BasicAuthScheme,
+)
+from .bearer_auth import BearerAuthScheme
+from .oauth2_authorization_code import (
+    AsyncAuthorizationCodeCredentials,
+    AsyncAuthorizationCodeCredentialsDict,
+    AsyncAuthorizationCodeCredentialsOrDict,
+    AsyncAuthorizationCodePrompt,
+    AsyncAuthorizationCodeTokenSource,
+    AuthorizationCodeCredentials,
+    AuthorizationCodeCredentialsDict,
+    AuthorizationCodeCredentialsOrDict,
+    AuthorizationCodePrompt,
+    AuthorizationCodeTokenSource,
+    PkceMethod,
+)
+from .oauth2_client_credentials import (
+    AsyncClientCredentialsTokenSource,
+    ClientCredentials,
+    ClientCredentialsDict,
+    ClientCredentialsOrDict,
+    ClientCredentialsTokenSource,
+)
+from .oauth2_password import (
+    AsyncPasswordTokenSource,
+    PasswordCredentials,
+    PasswordCredentialsDict,
+    PasswordCredentialsOrDict,
+    PasswordTokenSource,
+)
+from .oauth2_schemes import (
+    AsyncOAuth2RefreshableScheme,
+    AsyncOAuth2Scheme,
+    OAuth2RefreshableScheme,
+    OAuth2Scheme,
+)
+
+__all__ = [
+    # http / basic
+    "BasicAuthCredentials",
+    "BasicAuthCredentialsDict",
+    "BasicAuthCredentialsOrDict",
+    "BasicAuthScheme",
+    # http / bearer
+    "BearerAuthScheme",
+    # apiKey
+    "ApiKeyHeaderScheme",
+    "ApiKeyQueryScheme",
+    "ApiKeyCookieScheme",
+    # oauth2 -- the two caching tiers, grant-agnostic
+    "OAuth2Scheme",
+    "AsyncOAuth2Scheme",
+    "OAuth2RefreshableScheme",
+    "AsyncOAuth2RefreshableScheme",
+    # oauth2 / clientCredentials
+    "ClientCredentials",
+    "ClientCredentialsDict",
+    "ClientCredentialsOrDict",
+    "ClientCredentialsTokenSource",
+    "AsyncClientCredentialsTokenSource",
+    # oauth2 / password
+    "PasswordCredentials",
+    "PasswordCredentialsDict",
+    "PasswordCredentialsOrDict",
+    "PasswordTokenSource",
+    "AsyncPasswordTokenSource",
+    # oauth2 / authorizationCode
+    "AuthorizationCodeCredentials",
+    "AuthorizationCodeCredentialsDict",
+    "AuthorizationCodeCredentialsOrDict",
+    "AsyncAuthorizationCodeCredentials",
+    "AsyncAuthorizationCodeCredentialsDict",
+    "AsyncAuthorizationCodeCredentialsOrDict",
+    "AuthorizationCodePrompt",
+    "AsyncAuthorizationCodePrompt",
+    "PkceMethod",
+    "AuthorizationCodeTokenSource",
+    "AsyncAuthorizationCodeTokenSource",
+]

swagger_petstore_open_api_3_0/core/auth/schemes/api_key_auth.py

@@ -0,0 +1,53 @@
+"""``apiKey`` -- one credential, three destinations.
+
+OpenAPI's ``apiKey`` is a single type parameterised by ``in:``, so the three classes below differ
+only in which bucket of :class:`AuthParams` they fill."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ...params import param
+from ..models import AuthParams
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyHeaderScheme:
+    """``apiKey`` with ``in: header``.
+
+    Also every custom ``Authorization`` keyword an API invents, which needs no scheme of its own:
+    pass ``name="Authorization"`` and a value that already carries the keyword."""
+
+    name: str
+    value: str = field(repr=False)
+
+    def apply(self) -> AuthParams:
+        return AuthParams(headers=(param[str](self.name, self.value),))
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyQueryScheme:
+    """``apiKey`` with ``in: query``.
+
+    The value is percent-encoded, because :class:`Param` renders it exactly as an endpoint's own
+    query parameter -- the opposite obligation from the cookie below."""
+
+    name: str
+    value: str = field(repr=False)
+
+    def apply(self) -> AuthParams:
+        return AuthParams(query_params=(param[str](self.name, self.value),))
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCookieScheme:
+    """``apiKey`` with ``in: cookie``.
+
+    The value is sent verbatim. RFC 6265's ``cookie-value`` alphabet already admits every character
+    a base64 key uses, so percent-encoding it would corrupt the credential rather than protect it."""
+
+    name: str
+    value: str = field(repr=False)
+
+    def apply(self) -> AuthParams:
+        return AuthParams(cookies=(param[str](self.name, self.value),))

swagger_petstore_open_api_3_0/core/auth/schemes/basic_auth.py

@@ -0,0 +1,73 @@
+"""``http`` / ``basic`` -- RFC 7617."""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from typing_extensions import TypedDict
+
+from ...params import param
+from ..models import AuthParams
+
+
+class BasicAuthCredentials(BaseModel):
+    """The user-id and password of an ``http``/``basic`` scheme (RFC 7617)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    username: str
+    password: str = Field(repr=False)
+
+    @field_validator("username")
+    @classmethod
+    def _reject_colon(cls, value: str) -> str:
+        if ":" in value:
+            raise ValueError(
+                "username must not contain ':' -- RFC 7617 encodes 'user-id:password', so a colon "
+                f"in the user-id cannot be decoded unambiguously; got {value!r}"
+            )
+        return value
+
+    @classmethod
+    def coerce(cls, value: BasicAuthCredentialsOrDict) -> BasicAuthCredentials:
+        """Accept either spelling, validating the mapping form.
+
+        Unlike the other coercion seams in this runtime, no credential model's ``coerce`` takes
+        ``None``: an absent credential means *no scheme*, which the client decides before this.
+
+        Args:
+            value: The credential, as the typed model or as a mapping.
+
+        Returns:
+            The validated model, passed straight through when it already is one.
+
+        Raises:
+            ValidationError: If the mapping is missing a key, carries an unknown one, or holds a
+                user-id with a colon. It subclasses ``ValueError``."""
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+class BasicAuthCredentialsDict(TypedDict):
+    username: str
+    password: str
+
+
+BasicAuthCredentialsOrDict: TypeAlias = BasicAuthCredentials | BasicAuthCredentialsDict
+"""What a Basic credential accepts: the typed model, or a mapping carrying the same two keys."""
+
+
+@dataclass(frozen=True, slots=True)
+class BasicAuthScheme:
+    """``http``/``basic``: ``Authorization: Basic base64(user-id:password)``."""
+
+    credentials: BasicAuthCredentials
+
+    def apply(self) -> AuthParams:
+        raw = f"{self.credentials.username}:{self.credentials.password}"
+        encoded = b64encode(raw.encode()).decode()
+        return AuthParams(headers=(param[str]("Authorization", f"Basic {encoded}"),))

swagger_petstore_open_api_3_0/core/auth/schemes/bearer_auth.py

@@ -0,0 +1,21 @@
+"""``http`` / ``bearer`` -- and, on the wire, ``openIdConnect`` too."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ...params import param
+from ..models import AuthParams
+
+
+@dataclass(frozen=True, slots=True)
+class BearerAuthScheme:
+    """``http``/``bearer``: ``Authorization: Bearer <token>``.
+
+    Also the wire form of an ``openIdConnect`` scheme, whose discovery document says how a token is
+    obtained but not how it is sent."""
+
+    token: str = field(repr=False)
+
+    def apply(self) -> AuthParams:
+        return AuthParams(headers=(param[str]("Authorization", f"Bearer {self.token}"),))