fix(cte): validate subject_token_type and actor_token, clarify act sourcing

Add local empty/whitespace guards for subject_token_type and actor_token so
they fail with a clear INVALID_TOKEN_FORMAT instead of a generic round-trip
error from the token endpoint, matching the existing subject_token check.
Add tests for both cases.

Document that response.act is read from the id_token and that Auth0 writes
the same act onto the access token (verified against the platform token
dialects), noting the access token may be opaque. Add a comment on the login
path noting act reaches the session user via UserClaims. Rename the refresh
test to reflect that it pins the state-merge behavior the refresh path uses.

Author: kishore7snehil

examples/CustomTokenExchange.md

@@ -83,6 +83,8 @@ if response.act:
     print(f"Acting party: {response.act['sub']}")
 ```
 
+> **NOTE**: `response.act` is read from the ID token. Auth0 writes the same `act` claim onto the issued access token as well, so they reflect the same acting party. The access token may be opaque, in which case `act` cannot be read off it directly - the ID token is where you read it.
+
 When you establish a session with `login_with_custom_token_exchange()`, the `act` claim is persisted on the session user and can be read back later via `get_user()`:
 
 ```python

src/auth0_server_python/auth_server/server_client.py

@@ -2251,11 +2251,21 @@ async def custom_token_exchange(
                     CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
                     "subject_token cannot be empty or whitespace-only"
                 )
+            if not options.subject_token_type.strip():
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "subject_token_type cannot be empty or whitespace-only"
+                )
             if options.subject_token.strip().startswith("Bearer "):
                 raise CustomTokenExchangeError(
                     CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
                     "subject_token should not include 'Bearer ' prefix"
                 )
+            if options.actor_token is not None and not options.actor_token.strip():
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "actor_token cannot be empty or whitespace-only"
+                )
             if options.actor_token and options.actor_token.strip().startswith("Bearer "):
                 raise CustomTokenExchangeError(
                     CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
@@ -2444,6 +2454,8 @@ async def login_with_custom_token_exchange(
                             "ID token issuer mismatch. Ensure your Auth0 domain is configured correctly."
                         )
 
+                    # UserClaims allows extra fields, so any act claim in the
+                    # verified id_token is carried onto the session user here.
                     user_claims = UserClaims.parse_obj(claims)
                     # Extract sid from token if available
                     sid = claims.get("sid", sid)

src/auth0_server_python/tests/test_server_client.py

@@ -3141,6 +3141,58 @@ async def test_custom_token_exchange_missing_actor_token():
     assert "actor_token" in str(exc.value).lower()
 
 
+@pytest.mark.asyncio
+async def test_custom_token_exchange_empty_subject_token_type():
+    """Test that empty/whitespace subject_token_type is rejected locally."""
+    # Setup
+    client = ServerClient(
+        domain="auth0.local",
+        client_id="<client_id>",
+        client_secret="<client_secret>",
+        state_store=AsyncMock(),
+        transaction_store=AsyncMock(),
+        secret="some-secret"
+    )
+
+    # Act & Assert
+    with pytest.raises(CustomTokenExchangeError) as exc:
+        await client.custom_token_exchange(
+            CustomTokenExchangeOptions(
+                subject_token="token",
+                subject_token_type="   "
+            )
+        )
+    assert exc.value.code == CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT
+    assert "subject_token_type" in str(exc.value).lower()
+
+
+@pytest.mark.asyncio
+async def test_custom_token_exchange_whitespace_actor_token():
+    """Test that a whitespace-only actor_token is rejected locally."""
+    # Setup
+    client = ServerClient(
+        domain="auth0.local",
+        client_id="<client_id>",
+        client_secret="<client_secret>",
+        state_store=AsyncMock(),
+        transaction_store=AsyncMock(),
+        secret="some-secret"
+    )
+
+    # Act & Assert
+    with pytest.raises(CustomTokenExchangeError) as exc:
+        await client.custom_token_exchange(
+            CustomTokenExchangeOptions(
+                subject_token="token",
+                subject_token_type="urn:acme:token",
+                actor_token="   ",
+                actor_token_type="urn:ietf:params:oauth:token-type:access_token"
+            )
+        )
+    assert exc.value.code == CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT
+    assert "actor_token" in str(exc.value).lower()
+
+
 @pytest.mark.asyncio
 async def test_custom_token_exchange_api_error_400(mocker):
     """Test handling of 400 error from Auth0."""
@@ -3829,8 +3881,8 @@ async def test_login_with_custom_token_exchange_persists_act_on_user(mocker):
     assert result.state_data["user"]["act"] == {"sub": "agent|abc", "act": {"sub": "svc|xyz"}}
 
 
-def test_act_claim_survives_token_refresh():
-    """A refresh-token grant must not drop the login-time act claim from the user."""
+def test_state_merge_preserves_user_act_claim():
+    """The state merge used on refresh must not drop the user's act claim."""
     state_data = {
         "user": {"sub": "user123", "act": {"sub": "agent|abc"}},
         "id_token": "old.jwt",