ds_fetch_py_sdk.auth
====================

.. py:module:: ds_fetch_py_sdk.auth

.. autoapi-nested-parse::

   Authentication against the AI Commons identity server.

   - `BearerToken`: a platform JWT you already have.
   - `BrowserLogin`: OAuth authorization code + PKCE in the browser, including enterprise SSO.
   - `PasswordLogin`: email and password at `/auth/login/`, with TOTP MFA when enabled.
   - `ClientCredentials`: OAuth client credentials, for machines.

   Every flow signs in at the environment's issuer, never at one a server names. OAuth flows read
   its endpoints from its authorization-server metadata (RFC 8414), which must name that issuer,
   and bind tokens to the API with `resource` (RFC 8707).







Module Contents
---------------

.. py:class:: BearerToken(token: str)

   Bases: :py:obj:`httpx.Auth`


   A platform JWT you already have.


   .. py:method:: auth_flow(request: httpx.Request) -> collections.abc.Generator[httpx.Request, httpx.Response, None]

      Execute the authentication flow.

      To dispatch a request, `yield` it:

      ```
      yield request
      ```

      The client will `.send()` the response back into the flow generator. You can
      access it like so:

      ```
      response = yield request
      ```

      A `return` (or reaching the end of the generator) will result in the
      client returning the last response obtained from the server.

      You can dispatch as many requests as is necessary.



.. py:function:: default_cache() -> pathlib.Path

   Where sessions are cached: `$XDG_CONFIG_HOME/aic/credentials.json`, default `~/.config`.


.. py:class:: TokenAuth(*, issuer: str | None = None, cache: pathlib.Path | bool = False)

   Bases: :py:obj:`httpx.Auth`


   A session with the identity server: acquires, caches and renews tokens, and retries once on 401.

   Sessions are cached per environment in `default_cache()`, or at `cache`; `cache=False` keeps them
   in memory.


   .. py:method:: login() -> None

      Sign in now, replacing any cached session.



   .. py:method:: logout() -> None

      Forget the session, in memory and in the cache.



   .. py:method:: auth_flow(request: httpx.Request) -> collections.abc.Generator[httpx.Request, httpx.Response, None]

      Execute the authentication flow.

      To dispatch a request, `yield` it:

      ```
      yield request
      ```

      The client will `.send()` the response back into the flow generator. You can
      access it like so:

      ```
      response = yield request
      ```

      A `return` (or reaching the end of the generator) will result in the
      client returning the last response obtained from the server.

      You can dispatch as many requests as is necessary.



.. py:class:: OAuth(*, scope: str = 'openid read', **kwargs: Any)

   Bases: :py:obj:`TokenAuth`


   OAuth 2.1 against the identity server, with endpoints from RFC 8414 metadata.


   .. py:property:: metadata
      :type: dict[str, Any]


      The identity server's RFC 8414 metadata, checked to be its own and to use HTTPS.


.. py:class:: ClientCredentials(client_id: str, client_secret: str, **kwargs: Any)

   Bases: :py:obj:`OAuth`


   Machine-to-machine sign-in with a registered client id and secret.


.. py:class:: BrowserLogin(*, client_id: str | None = None, port: int = 8976, cache: pathlib.Path | bool = True, open_browser: bool = True, on_url: collections.abc.Callable[[str], None] | None = None, timeout: float = 300, **kwargs: Any)

   Bases: :py:obj:`OAuth`


   Interactive sign-in in the browser, including enterprise SSO.

   Uses authorization code with PKCE on a loopback redirect. Without a `client_id` the
   SDK registers a public client (RFC 7591) and caches its id with the session.
   `on_url` receives the sign-in URL, for when the browser cannot be opened; it defaults
   to writing it to stderr.


.. py:class:: PasswordLogin(email: str | None = None, password: str | None = None, *, mfa_code: str | collections.abc.Callable[[int], str] | None = None, cache: pathlib.Path | bool = True, **kwargs: Any)

   Bases: :py:obj:`TokenAuth`


   Sign in with email and password at the identity server's `/auth/login/`.

   When the account has MFA, `mfa_code` supplies the TOTP code: a string, or a callable that
   receives the number of digits and returns the code. The session is renewed with its refresh
   token; once that expires, signing in again needs the password.


.. py:function:: cached_session(env: ds_fetch_py_sdk.env.Environment, cache: pathlib.Path | None = None) -> TokenAuth | None

   The cached sign-in for `env`, as the auth that created it, or None.