fastapi-fullstack 0.1.7__py3-none-any.whl

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/csrf.py

@@ -0,0 +1,153 @@
+{%- if cookiecutter.use_jwt %}
+"""CSRF protection middleware for FastAPI.
+
+This module provides CSRF (Cross-Site Request Forgery) protection for
+state-changing HTTP methods (POST, PUT, PATCH, DELETE).
+
+The protection works by:
+1. Setting a CSRF token in a cookie on initial request
+2. Requiring the token to be sent in a header for state-changing requests
+3. Comparing the cookie token with the header token
+
+Usage:
+    Add to your main.py:
+
+    from app.core.csrf import CSRFMiddleware
+
+    app.add_middleware(CSRFMiddleware)
+
+    For endpoints that should be exempt (e.g., login):
+
+    @router.post("/login", tags=["csrf-exempt"])
+    async def login(...):
+        ...
+"""
+
+import secrets
+from collections.abc import Callable
+from typing import ClassVar
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from app.core.config import settings
+
+
+class CSRFMiddleware(BaseHTTPMiddleware):
+    """CSRF protection middleware.
+
+    Protects against Cross-Site Request Forgery attacks by requiring
+    a token to be present in both a cookie and a header for state-changing requests.
+    """
+
+    # Methods that require CSRF protection
+    PROTECTED_METHODS: ClassVar[set[str]] = {"POST", "PUT", "PATCH", "DELETE"}
+
+    # Cookie settings
+    COOKIE_NAME: ClassVar[str] = "csrf_token"
+    HEADER_NAME: ClassVar[str] = "X-CSRF-Token"
+
+    # Paths to exclude from CSRF protection
+    EXEMPT_PATHS: ClassVar[set[str]] = {
+        "/api/v1/auth/login",
+        "/api/v1/auth/register",
+        "/api/v1/auth/refresh",
+        "/api/v1/health",
+        "/api/v1/ready",
+        "/docs",
+        "/openapi.json",
+        "/redoc",
+    }
+
+    def __init__(self, app: Callable, **kwargs):
+        super().__init__(app)
+        self.exempt_paths = set(kwargs.get("exempt_paths", self.EXEMPT_PATHS))
+        self.cookie_name = kwargs.get("cookie_name", self.COOKIE_NAME)
+        self.header_name = kwargs.get("header_name", self.HEADER_NAME)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Handle the request and apply CSRF protection."""
+        # Skip for exempt paths
+        if self._is_exempt(request):
+            return await call_next(request)
+
+        # Get or generate CSRF token
+        csrf_token = request.cookies.get(self.cookie_name)
+        if not csrf_token:
+            csrf_token = self._generate_token()
+
+        # Check CSRF for protected methods
+        if request.method in self.PROTECTED_METHODS:
+            header_token = request.headers.get(self.header_name)
+
+            if not header_token:
+                return JSONResponse(
+                    status_code=403,
+                    content={
+                        "detail": "CSRF token missing",
+                        "message": f"Include the '{self.header_name}' header with the CSRF token",
+                    },
+                )
+
+            if not secrets.compare_digest(csrf_token, header_token):
+                return JSONResponse(
+                    status_code=403,
+                    content={
+                        "detail": "CSRF token invalid",
+                        "message": "The CSRF token does not match",
+                    },
+                )
+
+        # Process the request
+        response = await call_next(request)
+
+        # Set CSRF token cookie if not present
+        if not request.cookies.get(self.cookie_name):
+            response.set_cookie(
+                key=self.cookie_name,
+                value=csrf_token,
+                httponly=False,  # JavaScript needs to read this
+                secure=not settings.DEBUG,
+                samesite="lax",
+                max_age=3600 * 24,  # 24 hours
+            )
+
+        return response
+
+    def _is_exempt(self, request: Request) -> bool:
+        """Check if the request path is exempt from CSRF protection."""
+        path = request.url.path
+
+        # Check exact path matches
+        if path in self.exempt_paths:
+            return True
+
+        # Check path prefixes
+        for exempt in self.exempt_paths:
+            if path.startswith(exempt):
+                return True
+
+        # Check if endpoint has "csrf-exempt" tag
+        route = request.scope.get("route")
+        return bool(route and hasattr(route, "tags") and "csrf-exempt" in route.tags)
+
+    @staticmethod
+    def _generate_token() -> str:
+        """Generate a secure CSRF token."""
+        return secrets.token_urlsafe(32)
+
+
+def get_csrf_token(request: Request) -> str:
+    """Get the current CSRF token from cookies or generate a new one.
+
+    Use this in templates or API responses to provide the token to clients.
+    """
+    token = request.cookies.get(CSRFMiddleware.COOKIE_NAME)
+    if not token:
+        token = secrets.token_urlsafe(32)
+    return token
+
+{%- else %}
+"""CSRF protection - authentication not enabled."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/exceptions.py

@@ -0,0 +1,122 @@
+"""Application exceptions.
+
+Domain exceptions with HTTP status codes for the hybrid approach.
+These exceptions are caught by exception handlers and converted to proper HTTP responses.
+"""
+
+from typing import Any
+
+
+class AppException(Exception):
+    """Base exception for all application errors.
+
+    Attributes:
+        message: Human-readable error message.
+        code: Machine-readable error code for clients.
+        status_code: HTTP status code to return.
+        details: Additional error details (e.g., field names, IDs).
+    """
+
+    message: str = "An error occurred"
+    code: str = "APP_ERROR"
+    status_code: int = 500
+
+    def __init__(
+        self,
+        message: str | None = None,
+        code: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        self.message = message or self.__class__.message
+        self.code = code or self.__class__.code
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r})"
+
+
+# === 4xx Client Errors ===
+
+
+class NotFoundError(AppException):
+    """Resource not found (404)."""
+
+    message = "Resource not found"
+    code = "NOT_FOUND"
+    status_code = 404
+
+
+class AlreadyExistsError(AppException):
+    """Resource already exists (409)."""
+
+    message = "Resource already exists"
+    code = "ALREADY_EXISTS"
+    status_code = 409
+
+
+class ValidationError(AppException):
+    """Validation error (422)."""
+
+    message = "Validation error"
+    code = "VALIDATION_ERROR"
+    status_code = 422
+
+
+class AuthenticationError(AppException):
+    """Authentication failed (401)."""
+
+    message = "Authentication failed"
+    code = "AUTHENTICATION_ERROR"
+    status_code = 401
+
+
+class AuthorizationError(AppException):
+    """Authorization failed - insufficient permissions (403)."""
+
+    message = "Insufficient permissions"
+    code = "AUTHORIZATION_ERROR"
+    status_code = 403
+
+
+class RateLimitError(AppException):
+    """Rate limit exceeded (429)."""
+
+    message = "Rate limit exceeded"
+    code = "RATE_LIMIT_EXCEEDED"
+    status_code = 429
+
+
+class BadRequestError(AppException):
+    """Bad request (400)."""
+
+    message = "Bad request"
+    code = "BAD_REQUEST"
+    status_code = 400
+
+
+# === 5xx Server Errors ===
+
+
+class ExternalServiceError(AppException):
+    """External service unavailable (503)."""
+
+    message = "External service unavailable"
+    code = "EXTERNAL_SERVICE_ERROR"
+    status_code = 503
+
+
+class DatabaseError(AppException):
+    """Database error (500)."""
+
+    message = "Database error"
+    code = "DATABASE_ERROR"
+    status_code = 500
+
+
+class InternalError(AppException):
+    """Internal server error (500)."""
+
+    message = "Internal server error"
+    code = "INTERNAL_ERROR"
+    status_code = 500

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/logfire_setup.py

@@ -0,0 +1,101 @@
+{%- if cookiecutter.enable_logfire %}
+"""Logfire observability configuration."""
+
+import logfire
+
+from app.core.config import settings
+
+
+def setup_logfire() -> None:
+    """Configure Logfire instrumentation."""
+    logfire.configure(
+        token=settings.LOGFIRE_TOKEN,
+        service_name=settings.LOGFIRE_SERVICE_NAME,
+        environment=settings.LOGFIRE_ENVIRONMENT,
+        send_to_logfire="if-token-present",
+    )
+
+
+def instrument_app(app):
+    """Instrument FastAPI app with Logfire."""
+{%- if cookiecutter.logfire_fastapi %}
+    logfire.instrument_fastapi(app)
+{%- else %}
+    pass
+{%- endif %}
+
+
+{%- if cookiecutter.use_postgresql and cookiecutter.logfire_database %}
+
+
+def instrument_asyncpg():
+    """Instrument asyncpg for PostgreSQL."""
+    logfire.instrument_asyncpg()
+{%- endif %}
+
+
+{%- if cookiecutter.use_mongodb and cookiecutter.logfire_database %}
+
+
+def instrument_pymongo():
+    """Instrument PyMongo/Motor for MongoDB."""
+    logfire.instrument_pymongo(capture_statement=settings.DEBUG)
+{%- endif %}
+
+
+{%- if cookiecutter.use_sqlite and cookiecutter.logfire_database %}
+
+
+def instrument_sqlalchemy(engine):
+    """Instrument SQLAlchemy for SQLite."""
+    logfire.instrument_sqlalchemy(engine=engine)
+{%- endif %}
+
+
+{%- if cookiecutter.enable_redis and cookiecutter.logfire_redis %}
+
+
+def instrument_redis():
+    """Instrument Redis."""
+    logfire.instrument_redis()
+{%- endif %}
+
+
+{%- if cookiecutter.use_celery and cookiecutter.logfire_celery %}
+
+
+def instrument_celery():
+    """Instrument Celery."""
+    logfire.instrument_celery()
+{%- endif %}
+
+
+{%- if cookiecutter.logfire_httpx %}
+
+
+def instrument_httpx():
+    """Instrument HTTPX for outgoing HTTP requests."""
+    logfire.instrument_httpx()
+{%- endif %}
+
+
+{%- if cookiecutter.enable_ai_agent and cookiecutter.use_pydantic_ai %}
+
+
+def instrument_pydantic_ai():
+    """Instrument PydanticAI for AI agent observability."""
+    logfire.instrument_pydantic_ai()
+{%- endif %}
+{%- else %}
+"""Logfire is disabled for this project."""
+
+
+def setup_logfire() -> None:
+    """No-op when Logfire is disabled."""
+    pass
+
+
+def instrument_app(app):
+    """No-op when Logfire is disabled."""
+    pass
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/middleware.py

@@ -0,0 +1,99 @@
+"""Application middleware."""
+
+from typing import ClassVar
+from uuid import uuid4
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    """Middleware that adds a unique request ID to each request.
+
+    The request ID is taken from the X-Request-ID header if present,
+    otherwise a new UUID is generated. The ID is added to the response
+    headers and is available in request.state.request_id.
+    """
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Add request ID to request state and response headers."""
+        request_id = request.headers.get("X-Request-ID", str(uuid4()))
+        request.state.request_id = request_id
+
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+        return response
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Middleware that adds security headers to all responses.
+
+    This includes:
+    - Content-Security-Policy (CSP)
+    - X-Content-Type-Options
+    - X-Frame-Options
+    - X-XSS-Protection
+    - Referrer-Policy
+    - Permissions-Policy
+
+    Usage:
+        app.add_middleware(SecurityHeadersMiddleware)
+
+        # Or with custom CSP:
+        app.add_middleware(
+            SecurityHeadersMiddleware,
+            csp_directives={
+                "default-src": "'self'",
+                "script-src": "'self' 'unsafe-inline'",
+            }
+        )
+    """
+
+    DEFAULT_CSP_DIRECTIVES: ClassVar[dict[str, str]] = {
+        "default-src": "'self'",
+        "script-src": "'self'",
+        "style-src": "'self' 'unsafe-inline'",  # Allow inline styles for some UI libs
+        "img-src": "'self' data: https:",
+        "font-src": "'self' data:",
+        "connect-src": "'self'",
+        "frame-ancestors": "'none'",
+        "base-uri": "'self'",
+        "form-action": "'self'",
+    }
+
+    def __init__(
+        self,
+        app,
+        csp_directives: dict | None = None,
+        exclude_paths: set | None = None,
+    ):
+        super().__init__(app)
+        self.csp_directives = csp_directives or self.DEFAULT_CSP_DIRECTIVES
+        self.exclude_paths = exclude_paths or {"/docs", "/redoc", "/openapi.json"}
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Add security headers to the response."""
+        response = await call_next(request)
+
+        # Skip for docs/openapi endpoints which need different CSP
+        if request.url.path in self.exclude_paths:
+            return response
+
+        # Build CSP header
+        csp_value = "; ".join(
+            f"{directive} {value}" for directive, value in self.csp_directives.items()
+        )
+
+        # Add security headers
+        response.headers["Content-Security-Policy"] = csp_value
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Permissions-Policy"] = (
+            "accelerometer=(), camera=(), geolocation=(), gyroscope=(), "
+            "magnetometer=(), microphone=(), payment=(), usb=()"
+        )
+
+        return response

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/oauth.py

@@ -0,0 +1,23 @@
+{%- if cookiecutter.enable_oauth %}
+"""OAuth2 client configuration."""
+
+from authlib.integrations.starlette_client import OAuth
+
+from app.core.config import settings
+
+oauth = OAuth()
+
+{%- if cookiecutter.enable_oauth_google %}
+
+# Configure Google OAuth2
+oauth.register(
+    name="google",
+    client_id=settings.GOOGLE_CLIENT_ID,
+    client_secret=settings.GOOGLE_CLIENT_SECRET,
+    server_metadata_url="https://accounts.google.com/.well-known/openid-configuration",
+    client_kwargs={"scope": "openid email profile"},
+)
+{%- endif %}
+{%- else %}
+"""OAuth module - not configured."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/rate_limit.py

@@ -0,0 +1,58 @@
+{%- if cookiecutter.enable_rate_limiting %}
+"""Rate limiting configuration using slowapi.
+
+Default rate limit: {{ cookiecutter.rate_limit_requests }} requests per {{ cookiecutter.rate_limit_period }} seconds.
+Override with RATE_LIMIT_REQUESTS and RATE_LIMIT_PERIOD environment variables.
+"""
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from app.core.config import settings
+
+
+def get_default_rate_limit() -> str:
+    """Get default rate limit string from settings.
+
+    Returns a rate limit string like "100/minute" or "60/second".
+    """
+    requests = settings.RATE_LIMIT_REQUESTS
+    period = settings.RATE_LIMIT_PERIOD
+
+    # Convert period to a human-readable format
+    period_map = {
+        60: "minute",
+        3600: "hour",
+        86400: "day",
+    }
+
+    if period in period_map:
+        return f"{requests}/{period_map[period]}"
+    # For custom periods, use "per X seconds"
+    return f"{requests}/{period} seconds"
+
+
+# Rate limiter instance with configurable default
+limiter = Limiter(
+    key_func=get_remote_address,
+    default_limits=[get_default_rate_limit()],
+)
+
+# Common rate limit decorators for convenience
+# Usage: @rate_limit_low, @rate_limit_medium, @rate_limit_high
+def rate_limit_low(limit: str = "10/minute"):
+    """Low rate limit for expensive operations."""
+    return limiter.limit(limit)
+
+
+def rate_limit_medium(limit: str = "30/minute"):
+    """Medium rate limit for standard operations."""
+    return limiter.limit(limit)
+
+
+def rate_limit_high(limit: str = "100/minute"):
+    """High rate limit for lightweight operations."""
+    return limiter.limit(limit)
+{%- else %}
+"""Rate limiting - not configured."""
+{%- endif %}