sweatstack 0.60.0__py3-none-any.whl → 0.62.0__py3-none-any.whl

sweatstack/fastapi/__init__.py

@@ -1,20 +1,52 @@
 """FastAPI integration for SweatStack authentication.
 
 This module provides OAuth authentication for FastAPI applications using
-SweatStack as the identity provider.
+SweatStack as the identity provider. It includes support for user switching,
+allowing applications like coaching platforms to view data on behalf of
+other users.
 
 Example:
     from fastapi import FastAPI
-    from sweatstack.fastapi import configure, instrument, AuthenticatedUser
+    from sweatstack.fastapi import configure, instrument, AuthenticatedUser, SelectedUser, urls
 
     configure()  # uses environment variables
 
     app = FastAPI()
     instrument(app)
 
-    @app.get("/me")
-    def get_me(user: AuthenticatedUser):
-        return user.client.get_userinfo()
+    @app.get("/activities")
+    def get_activities(user: SelectedUser):
+        # Returns activities for the currently selected user
+        return user.client.get_activities()
+
+    @app.get("/my-athletes")
+    def get_athletes(user: AuthenticatedUser):
+        # Always returns the principal user's accessible users
+        return user.client.get_users()
+
+User Switching:
+    The module supports two methods of user switching:
+
+    1. URL-based switching (recommended for web apps):
+        Use urls.select_user(user_id) and urls.select_self() in templates:
+
+        <form method="post" action="{{ urls.select_user(athlete.id) }}">
+            <button>View as {{ athlete.name }}</button>
+        </form>
+
+    2. Programmatic switching:
+        Call client.switch_user() in your endpoint code:
+
+        @app.post("/select/{athlete_id}")
+        def select(athlete_id: str, user: AuthenticatedUser):
+            user.client.switch_user(athlete_id)
+            return RedirectResponse("/dashboard")
+
+Dependency Types:
+    - AuthenticatedUser: Always returns the principal (logged-in) user
+    - OptionalUser: Returns principal or None if not authenticated
+    - SelectedUser: Returns the selected user (delegated or principal)
+    - OptionalSelectedUser: Returns selected user or None if not authenticated
 """
 
 try:
@@ -28,16 +60,51 @@ except ImportError:
 from .config import configure, urls
 from .dependencies import (
     AuthenticatedUser,
+    OptionalSelectedUser,
     OptionalUser,
+    SelectedUser,
     SweatStackUser,
 )
+from .models import StoredTokens, TokenStore
 from .routes import instrument
+from .token_stores import EncryptedSQLiteTokenStore, SQLiteTokenStore
+from .webhooks import (
+    WebhookError,
+    WebhookPayload,
+    WebhookPayloadModel,
+    WebhookTokenRefreshError,
+    WebhookTokenStoreError,
+    WebhookUserNotFoundError,
+    WebhookVerificationError,
+    verify_signature,
+)
 
 __all__ = [
+    # Configuration
     "configure",
     "instrument",
+    "urls",
+    # User types
+    "SweatStackUser",
+    # User dependencies
     "AuthenticatedUser",
     "OptionalUser",
-    "SweatStackUser",
-    "urls",
+    "SelectedUser",
+    "OptionalSelectedUser",
+    # Webhook dependencies
+    "WebhookPayload",
+    "WebhookPayloadModel",
+    # Token storage
+    "TokenStore",
+    "StoredTokens",
+    "SQLiteTokenStore",
+    "EncryptedSQLiteTokenStore",
+    # Webhook utilities
+    "verify_signature",
+    # Exceptions
+    "WebhookError",
+    "WebhookVerificationError",
+    "WebhookTokenStoreError",
+    "WebhookUserNotFoundError",
+    "WebhookTokenRefreshError",
 ]

sweatstack/fastapi/config.py

@@ -1,13 +1,19 @@
 """Module-level configuration for the FastAPI plugin."""
 
+from __future__ import annotations
+
 import logging
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 from urllib.parse import quote
 
 from cryptography.fernet import Fernet
 from pydantic import SecretStr
 
+if TYPE_CHECKING:
+    from .models import TokenStore
+
 logger = logging.getLogger(__name__)
 
 
@@ -35,6 +41,8 @@ class FastAPIConfig:
     cookie_max_age: int
     auth_route_prefix: str
     redirect_unauthenticated: bool
+    webhook_secret: SecretStr | None = None
+    token_store: TokenStore | None = None
 
     @property
     def redirect_uri(self) -> str:
@@ -63,6 +71,8 @@ def configure(
     cookie_max_age: int = 86400,
     auth_route_prefix: str = "/auth/sweatstack",
     redirect_unauthenticated: bool = True,
+    webhook_secret: str | SecretStr | None = None,
+    token_store: TokenStore | None = None,
 ) -> None:
     """Configure the FastAPI plugin.
 
@@ -82,6 +92,10 @@ def configure(
         auth_route_prefix: URL prefix for auth routes. Defaults to "/auth/sweatstack".
         redirect_unauthenticated: If True, redirect unauthenticated requests to login
             with ?next= set to the current path. If False, return 401. Defaults to True.
+        webhook_secret: Secret for verifying webhook signatures. Falls back to
+            SWEATSTACK_WEBHOOK_SECRET env var. Required if using WebhookPayload dependency.
+        token_store: TokenStore implementation for persisting tokens. Required if using
+            AuthenticatedUser in webhook handlers.
     """
     global _config
 
@@ -90,6 +104,7 @@ def configure(
     client_secret = client_secret or os.environ.get("SWEATSTACK_CLIENT_SECRET")
     app_url = app_url or os.environ.get("APP_URL")
     session_secret = session_secret or os.environ.get("SWEATSTACK_SESSION_SECRET")
+    webhook_secret = webhook_secret or os.environ.get("SWEATSTACK_WEBHOOK_SECRET")
 
     # Validate required parameters
     if not client_id:
@@ -129,6 +144,9 @@ def configure(
     # Normalize prefix (strip trailing slash)
     auth_route_prefix = auth_route_prefix.rstrip("/")
 
+    # Convert webhook_secret to SecretStr if provided
+    webhook_secret_obj = _to_secret(webhook_secret) if webhook_secret else None
+
     _config = FastAPIConfig(
         client_id=client_id,
         client_secret=client_secret_obj,
@@ -139,6 +157,8 @@ def configure(
         cookie_max_age=cookie_max_age,
         auth_route_prefix=auth_route_prefix,
         redirect_unauthenticated=redirect_unauthenticated,
+        webhook_secret=webhook_secret_obj,
+        token_store=token_store,
     )
 
 
@@ -156,7 +176,20 @@ def get_config() -> FastAPIConfig:
 
 
 class _Urls:
-    """URL helpers for the FastAPI plugin."""
+    """URL helpers for the FastAPI plugin.
+
+    Provides methods to generate URLs for authentication and user selection routes.
+    These URLs can be used in templates or redirects.
+
+    Example:
+        from sweatstack.fastapi import urls
+
+        # In a template:
+        <a href="{{ urls.login() }}">Login</a>
+        <form method="post" action="{{ urls.select_user(athlete.id) }}">
+            <button>View as {{ athlete.name }}</button>
+        </form>
+    """
 
     def login(self, next: str | None = None) -> str:
         """Get the login URL.
@@ -173,5 +206,38 @@ class _Urls:
         """Get the logout URL."""
         return f"{get_config().auth_route_prefix}/logout"
 
+    def select_user(self, user_id: str, next: str | None = None) -> str:
+        """Get the URL to switch to viewing as another user.
+
+        Args:
+            user_id: The ID of the user to view as.
+            next: Optional path to redirect to after switching.
+
+        Example:
+            <form method="post" action="{{ urls.select_user(athlete.id) }}">
+                <button>View as {{ athlete.name }}</button>
+            </form>
+        """
+        base = f"{get_config().auth_route_prefix}/select-user/{user_id}"
+        if next:
+            return f"{base}?next={quote(next)}"
+        return base
+
+    def select_self(self, next: str | None = None) -> str:
+        """Get the URL to switch back to viewing as yourself.
+
+        Args:
+            next: Optional path to redirect to after switching.
+
+        Example:
+            <form method="post" action="{{ urls.select_self() }}">
+                <button>Back to my view</button>
+            </form>
+        """
+        base = f"{get_config().auth_route_prefix}/select-self"
+        if next:
+            return f"{base}?next={quote(next)}"
+        return base
+
 
 urls = _Urls()

sweatstack/fastapi/dependencies.py

@@ -1,9 +1,12 @@
 """FastAPI dependencies for authentication."""
 
+from __future__ import annotations
+
 import logging
 import time
 from dataclasses import dataclass
-from typing import Annotated, NoReturn, TypeAlias
+from datetime import datetime, timezone
+from typing import Annotated, NoReturn
 from urllib.parse import quote
 
 import httpx
@@ -13,6 +16,7 @@ from ..client import Client
 from ..constants import DEFAULT_URL
 from ..utils import decode_jwt_body
 from .config import get_config
+from .models import SessionData, StoredTokens, TokenSet, extract_user_id
 from .session import (
     SESSION_COOKIE_NAME,
     clear_session_cookie,
@@ -20,33 +24,54 @@ from .session import (
     set_session_cookie,
 )
 
+logger = logging.getLogger(__name__)
+
 TOKEN_EXPIRY_MARGIN = 5  # seconds
 
 
-@dataclass
+@dataclass(slots=True)
 class SweatStackUser:
     """Authenticated SweatStack user.
 
     Attributes:
-        user_id: The user's SweatStack ID.
         client: An authenticated Client instance for API calls.
     """
 
-    user_id: str
     client: Client
 
+    @property
+    def user_id(self) -> str:
+        """The user ID this client acts as."""
+        return extract_user_id(self.client.api_key)
+
 
-def is_token_expiring(token: str) -> bool:
+# ---------------------------------------------------------------------------
+# Token refresh
+# ---------------------------------------------------------------------------
+
+
+def _is_token_expiring(token: str) -> bool:
     """Check if a token is within TOKEN_EXPIRY_MARGIN seconds of expiring."""
     try:
         body = decode_jwt_body(token)
         return body["exp"] - TOKEN_EXPIRY_MARGIN < time.time()
     except Exception:
-        # If we can't decode, assume it's expired
         return True
 
 
-def refresh_access_token(
+def _extract_expiry(access_token: str) -> datetime:
+    """Extract expiry time from JWT access token."""
+    body = decode_jwt_body(access_token)
+    return datetime.fromtimestamp(body["exp"], tz=timezone.utc)
+
+
+def _extract_timezone(access_token: str) -> str:
+    """Extract timezone from JWT access token."""
+    body = decode_jwt_body(access_token)
+    return body.get("tz", "UTC")
+
+
+def _refresh_access_token(
     refresh_token: str,
     client_id: str,
     client_secret: str,
@@ -67,12 +92,39 @@ def refresh_access_token(
     return response.json()["access_token"]
 
 
-def _raise_unauthenticated(request: Request) -> NoReturn:
-    """Raise appropriate exception for unauthenticated requests.
+def _refresh_tokens_if_needed(tokens: TokenSet) -> TokenSet | None:
+    """Refresh tokens if the access token is expiring.
 
-    If redirect_unauthenticated is True, redirects to login with ?next= set.
-    Otherwise, raises 401 Unauthorized.
+    Returns new TokenSet if refreshed, None if no refresh needed.
     """
+    if not _is_token_expiring(tokens.access_token):
+        return None
+
+    token_body = decode_jwt_body(tokens.access_token)
+    tz = token_body.get("tz", "UTC")
+
+    config = get_config()
+    new_access_token = _refresh_access_token(
+        refresh_token=tokens.refresh_token,
+        client_id=config.client_id,
+        client_secret=config.client_secret.get_secret_value(),
+        tz=tz,
+    )
+
+    return TokenSet(
+        access_token=new_access_token,
+        refresh_token=tokens.refresh_token,
+        user_id=tokens.user_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Session helpers
+# ---------------------------------------------------------------------------
+
+
+def _raise_unauthenticated(request: Request) -> NoReturn:
+    """Raise appropriate exception for unauthenticated requests."""
     config = get_config()
     if config.redirect_unauthenticated:
         next_url = request.url.path
@@ -83,79 +135,272 @@ def _raise_unauthenticated(request: Request) -> NoReturn:
     raise HTTPException(status_code=401, detail="Not authenticated")
 
 
-def require_user(request: Request, response: Response) -> SweatStackUser:
-    """Dependency that requires an authenticated user.
-
-    Returns a SweatStackUser if the session is valid. If not authenticated,
-    behavior depends on the redirect_unauthenticated config:
-    - If True: redirects to login with ?next= set to current path
-    - If False: raises 401 Unauthorized
+def _get_session_or_raise(request: Request) -> SessionData:
+    """Get and validate session data, raising if invalid."""
+    raw_session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
+    if not raw_session:
+        _raise_unauthenticated(request)
 
-    Automatically refreshes tokens if they are about to expire.
-    """
-    session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
-    if not session:
+    try:
+        return SessionData.from_dict(raw_session)
+    except (KeyError, TypeError):
         _raise_unauthenticated(request)
 
-    access_token = session.get("access_token")
-    refresh_token = session.get("refresh_token")
-    user_id = session.get("user_id")
 
-    if not access_token or not user_id:
-        clear_session_cookie(response)
-        _raise_unauthenticated(request)
+def _get_session_or_none(request: Request) -> SessionData | None:
+    """Get session data if present and valid, None otherwise."""
+    raw_session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
+    if not raw_session:
+        return None
 
-    # Check if token needs refresh
-    if is_token_expiring(access_token):
-        if not refresh_token:
-            clear_session_cookie(response)
-            _raise_unauthenticated(request)
+    try:
+        return SessionData.from_dict(raw_session)
+    except (KeyError, TypeError):
+        return None
 
-        try:
-            # Extract timezone from current token
-            token_body = decode_jwt_body(access_token)
-            tz = token_body.get("tz", "UTC")
 
-            config = get_config()
-            new_access_token = refresh_access_token(
-                refresh_token=refresh_token,
+# ---------------------------------------------------------------------------
+# Webhook user loading
+# ---------------------------------------------------------------------------
+
+
+def _load_user_from_store(user_id: str) -> SweatStackUser:
+    """Load user from TokenStore for webhook context.
+
+    Args:
+        user_id: The user ID from the webhook payload.
+
+    Returns:
+        SweatStackUser with tokens loaded from the store.
+
+    Raises:
+        WebhookTokenStoreError: If token_store is not configured.
+        WebhookUserNotFoundError: If no tokens exist for the user.
+        WebhookTokenRefreshError: If token refresh fails.
+    """
+    # Import here to avoid circular imports
+    from .webhooks import (
+        WebhookTokenRefreshError,
+        WebhookTokenStoreError,
+        WebhookUserNotFoundError,
+    )
+
+    config = get_config()
+
+    if not config.token_store:
+        raise WebhookTokenStoreError(
+            "TokenStore required when using AuthenticatedUser in webhook handlers. "
+            "Configure with: configure(token_store=...)"
+        )
+
+    tokens = config.token_store.load(user_id)
+    if not tokens:
+        raise WebhookUserNotFoundError(
+            f"No stored tokens for user {user_id}. "
+            "User may not have authenticated with your app yet."
+        )
+
+    # Check if tokens need refresh
+    if _is_token_expiring(tokens.access_token):
+        try:
+            new_access_token = _refresh_access_token(
+                refresh_token=tokens.refresh_token,
                 client_id=config.client_id,
-                client_secret=config.client_secret,
-                tz=tz,
+                client_secret=config.client_secret.get_secret_value(),
+                tz=_extract_timezone(tokens.access_token),
+            )
+
+            tokens = StoredTokens(
+                user_id=tokens.user_id,
+                access_token=new_access_token,
+                refresh_token=tokens.refresh_token,
+                expires_at=_extract_expiry(new_access_token),
             )
 
-            # Update session with new token
-            session["access_token"] = new_access_token
-            set_session_cookie(response, session)
-            access_token = new_access_token
+            config.token_store.save(tokens)
+
+        except Exception as e:
+            raise WebhookTokenRefreshError(
+                f"Failed to refresh tokens for user {user_id}: {e}"
+            ) from e
 
-        except Exception:
-            logging.exception("Token refresh failed for user %s", user_id)
-            clear_session_cookie(response)
-            _raise_unauthenticated(request)
+    return SweatStackUser(
+        client=Client(
+            api_key=tokens.access_token,
+            refresh_token=tokens.refresh_token,
+            client_id=config.client_id,
+            client_secret=config.client_secret,
+        )
+    )
 
+
+# ---------------------------------------------------------------------------
+# Core dependency logic
+# ---------------------------------------------------------------------------
+
+
+def _create_user(
+    session: SessionData,
+    response: Response,
+    *,
+    use_delegated: bool,
+) -> SweatStackUser:
+    """Create user from session, refreshing tokens if needed."""
     config = get_config()
-    client = Client(
-        api_key=access_token,
-        refresh_token=refresh_token,
-        client_id=config.client_id,
-        client_secret=config.client_secret,  # Client accepts SecretStr directly
+
+    # Select which tokens to use
+    if use_delegated and session.delegated:
+        tokens = session.delegated
+        is_delegated = True
+    else:
+        tokens = session.principal
+        is_delegated = False
+
+    # Refresh tokens if needed and persist immediately
+    try:
+        refreshed = _refresh_tokens_if_needed(tokens)
+    except Exception:
+        logger.exception("Token refresh failed for user %s", tokens.user_id)
+        clear_session_cookie(response)
+        raise HTTPException(status_code=401, detail="Session expired")
+
+    if refreshed:
+        # Update session with refreshed tokens
+        if is_delegated:
+            session = SessionData(principal=session.principal, delegated=refreshed)
+        else:
+            session = SessionData(principal=refreshed, delegated=session.delegated)
+            # Persist refreshed principal tokens to store if configured
+            if config.token_store:
+                config.token_store.save(
+                    StoredTokens(
+                        user_id=refreshed.user_id,
+                        access_token=refreshed.access_token,
+                        refresh_token=refreshed.refresh_token,
+                        expires_at=_extract_expiry(refreshed.access_token),
+                    )
+                )
+        tokens = refreshed
+        set_session_cookie(response, session.to_dict())
+
+    return SweatStackUser(
+        client=Client(
+            api_key=tokens.access_token,
+            refresh_token=tokens.refresh_token,
+            client_id=config.client_id,
+            client_secret=config.client_secret,
+        )
     )
-    return SweatStackUser(user_id=user_id, client=client)
 
 
-def optional_user(request: Request, response: Response) -> SweatStackUser | None:
-    """Dependency that optionally returns an authenticated user.
+# ---------------------------------------------------------------------------
+# Dependency functions
+# ---------------------------------------------------------------------------
+
 
-    Returns a SweatStackUser if the session is valid, None otherwise.
-    Does not raise exceptions for missing or invalid sessions.
+async def _require_authenticated_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser:
+    """Dependency: always returns principal user.
+
+    In webhook context (detected by X-Sweatstack-Signature header),
+    loads the user from TokenStore instead of session cookie.
     """
+    # Import here to avoid circular imports
+    from .webhooks import WebhookPayloadModel, _detect_webhook_context
+
+    # Check if this is a webhook request
+    webhook_context: WebhookPayloadModel | None = await _detect_webhook_context(request)
+
+    if webhook_context:
+        # Webhook context: load from TokenStore
+        return _load_user_from_store(webhook_context.user_id)
+
+    # Browser context: load from cookie
+    session = _get_session_or_raise(request)
+    return _create_user(session, response, use_delegated=False)
+
+
+def _require_selected_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser:
+    """Dependency: returns delegated user if selected, otherwise principal."""
+    session = _get_session_or_raise(request)
+    return _create_user(session, response, use_delegated=True)
+
+
+def _optional_authenticated_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser | None:
+    """Dependency: returns principal user or None."""
+    session = _get_session_or_none(request)
+    if not session:
+        return None
     try:
-        return require_user(request, response)
+        return _create_user(session, response, use_delegated=False)
     except HTTPException:
         return None
 
 
-# Type aliases for use in route handlers
-AuthenticatedUser: TypeAlias = Annotated[SweatStackUser, Depends(require_user)]
-OptionalUser: TypeAlias = Annotated[SweatStackUser | None, Depends(optional_user)]
+def _optional_selected_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser | None:
+    """Dependency: returns selected user or None."""
+    session = _get_session_or_none(request)
+    if not session:
+        return None
+    try:
+        return _create_user(session, response, use_delegated=True)
+    except HTTPException:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Public type aliases
+# ---------------------------------------------------------------------------
+
+AuthenticatedUser = Annotated[SweatStackUser, Depends(_require_authenticated_user)]
+"""Dependency that always returns the principal (logged-in) user.
+
+Example:
+    @app.get("/my-athletes")
+    def get_athletes(user: AuthenticatedUser):
+        return user.client.get_users()
+"""
+
+SelectedUser = Annotated[SweatStackUser, Depends(_require_selected_user)]
+"""Dependency that returns the currently selected user.
+
+Returns the delegated user if one is selected, otherwise the principal user.
+
+Example:
+    @app.get("/activities")
+    def get_activities(user: SelectedUser):
+        return user.client.get_activities()
+"""
+
+OptionalUser = Annotated[SweatStackUser | None, Depends(_optional_authenticated_user)]
+"""Dependency that returns the principal user or None if not authenticated.
+
+Example:
+    @app.get("/")
+    def home(user: OptionalUser):
+        if user:
+            return {"logged_in": True, "user_id": user.user_id}
+        return {"logged_in": False}
+"""
+
+OptionalSelectedUser = Annotated[SweatStackUser | None, Depends(_optional_selected_user)]
+"""Dependency that returns the selected user or None if not authenticated.
+
+Example:
+    @app.get("/public-profile")
+    def profile(user: OptionalSelectedUser):
+        if user:
+            return user.client.get_user()
+        return {"message": "Not logged in"}
+"""