cliV1 0.0.8__py3-none-any.whl

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

swagger_petstore_open_api_3_0/core/auth/schemes/oauth2_authorization_code.py

@@ -0,0 +1,393 @@
+"""``oauth2`` / ``authorizationCode`` -- RFC 6749 §4.1, with RFC 7636 PKCE.
+
+The only grant that cannot complete without a human, and the only one needing the refreshable tier.
+
+**The human leg is a callback on the credentials**, not a two-step surface on the client: the source
+calls it in the middle of ``fetch`` -- build the URL, hand it over, exchange the code that comes
+back -- so the whole flow stays behind the one ``fetch(credentials)`` seam every grant shares.
+
+**The credentials are twinned** because that callback's flavour must match the transport awaiting
+it; a prompt blocking on a human is the last thing that should run inside an event loop."""
+
+from __future__ import annotations
+
+import secrets
+from base64 import urlsafe_b64encode
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Generic, Literal, TypeAlias
+
+from pydantic import ConfigDict, Field, model_validator
+from typing_extensions import NotRequired, Self, TypedDict
+
+from ..._internal.urls import build_url
+from ...bodies import form_body
+from ...decoding import async_json_decoder, json_decoder
+from ...params import UrlTemplate, param
+from ...raw_client import AsyncRawClient, RawClient
+from ...results import Success
+from ..models import (
+    CredentialsPlacement,
+    OAuth2Credentials,
+    OAuthParams,
+    OAuthTokenRefreshable,
+    ScopeT,
+    oauth_error_response,
+    scope_params,
+)
+
+AuthorizationCodePrompt: TypeAlias = Callable[[str], str]
+"""How the SDK obtains an authorization code: hand a URL to a human, get a code back.
+
+Given the fully built authorization URL, an implementation navigates the user to it, receives the
+redirect, and returns its ``code`` query parameter. Opening a browser and listening on the redirect
+URI are the caller's business: what is correct differs between a desktop app, a CLI and a test.
+
+Called on the first acquisition, and again whenever a refresh is refused. ⚠️ It runs **inside the
+scheme's lock**, so it must not issue a request that itself uses this scheme."""
+
+AsyncAuthorizationCodePrompt: TypeAlias = Callable[[str], Awaitable[str]]
+""":data:`AuthorizationCodePrompt` for the asynchronous client: awaited rather than called.
+
+A coroutine and not a union, so a synchronous prompt is a **type** error on the asynchronous
+credentials rather than a whole event loop discovered blocked on a human in production."""
+
+PkceMethod: TypeAlias = Literal["S256", "plain"]
+"""RFC 7636 §4.2's code-challenge transformations.
+
+A ``Literal`` and **not** a ``(str, Enum)``: these two members are fixed by an RFC, not derived from
+a description, so the set cannot grow after generation and a call site is checked statically."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Pkce:
+    """One authorization's verifier, its derived challenge, and which transformation derived it."""
+
+    verifier: str
+    challenge: str
+    method: PkceMethod
+
+
+def _generate_pkce(method: PkceMethod) -> _Pkce:
+    """A fresh RFC 7636 §4.1 verifier and its §4.2 challenge -- one pair per authorization.
+
+    Per acquisition rather than per client, because a verifier reused across authorizations is one
+    an observer of the first can replay against the second.
+
+    Args:
+        method: ``S256``, or ``plain`` where §7.2 permits it -- the verifier as its own challenge.
+
+    Returns:
+        The verifier, its challenge, and the method that derived it."""
+    verifier = secrets.token_urlsafe(32)
+    if method == "plain":
+        return _Pkce(verifier, verifier, method)
+    digest = sha256(verifier.encode("ascii")).digest()
+    return _Pkce(verifier, urlsafe_b64encode(digest).rstrip(b"=").decode("ascii"), method)
+
+
+class AuthorizationCodeCredentials(OAuth2Credentials, Generic[ScopeT]):
+    """What the authorization-code grant needs, for the synchronous client (RFC 6749 §4.1).
+
+    ``prompt_for_authorization_code`` is **required**, so a configured credential provably has a way
+    to obtain a code, checked when this model is built rather than at the first request.
+
+    ``state`` is **pass-through only**: sent on the authorization request, never generated or
+    validated here -- the SDK never sees the redirect, so producing and verifying it are the
+    caller's one job. ``pkce`` defaults to ``"S256"``; ``None`` disables it and then requires
+    ``client_secret``, which the validator below refuses at construction. ``scopes`` is typed by
+    the flow's declared vocabulary, as every grant's is."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    client_id: str
+    client_secret: str | None = Field(default=None, repr=False)
+    redirect_uri: str
+    scopes: list[ScopeT] | None = None
+    state: str | None = None
+    pkce: PkceMethod | None = "S256"
+    prompt_for_authorization_code: AuthorizationCodePrompt
+
+    @model_validator(mode="after")
+    def _require_a_secret_without_pkce(self) -> Self:
+        if self.pkce is None and self.client_secret is None:
+            raise ValueError(
+                "client_secret is required when pkce is None: a client that neither authenticates "
+                "nor proves possession of a code verifier cannot use the authorization-code grant "
+                'safely. Set pkce="S256" for a public client, or supply client_secret.'
+            )
+        return self
+
+    @classmethod
+    def coerce(cls, value: AuthorizationCodeCredentialsOrDict[ScopeT]) -> AuthorizationCodeCredentials[ScopeT]:
+        """Accept either spelling, validating the mapping form.
+
+        Args:
+            value: The credential, as the typed model or as a mapping.
+
+        Returns:
+            The validated model; see :meth:`BasicAuthCredentials.coerce` for why it takes no
+            ``None``.
+
+        Raises:
+            ValidationError: If a key is missing or unknown, if ``scopes`` names one this flow does
+                not declare, or if ``pkce`` is ``None`` without a ``client_secret``."""
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+class AuthorizationCodeCredentialsDict(TypedDict, Generic[ScopeT]):
+    client_id: str
+    client_secret: NotRequired[str | None]
+    redirect_uri: str
+    scopes: NotRequired[list[ScopeT] | None]
+    state: NotRequired[str | None]
+    pkce: NotRequired[PkceMethod | None]
+    prompt_for_authorization_code: AuthorizationCodePrompt
+
+
+AuthorizationCodeCredentialsOrDict: TypeAlias = (
+    AuthorizationCodeCredentials[ScopeT] | AuthorizationCodeCredentialsDict[ScopeT]
+)
+"""What an authorization-code credential accepts: the typed model, or a mapping of the same keys."""
+
+
+class AsyncAuthorizationCodeCredentials(OAuth2Credentials, Generic[ScopeT]):
+    """:class:`AuthorizationCodeCredentials` for the asynchronous client.
+
+    Identical but for ``prompt_for_authorization_code``, which is awaited. Written out rather than
+    sharing a base: the two would still need their own ``coerce``, ``TypedDict`` and validator."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    client_id: str
+    client_secret: str | None = Field(default=None, repr=False)
+    redirect_uri: str
+    scopes: list[ScopeT] | None = None
+    state: str | None = None
+    pkce: PkceMethod | None = "S256"
+    prompt_for_authorization_code: AsyncAuthorizationCodePrompt
+
+    @model_validator(mode="after")
+    def _require_a_secret_without_pkce(self) -> Self:
+        if self.pkce is None and self.client_secret is None:
+            raise ValueError(
+                "client_secret is required when pkce is None: a client that neither authenticates "
+                "nor proves possession of a code verifier cannot use the authorization-code grant "
+                'safely. Set pkce="S256" for a public client, or supply client_secret.'
+            )
+        return self
+
+    @classmethod
+    def coerce(
+        cls, value: AsyncAuthorizationCodeCredentialsOrDict[ScopeT]
+    ) -> AsyncAuthorizationCodeCredentials[ScopeT]:
+        """See :meth:`AuthorizationCodeCredentials.coerce`.
+
+        Args:
+            value: The credential, as the typed model or as a mapping.
+
+        Returns:
+            The validated model.
+
+        Raises:
+            ValidationError: If a key is missing or unknown, if ``scopes`` names one this flow does
+                not declare, or if ``pkce`` is ``None`` without a ``client_secret``."""
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+class AsyncAuthorizationCodeCredentialsDict(TypedDict, Generic[ScopeT]):
+    client_id: str
+    client_secret: NotRequired[str | None]
+    redirect_uri: str
+    scopes: NotRequired[list[ScopeT] | None]
+    state: NotRequired[str | None]
+    pkce: NotRequired[PkceMethod | None]
+    prompt_for_authorization_code: AsyncAuthorizationCodePrompt
+
+
+AsyncAuthorizationCodeCredentialsOrDict: TypeAlias = (
+    AsyncAuthorizationCodeCredentials[ScopeT] | AsyncAuthorizationCodeCredentialsDict[ScopeT]
+)
+""":data:`AuthorizationCodeCredentialsOrDict` for the asynchronous client."""
+
+
+def _authorization_params(
+    credentials: AuthorizationCodeCredentials[ScopeT] | AsyncAuthorizationCodeCredentials[ScopeT],
+    pkce: _Pkce | None,
+) -> OAuthParams:
+    """RFC 6749 §4.1.1's authorization request, as query parameters.
+
+    Shared by both flavours: what goes on an authorization URL does not depend on which transport
+    later exchanges the code.
+
+    Args:
+        credentials: The configured credentials, in either flavour.
+        pkce: This acquisition's PKCE pair, or ``None`` when PKCE is disabled.
+
+    Returns:
+        The query parameters for the authorization URL. ``state`` is omitted entirely when unset
+        rather than sent empty, since §4.1.1 only RECOMMENDS it."""
+    params = (
+        param[str]("response_type", "code"),
+        param[str]("client_id", credentials.client_id),
+        param[str]("redirect_uri", credentials.redirect_uri),
+        *scope_params(credentials.scopes),
+    )
+    if credentials.state is not None:
+        params = (*params, param[str]("state", credentials.state))
+    if pkce is None:
+        return params
+    return (
+        *params,
+        param[str]("code_challenge", pkce.challenge),
+        param[PkceMethod]("code_challenge_method", pkce.method),
+    )
+
+
+def _code_verifier_params(pkce: _Pkce | None) -> OAuthParams:
+    """RFC 7636 §4.5's ``code_verifier`` on the exchange.
+
+    Args:
+        pkce: This acquisition's PKCE pair, or ``None`` when PKCE is disabled.
+
+    Returns:
+        One ``code_verifier`` parameter, or an empty tuple."""
+    if pkce is None:
+        return ()
+    return (param[str]("code_verifier", pkce.verifier),)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AuthorizationCodeTokenSource(Generic[ScopeT]):
+    """The built-in :class:`RefreshableTokenSource` for the authorization-code grant.
+
+    Two requests with a human between them: :meth:`fetch` builds the authorization URL, hands it to
+    the credentials' prompt and exchanges the code; :meth:`refresh` skips both, which is the entire
+    reason this grant needs the refreshable tier.
+
+    ``refresh_url`` is its own field because the flow declares ``refreshUrl`` beside ``tokenUrl``;
+    §6 defaults it to the token endpoint, but a description naming another is read, not guessed."""
+
+    client: RawClient
+    authorization_url: UrlTemplate
+    token_url: UrlTemplate
+    refresh_url: UrlTemplate
+    placement: CredentialsPlacement
+
+    def fetch(self, credentials: AuthorizationCodeCredentials[ScopeT]) -> OAuthTokenRefreshable:
+        pkce = _generate_pkce(credentials.pkce) if credentials.pkce is not None else None
+        code = credentials.prompt_for_authorization_code(
+            build_url(self.authorization_url, query_params=_authorization_params(credentials, pkce))
+        )
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        return self.client.execute(
+            http_method="POST",
+            url_template=self.token_url,
+            headers=headers,
+            body=form_body(
+                param[str]("grant_type", "authorization_code"),
+                param[str]("code", code),
+                param[str]("redirect_uri", credentials.redirect_uri),
+                *_code_verifier_params(pkce),
+                *client_params,
+            ),
+            decoder=json_decoder[OAuthTokenRefreshable],
+            error_mapper=oauth_error_response,
+        ).unwrap()
+
+    def refresh(
+        self, credentials: AuthorizationCodeCredentials[ScopeT], refresh_token: str
+    ) -> OAuthTokenRefreshable | None:
+        """RFC 6749 §6, and ``None`` when the provider refuses.
+
+        The one operation in this runtime that reads an ``ApiResult`` instead of unwrapping it: a
+        refused refresh is a step in the flow, not an error, so the scheme re-acquires instead.
+
+        Args:
+            credentials: The configured credentials.
+            refresh_token: The refresh token to spend.
+
+        Returns:
+            The new token, or ``None`` for a provider refusal. A transport failure propagates, as
+            does a success whose body will not decode."""
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        result = self.client.execute(
+            http_method="POST",
+            url_template=self.refresh_url,
+            headers=headers,
+            body=form_body(
+                param[str]("grant_type", "refresh_token"),
+                param[str]("refresh_token", refresh_token),
+                *client_params,
+            ),
+            decoder=json_decoder[OAuthTokenRefreshable],
+            error_mapper=oauth_error_response,
+        )
+        return result.payload if isinstance(result, Success) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AsyncAuthorizationCodeTokenSource(Generic[ScopeT]):
+    """:class:`AuthorizationCodeTokenSource` for the asynchronous client.
+
+    The prompt is awaited, as are both requests."""
+
+    client: AsyncRawClient
+    authorization_url: UrlTemplate
+    token_url: UrlTemplate
+    refresh_url: UrlTemplate
+    placement: CredentialsPlacement
+
+    async def fetch(self, credentials: AsyncAuthorizationCodeCredentials[ScopeT]) -> OAuthTokenRefreshable:
+        pkce = _generate_pkce(credentials.pkce) if credentials.pkce is not None else None
+        code = await credentials.prompt_for_authorization_code(
+            build_url(self.authorization_url, query_params=_authorization_params(credentials, pkce))
+        )
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        return (
+            await self.client.execute(
+                http_method="POST",
+                url_template=self.token_url,
+                headers=headers,
+                body=form_body(
+                    param[str]("grant_type", "authorization_code"),
+                    param[str]("code", code),
+                    param[str]("redirect_uri", credentials.redirect_uri),
+                    *_code_verifier_params(pkce),
+                    *client_params,
+                ),
+                decoder=async_json_decoder[OAuthTokenRefreshable],
+                error_mapper=oauth_error_response,
+            )
+        ).unwrap()
+
+    async def refresh(
+        self, credentials: AsyncAuthorizationCodeCredentials[ScopeT], refresh_token: str
+    ) -> OAuthTokenRefreshable | None:
+        """See :meth:`AuthorizationCodeTokenSource.refresh`.
+
+        Args:
+            credentials: The configured credentials.
+            refresh_token: The refresh token to spend.
+
+        Returns:
+            The new token, or ``None`` for a provider refusal."""
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        result = await self.client.execute(
+            http_method="POST",
+            url_template=self.refresh_url,
+            headers=headers,
+            body=form_body(
+                param[str]("grant_type", "refresh_token"),
+                param[str]("refresh_token", refresh_token),
+                *client_params,
+            ),
+            decoder=async_json_decoder[OAuthTokenRefreshable],
+            error_mapper=oauth_error_response,
+        )
+        return result.payload if isinstance(result, Success) else None

swagger_petstore_open_api_3_0/core/auth/schemes/oauth2_client_credentials.py

@@ -0,0 +1,127 @@
+"""``oauth2`` / ``clientCredentials`` -- RFC 6749 §4.4.
+
+The grant with the least to it: no resource owner, so no second credential pair and no human. The
+whole request is a ``grant_type``, the scopes, and whatever the placement contributes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeAlias
+
+from pydantic import ConfigDict, Field
+from typing_extensions import NotRequired, TypedDict
+
+from ...bodies import form_body
+from ...decoding import async_json_decoder, json_decoder
+from ...params import UrlTemplate, param
+from ...raw_client import AsyncRawClient, RawClient
+from ..models import (
+    CredentialsPlacement,
+    OAuth2Credentials,
+    OAuthParams,
+    OAuthToken,
+    ScopeT,
+    oauth_error_response,
+    scope_params,
+)
+
+
+class ClientCredentials(OAuth2Credentials, Generic[ScopeT]):
+    """The client identifier and secret of an OAuth 2.0 ``clientCredentials`` flow (RFC 6749 §4.4).
+
+    ``scopes`` is a list this SDK joins for the wire, so a caller never writes §3.3's delimiter, and
+    it is typed by the flow's declared vocabulary -- so a scope the flow does not document fails the
+    build at the call site instead of the request at the provider."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    client_id: str
+    client_secret: str = Field(repr=False)
+    scopes: list[ScopeT] | None = None
+
+    @classmethod
+    def coerce(cls, value: ClientCredentialsOrDict[ScopeT]) -> ClientCredentials[ScopeT]:
+        """Accept either spelling, validating the mapping form.
+
+        Args:
+            value: The credential, as the typed model or as a mapping.
+
+        Returns:
+            The validated model; see :meth:`BasicAuthCredentials.coerce` for why it takes no
+            ``None``.
+
+        Raises:
+            ValidationError: If the mapping is missing a key, carries an unknown one, or names a
+                scope this flow does not declare."""
+        if isinstance(value, cls):
+            return value
+        return cls.model_validate(value)
+
+
+class ClientCredentialsDict(TypedDict, Generic[ScopeT]):
+    client_id: str
+    client_secret: str
+    scopes: NotRequired[list[ScopeT] | None]
+
+
+ClientCredentialsOrDict: TypeAlias = ClientCredentials[ScopeT] | ClientCredentialsDict[ScopeT]
+"""What a client-credentials credential accepts: the typed model, or a mapping of the same keys."""
+
+
+def _token_params(credentials: ClientCredentials[ScopeT]) -> OAuthParams:
+    """RFC 6749 §4.4.2's token request, minus the client's own credentials.
+
+    Shared by both flavours rather than duplicated, so an edit cannot land in one only.
+
+    Args:
+        credentials: The configured client credentials.
+
+    Returns:
+        The ``grant_type`` and the scopes; the placement's half is spliced in by each ``fetch``."""
+    return param[str]("grant_type", "client_credentials"), *scope_params(credentials.scopes)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClientCredentialsTokenSource(Generic[ScopeT]):
+    """The built-in :class:`TokenSource` for the client-credentials grant: POST the token request.
+
+    ``placement`` is a field rather than two subclasses, because the placements differ in *data* and
+    not in behaviour: :meth:`fetch` is identical for both. Carries no ``auth_scheme=`` -- the
+    credentials are on this request already, so the fetch provably cannot recurse into itself."""
+
+    client: RawClient
+    token_url: UrlTemplate
+    placement: CredentialsPlacement
+
+    def fetch(self, credentials: ClientCredentials[ScopeT]) -> OAuthToken:
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        return self.client.execute(
+            http_method="POST",
+            url_template=self.token_url,
+            headers=headers,
+            body=form_body(*_token_params(credentials), *client_params),
+            decoder=json_decoder[OAuthToken],
+            error_mapper=oauth_error_response,
+        ).unwrap()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AsyncClientCredentialsTokenSource(Generic[ScopeT]):
+    """:class:`ClientCredentialsTokenSource` for the asynchronous client: the request is awaited."""
+
+    client: AsyncRawClient
+    token_url: UrlTemplate
+    placement: CredentialsPlacement
+
+    async def fetch(self, credentials: ClientCredentials[ScopeT]) -> OAuthToken:
+        headers, client_params = self.placement(credentials.client_id, credentials.client_secret)
+        return (
+            await self.client.execute(
+                http_method="POST",
+                url_template=self.token_url,
+                headers=headers,
+                body=form_body(*_token_params(credentials), *client_params),
+                decoder=async_json_decoder[OAuthToken],
+                error_mapper=oauth_error_response,
+            )
+        ).unwrap()