hinbert-fastapi 0.1.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,8 @@
+"""Hinbert FastAPI application package.
+
+This package contains the HTTP application and its independently testable layers.
+It exists so the boilerplate can be installed as a reusable PyPI package while
+still permitting teams to replace individual modules with project-specific code.
+"""
+
+__version__ = "0.1.0"

app/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API namespace."""

app/api/deps/__init__.py

@@ -0,0 +1 @@
+"""Reusable FastAPI dependencies."""

app/api/deps/auth.py

@@ -0,0 +1,40 @@
+"""Bearer-token dependencies for protected routes."""
+
+from uuid import UUID
+
+from fastapi import Depends
+from fastapi.security import OAuth2PasswordBearer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.exceptions.custom_exceptions import UnauthorizedError
+from app.core.security.jwt import decode_token
+from app.db.session import get_db
+from app.models.domain.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+
+
+async def get_current_user(token: str = Depends(oauth2_scheme), session: AsyncSession = Depends(get_db)) -> User:
+    """Decode an access token and load its user, failing closed on any error."""
+    try:
+        subject = UUID(decode_token(token)["sub"])
+    except (ValueError, KeyError) as exc:
+        raise UnauthorizedError() from exc
+    user = await session.get(User, subject)
+    if user is None:
+        raise UnauthorizedError()
+    return user
+
+
+async def get_current_active_user(user: User = Depends(get_current_user)) -> User:
+    """Reject deactivated accounts before protected business operations."""
+    if not user.is_active:
+        raise UnauthorizedError("Inactive account")
+    return user
+
+
+async def get_current_admin(user: User = Depends(get_current_active_user)) -> User:
+    """Require an active account with administrator privileges."""
+    if not user.is_admin:
+        raise UnauthorizedError("Administrator privileges required")
+    return user

app/api/deps/pagination.py

@@ -0,0 +1,8 @@
+"""Validated pagination dependency shared by collection endpoints."""
+
+from fastapi import Query
+
+
+def pagination(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100)) -> tuple[int, int]:
+    """Return SQL offset and bounded page size."""
+    return (page - 1) * page_size, page_size

app/api/v1/__init__.py

@@ -0,0 +1 @@
+"""Version one API namespace."""

app/api/v1/endpoints/__init__.py

@@ -0,0 +1 @@
+"""Version one endpoint modules."""

app/api/v1/endpoints/auth.py

@@ -0,0 +1,255 @@
+"""Authentication endpoints for credentials, recovery, MFA, and OAuth."""
+
+import secrets
+from datetime import UTC, datetime, timedelta
+from urllib.parse import urlencode
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import RedirectResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps.auth import get_current_active_user
+from app.core.config.settings import get_settings
+from app.core.exceptions.custom_exceptions import UnauthorizedError
+from app.core.middleware.rate_limit import limiter
+from app.core.security.password import hash_password, verify_password
+from app.core.security.totp import new_secret, verify_code
+from app.db.session import get_db
+from app.models.domain.email_verification import EmailVerification
+from app.models.domain.password_reset import PasswordReset
+from app.models.domain.refresh_token import RefreshToken
+from app.models.domain.totp_secret import TotpSecret
+from app.models.domain.user import User
+from app.models.schemas.auth import EmailTokenRequest, LoginRequest, SignupRequest
+from app.models.schemas.password import ForgotPassword, ResetPassword
+from app.models.schemas.response import APIResponse
+from app.models.schemas.token import RefreshRequest, TokenResponse
+from app.models.schemas.totp import TotpSetupResponse, TotpVerify
+from app.models.schemas.user import UserOut
+from app.repositories.email_verification_repository import create as create_verification
+from app.repositories.email_verification_repository import get_by_token as get_verification
+from app.repositories.email_verification_repository import mark_used as mark_verification_used
+from app.repositories.password_reset_repository import create as create_reset
+from app.repositories.password_reset_repository import get_by_token as get_reset
+from app.repositories.password_reset_repository import mark_used as mark_reset_used
+from app.repositories.refresh_token_repository import find_active, revoke
+from app.repositories.user_repository import get_by_email
+from app.services.auth_service import hash_refresh_token, issue_tokens
+from app.services.email_service import send_reset_email, send_verification_email
+from app.services.social_auth_service import exchange_provider_code
+from app.services.user_service import create_user
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/signup", response_model=APIResponse[UserOut], status_code=201)
+@limiter.limit("10/minute")
+async def signup(request: Request, payload: SignupRequest, session: AsyncSession = Depends(get_db)):
+    """Create a user and persist a one-time email verification token."""
+    user = await create_user(session, payload)
+    raw_token = secrets.token_urlsafe(32)
+    await create_verification(
+        session,
+        EmailVerification(
+            user_id=user.id,
+            token_hash=hash_refresh_token(raw_token),
+            expires_at=datetime.now(UTC) + timedelta(hours=24),
+        ),
+    )
+    send_verification_email(user, raw_token)
+    return APIResponse(message="Account created", data=user, status_code=201)
+
+
+@router.post("/login", response_model=APIResponse[TokenResponse])
+@limiter.limit("10/minute")
+async def login(request: Request, payload: LoginRequest, session: AsyncSession = Depends(get_db)):
+    """Verify credentials and issue access plus opaque refresh credentials."""
+    user = await get_by_email(session, str(payload.email))
+    if user is None or not user.is_active or not verify_password(payload.password, user.password_hash):
+        raise UnauthorizedError("Invalid credentials")
+    access, refresh, digest, expiry = issue_tokens(user.id)
+    session.add(RefreshToken(user_id=user.id, token_hash=digest, expires_at=expiry))
+    await session.commit()
+    return APIResponse(message="Login successful", data=TokenResponse(access_token=access, refresh_token=refresh))
+
+
+@router.post("/refresh", response_model=APIResponse[TokenResponse])
+@limiter.limit("30/minute")
+async def refresh(request: Request, payload: RefreshRequest, session: AsyncSession = Depends(get_db)):
+    """Rotate a valid refresh token and revoke the predecessor."""
+    stored = await find_active(session, hash_refresh_token(payload.refresh_token))
+    if stored is None:
+        raise UnauthorizedError("Invalid refresh token")
+    user = await session.get(User, stored.user_id)
+    if user is None or not user.is_active:
+        raise UnauthorizedError("Inactive account")
+    access, raw_refresh, digest, expiry = issue_tokens(user.id)
+    await revoke(session, stored)
+    session.add(RefreshToken(user_id=user.id, token_hash=digest, expires_at=expiry))
+    await session.commit()
+    return APIResponse(message="Token refreshed", data=TokenResponse(access_token=access, refresh_token=raw_refresh))
+
+
+@router.post("/logout", response_model=APIResponse[None])
+@limiter.limit("30/minute")
+async def logout(request: Request, payload: RefreshRequest, session: AsyncSession = Depends(get_db)):
+    """Revoke the supplied refresh token without revealing whether it existed."""
+    stored = await find_active(session, hash_refresh_token(payload.refresh_token))
+    if stored is not None:
+        await revoke(session, stored)
+    return APIResponse(message="Logged out", data=None)
+
+
+@router.post("/verify-email", response_model=APIResponse[None])
+@limiter.limit("10/minute")
+async def verify_email(request: Request, payload: EmailTokenRequest, session: AsyncSession = Depends(get_db)):
+    """Consume a verification token and activate its account."""
+    stored = await get_verification(session, hash_refresh_token(payload.token))
+    if stored is None:
+        raise HTTPException(status_code=400, detail="Invalid verification token")
+    user = await session.get(User, stored.user_id)
+    if user is None:
+        raise HTTPException(status_code=400, detail="Invalid verification token")
+    user.is_verified = True
+    user.is_active = True
+    await mark_verification_used(session, stored)
+    return APIResponse(message="Email verified", data=None)
+
+
+@router.post("/forgot-password", response_model=APIResponse[None])
+@limiter.limit("5/minute")
+async def forgot_password(request: Request, payload: ForgotPassword, session: AsyncSession = Depends(get_db)):
+    """Issue a reset token and send it without disclosing account existence."""
+    user = await get_by_email(session, str(payload.email))
+    if user is not None:
+        raw_token = secrets.token_urlsafe(32)
+        await create_reset(
+            session,
+            PasswordReset(
+                user_id=user.id,
+                token_hash=hash_refresh_token(raw_token),
+                expires_at=datetime.now(UTC) + timedelta(hours=1),
+            ),
+        )
+        send_reset_email(user, raw_token)
+    return APIResponse(message="If the account exists, a reset email was sent", data=None)
+
+
+@router.post("/reset-password", response_model=APIResponse[None])
+@limiter.limit("5/minute")
+async def reset_password(request: Request, payload: ResetPassword, session: AsyncSession = Depends(get_db)):
+    """Consume a reset token and replace the stored bcrypt password hash."""
+    stored = await get_reset(session, hash_refresh_token(payload.token))
+    if stored is None:
+        raise HTTPException(status_code=400, detail="Invalid reset token")
+    user = await session.get(User, stored.user_id)
+    if user is None:
+        raise HTTPException(status_code=400, detail="Invalid reset token")
+    user.password_hash = hash_password(payload.password)
+    await mark_reset_used(session, stored)
+    return APIResponse(message="Password reset", data=None)
+
+
+@router.post("/totp/setup", response_model=APIResponse[TotpSetupResponse])
+@limiter.limit("10/minute")
+async def setup_totp(
+    request: Request, user: User = Depends(get_current_active_user), session: AsyncSession = Depends(get_db)
+):
+    """Generate encrypted TOTP provisioning data for the current user."""
+    secret = new_secret()
+    record = TotpSecret(user_id=user.id)
+    record.secret = secret
+    session.add(record)
+    await session.commit()
+    uri = __import__("pyotp").TOTP(secret).provisioning_uri(name=user.email, issuer_name=get_settings().app_name)
+    return APIResponse(message="TOTP configured", data=TotpSetupResponse(secret=secret, provisioning_uri=uri))
+
+
+@router.post("/totp/verify", response_model=APIResponse[None])
+@limiter.limit("10/minute")
+async def verify_totp(
+    request: Request,
+    payload: TotpVerify,
+    user: User = Depends(get_current_active_user),
+    session: AsyncSession = Depends(get_db),
+):
+    """Verify the user's encrypted TOTP secret and enable the factor."""
+    record = await session.get(TotpSecret, user.id)
+    if record is None or not verify_code(record.secret, payload.code):
+        raise HTTPException(status_code=400, detail="Invalid TOTP code")
+    return APIResponse(message="TOTP verified", data=None)
+
+
+@router.get("/google")
+@limiter.limit("30/minute")
+async def google_login(request: Request):
+    """Redirect to Google's OAuth authorization endpoint."""
+    settings = get_settings()
+    params = urlencode(
+        {
+            "client_id": settings.google_client_id,
+            "redirect_uri": "/api/v1/auth/google/callback",
+            "response_type": "code",
+            "scope": "openid email profile",
+        }
+    )
+    return RedirectResponse(f"https://accounts.google.com/o/oauth2/v2/auth?{params}")
+
+
+@router.get("/google/callback", response_model=APIResponse[TokenResponse])
+@limiter.limit("30/minute")
+async def google_callback(request: Request, code: str, session: AsyncSession = Depends(get_db)):
+    """Exchange Google's code and provision or authenticate the user."""
+    return await _social_login("google", code, session)
+
+
+@router.get("/facebook")
+@limiter.limit("30/minute")
+async def facebook_login(request: Request):
+    """Redirect to Facebook's OAuth authorization endpoint."""
+    settings = get_settings()
+    params = urlencode(
+        {
+            "client_id": settings.facebook_client_id,
+            "redirect_uri": "/api/v1/auth/facebook/callback",
+            "response_type": "code",
+            "scope": "email,public_profile",
+        }
+    )
+    return RedirectResponse(f"https://www.facebook.com/v19.0/dialog/oauth?{params}")
+
+
+@router.get("/facebook/callback", response_model=APIResponse[TokenResponse])
+@limiter.limit("30/minute")
+async def facebook_callback(request: Request, code: str, session: AsyncSession = Depends(get_db)):
+    """Exchange Facebook's code and provision or authenticate the user."""
+    return await _social_login("facebook", code, session)
+
+
+async def _social_login(provider: str, code: str, session: AsyncSession):
+    """Normalize a provider profile and issue the same token pair as password login."""
+    profile = await exchange_provider_code(provider, code)
+    user = await get_by_email(session, profile["email"])
+    if user is None:
+        user = User(
+            email=profile["email"],
+            full_name=profile["full_name"],
+            password_hash=hash_password(secrets.token_urlsafe(32)),
+            is_verified=True,
+        )
+        session.add(user)
+        await session.flush()
+    access, refresh_token, digest, expiry = issue_tokens(user.id)
+    session.add(RefreshToken(user_id=user.id, token_hash=digest, expires_at=expiry))
+    await session.commit()
+    return APIResponse(
+        message=f"{provider.title()} login successful",
+        data=TokenResponse(access_token=access, refresh_token=refresh_token),
+    )
+
+
+@router.get("/me", response_model=APIResponse[UserOut])
+@limiter.limit("60/minute")
+async def me(request: Request, user: User = Depends(get_current_active_user)):
+    """Return the authenticated user's safe profile."""
+    return APIResponse(data=user)

app/api/v1/endpoints/dashboard.py

@@ -0,0 +1,23 @@
+"""Operational dashboard endpoint placeholder for aggregated metrics."""
+
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps.auth import get_current_admin
+from app.core.middleware.rate_limit import limiter
+from app.db.session import get_db
+from app.models.domain.product import Product
+from app.models.domain.user import User
+from app.models.schemas.response import APIResponse
+
+router = APIRouter(prefix="/dashboard", tags=["dashboard"])
+
+
+@router.get("/stats", response_model=APIResponse[dict[str, int]])
+@limiter.limit("60/minute")
+async def stats(request: Request, _: User = Depends(get_current_admin), session: AsyncSession = Depends(get_db)):
+    """Return current user and product counts for administrators."""
+    users = await session.scalar(select(func.count()).select_from(User))
+    products = await session.scalar(select(func.count()).select_from(Product))
+    return APIResponse(data={"users": users or 0, "products": products or 0, "active_sessions": 0})

app/api/v1/endpoints/products.py

@@ -0,0 +1,102 @@
+"""Product CRUD endpoints with bounded filtering, sorting, and pagination."""
+
+from decimal import Decimal
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, Request
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps.auth import get_current_active_user
+from app.api.deps.pagination import pagination
+from app.core.exceptions.custom_exceptions import NotFoundError, UnauthorizedError
+from app.core.middleware.rate_limit import limiter
+from app.db.session import get_db
+from app.models.domain.product import Product
+from app.models.domain.user import User
+from app.models.schemas.product import ProductCreate, ProductOut, ProductPage
+from app.models.schemas.response import APIResponse
+from app.repositories.product_repository import ProductRepository
+from app.services.product_service import create_product, update_product
+
+router = APIRouter(prefix="/products", tags=["products"])
+
+
+@router.post("", response_model=APIResponse[ProductOut], status_code=201)
+@limiter.limit("60/minute")
+async def create(
+    request: Request,
+    payload: ProductCreate,
+    user: User = Depends(get_current_active_user),
+    session: AsyncSession = Depends(get_db),
+):
+    """Create a product owned by the authenticated user."""
+    product = await create_product(session, payload)
+    product.owner_id = user.id
+    await session.commit()
+    return APIResponse(message="Product created", data=product, status_code=201)
+
+
+@router.get("", response_model=APIResponse[ProductPage])
+@limiter.limit("120/minute")
+async def list_products(
+    request: Request,
+    page: tuple[int, int] = Depends(pagination),
+    category: str | None = None,
+    min_price: Decimal | None = Query(None, ge=0),
+    max_price: Decimal | None = Query(None, ge=0),
+    sort_by: str = Query("created_at", pattern="^(name|price|created_at)$"),
+    session: AsyncSession = Depends(get_db),
+):
+    """Return products and deterministic pagination metadata."""
+    offset, limit = page
+    items = await ProductRepository(session).get_all(offset, limit, category, min_price, max_price, sort_by)
+    total = await session.scalar(select(func.count()).select_from(Product))
+    return APIResponse(data={"items": items, "total_count": total or 0, "page": offset // limit + 1, "limit": limit})
+
+
+@router.get("/{product_id}", response_model=APIResponse[ProductOut])
+@limiter.limit("120/minute")
+async def get_product(request: Request, product_id: UUID, session: AsyncSession = Depends(get_db)):
+    """Return one product by UUID."""
+    product = await session.get(Product, product_id)
+    if product is None:
+        raise NotFoundError("Product not found")
+    return APIResponse(data=product)
+
+
+@router.put("/{product_id}", response_model=APIResponse[ProductOut])
+@limiter.limit("60/minute")
+async def update_product_endpoint(
+    request: Request,
+    product_id: UUID,
+    payload: ProductCreate,
+    user: User = Depends(get_current_active_user),
+    session: AsyncSession = Depends(get_db),
+):
+    """Update a product when the caller owns it or is an administrator."""
+    product = await session.get(Product, product_id)
+    if product is None:
+        raise NotFoundError("Product not found")
+    if product.owner_id not in {None, user.id} and not user.is_admin:
+        raise UnauthorizedError("Product ownership required")
+    return APIResponse(data=await update_product(session, product, payload), message="Product updated")
+
+
+@router.delete("/{product_id}", response_model=APIResponse[None])
+@limiter.limit("60/minute")
+async def delete_product(
+    request: Request,
+    product_id: UUID,
+    user: User = Depends(get_current_active_user),
+    session: AsyncSession = Depends(get_db),
+):
+    """Delete a product when the caller owns it or is an administrator."""
+    product = await session.get(Product, product_id)
+    if product is None:
+        raise NotFoundError("Product not found")
+    if product.owner_id not in {None, user.id} and not user.is_admin:
+        raise UnauthorizedError("Product ownership required")
+    await session.delete(product)
+    await session.commit()
+    return APIResponse(message="Product deleted", data=None)

app/api/v1/endpoints/users.py

@@ -0,0 +1,89 @@
+"""Authenticated profile and administrator user-management endpoints."""
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps.auth import get_current_active_user, get_current_admin
+from app.api.deps.pagination import pagination
+from app.core.middleware.rate_limit import limiter
+from app.db.session import get_db
+from app.models.domain.user import User
+from app.models.schemas.response import APIResponse
+from app.models.schemas.user import AdminUserUpdate, UserOut, UserUpdate
+from app.repositories import user_repository
+from app.services.user_service import update_user
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.patch("/me", response_model=APIResponse[UserOut])
+@limiter.limit("60/minute")
+async def update_me(
+    request: Request,
+    payload: UserUpdate,
+    user: User = Depends(get_current_active_user),
+    session: AsyncSession = Depends(get_db),
+):
+    """Update allowed profile fields for the current account."""
+    return APIResponse(data=await update_user(session, user, payload), message="Profile updated")
+
+
+@router.get("", response_model=APIResponse[list[UserOut]])
+@limiter.limit("60/minute")
+async def list_users(
+    request: Request,
+    page: tuple[int, int] = Depends(pagination),
+    _: User = Depends(get_current_admin),
+    session: AsyncSession = Depends(get_db),
+):
+    """List users for administrators with bounded pagination."""
+    return APIResponse(data=await user_repository.get_all(session, *page))
+
+
+@router.get("/{user_id}", response_model=APIResponse[UserOut])
+@limiter.limit("60/minute")
+async def get_user(
+    request: Request, user_id: UUID, _: User = Depends(get_current_admin), session: AsyncSession = Depends(get_db)
+):
+    """Return one user to an administrator."""
+    user = await user_repository.get_by_id(session, user_id)
+    if user is None:
+        from app.core.exceptions.custom_exceptions import NotFoundError
+
+        raise NotFoundError("User not found")
+    return APIResponse(data=user)
+
+
+@router.patch("/{user_id}", response_model=APIResponse[UserOut])
+@limiter.limit("30/minute")
+async def update_user_admin(
+    request: Request,
+    user_id: UUID,
+    payload: AdminUserUpdate,
+    _: User = Depends(get_current_admin),
+    session: AsyncSession = Depends(get_db),
+):
+    """Update profile and role fields as an administrator."""
+    user = await user_repository.get_by_id(session, user_id)
+    if user is None:
+        from app.core.exceptions.custom_exceptions import NotFoundError
+
+        raise NotFoundError("User not found")
+    return APIResponse(data=await user_repository.update(session, user, payload.model_dump(exclude_none=True)))
+
+
+@router.delete("/{user_id}", response_model=APIResponse[None])
+@limiter.limit("30/minute")
+async def delete_user(
+    request: Request, user_id: UUID, _: User = Depends(get_current_admin), session: AsyncSession = Depends(get_db)
+):
+    """Hard-delete a user and dependent records as an administrator."""
+    user = await user_repository.get_by_id(session, user_id)
+    if user is None:
+        from app.core.exceptions.custom_exceptions import NotFoundError
+
+        raise NotFoundError("User not found")
+    await user_repository.delete(session, user)
+    return APIResponse(message="User deleted", data=None)

app/api/v1/routers/__init__.py

@@ -0,0 +1 @@
+"""Router registration namespace."""

app/api/v1/routers/api_router.py

@@ -0,0 +1,11 @@
+"""Central versioned router registry."""
+
+from fastapi import APIRouter
+
+from app.api.v1.endpoints import auth, dashboard, products, users
+
+api_router = APIRouter()
+api_router.include_router(auth.router)
+api_router.include_router(users.router)
+api_router.include_router(products.router)
+api_router.include_router(dashboard.router)

app/core/__init__.py

@@ -0,0 +1 @@
+"""Cross-cutting configuration, security, middleware, and exception modules."""

app/core/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration and database setup namespace."""

app/core/config/database.py

@@ -0,0 +1,13 @@
+"""Async SQLAlchemy engine and session factory.
+
+The engine is created lazily at import time and sessions are request-scoped by
+dependency. Pool values should be tuned to deployment capacity, not guessed in
+individual endpoints.
+"""
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config.settings import get_settings
+
+engine = create_async_engine(get_settings().database_url, pool_pre_ping=True)
+SessionLocal = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)

app/core/config/settings.py

@@ -0,0 +1,83 @@
+"""Validated environment configuration for every runtime component.
+
+Pydantic Settings reads environment variables and an optional ``.env`` file,
+making deployments twelve-factor friendly. Change defaults here only for safe
+local development; production secrets must come from a secret manager.
+"""
+
+from functools import lru_cache
+
+from pydantic import AliasChoices, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings with validation and conservative security defaults."""
+
+    app_name: str = Field(default="Hinbert FastAPI", validation_alias=AliasChoices("APP_NAME", "HINBERT_APP_NAME"))
+    api_prefix: str = "/api/v1"
+    environment: str = Field(default="development", validation_alias=AliasChoices("ENVIRONMENT", "HINBERT_ENVIRONMENT"))
+    database_url: str = Field(
+        default="postgresql+asyncpg://postgres:postgres@localhost:5432/app",
+        validation_alias=AliasChoices("DATABASE_URL", "HINBERT_DATABASE_URL"),
+    )
+    redis_url: str = Field(
+        default="redis://localhost:6379/0", validation_alias=AliasChoices("REDIS_URL", "HINBERT_REDIS_URL")
+    )
+    debug: bool = Field(default=False, validation_alias=AliasChoices("DEBUG", "HINBERT_DEBUG"))
+    jwt_secret_key: SecretStr = Field(
+        default=SecretStr("change-me-in-production"),
+        validation_alias=AliasChoices("SECRET_KEY", "HINBERT_JWT_SECRET_KEY"),
+    )
+    jwt_algorithm: str = Field(default="HS256", validation_alias=AliasChoices("ALGORITHM", "HINBERT_JWT_ALGORITHM"))
+    access_token_minutes: int = Field(
+        default=15, validation_alias=AliasChoices("ACCESS_TOKEN_EXPIRE_MINUTES", "HINBERT_ACCESS_TOKEN_MINUTES")
+    )
+    refresh_token_days: int = Field(
+        default=30, validation_alias=AliasChoices("REFRESH_TOKEN_EXPIRE_DAYS", "HINBERT_REFRESH_TOKEN_DAYS")
+    )
+    cors_origins: list[str] = Field(
+        default_factory=lambda: ["http://localhost:3000"],
+        validation_alias=AliasChoices("BACKEND_CORS_ORIGINS", "HINBERT_CORS_ORIGINS"),
+    )
+    smtp_host: str = Field(default="localhost", validation_alias=AliasChoices("SMTP_HOST", "HINBERT_SMTP_HOST"))
+    smtp_port: int = Field(default=587, validation_alias=AliasChoices("SMTP_PORT", "HINBERT_SMTP_PORT"))
+    smtp_username: str = Field(default="", validation_alias=AliasChoices("SMTP_USER", "HINBERT_SMTP_USERNAME"))
+    smtp_password: SecretStr = Field(
+        default=SecretStr(""), validation_alias=AliasChoices("SMTP_PASSWORD", "HINBERT_SMTP_PASSWORD")
+    )
+    smtp_from: str = Field(
+        default="no-reply@example.com", validation_alias=AliasChoices("EMAIL_FROM", "HINBERT_SMTP_FROM")
+    )
+    google_client_id: str = Field(
+        default="", validation_alias=AliasChoices("GOOGLE_CLIENT_ID", "HINBERT_GOOGLE_CLIENT_ID")
+    )
+    google_client_secret: SecretStr = Field(
+        default=SecretStr(""), validation_alias=AliasChoices("GOOGLE_CLIENT_SECRET", "HINBERT_GOOGLE_CLIENT_SECRET")
+    )
+    facebook_client_id: str = Field(
+        default="", validation_alias=AliasChoices("FACEBOOK_CLIENT_ID", "HINBERT_FACEBOOK_CLIENT_ID")
+    )
+    facebook_client_secret: SecretStr = Field(
+        default=SecretStr(""), validation_alias=AliasChoices("FACEBOOK_CLIENT_SECRET", "HINBERT_FACEBOOK_CLIENT_SECRET")
+    )
+    rate_limit: str = Field(
+        default="100/minute", validation_alias=AliasChoices("RATE_LIMIT_PER_MINUTE", "HINBERT_RATE_LIMIT")
+    )
+
+    model_config = SettingsConfigDict(env_file=".env", env_prefix="", extra="ignore")
+
+    @field_validator("jwt_secret_key")
+    @classmethod
+    def reject_weak_production_secret(cls, value: SecretStr) -> SecretStr:
+        """Prevent the documented development secret from reaching production."""
+        secret = value.get_secret_value()
+        if secret == "change-me-in-production" or len(secret) < 32:
+            raise ValueError("SECRET_KEY must be at least 32 characters and must not use the default value")
+        return value
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return one cached, validated settings object per process."""
+    return Settings()

app/core/exceptions/__init__.py

@@ -0,0 +1 @@
+"""Public application exception types."""