fastapi-fullstack 0.1.7__py3-none-any.whl

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

@@ -0,0 +1,271 @@
+"""Input sanitization utilities.
+
+This module provides security-focused input sanitization functions:
+- HTML sanitization to prevent XSS attacks
+- Path traversal prevention for file operations
+- Common input cleaning utilities
+
+Note: SQL injection is prevented by using SQLAlchemy ORM with parameterized queries.
+"""
+
+import html
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import TypeVar
+
+# Default allowed HTML tags for rich text content
+DEFAULT_ALLOWED_TAGS = frozenset({
+    "a", "abbr", "acronym", "b", "blockquote", "br", "code",
+    "em", "i", "li", "ol", "p", "pre", "strong", "ul",
+})
+
+# Default allowed HTML attributes
+DEFAULT_ALLOWED_ATTRIBUTES = {
+    "a": frozenset({"href", "title", "rel"}),
+    "abbr": frozenset({"title"}),
+    "acronym": frozenset({"title"}),
+}
+
+
+def sanitize_html(
+    content: str,
+    allowed_tags: frozenset[str] | None = None,
+    strip: bool = True,
+) -> str:
+    """Sanitize HTML content to prevent XSS attacks.
+
+    This is a simple implementation that escapes all HTML.
+    For rich text support, consider using the `bleach` library.
+
+    Args:
+        content: The HTML content to sanitize.
+        allowed_tags: Not used in simple mode (for bleach compatibility).
+        strip: Not used in simple mode (for bleach compatibility).
+
+    Returns:
+        Escaped HTML-safe string.
+
+    Example:
+        >>> sanitize_html("<script>alert('xss')</script>")
+        "&lt;script&gt;alert('xss')&lt;/script&gt;"
+    """
+    if not content:
+        return ""
+
+    return html.escape(content)
+
+
+def sanitize_filename(filename: str, allow_unicode: bool = False) -> str:
+    """Sanitize a filename to prevent path traversal and unsafe characters.
+
+    Args:
+        filename: The filename to sanitize.
+        allow_unicode: Whether to allow unicode characters.
+
+    Returns:
+        A safe filename string.
+
+    Example:
+        >>> sanitize_filename("../../../etc/passwd")
+        "etc_passwd"
+        >>> sanitize_filename("hello world.txt")
+        "hello_world.txt"
+    """
+    if not filename:
+        return ""
+
+    # Normalize unicode
+    if allow_unicode:
+        filename = unicodedata.normalize("NFKC", filename)
+    else:
+        filename = (
+            unicodedata.normalize("NFKD", filename)
+            .encode("ascii", "ignore")
+            .decode("ascii")
+        )
+
+    # Get just the filename (remove any path components)
+    filename = os.path.basename(filename)
+
+    # Remove null bytes
+    filename = filename.replace("\x00", "")
+
+    # Replace path separators and special characters
+    filename = re.sub(r"[/\\:*?\"<>|]", "_", filename)
+
+    # Replace multiple underscores/spaces with single underscore
+    filename = re.sub(r"[\s_]+", "_", filename)
+
+    # Remove leading/trailing underscores and dots
+    filename = filename.strip("._")
+
+    # Ensure we have a valid filename
+    if not filename:
+        return "unnamed"
+
+    return filename
+
+
+def validate_safe_path(
+    base_dir: Path | str,
+    user_path: str,
+) -> Path:
+    """Validate that a user-provided path is within the allowed base directory.
+
+    Prevents path traversal attacks by ensuring the resolved path
+    is within the expected directory.
+
+    Args:
+        base_dir: The base directory that all paths must be within.
+        user_path: The user-provided path to validate.
+
+    Returns:
+        The resolved, safe path.
+
+    Raises:
+        ValueError: If the path would escape the base directory.
+
+    Example:
+        >>> validate_safe_path("/uploads", "../../../etc/passwd")
+        Raises ValueError
+        >>> validate_safe_path("/uploads", "images/photo.jpg")
+        Path("/uploads/images/photo.jpg")
+    """
+    base_path = Path(base_dir).resolve()
+    user_path_sanitized = sanitize_filename(user_path.lstrip("/\\"))
+
+    # Resolve the full path
+    full_path = (base_path / user_path_sanitized).resolve()
+
+    # Check if the resolved path is within the base directory
+    try:
+        full_path.relative_to(base_path)
+    except ValueError as err:
+        raise ValueError(
+            f"Path traversal detected: {user_path!r} would escape {base_dir!r}"
+        ) from err
+
+    return full_path
+
+
+def sanitize_string(
+    value: str,
+    max_length: int | None = None,
+    allow_newlines: bool = True,
+    strip_whitespace: bool = True,
+) -> str:
+    """Sanitize a string input with various options.
+
+    Args:
+        value: The string to sanitize.
+        max_length: Maximum allowed length (truncates if exceeded).
+        allow_newlines: Whether to preserve newlines.
+        strip_whitespace: Whether to strip leading/trailing whitespace.
+
+    Returns:
+        Sanitized string.
+    """
+    if not value:
+        return ""
+
+    # Strip null bytes and other control characters (except newlines if allowed)
+    if allow_newlines:
+        value = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", value)
+    else:
+        value = re.sub(r"[\x00-\x1f\x7f]", "", value)
+
+    # Strip whitespace if requested
+    if strip_whitespace:
+        value = value.strip()
+
+    # Truncate if needed
+    if max_length is not None and len(value) > max_length:
+        value = value[:max_length]
+
+    return value
+
+
+def sanitize_email(email: str) -> str:
+    """Basic email sanitization.
+
+    Note: For proper email validation, use Pydantic's EmailStr type.
+    This function only performs basic cleaning.
+
+    Args:
+        email: The email address to sanitize.
+
+    Returns:
+        Lowercased, stripped email.
+    """
+    if not email:
+        return ""
+
+    return email.strip().lower()
+
+
+T = TypeVar("T", int, float)
+
+
+def sanitize_numeric(
+    value: str | int | float,
+    value_type: type[T],
+    min_value: T | None = None,
+    max_value: T | None = None,
+    default: T | None = None,
+) -> T | None:
+    """Sanitize and validate a numeric value.
+
+    Args:
+        value: The value to sanitize (can be string or numeric).
+        value_type: The expected type (int or float).
+        min_value: Minimum allowed value.
+        max_value: Maximum allowed value.
+        default: Default value if conversion fails.
+
+    Returns:
+        The sanitized numeric value, or default if invalid.
+
+    Example:
+        >>> sanitize_numeric("100", int, min_value=0, max_value=1000)
+        100
+        >>> sanitize_numeric("abc", int, default=0)
+        0
+    """
+    try:
+        result = value_type(value)
+
+        if min_value is not None and result < min_value:
+            result = min_value
+        if max_value is not None and result > max_value:
+            result = max_value
+
+        return result
+    except (ValueError, TypeError):
+        return default
+
+
+def escape_sql_like(pattern: str, escape_char: str = "\\") -> str:
+    """Escape special characters in a LIKE pattern.
+
+    Use this when building LIKE queries with user input.
+
+    Args:
+        pattern: The pattern to escape.
+        escape_char: The escape character to use.
+
+    Returns:
+        Escaped pattern safe for use in LIKE queries.
+
+    Example:
+        >>> escape_sql_like("100%")
+        "100\\%"
+        >>> escape_sql_like("under_score")
+        "under\\_score"
+    """
+    # Escape the escape character first, then special chars
+    pattern = pattern.replace(escape_char, escape_char + escape_char)
+    pattern = pattern.replace("%", escape_char + "%")
+    pattern = pattern.replace("_", escape_char + "_")
+    return pattern

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

@@ -0,0 +1,102 @@
+{%- if cookiecutter.use_jwt %}
+"""Security utilities for JWT authentication."""
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import bcrypt
+import jwt
+
+from app.core.config import settings
+
+
+def create_access_token(
+    subject: str | Any,
+    expires_delta: timedelta | None = None,
+) -> str:
+    """Create a JWT access token."""
+    if expires_delta:
+        expire = datetime.now(UTC) + expires_delta
+    else:
+        expire = datetime.now(UTC) + timedelta(
+            minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+        )
+
+    to_encode = {"exp": expire, "sub": str(subject), "type": "access"}
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def create_refresh_token(
+    subject: str | Any,
+    expires_delta: timedelta | None = None,
+) -> str:
+    """Create a JWT refresh token."""
+    if expires_delta:
+        expire = datetime.now(UTC) + expires_delta
+    else:
+        expire = datetime.now(UTC) + timedelta(
+            minutes=settings.REFRESH_TOKEN_EXPIRE_MINUTES
+        )
+
+    to_encode = {"exp": expire, "sub": str(subject), "type": "refresh"}
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def verify_token(token: str) -> dict[str, Any] | None:
+    """Verify a JWT token and return payload."""
+    try:
+        payload = jwt.decode(
+            token,
+            settings.SECRET_KEY,
+            algorithms=[settings.ALGORITHM],
+        )
+        return payload
+    except jwt.PyJWTError:
+        return None
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against a hash."""
+    return bcrypt.checkpw(
+        plain_password.encode("utf-8"),
+        hashed_password.encode("utf-8"),
+    )
+
+
+def get_password_hash(password: str) -> str:
+    """Hash a password."""
+    return bcrypt.hashpw(
+        password.encode("utf-8"),
+        bcrypt.gensalt(),
+    ).decode("utf-8")
+
+
+{%- elif cookiecutter.use_api_key %}
+"""Security utilities for API Key authentication."""
+
+from fastapi import HTTPException, Security, status
+from fastapi.security import APIKeyHeader
+
+from app.core.config import settings
+
+api_key_header = APIKeyHeader(name=settings.API_KEY_HEADER, auto_error=False)
+
+
+async def verify_api_key(api_key: str = Security(api_key_header)) -> str:
+    """Verify API key from header."""
+    if api_key is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="API Key header missing",
+        )
+    if api_key != settings.API_KEY:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid API Key",
+        )
+    return api_key
+
+
+{%- else %}
+"""Security - not configured."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/db/__init__.py

@@ -0,0 +1,7 @@
+"""Database module."""
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+
+from app.db.base import Base
+
+__all__ = ["Base"]
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/db/base.py

@@ -0,0 +1,41 @@
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+"""SQLAlchemy base model."""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, MetaData, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+# Naming convention for database constraints and indexes
+# This ensures consistent naming across all migrations
+NAMING_CONVENTION = {
+    "ix": "%(column_0_label)s_idx",
+    "uq": "%(table_name)s_%(column_0_name)s_key",
+    "ck": "%(table_name)s_%(constraint_name)s_check",
+    "fk": "%(table_name)s_%(column_0_name)s_fkey",
+    "pk": "%(table_name)s_pkey",
+}
+
+
+class Base(DeclarativeBase):
+    """Base class for all SQLAlchemy models."""
+
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+
+
+class TimestampMixin:
+    """Mixin for created_at and updated_at timestamps."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        onupdate=func.now(),
+        nullable=True,
+    )
+{%- else %}
+"""Database base - not using SQLAlchemy."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/db/models/__init__.py

@@ -0,0 +1,31 @@
+"""Database models."""
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+# ruff: noqa: I001, RUF022 - Imports structured for Jinja2 template conditionals
+{%- endif %}
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+{%- set models = [] %}
+{%- if cookiecutter.use_jwt %}
+{%- set _ = models.append("User") %}
+from app.db.models.user import User
+{%- endif %}
+{%- if cookiecutter.enable_session_management and cookiecutter.use_jwt %}
+{%- set _ = models.append("Session") %}
+from app.db.models.session import Session
+{%- endif %}
+{%- if cookiecutter.include_example_crud %}
+{%- set _ = models.append("Item") %}
+from app.db.models.item import Item
+{%- endif %}
+{%- if cookiecutter.enable_conversation_persistence %}
+{%- set _ = models.extend(["Conversation", "Message", "ToolCall"]) %}
+from app.db.models.conversation import Conversation, Message, ToolCall
+{%- endif %}
+{%- if cookiecutter.enable_webhooks %}
+{%- set _ = models.extend(["Webhook", "WebhookDelivery"]) %}
+from app.db.models.webhook import Webhook, WebhookDelivery
+{%- endif %}
+{%- if models %}
+
+__all__ = {{ models }}
+{%- endif %}
+{%- endif %}