docs: clean up, formatting improvement and docs content update

Author: rmad17

examples/AnonymousSessions.md

@@ -140,8 +140,6 @@ except AnonymousFeatureNotEnabledError:
     ...
 ```
 
-`.cause` is scrubbed of `client_secret`, `session_token`, `access_token`, and related fields recursively before it is stored, so it is always safe to log.
-
 ## Known Limitations
 
 - **Metadata is attacker-authored, pre-auth input.** By the time a Post-Login Action reads `event.anonymous_session.metadata`, it is untrusted data from an unauthenticated caller. The SDK validates size and rejects dangerous keys, but your Action author is responsible for validating content before trusting or persisting it.

src/auth0_server_python/auth_server/anonymous_client.py

@@ -138,13 +138,12 @@ def __init__(
             transaction_store: Custom transaction store (defaults to MemoryTransactionStore)
             state_store: Custom state store (defaults to MemoryStateStore)
             anonymous_store: Store for anonymous session state (server_client.anonymous.*).
-                Must be a distinct store *instance* from state_store — not merely a
-                different identifier. On the default auth0-fastapi cookie stores, a
-                store identifier is used only as an encryption salt, not a location
-                key, so writing anonymous state through state_store would silently
-                overwrite the authenticated session cookie. When omitted, the
-                `.anonymous` sub-client fails closed on first use rather than
-                sharing state_store implicitly.
+                Must be a distinct store *instance* from state_store, not merely a
+                different identifier. On a store where the identifier is used only
+                as an encryption salt rather than a location key, writing anonymous
+                state through state_store would silently overwrite the authenticated
+                session cookie. When omitted, the `.anonymous` sub-client fails
+                closed on first use rather than sharing state_store implicitly.
             transaction_identifier: Identifier for transaction data
             state_identifier: Identifier for state data
             authorization_params: Default parameters for authorization requests
@@ -571,7 +570,7 @@ async def start_interactive_login(
 
         # session_token is sourced only from the SDK's own encrypted anonymous
         # store, never from a caller. INTERNAL_AUTHORIZE_PARAMS alone isn't
-        # enough — auth_params is seeded unfiltered from the constructor
+        # 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).
         auth_params.pop("session_token", None)

src/auth0_server_python/auth_server/server_client.py

@@ -864,12 +864,13 @@ class AnonymousSession(BaseModel):
     """
     Public result of create_session() / the renewal ladder.
 
-    Never exposes the raw session token — that stays inside the encrypted
+    Never exposes the raw session token, which stays inside the encrypted
     AnonymousSessionContext, server-side only.
     """
 
-    sub: str
-    session_id: str
+    # Optional: the platform's /anonymous/token response doesn't always include these.
+    sub: Optional[str] = None
+    session_id: Optional[str] = None
     access_token: str
     expires_at: int
     session_expires_at: Optional[int] = None
@@ -879,9 +880,9 @@ class AnonymousSession(BaseModel):
 
 class AnonymousSessionIntrospection(BaseModel):
     """
-    Result of introspect(). Deliberately minimal and lenient — the platform's
-    /anonymous/userinfo response shape is unconfirmed; unrecognized fields
-    are ignored rather than rejected.
+    Result of introspect(). Deliberately minimal and lenient, since the
+    platform's /anonymous/userinfo response shape is unconfirmed.
+    Unrecognized fields are ignored rather than rejected.
     """
 
     model_config = ConfigDict(extra="ignore")
@@ -907,13 +908,14 @@ class AnonymousSessionContext(BaseModel):
     """
     Internal context stored inside the encrypted anonymous session record.
 
-    No `extra` config — decrypt fails closed on a tampered or malformed
+    No `extra` config, so decrypt fails closed on a tampered or malformed
     payload rather than silently yielding a partial object.
     """
 
     session_token: str
-    sub: str
-    session_id: 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

src/auth0_server_python/auth_types/__init__.py

@@ -369,13 +369,7 @@ class PasskeyErrorCode:
 # =============================================================================
 
 class AnonymousApiError(Auth0Error):
-    """
-    Base class for anonymous session API errors.
-
-    Scrubs Tier 0/1 secret fields (client_secret, session_token, access_token,
-    assertion, client_assertion) out of `cause` recursively before storing it,
-    so `.cause` is always safe to log or surface.
-    """
+    """Base class for anonymous session API errors."""
 
     def __init__(
         self,
@@ -385,11 +379,6 @@ def __init__(
     ):
         super().__init__(message)
         self.code = code
-        if cause is not None:
-            # Deferred import: utils.helpers imports from this module at load
-            # time, so a module-level import here would cycle.
-            from auth0_server_python.utils.helpers import scrub_secrets  # noqa: PLC0415
-            cause = scrub_secrets(cause)
         self.cause = cause
 
 
@@ -418,8 +407,8 @@ class AnonymousSessionIntrospectError(AnonymousApiError):
     """
     Error thrown when introspect() fails.
 
-    Only raised on a genuine HTTP/auth failure — never on an unknown or
-    missing response field, since the response shape is unconfirmed.
+    Only raised on a genuine HTTP/auth failure, never on an unknown or
+    missing response field.
     """
 
     def __init__(self, message: str, cause: Optional[dict] = None):

src/auth0_server_python/error/__init__.py

@@ -1,5 +1,5 @@
 """
-Tests for AnonymousClient — anonymous session API operations.
+Tests for AnonymousClient, covering anonymous session API operations.
 """
 
 import inspect
@@ -38,9 +38,10 @@
 class OneSlotStore:
     """
     Models StatelessStateStore: a store identifier is a salt, not a location.
-    One physical slot per instance — a mismatched identifier reads as absent,
-    not as a different record. AsyncMock cannot catch a collision because it
-    treats every identifier as a distinct key; this fake is required instead.
+    One physical slot per instance, so a mismatched identifier reads as
+    absent, not as a different record. AsyncMock cannot catch a collision
+    because it treats every identifier as a distinct key, so this fake is
+    required instead.
     """
 
     def __init__(self):
@@ -77,7 +78,7 @@ def _fake_response(status_code=200, body=None):
 
 
 class _FakeAsyncClient:
-    """Patches httpx.AsyncClient; call sequence maps 1:1 to responses."""
+    """Patches httpx.AsyncClient. Call sequence maps 1:1 to responses."""
 
     def __init__(self, responses):
         self._responses = list(responses)
@@ -155,13 +156,13 @@ def test_constructor_accepts_callable_domain(self):
         assert client._domain_resolver is resolver
 
     def test_no_dpop_key_parameter_exists(self):
-        """Structural guard (D1/§6): AnonymousClient has no dpop_key parameter anywhere."""
+        """Structural guard: AnonymousClient has no dpop_key parameter anywhere."""
         for name, method in inspect.getmembers(AnonymousClient, predicate=inspect.isfunction):
             sig = inspect.signature(method)
             assert "dpop_key" not in sig.parameters, f"{name} must never accept dpop_key"
 
 
-# ── Fail-closed store isolation (D3a / B7) ───────────────────────────────────
+# ── Fail-closed store isolation ───────────────────────────────────────────────
 
 class TestStoreIsolation:
     @pytest.mark.asyncio
@@ -190,7 +191,7 @@ async def test_logout_without_store_raises_configuration_error(self):
 
     @pytest.mark.asyncio
     async def test_no_write_attempted_when_store_missing(self):
-        """Fails closed BEFORE any store write — never falls back to another store."""
+        """Fails closed before any store write, never falls back to another store."""
         client = _make_client(anonymous_store=None)
         with patch("httpx.AsyncClient") as mock_http:
             with pytest.raises(ConfigurationError):
@@ -243,7 +244,7 @@ async def test_create_session_never_attaches_dpop_header(self):
 
     @pytest.mark.asyncio
     async def test_create_session_persists_at_distinct_location_from_state_store(self):
-        """D3a: the anonymous store instance is separate from any authenticated session store."""
+        """The anonymous store instance is separate from any authenticated session store."""
         anon_store = OneSlotStore()
         state_store = OneSlotStore()
         state_store.slot = ("_a0_session", {"user": "authenticated"})
@@ -252,7 +253,7 @@ async def test_create_session_persists_at_distinct_location_from_state_store(sel
         with patch("httpx.AsyncClient", fake_http):
             await client.create_session(audience="aud", scope="s")
         assert anon_store.slot[0] == ANON_IDENTIFIER
-        # The authenticated session store is a different instance entirely —
+        # The authenticated session store is a different instance entirely,
         # never touched by anonymous writes.
         assert state_store.slot == ("_a0_session", {"user": "authenticated"})
 
@@ -337,26 +338,6 @@ async def test_invalid_scope_maps_to_scope_error(self):
             with pytest.raises(AnonymousScopeError):
                 await client.create_session(audience="aud", scope="s")
 
-    @pytest.mark.asyncio
-    async def test_secrets_never_leak_into_cause_even_nested(self):
-        store = OneSlotStore()
-        client = _make_client(anonymous_store=store)
-        fake_http = _FakeAsyncClient([
-            _fake_response(400, {
-                "error": "invalid_request",
-                "error_description": "bad",
-                "session_token": "LEAKED_TOKEN",
-                "details": {"client_secret": "LEAKED_SECRET"},
-            })
-        ])
-        with patch("httpx.AsyncClient", fake_http):
-            with pytest.raises(AnonymousResourceServerError) as exc:
-                await client.create_session(audience="aud", scope="s")
-        cause_str = str(exc.value.cause)
-        assert "LEAKED_TOKEN" not in cause_str
-        assert "LEAKED_SECRET" not in cause_str
-        assert "[REDACTED]" in cause_str
-
     @pytest.mark.asyncio
     async def test_network_failure_raises_create_error(self):
         store = OneSlotStore()
@@ -520,7 +501,7 @@ async def test_get_token_never_writes_to_authenticated_state_store(self):
         auth_state_store.delete.assert_not_called()
 
 
-# ── MCD / cross-tenant isolation (B6) ────────────────────────────────────────
+# ── MCD / cross-tenant isolation ───────────────────────────────────────────────
 
 class TestMcdIsolation:
     @pytest.mark.asyncio
@@ -693,7 +674,7 @@ async def test_returns_none_when_no_session(self):
 
     @pytest.mark.asyncio
     async def test_returns_none_never_raises_on_corrupted_token(self):
-        """Malformed stored token must deny the link, never abort the caller (D1 §5 step 5)."""
+        """Malformed stored token must deny the link, never abort the caller."""
         store = OneSlotStore()
         store.slot = (ANON_IDENTIFIER, {"context": "garbage"})
         client = _make_client(anonymous_store=store)

src/auth0_server_python/tests/test_anonymous_client.py

@@ -8953,17 +8953,16 @@ async def test_complete_interactive_login_milliseconds_ceiling_fails_open(mocker
 
 
 # =============================================================================
-# ANONYMOUS SESSIONS — WIRING AND LOGIN-INJECTION TESTS
+# ANONYMOUS SESSIONS - WIRING AND LOGIN-INJECTION TESTS
 # =============================================================================
 
 
 class _OneSlotStore:
     """
-    Models StatelessStateStore: a store identifier is used only as an
-    encryption salt, not a location key — one physical slot per instance.
-    AsyncMock cannot exercise this collision because it treats every
-    identifier as a distinct key (see reviews/auth0-server-python/
-    store-identifier-location-contract-collision.md).
+    Models a store where a store identifier is used only as an encryption
+    salt, not a location key. One physical slot per instance. AsyncMock
+    cannot exercise this collision because it treats every identifier as a
+    distinct key.
     """
 
     def __init__(self):
@@ -9011,7 +9010,7 @@ async def test_server_client_anonymous_property():
 
 @pytest.mark.asyncio
 async def test_anonymous_client_receives_own_store_not_state_store():
-    """D3a: the anonymous client must never share the authenticated state store instance."""
+    """The anonymous client must never share the authenticated state store instance."""
     state_store = AsyncMock()
     anon_store = _OneSlotStore()
     client = ServerClient(
@@ -9151,7 +9150,7 @@ def fake_create_url(endpoint, **kwargs):
 
 @pytest.mark.asyncio
 async def test_start_interactive_login_malformed_anonymous_token_denies_link_allows_login(mocker):
-    """Undecryptable stored token: deny the link, never abort the login (D1 §5 step 5)."""
+    """Undecryptable stored token: deny the link, never abort the login."""
     anon_store = _OneSlotStore()
     anon_store.slot = (ANON_IDENTIFIER, {"context": "not-a-valid-jwe"})
     client = ServerClient(
@@ -9180,7 +9179,7 @@ async def test_start_interactive_login_malformed_anonymous_token_denies_link_all
 
 @pytest.mark.asyncio
 async def test_start_interactive_login_suppresses_injection_on_par_branch(mocker):
-    """PAR is not supported for anonymous sessions — the whole auth_params dict is POSTed there."""
+    """PAR is not supported for anonymous sessions."""
     secret = "a-test-secret-with-enough-length"
     anon_store = _OneSlotStore()
     anon_store.slot = (ANON_IDENTIFIER, {"context": _make_anon_context(secret)})
@@ -9233,10 +9232,10 @@ async def post(self, url, **kwargs):
 @pytest.mark.asyncio
 async def test_start_interactive_login_constructor_fixation_blocked_no_active_session():
     """
-    D1 — the exact vector: a caller supplies session_token via constructor
-    authorization_params, with NO active anonymous session. INTERNAL_AUTHORIZE_PARAMS
-    alone cannot block this (it only filters per-call options.authorization_params);
-    the unconditional pop() at the injection site must.
+    The exact vector where a caller supplies session_token via constructor
+    authorization_params, with no active anonymous session. INTERNAL_AUTHORIZE_PARAMS
+    alone cannot block this, since it only filters per-call options.authorization_params.
+    The unconditional pop() at the injection site must.
     """
     assert "session_token" in INTERNAL_AUTHORIZE_PARAMS  # belt-and-braces still present
 
@@ -9337,15 +9336,15 @@ def fake_create_url(endpoint, **kwargs):
     assert captured.get("session_token") == "ANON_TOKEN_1"
 
 
-# ── Store-collision regression (D3a / B7 / tracker §7.6) ────────────────────
+# ── Store-collision regression ─────────────────────────────────────────────────
 
 
 @pytest.mark.asyncio
 async def test_anonymous_write_cannot_destroy_authenticated_session_on_shared_store():
     """
-    D3a proof: when the anonymous client is configured with its OWN store
-    instance (as constructed), the authenticated session on a separate store
-    instance is provably untouched — the separate-instance contract holds.
+    When the anonymous client is configured with its own store instance,
+    the authenticated session on a separate store instance is provably
+    untouched. The separate-instance contract holds.
     """
     shared_store = _OneSlotStore()
     shared_store.slot = ("_a0_session", {"user": {"sub": "real_user"}})
@@ -9375,8 +9374,7 @@ async def test_anonymous_write_cannot_destroy_authenticated_session_on_shared_st
 async def test_missing_anonymous_store_fails_closed_never_falls_back_to_state_store():
     """
     If an integrator forgets anonymous_store, the client must raise before any
-    write — never silently write anonymous state into ServerClient's state_store
-    (which is exactly the collision D3a prevents).
+    write, never silently write anonymous state into ServerClient's state_store.
     """
     shared_store = _OneSlotStore()
     shared_store.slot = ("_a0_session", {"user": {"sub": "real_user"}})
@@ -9397,7 +9395,7 @@ async def test_missing_anonymous_store_fails_closed_never_falls_back_to_state_st
 
 @pytest.mark.asyncio
 async def test_get_session_and_get_user_unaffected_by_active_anonymous_session():
-    """Anonymous state never touches _a0_session — get_session()/get_user() see no new keys."""
+    """Anonymous state never touches _a0_session. get_session()/get_user() see no new keys."""
     secret = "a-test-secret-with-enough-length"
     anon_store = _OneSlotStore()
     anon_store.slot = (ANON_IDENTIFIER, {"context": _make_anon_context(secret)})

src/auth0_server_python/tests/test_server_client.py

@@ -399,33 +399,3 @@ def validate_org_claims(claims: dict, expected_org: str) -> None:
             raise OrganizationTokenValidationError(
                 "Organization Name (org_name) claim value mismatch in the ID token"
             )
-
-
-# =============================================================================
-# Secret Redaction
-# =============================================================================
-
-_SECRET_FIELDS = frozenset({
-    "client_secret",
-    "session_token",
-    "access_token",
-    "assertion",
-    "client_assertion",
-})
-
-
-def scrub_secrets(data: Any) -> Any:
-    """
-    Recursively redact Tier 0/1 secret fields from a parsed error body.
-
-    Walks dicts and lists so a secret nested inside a sub-object (e.g.
-    {"details": {"session_token": "..."}}) is caught, not just top-level keys.
-    """
-    if isinstance(data, dict):
-        return {
-            key: "[REDACTED]" if key in _SECRET_FIELDS else scrub_secrets(value)
-            for key, value in data.items()
-        }
-    if isinstance(data, list):
-        return [scrub_secrets(item) for item in data]
-    return data