fastapi-twitch 0.1.0__py3-none-any.whl

fastapi_twitch/__init__.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ._constants import DEFAULT_SCOPES
+from .core import TwitchOAuthClient
+from .exceptions import (
+    ConfigurationError,
+    InvalidPKCEError,
+    InvalidStateError,
+    OAuthError,
+    ScopeMissingError,
+    StateStoreError,
+    TwitchAPIError,
+    TwitchAuthError,
+)
+from .models import StatePayload, TokenSet, TwitchTokens, TwitchUser
+from .state import RedisStateStore, SessionStateStore, StateStore
+
+if TYPE_CHECKING:
+    from .integrations.fastapi import TwitchAuth
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_SCOPES",
+    "ConfigurationError",
+    "InvalidPKCEError",
+    "InvalidStateError",
+    "OAuthError",
+    "RedisStateStore",
+    "ScopeMissingError",
+    "SessionStateStore",
+    "StatePayload",
+    "StateStore",
+    "StateStoreError",
+    "TokenSet",
+    "TwitchAPIError",
+    "TwitchAuth",
+    "TwitchAuthError",
+    "TwitchOAuthClient",
+    "TwitchTokens",
+    "TwitchUser",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "TwitchAuth":
+        try:
+            from .integrations.fastapi import TwitchAuth as _TwitchAuth
+        except ImportError as exc:
+            raise ImportError(
+                "TwitchAuth requires the FastAPI extra: "
+                "`pip install 'fastapi-twitch[fastapi]'`"
+            ) from exc
+        return _TwitchAuth
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

fastapi_twitch/_constants.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+DEFAULT_SCOPES: tuple[str, ...] = ("user:read:email",)
+
+AUTH_URL = "https://id.twitch.tv/oauth2/authorize"
+TOKEN_URL = "https://id.twitch.tv/oauth2/token"
+VALIDATE_URL = "https://id.twitch.tv/oauth2/validate"
+REVOKE_URL = "https://id.twitch.tv/oauth2/revoke"
+HELIX_USERS_URL = "https://api.twitch.tv/helix/users"
+
+DEFAULT_TIMEOUT: float = 10.0
+DEFAULT_STATE_TTL_SECONDS: int = 600
+TOKEN_MASK_KEEP: int = 4
+MAX_HELIX_IDS_PER_REQUEST: int = 100

fastapi_twitch/core.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import urllib.parse
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from ._constants import (
+    AUTH_URL,
+    DEFAULT_TIMEOUT,
+    HELIX_USERS_URL,
+    MAX_HELIX_IDS_PER_REQUEST,
+    REVOKE_URL,
+    TOKEN_URL,
+    VALIDATE_URL,
+)
+from .exceptions import OAuthError, TwitchAPIError
+from .models import TokenSet, TwitchTokens, TwitchUser
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+class TwitchOAuthClient:
+    """Async Twitch OAuth 2.0 + Helix ``/users`` client.
+
+    Owns an :class:`httpx.AsyncClient` (or uses an injected one) and exposes
+    PKCE-aware login, code exchange, refresh, validation, revocation, and
+    account-data fetches. No FastAPI imports — safe to use from aiohttp,
+    plain asyncio scripts, or Celery tasks.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not client_id:
+            raise ValueError("client_id is required")
+        if not client_secret:
+            raise ValueError("client_secret is required")
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+    @property
+    def client_id(self) -> str:
+        return self._client_id
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> TwitchOAuthClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    @staticmethod
+    def generate_state() -> str:
+        """Cryptographically-strong state token (32 bytes, URL-safe)."""
+        return secrets.token_urlsafe(32)
+
+    @staticmethod
+    def generate_pkce_pair() -> tuple[str, str]:
+        """Return ``(code_verifier, code_challenge)`` for S256 PKCE."""
+        verifier = secrets.token_urlsafe(64)
+        return verifier, TwitchOAuthClient.challenge_for(verifier)
+
+    @staticmethod
+    def challenge_for(code_verifier: str) -> str:
+        """Return the S256 ``code_challenge`` matching a ``code_verifier``."""
+        return _b64url(hashlib.sha256(code_verifier.encode("ascii")).digest())
+
+    def login_url(
+        self,
+        *,
+        redirect_uri: str,
+        state: str,
+        code_challenge: str,
+        scopes: list[str],
+    ) -> str:
+        if not redirect_uri:
+            raise ValueError("redirect_uri is required")
+        if not state:
+            raise ValueError("state is required")
+        if not code_challenge:
+            raise ValueError("code_challenge is required")
+        params = {
+            "client_id": self._client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": " ".join(scopes),
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+        }
+        return f"{AUTH_URL}?{urllib.parse.urlencode(params)}"
+
+    def _auth_headers(self) -> dict[str, str]:
+        # RFC 6749 §2.3.1 - client_secret_basic
+        token = _b64url(f"{self._client_id}:{self._client_secret}".encode())
+        return {
+            "Authorization": f"Basic {token}",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        }
+
+    def _bearer_headers(self, access_token: str) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {access_token}",
+            "Client-Id": self._client_id,
+            "Accept": "application/json",
+        }
+
+    async def _post_form(self, url: str, data: dict[str, str]) -> dict[str, Any]:
+        try:
+            response = await self._http.post(url, data=data, headers=self._auth_headers())
+        except httpx.HTTPError as exc:
+            raise TwitchAPIError(0, str(exc)) from exc
+        return self._parse_json(response)
+
+    async def _post_empty(self, url: str, params: dict[str, str]) -> None:
+        try:
+            response = await self._http.post(url, params=params, headers=self._auth_headers())
+        except httpx.HTTPError as exc:
+            raise TwitchAPIError(0, str(exc)) from exc
+        if response.status_code >= 400:
+            raise TwitchAPIError(response.status_code, response.text)
+
+    @staticmethod
+    def _parse_json(response: httpx.Response) -> dict[str, Any]:
+        if response.status_code == 400:
+            # RFC 6749 error envelope
+            try:
+                payload = response.json()
+            except (ValueError, json.JSONDecodeError):
+                raise TwitchAPIError(response.status_code, response.text) from None
+            raise OAuthError(
+                str(payload.get("error", "unknown_error")),
+                payload.get("error_description"),
+            )
+        if response.status_code >= 400:
+            raise TwitchAPIError(response.status_code, response.text)
+        try:
+            payload = response.json()
+        except (ValueError, json.JSONDecodeError) as exc:
+            raise TwitchAPIError(response.status_code, response.text) from exc
+        if not isinstance(payload, dict):
+            raise TwitchAPIError(response.status_code, "non-object response")
+        return payload
+
+    @staticmethod
+    def _parse_tokens(payload: dict[str, Any]) -> TwitchTokens:
+        try:
+            return TwitchTokens(
+                access_token=payload["access_token"],
+                refresh_token=payload["refresh_token"],
+                expires_in=int(payload["expires_in"]),
+                scope=(
+                    payload.get("scope", "").split()
+                    if isinstance(payload.get("scope"), str)
+                    else list(payload.get("scope", []))
+                ),
+                obtained_at=datetime.now(timezone.utc),
+            )
+        except KeyError as exc:
+            raise OAuthError("invalid_response", f"missing field: {exc.args[0]}") from exc
+
+    async def exchange_code(
+        self,
+        *,
+        code: str,
+        redirect_uri: str,
+        code_verifier: str,
+    ) -> TwitchTokens:
+        """Trade an authorization code for a token set (PKCE-protected)."""
+        if not code:
+            raise ValueError("code is required")
+        if not redirect_uri:
+            raise ValueError("redirect_uri is required")
+        if not code_verifier:
+            raise ValueError("code_verifier is required")
+        payload = await self._post_form(
+            TOKEN_URL,
+            {
+                "client_id": self._client_id,
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "code_verifier": code_verifier,
+            },
+        )
+        return self._parse_tokens(payload)
+
+    async def refresh_tokens(self, *, refresh_token: str) -> TwitchTokens:
+        if not refresh_token:
+            raise ValueError("refresh_token is required")
+        payload = await self._post_form(
+            TOKEN_URL,
+            {
+                "client_id": self._client_id,
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+            },
+        )
+        return self._parse_tokens(payload)
+
+    async def validate(self, access_token: str) -> TwitchUser:
+        """Call ``GET /oauth2/validate`` to confirm a token + return minimal user."""
+        if not access_token:
+            raise ValueError("access_token is required")
+        try:
+            response = await self._http.get(
+                VALIDATE_URL,
+                headers={"Authorization": f"OAuth {access_token}"},
+            )
+        except httpx.HTTPError as exc:
+            raise TwitchAPIError(0, str(exc)) from exc
+        if response.status_code == 401:
+            raise TwitchAPIError(401, "token invalid or expired")
+        if response.status_code >= 400:
+            raise TwitchAPIError(response.status_code, response.text)
+        data = self._parse_json(response)
+        try:
+            return TwitchUser(
+                id=str(data["user_id"]),
+                login=data["login"],
+                scopes=data.get("scopes", []) or [],
+            )
+        except KeyError as exc:
+            raise OAuthError("invalid_response", f"missing field: {exc.args[0]}") from exc
+
+    async def revoke(self, *, token: str) -> None:
+        """Best-effort token revocation. Twitch always returns 200 even for unknown tokens."""
+        if not token:
+            raise ValueError("token is required")
+        await self._post_empty(REVOKE_URL, {"client_id": self._client_id, "token": token})
+
+    async def fetch_user(
+        self,
+        *,
+        access_token: str,
+        user_id: str | None = None,
+        login: str | None = None,
+    ) -> TwitchUser:
+        """Fetch one user via Helix ``GET /helix/users``.
+
+        Without ``user_id``/``login`` returns the current token holder.
+        """
+        users = await self.fetch_users(
+            access_token=access_token, ids=[user_id] if user_id else None,
+            logins=[login] if login else None,
+        )
+        if not users:
+            raise TwitchAPIError(404, "user not found")
+        return users[0]
+
+    async def fetch_users(
+        self,
+        *,
+        access_token: str,
+        ids: list[str] | None = None,
+        logins: list[str] | None = None,
+    ) -> list[TwitchUser]:
+        """Fetch up to 100 users at a time. Splits into batches automatically."""
+        if not access_token:
+            raise ValueError("access_token is required")
+        ids = ids or []
+        logins = logins or []
+        if not ids and not logins:
+            return [await self._fetch_helix_me(access_token)]
+
+        results: list[TwitchUser] = []
+        for chunk in _chunked(ids, MAX_HELIX_IDS_PER_REQUEST):
+            results.extend(await self._fetch_helix(access_token, id_=chunk, login=None))
+        for chunk in _chunked(logins, MAX_HELIX_IDS_PER_REQUEST):
+            results.extend(await self._fetch_helix(access_token, id_=None, login=chunk))
+        return results
+
+    async def _fetch_helix_me(self, access_token: str) -> TwitchUser:
+        try:
+            response = await self._http.get(
+                HELIX_USERS_URL, headers=self._bearer_headers(access_token)
+            )
+        except httpx.HTTPError as exc:
+            raise TwitchAPIError(0, str(exc)) from exc
+        users = self._parse_helix_users(response)
+        if not users:
+            raise TwitchAPIError(404, "user not found")
+        return users[0]
+
+    async def _fetch_helix(
+        self,
+        access_token: str,
+        *,
+        id_: list[str] | None,
+        login: list[str] | None,
+    ) -> list[TwitchUser]:
+        params: dict[str, Any] = {}
+        if id_:
+            params["id"] = id_
+        if login:
+            params["login"] = login
+        try:
+            response = await self._http.get(
+                HELIX_USERS_URL, params=params, headers=self._bearer_headers(access_token)
+            )
+        except httpx.HTTPError as exc:
+            raise TwitchAPIError(0, str(exc)) from exc
+        return self._parse_helix_users(response)
+
+    @staticmethod
+    def _parse_helix_users(response: httpx.Response) -> list[TwitchUser]:
+        if response.status_code == 401:
+            raise TwitchAPIError(401, "token invalid or expired")
+        if response.status_code >= 400:
+            raise TwitchAPIError(response.status_code, response.text)
+        try:
+            payload = response.json()
+        except (ValueError, json.JSONDecodeError) as exc:
+            raise TwitchAPIError(response.status_code, response.text) from exc
+        data = payload.get("data") or []
+        if not data:
+            return []
+        return [TwitchOAuthClient._parse_helix_user(item) for item in data]
+
+    @staticmethod
+    def _parse_helix_user(item: dict[str, Any]) -> TwitchUser:
+        created_at_raw = item.get("created_at")
+        created_at: datetime | None = None
+        if created_at_raw:
+            created_at = datetime.fromisoformat(created_at_raw.replace("Z", "+00:00"))
+        try:
+            return TwitchUser(
+                id=str(item["id"]),
+                login=item["login"],
+                display_name=item.get("display_name"),
+                type=item.get("type"),
+                broadcaster_type=item.get("broadcaster_type"),
+                description=item.get("description"),
+                profile_image_url=item.get("profile_image_url"),
+                offline_image_url=item.get("offline_image_url"),
+                view_count=item.get("view_count"),
+                email=item.get("email"),
+                created_at=created_at,
+            )
+        except KeyError as exc:
+            raise OAuthError("invalid_response", f"missing field: {exc.args[0]}") from exc
+
+    async def complete_login(
+        self,
+        *,
+        code: str,
+        redirect_uri: str,
+        code_verifier: str,
+    ) -> TokenSet:
+        """Exchange code → validate → fetch user. Best-effort Helix fetch."""
+        tokens = await self.exchange_code(
+            code=code, redirect_uri=redirect_uri, code_verifier=code_verifier
+        )
+        minimal = await self.validate(tokens.access_token)
+        try:
+            full = await self.fetch_user(access_token=tokens.access_token)
+            user = full.model_copy(update={"scopes": minimal.scopes or full.scopes})
+        except TwitchAPIError:
+            user = minimal
+        return TokenSet(tokens=tokens, user=user, validated_at=datetime.now(timezone.utc))
+
+
+def _chunked(items: list[str], size: int) -> list[list[str]]:
+    return [items[i : i + size] for i in range(0, len(items), size)]
+
+
+__all__ = ["TwitchOAuthClient"]

fastapi_twitch/exceptions.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+
+class TwitchAuthError(Exception):
+    """Base exception for all library errors."""
+
+
+class ConfigurationError(TwitchAuthError):
+    """Library is misconfigured (e.g. http:// redirect_uri in production)."""
+
+
+class StateStoreError(TwitchAuthError):
+    """State store backend failed."""
+
+
+class InvalidStateError(TwitchAuthError):
+    """OAuth state mismatch / missing / already used."""
+
+
+class InvalidPKCEError(TwitchAuthError):
+    """PKCE code_verifier missing or mismatched (server-side bug)."""
+
+
+class OAuthError(TwitchAuthError):
+    """Twitch returned an OAuth error response.
+
+    Maps to RFC 6749 §4.1.2.1 / §5.2 error codes
+    (e.g. ``invalid_grant``, ``invalid_client``).
+    """
+
+    def __init__(self, code: str, description: str | None = None) -> None:
+        self.code = code
+        self.description = description
+        super().__init__(f"{code}: {description}" if description else code)
+
+
+class TwitchAPIError(TwitchAuthError):
+    """Non-2xx response from Twitch (transport-level or Helix)."""
+
+    def __init__(self, status_code: int, body: str | None = None) -> None:
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"Twitch API returned {status_code}")
+
+
+class ScopeMissingError(TwitchAuthError):
+    """Requested data requires a scope the token does not have."""
+
+    def __init__(self, required: str, granted: list[str]) -> None:
+        self.required = required
+        self.granted = granted
+        super().__init__(f"scope '{required}' not granted (have: {granted})")