auth0-api-python 1.0.0b10__py3-none-any.whl → 1.0.0b11__py3-none-any.whl

auth0_api_python/__init__.py

@@ -11,11 +11,25 @@ from .cache import CacheAdapter, InMemoryCache
 from .config import ApiClientOptions
 from .errors import (
     ApiError,
+    AuthServerUnavailableError,
     ConfigurationError,
     DomainsResolverError,
+    GetAccessTokenForConnectionError,
+    GetClientCredentialsTokenError,
     GetTokenByExchangeProfileError,
+    MissingOrganizationError,
+    OrganizationNotAllowedError,
+    VerifyAccessTokenError,
+)
+from .token_store import (
+    AbstractTokenStore,
+    IndexedTokenStore,
+    TokenIndexMember,
+    TokenSet,
+    VerifiedToken,
 )
 from .types import (
+    ClientCredentialsTokenResult,
     DomainsResolver,
     DomainsResolverContext,
     OnBehalfOfTokenResult,
@@ -25,14 +39,26 @@ __all__ = [
     "ApiClient",
     "ApiClientOptions",
     "ApiError",
+    "AuthServerUnavailableError",
     "CacheAdapter",
+    "ClientCredentialsTokenResult",
     "ConfigurationError",
     "DomainsResolver",
     "DomainsResolverContext",
     "DomainsResolverError",
+    "GetAccessTokenForConnectionError",
+    "GetClientCredentialsTokenError",
     "GetTokenByExchangeProfileError",
+    "VerifyAccessTokenError",
     "get_current_actor",
     "get_delegation_chain",
     "InMemoryCache",
+    "MissingOrganizationError",
+    "AbstractTokenStore",
+    "IndexedTokenStore",
+    "TokenIndexMember",
+    "VerifiedToken",
     "OnBehalfOfTokenResult",
+    "OrganizationNotAllowedError",
+    "TokenSet",
 ]

auth0_api_python/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal machinery for auth0-api-python. Not part of the public API."""

auth0_api_python/_internal/cache_expiry.py

@@ -0,0 +1,9 @@
+"""Freshness rule shared by every cache of a token the SDK minted."""
+
+# A token this close to expiry is treated as expired, so it is unlikely to lapse before the caller uses it.
+EXPIRY_BUFFER_SECONDS = 30
+
+
+def is_fresh(expires_at: int, now: int) -> bool:
+    """True when a cached token still has more than the expiry buffer left."""
+    return expires_at - EXPIRY_BUFFER_SECONDS > now

auth0_api_python/_internal/cache_keys.py

@@ -0,0 +1,147 @@
+"""Cache-key builders and scope helpers for the tokens the SDK mints."""
+
+import hashlib
+
+from ..utils import get_unverified_payload
+
+_FIELD_SEPARATOR = "\x1f"
+
+
+def _normalized_scopes(scope: str | None) -> str:
+    """Sort and dedupe scopes so equivalent scope strings produce the same cache key."""
+    if not scope:
+        return ""
+    return " ".join(sorted(set(scope.split())))
+
+
+def is_covered_by(requested: str | None, granted: str | None) -> bool:
+    """True when the requested scopes are all covered by the granted scopes."""
+    granted_set = set(_normalized_scopes(granted).split())
+    requested_set = set(_normalized_scopes(requested).split())
+    return requested_set.issubset(granted_set)
+
+
+def session_fingerprint(access_token: str) -> str:
+    """
+    Derive a session-scoped fingerprint for an access token, to keep concurrent
+    sessions' cached tokens from colliding. Not a trust or authorization signal:
+    the token is decoded without signature verification.
+    """
+    try:
+        payload = get_unverified_payload(access_token)
+    except ValueError:
+        return hashlib.sha256(access_token.encode()).hexdigest()
+
+    sid = payload.get("sid")
+    if isinstance(sid, str) and sid:
+        return sid
+
+    jti = payload.get("jti")
+    if isinstance(jti, str) and jti:
+        return jti
+
+    return hashlib.sha256(access_token.encode()).hexdigest()
+
+
+def _obo_identity_fields(
+    namespace: str,
+    *,
+    issuer: str,
+    incoming_client_id: str,
+    exchange_tenant: str,
+    exchange_client_id: str,
+    audience: str,
+    org_id: str | None,
+    session_key: str,
+) -> list[str]:
+    """The fields every OBO cache key shares, namespaced by key kind.
+
+    Folds in the verified issuer, the incoming token's client, the exchange tenant, and the
+    exchange client so a token minted under one of them is never read back under another.
+    """
+    return [
+        namespace,
+        issuer,
+        incoming_client_id,
+        exchange_tenant,
+        exchange_client_id,
+        audience,
+        org_id or "",
+        session_key,
+    ]
+
+
+def obo_cache_key(
+    *,
+    layout: str,
+    sub: str,
+    issuer: str,
+    incoming_client_id: str,
+    exchange_tenant: str,
+    exchange_client_id: str,
+    audience: str,
+    org_id: str | None,
+    scopes: str | None,
+    session_key: str,
+) -> str:
+    """Token cache key for an On Behalf Of exchange.
+
+    layout is "strict" or "index" so the two scope-matching modes never read each other's tokens.
+    The normalized scopes are folded in.
+    """
+    fields = _obo_identity_fields(
+        "obo_token_" + layout,
+        issuer=issuer,
+        incoming_client_id=incoming_client_id,
+        exchange_tenant=exchange_tenant,
+        exchange_client_id=exchange_client_id,
+        audience=audience,
+        org_id=org_id,
+        session_key=session_key,
+    )
+    fields.append(_normalized_scopes(scopes))
+    return sub + ":" + hashlib.sha256(_FIELD_SEPARATOR.join(fields).encode()).hexdigest()
+
+
+def index_cache_key(
+    *,
+    sub: str,
+    issuer: str,
+    incoming_client_id: str,
+    exchange_tenant: str,
+    exchange_client_id: str,
+    audience: str,
+    org_id: str | None,
+    session_key: str,
+) -> str:
+    """Cache key for the OBO token index, scoped to caller, issuer, exchange, audience, org, and session.
+
+    The "obo_index" namespace keeps it from colliding with either layout's token cache key.
+    """
+    fields = _obo_identity_fields(
+        "obo_index",
+        issuer=issuer,
+        incoming_client_id=incoming_client_id,
+        exchange_tenant=exchange_tenant,
+        exchange_client_id=exchange_client_id,
+        audience=audience,
+        org_id=org_id,
+        session_key=session_key,
+    )
+    return sub + ":" + hashlib.sha256(_FIELD_SEPARATOR.join(fields).encode()).hexdigest()
+
+
+def m2m_cache_key(*, tenant: str, client_id: str, audience: str, scopes: str | None) -> str:
+    """Cache key for a client-credentials (M2M) exchange, scoped to tenant, client, audience, and scopes."""
+    fields = _FIELD_SEPARATOR.join(
+        ["m2m", tenant, client_id, audience, _normalized_scopes(scopes)]
+    )
+    return hashlib.sha256(fields.encode()).hexdigest()
+
+
+def token_vault_cache_key(
+    *, sub: str, connection: str, tenant: str, client_id: str, login_hint: str | None = None
+) -> str:
+    """Cache key for a Token Vault exchange, scoped to tenant, client, caller, connection, and login hint."""
+    fields = _FIELD_SEPARATOR.join(["token_vault", tenant, client_id, sub, connection, login_hint or ""])
+    return hashlib.sha256(fields.encode()).hexdigest()

auth0_api_python/_internal/obo_cache.py

@@ -0,0 +1,229 @@
+"""Caching for On Behalf Of exchanges: cache-key identity, lookup, and write."""
+
+import logging
+import time
+from typing import NamedTuple, cast
+
+from ..token_store import (
+    AbstractTokenStore,
+    IndexedTokenStore,
+    TokenSet,
+    VerifiedToken,
+)
+from ..types import OnBehalfOfTokenResult
+from .cache_expiry import is_fresh
+from .cache_keys import (
+    _normalized_scopes,
+    index_cache_key,
+    is_covered_by,
+    obo_cache_key,
+    session_fingerprint,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _OboIdentity(NamedTuple):
+    """The verified fields that identify one caller's OBO cache entries."""
+
+    sub: str
+    issuer: str
+    incoming_client_id: str
+    org_id: str | None
+    session_key: str
+
+
+class OboCache:
+    """Caches On Behalf Of exchange results in a token store, keyed by verified caller identity.
+
+    scope_matching controls reuse. "strict" reuses a cached token only when its granted scopes
+    equal the request. "non_strict" reuses any cached token whose granted scopes cover the
+    request, which needs the per-caller index and so an IndexedTokenStore.
+    """
+
+    def __init__(
+        self,
+        token_store: AbstractTokenStore,
+        *,
+        exchange_tenant: str,
+        exchange_client_id: str,
+        scope_matching: str,
+    ) -> None:
+        self._store = token_store
+        self._exchange_tenant = exchange_tenant
+        self._exchange_client_id = exchange_client_id
+        self._mode = scope_matching
+
+    def identity(self, verified: VerifiedToken) -> _OboIdentity | None:
+        """Build the cache identity from verified claims, or None when they lack a usable subject."""
+        claims = verified.claims
+        sub = claims.get("sub")
+        if not isinstance(sub, str) or not sub:
+            logger.warning("Verified token has no usable sub claim, skipping cache")
+            return None
+        issuer = claims.get("iss")
+        if not isinstance(issuer, str) or not issuer:
+            logger.warning("Verified token has no iss claim, skipping cache")
+            return None
+        org_id = claims.get("org_id") if isinstance(claims.get("org_id"), str) else None
+        incoming = claims.get("azp") or claims.get("client_id")
+        incoming_client_id = incoming if isinstance(incoming, str) else ""
+        return _OboIdentity(
+            sub=sub,
+            issuer=issuer,
+            incoming_client_id=incoming_client_id,
+            org_id=org_id,
+            session_key=session_fingerprint(verified.access_token),
+        )
+
+    async def lookup(
+        self, identity: _OboIdentity, audience: str, scope: str | None
+    ) -> OnBehalfOfTokenResult | None:
+        """Return a reusable cached token for this request, or None on a miss."""
+        if self._mode == "non_strict":
+            return await self._index_lookup(identity, audience, scope)
+        return await self._strict_lookup(identity, audience, scope)
+
+    async def write(
+        self,
+        identity: _OboIdentity,
+        audience: str,
+        scope: str | None,
+        obo_result: OnBehalfOfTokenResult,
+    ) -> None:
+        """Store a freshly exchanged token under its granted scopes."""
+        # When Auth0 does not echo the granted scope, the requested scope is the best label available.
+        granted = _normalized_scopes(obo_result["scope"] if "scope" in obo_result else scope)
+        entry: TokenSet = {
+            "access_token": obo_result["access_token"],
+            "expires_at": obo_result["expires_at"],
+            "granted_scopes": granted,
+        }
+        try:
+            if self._mode == "non_strict":
+                token_key = self._token_key(identity, audience, "index", granted)
+                await self._store.set(token_key, entry)
+                await cast(IndexedTokenStore, self._store).add_index_member(
+                    self._index_key(identity, audience),
+                    {"token_key": token_key, "granted_scopes": granted, "expires_at": obo_result["expires_at"]},
+                )
+            else:
+                await self._store.set(self._token_key(identity, audience, "strict", granted), entry)
+        except Exception as exc:
+            logger.warning("Token store write failed, token still returned: %s", exc)
+
+    # ===== Private methods =====
+
+    def _token_key(self, identity: _OboIdentity, audience: str, layout: str, scopes: str | None) -> str:
+        return obo_cache_key(
+            layout=layout,
+            sub=identity.sub,
+            issuer=identity.issuer,
+            incoming_client_id=identity.incoming_client_id,
+            exchange_tenant=self._exchange_tenant,
+            exchange_client_id=self._exchange_client_id,
+            audience=audience,
+            org_id=identity.org_id,
+            scopes=scopes,
+            session_key=identity.session_key,
+        )
+
+    def _index_key(self, identity: _OboIdentity, audience: str) -> str:
+        return index_cache_key(
+            sub=identity.sub,
+            issuer=identity.issuer,
+            incoming_client_id=identity.incoming_client_id,
+            exchange_tenant=self._exchange_tenant,
+            exchange_client_id=self._exchange_client_id,
+            audience=audience,
+            org_id=identity.org_id,
+            session_key=identity.session_key,
+        )
+
+    @staticmethod
+    def _warn_read_failed(exc: Exception) -> None:
+        # A bad secret or tampered entry fails inside the store's decrypt, so it surfaces here too.
+        logger.warning("Token store read failed or entry was unreadable, treating as cache miss: %s", exc)
+
+    @staticmethod
+    def _well_formed_member(member: object) -> bool:
+        """True when an index member has the fields the lookup reads, so a malformed one is a miss."""
+        return (
+            isinstance(member, dict)
+            and isinstance(member.get("token_key"), str)
+            and isinstance(member.get("granted_scopes"), str)
+            and isinstance(member.get("expires_at"), int)
+        )
+
+    @staticmethod
+    def _usable_entry(cached: TokenSet | None, now: int) -> bool:
+        if cached is None:
+            return False
+        if "access_token" not in cached or "expires_at" not in cached:
+            logger.warning("Token store returned a malformed entry, treating as cache miss")
+            return False
+        return is_fresh(cached["expires_at"], now)
+
+    @staticmethod
+    def _hit(cached: TokenSet, now: int) -> OnBehalfOfTokenResult:
+        result: OnBehalfOfTokenResult = {
+            "access_token": cached["access_token"],
+            "expires_in": cached["expires_at"] - now,
+            "expires_at": cached["expires_at"],
+        }
+        granted = cached.get("granted_scopes")
+        if granted is not None:
+            result["scope"] = granted
+        return result
+
+    async def _strict_lookup(
+        self, identity: _OboIdentity, audience: str, scope: str | None
+    ) -> OnBehalfOfTokenResult | None:
+        now = int(time.time())
+        try:
+            cached = await self._store.get(self._token_key(identity, audience, "strict", scope))
+        except Exception as exc:
+            self._warn_read_failed(exc)
+            return None
+        if not self._usable_entry(cached, now):
+            return None
+        # Entries are stored under their granted-scope key, so confirm the grant matches exactly.
+        if _normalized_scopes(cached.get("granted_scopes")) != _normalized_scopes(scope):
+            return None
+        return self._hit(cached, now)
+
+    async def _index_lookup(
+        self, identity: _OboIdentity, audience: str, scope: str | None
+    ) -> OnBehalfOfTokenResult | None:
+        # An unscoped request is covered by every cached token, so never reuse for one.
+        requested_scopes = _normalized_scopes(scope)
+        if not requested_scopes:
+            return None
+        now = int(time.time())
+        indexed = cast(IndexedTokenStore, self._store)
+        try:
+            members = await indexed.list_index_members(self._index_key(identity, audience))
+            candidates = [
+                m for m in members
+                if self._well_formed_member(m) and is_fresh(m["expires_at"], now) and is_covered_by(scope, m["granted_scopes"])
+            ]
+        except Exception as exc:
+            self._warn_read_failed(exc)
+            return None
+        requested = set(requested_scopes.split())
+        # Prefer an exact grant, then the covering grant with the fewest extra scopes.
+        candidates.sort(key=lambda m: len(set(_normalized_scopes(m["granted_scopes"]).split()) - requested))
+        for member in candidates:
+            # A failing store would fail every remaining read too, so stop at the first one.
+            try:
+                cached = await self._store.get(member["token_key"])
+            except Exception as exc:
+                self._warn_read_failed(exc)
+                return None
+            if not self._usable_entry(cached, now):
+                continue
+            # Trust the token value's own grant, not only the index label.
+            if not is_covered_by(scope, cached.get("granted_scopes")):
+                continue
+            return self._hit(cached, now)
+        return None

auth0_api_python/_internal/token_vault_cache.py

@@ -0,0 +1,72 @@
+"""Caching for Token Vault (federated connection) exchanges: lookup and write."""
+
+import logging
+import time
+from typing import Any
+
+from ..token_store import AbstractTokenStore, TokenSet
+from .cache_expiry import is_fresh
+from .cache_keys import _normalized_scopes, token_vault_cache_key
+
+logger = logging.getLogger(__name__)
+
+
+class TokenVaultCache:
+    """Caches Token Vault exchange results in a token store, keyed by caller and connection.
+
+    ApiClient builds one TokenVaultCache when a token_store is configured and delegates
+    every cache decision to it.
+    """
+
+    def __init__(self, token_store: AbstractTokenStore) -> None:
+        self._store = token_store
+
+    def cache_key(
+        self, tenant: str, client_id: str, sub: Any, connection: str, login_hint: str | None = None
+    ) -> str | None:
+        """Return the cache key, or None when sub is not a usable string (cache skipped with a warning)."""
+        if not isinstance(sub, str) or not sub:
+            logger.warning("Access token has no usable sub claim, skipping Token Vault cache")
+            return None
+        return token_vault_cache_key(
+            sub=sub, connection=connection, tenant=tenant, client_id=client_id, login_hint=login_hint
+        )
+
+    async def lookup(self, key: str) -> dict | None:
+        """Return a live cached token or None. Miss cases: absent, malformed, expired."""
+        cached: TokenSet | None = None
+        try:
+            cached = await self._store.get(key)
+        except Exception as exc:
+            logger.warning("Token store read failed, treating as cache miss: %s", exc)
+            return None
+
+        if cached is None:
+            return None
+        access_token = cached.get("access_token")
+        expires_at = cached.get("expires_at")
+        if not isinstance(access_token, str) or not access_token or not isinstance(expires_at, int):
+            logger.warning("Token store returned a malformed entry, treating as cache miss")
+            return None
+        now = int(time.time())
+        if not is_fresh(expires_at, now):
+            return None
+
+        return {
+            "access_token": access_token,
+            "expires_in": expires_at - now,
+            "expires_at": expires_at,
+            "scope": cached.get("granted_scopes") or "",
+        }
+
+    async def write(self, key: str, result: dict) -> None:
+        """Store a freshly exchanged connection token. Failures are logged and swallowed."""
+        entry: TokenSet = {
+            "access_token": result["access_token"],
+            "expires_at": result["expires_at"],
+            "granted_scopes": _normalized_scopes(result.get("scope")),
+        }
+        try:
+            await self._store.set(key, entry)
+        except Exception as exc:
+            logger.warning("Token store write failed, token still returned: %s", exc)

auth0_api_python/act.py

@@ -3,14 +3,14 @@ Helpers for working with the `act` claim on verified access token claims.
 """
 
 from collections.abc import Mapping
-from typing import Any, Optional
+from typing import Any
 
 from .errors import VerifyAccessTokenError
 
 INVALID_ACT_CLAIM_MESSAGE = "Invalid act claim"
 
 
-def get_current_actor(claims: Mapping[str, Any]) -> Optional[str]:
+def get_current_actor(claims: Mapping[str, Any]) -> str | None:
     """
     Return the current actor from the outermost `act.sub`, if present.