fastapi-auth-starter 0.1.3__py3-none-any.whl

fastapi_auth_starter-0.1.3.data/data/app/core/config.py

@@ -0,0 +1,107 @@
+"""
+Application configuration settings
+Handles environment variables and configuration management
+All configuration values should be set in .env file or environment variables
+Reference: https://fastapi.tiangolo.com/advanced/settings/
+"""
+import json
+from pydantic import Field, ConfigDict
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """
+    Application settings loaded from environment variables
+    Uses pydantic BaseSettings for validation and type conversion
+    
+    All values should be set in .env file (see .env.example for template)
+    """
+    # API Configuration
+    # These can have defaults but should be overridden in .env
+    API_V1_PREFIX: str = "/api/v1"
+    PROJECT_NAME: str = "FastAPI Auth Starter"
+    VERSION: str = "0.1.0"
+    
+    # Database Configuration
+    # PostgreSQL connection string format: postgresql+asyncpg://user:password@host:port/dbname
+    # Reference: https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls
+    # Set in .env file or Vercel environment variables
+    # Note: Special characters in password must be URL-encoded (e.g., ! = %21)
+    DATABASE_URL: str = Field(
+        ...,
+        description="PostgreSQL database URL. Must be set via environment variable."
+    )
+
+    # WorkOS Configuration
+    # WorkOS API key for user management
+    # Reference: https://workos.com/docs/reference/api-reference/user-management
+    WORKOS_API_KEY: str = Field(
+        ...,
+        description="WorkOS API key. Must be set via environment variable."
+    )
+    WORKOS_CLIENT_ID: str = Field(
+        ...,
+        description="WorkOS client ID. Must be set via environment variable."
+    )
+
+    WORKOS_DEFAULT_CONNECTION_ID: str | None = Field(
+        None,
+        description="Default WorkOS SSO connection ID. Can be overridden by frontend."
+    )
+    # Allowed redirect URIs (comma-separated or JSON array)
+    # Security: Only these URIs are allowed for OAuth redirects
+    WORKOS_ALLOWED_REDIRECT_URIS: str = Field(
+        ...,
+        description="Comma-separated list of allowed redirect URIs for OAuth"
+    )
+    
+    @property
+    def allowed_redirect_uris_list(self) -> list[str]:
+        """
+        Parse allowed redirect URIs into a list.
+        
+        Supports two formats:
+        1. JSON array: ["https://app.example.com/callback", "https://app2.example.com/callback"]
+        2. Comma-separated: https://app.example.com/callback,https://app2.example.com/callback
+        
+        Reference: https://docs.python.org/3/library/json.html
+        """
+        raw = self.WORKOS_ALLOWED_REDIRECT_URIS.strip()
+        if not raw:
+            return []
+        
+        # Try parsing as JSON first (supports JSON array format)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            # Fall back to comma-separated string format
+            return [uri.strip() for uri in raw.split(",") if uri.strip()]
+        
+        # Handle parsed JSON result
+        if isinstance(parsed, str):
+            return [parsed.strip()]
+        if isinstance(parsed, list):
+            return [str(uri).strip() for uri in parsed if str(uri).strip()]
+        
+        raise ValueError(
+            "WORKOS_ALLOWED_REDIRECT_URIS must be a JSON array or comma-separated string"
+        )
+    # Alembic Configuration
+    # Used for database migrations
+    # Reference: https://alembic.sqlalchemy.org/en/latest/tutorial.html
+    ALEMBIC_CONFIG: str = "alembic.ini"
+    
+    # Pydantic v2 configuration
+    # Reference: https://docs.pydantic.dev/latest/api/config/
+    model_config = ConfigDict(
+        env_file=".env",  # Load from .env file (required)
+        case_sensitive=True,  # Environment variable names are case-sensitive
+        extra="ignore",  # Ignore extra environment variables not defined in this class
+        # This allows additional env vars (like WorkOS config) to exist without causing validation errors
+    )
+
+
+# Global settings instance
+# Import this in other modules to access configuration
+settings = Settings()
+

fastapi_auth_starter-0.1.3.data/data/app/core/database.py

@@ -0,0 +1,106 @@
+"""
+Database connection and session management
+Uses SQLAlchemy async engine for PostgreSQL
+Reference: https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html
+"""
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.pool import NullPool
+
+from app.core.config import settings
+
+
+# Validate DATABASE_URL is set
+if not settings.DATABASE_URL:
+    raise ValueError(
+        "DATABASE_URL environment variable is not set. "
+        "Please set it in your .env file or Vercel environment variables."
+    )
+
+# Create async engine for PostgreSQL
+# Using NullPool for serverless (Vercel) - each request gets a fresh connection
+# Connection pooling doesn't work well in serverless environments where functions
+# are isolated and can be terminated/cold-started
+# Reference: https://docs.sqlalchemy.org/en/20/core/pooling.html#switching-pool-implementations
+# Reference: https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#using-multiple-asyncio-event-loops
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=False,  # Set to True for SQL query logging (useful for debugging)
+    poolclass=NullPool,  # No connection pooling - each request gets a new connection
+    # This is critical for serverless environments where connection reuse
+    # across function invocations causes connection termination errors
+    # Reference: https://docs.sqlalchemy.org/en/20/core/pooling.html#disabling-pooling-using-nullpool
+    connect_args={
+        # asyncpg-specific connection arguments
+        # Reference: https://magicstack.github.io/asyncpg/current/api/index.html#connection
+        "command_timeout": 60,  # Increased timeout for serverless network latency
+        "server_settings": {
+            "application_name": "fastapi_auth_starter",
+        },
+    },
+)
+
+
+# Create async session factory
+# This is used to create database sessions throughout the application
+# Reference: https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#session-basics
+async_session_maker = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,  # Keep objects accessible after commit
+    # This is important for serverless - objects remain accessible after commit
+    # allowing timestamps to be read even if not refreshed
+    autocommit=False,
+    autoflush=False,
+)
+
+
+# Base class for all database models
+# All models should inherit from this class
+# Reference: https://docs.sqlalchemy.org/en/20/orm/declarative_styles.html
+class Base(DeclarativeBase):
+    """Base class for SQLAlchemy declarative models"""
+    pass
+
+
+# Dependency to get database session
+# Used in FastAPI route handlers via dependency injection
+# Reference: https://fastapi.tiangolo.com/tutorial/dependencies/
+async def get_db() -> AsyncSession:
+    """
+    Dependency function that provides a database session
+    Automatically closes the session after the request completes
+    
+    For serverless environments (Vercel), this ensures proper transaction handling:
+    - Commits on success
+    - Rolls back on error
+    - Always closes the session
+    """
+    async with async_session_maker() as session:
+        try:
+            yield session
+            # Commit transaction on success
+            # This commits all changes made during the request
+            # In serverless, this must complete before the function terminates
+            await session.commit()
+        except Exception as e:
+            # Rollback on any exception to maintain data consistency
+            try:
+                await session.rollback()
+            except Exception:
+                # If rollback fails, connection is likely already closed
+                # This can happen in serverless when connections are terminated
+                pass
+            # Re-raise the original exception so FastAPI can handle it properly
+            raise
+        finally:
+            # Always close the session to release connection
+            # With NullPool, this closes the connection completely
+            # In serverless, this is critical to prevent connection leaks
+            try:
+                await session.close()
+            except Exception:
+                # If close fails, connection is likely already closed or terminated
+                # This is acceptable - we're in cleanup anyway
+                pass
+

fastapi_auth_starter-0.1.3.data/data/app/core/dependencies.py

@@ -0,0 +1,148 @@
+"""
+Authentication dependencies for protecting endpoints
+Reference: https://fastapi.tiangolo.com/tutorial/dependencies/
+"""
+import asyncio
+import logging
+from functools import lru_cache
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from workos import WorkOSClient
+from workos.exceptions import AuthenticationException, NotFoundException
+
+from app.services.auth import AuthService
+from app.api.v1.schemas.auth import WorkOSUserResponse
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+# HTTPBearer automatically extracts Bearer token from Authorization header
+# Reference: https://fastapi.tiangolo.com/reference/security/#fastapi.security.HTTPBearer
+security = HTTPBearer()
+
+
+@lru_cache()
+def get_auth_service() -> AuthService:
+    """
+    Get a singleton AuthService instance.
+    
+    Using lru_cache ensures the same AuthService instance is reused across requests,
+    which preserves the JWKS cache (_jwks_cache and _jwks_cache_expiry) at the
+    application level rather than request level. This avoids repeated JWKS API calls
+    to WorkOS and improves performance.
+    
+    Reference: https://docs.python.org/3/library/functools.html#functools.lru_cache
+    """
+    return AuthService()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security)
+) -> WorkOSUserResponse:
+    """
+    Dependency to get the current authenticated user.
+    
+    Validates the JWT access token from the Authorization header using WorkOS JWKS,
+    then fetches full user details from WorkOS.
+    
+    Usage:
+        @router.get("/protected")
+        async def protected_route(current_user = Depends(get_current_user)):
+            return {"user_id": current_user.id, "email": current_user.email}
+    
+    Args:
+        credentials: HTTPAuthorizationCredentials containing the Bearer token
+        
+    Returns:
+        WorkOSUserResponse: The authenticated user with full details
+        
+    Raises:
+        HTTPException: 401 if token is invalid or missing
+    """
+    auth_service = get_auth_service()
+    
+    try:
+        # Extract the token from credentials
+        access_token = credentials.credentials
+        logger.debug(f"Verifying session with token: {access_token[:20]}...")
+        
+        # Verify the session with WorkOS (validates JWT signature and expiration)
+        # Reference: https://workos.com/docs/reference/authkit/session-tokens/access-token
+        session_data = await auth_service.verify_session(access_token)
+        
+        user_id = session_data.get('user_id')
+        if not user_id:
+            logger.error("Token missing user_id (sub claim)")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token: missing user information",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        logger.debug(f"Token verified successfully. User ID: {user_id}")
+        
+        # Fetch full user details from WorkOS
+        # The JWT contains basic info, but we fetch full details for complete user object
+        workos_client = WorkOSClient(
+            api_key=settings.WORKOS_API_KEY,
+            client_id=settings.WORKOS_CLIENT_ID
+        )
+        
+        # Offload synchronous WorkOS call to thread pool
+        workos_user = await asyncio.to_thread(
+            workos_client.user_management.get_user,
+            user_id=user_id
+        )
+        
+        # Convert WorkOS user to our schema
+        user = WorkOSUserResponse(
+            object=workos_user.object,
+            id=workos_user.id,
+            email=workos_user.email,
+            first_name=workos_user.first_name,
+            last_name=workos_user.last_name,
+            email_verified=workos_user.email_verified,
+            profile_picture_url=workos_user.profile_picture_url,
+            created_at=workos_user.created_at,
+            updated_at=workos_user.updated_at,
+        )
+        
+        logger.debug(f"User fetched: {user.id} ({user.email})")
+        return user
+        
+    except ValueError as e:
+        # Map error to RFC6750-compliant WWW-Authenticate header
+        msg = str(e)
+        # Default values
+        error = "invalid_token"
+        description = msg or "The access token is invalid"
+
+        if "expired" in msg.lower():
+            description = "The access token expired"
+
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=msg,
+            headers={
+                "WWW-Authenticate": f'Bearer realm="api", error="{error}", error_description="{description}"'
+            },
+        ) from e
+    except NotFoundException:
+        # User not found in WorkOS (shouldn't happen if token is valid)
+        logger.error(f"User not found in WorkOS after token verification")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    except HTTPException:
+        # Re-raise HTTP exceptions (already formatted)
+        raise
+    except Exception as e:
+        # Unexpected error - log full details for debugging
+        logger.error(f"Unexpected authentication error: {type(e).__name__}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Authentication failed: {str(e)}",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from e

fastapi_auth_starter-0.1.3.data/data/app/core/exceptions.py

@@ -0,0 +1,7 @@
+class InvalidPasswordException(Exception):
+    """
+    Exception raised when the old password is incorrect
+    """
+    def __init__(self, message: str = "Old password is incorrect"):
+        self.message = message
+        super().__init__(self.message)

fastapi_auth_starter-0.1.3.data/data/app/db/__init__.py

@@ -0,0 +1,4 @@
+"""
+Database utilities and helpers
+"""
+

fastapi_auth_starter-0.1.3.data/data/app/main.py

@@ -0,0 +1,91 @@
+"""
+FastAPI application entry point
+Main application factory and configuration
+Reference: https://fastapi.tiangolo.com/tutorial/bigger-applications/
+"""
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from sqlalchemy import text
+
+from app.api.v1.api import api_router
+from app.core.config import settings
+from app.core.database import engine
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lifespan context manager for startup and shutdown events
+    Validates database connection on startup
+    Reference: https://fastapi.tiangolo.com/advanced/events/
+    """
+    # Startup: Test database connection
+    try:
+        async with engine.begin() as conn:
+            await conn.execute(text("SELECT 1"))
+        logger.info("✓ Database connection successful")
+    except Exception as e:
+        logger.error(f"✗ Database connection failed: {e}")
+        logger.error(
+            "Please check:\n"
+            "1. DATABASE_URL is set correctly in Vercel environment variables\n"
+            "2. AWS RDS security group allows connections from Vercel IP ranges\n"
+            "3. Database is accessible and credentials are correct"
+        )
+        # Don't raise - let the app start but connections will fail
+        # This allows health checks to work
+    
+    yield
+    
+    # Shutdown: Dispose of database connections
+    await engine.dispose()
+    logger.info("Database connections closed")
+
+
+# Create FastAPI application instance
+# Reference: https://fastapi.tiangolo.com/reference/fastapi/
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    description="A clean architecture FastAPI starter with PostgreSQL and Alembic",
+    docs_url="/docs",  # Swagger UI documentation
+    redoc_url="/redoc",  # ReDoc documentation
+    lifespan=lifespan,  # Add lifespan for startup/shutdown events
+)
+
+allowed_origins = [
+    "http://localhost:3000",
+    # add other trusted origins here
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Include API routers
+# All routes from api_router will be included in the main app
+app.include_router(api_router)
+
+
+@app.get("/")
+async def root():
+    """
+    Root endpoint
+    Provides basic information about the API
+    """
+    return {
+        "message": f"Welcome to {settings.PROJECT_NAME}",
+        "version": settings.VERSION,
+        "docs": "/docs",
+    }
+

fastapi_auth_starter-0.1.3.data/data/app/models/__init__.py

@@ -0,0 +1,14 @@
+"""
+Database models
+All SQLAlchemy models should be defined here or imported here
+"""
+
+# Import Base for models to inherit from
+from app.core.database import Base
+
+# Import models here as they are created
+from app.models.task import Task
+from app.models.user import User
+
+# Export all models for easy imports
+__all__ = ["Base", "Task", "User"]

fastapi_auth_starter-0.1.3.data/data/app/models/task.py

@@ -0,0 +1,56 @@
+"""
+Task database model
+SQLAlchemy model for tasks
+Reference: https://docs.sqlalchemy.org/en/20/orm/declarative_styles.html
+"""
+from datetime import datetime
+from sqlalchemy import Integer, String, Boolean, DateTime, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.database import Base
+
+
+class Task(Base):
+    """
+    Task model representing a task in the database
+    
+    Attributes:
+        id: Primary key, auto-incrementing integer
+        title: Task title (required)
+        description: Optional task description
+        completed: Whether the task is completed (default: False)
+        created_at: Timestamp when task was created (auto-generated)
+        updated_at: Timestamp when task was last updated (auto-generated)
+    
+    Reference: https://docs.sqlalchemy.org/en/20/orm/mapped_sql_expressions.html
+    """
+    __tablename__ = "tasks"
+    
+    # Primary key
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    
+    # Task fields
+    title: Mapped[str] = mapped_column(String(200), nullable=False, index=True)
+    description: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    completed: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    
+    # Timestamps
+    # Using server_default with func.now() for automatic timestamp generation
+    # These are set by PostgreSQL on INSERT/UPDATE
+    # Reference: https://docs.sqlalchemy.org/en/20/core/defaults.html#server-side-defaults
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),  # Server-side default for creation time
+        nullable=False,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),  # Server-side default for initial value
+        onupdate=func.now(),  # Update on modification
+        nullable=False,
+    )
+    
+    def __repr__(self) -> str:
+        """String representation of Task"""
+        return f"<Task(id={self.id}, title='{self.title}', completed={self.completed})>"
+

fastapi_auth_starter-0.1.3.data/data/app/models/user.py

@@ -0,0 +1,45 @@
+from datetime import datetime
+from typing import Optional
+from sqlalchemy import Boolean, DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+from app.core.database import Base
+
+
+class User(Base):
+    """
+    User model representing a user in the database
+    
+    Attributes:
+        id: Primary key, UUID
+        email: User email (required)
+        first_name: User first name (optional)
+        last_name: User last name (optional)
+        created_at: Timestamp when user was created (auto-generated)
+        updated_at: Timestamp when user was last updated (auto-generated)
+
+    Reference: https://docs.sqlalchemy.org/en/20/orm/mapped_sql_expressions.html
+    """
+    __tablename__ = "users"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    email: Mapped[str] = mapped_column(String, unique=True, index=True)
+    first_name: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    last_name: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    # pending_verification_token: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    # token_expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+    # is_verified: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),  # Server-side default for creation time
+        nullable=False,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),  # Server-side default for initial value
+        onupdate=func.now(),  # Update on modification
+        nullable=False,
+    )
+
+    def __repr__(self) -> str:
+        "String representation of user"
+        return f"<User(id={self.id}, email='{self.email}', created_at={self.created_at})>"

fastapi_auth_starter-0.1.3.data/data/app/services/__init__.py

@@ -0,0 +1,8 @@
+"""
+Business logic services
+Service layer for application business logic
+"""
+
+from app.services.task import TaskService
+
+__all__ = ["TaskService"]