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

sweatstack/fastapi/__init__.py

@@ -65,7 +65,19 @@ from .dependencies import (
     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
@@ -74,9 +86,25 @@ __all__ = [
     "urls",
     # User types
     "SweatStackUser",
-    # Dependencies
+    # User dependencies
     "AuthenticatedUser",
     "OptionalUser",
     "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,
     )
 
 

sweatstack/fastapi/dependencies.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import logging
 import time
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from typing import Annotated, NoReturn
 from urllib.parse import quote
 
@@ -15,7 +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, TokenSet, extract_user_id
+from .models import SessionData, StoredTokens, TokenSet, extract_user_id
 from .session import (
     SESSION_COOKIE_NAME,
     clear_session_cookie,
@@ -58,6 +59,18 @@ def _is_token_expiring(token: str) -> bool:
         return True
 
 
+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,
@@ -146,6 +159,81 @@ def _get_session_or_none(request: Request) -> SessionData | None:
         return None
 
 
+# ---------------------------------------------------------------------------
+# 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.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),
+            )
+
+            config.token_store.save(tokens)
+
+        except Exception as e:
+            raise WebhookTokenRefreshError(
+                f"Failed to refresh tokens for user {user_id}: {e}"
+            ) from e
+
+    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
 # ---------------------------------------------------------------------------
@@ -182,6 +270,16 @@ def _create_user(
             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())
 
@@ -200,11 +298,26 @@ def _create_user(
 # ---------------------------------------------------------------------------
 
 
-def _require_authenticated_user(
+async def _require_authenticated_user(
     request: Request,
     response: Response,
 ) -> SweatStackUser:
-    """Dependency: always returns principal user."""
+    """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)
 

sweatstack/fastapi/models.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
 
 from pydantic import SecretStr
 
@@ -107,3 +108,68 @@ def extract_user_id(jwt_token: str | SecretStr) -> str:
         return user_id
     except (IndexError, KeyError) as e:
         raise ValueError(f"Malformed JWT token: {e}") from e
+
+
+# ---------------------------------------------------------------------------
+# Token storage for webhook support
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class StoredTokens:
+    """Token data for persistent storage.
+
+    Used by TokenStore implementations to persist tokens for webhook handling.
+    The library does NOT encrypt tokens - see Security section in documentation.
+
+    Attributes:
+        user_id: The SweatStack user ID.
+        access_token: The OAuth access token.
+        refresh_token: The OAuth refresh token.
+        expires_at: When the access token expires.
+    """
+
+    user_id: str
+    access_token: str
+    refresh_token: str
+    expires_at: datetime
+
+    def __repr__(self) -> str:
+        """Hide sensitive data in logs."""
+        return (
+            f"StoredTokens(user_id={self.user_id!r}, "
+            f"access_token='***', refresh_token='***', "
+            f"expires_at={self.expires_at!r})"
+        )
+
+
+@runtime_checkable
+class TokenStore(Protocol):
+    """Protocol for persisting OAuth tokens.
+
+    Implement this interface to enable AuthenticatedUser in webhook handlers.
+    The library calls these methods automatically:
+    - save(): After OAuth callback and token refresh
+    - load(): When handling webhooks
+    - delete(): On logout
+
+    Thread Safety:
+        All methods may be called concurrently. Your implementation must be thread-safe.
+
+    Error Handling:
+        - save(): Use upsert semantics (don't raise on duplicate user_id)
+        - load(): Return None if user not found (don't raise)
+        - delete(): Be idempotent (don't raise if user doesn't exist)
+    """
+
+    def save(self, tokens: StoredTokens) -> None:
+        """Save or update tokens for a user."""
+        ...
+
+    def load(self, user_id: str) -> StoredTokens | None:
+        """Load tokens for a user. Returns None if not found."""
+        ...
+
+    def delete(self, user_id: str) -> None:
+        """Delete tokens for a user. Idempotent."""
+        ...

sweatstack/fastapi/routes.py

@@ -15,7 +15,8 @@ from fastapi.responses import RedirectResponse
 from ..constants import DEFAULT_URL
 from ..utils import decode_jwt_body
 from .config import get_config
-from .models import SessionData, TokenSet
+from .dependencies import _extract_expiry
+from .models import SessionData, StoredTokens, TokenSet
 from .session import (
     SESSION_COOKIE_NAME,
     STATE_COOKIE_NAME,
@@ -166,28 +167,34 @@ def create_router() -> APIRouter:
         code: str | None = None,
         state: str | None = None,
         error: str | None = None,
+        error_description: str | None = None,
     ) -> Response:
         """Handle OAuth callback from SweatStack."""
         config = get_config()
 
+        def error_redirect(error_code: str) -> Response:
+            """Redirect to / with error code in query params."""
+            response = RedirectResponse(url=f"/?auth_error={error_code}", status_code=302)
+            clear_state_cookie(response)
+            return response
+
         # Get state cookie
         state_cookie = request.cookies.get(STATE_COOKIE_NAME)
 
-        # Clear state cookie regardless of outcome
-        response = RedirectResponse(url="/", status_code=302)
-        clear_state_cookie(response)
-
-        # Handle OAuth errors
+        # Handle OAuth errors from provider
         if error:
-            return response
+            logger.warning("OAuth error from provider: %s - %s", error, error_description)
+            return error_redirect(error)
 
         # Verify state (CSRF protection)
         if not state or not state_cookie or state != state_cookie:
-            return Response(content="Invalid state", status_code=400)
+            logger.warning("OAuth state mismatch (possible CSRF)")
+            return error_redirect("invalid_state")
 
         # Exchange code for tokens
         if not code:
-            return Response(content="Missing authorization code", status_code=400)
+            logger.warning("OAuth callback missing authorization code")
+            return error_redirect("missing_code")
 
         try:
             token_response = httpx.post(
@@ -202,24 +209,31 @@ def create_router() -> APIRouter:
             )
             token_response.raise_for_status()
             tokens = token_response.json()
-        except Exception:
-            return response  # Redirect to / on token exchange failure
+        except httpx.HTTPStatusError as e:
+            logger.error("Token exchange failed: %s - %s", e.response.status_code, e.response.text)
+            return error_redirect("token_exchange_failed")
+        except Exception as e:
+            logger.error("Token exchange error: %s", e)
+            return error_redirect("token_exchange_failed")
 
         access_token = tokens.get("access_token")
         refresh_token = tokens.get("refresh_token")
 
         if not access_token:
-            return response
+            logger.error("Token response missing access_token")
+            return error_redirect("invalid_token_response")
 
         # Extract user_id from JWT
         try:
             token_body = decode_jwt_body(access_token)
             user_id = token_body.get("sub")
-        except Exception:
-            return response
+        except Exception as e:
+            logger.error("Failed to decode access token: %s", e)
+            return error_redirect("invalid_token")
 
         if not user_id:
-            return response
+            logger.error("Access token missing 'sub' claim")
+            return error_redirect("invalid_token")
 
         # Create session
         session_data = {
@@ -228,6 +242,17 @@ def create_router() -> APIRouter:
             "user_id": user_id,
         }
 
+        # Persist tokens to store if configured
+        if config.token_store:
+            config.token_store.save(
+                StoredTokens(
+                    user_id=user_id,
+                    access_token=access_token,
+                    refresh_token=refresh_token,
+                    expires_at=_extract_expiry(access_token),
+                )
+            )
+
         # Determine redirect URL from state
         state_data = parse_state(state)
         redirect_url = state_data.get("next", "/")
@@ -238,8 +263,16 @@ def create_router() -> APIRouter:
         return response
 
     @router.post("/logout")
-    def logout() -> Response:
+    def logout(request: Request) -> Response:
         """Clear session and redirect to /."""
+        config = get_config()
+
+        # Delete tokens from store if configured
+        if config.token_store:
+            session = _get_session_data(request)
+            if session:
+                config.token_store.delete(session.principal.user_id)
+
         response = RedirectResponse(url="/", status_code=302)
         clear_session_cookie(response)
         return response
@@ -298,6 +331,39 @@ def create_router() -> APIRouter:
     return router
 
 
+def _warn_if_webhook_misconfigured(app: FastAPI) -> None:
+    """Log error if WebhookPayload is used but webhook_secret not configured."""
+    config = get_config()
+
+    if config.webhook_secret:
+        return  # Properly configured
+
+    # Import here to avoid circular imports
+    from .webhooks import _require_webhook_payload
+
+    # Check if any route uses WebhookPayload dependency
+    for route in app.routes:
+        if not hasattr(route, "dependant"):
+            continue
+
+        if _uses_dependency(route.dependant, _require_webhook_payload):
+            raise RuntimeError(
+                f"Route '{route.path}' uses WebhookPayload but webhook_secret is not configured. "
+                "Webhook signature verification will fail at runtime. "
+                "Configure with the SWEATSTACK_WEBHOOK_SECRET env variable or configure(webhook_secret='whsec_...')"
+            )
+
+
+def _uses_dependency(dependant, target_callable) -> bool:
+    """Check if a dependency tree includes the target callable."""
+    for dep in dependant.dependencies:
+        if dep.call is target_callable:
+            return True
+        if hasattr(dep, "dependant") and _uses_dependency(dep.dependant, target_callable):
+            return True
+    return False
+
+
 def instrument(app: FastAPI) -> None:
     """Add SweatStack auth routes to a FastAPI application.
 
@@ -310,3 +376,8 @@ def instrument(app: FastAPI) -> None:
     config = get_config()  # This will raise if not configured
     router = create_router()
     app.include_router(router, prefix=config.auth_route_prefix)
+
+    # Validate webhook configuration at startup (after all routes are registered)
+    @app.on_event("startup")
+    def _check_webhook_config():
+        _warn_if_webhook_misconfigured(app)

sweatstack/fastapi/token_stores.py

@@ -0,0 +1,238 @@
+"""Token store implementations for development use.
+
+WARNING: These implementations are for LOCAL DEVELOPMENT ONLY.
+Do not use in production. Implement your own TokenStore with proper
+database infrastructure, encryption, and monitoring.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+from datetime import datetime
+from pathlib import Path
+
+from .models import StoredTokens, TokenStore
+
+logger = logging.getLogger(__name__)
+
+
+class SQLiteTokenStore(TokenStore):
+    """SQLite-based TokenStore for local development.
+
+    WARNING: This implementation is for LOCAL DEVELOPMENT ONLY.
+    Do not use in production. For production, implement your own
+    TokenStore with proper database infrastructure, encryption,
+    and monitoring.
+
+    Features:
+        - File-based storage (no external database required)
+        - Thread-safe with connection-per-thread pattern
+        - Auto-creates table on first use
+
+    Args:
+        db_path: Path to SQLite database file. Defaults to "sweatstack_tokens.db"
+            in current directory.
+    """
+
+    def __init__(self, db_path: str | Path = "sweatstack_tokens.db"):
+        self.db_path = str(db_path)
+        self._local = threading.local()
+
+        logger.warning(
+            "SQLiteTokenStore is for LOCAL DEVELOPMENT ONLY. "
+            "Do not use in production. Implement a proper TokenStore "
+            "with your production database."
+        )
+
+        self._init_db()
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get thread-local database connection."""
+        if not hasattr(self._local, "connection"):
+            self._local.connection = sqlite3.connect(
+                self.db_path,
+                check_same_thread=False,
+            )
+            self._local.connection.row_factory = sqlite3.Row
+        return self._local.connection
+
+    def _init_db(self) -> None:
+        """Create tokens table if it doesn't exist."""
+        conn = self._get_connection()
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS sweatstack_tokens (
+                user_id TEXT PRIMARY KEY,
+                access_token TEXT NOT NULL,
+                refresh_token TEXT NOT NULL,
+                expires_at TEXT NOT NULL
+            )
+        """)
+        conn.commit()
+
+    def save(self, tokens: StoredTokens) -> None:
+        """Save or update tokens for a user."""
+        conn = self._get_connection()
+        conn.execute(
+            """
+            INSERT INTO sweatstack_tokens (user_id, access_token, refresh_token, expires_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(user_id) DO UPDATE SET
+                access_token = excluded.access_token,
+                refresh_token = excluded.refresh_token,
+                expires_at = excluded.expires_at
+            """,
+            (
+                tokens.user_id,
+                tokens.access_token,
+                tokens.refresh_token,
+                tokens.expires_at.isoformat(),
+            ),
+        )
+        conn.commit()
+
+    def load(self, user_id: str) -> StoredTokens | None:
+        """Load tokens for a user. Returns None if not found."""
+        conn = self._get_connection()
+        row = conn.execute(
+            "SELECT * FROM sweatstack_tokens WHERE user_id = ?",
+            (user_id,),
+        ).fetchone()
+
+        if row:
+            return StoredTokens(
+                user_id=row["user_id"],
+                access_token=row["access_token"],
+                refresh_token=row["refresh_token"],
+                expires_at=datetime.fromisoformat(row["expires_at"]),
+            )
+        return None
+
+    def delete(self, user_id: str) -> None:
+        """Delete tokens for a user. Idempotent."""
+        conn = self._get_connection()
+        conn.execute(
+            "DELETE FROM sweatstack_tokens WHERE user_id = ?",
+            (user_id,),
+        )
+        conn.commit()
+
+
+class EncryptedSQLiteTokenStore(TokenStore):
+    """Encrypted SQLite TokenStore for local development.
+
+    WARNING: This implementation is for LOCAL DEVELOPMENT ONLY.
+    Do not use in production. This demonstrates the encryption pattern -
+    adapt it for your production database.
+
+    Encrypts access_token and refresh_token using Fernet (AES-128-CBC + HMAC).
+    user_id and expires_at are stored unencrypted for queries.
+
+    Args:
+        encryption_key: Fernet key for encryption. Generate with:
+            python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+        db_path: Path to SQLite database file.
+    """
+
+    def __init__(
+        self,
+        encryption_key: str | bytes,
+        db_path: str | Path = "sweatstack_tokens_encrypted.db",
+    ):
+        # Import here so cryptography is optional for basic usage
+        from cryptography.fernet import Fernet
+
+        self.db_path = str(db_path)
+        self._local = threading.local()
+
+        if isinstance(encryption_key, str):
+            encryption_key = encryption_key.encode()
+        self._fernet = Fernet(encryption_key)
+
+        logger.warning(
+            "EncryptedSQLiteTokenStore is for LOCAL DEVELOPMENT ONLY. "
+            "Do not use in production. This demonstrates the encryption "
+            "pattern - implement with your production database."
+        )
+
+        self._init_db()
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get thread-local database connection."""
+        if not hasattr(self._local, "connection"):
+            self._local.connection = sqlite3.connect(
+                self.db_path,
+                check_same_thread=False,
+            )
+            self._local.connection.row_factory = sqlite3.Row
+        return self._local.connection
+
+    def _init_db(self) -> None:
+        """Create tokens table if it doesn't exist."""
+        conn = self._get_connection()
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS sweatstack_tokens (
+                user_id TEXT PRIMARY KEY,
+                access_token_encrypted TEXT NOT NULL,
+                refresh_token_encrypted TEXT NOT NULL,
+                expires_at TEXT NOT NULL
+            )
+        """)
+        conn.commit()
+
+    def _encrypt(self, value: str) -> str:
+        """Encrypt a string value."""
+        return self._fernet.encrypt(value.encode()).decode()
+
+    def _decrypt(self, value: str) -> str:
+        """Decrypt a string value."""
+        return self._fernet.decrypt(value.encode()).decode()
+
+    def save(self, tokens: StoredTokens) -> None:
+        """Save or update tokens for a user."""
+        conn = self._get_connection()
+        conn.execute(
+            """
+            INSERT INTO sweatstack_tokens
+                (user_id, access_token_encrypted, refresh_token_encrypted, expires_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(user_id) DO UPDATE SET
+                access_token_encrypted = excluded.access_token_encrypted,
+                refresh_token_encrypted = excluded.refresh_token_encrypted,
+                expires_at = excluded.expires_at
+            """,
+            (
+                tokens.user_id,
+                self._encrypt(tokens.access_token),
+                self._encrypt(tokens.refresh_token),
+                tokens.expires_at.isoformat(),
+            ),
+        )
+        conn.commit()
+
+    def load(self, user_id: str) -> StoredTokens | None:
+        """Load tokens for a user. Returns None if not found."""
+        conn = self._get_connection()
+        row = conn.execute(
+            "SELECT * FROM sweatstack_tokens WHERE user_id = ?",
+            (user_id,),
+        ).fetchone()
+
+        if row:
+            return StoredTokens(
+                user_id=row["user_id"],
+                access_token=self._decrypt(row["access_token_encrypted"]),
+                refresh_token=self._decrypt(row["refresh_token_encrypted"]),
+                expires_at=datetime.fromisoformat(row["expires_at"]),
+            )
+        return None
+
+    def delete(self, user_id: str) -> None:
+        """Delete tokens for a user. Idempotent."""
+        conn = self._get_connection()
+        conn.execute(
+            "DELETE FROM sweatstack_tokens WHERE user_id = ?",
+            (user_id,),
+        )
+        conn.commit()

sweatstack/fastapi/webhooks.py

@@ -0,0 +1,201 @@
+"""Webhook handling for the FastAPI plugin."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+
+from .config import get_config
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class WebhookError(Exception):
+    """Base class for webhook-related errors."""
+
+    pass
+
+
+class WebhookVerificationError(WebhookError):
+    """Raised when webhook signature verification fails."""
+
+    pass
+
+
+class WebhookTokenStoreError(WebhookError):
+    """Raised when TokenStore is required but not configured."""
+
+    pass
+
+
+class WebhookUserNotFoundError(WebhookError):
+    """Raised when no stored tokens exist for the webhook's user_id."""
+
+    pass
+
+
+class WebhookTokenRefreshError(WebhookError):
+    """Raised when token refresh fails in webhook context."""
+
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Webhook payload model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookPayloadModel:
+    """Verified webhook payload data.
+
+    Attributes:
+        user_id: The SweatStack user ID this webhook relates to.
+        event_type: The type of event (e.g., "activity_created").
+        resource_id: The ID of the affected resource.
+        timestamp: When the event occurred.
+    """
+
+    user_id: str
+    event_type: str
+    resource_id: str
+    timestamp: datetime
+
+
+# ---------------------------------------------------------------------------
+# Signature verification
+# ---------------------------------------------------------------------------
+
+TIMESTAMP_TOLERANCE = 300  # 5 minutes
+
+
+def verify_signature(
+    payload: bytes,
+    signature_header: str,
+    secret: str,
+) -> None:
+    """Verify webhook signature.
+
+    SweatStack uses HMAC-SHA256 signatures. The signature header format is:
+    t={timestamp},v1={signature}
+
+    The signed payload is: {timestamp}.{raw_json_body}
+
+    Args:
+        payload: The raw request body bytes.
+        signature_header: The X-Sweatstack-Signature header value.
+        secret: The webhook secret.
+
+    Raises:
+        WebhookVerificationError: If signature is invalid or timestamp too old.
+    """
+    try:
+        parts = dict(p.split("=", 1) for p in signature_header.split(","))
+        timestamp = int(parts["t"])
+        signature = parts["v1"]
+    except (KeyError, ValueError) as e:
+        raise WebhookVerificationError("Invalid signature header format") from e
+
+    # Check timestamp to prevent replay attacks
+    if abs(time.time() - timestamp) > TIMESTAMP_TOLERANCE:
+        raise WebhookVerificationError("Timestamp outside tolerance window")
+
+    # Compute expected signature
+    signed_payload = f"{timestamp}.".encode() + payload
+    expected = hmac.new(
+        secret.encode(),
+        signed_payload,
+        hashlib.sha256,
+    ).hexdigest()
+
+    # Constant-time comparison to prevent timing attacks
+    if not hmac.compare_digest(expected, signature):
+        raise WebhookVerificationError("Invalid signature")
+
+
+# ---------------------------------------------------------------------------
+# FastAPI dependencies
+# ---------------------------------------------------------------------------
+
+
+async def _detect_webhook_context(request: Request) -> WebhookPayloadModel | None:
+    """Detect if this is a webhook request and return verified payload.
+
+    This dependency is cached per-request by FastAPI. It's used by both
+    WebhookPayload (which requires it) and AuthenticatedUser (which uses it
+    to detect webhook context for token loading).
+
+    Returns:
+        WebhookPayloadModel if this is a verified webhook request, None otherwise.
+
+    Raises:
+        WebhookVerificationError: If signature header is present but invalid.
+    """
+    signature = request.headers.get("X-Sweatstack-Signature")
+    if not signature:
+        return None  # Not a webhook request - fast path
+
+    config = get_config()
+
+    if not config.webhook_secret:
+        raise WebhookVerificationError(
+            "Webhook received but webhook_secret not configured. "
+            "Add webhook_secret to configure() to enable webhook handling."
+        )
+
+    body = await request.body()
+    secret = (
+        config.webhook_secret.get_secret_value()
+        if hasattr(config.webhook_secret, "get_secret_value")
+        else config.webhook_secret
+    )
+    verify_signature(body, signature, secret)
+
+    try:
+        data = json.loads(body)
+        return WebhookPayloadModel(
+            user_id=data["user_id"],
+            event_type=data["event_type"],
+            resource_id=data["resource_id"],
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+        )
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        raise WebhookVerificationError(f"Invalid webhook payload: {e}") from e
+
+
+async def _require_webhook_payload(
+    webhook_context: Annotated[WebhookPayloadModel | None, Depends(_detect_webhook_context)],
+) -> WebhookPayloadModel:
+    """Dependency that requires a verified webhook payload.
+
+    Raises:
+        HTTPException: If request is not a valid webhook.
+    """
+    if webhook_context is None:
+        raise HTTPException(status_code=400, detail="Missing or invalid webhook signature")
+    return webhook_context
+
+
+# Public type alias for use in endpoint signatures
+WebhookPayload = Annotated[WebhookPayloadModel, Depends(_require_webhook_payload)]
+"""Dependency that returns a verified webhook payload.
+
+The signature is verified before your handler runs. If verification fails,
+a 400 response is returned automatically.
+
+Example:
+    @app.post("/webhooks/sweatstack")
+    def handle_webhook(payload: WebhookPayload):
+        print(f"Event: {payload.event_type} for user {payload.user_id}")
+        return {"status": "received"}
+"""

{sweatstack-0.61.0.dist-info → sweatstack-0.62.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.61.0
+Version: 0.62.0
 Summary: The official Python client for SweatStack
 Author-email: Aart Goossens <aart@gssns.io>
 Requires-Python: >=3.9

{sweatstack-0.61.0.dist-info → sweatstack-0.62.0.dist-info}/RECORD

@@ -11,13 +11,15 @@ sweatstack/streamlit.py,sha256=wnabWhife9eMAdkECPjRKkzE82KZoi_H8YzucZl_m9s,19604
 sweatstack/sweatshell.py,sha256=MYLNcWbOdceqKJ3S0Pe8dwHXEeYsGJNjQoYUXpMTftA,333
 sweatstack/utils.py,sha256=AwHRdC1ziOZ5o9RBIB21Uxm-DoClVRAJSVvgsmSmvps,1801
 sweatstack/Sweat Stack examples/Getting started.ipynb,sha256=k2hiSffWecoQ0VxjdpDcgFzBXDQiYEebhnAYlu8cgX8,6335204
-sweatstack/fastapi/__init__.py,sha256=J20u-R3ABLP0vGLl3m_H76nTvpoMHtpKpyH8vufb9kM,2465
-sweatstack/fastapi/config.py,sha256=S9Y5G5YprSugICtkCdVEUBwdbGsg2MuzdPx8QJaP8XA,7850
-sweatstack/fastapi/dependencies.py,sha256=6QrWCcYJJXI0-Tn2A4hKimVMCa45rRUAu-gijtgAq4k,8739
-sweatstack/fastapi/models.py,sha256=2VNKITN7LKacQxxVgYJjDaZ6Xq2eYBtvkQbq7H6bLlY,3386
-sweatstack/fastapi/routes.py,sha256=Y-g8DMM2gG_8ETnLN7ZfUqBT8AkwIG9WFbEqJtyyKcM,10058
+sweatstack/fastapi/__init__.py,sha256=BteLHro6KCVknIgNAp6OS5ZJRWmIXHS4iXOLOSyN2Mc,3216
+sweatstack/fastapi/config.py,sha256=nNiZOeAXbipK4l2mxaPfaLwz2Ml-Eu7n-G46yGlvjA4,8764
+sweatstack/fastapi/dependencies.py,sha256=8kfKqe-js1G7LLe2AR8xpChtoCKrDG3-F0VkZyXMlIo,12620
+sweatstack/fastapi/models.py,sha256=vBImNywlKiw-10ZODRAHZSrWG3Xfla8uuXA0Y-p0Opc,5499
+sweatstack/fastapi/routes.py,sha256=qNRSod_ZWziFptInplmwmrOe5ZwpJbL7kE5LHWJIxC8,13106
 sweatstack/fastapi/session.py,sha256=BtRPCmIEaToJPwFyZ0fqWGlmnDHuWKy8nri9dJrPXaA,2717
-sweatstack-0.61.0.dist-info/METADATA,sha256=RGfVVMy3zO08wiJw98gF-9IW_8gjuYsJ3Kg58BAJyi4,994
-sweatstack-0.61.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-sweatstack-0.61.0.dist-info/entry_points.txt,sha256=kCzOUQI3dqbTpEYqtgYDeiKFaqaA7BMlV6D24BMzCFU,208
-sweatstack-0.61.0.dist-info/RECORD,,
+sweatstack/fastapi/token_stores.py,sha256=-waq0CQLszIp-2uLwWgkMz8IbsmUC7xopvM2F12sbMo,8207
+sweatstack/fastapi/webhooks.py,sha256=ShRQRkarJ3vuEkT1lkl1-_oQbPQTLNkgQ2E6Mm4UepU,6066
+sweatstack-0.62.0.dist-info/METADATA,sha256=SqQNBCJZibHU6qQaQi1ij-OLHAWt082zfxPrXSFiJY4,994
+sweatstack-0.62.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sweatstack-0.62.0.dist-info/entry_points.txt,sha256=kCzOUQI3dqbTpEYqtgYDeiKFaqaA7BMlV6D24BMzCFU,208
+sweatstack-0.62.0.dist-info/RECORD,,