sweatstack 0.59.0__py3-none-any.whl → 0.61.0__py3-none-any.whl

sweatstack/client.py

@@ -19,6 +19,8 @@ from importlib.metadata import version
 from io import BytesIO
 from pathlib import Path
 from typing import Any, Dict, Generator, get_type_hints, List, Literal
+
+from pydantic import SecretStr
 from urllib.parse import parse_qs, urlparse
 
 import httpx
@@ -86,7 +88,7 @@ class _LocalCacheMixin:
             raise ValueError("Not authenticated. Please call authenticate() or login() first.")
 
         try:
-            jwt_body = decode_jwt_body(self.api_key)
+            jwt_body = decode_jwt_body(self.api_key.get_secret_value())
             user_id = jwt_body.get("sub")
             if not user_id:
                 raise ValueError("Unable to extract user ID from token")
@@ -208,6 +210,15 @@ except ImportError:
     __version__ = "unknown"
 
 
+def _to_secret(value: str | SecretStr | None) -> SecretStr | None:
+    """Convert a string to SecretStr, or return None if value is None."""
+    if value is None:
+        return None
+    if isinstance(value, SecretStr):
+        return value
+    return SecretStr(value)
+
+
 class _OAuth2Mixin:
     """OAuth2 authentication methods for the Client class."""
 
@@ -317,7 +328,6 @@ class _OAuth2Mixin:
         token_response = TokenResponse.model_validate(response.json())
 
         self.api_key = token_response.access_token
-        self.jwt = token_response.access_token  # For backward compatibility
         self.refresh_token = token_response.refresh_token
 
         if persist:
@@ -400,13 +410,12 @@ class _OAuth2Mixin:
 
         if hasattr(server, "code"):
             try:
-                token_response = self.exchange_code_for_token(
+                self.exchange_code_for_token(
                     code=server.code,
                     client_id=OAUTH2_CLIENT_ID,
                     code_verifier=code_verifier,
                     persist=persist_api_key,
                 )
-                self.jwt = token_response.access_token
                 print("SweatStack Python login successful.")
             except Exception as e:
                 raise Exception("SweatStack Python login failed. Please try again.") from e
@@ -665,12 +674,12 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
     def __init__(
         self,
-        api_key: str | None = None,
-        refresh_token: str | None = None,
+        api_key: str | SecretStr | None = None,
+        refresh_token: str | SecretStr | None = None,
         url: str | None = None,
         streamlit_compatible: bool = False,
         client_id: str | None = None,
-        client_secret: str | None = None,
+        client_secret: str | SecretStr | None = None,
     ):
         """Initialize a SweatStack client.
 
@@ -679,16 +688,18 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             refresh_token: Optional refresh token for automatic token renewal.
             url: Optional SweatStack instance URL. Defaults to production.
             streamlit_compatible: Set to True when using in Streamlit apps.
+            client_id: Optional OAuth client ID. Defaults to the public client ID.
+            client_secret: Optional OAuth client secret for confidential clients.
         """
-        self.api_key = api_key
-        self.refresh_token = refresh_token
+        self._api_key: SecretStr | None = _to_secret(api_key)
+        self._refresh_token: SecretStr | None = _to_secret(refresh_token)
+        self._client_secret: SecretStr | None = _to_secret(client_secret)
         self.url = url
         self.streamlit_compatible = streamlit_compatible
         self.client_id = client_id or OAUTH2_CLIENT_ID
-        self.client_secret = client_secret
 
     def _do_token_refresh(self, tz: str) -> str:
-        refresh_token = self.refresh_token
+        refresh_token = self._refresh_token
         if refresh_token is None:
             raise ValueError(
                 "Cannot refresh token: no refresh_token available. "
@@ -700,10 +711,10 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 "/api/v1/oauth/token",
                 data={
                     "grant_type": "refresh_token",
-                    "refresh_token": refresh_token,
+                    "refresh_token": refresh_token.get_secret_value(),
                     "tz": tz,
                     "client_id": self.client_id,
-                    "client_secret": self.client_secret,
+                    "client_secret": self._client_secret.get_secret_value() if self._client_secret else None,
                 },
             )
             self._raise_for_status(response)
@@ -717,7 +728,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             if body["exp"] - TOKEN_EXPIRY_MARGIN < time.time():
                 # Token is (almost) expired, refresh it
                 token = self._do_token_refresh(body["tz"])
-                self._api_key = token
+                self._api_key = SecretStr(token)
         except Exception as exception:
             logging.warning("Exception checking token expiry: %s", exception)
             # If token can't be decoded, just return as-is
@@ -727,14 +738,17 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         return token
 
     @property
-    def api_key(self) -> str:
+    def api_key(self) -> SecretStr | None:
         """The current API access token.
 
         Automatically loads from instance, environment (SWEATSTACK_API_KEY),
         or persistent storage. Refreshes expired tokens automatically.
+
+        Returns a SecretStr to prevent accidental logging of the token.
+        Use .get_secret_value() to get the actual token string.
         """
         if self._api_key is not None:
-            value = self._api_key
+            value = self._api_key.get_secret_value()
         elif value := os.getenv("SWEATSTACK_API_KEY"):
             pass
         else:
@@ -744,30 +758,56 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             # A non-authenticated client is a potentially valid use-case.
             return None
 
-        return self._check_token_expiry(value)
+        # Check expiry and potentially refresh (returns the string value)
+        checked_value = self._check_token_expiry(value)
+        return SecretStr(checked_value)
 
     @api_key.setter
-    def api_key(self, value: str):
-        self._api_key = value
+    def api_key(self, value: str | SecretStr | None):
+        self._api_key = _to_secret(value)
     
     @property
-    def refresh_token(self) -> str:
+    def refresh_token(self) -> SecretStr | None:
         """The refresh token used for automatic token renewal.
 
         Loads from instance, environment (SWEATSTACK_REFRESH_TOKEN), or persistent storage.
+
+        Returns a SecretStr to prevent accidental logging of the token.
+        Use .get_secret_value() to get the actual token string.
         """
         if self._refresh_token is not None:
             return self._refresh_token
         elif value := os.getenv("SWEATSTACK_REFRESH_TOKEN"):
-            pass
+            return SecretStr(value)
         else:
             _, value = self._load_persistent_tokens()
-
-        return value
+            return _to_secret(value)
 
     @refresh_token.setter
-    def refresh_token(self, value: str):
-        self._refresh_token = value
+    def refresh_token(self, value: str | SecretStr | None):
+        self._refresh_token = _to_secret(value)
+
+    @property
+    def client_secret(self) -> SecretStr | None:
+        """The OAuth client secret for confidential clients.
+
+        Returns a SecretStr to prevent accidental logging of the secret.
+        Use .get_secret_value() to get the actual secret string.
+        """
+        return self._client_secret
+
+    @client_secret.setter
+    def client_secret(self, value: str | SecretStr | None):
+        self._client_secret = _to_secret(value)
+
+    @property
+    def jwt(self) -> SecretStr | None:
+        """Alias for api_key (backward compatibility)."""
+        return self.api_key
+
+    @jwt.setter
+    def jwt(self, value: str | SecretStr | None):
+        self.api_key = value
 
     @property
     def url(self) -> str:
@@ -808,7 +848,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             token = self.api_key
 
         if token:
-            headers["Authorization"] = f"Bearer {token}"
+            headers["Authorization"] = f"Bearer {token.get_secret_value()}"
 
         with httpx.Client(base_url=self.url, headers=headers, timeout=60) as client:
             yield client
@@ -1644,7 +1684,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             raise ValueError("Not authenticated. Please call authenticate() or login() first.")
 
         try:
-            jwt_body = decode_jwt_body(self.api_key)
+            jwt_body = decode_jwt_body(self.api_key.get_secret_value())
             user_id = jwt_body.get("sub")
             if not user_id:
                 raise ValueError("Unable to extract user ID from token")

sweatstack/fastapi/__init__.py

@@ -0,0 +1,82 @@
+"""FastAPI integration for SweatStack authentication.
+
+This module provides OAuth authentication for FastAPI applications using
+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, SelectedUser, urls
+
+    configure()  # uses environment variables
+
+    app = FastAPI()
+    instrument(app)
+
+    @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:
+    import fastapi  # noqa: F401
+except ImportError:
+    raise ImportError(
+        "FastAPI is required for sweatstack.fastapi. "
+        "Install it with: pip install 'sweatstack[fastapi]'"
+    )
+
+from .config import configure, urls
+from .dependencies import (
+    AuthenticatedUser,
+    OptionalSelectedUser,
+    OptionalUser,
+    SelectedUser,
+    SweatStackUser,
+)
+from .routes import instrument
+
+__all__ = [
+    # Configuration
+    "configure",
+    "instrument",
+    "urls",
+    # User types
+    "SweatStackUser",
+    # Dependencies
+    "AuthenticatedUser",
+    "OptionalUser",
+    "SelectedUser",
+    "OptionalSelectedUser",
+]

sweatstack/fastapi/config.py

@@ -0,0 +1,223 @@
+"""Module-level configuration for the FastAPI plugin."""
+
+import logging
+import os
+from dataclasses import dataclass
+from urllib.parse import quote
+
+from cryptography.fernet import Fernet
+from pydantic import SecretStr
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_fernet_key(key: str) -> None:
+    """Validate that a string is a valid Fernet key."""
+    try:
+        Fernet(key.encode() if isinstance(key, str) else key)
+    except Exception:
+        raise ValueError(
+            f"Invalid session_secret. Fernet keys must be 32 url-safe base64-encoded bytes. "
+            f"Generate one with: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\""
+        )
+
+
+@dataclass
+class FastAPIConfig:
+    """Internal configuration for the FastAPI plugin."""
+
+    client_id: str
+    client_secret: SecretStr
+    app_url: str
+    session_secret: SecretStr | list[SecretStr]
+    scopes: list[str]
+    cookie_secure: bool
+    cookie_max_age: int
+    auth_route_prefix: str
+    redirect_unauthenticated: bool
+
+    @property
+    def redirect_uri(self) -> str:
+        """Construct the OAuth redirect URI from app_url and auth_route_prefix."""
+        return f"{self.app_url.rstrip('/')}{self.auth_route_prefix}/callback"
+
+
+_config: FastAPIConfig | None = None
+
+
+def _to_secret(value: str | SecretStr) -> SecretStr:
+    """Convert a string to SecretStr if needed."""
+    if isinstance(value, SecretStr):
+        return value
+    return SecretStr(value)
+
+
+def configure(
+    *,
+    client_id: str | None = None,
+    client_secret: str | SecretStr | None = None,
+    app_url: str | None = None,
+    session_secret: str | SecretStr | list[str | SecretStr] | None = None,
+    scopes: list[str] | None = None,
+    cookie_secure: bool | None = None,
+    cookie_max_age: int = 86400,
+    auth_route_prefix: str = "/auth/sweatstack",
+    redirect_unauthenticated: bool = True,
+) -> None:
+    """Configure the FastAPI plugin.
+
+    Args:
+        client_id: OAuth client ID. Falls back to SWEATSTACK_CLIENT_ID env var.
+        client_secret: OAuth client secret. Falls back to SWEATSTACK_CLIENT_SECRET env var.
+        app_url: Base URL of the application (e.g., "http://localhost:8000").
+            Falls back to APP_URL env var.
+            The OAuth redirect URI is derived as: app_url + auth_route_prefix + "/callback"
+        session_secret: Fernet key(s) for cookie encryption. Can be a single key
+            or a list of keys for key rotation (first encrypts, all decrypt).
+            Falls back to SWEATSTACK_SESSION_SECRET env var.
+        scopes: OAuth scopes to request. Defaults to ["profile", "data:read"].
+        cookie_secure: Whether to set the Secure flag on cookies. If not specified,
+            auto-detected from app_url (True for https, False for http).
+        cookie_max_age: Session cookie lifetime in seconds. Defaults to 86400 (24h).
+        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.
+    """
+    global _config
+
+    # Resolve from environment variables
+    client_id = client_id or os.environ.get("SWEATSTACK_CLIENT_ID")
+    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")
+
+    # Validate required parameters
+    if not client_id:
+        raise ValueError("client_id is required (or set SWEATSTACK_CLIENT_ID)")
+    if not client_secret:
+        raise ValueError("client_secret is required (or set SWEATSTACK_CLIENT_SECRET)")
+    if not app_url:
+        raise ValueError("app_url is required (or set APP_URL)")
+    if not session_secret:
+        raise ValueError("session_secret is required (or set SWEATSTACK_SESSION_SECRET)")
+
+    # Auto-detect cookie_secure from app_url scheme
+    if cookie_secure is None:
+        cookie_secure = app_url.startswith("https://")
+        if not cookie_secure and "localhost" not in app_url and "127.0.0.1" not in app_url:
+            logger.warning(
+                "Using HTTP with non-localhost URL (%s) - cookies will not be secure",
+                app_url,
+            )
+
+    # Validate and convert session secret(s)
+    secret_list = [session_secret] if isinstance(session_secret, (str, SecretStr)) else session_secret
+    for secret in secret_list:
+        secret_value = secret.get_secret_value() if isinstance(secret, SecretStr) else secret
+        _validate_fernet_key(secret_value)
+
+    # Convert to SecretStr
+    client_secret_obj = _to_secret(client_secret)
+    if isinstance(session_secret, (str, SecretStr)):
+        session_secret_obj: SecretStr | list[SecretStr] = _to_secret(session_secret)
+    else:
+        session_secret_obj = [_to_secret(s) for s in session_secret]
+
+    if scopes is None:
+        scopes = ["profile", "data:read"]
+
+    # Normalize prefix (strip trailing slash)
+    auth_route_prefix = auth_route_prefix.rstrip("/")
+
+    _config = FastAPIConfig(
+        client_id=client_id,
+        client_secret=client_secret_obj,
+        app_url=app_url,
+        session_secret=session_secret_obj,
+        scopes=scopes,
+        cookie_secure=cookie_secure,
+        cookie_max_age=cookie_max_age,
+        auth_route_prefix=auth_route_prefix,
+        redirect_unauthenticated=redirect_unauthenticated,
+    )
+
+
+def get_config() -> FastAPIConfig:
+    """Get the current configuration.
+
+    Raises:
+        RuntimeError: If configure() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError(
+            "configure() must be called before instrument()"
+        )
+    return _config
+
+
+class _Urls:
+    """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.
+
+        Args:
+            next: Optional path to redirect to after login.
+        """
+        base = f"{get_config().auth_route_prefix}/login"
+        if next:
+            return f"{base}?next={quote(next)}"
+        return base
+
+    def logout(self) -> str:
+        """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()