earthscope-sdk 0.2.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

earthscope_sdk/__init__.py

@@ -1 +1,5 @@
-__version__ = "0.2.1"
+__version__ = "1.0.0"
+
+from earthscope_sdk.client import AsyncEarthScopeClient, EarthScopeClient
+
+__all__ = ["AsyncEarthScopeClient", "EarthScopeClient"]

earthscope_sdk/auth/auth_flow.py

@@ -1,441 +1,335 @@
 import datetime as dt
-import json
 import logging
+from contextlib import suppress
+from typing import Optional
 
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import Dict, Optional, Union
-import jwt
+import httpx
+from pydantic import ValidationError
 
-import requests
+from earthscope_sdk.auth.error import (
+    InvalidRefreshTokenError,
+    NoAccessTokenError,
+    NoRefreshTokenError,
+    NoTokensError,
+)
+from earthscope_sdk.common.context import SdkContext
+from earthscope_sdk.config.models import AccessTokenBody, Tokens
 
 logger = logging.getLogger(__name__)
 
 
-class AuthFlowError(Exception):
-    """Generic authentication flow error"""
-
-
-class UnauthorizedError(AuthFlowError):
-    pass
-
-
-class NoTokensError(AuthFlowError):
-    pass
-
-
-class NoIdTokenError(NoTokensError):
-    pass
-
-
-class NoRefreshTokenError(NoTokensError):
-    pass
-
-
-class InvalidRefreshTokenError(AuthFlowError):
-    pass
-
-
-@dataclass
-class TokensResponse:
-    access_token: str
-    refresh_token: Optional[str]
-    id_token: Optional[str]
-    token_type: str
-    expires_in: int
-    scope: Optional[str]
-
-
-@dataclass
-class UnvalidatedTokens:
-    access_token: str
-    id_token: Optional[str]
-    refresh_token: Optional[str]
-    scope: str
-
-    @classmethod
-    def from_dict(cls, o: Dict):
-        return cls(
-            access_token=o.get("access_token"),
-            id_token=o.get("id_token"),
-            refresh_token=o.get("refresh_token"),
-            scope=o.get("scope"),
-        )
-
-
-@dataclass
-class ValidTokens(UnvalidatedTokens):
-    expires_at: int
-    issued_at: int
-
-    @classmethod
-    def from_unvalidated(cls, creds: UnvalidatedTokens, body: Dict):
-        return cls(
-            access_token=creds.access_token,
-            id_token=creds.id_token,
-            refresh_token=creds.refresh_token,
-            scope=creds.scope,
-            expires_at=body.get("exp"),
-            issued_at=body.get("iat"),
-        )
-
-
-class AuthFlow(ABC):
+class AuthFlow(httpx.Auth):
     """
-    This is an abstract class that handles retrieving, validating, saving, and refreshing access tokens.
-
-    Attributes
-    __________
-    domain : str
-        Auth0 tenant domain URL or custom domain (default is 'login.earthscope.org')
-    audience : str
-        Auth0 API Identifier (default is 'https://account.earthscope.org')
-    client_id : str
-        Identification value of Auth0 Application (default is 'b9DtAFBd6QvMg761vI3YhYquNZbJX5G0')
-    scope : str
-        The specific actions Auth0 applications can be allowed to do or information that they can request on a user’s behalf.
-    _tokens : str, optional
-        Access or ID Token
-    _access_token_body : dict, optional
-        Body of the decrypted access token
-    _id_token_body : dict, optional
-        Body of the decrypted id token
-
-    Methods
-    _______
-    load_tokens
-        Load the token (abstract method)
-    save_tokens(creds)
-        Save the token (abstract method)
-    refresh(scope=None, revoke=False)
-        Refresh the access token or revoke the refresh token
-    validate_and_save_tokens(unvalidated_creds)
-        Validate and save the token
-    validate_tokens(unvalidated_creds)
-        Validate the token
-    get_access_token_refresh_if_necessary(no_auto_refresh=False, auto_refresh_threshold=3600)
-        Retrieve the access token. Automatically refreshes the token when necessary.
-
+    Generic oauth2 flow class for handling retrieving, validating, saving, and refreshing access tokens.
     """
+
     @property
     def access_token(self):
         """
-        Get access token
-
-        Returns
-        -------
-        access token: str
-        """
-        return self.tokens.access_token
+        Access token
 
-    @property
-    def access_token_body(self):
+        Raises:
+            NoTokensError: no tokens (at all) are present
+            NoAccessTokenError: no access token is present
         """
-        Body of the access token
+        if at := self.tokens.access_token:
+            return at.get_secret_value()
 
-        Raises
-        ______
-        NoTokensError
-            If there is no token
-
-        Returns
-        -------
-        access_token_body: dict
-        """
-        if self._access_token_body is None:
-            raise NoTokensError
-        return self._access_token_body
+        raise NoAccessTokenError("No access token was found. Please re-authenticate.")
 
     @property
-    def tokens(self):
+    def access_token_body(self):
         """
-        Get tokens
-
-        raises
-        ------
-        NoTokensError
-            If no token to retrieve
+        Access token body
 
-        Returns
-        -------
-        tokens
+        Raises:
+            NoAccessTokenError: no access token is present
         """
-        if not self._tokens:
-            raise NoTokensError
+        if body := self._access_token_body:
+            return body
 
-        return self._tokens
+        raise NoAccessTokenError("No access token was found. Please re-authenticate.")
 
     @property
     def expires_at(self):
         """
-        When the token expires
+        Time of access token expiration
 
-        Returns
-        -------
-        datetime
+        Raises:
+            NoAccessTokenError: no access token is present
         """
-        return dt.datetime.fromtimestamp(self.tokens.expires_at, dt.timezone.utc)
+        return self.access_token_body.expires_at
 
     @property
-    def id_token(self):
+    def has_refresh_token(self):
         """
-        Get the ID token
-
-        Raises
-        ------
-        NoIDTokenError
-            If there is no id token to be retrieved
-
-        Returns
-        -------
-        id token: srt
+        Whether or not we have a refresh token
         """
-        idt = self.tokens.id_token
-        if not idt:
-            raise NoIdTokenError
-
-        return idt
+        try:
+            return self.refresh_token is not None
+        except NoTokensError:
+            return False
 
     @property
-    def id_token_body(self):
+    def issued_at(self):
         """
-        Body of the id token
-
-        Raises
-        ______
-        NoIdTokenError
-            If there is no id token
+        Time of access token creation
 
-        Returns
-        -------
-        id_token_body: dict
+        Raises:
+            NoAccessTokenError: no access token is present
         """
-        if self._id_token_body is None:
-            raise NoIdTokenError
-        return self._id_token_body
+        return self.access_token_body.issued_at
 
     @property
-    def issued_at(self):
+    def refresh_token(self):
         """
-        When the token was issued
+        Refresh token
 
-        Returns
-        -------
-        datetime
+        Raises:
+            NoTokensError: no tokens (at all) are present
+            NoRefreshTokenError: no refresh token is present
         """
-        return dt.datetime.fromtimestamp(self.tokens.issued_at, dt.timezone.utc)
+        if rt := self.tokens.refresh_token:
+            return rt.get_secret_value()
+
+        raise NoRefreshTokenError("No refresh token was found. Please re-authenticate.")
 
     @property
-    def refresh_token(self):
+    def scope(self):
         """
-        Get the refresh token
+        Access token scope
 
-        Raises
-        ------
-        NoRefreshTokenError
-            If there is no refresh token to be retrieved
-
-        Returns
-        -------
-        refresh token: srt
+        Raises:
+            NoAccessTokenError: no access token is present
         """
-        rt = self.tokens.refresh_token
-        if not rt:
-            raise NoRefreshTokenError
-
-        return rt
+        return set(self.access_token_body.scope.split())
 
     @property
-    def has_refresh_token(self):
+    def tokens(self):
         """
-        If the acces token contains a refresh token
+        Oauth2 tokens managed by this auth flow
 
-        Returns
-        -------
-        boolean
+        Raises:
+            NoTokensError: no tokens (at all) are present
         """
-        try:
-            return self.tokens.refresh_token is not None
-        except NoTokensError:
-            return False
+        if tokens := self._tokens:
+            return tokens
+
+        raise NoTokensError("No tokens were found. Please re-authenticate.")
 
     @property
     def ttl(self):
         """
-        Time to live of the token
+        Access token time-to-live (ttl) before expiration
 
-        Returns
-        -------
-        datetime
+        Raises:
+            NoAccessTokenError: no access token is present
         """
-        return self.expires_at - dt.datetime.now(dt.timezone.utc)
+        return self.access_token_body.ttl
+
+    def __init__(self, ctx: SdkContext) -> None:
+        self._ctx = ctx
+        self._settings = ctx.settings.oauth2
 
-    def __init__(self, domain: str, audience: str, client_id: str, scope: str) -> None:
-        self.auth0_domain = domain
-        self.auth0_audience = audience
-        self.auth0_client_id = client_id
-        self.token_scope = scope
+        # Local state
+        self._access_token_body: Optional[AccessTokenBody] = None
+        self._tokens: Optional[Tokens] = None
 
-        self._tokens: Optional[ValidTokens] = None
-        self._access_token_body: Optional[Dict[str, Union[str, int]]] = None
-        self._id_token_body: Optional[Dict[str, Union[str, int]]] = None
+        # httpx.Auth objects can be used in either sync or async clients so we
+        # facilitate both from the same class
+        self.refresh = ctx.syncify(self.async_refresh)
+        self.refresh_if_necessary = ctx.syncify(self.async_refresh_if_necessary)
+        self.revoke_refresh_token = ctx.syncify(self.async_revoke_refresh_token)
 
-    @abstractmethod
-    def load_tokens(self):
+        # Initialize with provided tokens
+        with suppress(ValidationError):
+            self._validate_tokens(self._settings)
+
+    async def async_refresh(self, scope: Optional[str] = None):
         """
-        Load the token (abstract method)
+        Refresh the access token
+
+        Args:
+            scope: the specific oauth2 scopes to request
+
+        Raises:
+            NoTokensError: no tokens (at all) are present
+            NoRefreshTokenError: no refresh token is present
+            InvalidRefreshTokenError: the token refresh failed
+        """
+        from httpx import HTTPStatusError, ReadTimeout
+
+        refresh_token = self.refresh_token
+        scope = scope or self._settings.scope
+
+        request = self._ctx.httpx_client.build_request(
+            "POST",
+            f"{self._settings.domain}oauth/token",
+            headers={"content-type": "application/x-www-form-urlencoded"},
+            data={
+                "grant_type": "refresh_token",
+                "client_id": self._settings.client_id,
+                "refresh_token": refresh_token,
+                "scopes": scope,
+            },
+        )
+
+        try:
+            async for attempt in self._settings.retry.retry_context(ReadTimeout):
+                with attempt:
+                    r = await self._ctx.httpx_client.send(request, auth=None)
+                    r.raise_for_status()
+        except HTTPStatusError as e:
+            logger.error(
+                f"error during token refresh ({attempt.num} attempts): {e.response.content}"
+            )
+            raise InvalidRefreshTokenError("refresh token exchange failed")
+        except Exception as e:
+            logger.error(
+                f"error during token refresh ({attempt.num} attempts)", exc_info=e
+            )
+            raise InvalidRefreshTokenError("refresh token exchange failed") from e
+
+        # add previous refresh token to new tokens if omitted from resp
+        # (i.e. we have a non-rotating refresh token)
+        resp: dict = r.json()
+        resp.setdefault("refresh_token", refresh_token)
+
+        self._validate_and_save_tokens(resp)
+
+        logger.debug(f"Refreshed tokens: {self._tokens}")
+        return self
+
+    async def async_refresh_if_necessary(
+        self,
+        scope: Optional[str] = None,
+        auto_refresh_threshold: int = 60,
+    ):
         """
-        pass
+        Refresh the access token if it is expired or bootstrap the access token from a refresh token
+
+        Args:
+            scope: the specific oauth2 scopes to request
+            auto_refresh_threshold: access token TTL remaining (in seconds) before auto-refreshing
 
-    @abstractmethod
-    def save_tokens(self, creds: ValidTokens):
+        Raises:
+            NoTokensError: no tokens (at all) are present
+            NoRefreshTokenError: no refresh token is present
+            InvalidRefreshTokenError: the token refresh failed
         """
-        Save the token (abstract method)
+        # Suppress to allow bootstrapping with a refresh token
+        with suppress(NoAccessTokenError):
+            if self.ttl >= dt.timedelta(seconds=auto_refresh_threshold):
+                return self
+
+        return await self.async_refresh(scope=scope)
 
-        Parameters
-        ----------
-        creds : ValidTokens
+    async def async_revoke_refresh_token(self):
         """
-        pass
+        Revoke the refresh token.
+
+        This invalidates the refresh token server-side so it may never again be used to
+        get new access tokens.
 
-    def refresh(self, scope: Optional[str] = None, revoke: bool = False):
+        Raises:
+            NoTokensError: no tokens (at all) are present
+            NoRefreshTokenError: no refresh token is present
+            InvalidRefreshTokenError: the token revocation failed
         """
-        Refresh the access token
+        refresh_token = self.refresh_token
 
-        Parameters
-        __________
-        scope : str, optional
-            The specific actions Auth0 applications can be allowed to do or information that they can request on a user’s behalf.
-        revoke: bool, optional
-            Whether to revoke the refresh token (default is False)
-
-        Raises
-        ______
-        InvalidRefreshTokenError
-            If the token refresh fails
-        """
-        scope = scope or self.token_scope
-
-        if not self.has_refresh_token:
-            raise NoRefreshTokenError("No refresh token was found. Please re-authenticate.")
-
-        if revoke:
-            r = requests.post(
-                f"https://{self.auth0_domain}/oauth/revoke",
-                headers={"content-type": "application/json"},
-                data=json.dumps({
-                    "client_id": self.auth0_client_id,
-                    "token": self.refresh_token,
-                }),
-            )
-            if r.status_code == 200:
-                logger.debug(f"Refresh token revoked: {self.refresh_token}")
-                return
-            else:
-                raise RuntimeError(r.json()["detail"])
-                
-
-        else:
-            r = requests.post(
-                f"https://{self.auth0_domain}/oauth/token",
-                headers={"content-type": "application/x-www-form-urlencoded"},
-                data={
-                    "grant_type": "refresh_token",
-                    "client_id": self.auth0_client_id,
-                    "refresh_token": self.refresh_token,
-                    "scopes": scope,
-                },
-            )
+        r = await self._ctx.httpx_client.post(
+            f"{self._settings.domain}oauth/revoke",
+            auth=None,  # override client default
+            headers={"content-type": "application/json"},
+            json={
+                "client_id": self._settings.client_id,
+                "token": refresh_token,
+            },
+        )
 
-            # add previous refresh token to new access token
-            if r.status_code == 200:
-                refresh_token = self.refresh_token
-                self.validate_and_save_tokens(r.json())
-                if not self.has_refresh_token:
-                    self._tokens.refresh_token = refresh_token
-                    self.save_tokens(self._tokens)
-                logger.debug(f"Refreshed tokens: {self._tokens}")
-                return self
+        if r.status_code != 200:
+            logger.error(f"error while revoking refresh token: {r.content}")
+            raise InvalidRefreshTokenError("refresh token revocation failed")
 
-        raise InvalidRefreshTokenError
+        logger.debug(f"Refresh token revoked: {refresh_token}")
+        return self
 
-    def validate_and_save_tokens(self, unvalidated_creds: Dict):
+    def _validate_and_save_tokens(self, unvalidated_tokens: dict):
         """
-        Validate and save the token
+        Validate then save tokens to local storage
 
-        Parameters
-        __________
-        unvalidated_creds: dict
-            The unvalidated credentials to be validated
+        Args:
+            unvalidated_tokens: tokens that have yet to be validated
+
+        Returns:
+            this auth flow
+
+        Raises:
+            pydantic.ValidationError: the token's body could not be decoded
         """
-        self.validate_tokens(unvalidated_creds)
+        self._validate_tokens(unvalidated_tokens)
+
         try:
-            self.save_tokens(self._tokens)
+            self._ctx.settings.write_tokens(self._tokens)
         except Exception as e:
             logger.error("Error while persisting tokens", exc_info=e)
+            raise
 
         return self
 
-    def validate_tokens(self, unvalidated_creds: Dict):
+    def _validate_tokens(self, unvalidated_tokens: dict):
         """
-        Validate the token
+        Validate the tokens
 
-        Paramaters
-        ----------
-        unvalidated_creds: dict
-            The unvalidated credentials to be validated
-        """
-        creds = UnvalidatedTokens.from_dict(unvalidated_creds)
-        idt_body: Optional[Dict] = None
+        Args:
+            unvalidated_tokens: tokens that have yet to be validated
 
-        try:
-            at_body = jwt.decode(
-                creds.access_token,
-                options={"verify_signature": False},
-            )
+        Returns:
+            this auth flow
 
-            if creds.id_token:
-                idt_body = jwt.decode(
-                    creds.id_token,
-                    options={"verify_signature": False},
-                )
-        except Exception as e:
-            logger.error("Invalid tokens", exc_info=e)
-            raise
+        Raises:
+            pydantic.ValidationError: the token's body could not be decoded
+        """
 
-        self._access_token_body = at_body
-        self._id_token_body = idt_body
-        self._tokens = ValidTokens.from_unvalidated(
-            creds=creds,
-            body=at_body,
-        )
-        self.token_scope = self._tokens.scope
+        tokens = Tokens.model_validate(unvalidated_tokens)
+
+        self._access_token_body = tokens.access_token_body
+        self._tokens = tokens
 
         return self
 
-    def get_access_token_refresh_if_necessary(self, no_auto_refresh: bool = False, auto_refresh_threshold: int = 3600):
+    ##########
+    # The following methods make this class compatible with httpx.Auth.
+    ##########
+
+    async def async_auth_flow(self, request: httpx.Request):
+        """
+        Injects authorization into the request
+
+        (this method makes this class httpx.Auth compatible)
         """
-        Retrieve the access token. Automatically refreshes the token when necessary.
+        super().async_auth_flow
+        if request.headers.get("authorization") is None:
+            if self._settings.is_host_allowed(request.url.host):
+                await self.async_refresh_if_necessary()
+                access_token = self.access_token
+                request.headers["authorization"] = f"Bearer {access_token}"
 
-        Parameters
-        ___________
-        no_auto_refresh: bool, optional
-            Disable automatic token refresh. The default behavior is to automatically attempt to refresh the token if it can be refreshed and there is less than 1 hour before the token expires (default is False)
-        auto_refresh_threshold: int, optional
-            The amount of time remaining (in seconds) before token expiration after which a refresh is automatically attempted (default is 3600)
+        yield request
+
+    def sync_auth_flow(self, request: httpx.Request):
+        """
+        Injects authorization into the request
 
-        Return
-        ________
-        access_token: str
+        (this method makes this class httpx.Auth compatible)
         """
+        # NOTE: we explicitly redefine this sync method because ctx.syncify()
+        # does not support generators
+        if request.headers.get("authorization") is None:
+            if self._settings.is_host_allowed(request.url.host):
+                self.refresh_if_necessary()
+                access_token = self.access_token
+                request.headers["authorization"] = f"Bearer {access_token}"
 
-        self.load_tokens()
-        if (
-                not no_auto_refresh
-                and self.ttl < dt.timedelta(seconds=auto_refresh_threshold)
-        ):
-            try:
-                self.refresh()
-            except InvalidRefreshTokenError:
-                raise InvalidRefreshTokenError("Unable to refresh because the refresh token is not valid. Use 'no-auto-refresh' option to get token anyway. To resolve, re-authenticate")
-        return self.access_token
+        yield request