chore: trimmed comments

Author: rmad17

src/auth0_server_python/auth_server/anonymous_client.py

@@ -199,7 +199,6 @@ def _map_anonymous_error(
 
         if code in ("session_expired", "invalid_session_token"):
             return _AnonymousSessionExpired(description)
-        # Distinguishes DPoP-mandated clients from a plain client-not-enabled block.
         if status_code == 400 and "Proof-of-Possession" in description:
             return AnonymousClientNotSupportedError(description, error_data)
         if code == "feature_not_enabled":
@@ -273,10 +272,6 @@ def _encrypt_context(self, context: AnonymousSessionContext) -> str:
     def _decrypt_context(self, stored: Any) -> AnonymousSessionContext:
         """Decrypt and validate a stored anonymous session record.
 
-        A crypto-library failure and a validation failure both mean the
-        record is unusable, and both must convert to the same internal
-        signal instead of an untyped exception reaching the caller.
-
         Args:
             stored: The raw record read from the anonymous store.
 
@@ -313,8 +308,6 @@ async def _create_session_at(
     ) -> AnonymousSession:
         """Create a fresh anonymous session against a resolved domain.
 
-        Shared by create_session() and every renewal-ladder fallback.
-
         Args:
             domain: The resolved tenant domain.
             audience: Audience for the new session, or None.
@@ -344,9 +337,7 @@ async def _create_session_at(
             try:
                 response = await client.post(f"{base_url}/anonymous/token", json=body)
             except httpx.HTTPError as e:
-                raise AnonymousCreateError(
-                    "Failed to reach the anonymous token endpoint"
-                ) from e
+                raise AnonymousCreateError("Failed to reach the anonymous token endpoint") from e
 
             if response.status_code != 200:
                 error_data = self._parse_anonymous_error_body(response)
@@ -359,9 +350,7 @@ async def _create_session_at(
             try:
                 token_response = AnonymousTokenResponse.model_validate(response.json())
             except (json.JSONDecodeError, ValueError, ValidationError) as e:
-                raise AnonymousCreateError(
-                    "Failed to parse anonymous token response"
-                ) from e
+                raise AnonymousCreateError("Failed to parse anonymous token response") from e
 
         if not token_response.session_token:
             raise AnonymousCreateError("Anonymous token response missing required fields")
@@ -408,9 +397,6 @@ async def _remint(
     ) -> AnonymousSession:
         """Re-mint an access token using the stored session token.
 
-        Retries once by minting a brand-new session if the stored session
-        token is itself rejected as expired or invalid.
-
         Args:
             context: The current decrypted session context.
             store_options: Options passed to the anonymous store.
@@ -425,7 +411,10 @@ async def _remint(
         """
         domain = context.domain or await self._resolve_domain(store_options)
         base_url = f"https://{domain}"
-        body: dict[str, Any] = {"client_id": self._client_id, "session_token": context.session_token}
+        body: dict[str, Any] = {
+            "client_id": self._client_id,
+            "session_token": context.session_token,
+        }
         if self._client_secret:
             body["client_secret"] = self._client_secret
 
@@ -456,7 +445,6 @@ async def _remint(
 
         now = int(time.time())
         new_context = AnonymousSessionContext(
-            # Rewrite when a fresh session_token is present, else keep the old one.
             session_token=token_response.session_token or context.session_token,
             sub=token_response.sub or context.sub,
             session_id=token_response.session_id or context.session_id,
@@ -495,18 +483,14 @@ async def _remint(
     async def get_session_token_for_injection(
         self, store_options: Optional[dict[str, Any]] = None
     ) -> Optional[str]:
-        """Read the active session token for login injection.
-
-        Does not trigger the renewal ladder. Never raises: no configured
-        store, no active session, and an undecryptable record all return
-        None, so malformed linking state denies the link instead of
-        aborting the login.
+        """Read the active session token for login injection without renewing.
 
         Args:
             store_options: Options passed to the anonymous store.
 
         Returns:
-            The raw session token, or None.
+            The raw session token, or None when there is no store, no active
+            session, or the stored record cannot be decrypted.
         """
         if self._anonymous_store is None:
             return None
@@ -577,16 +561,9 @@ async def create_session(
             domain, audience=audience, scope=scope, metadata=metadata, store_options=store_options
         )
 
-    async def get_token(
-        self, store_options: Optional[dict[str, Any]] = None
-    ) -> AnonymousSession:
+    async def get_token(self, store_options: Optional[dict[str, Any]] = None) -> AnonymousSession:
         """Return a valid anonymous access token, renewing or re-minting as needed.
 
-        The renewal ladder: a fresh cached token is returned as-is. An
-        expired one is re-minted from the stored session token. A session
-        token that is itself expired or invalid silently mints a brand-new
-        session, once. Any other error is raised, never swallowed or retried.
-
         Args:
             store_options: Options passed to the anonymous store.
 
@@ -606,7 +583,6 @@ async def get_token(
         try:
             context = self._decrypt_context(stored)
         except _AnonymousSessionExpired:
-            # No audience/scope to recover, fall back to configured defaults.
             domain = await self._resolve_domain(store_options)
             return await self._create_session_at(
                 domain,
@@ -648,11 +624,7 @@ async def get_token(
     async def introspect(
         self, store_options: Optional[dict[str, Any]] = None
     ) -> AnonymousSessionIntrospection:
-        """Return the current anonymous session status without mutating it.
-
-        Never triggers the renewal ladder and never writes to the store. An
-        unreadable stored context is a hard failure here, not a silent
-        re-mint. Uses the cached access token as a Bearer credential.
+        """Return the current anonymous session status without mutating the store.
 
         Args:
             store_options: Options passed to the anonymous store.
@@ -706,12 +678,7 @@ async def introspect(
                 ) from e
 
     async def logout(self, store_options: Optional[dict[str, Any]] = None) -> None:
-        """Clear the locally-held anonymous session.
-
-        No server-side revocation exists: access tokens already issued
-        remain valid until natural expiry. The remote POST is best-effort
-        only. The local store clear is what actually ends the session from
-        this SDK's perspective.
+        """Clear the locally-held anonymous session without revoking issued tokens.
 
         Args:
             store_options: Options passed to the anonymous store.

src/auth0_server_python/auth_server/server_client.py

@@ -225,7 +225,7 @@ def __init__(
             headers=self._telemetry_headers,
         )
 
-        # Deliberately given its own store, never self._state_store.
+        # Its own store, never self._state_store, so anonymous state stays isolated.
         self._anonymous_client = AnonymousClient(
             domain=domain,
             client_id=self._client_id,
@@ -568,11 +568,9 @@ async def start_interactive_login(
         if options.invitation:
             auth_params["invitation"] = options.invitation
 
-        # session_token is sourced only from the SDK's own encrypted anonymous
-        # store, never from a caller. INTERNAL_AUTHORIZE_PARAMS alone isn't
-        # enough, since auth_params is seeded unfiltered from the constructor
-        # defaults above, so a caller-supplied value would survive that filter.
-        # Suppressed entirely on the PAR branch below (unsupported there).
+        # session_token comes only from the SDK's own encrypted anonymous
+        # store, never a caller. The pop strips any value seeded from the
+        # constructor defaults, closing a session-fixation vector.
         auth_params.pop("session_token", None)
         anonymous_session_token = None
         if not self._pushed_authorization_requests:

src/auth0_server_python/auth_types/__init__.py

@@ -871,14 +871,8 @@ class PasskeyTokenResponse(BaseModel):
 
 
 class AnonymousSession(BaseModel):
-    """
-    Public result of create_session() / the renewal ladder.
-
-    Never exposes the raw session token, which stays inside the encrypted
-    AnonymousSessionContext, server-side only.
-    """
+    """Public result of create_session() and the renewal ladder."""
 
-    # Optional: the platform's /anonymous/token response doesn't always include these.
     sub: Optional[str] = None
     session_id: Optional[str] = None
     access_token: str
@@ -889,11 +883,7 @@ class AnonymousSession(BaseModel):
 
 
 class AnonymousSessionIntrospection(BaseModel):
-    """
-    Result of introspect(). Deliberately minimal and lenient, since the
-    platform's /anonymous/userinfo response shape is unconfirmed.
-    Unrecognized fields are ignored rather than rejected.
-    """
+    """Result of introspect(), lenient to unrecognized response fields."""
 
     model_config = ConfigDict(extra="ignore")
     sub: str
@@ -915,25 +905,21 @@ class AnonymousTokenResponse(BaseModel):
 
 
 class AnonymousSessionContext(BaseModel):
-    """
-    Internal context stored inside the encrypted anonymous session record.
+    """Internal context stored inside the encrypted anonymous session record.
 
-    No `extra` config, so decrypt fails closed on a tampered or malformed
-    payload rather than silently yielding a partial object.
+    Rejects extra fields so a tampered payload fails closed on decrypt.
     """
 
     session_token: str
-    # sub/session_id: optional for the same reason as AnonymousSession above.
     sub: Optional[str] = None
     session_id: Optional[str] = None
     access_token: str
     expires_at: int
     session_expires_at: Optional[int] = None
     metadata: Optional[dict[str, Any]] = None
     created_at: int
-    # Resolved domain at creation time. Gated on in resolver/MCD mode so a
-    # session minted against tenant A cannot be read back for tenant B.
-    # None when the client uses a static domain.
+    # Resolved domain at creation, gated on in resolver/MCD mode so a session
+    # minted for one tenant cannot be read back for another.
     domain: Optional[str] = None
     audience: Optional[str] = None
     scope: Optional[str] = None

src/auth0_server_python/error/__init__.py

@@ -404,12 +404,7 @@ def __init__(self, message: str, cause: Optional[dict] = None):
 
 
 class AnonymousIntrospectError(AnonymousApiError):
-    """
-    Error thrown when introspect() fails.
-
-    Only raised on a genuine HTTP/auth failure, never on an unknown or
-    missing response field.
-    """
+    """Error thrown when introspect() fails on an HTTP or auth failure."""
 
     def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__("anonymous_introspect_error", message, cause)
@@ -451,10 +446,9 @@ def __init__(self, message: str, cause: Optional[dict] = None):
 
 
 class _AnonymousSessionExpired(Auth0Error):
-    """
-    Internal-only signal that the stored session token is expired or invalid.
+    """Internal-only signal that the stored session token is expired or invalid.
 
-    Drives the silent re-mint in the renewal ladder. Never raised to SDK callers.
+    Never raised to SDK callers.
     """
 
     def __init__(self, message: str = "The anonymous session token is expired or invalid."):