feat(auth): add Python authentication facade

README.md

@@ -77,3 +77,6 @@ VOLCANO_SDK_CONTRACT_FIXTURE=/absolute/path/to/fixture.json \
 ```
 
 The fixture must be an absolute path to a mode-`0600` JSON file.
+
+See [Authentication](docs/authentication.md) for account, session, hosted auth,
+and OAuth examples.

docs/authentication.md

@@ -0,0 +1,174 @@
+# Authentication
+
+Create a client with your project URL and anonymous key, then use `client.auth`
+for account and session operations.
+
+```python
+from volcano_sdk import VolcanoClient
+
+client = VolcanoClient(
+    api_url="https://api.volcano.dev",
+    anon_key="your-anon-key",
+)
+
+session = client.auth.sign_in(
+    email="user@example.com",
+    password="your-password",
+)
+
+print(client.current_user.id)
+print(session.expires_at)
+```
+
+The client keeps the active `current_user` and `current_session` in memory.
+Pass both tokens when restoring an existing session in a new client. An access
+token without a refresh token is valid, but a refresh token without an access
+token is rejected.
+
+```python
+restored = VolcanoClient(
+    api_url="https://api.volcano.dev",
+    anon_key="your-anon-key",
+    access_token=session.access_token,
+    refresh_token=session.refresh_token,
+)
+
+restored.auth.refresh_session()
+```
+
+Store tokens in the secure storage provided by your runtime. Do not log them or
+place them in source control.
+
+## Manage the session
+
+Subscribe to auth-state changes when application state must follow the client.
+The listener runs immediately with the current user and after committed auth
+changes. Call the returned function to unsubscribe.
+
+```python
+unsubscribe = client.auth.on_auth_state_change(
+    lambda user: print("signed in" if user else "signed out")
+)
+
+client.auth.refresh_session()
+client.auth.sign_out()
+unsubscribe()
+```
+
+A failed refresh clears local authentication so stale credentials are not
+reused. `sign_out()` also clears local state if the remote revoke fails.
+
+List and revoke device sessions through the same facade:
+
+```python
+page = client.auth.get_sessions(page=1, limit=20)
+
+for device_session in page.sessions:
+    print(device_session.id, device_session.last_seen_at)
+
+client.auth.delete_session(session_id="session-id")
+client.auth.delete_all_other_sessions()
+```
+
+## Create and update accounts
+
+Sign-up can return without a session when email confirmation is required.
+
+```python
+result = client.auth.sign_up(
+    email="new-user@example.com",
+    password="your-password",
+    user_metadata={"plan": "starter"},
+)
+
+if result.confirmation_required:
+    print("Check your email")
+```
+
+Update the current user, or start with an anonymous account and preserve its
+identity when converting it:
+
+```python
+client.auth.update_user(user_metadata={"plan": "pro"})
+
+client.auth.sign_out()
+client.auth.sign_up_anonymous(user_metadata={"source": "demo"})
+anonymous_id = client.current_user.id
+
+converted = client.auth.convert_anonymous(
+    email="converted@example.com",
+    password="your-password",
+)
+assert converted.id == anonymous_id
+```
+
+Email workflows are available as explicit operations:
+
+```python
+client.auth.resend_confirmation(email="new-user@example.com")
+client.auth.confirm_email(token="confirmation-token")
+client.auth.forgot_password(email="user@example.com")
+client.auth.reset_password(
+    token="recovery-token",
+    new_password="your-new-password",
+)
+
+change = client.auth.request_email_change(new_email="next@example.com")
+client.auth.confirm_email_change(token="email-change-token")
+# Or cancel a pending request:
+client.auth.cancel_email_change()
+```
+
+## Open hosted auth and OAuth
+
+Hosted auth returns a URL and generated state value for your application to
+retain before navigation:
+
+```python
+request = client.auth.get_hosted_auth_url(
+    project_id="project-id",
+    action="login",
+)
+print(request.authorization_url)
+```
+
+OAuth authorization follows the same pattern. Preserve `request.state` and
+pass it as `expected_state` during exchange; the SDK rejects a mismatch before
+calling the API.
+
+```python
+request = client.auth.get_oauth_authorization_url(
+    provider="github",
+    redirect_url="https://app.example.com/auth/callback",
+)
+
+# After the provider redirects to your application:
+client.auth.exchange_oauth_code(
+    code="authorization-code",
+    redirect_url="https://app.example.com/auth/callback",
+    state="state-from-callback",
+    expected_state=request.state,
+)
+```
+
+Signed-in users can link providers, inspect them, refresh provider tokens, and
+call provider APIs through Volcano:
+
+```python
+link = client.auth.link_oauth_provider(
+    provider="github",
+    redirect_url="https://app.example.com/auth/link/callback",
+)
+
+providers = client.auth.get_linked_oauth_providers()
+token = client.auth.get_oauth_provider_token(provider="github")
+client.auth.refresh_oauth_token(provider="github")
+profile = client.auth.call_oauth_api(
+    provider="github",
+    endpoint="/user",
+)
+client.auth.unlink_oauth_provider(provider="github")
+```
+
+Keep generated state values and provider tokens secret. Navigate to the returned
+authorization URL only after storing its matching state value.

features/contract/auth.feature

@@ -7,3 +7,65 @@ Feature: SDK authentication contract
     Then the SDK operation succeeds
     And the current session belongs to the contract user
     And the current session exposes access and refresh tokens
+
+  @auth @SDK-AUTH-002
+  Scenario: Password sign-up acknowledges a session-less account
+    Given a unique unconfirmed contract user
+    When the client signs up with the new user's credentials
+    Then the SDK operation succeeds
+    And sign-up is acknowledged without a session
+    And the current session is empty
+
+  @auth @SDK-AUTH-003
+  Scenario: The current user can be retrieved and updated
+    Given the client is signed in as the confirmed contract user
+    When the client retrieves the current user
+    Then the current user belongs to the contract user
+    When the client updates the current user's metadata
+    Then the current user contains the updated metadata
+
+  @auth @SDK-AUTH-004
+  Scenario: Refresh rotates tokens and failed refresh clears authentication
+    Given the client is signed in as the confirmed contract user
+    When the client refreshes the current session
+    Then the current session exposes rotated access and refresh tokens
+    When the client refreshes with an invalid refresh token
+    Then the SDK operation fails
+    And the current session is empty
+
+  @auth @SDK-AUTH-005
+  Scenario: Sign-out clears local authentication
+    Given the client is signed in as the confirmed contract user
+    When the client signs out
+    Then the SDK operation succeeds
+    And the current session is empty
+
+  @auth @SDK-AUTH-006
+  Scenario: Auth-state listeners observe changes until unsubscribe
+    Given the client is signed in as the confirmed contract user
+    When the client subscribes to auth-state changes
+    Then the listener immediately observes the current user
+    When the client signs out
+    Then the listener observes the signed-out state
+    When the client unsubscribes from auth-state changes
+    And the client signs in with the contract user's credentials
+    Then the listener receives no additional events
+
+  @auth @SDK-AUTH-007
+  Scenario: An anonymous user can convert to a credentialed account
+    Given a unique anonymous contract user
+    When the client signs up anonymously
+    Then the current session belongs to the anonymous user
+    When the client converts the anonymous user with credentials
+    Then the SDK operation succeeds
+    And the converted user keeps the anonymous user identity
+
+  @auth @SDK-AUTH-011
+  Scenario: A user can inspect and delete their sessions
+    Given the client is signed in as the confirmed contract user on multiple sessions
+    When the client lists the current user's sessions
+    Then the session list contains the current session
+    When the client deletes another current-user session
+    Then the deleted session is absent from the session list
+    When the client deletes all current-user sessions
+    Then the current session is empty

features/contract_support.py

@@ -61,34 +61,29 @@ def classify_error(error: Exception) -> str:
         (ServerError, "server error"),
         (TransportError, "transport error"),
     )
-    matched_category = next(
-        (
-            category
-            for error_type, category in categories
-            if isinstance(error, error_type)
-        ),
-        None,
-    )
-    if matched_category is not None:
-        return matched_category
+    for error_type, category in categories:
+        if isinstance(error, error_type):
+            return category
     if isinstance(error, VolcanoError):
-        status = error.status
-        if status in (401, 403):
-            return "authentication error"
-        if status in (400, 422):
-            return "validation error"
-        category_by_status = {
-            HTTP_NOT_FOUND: "not found",
-            HTTP_CONFLICT: "conflict",
-            HTTP_RATE_LIMITED: "rate limited",
-        }
-        if status in category_by_status:
-            return category_by_status[status]
-        if (
-            status is not None
-            and HTTP_SERVER_ERROR_MIN <= status <= HTTP_SERVER_ERROR_MAX
-        ):
-            return "server error"
+        return _classify_volcano_status(error.status)
+    return "transport error"
+
+
+def _classify_volcano_status(status: int | None) -> str:
+    category_by_status = {
+        400: "validation error",
+        401: "authentication error",
+        403: "authentication error",
+        422: "validation error",
+        HTTP_NOT_FOUND: "not found",
+        HTTP_CONFLICT: "conflict",
+        HTTP_RATE_LIMITED: "rate limited",
+    }
+    category = category_by_status.get(status)
+    if category is not None:
+        return category
+    if status is not None and HTTP_SERVER_ERROR_MIN <= status <= HTTP_SERVER_ERROR_MAX:
+        return "server error"
     return "transport error"
 
 
@@ -105,6 +100,9 @@ def __init__(self, fixture: dict[str, Any]) -> None:
             service_key=fixture["service_key"],
         )
         suffix = f"py-{os.getpid()}-{secrets.token_hex(5)}"
+        self.unique_email = f"{suffix}@example.com"
+        self.unique_password = f"Sdk-{suffix}!123"
+        self.metadata_marker = f"updated-{suffix}"
         self.storage_path = f"{fixture['storage_path']}.{suffix}"
         self.realtime_channel = f"{fixture['realtime_channel']}-{suffix}"
         self.lock_key = f"{fixture['lock_key']}-{suffix}"
@@ -117,6 +115,14 @@ def __init__(self, fixture: dict[str, Any]) -> None:
         self.subscriber: Channel | None = None
         self.publisher: Channel | None = None
         self.realtime_clients: list[VolcanoClient] = []
+        self.secondary_client: VolcanoClient | None = None
+        self.listener_events: list[str | None] = []
+        self.listener_event_count = 0
+        self.unsubscribe_auth: Callable[[], None] | None = None
+        self.previous_access_token: str | None = None
+        self.previous_refresh_token: str | None = None
+        self.anonymous_user_id: str | None = None
+        self.deleted_session_id: str | None = None
         self.cleanup_callbacks: list[Callable[[], None]] = []
         self.loop = asyncio.new_event_loop()