sovaria-sdk 0.2.0__py3-none-any.whl

sovaria/__init__.py

@@ -0,0 +1,105 @@
+"""
+sovaria — Python SDK for the Sovaria BaaS platform.
+
+Phase 1 §9 Sprint 3.2
+
+Quick start:
+    from sovaria import SovariaClient
+
+    async with SovariaClient("https://api.sovaria.in") as sov:
+        tokens = await sov.login("you@example.com", "password")
+        org    = await sov.create_node("ORG", "Acme Corp")
+        proj   = await sov.create_node("PROJECT", "Main App")
+        _      = await sov.create_edge(org.node_id, proj.node_id, "OWNS")
+        ctx    = await sov.get_context(tokens.user_id, proj.node_id)
+        print(ctx.roles)  # ['owner']
+"""
+
+from pathlib import Path
+from typing import Any
+
+from .client import SovariaClient, SovariaSyncClient
+from .complete_api import CompleteAPIMixin
+from .config import SovariaPortalConfig
+from .data import DataClient
+from .models import (
+    ContextManifest,
+    EdgeResponse,
+    NodeResponse,
+    NodeType,
+    RelationType,
+    SovariaError,
+    TokenResponse,
+)
+from .project import (
+    DEFAULT_CONFIG_FILENAME,
+    SovariaProjectConfig,
+    SovariaProjectScaffoldResult,
+    client_from_project_config,
+    create_project_from_config,
+    create_project_from_config_file,
+    default_project_config,
+    load_project_config,
+    write_project_config_template,
+)
+
+
+def create_client(config: SovariaPortalConfig | dict[str, Any]) -> SovariaClient:
+    """Create a Sovaria client from portal-style configuration."""
+    return SovariaClient.from_portal_config(config)
+
+
+def create_sync_client(config: SovariaPortalConfig | dict[str, Any]) -> SovariaSyncClient:
+    """Create a synchronous Sovaria client from portal-style configuration."""
+    return SovariaSyncClient.from_portal_config(config)
+
+
+def client_from_config_file(
+    config_path: str | Path | None = None,
+    *,
+    access_token: str | None = None,
+) -> SovariaClient:
+    """Create a client from sovaria.config.json (walks up from cwd when path omitted)."""
+    bootstrap = client_from_project_config(config_path, access_token=access_token)
+    return create_client(bootstrap)
+
+
+def sync_client_from_config_file(
+    config_path: str | Path | None = None,
+    *,
+    access_token: str | None = None,
+) -> SovariaSyncClient:
+    """Synchronous variant of client_from_config_file."""
+    bootstrap = client_from_project_config(config_path, access_token=access_token)
+    return create_sync_client(bootstrap)
+
+
+__all__ = [
+    "SovariaClient",
+    "SovariaSyncClient",
+    "CompleteAPIMixin",
+    "SovariaPortalConfig",
+    "create_client",
+    "create_sync_client",
+    "client_from_config_file",
+    "sync_client_from_config_file",
+    "client_from_project_config",
+    "DataClient",
+    "TokenResponse",
+    "NodeResponse",
+    "EdgeResponse",
+    "ContextManifest",
+    "SovariaError",
+    "NodeType",
+    "RelationType",
+    "DEFAULT_CONFIG_FILENAME",
+    "SovariaProjectConfig",
+    "SovariaProjectScaffoldResult",
+    "create_project_from_config",
+    "create_project_from_config_file",
+    "default_project_config",
+    "load_project_config",
+    "write_project_config_template",
+]
+
+__version__ = "0.2.0"

sovaria/auth.py

@@ -0,0 +1,187 @@
+"""
+sovaria.auth — Token storage and automatic refresh for the Python SDK.
+
+Phase 1 §9 Sprint 3.2: "SDK stores tokens in memory; CLI stores them via keyring."
+
+The AuthManager is injected into SovariaClient and handles:
+  1. Storing access_token / refresh_token in memory.
+  2. Checking expiry before each request (based on `expires_in`).
+  3. Calling `POST /api/v1/auth/refresh` to obtain a new pair when the
+     access token is within `_refresh_margin_seconds` of expiry.
+
+Thread-safety: asyncio.Lock guards the refresh critical section so that
+concurrent coroutines do not trigger multiple simultaneous refreshes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING
+
+import httpx
+
+from sovaria.models import SovariaError, TokenResponse
+
+if TYPE_CHECKING:
+    pass
+
+
+class AuthManager:
+    """
+    In-memory token manager for the SDK.
+
+    The `refresh_margin_seconds` window ensures we refresh before
+    expiry rather than on the first 401, avoiding a failed request.
+    """
+
+    _refresh_margin_seconds: int = 60  # refresh when < 60 s remain
+
+    def __init__(self, base_url: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at: float = 0.0  # Unix timestamp
+        self._lock = asyncio.Lock()
+        # Phase 2 Sprint 1: KEK cache — derived once per session via Argon2id.
+        # Stays in RAM; never serialised, never sent over the wire.
+        self._kek: bytes | None = None  # 256-bit Key Encryption Key
+        self._argon2_salt: bytes | None = None  # 128-bit user salt (from server)
+
+    # ── Token lifecycle methods ────────────────────────────────────────────────
+
+    def set_tokens(self, resp: TokenResponse) -> None:
+        """Store token pair returned by login / refresh."""
+        if not resp.access_token:
+            raise SovariaError(400, "Missing access token in auth response")
+
+        self._access_token = resp.access_token
+        if resp.mfa_required:
+            self._refresh_token = None
+            ttl = resp.expires_in if resp.expires_in is not None else 300
+            self._expires_at = time.time() + ttl
+            return
+
+        self._refresh_token = resp.refresh_token
+        ttl = resp.expires_in if resp.expires_in is not None else 3600
+        self._expires_at = time.time() + ttl
+
+    def set_bearer_token(self, access_token: str, *, expires_in: int = 31_536_000) -> None:
+        """
+        Store a pre-issued access token (portal/publishable-key style bootstrap).
+
+        This mode intentionally omits a refresh token. Callers can still switch to
+        login()/set_tokens() later when they need refresh support.
+        """
+        token = access_token.strip()
+        if not token:
+            raise SovariaError(400, "Access token cannot be empty")
+        self._access_token = token
+        self._refresh_token = None
+        self._expires_at = time.time() + max(int(expires_in), self._refresh_margin_seconds + 1)
+
+    def clear(self) -> None:
+        """Remove all stored tokens and KEK (logout)."""
+        self._access_token = None
+        self._refresh_token = None
+        self._expires_at = 0.0
+        # Phase 2: zero KEK bytes then discard reference
+        if self._kek is not None:
+            try:
+                from sovaria.utils.crypto import _zero_bytes  # noqa: PLC0415
+
+                _zero_bytes(self._kek)
+            except Exception:  # noqa: BLE001
+                pass
+        self._kek = None
+        self._argon2_salt = None
+
+    @property
+    def access_token(self) -> str | None:
+        return self._access_token
+
+    @property
+    def is_authenticated(self) -> bool:
+        return bool(self._access_token)
+
+    # ── Phase 2: KEK management ───────────────────────────────────────────────
+
+    def set_kek(self, kek: bytes, salt: bytes) -> None:
+        """
+        Cache the derived Argon2id KEK for the session lifetime.
+
+        Called once by SovariaClient.login() after a successful Argon2id
+        derivation.  The KEK is reused for all document encrypt/decrypt calls
+        so users only pay the ~300ms Argon2id cost once per login.
+
+        Args:
+            kek:  32-byte (256-bit) key derived by Argon2id.
+            salt: 16-byte salt returned by Axis on login (stored for logging/debug).
+        """
+        self._kek = kek
+        self._argon2_salt = salt
+
+    @property
+    def kek(self) -> bytes | None:
+        """Return the cached KEK, or None if derive_kek() has not been called yet."""
+        return self._kek
+
+    @property
+    def argon2_salt(self) -> bytes | None:
+        """Return the cached Argon2id salt for this session."""
+        return self._argon2_salt
+
+    def _needs_refresh(self) -> bool:
+        """True when the access token exists but is absent or close to expiry.
+
+        Returns ``False`` when not logged in (no access token) — in that case
+        ``ensure_token_fresh`` is a no-op and the caller must call ``login``
+        explicitly before making authenticated requests.
+        """
+        if not self._access_token:
+            return False  # not logged in at all — can't refresh
+        return time.time() >= (self._expires_at - self._refresh_margin_seconds)
+
+    # ── Proactive refresh ─────────────────────────────────────────────────────
+
+    async def ensure_token_fresh(self, client: httpx.AsyncClient) -> None:
+        """
+        Called before every request.  Uses a lock so that concurrent
+        coroutines don't each attempt their own refresh simultaneously.
+        """
+        if not self._needs_refresh():
+            return
+
+        async with self._lock:
+            # Double-check inside the lock — another coroutine may have
+            # already refreshed while we were waiting.
+            if not self._needs_refresh():
+                return
+
+            await self._do_refresh(client)
+
+    async def _do_refresh(self, client: httpx.AsyncClient) -> None:
+        if not self._refresh_token:
+            raise SovariaError(401, "No refresh token available — please log in again")
+
+        response = await client.post(
+            f"{self._base_url}/api/v1/auth/refresh",
+            json={"refresh_token": self._refresh_token},
+        )
+
+        if response.status_code != 200:
+            self.clear()
+            raise SovariaError(
+                response.status_code,
+                response.json().get("detail", "Refresh failed"),
+            )
+
+        self.set_tokens(TokenResponse(**response.json()))
+
+    # ── Request helper ────────────────────────────────────────────────────────
+
+    def inject_auth_header(self, headers: dict) -> dict:
+        """Return headers dict with Authorization injected."""
+        if self._access_token:
+            return {**headers, "Authorization": f"Bearer {self._access_token}"}
+        return headers