torii-backend 0.0.2__py3-none-any.whl

torii_backend/__init__.py

@@ -0,0 +1,57 @@
+"""torii-backend — backend SDK for torii.
+
+Verify JWTs networklessly, call ``/api/server/v1/**`` with a secret key,
+and (soon) verify outbound webhook signatures. Framework-agnostic; an
+optional FastAPI dependency adapter lives in ``torii_backend.fastapi``.
+"""
+
+from torii_backend.client import ToriiClient, create_torii_client
+from torii_backend.errors import ToriiApiError, ToriiAuthError
+
+# Generated data types — re-exported under stable Torii* aliases so the
+# public surface is independent of the generator's naming.
+from torii_backend.generated.models import (
+    CreateUserRequest as ToriiCreateUserInput,
+)
+from torii_backend.generated.models import (
+    CursorPageResponseUserResponse as ToriiCursorPageUser,
+)
+from torii_backend.generated.models import (
+    ProblemDetail as ToriiProblemDetail,
+)
+from torii_backend.generated.models import (
+    UpdateUserRequest as ToriiUpdateUserInput,
+)
+from torii_backend.generated.models import (
+    UserResponse as ToriiUser,
+)
+from torii_backend.generated.models import (
+    UserSessionResponse as ToriiSession,
+)
+from torii_backend.types import ToriiAuth
+from torii_backend.verify import (
+    authenticate_request,
+    clear_jwks_cache_for_tests,
+    verify_token,
+    verify_webhook,
+)
+
+__all__ = [
+    "ToriiApiError",
+    "ToriiAuth",
+    "ToriiAuthError",
+    "ToriiClient",
+    "ToriiCreateUserInput",
+    "ToriiCursorPageUser",
+    "ToriiProblemDetail",
+    "ToriiSession",
+    "ToriiUpdateUserInput",
+    "ToriiUser",
+    "authenticate_request",
+    "clear_jwks_cache_for_tests",
+    "create_torii_client",
+    "verify_token",
+    "verify_webhook",
+]
+
+__version__ = "0.0.1"

torii_backend/client.py

@@ -0,0 +1,307 @@
+"""ToriiClient — entry point for the REST surface.
+
+Wraps the openapi-generator output under ``torii_backend.generated``
+behind a thin, hand-written facade so callers see ergonomic methods
+instead of the generator's verbose ``_request_timeout``/``_headers``/...
+parameter sprawl.
+
+Types and endpoints come from the OpenAPI spec via ``openapi-generator``;
+only the wrapper + auth helpers are hand-written. When the spec grows,
+regenerate and add a one-line wrapper method per new endpoint.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any
+from uuid import UUID
+
+from torii_backend.errors import ToriiApiError
+from torii_backend.generated import (
+    ApiClient,
+    ApiException,
+    Configuration,
+    ServerSessionsApi,
+    ServerUsersApi,
+)
+from torii_backend.generated.models import (
+    CreateUserRequest,
+    CursorPageResponseUserResponse,
+    ServerUserSearchRequest,
+    UpdateUserRequest,
+    UserResponse,
+    UserSessionResponse,
+)
+
+# Sentinel to distinguish "argument not passed" from "explicit None" in the
+# keyword-arg flavour of ``users.update`` / ``users.create``. We must NOT use
+# ``None`` for this purpose because PATCH semantics require ``None`` to mean
+# "clear this field on the server". See README "PATCH semantics".
+_UNSET: Any = object()
+
+DEFAULT_API_URL = "https://api.torii.so"
+
+
+class UsersClient:
+    def __init__(self, api: ServerUsersApi) -> None:
+        self._api = api
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | UUID | None = None,
+        name: str | None = None,
+        email: str | None = None,
+        statuses: list[str] | None = None,
+        created_after: str | datetime | None = None,
+        created_before: str | datetime | None = None,
+    ) -> CursorPageResponseUserResponse:
+        """Search users. Server-side cursor-paginated; loop with the
+        returned ``next_cursor`` until ``has_more`` is False."""
+        search = ServerUserSearchRequest.from_dict(
+            {
+                "name": name,
+                "email": email,
+                "statuses": statuses,
+                "createdAfter": created_after,
+                "createdBefore": created_before,
+            }
+        )
+        with _translate_api_error():
+            return self._api.search_users(
+                limit=limit,
+                cursor=_coerce_uuid(cursor),
+                server_user_search_request=search,
+            )
+
+    def get(self, user_id: str | UUID) -> UserResponse:
+        with _translate_api_error():
+            return self._api.get_user(_coerce_uuid(user_id))
+
+    def create(
+        self,
+        input: CreateUserRequest | dict[str, Any] | None = None,
+        *,
+        email: str | None = _UNSET,
+        password: str | None = _UNSET,
+        name: str | None = _UNSET,
+        phone: str | None = _UNSET,
+        address: str | None = _UNSET,
+        date_of_birth: str | date | None = _UNSET,
+    ) -> UserResponse:
+        """Create a user.
+
+        Two call shapes:
+          * Pass a ``CreateUserRequest`` / dict positionally; OR
+          * Pass keyword args directly (``email=...``, ``name=...``, etc.).
+        """
+        if input is not None:
+            body = (
+                input
+                if isinstance(input, CreateUserRequest)
+                else CreateUserRequest.from_dict(input)
+            )
+        else:
+            kwargs = {
+                "email": email,
+                "password": password,
+                "name": name,
+                "phone": phone,
+                "address": address,
+                "dateOfBirth": date_of_birth,
+            }
+            body = CreateUserRequest.model_validate(
+                {k: v for k, v in kwargs.items() if v is not _UNSET}
+            )
+        with _translate_api_error():
+            return self._api.create_user(body)
+
+    def update(
+        self,
+        user_id: str | UUID,
+        input: UpdateUserRequest | dict[str, Any] | None = None,
+        *,
+        name: str | None = _UNSET,
+        phone: str | None = _UNSET,
+        locale: str | None = _UNSET,
+        address: str | None = _UNSET,
+        date_of_birth: str | date | None = _UNSET,
+    ) -> UserResponse:
+        """Patch a user.
+
+        Tri-state PATCH semantics — only fields the caller explicitly set
+        are sent to the server:
+          * not passed → omitted from the JSON body → server leaves alone
+          * ``None``   → emitted as ``null``        → server clears
+          * value      → emitted with value         → server updates
+
+        Two call shapes:
+          * Pass an ``UpdateUserRequest`` / dict positionally; the request
+            model's ``model_fields_set`` drives which keys are sent; OR
+          * Pass keyword args directly (``name="Ada"``, ``phone=None``, ...).
+            Only the kwargs you pass appear on the wire.
+        """
+        if input is not None:
+            model = (
+                input
+                if isinstance(input, UpdateUserRequest)
+                else UpdateUserRequest.model_validate(input)
+            )
+        else:
+            kwargs = {
+                "name": name,
+                "phone": phone,
+                "locale": locale,
+                "address": address,
+                "dateOfBirth": date_of_birth,
+            }
+            model = UpdateUserRequest.model_validate(
+                {k: v for k, v in kwargs.items() if v is not _UNSET}
+            )
+        # Build the wire body from the model's *explicitly set* fields only.
+        # We must NOT pass the model through the generated ``update_user`` —
+        # it's wrapped in pydantic's ``@validate_call`` which would re-coerce
+        # the dict back into an ``UpdateUserRequest`` and then serialize via
+        # ``to_dict()`` (which uses ``exclude_none=True``). That collapses
+        # ``phone=None`` ("clear this field") into "omit", breaking tri-state.
+        # Drop down to the serializer + ``call_api`` directly so the dict we
+        # built survives untouched.
+        body = model.model_dump(exclude_unset=True, by_alias=True)
+        with _translate_api_error():
+            return self._patch_user(_coerce_uuid(user_id), body)
+
+    def _patch_user(self, user_id: Any, body: dict[str, Any]) -> UserResponse:
+        params = self._api._update_user_serialize(
+            user_id=user_id,
+            update_user_request=body,
+            _request_auth=None,
+            _content_type=None,
+            _headers=None,
+            _host_index=0,
+        )
+        response = self._api.api_client.call_api(*params)
+        response.read()
+        return self._api.api_client.response_deserialize(
+            response_data=response,
+            response_types_map={"200": "UserResponse"},
+        ).data
+
+    def delete(self, user_id: str | UUID) -> None:
+        with _translate_api_error():
+            self._api.delete_user(_coerce_uuid(user_id))
+
+    def ban(self, user_id: str | UUID) -> UserResponse:
+        with _translate_api_error():
+            return self._api.ban_user(_coerce_uuid(user_id))
+
+    def unban(self, user_id: str | UUID) -> UserResponse:
+        with _translate_api_error():
+            return self._api.unban_user(_coerce_uuid(user_id))
+
+
+class SessionsClient:
+    def __init__(self, api: ServerSessionsApi) -> None:
+        self._api = api
+
+    def list_for_user(self, user_id: str | UUID) -> list[UserSessionResponse]:
+        with _translate_api_error():
+            return self._api.list_sessions(_coerce_uuid(user_id))
+
+    def revoke_all_for_user(self, user_id: str | UUID) -> None:
+        with _translate_api_error():
+            self._api.revoke_all_sessions(_coerce_uuid(user_id))
+
+    def revoke(self, user_id: str | UUID, session_id: str | UUID) -> None:
+        with _translate_api_error():
+            self._api.revoke_session(_coerce_uuid(user_id), _coerce_uuid(session_id))
+
+
+class ToriiClient:
+    """Construct via :func:`create_torii_client`."""
+
+    def __init__(self, api_client: ApiClient) -> None:
+        self._api_client = api_client
+        self.users = UsersClient(ServerUsersApi(api_client))
+        self.sessions = SessionsClient(ServerSessionsApi(api_client))
+
+    def close(self) -> None:
+        self._api_client.close()
+
+    def __enter__(self) -> ToriiClient:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+
+def create_torii_client(
+    *,
+    secret_key: str,
+    api_url: str | None = None,
+) -> ToriiClient:
+    """Build a torii backend client.
+
+    Example::
+
+        torii = create_torii_client(secret_key=os.environ["TORII_SECRET_KEY"])
+        user = torii.users.get("user_abc")
+
+    ``api_url`` defaults to ``https://api.torii.so``. Override for staging
+    or self-hosted.
+    """
+    if not secret_key:
+        raise ValueError("create_torii_client: secret_key is required")
+    config = Configuration(host=(api_url or DEFAULT_API_URL).rstrip("/"))
+    api_client = ApiClient(configuration=config)
+    # Spec doesn't declare a securityScheme, so authorise via a default
+    # header on every request rather than the ``access_token`` config slot.
+    api_client.set_default_header("Authorization", f"Bearer {secret_key}")
+    return ToriiClient(api_client)
+
+
+def _coerce_uuid(value: str | UUID | None) -> Any:
+    """Generated methods accept UUID for path params. We let callers pass
+    either ``str`` or ``UUID`` and coerce here."""
+    if value is None:
+        return None
+    if isinstance(value, UUID):
+        return value
+    return UUID(value)
+
+
+class _translate_api_error:
+    """Context manager: re-raise the generator's ``ApiException`` as our
+    stable ``ToriiApiError`` so callers don't depend on generator
+    internals to catch failures."""
+
+    def __enter__(self) -> _translate_api_error:
+        return self
+
+    def __exit__(self, exc_type, exc, _tb) -> bool:
+        if exc is None or not isinstance(exc, ApiException):
+            return False
+        body: Any = exc.body
+        if isinstance(body, bytes):
+            try:
+                body = body.decode("utf-8")
+            except UnicodeDecodeError:
+                body = None
+        if isinstance(body, str):
+            try:
+                import json
+
+                body = json.loads(body)
+            except ValueError:
+                pass
+        message = _extract_message(body) or f"torii {exc.status} {exc.reason or ''}".strip()
+        raise ToriiApiError(message, exc.status or 0, body) from exc
+
+
+def _extract_message(body: Any) -> str | None:
+    if isinstance(body, dict):
+        for key in ("detail", "title", "message"):
+            value = body.get(key)
+            if isinstance(value, str):
+                return value
+    return None

torii_backend/errors.py

@@ -0,0 +1,42 @@
+"""Error types raised by torii_backend."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ToriiApiError(Exception):
+    """Raised when ``/api/server/v1/**`` responds non-2xx.
+
+    Inspect ``status``, ``code`` (from the RFC 7807 error body if present),
+    and ``support_id`` (echoed from the server's correlation id) for
+    diagnostics. ``body`` contains the raw parsed response.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        body: Any = None,
+    ):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.code: str | None = None
+        self.support_id: str | None = None
+        if isinstance(body, dict):
+            code = body.get("code")
+            support_id = body.get("supportId") or body.get("support_id")
+            if isinstance(code, str):
+                self.code = code
+            if isinstance(support_id, str):
+                self.support_id = support_id
+
+
+class ToriiAuthError(Exception):
+    """Raised by ``verify_token`` / ``authenticate_request`` when a token
+    cannot be verified (bad signature, wrong issuer, missing claims, ...)."""
+
+    def __init__(self, message: str, cause: BaseException | None = None):
+        super().__init__(message)
+        self.cause = cause

torii_backend/fastapi.py

@@ -0,0 +1,58 @@
+"""FastAPI dependency adapter.
+
+``fastapi`` is an optional install — depend on ``torii-backend[fastapi]``
+to pull it in. Importing this module without FastAPI raises a clear
+error so the dependency requirement is obvious.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+try:
+    from fastapi import HTTPException, Request
+except ImportError as e:  # pragma: no cover - import guard
+    raise ImportError(
+        "torii_backend.fastapi requires fastapi. Install with `pip install torii-backend[fastapi]`."
+    ) from e
+
+from torii_backend.errors import ToriiAuthError
+from torii_backend.types import ToriiAuth
+from torii_backend.verify import authenticate_request
+
+
+def require_auth(
+    *,
+    issuer: str,
+    audience: str | list[str] | None = None,
+    leeway: float = 30.0,
+) -> Callable[[Request], ToriiAuth]:
+    """Return a FastAPI dependency that authenticates the request.
+
+    Example::
+
+        from fastapi import Depends, FastAPI
+        from torii_backend.fastapi import require_auth
+
+        app = FastAPI()
+
+        @app.get("/me")
+        def me(auth = Depends(require_auth(issuer="https://acme.torii.so"))):
+            return {"user_id": auth.user_id}
+    """
+
+    def dependency(request: Request) -> ToriiAuth:
+        try:
+            return authenticate_request(
+                request.headers,
+                issuer=issuer,
+                audience=audience,
+                leeway=leeway,
+            )
+        except ToriiAuthError as exc:
+            raise HTTPException(
+                status_code=401,
+                detail={"code": "authentication_failed", "message": str(exc)},
+            ) from exc
+
+    return dependency

torii_backend/generated/__init__.py

@@ -0,0 +1,64 @@
+# coding: utf-8
+
+# flake8: noqa
+
+"""
+    OpenAPI definition
+
+    No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+    The version of the OpenAPI document: v0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+__version__ = "1.0.0"
+
+# Define package exports
+__all__ = [
+    "ServerSessionsApi",
+    "ServerUsersApi",
+    "ApiResponse",
+    "ApiClient",
+    "Configuration",
+    "OpenApiException",
+    "ApiTypeError",
+    "ApiValueError",
+    "ApiKeyError",
+    "ApiAttributeError",
+    "ApiException",
+    "CreateUserRequest",
+    "CursorPageResponseUserResponse",
+    "ProblemDetail",
+    "ServerUserSearchRequest",
+    "UpdateUserRequest",
+    "UserResponse",
+    "UserSessionResponse",
+]
+
+# import apis into sdk package
+from torii_backend.generated.api.server_sessions_api import ServerSessionsApi as ServerSessionsApi
+from torii_backend.generated.api.server_users_api import ServerUsersApi as ServerUsersApi
+
+# import ApiClient
+from torii_backend.generated.api_response import ApiResponse as ApiResponse
+from torii_backend.generated.api_client import ApiClient as ApiClient
+from torii_backend.generated.configuration import Configuration as Configuration
+from torii_backend.generated.exceptions import OpenApiException as OpenApiException
+from torii_backend.generated.exceptions import ApiTypeError as ApiTypeError
+from torii_backend.generated.exceptions import ApiValueError as ApiValueError
+from torii_backend.generated.exceptions import ApiKeyError as ApiKeyError
+from torii_backend.generated.exceptions import ApiAttributeError as ApiAttributeError
+from torii_backend.generated.exceptions import ApiException as ApiException
+
+# import models into sdk package
+from torii_backend.generated.models.create_user_request import CreateUserRequest as CreateUserRequest
+from torii_backend.generated.models.cursor_page_response_user_response import CursorPageResponseUserResponse as CursorPageResponseUserResponse
+from torii_backend.generated.models.problem_detail import ProblemDetail as ProblemDetail
+from torii_backend.generated.models.server_user_search_request import ServerUserSearchRequest as ServerUserSearchRequest
+from torii_backend.generated.models.update_user_request import UpdateUserRequest as UpdateUserRequest
+from torii_backend.generated.models.user_response import UserResponse as UserResponse
+from torii_backend.generated.models.user_session_response import UserSessionResponse as UserSessionResponse
+

torii_backend/generated/api/__init__.py

@@ -0,0 +1,6 @@
+# flake8: noqa
+
+# import apis into api package
+from torii_backend.generated.api.server_sessions_api import ServerSessionsApi
+from torii_backend.generated.api.server_users_api import ServerUsersApi
+