volcano-sdk-python 0.8.0__tar.gz → 0.9.0__tar.gz

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

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

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.0](https://github.com/Kong/volcano-sdk-python/compare/v0.8.0...v0.9.0) (2026-09-18)
+
+
+### Features
+
+* **auth:** add token bootstrap with server session continuity ([#159](https://github.com/Kong/volcano-sdk-python/issues/159)) ([0dd9512](https://github.com/Kong/volcano-sdk-python/commit/0dd9512e543e2713233b3632a16ffae0e8c69d1b))
+
 ## [0.8.0](https://github.com/Kong/volcano-sdk-python/compare/v0.7.3...v0.8.0) (2026-09-18)
 
 

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.8.0
+Version: 0.9.0
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -593,6 +593,14 @@ Success returns `None`. The reset revokes the recovered account's existing sessi
 sign it in. The client keeps any unrelated local session unchanged; sign in with the new password
 when the reset flow completes.
 
+To start with only a supplied user access token, pass `access_token` to
+`VolcanoClient`. Construction makes no request and leaves `refresh_token`,
+`user_id`, and `user` as `None` until supplied or validated by the server.
+`get_user()` validates and caches the profile without changing credentials.
+Without a refresh token, `refresh_session()` raises `AuthenticationError` and
+`sign_out()` revokes the server session using the access token and clears local state.
+Supply `refresh_token` with `access_token` to enable refresh. See the [token bootstrap example](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md#use-a-supplied-access-token).
+
 Copy a complete native session into another client's memory:
 
 ```python
@@ -650,9 +658,13 @@ client.auth.sign_out()
 assert client.auth.get_session() is None
 ```
 
+Sign-out uses the refresh token directly when the SDK received both credentials together from
+sign-in or a validated refresh. Supplied credentials use the access-token session; on HTTP 401,
+the SDK can refresh once and revoke that same session without adopting the renewed credentials.
 Calling `sign_out()` without a session succeeds without a request. A revocation failure is raised
-after the captured local session is cleared. A newer session established while sign-out is in
-flight remains current.
+after the captured local session is cleared. Sign-out waits for an already-running refresh and uses its validated credentials.
+Later refresh attempts raise `SessionChangedError` without a request. Concurrent sign-out calls
+share one result. A separate sign-in or adoption remains current.
 
 Realtime is async. Channels wrap `centrifuge-python`; the underlying client and
 subscription objects are not part of the public API.

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/README.md

@@ -571,6 +571,14 @@ Success returns `None`. The reset revokes the recovered account's existing sessi
 sign it in. The client keeps any unrelated local session unchanged; sign in with the new password
 when the reset flow completes.
 
+To start with only a supplied user access token, pass `access_token` to
+`VolcanoClient`. Construction makes no request and leaves `refresh_token`,
+`user_id`, and `user` as `None` until supplied or validated by the server.
+`get_user()` validates and caches the profile without changing credentials.
+Without a refresh token, `refresh_session()` raises `AuthenticationError` and
+`sign_out()` revokes the server session using the access token and clears local state.
+Supply `refresh_token` with `access_token` to enable refresh. See the [token bootstrap example](https://github.com/Kong/volcano-sdk-python/blob/main/docs/README.md#use-a-supplied-access-token).
+
 Copy a complete native session into another client's memory:
 
 ```python
@@ -628,9 +636,13 @@ client.auth.sign_out()
 assert client.auth.get_session() is None
 ```
 
+Sign-out uses the refresh token directly when the SDK received both credentials together from
+sign-in or a validated refresh. Supplied credentials use the access-token session; on HTTP 401,
+the SDK can refresh once and revoke that same session without adopting the renewed credentials.
 Calling `sign_out()` without a session succeeds without a request. A revocation failure is raised
-after the captured local session is cleared. A newer session established while sign-out is in
-flight remains current.
+after the captured local session is cleared. Sign-out waits for an already-running refresh and uses its validated credentials.
+Later refresh attempts raise `SessionChangedError` without a request. Concurrent sign-out calls
+share one result. A separate sign-in or adoption remains current.
 
 Realtime is async. Channels wrap `centrifuge-python`; the underlying client and
 subscription objects are not part of the public API.

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/docs/README.md

@@ -51,7 +51,7 @@ finally:
 ```
 
 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.
+It signs in, fetches the server-validated profile, prints the user's email, revokes its server session, 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`.
 
@@ -73,6 +73,41 @@ 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 a supplied access token
+
+For a server request that already carries a user's access token, create a client for that request:
+
+```python
+import os
+
+from volcano_sdk import VolcanoClient
+
+
+def load_request_user(access_token: str):
+    client = VolcanoClient(
+        anon_key=os.environ["VOLCANO_ANON_KEY"],
+        access_token=access_token,
+    )
+    return client.auth.get_user()
+```
+
+Call this helper from your request handler with the bearer token from that request.
+For a Volcano function, use the access token in `event["__volcano_auth"]["access_token"]` supplied for that invocation.
+The helper validates the token with Volcano before returning the user.
+
+Once a user identity has been validated, a refresh response for another user is rejected and leaves the current credentials unchanged.
+Construction makes no request and does not persist credentials.
+The initial snapshot has `refresh_token=None`, `user_id=None`, and `user=None`.
+A successful profile read fills in the validated identity and cached user while retaining the supplied access token.
+Without a refresh token, an HTTP 401 remains an authentication error, `refresh_session()` raises `AuthenticationError`, and `sign_out()` revokes the server session identified by the access token before clearing local state.
+Refresh must preserve the server session identified by the access JWT, even before a profile is loaded. A different session is rejected, including another session for the same user. Supplied credentials need a readable session identifier to refresh, even when you provide a user profile or load it from the server. Profile data does not prove that access and refresh tokens belong together.
+For supplied credentials, sign-out revokes the access-token session. On HTTP 401, it can refresh once and revoke that same session without adopting the renewed credentials locally.
+When the SDK received both credentials together from sign-in or a validated refresh, it uses the refresh token directly, even if access has expired.
+Sign-out joins an existing refresh and prevents later refresh attempts for that session. Concurrent sign-outs share one result; a separate sign-in or adoption remains current.
+Pass `refresh_token` alongside `access_token` when the client should refresh that session.
+A revocation failure is reported after local clearing; it does not prove that copied tokens are invalid.
+Adopting a session with `set_session()` still requires complete credentials and identity.
+
 ## 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.

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/features/contract_support.py

@@ -116,6 +116,7 @@ class ContractWorld:
         self.last_outcome: Outcome | None = None
         self.previous_session: Session | None = None
         self.signed_out_session: Session | None = None
+        self.bootstrap_cleanup: Callable[[], None] | None = None
         self.auth_state_events: list[tuple[AuthChangeEvent, Session | None]] = []
         self.subscriber: Channel | None = None
         self.publisher: Channel | None = None

volcano_sdk_python-0.9.0/features/staged/auth-token-bootstrap.feature

@@ -0,0 +1,31 @@
+Feature: SDK token-only authentication
+
+  @auth @SDK-AUTH-008
+  Scenario: A client uses a supplied access token without inventing session fields
+    Given an authenticated client
+    When a fresh client tries to refresh a supplied profile without a session identifier
+    Then the SDK operation fails
+    When a fresh client starts with only the current access token
+    Then the SDK operation succeeds
+    And the token-only session has no cached user
+    And the session retains only the supplied access 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 session retains only the supplied access token
+    When the client signs out
+    Then the SDK operation succeeds
+    And the current session is empty
+    When a fresh client loads a profile with the signed-out access token
+    Then the SDK operation fails with an authentication error
+    When a fresh client starts with a rejected access token
+    And the client loads its server-validated profile
+    Then the SDK operation fails with an authentication error
+    And the session retains only the supplied access token
+    And the token-only session has no cached user
+    When the client refreshes the current session
+    Then the SDK operation fails
+    And the session retains only the supplied access token
+    When the client signs out
+    Then the SDK operation succeeds
+    And the current session is empty

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/features/steps/sdk_contract_steps.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import time
+from dataclasses import replace
 from typing import Any
 from uuid import uuid4
 
@@ -78,6 +79,65 @@ def refresh_current_session(context: Any) -> None:
     world.record(world.client.auth.refresh_session)
 
 
+@when("a fresh client tries to refresh a supplied profile without a session identifier")
+def refresh_supplied_profile_without_sid(context: Any) -> None:
+    world = _world(context)
+    source = world.client.auth.get_session()
+    assert source is not None
+    target = VolcanoClient(
+        api_url=world.fixture["api_url"], anon_key=world.fixture["anon_key"]
+    )
+    supplied = target.auth.set_session(replace(source, access_token=REJECTED_BEARER))
+    world.record(target.auth.refresh_session)
+    assert target.auth.get_session() == supplied
+
+
+@when("a fresh client starts with only the current access token")
+def bootstrap_access_token(context: Any) -> None:
+    world = _world(context)
+    source = world.client
+    world.previous_session = source.auth.get_session()
+    assert world.previous_session is not None
+    world.bootstrap_cleanup = source.auth.sign_out
+    world.cleanup_callbacks.append(world.bootstrap_cleanup)
+    world.client = VolcanoClient(
+        api_url=world.fixture["api_url"],
+        anon_key=world.fixture["anon_key"],
+        access_token=world.previous_session.access_token,
+    )
+    world.record(world.client.auth.get_session)
+
+
+@then("the token-only session has no cached user")
+def token_session_has_no_user(context: Any) -> None:
+    session = _world(context).client.current_session
+    assert session is not None
+    assert session.user_id is None
+    assert session.user is None
+
+
+@when("a fresh client starts with a rejected access token")
+def bootstrap_rejected_token(context: Any) -> None:
+    world = _world(context)
+    world.client = VolcanoClient(
+        api_url=world.fixture["api_url"],
+        anon_key=world.fixture["anon_key"],
+        access_token=REJECTED_BEARER,
+    )
+    world.previous_session = world.client.current_session
+    world.record(world.client.auth.get_session)
+
+
+@then("the session retains only the supplied access token")
+def token_session_retains_access(context: Any) -> None:
+    world = _world(context)
+    session = world.client.current_session
+    assert session is not None
+    assert world.previous_session is not None
+    assert session.access_token == world.previous_session.access_token
+    assert session.refresh_token is None
+
+
 @then("the refreshed session becomes current")
 def refreshed_session_becomes_current(context: Any) -> None:
     world = _world(context)
@@ -92,7 +152,10 @@ def sign_out(context: Any) -> None:
     world = _world(context)
     world.signed_out_session = world.client.auth.get_session()
     assert world.signed_out_session is not None
-    world.record(world.client.auth.sign_out)
+    outcome = world.record(world.client.auth.sign_out)
+    if outcome.ok and world.bootstrap_cleanup is not None:
+        world.cleanup_callbacks.remove(world.bootstrap_cleanup)
+        world.bootstrap_cleanup = None
 
 
 @then("the current session is empty")
@@ -100,6 +163,18 @@ def current_session_is_empty(context: Any) -> None:
     assert _world(context).client.auth.get_session() is None
 
 
+@when("a fresh client loads a profile with the signed-out access token")
+def load_signed_out_profile(context: Any) -> None:
+    world = _world(context)
+    assert world.signed_out_session is not None
+    target = VolcanoClient(
+        api_url=world.fixture["api_url"],
+        anon_key=world.fixture["anon_key"],
+        access_token=world.signed_out_session.access_token,
+    )
+    world.record(target.auth.get_user)
+
+
 @when("a fresh client tries to refresh the signed-out session")
 def refresh_signed_out_session(context: Any) -> None:
     world = _world(context)
@@ -128,6 +203,13 @@ def operation_succeeds(context: Any) -> None:
     assert outcome.ok, f"SDK operation failed ({outcome.category}): {outcome.error}"
 
 
+@then("the SDK operation fails")
+def operation_fails(context: Any) -> None:
+    outcome = _world(context).last_outcome
+    assert outcome is not None
+    assert not outcome.ok
+
+
 @then("the current session belongs to the contract user")
 def session_belongs_to_contract_user(context: Any) -> None:
     world = _world(context)
@@ -164,12 +246,14 @@ def authenticated_client(context: Any) -> None:
 
 @given("the client replaces its access token with a rejected token")
 def replace_access_token(context: Any) -> None:
-    client = _world(context).client
+    world = _world(context)
+    client = world.client
     session = client.auth.get_session()
     assert session is not None
-    client.auth.set_session(
+    header, payload, _signature = session.access_token.split(".")
+    world.previous_session = client.auth.set_session(
         Session(
-            access_token=REJECTED_BEARER,
+            access_token=f"{header}.{payload}.sdk-contract-rejected-signature",
             refresh_token=session.refresh_token,
             user_id=session.user_id,
         )
@@ -184,7 +268,8 @@ def read_replaced_token(context: Any) -> None:
     session = world.client.auth.get_session()
     assert session is not None
     assert session.access_token
-    assert session.access_token != REJECTED_BEARER
+    assert world.previous_session is not None
+    assert session.access_token != world.previous_session.access_token
     assert session.refresh_token
     assert session.user_id == world.fixture["user_id"]
 

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/pyproject.toml

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

{volcano_sdk_python-0.8.0 → volcano_sdk_python-0.9.0}/scripts/check_package.sh

@@ -23,8 +23,12 @@ cat > "$smoke_dir/consumer.py" <<'PY'
 from typing import assert_type
 from volcano_sdk import Session, User, VolcanoClient
 
-client = VolcanoClient(anon_key="example")
+client = VolcanoClient(anon_key="example", access_token="supplied-access")
 assert_type(client.auth.get_session(), Session | None)
+session = client.auth.get_session()
+if session is not None:
+    assert_type(session.refresh_token, str | None)
+    assert_type(session.user_id, str | None)
 assert_type(client.auth.get_user(), User)
 assert_type(client.storage.from_("assets").download("hello.txt"), bytes)
 PY
@@ -49,6 +53,7 @@ PY
     "$typechecker" --no-incremental --python-executable "$smoke_dir/venv/bin/python" consumer.py
     cp consumer.py invalid.py
     echo 'client.auth.sign_in(email=42, password="example")' >> invalid.py
+    echo 'VolcanoClient(anon_key="example", access_token=42)' >> invalid.py
     if "$typechecker" --no-incremental --python-executable "$smoke_dir/venv/bin/python" invalid.py > typing-error.log 2>&1; then
       echo "Installed SDK did not reject an invalid argument type" >&2
       exit 1

volcano_sdk_python-0.9.0/src/volcano_sdk/_session.py

@@ -0,0 +1,70 @@
+"""Internal session continuity checks shared by refresh and revocation."""
+
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, cast
+from uuid import UUID
+
+from .errors import AuthenticationError
+
+if TYPE_CHECKING:
+    from .models import Session
+
+_JWT_PARTS = 3
+_REFRESH_USER_MISMATCH = "Refreshed session belongs to a different user"
+_REFRESH_SESSION_MISMATCH = "Refreshed credentials belong to a different server session"
+_MISSING_SESSION_ID = "Cannot refresh supplied credentials without a session identifier"
+
+
+def session_id_from_access_token(access_token: str) -> str | None:
+    """Read an untrusted continuity constraint; this never authenticates a user."""
+    parts = access_token.split(".")
+    if len(parts) != _JWT_PARTS:
+        return None
+    padding = "=" * (-len(parts[1]) % 4)
+    try:
+        payload: object = json.loads(
+            base64.urlsafe_b64decode(parts[1] + padding).decode()
+        )
+    except (ValueError, UnicodeDecodeError, RecursionError):
+        return None
+    if not isinstance(payload, Mapping):
+        return None
+    values = cast("Mapping[object, object]", payload)
+    session_id = values.get("session_id")
+    if not isinstance(session_id, str) or not session_id.strip():
+        return None
+    try:
+        return str(UUID(session_id.strip()))
+    except ValueError:
+        return None
+
+
+def validate_refresh_source(current: Session, *, verified: bool = False) -> None:
+    """Require a session constraint for supplied credentials."""
+    if not verified and session_id_from_access_token(current.access_token) is None:
+        raise AuthenticationError(_MISSING_SESSION_ID)
+
+
+def validate_refresh_identity(current: Session | None, refreshed: Session) -> None:
+    """Reject a refresh outside the captured server session or validated user."""
+    if current is None:
+        return
+    session_id = session_id_from_access_token(current.access_token)
+    if session_id is not None and session_id != session_id_from_access_token(
+        refreshed.access_token
+    ):
+        raise AuthenticationError(_REFRESH_SESSION_MISMATCH)
+    if current.user_id is None:
+        return
+    if current.user_id == refreshed.user_id:
+        return
+    try:
+        matches = UUID(current.user_id) == UUID(str(refreshed.user_id))
+    except ValueError:
+        matches = False
+    if not matches:
+        raise AuthenticationError(_REFRESH_USER_MISMATCH)

volcano_sdk_python-0.9.0/src/volcano_sdk/_session_operations.py

@@ -0,0 +1,158 @@
+"""Bound refresh and revocation work to one explicitly established session."""
+
+from __future__ import annotations
+
+from concurrent.futures import Future
+from threading import Lock
+from typing import TYPE_CHECKING, TypeVar
+
+from .errors import SessionChangedError, VolcanoError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .models import Session
+
+_T = TypeVar("_T")
+
+
+def _copy_failure(error: BaseException, *, include_cause: bool = True) -> BaseException:
+    """Copy public failure details without retaining request frames or contexts."""
+    copied = type(error).__new__(type(error), *error.args)
+    if isinstance(error, VolcanoError) and isinstance(copied, VolcanoError):
+        copied.status = error.status
+        copied.code = error.code
+        copied.retry_after = error.retry_after
+    if include_cause and isinstance(error.__cause__, VolcanoError):
+        copied.__cause__ = _copy_failure(error.__cause__, include_cause=False)
+    return copied
+
+
+class SessionOperations:
+    """Retain only this session's latest refresh and shared sign-out outcome."""
+
+    def __init__(self, verified: Session | None = None) -> None:
+        self._lock = Lock()
+        self.refreshing: Future[Session] | None = None
+        self.signing_out: Future[BaseException | None] | None = None
+        self._locally_cleared = False
+        self._verified_pair = (
+            (verified.access_token, verified.refresh_token)
+            if verified is not None
+            else None
+        )
+
+    def verify_pair(self, session: Session | None) -> None:
+        with self._lock:
+            if self._locally_cleared:
+                return
+            self._verified_pair = (
+                (session.access_token, session.refresh_token)
+                if session is not None
+                else None
+            )
+
+    def clear_local_credentials(self) -> None:
+        """Keep pending revocation joinable; discard credentials after other clears."""
+        with self._lock:
+            if self.signing_out is not None:
+                return
+            self._locally_cleared = True
+            self._verified_pair = None
+            refreshing = self.refreshing
+        if refreshing is not None:
+            refreshing.add_done_callback(self._forget_refresh)
+
+    def _forget_refresh(self, refreshing: Future[Session]) -> None:
+        with self._lock:
+            if self.refreshing is refreshing:
+                self.refreshing = None
+
+    def has_verified_pair(self, session: Session) -> bool:
+        with self._lock:
+            return session.refresh_token is not None and self._verified_pair == (
+                session.access_token,
+                session.refresh_token,
+            )
+
+    def refresh(self, operation: Callable[[], Session]) -> Session:
+        with self._lock:
+            if self.signing_out is not None or self._locally_cleared:
+                raise SessionChangedError
+            future = self.refreshing
+            if future is None or future.done():
+                future = self.refreshing = Future()
+                owner = True
+            else:
+                owner = False
+        if owner:
+            self._complete(future, operation)
+        return future.result()
+
+    def sign_out(
+        self, operation: Callable[[Future[Session] | None, bool], None]
+    ) -> None:
+        with self._lock:
+            future = self.signing_out
+            if future is None:
+                future = self.signing_out = Future()
+                owner = True
+            else:
+                owner = False
+            preceding = self.refreshing
+            pending = preceding is not None and not preceding.done()
+        if owner:
+            self._complete_revocation(future, operation, preceding, pending=pending)
+        self._sign_out_result(future)
+
+    def wait_for_sign_out(self) -> None:
+        with self._lock:
+            future = self.signing_out
+            pending = future is not None and not future.done()
+        if pending and future is not None:
+            self._sign_out_result(future)
+
+    @staticmethod
+    def _sign_out_result(future: Future[BaseException | None]) -> None:
+        failure = future.result()
+        if failure is not None:
+            # Raising the retained template would attach credential-bearing frames.
+            raise _copy_failure(failure)
+
+    def _complete_revocation(
+        self,
+        future: Future[BaseException | None],
+        operation: Callable[[Future[Session] | None, bool], None],
+        preceding: Future[Session] | None,
+        *,
+        pending: bool,
+    ) -> None:
+        try:
+            self._revoke(operation, preceding, pending=pending)
+        except BaseException as error:
+            future.set_result(_copy_failure(error))
+            raise
+        future.set_result(None)
+
+    def _revoke(
+        self,
+        operation: Callable[[Future[Session] | None, bool], None],
+        preceding: Future[Session] | None,
+        *,
+        pending: bool,
+    ) -> None:
+        try:
+            operation(preceding, pending)
+        finally:
+            with self._lock:
+                self._verified_pair = None
+                self.refreshing = None
+
+    @staticmethod
+    def _complete(future: Future[_T], operation: Callable[[], _T]) -> None:
+        try:
+            future.set_result(operation())
+        except BaseException as error:
+            # Every waiter must finish, including when the owner is interrupted.
+            future.set_exception(error)
+            raise