tausi 0.1.0__py3-none-any.whl

tausi/__init__.py

@@ -0,0 +1,39 @@
+"""Official Python SDK for Tausi.
+
+* :class:`TausiBackend` (secret key ``sk_...``): verify session tokens and manage users.
+* :class:`TausiClient` (publishable key ``pk_...``): sign users in from server-rendered apps, scripts and CLIs.
+* ``tausi.django`` and ``tausi.flask``: framework integrations.
+"""
+
+from ._http import SDK_VERSION, HttpResponse, Transport, urllib_transport
+from .backend import TausiBackend, bearer_token
+from .client import TausiClient, oauth_error_message, parse_oauth_redirect, random_device_id
+from .errors import TausiError
+from .models import AuthResult, OAuthStart, Page, Session, User
+from .pkce import create_pkce
+from .token_store import MappingTokenStore, MemoryTokenStore, TokenStore
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "SDK_VERSION",
+    "AuthResult",
+    "HttpResponse",
+    "MappingTokenStore",
+    "MemoryTokenStore",
+    "OAuthStart",
+    "Page",
+    "Session",
+    "TausiBackend",
+    "TausiClient",
+    "TausiError",
+    "TokenStore",
+    "Transport",
+    "User",
+    "bearer_token",
+    "create_pkce",
+    "oauth_error_message",
+    "parse_oauth_redirect",
+    "random_device_id",
+    "urllib_transport",
+]

tausi/_http.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple
+
+from .errors import TausiError
+
+SDK_VERSION = "0.1.0"
+
+
+@dataclass
+class HttpResponse:
+    status: int
+    headers: Dict[str, str]  # lower-cased names
+    body: bytes = b""
+
+    def header(self, name: str) -> Optional[str]:
+        return self.headers.get(name.lower())
+
+
+#: A transport sends one request and returns the raw response (any status).
+#: It raises OSError / TimeoutError for network problems. Swap it out for
+#: tests or to use requests/httpx: ``transport(method, url, headers, body, timeout)``.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], HttpResponse]
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:  # noqa: D401
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> HttpResponse:
+    """Default transport: the standard library, no dependencies."""
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with _opener.open(req, timeout=timeout) as res:
+            return HttpResponse(res.status, {k.lower(): v for k, v in res.headers.items()}, res.read())
+    except urllib.error.HTTPError as e:
+        return HttpResponse(e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, e.read() or b"")
+
+
+@dataclass
+class Http:
+    base_url: str
+    transport: Transport = urllib_transport
+    timeout: float = 10.0
+    user_agent: str = field(default=f"tausi-python/{SDK_VERSION}")
+
+    def __post_init__(self) -> None:
+        if not self.base_url.startswith(("http://", "https://")):
+            raise ValueError("base_url must be an absolute http(s) URL, e.g. https://tausi.app")
+        self.base = self.base_url.rstrip("/") + "/api/v1"
+
+    def request(self, method: str, path: str, headers: Mapping[str, str], body: Any = None) -> Tuple[Any, HttpResponse]:
+        """Sends one request. Returns ``(data, response)`` or raises TausiError."""
+        h = {"accept": "application/json", "user-agent": self.user_agent, **headers}
+        raw: Optional[bytes] = None
+        if body is not None:
+            h["content-type"] = "application/json"
+            raw = json.dumps(body).encode()
+        try:
+            res = self.transport(method, self.base + path, h, raw, self.timeout)
+        except (TimeoutError, socket.timeout) as e:
+            raise TausiError(0, "TIMEOUT", "The authentication server did not answer in time.", details=e) from e
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, (TimeoutError, socket.timeout)):
+                raise TausiError(0, "TIMEOUT", "The authentication server did not answer in time.", details=e) from e
+            raise TausiError(0, "NETWORK_ERROR", "Could not reach the authentication server.", details=e) from e
+        except OSError as e:
+            raise TausiError(0, "NETWORK_ERROR", "Could not reach the authentication server.", details=e) from e
+
+        payload: Dict[str, Any] = {}
+        if res.body:
+            try:
+                parsed = json.loads(res.body)
+                if isinstance(parsed, dict):
+                    payload = parsed
+            except ValueError:
+                pass
+        if 200 <= res.status < 300:
+            return payload.get("data"), res
+
+        err = payload.get("error") if isinstance(payload.get("error"), dict) else {}
+        retry: Optional[int] = None
+        try:
+            retry = int(res.header("retry-after") or "")
+            if retry <= 0:
+                retry = None
+        except ValueError:
+            pass
+        raise TausiError(
+            status=res.status,
+            code=str(err.get("code") or "UNKNOWN"),
+            message=str(err.get("message") or f"HTTP {res.status}"),
+            details=err.get("details"),
+            request_id=payload.get("requestId") or res.header("x-request-id"),
+            retry_after=retry,
+        )
+
+
+def query(params: Mapping[str, Any]) -> str:
+    clean = {}
+    for k, v in params.items():
+        if v is None:
+            continue
+        clean[k] = ("true" if v else "false") if isinstance(v, bool) else str(v)
+    return "?" + urllib.parse.urlencode(clean) if clean else ""
+
+
+def seg(s: str) -> str:
+    return urllib.parse.quote(s, safe="")

tausi/backend.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any, Dict, Mapping, Optional, Sequence, Union
+
+from ._http import Http, Transport, query, seg, urllib_transport
+from .errors import TausiError
+from .models import AuthResult, Page, Session, User
+
+_BEARER = re.compile(r"^Bearer\s+(\S+)$", re.IGNORECASE)
+
+
+def bearer_token(value: Any) -> Optional[str]:
+    """Reads the token from ``Authorization: Bearer <token>``.
+
+    Accepts the header value itself, a headers mapping, or any request
+    object with ``.headers`` (Django, Flask, Starlette...) or ``.META``.
+    """
+    header: Optional[str]
+    if value is None or isinstance(value, str):
+        header = value
+    else:
+        headers = getattr(value, "headers", None)
+        if headers is None and hasattr(value, "META"):
+            header = value.META.get("HTTP_AUTHORIZATION")
+        else:
+            src = headers if headers is not None else value
+            header = src.get("Authorization") or src.get("authorization")
+    m = _BEARER.match((header or "").strip())
+    return m.group(1) if m else None
+
+
+def _until(until: Optional[Union[datetime, str]], hours: Optional[float]) -> Dict[str, Any]:
+    if (until is None) == (hours is None):
+        raise ValueError("Pass either until= or hours=.")
+    if hours is not None:
+        return {"durationHours": hours}
+    if isinstance(until, datetime):
+        until = (until if until.tzinfo else until.replace(tzinfo=timezone.utc)).isoformat()
+    return {"until": until}
+
+
+class _Users:
+    def __init__(self, call: Any) -> None:
+        self._call = call
+
+    def list(
+        self,
+        q: Optional[str] = None,
+        verified: Optional[bool] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        access: Optional[str] = None,
+    ) -> Page[User]:
+        """``access``: "active", "suspended" or "banned"."""
+        d = self._call("GET", "/backend/users" + query({"q": q, "verified": verified, "access": access, "page": page, "pageSize": page_size}))
+        return Page([User.from_dict(u) for u in d["items"]], d["total"], d["page"], d["pageSize"])
+
+    def get(self, user_id: str) -> Dict[str, Any]:
+        """``{"user": User, "status", "activeSessions", "lastActiveAt", "accounts", "sessions", "recentAudit", ...}``."""
+        d = dict(self._call("GET", f"/backend/users/{seg(user_id)}"))
+        d["user"] = User.from_dict({**d["user"], "status": d.get("status"), "activeSessions": d.get("activeSessions"), "lastActiveAt": d.get("lastActiveAt")})
+        return d
+
+    def update(
+        self,
+        user_id: str,
+        name: Optional[str] = None,
+        email_verified: Optional[bool] = None,
+        *,
+        first_name: Any = ...,
+        last_name: Any = ...,
+        username: Any = ...,
+        phone_number: Any = ...,
+        phone_number_verified: Optional[bool] = None,
+        locale: Any = ...,
+        timezone: Any = ...,
+        public_metadata: Optional[Dict[str, Any]] = None,
+        private_metadata: Optional[Dict[str, Any]] = None,
+    ) -> User:
+        """Changes a user. Roles can't be changed with a secret key.
+
+        Leave an attribute out to keep it, pass None to clear it. Metadata
+        replaces the stored object as a whole (max 8 KB each); public metadata
+        is readable by the user, private metadata never leaves your backend.
+        """
+        from .client import _attrs
+
+        patch: Dict[str, Any] = {}
+        if name is not None:
+            patch["name"] = name
+        if email_verified is not None:
+            patch["emailVerified"] = email_verified
+        patch.update(_attrs(first_name=first_name, last_name=last_name, username=username, phone_number=phone_number, locale=locale, timezone=timezone, keep_none=True))
+        if phone_number_verified is not None:
+            patch["phoneNumberVerified"] = phone_number_verified
+        if public_metadata is not None:
+            patch["publicMetadata"] = public_metadata
+        if private_metadata is not None:
+            patch["privateMetadata"] = private_metadata
+        return User.from_dict(self._call("PATCH", f"/backend/users/{seg(user_id)}", patch)["user"])
+
+    def delete(self, user_id: str) -> None:
+        self._call("DELETE", f"/backend/users/{seg(user_id)}")
+
+    def ban(self, user_id: str, reason: Optional[str] = None) -> User:
+        """Bans until unbanned: signs the user out everywhere and refuses sign-in (ACCOUNT_BANNED).
+
+        ``reason`` is an internal note; the user never sees it.
+        """
+        return User.from_dict(self._call("POST", f"/backend/users/{seg(user_id)}/ban", {"reason": reason})["user"])
+
+    def unban(self, user_id: str) -> User:
+        return User.from_dict(self._call("DELETE", f"/backend/users/{seg(user_id)}/ban")["user"])
+
+    def suspend(
+        self,
+        user_id: str,
+        *,
+        until: Optional[Union[datetime, str]] = None,
+        hours: Optional[float] = None,
+        reason: Optional[str] = None,
+    ) -> User:
+        """Suspends for ``hours`` or until ``until`` (1 minute to 1 year): signs the user out and
+        refuses sign-in (ACCOUNT_SUSPENDED) until then. It lifts by itself."""
+        return User.from_dict(self._call("POST", f"/backend/users/{seg(user_id)}/suspend", {**_until(until, hours), "reason": reason})["user"])
+
+    def unsuspend(self, user_id: str) -> User:
+        return User.from_dict(self._call("DELETE", f"/backend/users/{seg(user_id)}/suspend")["user"])
+
+    def bulk(
+        self,
+        action: str,
+        ids: Sequence[str],
+        *,
+        reason: Optional[str] = None,
+        until: Optional[Union[datetime, str]] = None,
+        hours: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """One action on up to 100 users: "delete", "ban", "unban", "suspend", "unsuspend",
+        "revoke_sessions" or "verify_email". Returns ``{results: [{id, ok, error?}], succeeded, failed}``."""
+        body: Dict[str, Any] = {"action": action, "ids": list(ids)}
+        if reason is not None:
+            body["reason"] = reason
+        if until is not None or hours is not None:
+            body.update(_until(until, hours))
+        return dict(self._call("POST", "/backend/users/bulk", body))
+
+    def revoke_sessions(self, user_id: str) -> int:
+        """Signs the user out everywhere. Returns how many sessions were revoked."""
+        return int(self._call("POST", f"/backend/users/{seg(user_id)}/revoke-sessions", {})["revoked"])
+
+
+class _Sessions:
+    def __init__(self, call: Any) -> None:
+        self._call = call
+
+    def list(self, page: Optional[int] = None, page_size: Optional[int] = None) -> Page[Dict[str, Any]]:
+        d = self._call("GET", "/backend/sessions" + query({"page": page, "pageSize": page_size}))
+        return Page(list(d["items"]), d["total"], d["page"], d["pageSize"])
+
+
+class TausiBackend:
+    """Server-side client for one project, authenticated with its secret key.
+
+        tausi = TausiBackend("https://tausi.app", os.environ["TAUSI_SECRET_KEY"])
+        auth = tausi.authenticate_request(request)
+        if auth is None:
+            return 401
+    """
+
+    def __init__(self, base_url: str, secret_key: str, *, timeout: float = 10.0, transport: Transport = urllib_transport) -> None:
+        if not secret_key or not secret_key.startswith("sk_"):
+            raise ValueError("TausiBackend needs a project secret key (sk_...).")
+        self._http = Http(base_url, transport=transport, timeout=timeout)
+        self._headers = {"authorization": f"Bearer {secret_key}"}
+        self.users = _Users(self._call)
+        self.sessions = _Sessions(self._call)
+
+    def _call(self, method: str, path: str, body: Any = None) -> Any:
+        return self._http.request(method, path, self._headers, body)[0]
+
+    def verify_session(self, session_token: Optional[str]) -> Optional[AuthResult]:
+        """Checks a session token your frontend sent.
+
+        Returns None when it is unknown, expired, revoked, malformed or from
+        another project. Raises TausiError only for problems on your side
+        (bad key, network, 5xx).
+        """
+        if not session_token:
+            return None
+        try:
+            r = self._call("POST", "/backend/sessions/verify", {"sessionToken": session_token})
+        except TausiError as e:
+            if e.status == 400:  # malformed token
+                return None
+            raise
+        if not r or not r.get("valid") or not r.get("user") or not r.get("session"):
+            return None
+        return AuthResult(User.from_dict(r["user"]), Session.from_dict(r["session"]))
+
+    def authenticate_request(self, request: Any) -> Optional[AuthResult]:
+        """Reads the bearer token from a request (or header value) and verifies it."""
+        return self.verify_session(bearer_token(request))
+
+    def get_project(self) -> Mapping[str, Any]:
+        """The key's project ``{id, name, publishableKey}``: a startup check that the key works."""
+        return self._call("GET", "/backend/project")["project"]

tausi/client.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import secrets
+import urllib.parse
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
+
+from ._http import Http, Transport, seg, urllib_transport
+from .errors import TausiError
+from .models import AuthResult, OAuthStart, Session, User
+from .pkce import create_pkce
+from .token_store import MemoryTokenStore, TokenStore
+
+
+_ATTR_KEYS = {
+    "first_name": "firstName",
+    "last_name": "lastName",
+    "username": "username",
+    "phone_number": "phoneNumber",
+    "locale": "locale",
+    "timezone": "timezone",
+}
+
+
+def _attrs(keep_none: bool, **values: Any) -> Dict[str, Any]:
+    """Profile attributes in API casing. ``...`` means "leave out"; None clears (when editing)."""
+    out: Dict[str, Any] = {}
+    for py, value in values.items():
+        if value is ... or (value is None and not keep_none):
+            continue
+        out[_ATTR_KEYS[py]] = value
+    return out
+
+
+def _captcha(token: Optional[str]) -> Dict[str, str]:
+    """The bot-check token travels in a header (Tausi verifies it with Turnstile / hCaptcha)."""
+    return {"x-tausi-captcha": token} if token else {}
+
+
+def random_device_id() -> str:
+    """A random per-install ID for X-Tausi-Device. Persist it yourself (one per install or browser)."""
+    return secrets.token_hex(16)
+
+
+def parse_oauth_redirect(url: str) -> Tuple[Optional[str], Optional[str]]:
+    """``(code, error)`` from a redirect URL carrying ?tausi_code=… or ?tausi_error=…."""
+    qs = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    return (qs.get("tausi_code") or [None])[0], (qs.get("tausi_error") or [None])[0]
+
+
+def oauth_error_message(code: str) -> str:
+    """User-facing text for ?tausi_error codes."""
+    return {
+        "access_denied": "Sign-in was cancelled.",
+        "account_not_linked": "An account with this email already exists. Sign in with your password, or verify your email first.",
+        "email_not_verified": "Confirm your email address first. We've sent you a link.",
+        "email_not_found": "The provider didn't share your email address, which this app needs.",
+        "signup_limited": "Too many accounts have been created from this network or device.",
+        "account_banned": "This account has been banned.",
+        "account_suspended": "This account is suspended for now. Try again later.",
+        "device_required": "Sign up from the app.",
+    }.get(code, "Sign-in didn't complete. Please try again.")
+
+
+class TausiClient:
+    """End-user client (publishable key).
+
+    Use it for server-rendered apps where Python signs the user in and keeps
+    their token server-side (the Django or Flask session), and for scripts,
+    CLIs and desktop apps. Every method returns data or raises TausiError.
+
+        tausi = TausiClient("https://tausi.app", "pk_...")
+        result = tausi.sign_in("asha@example.com", "correct horse battery")
+        token = tausi.get_token()
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        publishable_key: str,
+        *,
+        token_store: Optional[TokenStore] = None,
+        device_id: Optional[str] = None,
+        origin: Optional[str] = None,
+        timeout: float = 10.0,
+        transport: Transport = urllib_transport,
+        on_session_change: Optional[Callable[[Optional[str]], None]] = None,
+    ) -> None:
+        if publishable_key and publishable_key.startswith("sk_"):
+            raise ValueError("Never use a secret key in TausiClient. Use TausiBackend for secret keys.")
+        if not publishable_key or not publishable_key.startswith("pk_"):
+            raise ValueError("TausiClient needs a publishable key (pk_...).")
+        self._http = Http(base_url, transport=transport, timeout=timeout)
+        self._key = publishable_key
+        self._store: TokenStore = token_store if token_store is not None else MemoryTokenStore()
+        self._device_id = device_id
+        self._origin = origin
+        self._on_change = on_session_change
+
+    # ---- token ----
+
+    def get_token(self) -> Optional[str]:
+        """The current session token: send it to your API as ``Authorization: Bearer``."""
+        return self._store.get()
+
+    def _set_token(self, token: Optional[str]) -> None:
+        self._store.set(token)
+        if self._on_change:
+            self._on_change(token)
+
+    def _call(self, method: str, path: str, body: Any = None, headers: Optional[Dict[str, str]] = None) -> Any:
+        extra = headers or {}
+        headers = {"x-tausi-key": self._key, **extra}
+        if self._device_id:
+            headers["x-tausi-device"] = self._device_id
+        if self._origin:
+            headers["origin"] = self._origin
+        token = self.get_token()
+        if token:
+            headers["authorization"] = f"Bearer {token}"
+        try:
+            data, res = self._http.request(method, path, headers, body)
+        except TausiError as e:
+            # A rejected token is useless: forget it so the app shows signed-out UI.
+            if e.status == 401 and e.code == "UNAUTHENTICATED" and token:
+                self._set_token(None)
+            raise
+        renewed = res.header("x-tausi-session-token")
+        if renewed and renewed != token:
+            self._set_token(renewed)
+        return data
+
+    def _signed_in(self, r: Mapping[str, Any]) -> AuthResult:
+        self._set_token(r["sessionToken"])
+        return AuthResult(User.from_dict(r["user"]), Session.from_dict(r["session"]))
+
+    # ---- email + password ----
+
+    def sign_up(
+        self,
+        email: str,
+        password: str,
+        name: str,
+        *,
+        first_name: Optional[str] = None,
+        last_name: Optional[str] = None,
+        username: Optional[str] = None,
+        phone_number: Optional[str] = None,
+        locale: Optional[str] = None,
+        timezone: Optional[str] = None,
+        redirect_to: Optional[str] = None,
+        captcha_token: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Creates an account: ``{message, verificationRequired}``. No session is created.
+
+        ``redirect_to`` is where the verification link sends the user (an allowed
+        origin or one of the project's Redirect URLs); default: the App URL.
+
+        Raises TausiError ``EMAIL_ALREADY_REGISTERED`` (409) when the email has
+        an account (its owner gets an email) and ``USERNAME_TAKEN`` for a taken username.
+        """
+        body: Dict[str, Any] = {"email": email, "password": password, "name": name}
+        body.update(_attrs(first_name=first_name, last_name=last_name, username=username, phone_number=phone_number, locale=locale, timezone=timezone, keep_none=False))
+        if redirect_to:
+            body["redirectTo"] = redirect_to
+        return self._call("POST", "/auth/sign-up/email", body, headers=_captcha(captcha_token))
+
+    def sign_in(self, email: str, password: str, remember_me: Optional[bool] = None, captcha_token: Optional[str] = None) -> AuthResult:
+        body: Dict[str, Any] = {"email": email, "password": password}
+        if remember_me is not None:
+            body["rememberMe"] = remember_me
+        return self._signed_in(self._call("POST", "/auth/sign-in/email", body, headers=_captcha(captcha_token)))
+
+    def sign_out(self) -> None:
+        """Ends the session on the server and forgets the token (even if the server is unreachable)."""
+        try:
+            if self.get_token():
+                self._call("POST", "/auth/sign-out", {})
+        finally:
+            self._set_token(None)
+
+    def get_session(self) -> Optional[AuthResult]:
+        """The signed-in user and session, or None (no request is made without a token)."""
+        if not self.get_token():
+            return None
+        try:
+            r = self._call("GET", "/auth/session")
+        except TausiError as e:
+            if e.status == 401:
+                return None
+            raise
+        if not r or not r.get("user") or not r.get("session"):
+            return None
+        return AuthResult(User.from_dict(r["user"]), Session.from_dict(r["session"]))
+
+    def send_verification_email(self, email: str, redirect_to: Optional[str] = None) -> Dict[str, Any]:
+        return self._call("POST", "/auth/send-verification-email", {"email": email, **({"redirectTo": redirect_to} if redirect_to else {})})
+
+    def verify_email(self, token: str) -> Dict[str, Any]:
+        return self._call("POST", "/auth/verify-email", {"token": token})
+
+    def forgot_password(self, email: str, redirect_to: Optional[str] = None, captcha_token: Optional[str] = None) -> Dict[str, Any]:
+        """``redirect_to``: the page (or deep link) the reset email opens, with ?token=…&type=password_reset."""
+        return self._call("POST", "/auth/forgot-password", {"email": email, **({"redirectTo": redirect_to} if redirect_to else {})}, headers=_captcha(captcha_token))
+
+    def get_captcha_config(self) -> Optional[Dict[str, Any]]:
+        """``{provider, siteKey, actions}`` when the project has a bot check, else None.
+        Render the provider's widget and pass its token as ``captcha_token``."""
+        return self._call("GET", "/auth/providers").get("captcha")
+
+    def reset_password(self, token: str, new_password: str) -> Dict[str, Any]:
+        return self._call("POST", "/auth/reset-password", {"token": token, "newPassword": new_password})
+
+    def change_password(self, current_password: str, new_password: str) -> None:
+        """Every other session is signed out and this one gets a fresh token."""
+        r = self._call("POST", "/auth/change-password", {"currentPassword": current_password, "newPassword": new_password})
+        if r and r.get("sessionToken"):
+            self._set_token(r["sessionToken"])
+
+    # ---- profile ----
+
+    def get_user(self) -> User:
+        return User.from_dict(self._call("GET", "/users/me")["user"])
+
+    def update_user(
+        self,
+        name: Optional[str] = None,
+        image: Any = ...,
+        *,
+        first_name: Any = ...,
+        last_name: Any = ...,
+        username: Any = ...,
+        phone_number: Any = ...,
+        locale: Any = ...,
+        timezone: Any = ...,
+    ) -> User:
+        """Edits the signed-in user's profile. Leave an argument out to keep it; pass None to clear it.
+
+        A new ``phone_number`` is unverified. Raises ``USERNAME_TAKEN`` (409) for a taken username.
+        """
+        patch: Dict[str, Any] = {}
+        if name is not None:
+            patch["name"] = name
+        if image is not ...:
+            patch["image"] = image
+        patch.update(_attrs(first_name=first_name, last_name=last_name, username=username, phone_number=phone_number, locale=locale, timezone=timezone, keep_none=True))
+        return User.from_dict(self._call("PATCH", "/users/me", patch)["user"])
+
+    def delete_account(self, password: str) -> None:
+        self._call("DELETE", "/users/me", {"password": password})
+        self._set_token(None)
+
+    # ---- sessions ----
+
+    def list_sessions(self) -> List[Dict[str, Any]]:
+        return list(self._call("GET", "/auth/sessions")["sessions"])
+
+    def revoke_session(self, session_id: str) -> None:
+        self._call("DELETE", f"/auth/sessions/{seg(session_id)}")
+
+    def revoke_other_sessions(self) -> int:
+        """Signs out every other device. Returns how many sessions were revoked."""
+        return int(self._call("DELETE", "/auth/sessions")["revoked"])
+
+    # ---- social sign-in ----
+
+    def get_providers(self) -> List[Dict[str, Any]]:
+        """Sign-in methods the project enabled: ``[{id, kind, displayName}, ...]``."""
+        return list(self._call("GET", "/auth/providers")["providers"])
+
+    def start_oauth(self, provider: str, redirect_to: str) -> OAuthStart:
+        """Starts a social sign-in with PKCE.
+
+        Redirect the browser to ``url`` and keep ``code_verifier``. The user
+        comes back to ``redirect_to`` (on one of the project's allowed
+        origins) with ?tausi_code=… or ?tausi_error=…; then call
+        :meth:`handle_oauth_redirect`.
+        """
+        verifier, challenge = create_pkce()
+        qs: Dict[str, str] = {
+            "key": self._key,
+            "redirect_to": redirect_to,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+        }
+        if self._device_id:
+            qs["device"] = self._device_id
+        return OAuthStart(f"{self._http.base}/auth/oauth/{seg(provider)}?{urllib.parse.urlencode(qs)}", verifier)
+
+    def exchange_oauth_code(self, code: str, code_verifier: str) -> AuthResult:
+        """Trades the one-time code for a session (stored like sign_in)."""
+        return self._signed_in(self._call("POST", "/auth/oauth/exchange", {"code": code, "codeVerifier": code_verifier}))
+
+    def handle_oauth_redirect(self, url: str, code_verifier: str) -> Optional[AuthResult]:
+        """Exchanges the code in ``url``, raises the provider error as TausiError (status 0), or returns None."""
+        code, error = parse_oauth_redirect(url)
+        if error:
+            raise TausiError(0, error, oauth_error_message(error))
+        return self.exchange_oauth_code(code, code_verifier) if code else None