volcano-sdk-python 0.7.2__tar.gz → 0.7.3__tar.gz

volcano_sdk_python-0.7.3/.github/workflows/lint-docs.yml

@@ -0,0 +1,16 @@
+name: Lint docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/lint-docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    uses: Kong/volcano-docs/.github/workflows/lint-docs.yml@2eed9e93cae0b070f57788e7c270ccfbb4cd4579
+    with:
+      path: docs

volcano_sdk_python-0.7.3/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.7.3"
+}

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.7.3](https://github.com/Kong/volcano-sdk-python/compare/v0.7.2...v0.7.3) (2026-09-17)
+
+
+### Bug Fixes
+
+* **auth:** refresh rejected profile requests within their session ([#157](https://github.com/Kong/volcano-sdk-python/issues/157)) ([534e5e2](https://github.com/Kong/volcano-sdk-python/commit/534e5e270c94cad758779d98714b217263537dc0))
+
 ## [0.7.2](https://github.com/Kong/volcano-sdk-python/compare/v0.7.1...v0.7.2) (2026-09-17)
 
 

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.7.2
+Version: 0.7.3
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -25,6 +25,8 @@ Description-Content-Type: text/markdown
 Use the Volcano Python SDK to access authentication, databases, storage,
 functions, locks, logs, and realtime events. Requires Python 3.11 or later.
 
+Start with the [Python quickstart](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md).
+
 ## Install
 
 ```shell

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/README.md

@@ -3,6 +3,8 @@
 Use the Volcano Python SDK to access authentication, databases, storage,
 functions, locks, logs, and realtime events. Requires Python 3.11 or later.
 
+Start with the [Python quickstart](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md).
+
 ## Install
 
 ```shell

volcano_sdk_python-0.7.3/docs/README.md

@@ -0,0 +1,82 @@
+---
+title: Python SDK
+description: Install the Volcano Python SDK and authenticate a user from a Python application.
+order: 1
+---
+
+Use `volcano-sdk-python` for authentication, database queries, storage, functions, logs, locks, and realtime events.
+REST calls are synchronous and raise typed exceptions on failure.
+Python 3.11 or later is required; CI tests Python 3.11 and 3.14.
+
+## Install the published package
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install volcano-sdk-python
+```
+
+The [PyPI distribution](https://pypi.org/project/volcano-sdk-python/) is named `volcano-sdk-python`.
+Import it as `volcano_sdk`.
+The package includes type information for mypy and other PEP 561-compatible checkers.
+
+## Sign in and read a profile
+
+Create a project, enable [email and password authentication](/platform/authentication/configuring-auth-methods), and create a user with a confirmed email when your project requires confirmation.
+Use that project's [anonymous key](/platform/authentication/security/anon-keys).
+Set `VOLCANO_ANON_KEY`, `VOLCANO_USER_EMAIL`, and `VOLCANO_USER_PASSWORD` in your environment.
+Set `VOLCANO_API_URL` only when using a different API endpoint, such as local mode.
+
+Save this as `quickstart.py`:
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    anon_key=os.environ["VOLCANO_ANON_KEY"],
+    api_url=os.environ.get("VOLCANO_API_URL", "https://api.volcano.dev"),
+)
+session = client.auth.sign_in(
+    email=os.environ["VOLCANO_USER_EMAIL"],
+    password=os.environ["VOLCANO_USER_PASSWORD"],
+)
+try:
+    user = client.auth.get_user()
+    assert user.id == session.user_id
+    print(f"Signed in as {user.email}")
+finally:
+    client.auth.sign_out()
+```
+
+Run it with `python quickstart.py`.
+It signs in, fetches the server-validated profile, prints the user's email, revokes its refresh token, and clears the local session.
+An invalid email or password raises `AuthenticationError`; failed network requests raise `TransportError`.
+Both inherit from `VolcanoError` and are exported from `volcano_sdk`.
+
+## Keep authentication scoped to one user
+
+A client holds its current session in memory.
+Use a separate client for each independent user session; do not share one mutable client across users in a web server.
+`client.current_session` and `client.auth.get_session()` read the local immutable snapshot without a request.
+Use `client.auth.get_user()` when you need a server-validated profile.
+Successful profile operations update the cached user while preserving the current credentials.
+If `get_user()`, `update_user()`, `convert_anonymous()`, or `confirm_email_change()` receives an HTTP 401 and the session has a usable refresh token, the client refreshes once and retries with the original request values.
+These operations do not retry other HTTP failures or ambiguous network failures, and they never retry under a replacement session.
+
+`sign_up()` returns an acknowledgement without signing in by default.
+Pass `sign_in_when_allowed=True` to sign in only when the project does not require email confirmation.
+To adopt an existing session, pass a `Session` containing its access token, refresh token, and user ID to `client.auth.set_session()`.
+The SDK does not persist tokens for you.
+
+For operations that require a [service key](/platform/authentication/security/service-keys), pass `service_key` to the constructor in trusted server code.
+Keep service keys and user credentials out of source control and client applications.
+
+## Use the rest of the API
+
+The SDK repository contains [examples for every public facade](https://github.com/Kong/volcano-sdk-python#try-the-contract-facade), including database filters and mutations, resumable uploads, function invocation, log queries, lock guards, and realtime presence and database changes.
+Realtime uses an asynchronous lifecycle; follow those examples to connect and disconnect its channels.
+
+See [release notes](https://github.com/Kong/volcano-sdk-python/releases) for version changes and [GitHub issues](https://github.com/Kong/volcano-sdk-python/issues) to report a problem.
+Include the package version, Python version, and a minimal reproduction without credentials.

volcano_sdk_python-0.7.3/features/staged/auth-profile-refresh.feature

@@ -0,0 +1,10 @@
+Feature: SDK profile authentication recovery
+
+  @auth @SDK-AUTH-007
+  Scenario: A rejected profile read refreshes the session and caches the same user
+    Given an authenticated client
+    And the client replaces its access token with a rejected token
+    When the client loads its server-validated profile
+    Then the SDK operation succeeds
+    And the returned and cached profiles belong to the contract user
+    And the profile read replaces the rejected token for the same user

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/features/steps/sdk_contract_steps.py

@@ -175,6 +175,7 @@ def replace_access_token(context: Any) -> None:
     )
 
 
+@then("the profile read replaces the rejected token for the same user")
 @then("the storage operation replaces the rejected token for the same user")
 @then("the database read replaces the rejected token for the same user")
 def read_replaced_token(context: Any) -> None:
@@ -187,6 +188,23 @@ def read_replaced_token(context: Any) -> None:
     assert session.user_id == world.fixture["user_id"]
 
 
+@when("the client loads its server-validated profile")
+def load_server_profile(context: Any) -> None:
+    world = _world(context)
+    world.record(world.client.auth.get_user)
+
+
+@then("the returned and cached profiles belong to the contract user")
+def profiles_belong_to_contract_user(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.last_outcome.value.id == world.fixture["user_id"]
+    session = world.client.current_session
+    assert session is not None
+    assert session.user is not None
+    assert session.user["id"] == world.fixture["user_id"]
+
+
 @when("one client pauses delivery for 1 second and then resumes with the same handler")
 def pause_and_resume(context: Any) -> None:
     world = _world(context)

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "volcano-sdk-python"
-version = "0.7.2"
+version = "0.7.3"
 description = "Official Python SDK for Volcano"
 readme = "README.md"
 requires-python = ">=3.11"

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/src/volcano_sdk/_transport.py

@@ -13,14 +13,10 @@ from uuid import UUID, uuid4
 import httpx
 
 from ._generated.api.authentication import (
-    auth_confirm_email_change,
-    auth_convert_anonymous,
-    auth_get_user,
     auth_logout,
     auth_refresh,
     auth_signin,
     auth_signup,
-    auth_update_user,
 )
 from ._generated.api.authentication.auth_cancel_email_change import (
     _get_kwargs as cancel_email_change_kwargs,
@@ -28,6 +24,18 @@ from ._generated.api.authentication.auth_cancel_email_change import (
 from ._generated.api.authentication.auth_confirm_email import (
     _get_kwargs as confirm_email_kwargs,
 )
+from ._generated.api.authentication.auth_confirm_email_change import (
+    _build_response as build_auth_confirm_email_change_response,
+)
+from ._generated.api.authentication.auth_confirm_email_change import (
+    _get_kwargs as auth_confirm_email_change_kwargs,
+)
+from ._generated.api.authentication.auth_convert_anonymous import (
+    _build_response as build_auth_convert_anonymous_response,
+)
+from ._generated.api.authentication.auth_convert_anonymous import (
+    _get_kwargs as auth_convert_anonymous_kwargs,
+)
 from ._generated.api.authentication.auth_delete_all_my_sessions import (
     _get_kwargs as delete_all_my_sessions_kwargs,
 )
@@ -40,6 +48,12 @@ from ._generated.api.authentication.auth_forgot_password import (
 from ._generated.api.authentication.auth_get_my_sessions import (
     _get_kwargs as get_my_sessions_kwargs,
 )
+from ._generated.api.authentication.auth_get_user import (
+    _build_response as build_auth_get_user_response,
+)
+from ._generated.api.authentication.auth_get_user import (
+    _get_kwargs as auth_get_user_kwargs,
+)
 from ._generated.api.authentication.auth_request_email_change import (
     _get_kwargs as request_email_change_kwargs,
 )
@@ -52,6 +66,12 @@ from ._generated.api.authentication.auth_reset_password import (
 from ._generated.api.authentication.auth_signup_anonymous import (
     _get_kwargs as signup_anonymous_kwargs,
 )
+from ._generated.api.authentication.auth_update_user import (
+    _build_response as build_auth_update_user_response,
+)
+from ._generated.api.authentication.auth_update_user import (
+    _get_kwargs as auth_update_user_kwargs,
+)
 from ._generated.api.database_queries import (
     query_database_select,
 )
@@ -829,9 +849,13 @@ class GeneratedTransport:
         )
         try:
             with self._client(authorization) as client:
-                response = auth_convert_anonymous.sync_detailed(
-                    client=client,
-                    body=body,
+                raw_response = client.get_httpx_client().request(
+                    **auth_convert_anonymous_kwargs(body=body)
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_convert_anonymous_response(
+                    client=client, response=raw_response
                 )
         except (
             AttributeError,
@@ -928,9 +952,13 @@ class GeneratedTransport:
         body = AuthConfirmEmailChangeBody(email_change_token=token)
         try:
             with self._client(authorization) as client:
-                response = auth_confirm_email_change.sync_detailed(
-                    client=client,
-                    body=body,
+                raw_response = client.get_httpx_client().request(
+                    **auth_confirm_email_change_kwargs(body=body)
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_confirm_email_change_response(
+                    client=client, response=raw_response
                 )
         except (
             AttributeError,
@@ -1204,7 +1232,14 @@ class GeneratedTransport:
     def auth_get_user(self, *, authorization: str) -> TransportResponse:
         try:
             with self._client(authorization) as client:
-                response = auth_get_user.sync_detailed(client=client)
+                raw_response = client.get_httpx_client().request(
+                    **auth_get_user_kwargs()
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_get_user_response(
+                    client=client, response=raw_response
+                )
         except (
             AttributeError,
             KeyError,
@@ -1239,7 +1274,14 @@ class GeneratedTransport:
         )
         try:
             with self._client(authorization) as client:
-                response = auth_update_user.sync_detailed(client=client, body=body)
+                raw_response = client.get_httpx_client().request(
+                    **auth_update_user_kwargs(body=body)
+                )
+                if raw_response.status_code == HTTP_UNAUTHORIZED:
+                    return self._raw_response(raw_response)
+                response = build_auth_update_user_response(
+                    client=client, response=raw_response
+                )
         except (
             AttributeError,
             KeyError,

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/src/volcano_sdk/auth.py

@@ -9,6 +9,7 @@ import secrets
 import threading
 from collections.abc import Mapping
 from contextlib import suppress
+from copy import deepcopy
 from dataclasses import replace
 from datetime import datetime
 from http import HTTPStatus
@@ -574,18 +575,22 @@ class Auth:
         metadata: Mapping[str, object] | None = None,
     ) -> User:
         """Attach email credentials to the current anonymous account."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthConvertAnonymousTransport", self._client._transport)
-        response = invoke(
-            transport.auth_convert_anonymous,
-            authorization=current.access_token,
-            email=email,
-            password=password,
-            metadata=dict(metadata or {}),
+        request_metadata = deepcopy(dict(metadata or {}))
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_convert_anonymous,
+                authorization=access_token,
+                email=email,
+                password=password,
+                metadata=request_metadata,
+            ),
+            binding=binding,
         )
-        return self._update_current_user(response_payload(response, 200), generation)
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def reset_password_for_email(self, *, email: str) -> None:
         """Request a reset email without revealing whether the account exists."""
@@ -629,16 +634,19 @@ class Auth:
 
     def confirm_email_change(self, *, token: str) -> User:
         """Confirm a pending email change and return the updated user."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthConfirmEmailChangeTransport", self._client._transport)
-        response = invoke(
-            transport.auth_confirm_email_change,
-            authorization=current.access_token,
-            token=token,
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_confirm_email_change,
+                authorization=access_token,
+                token=token,
+            ),
+            binding=binding,
         )
-        return self._update_current_user(response_payload(response, 200), generation)
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def delete_all_other_sessions(self) -> None:
         """Delete every other session while preserving the current session."""
@@ -944,7 +952,10 @@ class Auth:
         )
         response_payload(response, 200)
 
-    def _update_current_user(self, payload: object, generation: int) -> User:
+    def _update_current_user(
+        self, payload: object, binding: tuple[int, int, Session | None]
+    ) -> User:
+        generation = self._owned_refresh_session(binding)[0]
         user, snapshot = _user_from_payload(payload)
         if not self._client._update_session_user_if_current(snapshot, generation):
             raise SessionChangedError
@@ -952,12 +963,17 @@ class Auth:
 
     def get_user(self) -> User:
         """Load a server-validated profile for the current session."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthGetUserTransport", self._client._transport)
-        response = invoke(transport.auth_get_user, authorization=current.access_token)
-        return self._update_current_user(response_payload(response, 200), generation)
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_get_user, authorization=access_token
+            ),
+            binding=binding,
+        )
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def update_user(
         self,
@@ -966,17 +982,21 @@ class Auth:
         metadata: Mapping[str, object] | None = None,
     ) -> User:
         """Update and return the current user's server-validated profile."""
-        generation, current = self._client._capture_session()
-        if current is None:
+        binding = self._client._capture_session_binding()
+        if binding[2] is None:
             raise AuthenticationError(_NO_ACTIVE_SESSION)
         transport = cast("AuthUpdateUserTransport", self._client._transport)
-        response = invoke(
-            transport.auth_update_user,
-            authorization=current.access_token,
-            password=password,
-            metadata=None if metadata is None else dict(metadata),
+        request_metadata = None if metadata is None else deepcopy(dict(metadata))
+        response = self._session_request(
+            lambda access_token: invoke(
+                transport.auth_update_user,
+                authorization=access_token,
+                password=password,
+                metadata=request_metadata,
+            ),
+            binding=binding,
         )
-        return self._update_current_user(response_payload(response, 200), generation)
+        return self._update_current_user(response_payload(response, 200), binding)
 
     def sign_in(self, *, email: str, password: str) -> Session:
         """Sign in a user and store the returned session."""

{volcano_sdk_python-0.7.2 → volcano_sdk_python-0.7.3}/tests/unit/test_contract_bindings.py

@@ -84,6 +84,12 @@ def test_staged_storage_feature_matches_proposed_shared_source() -> None:
     assert hashlib.sha256(staged.read_bytes()).hexdigest() == expected
 
 
+def test_staged_profile_feature_matches_proposed_shared_source() -> None:
+    staged = ROOT / "features" / "staged" / "auth-profile-refresh.feature"
+    expected = "df46f1c374fcbdeb790cde0781ff14f580e56c44ac9aa6445d97469a385f6f51"
+    assert hashlib.sha256(staged.read_bytes()).hexdigest() == expected
+
+
 def test_every_contract_phrase_is_bound_verbatim() -> None:
     registry.clear()
     _load_module(
@@ -109,6 +115,9 @@ def test_every_contract_phrase_is_bound_verbatim() -> None:
         "the client replaces its access token with a rejected token",
         "the database read replaces the rejected token for the same user",
         "the storage operation replaces the rejected token for the same user",
+        "the profile read replaces the rejected token for the same user",
+        "the client loads its server-validated profile",
+        "the returned and cached profiles belong to the contract user",
         (
             "one client pauses delivery for 1 second "
             "and then resumes with the same handler"

volcano_sdk_python-0.7.3/tests/unit/test_profile_refresh.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+import pytest
+
+from volcano_sdk import (
+    AuthenticationError,
+    Session,
+    SessionChangedError,
+    VolcanoClient,
+    VolcanoError,
+)
+from volcano_sdk._transport import GeneratedTransport
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+OPERATIONS = ("get_user", "update_user", "convert_anonymous", "confirm_email_change")
+USER_ID = "00000000-0000-4000-8000-000000000001"
+PROFILE = {"id": USER_ID, "email": "updated@example.com", "status": "active"}
+
+
+def make_client(handler: Callable[[httpx.Request], httpx.Response]) -> VolcanoClient:
+    client = VolcanoClient(
+        anon_key="anon",
+        _transport=GeneratedTransport(
+            api_url="https://api.test.volcano.dev",
+            httpx_transport=httpx.MockTransport(handler),
+        ),
+    )
+    client.auth.set_session(Session("old-access", "old-refresh", USER_ID))
+    return client
+
+
+def profile_operation(
+    client: VolcanoClient, operation: str, metadata: dict[str, object]
+) -> object:
+    operations: dict[str, Callable[[], object]] = {
+        "get_user": client.auth.get_user,
+        "update_user": lambda: client.auth.update_user(
+            password="secret", metadata=metadata
+        ),
+        "convert_anonymous": lambda: client.auth.convert_anonymous(
+            email="updated@example.com", password="secret", metadata=metadata
+        ),
+        "confirm_email_change": lambda: client.auth.confirm_email_change(
+            token="confirmation"
+        ),
+    }
+    return operations[operation]()
+
+
+def refresh_response() -> httpx.Response:
+    return httpx.Response(
+        200,
+        json={
+            "access_token": "new-access",
+            "refresh_token": "new-refresh",
+            "token_type": "bearer",
+            "expires_in": 3600,
+            "user": PROFILE,
+        },
+    )
+
+
+@pytest.mark.parametrize("operation", OPERATIONS)
+@pytest.mark.parametrize("rejection", [b'{"error":"expired"}', b"", b"not json"])
+def test_profile_refreshes_once_preserving_request_and_cached_user(
+    operation: str, rejection: bytes
+) -> None:
+    requests: list[httpx.Request] = []
+    roles = ["editor"]
+    metadata: dict[str, object] = {"roles": roles}
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path == "/auth/refresh":
+            roles.append("changed while refreshing")
+            return refresh_response()
+        if request.headers["authorization"] == "Bearer old-access":
+            return httpx.Response(401, content=rejection)
+        return httpx.Response(200, json={"user": PROFILE})
+
+    client = make_client(handle)
+    events: list[str] = []
+    client.auth.on_auth_state_change(lambda event, _session: events.append(event))
+    profile_operation(client, operation, metadata)
+    assert [r.headers["authorization"] for r in requests] == [
+        "Bearer old-access",
+        "Bearer anon",
+        "Bearer new-access",
+    ]
+    assert requests[0].url == requests[2].url
+    assert requests[0].method == requests[2].method
+    assert requests[0].content == requests[2].content
+    assert client.current_session is not None
+    assert client.current_session.access_token == "new-access"
+    assert client.current_session.user is not None
+    assert client.current_session.user["email"] == PROFILE["email"]
+    assert events == ["INITIAL_SESSION", "TOKEN_REFRESHED"]
+
+
+@pytest.mark.parametrize("operation", OPERATIONS)
+@pytest.mark.parametrize("refresh_status", [200, 401, 503])
+def test_profile_bounds_retries_and_retains_original_failure(
+    operation: str, refresh_status: int
+) -> None:
+    requests: list[httpx.Request] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path == "/auth/refresh":
+            return (
+                refresh_response()
+                if refresh_status == 200
+                else httpx.Response(refresh_status, json={"error": "refresh failed"})
+            )
+        return httpx.Response(401, json={"error": "profile denied"})
+
+    client = make_client(handle)
+    with pytest.raises(AuthenticationError, match="profile denied"):
+        profile_operation(client, operation, {})
+    assert len(requests) == (3 if refresh_status == 200 else 2)
+    assert (client.current_session is None) == (refresh_status == 401)
+
+
+@pytest.mark.parametrize("operation", OPERATIONS)
+@pytest.mark.parametrize("status", [403, 500])
+def test_profile_does_not_refresh_other_failures(operation: str, status: int) -> None:
+    requests: list[httpx.Request] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return httpx.Response(status, json={"error": "denied"})
+
+    with pytest.raises(VolcanoError):
+        profile_operation(make_client(handle), operation, {})
+    assert len(requests) == 1
+
+
+@pytest.mark.parametrize("operation", OPERATIONS)
+@pytest.mark.parametrize("replace_at", ["first", "refresh", "retry"])
+def test_profile_refresh_never_adopts_a_replacement_session(
+    operation: str, replace_at: str
+) -> None:
+    requests: list[httpx.Request] = []
+    replacement = Session("replacement-access", "replacement-refresh", USER_ID)
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        stage = (
+            "refresh"
+            if request.url.path == "/auth/refresh"
+            else ("first" if len(requests) == 1 else "retry")
+        )
+        if stage == replace_at:
+            client.auth.set_session(replacement)
+        if stage == "refresh":
+            return refresh_response()
+        return (
+            httpx.Response(401, json={"error": "expired"})
+            if stage == "first"
+            else httpx.Response(200, json={"user": PROFILE})
+        )
+
+    client = make_client(handle)
+    with pytest.raises(SessionChangedError):
+        profile_operation(client, operation, {})
+    assert client.current_session == replacement
+    assert len(requests) == {"first": 1, "refresh": 2, "retry": 3}[replace_at]
+
+
+@pytest.mark.parametrize("operation", OPERATIONS)
+def test_profile_does_not_replay_an_ambiguous_transport_failure(operation: str) -> None:
+    requests: list[httpx.Request] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        message = "response lost"
+        raise httpx.ReadError(message, request=request)
+
+    with pytest.raises(VolcanoError, match="response lost"):
+        profile_operation(make_client(handle), operation, {})
+    assert len(requests) == 1