first commit

Author: YuriFontella

.env.example

@@ -0,0 +1,24 @@
+# Security Settings
+SECRET_KEY=change_me_dev_secret_key
+SESSION_SALT=xYzDeV@0000
+PBKDF2_ITERATIONS=600_000
+PBKDF2_ALGORITHM=sha256
+MAX_FINGERPRINT_VALUE=100000000
+BCRYPT_GENSALT=12
+
+# CORS (comma-separated list)
+ALLOWED_CORS_ORIGINS=*
+
+# CSRF Settings
+CSRF_COOKIE_NAME=XSRF-TOKEN
+CSRF_COOKIE_SECURE=false
+
+# Database Settings
+DATABASE_DSN=postgresql://postgres:password@localhost:5432/app_db
+DATABASE_MIN_SIZE=4
+DATABASE_MAX_SIZE=16
+DATABASE_MAX_QUERIES=50000
+DATABASE_MAX_INACTIVE_CONNECTION_LIFETIME=300.0
+
+# JWT Settings
+JWT_ALGORITHM=HS256

.gitignore

@@ -0,0 +1,9 @@
+__pycache__
+.idea
+.env
+.venv
+venv
+.DS_Store
+.ruff_cache
+.vscode
+poetry.lock

README.md

@@ -0,0 +1,78 @@
+## Litestar Auth
+
+### 1. Prerequisites
+
+* Python 3.13+
+* [Poetry](https://python-poetry.org/) (dependency manager)
+
+Poetry installation (if you don't have it):
+
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+### 2. Environment variables (.env)
+
+Copy the `.env.example` file to `.env` and change the values as needed:
+
+```bash
+cp .env.example .env
+```
+
+### 3. Install dependencies
+
+```bash
+poetry install
+```
+
+Configure pre-commit hooks:
+
+```bash
+pre-commit install --config pre-commit.yaml
+```
+
+Activate the virtual shell
+
+```bash
+poetry shell
+```
+
+### 4. Database
+
+Create the database (adjust the name according to your DSN):
+
+```bash
+createdb db
+```
+
+Apply manual SQL migrations (e.g.: content in `src/db/migrations/`).
+
+### 5. Run the server
+
+Basic command:
+
+```bash
+litestar run
+```
+
+Examples with options:
+
+```bash
+litestar run -r -P -d -p 9000 -H 0.0.0.0
+litestar run --wc 4
+litestar run -h
+```
+
+### 6. OpenAPI / ReDoc
+
+Access at:
+
+```
+http://localhost:PORT/schema/redoc
+```
+
+Replace `PORT` with the port used (default 8000 if not specified).
+
+---
+
+**More features:** [litestar-asyncpg](https://github.com/YuriFontella/litestar-asyncpg)

app.py

@@ -0,0 +1,12 @@
+from litestar import Litestar
+from src.server.core import ApplicationCore
+import logging
+
+logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s %(name)s %(message)s')
+
+
+def create_app() -> Litestar:
+    return Litestar(plugins=[ApplicationCore()])
+
+
+app = create_app()

pre-commit.yaml

@@ -0,0 +1,14 @@
+repos:
+  # Black
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+
+  # Ruff
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "litestar-auth-api"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Yuri Fontella", email = "yurifc4@gmail.com"}
+]
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "litestar[standard] (>=2.17.0,<3.0.0)",
+    "litestar-asyncpg (>=0.5.0,<1.0.0)",
+    "pyjwt (>=2.10.1,<3.0.0)",
+    "bcrypt (>=4.3.0,<5.0.0)",
+    "python-dotenv (>=1.1.1,<2.0.0)",
+    "dnspython (>=2.8.0,<3.0.0)",
+    "email-validator (>=2.3.0,<3.0.0)",
+]
+
+[tool.poetry]
+packages = [{ include = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+black = "^25.1.0"
+ruff = "^0.12.12"
+pre-commit = "^4.3.0"
+
+[build-system]
+requires = ["poetry-core>=2.2.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

src/config/app.py

@@ -0,0 +1,51 @@
+from typing import Literal, Tuple
+
+from litestar.config.compression import CompressionConfig
+from litestar.config.cors import CORSConfig
+from litestar.config.csrf import CSRFConfig
+from litestar.middleware.rate_limit import RateLimitConfig
+from litestar_asyncpg import AsyncpgConfig, PoolConfig
+
+from src.config.base import get_settings
+
+settings = get_settings()
+
+csrf = CSRFConfig(
+    secret=settings.app.SECRET_KEY,
+    cookie_name=settings.app.CSRF_COOKIE_NAME,
+    cookie_secure=settings.app.CSRF_COOKIE_SECURE,
+    safe_methods={
+        "POST",
+        "GET",
+        "OPTIONS",
+    },
+)
+
+cors = CORSConfig(
+    allow_origins=settings.app.ALLOWED_CORS_ORIGINS,
+    allow_methods=[
+        "GET",
+        "POST",
+        "DELETE",
+        "PUT",
+        "PATCH",
+        "OPTIONS",
+    ],
+    allow_headers=["Origin", "Content-Type", "X-CSRFToken", "X-Access-Token"],
+    allow_credentials=True,
+)
+
+compression = CompressionConfig(backend="gzip", gzip_compress_level=9)
+
+rate_limit: Tuple[Literal["second"], int] = ("second", 10)
+rate_limit_config = RateLimitConfig(rate_limit=rate_limit, exclude=["/schema"])
+
+asyncpg = AsyncpgConfig(
+    pool_config=PoolConfig(
+        dsn=settings.db.DSN,
+        min_size=settings.db.MIN_SIZE,
+        max_size=settings.db.MAX_SIZE,
+        max_queries=settings.db.MAX_QUERIES,
+        max_inactive_connection_lifetime=settings.db.MAX_INACTIVE_CONNECTION_LIFETIME,
+    )
+)

src/config/base.py

@@ -0,0 +1,86 @@
+import os
+from typing import Optional, List
+
+from dataclasses import dataclass, field
+from functools import lru_cache
+
+
+@dataclass
+class DatabaseSettings:
+    DSN: Optional[str] = None
+    MIN_SIZE: int = 4
+    MAX_SIZE: int = 16
+    MAX_QUERIES: int = 50000
+    MAX_INACTIVE_CONNECTION_LIFETIME: float = 300.0
+
+    def __post_init__(self):
+        self.DSN = self.DSN or os.getenv("DATABASE_DSN")
+        self.MIN_SIZE = int(os.getenv("DATABASE_MIN_SIZE", self.MIN_SIZE))
+        self.MAX_SIZE = int(os.getenv("DATABASE_MAX_SIZE", self.MAX_SIZE))
+        self.MAX_QUERIES = int(os.getenv("DATABASE_MAX_QUERIES", self.MAX_QUERIES))
+        self.MAX_INACTIVE_CONNECTION_LIFETIME = float(
+            os.getenv(
+                "DATABASE_MAX_INACTIVE_CONNECTION_LIFETIME",
+                self.MAX_INACTIVE_CONNECTION_LIFETIME,
+            )
+        )
+
+
+@dataclass
+class AppSettings:
+    SECRET_KEY: Optional[str] = None
+    ALLOWED_CORS_ORIGINS: List[str] = field(default_factory=list)
+    CSRF_COOKIE_NAME: str = "XSRF-TOKEN"
+    CSRF_COOKIE_SECURE: bool = False
+    JWT_ALGORITHM: str = "HS256"
+    SESSION_SALT: Optional[str] = None
+    PBKDF2_ITERATIONS: int = 600_000
+    PBKDF2_ALGORITHM: str = "sha256"
+    MAX_FINGERPRINT_VALUE: int = 100_000_000
+    BCRYPT_GENSALT: int = 12
+
+    def __post_init__(self):
+        self.SECRET_KEY = self.SECRET_KEY or os.getenv("SECRET_KEY")
+        self.SESSION_SALT = self.SESSION_SALT or os.getenv("SESSION_SALT")
+        self.PBKDF2_ITERATIONS = int(os.getenv("PBKDF2_ITERATIONS", self.PBKDF2_ITERATIONS))
+        self.PBKDF2_ALGORITHM = os.getenv("PBKDF2_ALGORITHM", self.PBKDF2_ALGORITHM)
+        self.MAX_FINGERPRINT_VALUE = int(os.getenv("MAX_FINGERPRINT_VALUE", self.MAX_FINGERPRINT_VALUE))
+        self.BCRYPT_GENSALT = int(os.getenv("BCRYPT_GENSALT", self.BCRYPT_GENSALT))
+
+        if not self.ALLOWED_CORS_ORIGINS:
+            cors_origins = os.getenv("ALLOWED_CORS_ORIGINS")
+            if cors_origins:
+                self.ALLOWED_CORS_ORIGINS = [
+                    origin.strip() for origin in cors_origins.split(",")
+                ]
+            else:
+                self.ALLOWED_CORS_ORIGINS = ["*"]
+
+        self.CSRF_COOKIE_NAME = os.getenv("CSRF_COOKIE_NAME", self.CSRF_COOKIE_NAME)
+        self.CSRF_COOKIE_SECURE = os.getenv("CSRF_COOKIE_SECURE", "").lower() in (
+            "true",
+            "1",
+            "yes",
+        )
+        self.JWT_ALGORITHM = os.getenv("JWT_ALGORITHM", self.JWT_ALGORITHM)
+
+
+@dataclass
+class Settings:
+    app: AppSettings = field(default_factory=AppSettings)
+    db: DatabaseSettings = field(default_factory=DatabaseSettings)
+
+    @classmethod
+    def from_env(cls, dotenv_filename: str = ".env") -> "Settings":
+        from pathlib import Path
+        from dotenv import load_dotenv
+
+        env_file = Path(f"{os.curdir}/{dotenv_filename}")
+        if env_file.is_file():
+            load_dotenv(env_file, override=True)
+        return Settings()
+
+
+@lru_cache(maxsize=1, typed=True)
+def get_settings() -> Settings:
+    return Settings.from_env()

src/config/constants.py

@@ -0,0 +1,4 @@
+from pathlib import Path
+
+
+MIGRATIONS_DIR = Path(__file__).resolve().parent.parent / "db" / "migrations"

src/db/migrations/001_create_extension.sql

@@ -0,0 +1,2 @@
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+