cliV1 0.0.6__py3-none-any.whl

swagger_petstore_open_api_3_1_0/core/auth/models.py

@@ -0,0 +1,216 @@
+"""What every security scheme trades in, and the OAuth 2.0 vocabulary its grants share.
+
+:class:`AuthParams` is what one scheme contributes to a request. The rest is managed OAuth 2.0's
+grant-agnostic half: the token endpoint's success and error bodies (RFC 6749 §5.1 and §5.2, fixed for
+every provider, which is why they are runtime types at all), §2.3.1's client-authentication placements,
+§3.3's scope delimiter, and the scope vocabulary parameter every grant's credentials carry.
+
+The bottom of the auth layer. It names no protocol and no scheme, so ``protocols``, ``composition`` and
+``schemes/`` all import from here and nothing imports back. It performs no token request either --
+which is why no ``RawClient``, ``form_body`` or ``UrlTemplate`` appears below."""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Final, TypeAlias
+from urllib.parse import quote
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ``TypeVar`` from here and not ``typing``: PEP 696 defaults reach ``typing`` at 3.13, and ``ScopeT``
+# below needs one at the 3.10 floor.
+from typing_extensions import TypeVar
+
+from .._internal.wire import parse_json, text_values
+from ..decoding import ErrorMapper
+from ..params import Param, param
+from ..results import RawError
+
+
+@dataclass(frozen=True, slots=True)
+class AuthParams:
+    """What one scheme contributes to a request.
+
+    Held as :class:`Param` rather than plain strings, so a credential is validated, dumped and
+    encoded by the same code as an endpoint's own parameters."""
+
+    headers: tuple[Param[Any], ...] = ()
+    query_params: tuple[Param[Any], ...] = ()
+    cookies: tuple[Param[Any], ...] = ()
+
+    def request_headers(self) -> tuple[Param[Any], ...]:
+        """Every header this contributes, cookie pairs folded into one ``Cookie`` (RFC 6265).
+
+        Folding here rather than at each scheme is what lets two cookie-bearing schemes compose;
+        two ``Cookie`` parameters would see the second overwrite the first. This covers only what
+        *this request's* schemes contributed -- folding the jar across the API's, the endpoint's and
+        the caller's layers is ``_internal/headers.py``'s.
+
+        The jar is tested rather than the tuple, so cookies that all render to nothing contribute no
+        header at all instead of an empty one that would clobber a lower layer.
+
+        Returns:
+            The headers, plus one folded ``Cookie`` when any cookie was contributed."""
+        jar = "; ".join(f"{cookie.key}={value}" for cookie in self.cookies for value in text_values(cookie))
+        if not jar:
+            return self.headers
+
+        return *self.headers, param[str]("Cookie", jar)
+
+
+ScopeT = TypeVar("ScopeT", bound=str, default=str)
+"""A grant's scope vocabulary, as its flow declares it.
+
+Bound to ``str`` because RFC 6749 §3.3 puts scopes on the wire as space-delimited strings, and
+defaulted to it so an unparametrized credential means what it always did: any scope the provider
+accepts, which is also what a flow declaring no scopes emits."""
+
+
+class OAuth2Credentials(BaseModel):
+    """The base every OAuth 2.0 grant's credentials share, carrying one thing: their repr.
+
+    Each grant's credentials are generic over :data:`ScopeT`, and pydantic names a parametrized model
+    after its parametrization -- so an unhelped repr prints the flow's whole scope vocabulary in place
+    of the class a caller wrote. This restores the latter.
+
+    ⚠️ **It declares no fields, and must not gain one.** Pydantic orders a base's fields ahead of a
+    subclass's, so a field here would move to the front of every credential's repr and ``model_dump``.
+    A grant's own fields stay in its own model, which is also where ``model_config``, its ``coerce``
+    and its validators stay."""
+
+    def __repr_name__(self) -> str:
+        """The class name without its parametrization.
+
+        Returns:
+            The unsubscripted class's name, or this class's own when it was never subscripted."""
+        origin = type(self).__pydantic_generic_metadata__["origin"]
+        return origin.__name__ if origin is not None else type(self).__name__
+
+
+class OAuthToken(BaseModel):
+    """The token endpoint's success body (RFC 6749 §5.1), and what a token source returns.
+
+    ``expires_in`` is RECOMMENDED rather than required, so its absence means "no client-side
+    deadline". ``token_type`` is parsed because the RFC requires it and deliberately **not** used
+    when applying: echoing a wire keyword into ``Authorization`` would put unvalidated data there.
+
+    No ``refresh_token``: RFC 6749 §4.4.3 says the client-credentials grant SHOULD NOT be issued
+    one. A grant that may be returns :class:`OAuthTokenRefreshable` instead."""
+
+    model_config = ConfigDict(frozen=True)
+
+    access_token: str = Field(repr=False)
+    token_type: str
+    expires_in: int | None = None
+    scope: str | None = None
+
+
+class OAuthTokenRefreshable(OAuthToken):
+    """The token endpoint's success body for a grant that may issue a refresh token.
+
+    RFC 6749 §4.1.4 and §4.3.3 both make ``refresh_token`` OPTIONAL. A subclass rather than an
+    optional field, so a source's declared return type says which tier it belongs to."""
+
+    refresh_token: str | None = Field(default=None, repr=False)
+
+
+class OAuthProviderError(BaseModel):
+    """The token endpoint's error body (RFC 6749 §5.2).
+
+    Typed, unlike the rest of a failed token fetch, because §5.2 fixes these three members for every
+    provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    error: str
+    error_description: str | None = None
+    error_uri: str | None = None
+
+
+OAuthError: TypeAlias = OAuthProviderError | RawError
+"""What a failed token fetch carries: the RFC 6749 §5.2 body, or the raw response without one."""
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthErrorResponse:
+    """Error mapper for the token endpoint.
+
+    The only mapper here that selects a *schema*, and it can: RFC 6749 §5.2 fixes one error body for
+    every provider. A response that does not conform becomes a :class:`RawError` rather than raising
+    out of the mapper, because a failed fetch must surface the provider's answer, not a parse error."""
+
+    def map(self, status_code: int, content: bytes) -> OAuthError:
+        try:
+            return OAuthProviderError.model_validate(parse_json(content))
+        except ValueError:
+            return RawError(status_code, content)
+
+
+oauth_error_response: Final[ErrorMapper[OAuthError]] = OAuthErrorResponse()
+
+
+OAuthParams: TypeAlias = tuple[Param[Any], ...]
+"""One destination's worth of parameters: half a token request, or an authorization URL's query."""
+
+CredentialsPlacement: TypeAlias = Callable[[str, str | None], tuple[OAuthParams, OAuthParams]]
+"""Where a client's own credentials travel on a token request: its headers, and its form fields.
+
+Named after the specification extension it is read from, ``x-oauth2-credentials-placement``.
+Grant-agnostic: RFC 6749 §2.3.1 authenticates the *client*, which every grant does identically."""
+
+
+def scope_params(scopes: Sequence[str] | None) -> OAuthParams:
+    """The ``scope`` field, or nothing at all when no scopes were asked for.
+
+    RFC 6749 §3.3's space delimiter, written once, so a caller passes a list and never learns it.
+    Takes a ``Sequence`` so a credential's narrowed ``list[ScopeT]`` reaches it without a copy.
+
+    Args:
+        scopes: The scopes to request; absent or empty asks for the client's defaults.
+
+    Returns:
+        One ``scope`` parameter, or an empty tuple."""
+    if not scopes:
+        return ()
+    return (param[str]("scope", " ".join(scopes)),)
+
+
+def client_secret_basic(client_id: str, client_secret: str | None) -> tuple[OAuthParams, OAuthParams]:
+    """RFC 6749 §2.3.1: the client authenticates with HTTP Basic on the token request.
+
+    Both halves are percent-encoded before base64, as §2.3.1 requires. A client with **no secret**
+    identifies itself with a ``client_id`` form field instead, which is §3.2.1's requirement exactly
+    then rather than a degraded fallback.
+
+    Args:
+        client_id: The client's identifier, as issued by the provider.
+        client_secret: Its secret, or ``None`` for a public client.
+
+    Returns:
+        The headers and the form fields the client's credentials contribute, in that order."""
+    if client_secret is None:
+        return (), (param[str]("client_id", client_id),)
+    raw = f"{quote(client_id, safe='')}:{quote(client_secret, safe='')}"
+    return (param[str]("Authorization", f"Basic {b64encode(raw.encode()).decode()}"),), ()
+
+
+def client_secret_post(client_id: str, client_secret: str | None) -> tuple[OAuthParams, OAuthParams]:
+    """RFC 6749 §2.3.1's alternative: the credentials travel in the form body instead.
+
+    The empty header tuple is the invariant, not an oversight -- carrying the pair in both places
+    would authenticate the client twice.
+
+    Args:
+        client_id: The client's identifier, as issued by the provider.
+        client_secret: Its secret, omitted entirely when ``None`` (§3.2.1).
+
+    Returns:
+        An empty header tuple, and the form fields the client's credentials contribute."""
+    if client_secret is None:
+        return (), (param[str]("client_id", client_id),)
+    return (), (
+        param[str]("client_id", client_id),
+        param[str]("client_secret", client_secret),
+    )

swagger_petstore_open_api_3_1_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_1_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_1_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_1_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_1_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}"),))