hinbert-fastapi 0.1.0__py3-none-any.whl

app/core/exceptions/base_exception.py

@@ -0,0 +1,9 @@
+"""Base exception carrying safe, client-facing error metadata."""
+
+
+class AppException(Exception):
+    """Domain error with HTTP status and serializable validation details."""
+
+    def __init__(self, message: str, status_code: int = 400, errors: list[str] | None = None):
+        super().__init__(message)
+        self.message, self.status_code, self.errors = message, status_code, errors or []

app/core/exceptions/custom_exceptions.py

@@ -0,0 +1,17 @@
+"""Frequently used domain exceptions with stable status codes."""
+
+from app.core.exceptions.base_exception import AppException
+
+
+class NotFoundError(AppException):
+    """Represent a requested resource that is absent."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, 404)
+
+
+class UnauthorizedError(AppException):
+    """Represent missing or invalid authentication."""
+
+    def __init__(self, message: str = "Authentication required"):
+        super().__init__(message, 401)

app/core/middleware/__init__.py

@@ -0,0 +1 @@
+"""HTTP middleware and exception handling components."""

app/core/middleware/cors.py

@@ -0,0 +1,5 @@
+"""CORS policy documentation and extension point.
+
+The actual middleware is installed in ``app.main`` from validated settings.
+Keeping policy data in settings makes allowed origins auditable per deployment.
+"""

app/core/middleware/error_handler.py

@@ -0,0 +1,23 @@
+"""Consistent JSON handling for domain exceptions and unexpected failures."""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from app.core.exceptions.base_exception import AppException
+
+
+def register_exception_handlers(application: FastAPI) -> None:
+    """Register handlers that preserve the public response contract."""
+
+    @application.exception_handler(AppException)
+    async def handle_app_exception(_: Request, exc: AppException) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "success": False,
+                "message": exc.message,
+                "data": None,
+                "errors": exc.errors,
+                "status_code": exc.status_code,
+            },
+        )

app/core/middleware/logging.py

@@ -0,0 +1,29 @@
+"""Request timing middleware with correlation-friendly structured logging."""
+
+import time
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+
+from app.utils.logger import logger
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """Log method, path, status, and duration without logging request bodies."""
+
+    async def dispatch(self, request: Request, call_next):
+        """Process one request and record an operational timing event."""
+        started = time.perf_counter()
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+        logger.info(
+            "{method} {path} {status} {duration:.3f}s",
+            method=request.method,
+            path=request.url.path,
+            status=response.status_code,
+            duration=time.perf_counter() - started,
+        )
+        return response

app/core/middleware/rate_limit.py

@@ -0,0 +1,27 @@
+"""SlowAPI limiter configuration and exception registration."""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from slowapi import Limiter
+from slowapi.errors import RateLimitExceeded
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+DEFAULT_LIMIT = "100/minute"
+
+
+def register_rate_limit(application: FastAPI) -> None:
+    """Register a uniform response for requests exceeding configured limits."""
+
+    @application.exception_handler(RateLimitExceeded)
+    async def handle_rate_limit(_: Request, __: RateLimitExceeded) -> JSONResponse:
+        return JSONResponse(
+            status_code=429,
+            content={
+                "success": False,
+                "message": "Rate limit exceeded",
+                "data": None,
+                "errors": [],
+                "status_code": 429,
+            },
+        )

app/core/security/__init__.py

@@ -0,0 +1 @@
+"""Authentication, authorization, and cryptographic helpers."""

app/core/security/auth.py

@@ -0,0 +1,8 @@
+"""Small authentication primitives shared by services and dependencies."""
+
+from app.core.security.password import verify_password
+
+
+def authenticate_password(password: str, password_hash: str) -> bool:
+    """Return whether credentials match without exposing password details."""
+    return verify_password(password, password_hash)

app/core/security/jwt.py

@@ -0,0 +1,33 @@
+"""JWT access-token creation and validation.
+
+Access tokens are short-lived and carry only a subject and token type. Refresh
+tokens are generated separately and must be hashed before database persistence.
+"""
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import UUID
+
+from jose import JWTError, jwt
+
+from app.core.config.settings import get_settings
+
+
+def create_token(subject: UUID | str, token_type: str, expires_delta: timedelta) -> str:
+    """Create a signed JWT for a subject and explicit token type."""
+    now = datetime.now(UTC)
+    payload: dict[str, Any] = {"sub": str(subject), "type": token_type, "iat": now, "exp": now + expires_delta}
+    settings = get_settings()
+    return jwt.encode(payload, settings.jwt_secret_key.get_secret_value(), algorithm=settings.jwt_algorithm)
+
+
+def decode_token(token: str, expected_type: str = "access") -> dict[str, Any]:
+    """Decode and validate a JWT, raising ``ValueError`` for invalid tokens."""
+    settings = get_settings()
+    try:
+        payload = jwt.decode(token, settings.jwt_secret_key.get_secret_value(), algorithms=[settings.jwt_algorithm])
+    except JWTError as exc:
+        raise ValueError("Invalid or expired token") from exc
+    if payload.get("type") != expected_type or not payload.get("sub"):
+        raise ValueError("Invalid token type")
+    return payload

app/core/security/oauth.py

@@ -0,0 +1,8 @@
+"""OAuth provider configuration boundary.
+
+Provider exchange logic belongs in ``social_auth_service`` so credentials and
+HTTP clients can be mocked in tests. Add provider-specific scopes and callback
+URLs there without coupling the rest of the application to an SDK.
+"""
+
+SUPPORTED_PROVIDERS = ("google", "facebook")

app/core/security/password.py

@@ -0,0 +1,18 @@
+"""Password hashing using bcrypt through Passlib.
+
+Only password hashes are persisted; plaintext passwords are never logged or
+returned. Replace the scheme configuration here if an enterprise KMS policy
+requires a different approved password verifier.
+"""
+
+import bcrypt
+
+
+def hash_password(password: str) -> str:
+    """Hash a password with bcrypt and return the encoded hash."""
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    """Constant-time verify a candidate password against its stored hash."""
+    return bcrypt.checkpw(password.encode("utf-8"), password_hash.encode("utf-8"))

app/core/security/totp.py

@@ -0,0 +1,13 @@
+"""TOTP primitives for optional multi-factor authentication."""
+
+import pyotp
+
+
+def new_secret() -> str:
+    """Generate a cryptographically random Base32 TOTP secret."""
+    return pyotp.random_base32()
+
+
+def verify_code(secret: str, code: str) -> bool:
+    """Verify a current TOTP code with a small clock-skew window."""
+    return bool(pyotp.TOTP(secret).verify(code, valid_window=1))

app/db/__init__.py

@@ -0,0 +1 @@
+"""Database session and migration support."""

app/db/base.py

@@ -0,0 +1,7 @@
+"""Declarative SQLAlchemy base imported by Alembic and model modules."""
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """Common parent for all database tables."""

app/db/migrations/env.py

@@ -0,0 +1,39 @@
+"""Alembic environment configured for async SQLAlchemy metadata discovery."""
+
+import asyncio
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+import app.models  # noqa: F401
+from app.core.config.settings import get_settings
+from app.db.base import Base
+
+config = context.config
+config.set_main_option("sqlalchemy.url", get_settings().database_url.replace("%", "%%"))
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Generate SQL without opening a database connection."""
+    context.configure(url=get_settings().database_url, target_metadata=target_metadata, literal_binds=True)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    """Run migrations through the async database driver."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}), prefix="sqlalchemy.", poolclass=pool.NullPool
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(lambda sync: context.configure(connection=sync, target_metadata=target_metadata))
+        await connection.run_sync(lambda _: context.run_migrations())
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())

app/db/migrations/versions/97ed1bc05f4a_complete_product_and_totp_fields.py

@@ -0,0 +1,49 @@
+"""complete_product_and_totp_fields
+
+Revision ID: 97ed1bc05f4a
+Revises: f8b632aa11da
+Create Date: 2026-09-04 03:49:08.642114
+
+This generated migration is reviewed source code. Keep schema changes small,
+reversible, and paired with application compatibility during rollout.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "97ed1bc05f4a"
+down_revision: str | Sequence[str] | None = "f8b632aa11da"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Apply the generated schema change."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column("products", sa.Column("category", sa.String(length=100), nullable=False, server_default="general"))
+    op.add_column("products", sa.Column("owner_id", sa.Uuid(), nullable=True))
+    op.create_index(op.f("ix_products_category"), "products", ["category"], unique=False)
+    op.create_index(op.f("ix_products_owner_id"), "products", ["owner_id"], unique=False)
+    with op.batch_alter_table("products", recreate="always") as batch_op:
+        batch_op.create_foreign_key("fk_products_owner_id_users", "users", ["owner_id"], ["id"], ondelete="SET NULL")
+    with op.batch_alter_table("totp_secrets") as batch_op:
+        batch_op.add_column(sa.Column("encrypted_secret", sa.String(length=512), nullable=True))
+        batch_op.drop_column("secret")
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Reverse the generated schema change."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("totp_secrets") as batch_op:
+        batch_op.add_column(sa.Column("secret", sa.VARCHAR(length=128), nullable=True))
+        batch_op.drop_column("encrypted_secret")
+    with op.batch_alter_table("products") as batch_op:
+        batch_op.drop_constraint("fk_products_owner_id_users", type_="foreignkey")
+        batch_op.drop_index(op.f("ix_products_owner_id"))
+        batch_op.drop_index(op.f("ix_products_category"))
+        batch_op.drop_column("owner_id")
+        batch_op.drop_column("category")
+    # ### end Alembic commands ###

app/db/migrations/versions/f8b632aa11da_initial_migration.py

@@ -0,0 +1,113 @@
+"""initial_migration
+
+Revision ID: f8b632aa11da
+Revises:
+Create Date: 2026-09-04 03:32:35.906981
+
+This generated migration is reviewed source code. Keep schema changes small,
+reversible, and paired with application compatibility during rollout.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "f8b632aa11da"
+down_revision: str | Sequence[str] | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Apply the generated schema change."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "products",
+        sa.Column("name", sa.String(length=200), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("price", sa.Numeric(precision=12, scale=2), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_products_name"), "products", ["name"], unique=False)
+    op.create_table(
+        "users",
+        sa.Column("email", sa.String(length=320), nullable=False),
+        sa.Column("full_name", sa.String(length=200), nullable=False),
+        sa.Column("password_hash", sa.String(length=255), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_admin", sa.Boolean(), nullable=False),
+        sa.Column("is_verified", sa.Boolean(), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
+    op.create_table(
+        "email_verifications",
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("token_hash"),
+    )
+    op.create_table(
+        "password_resets",
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("token_hash"),
+    )
+    op.create_table(
+        "refresh_tokens",
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_refresh_tokens_token_hash"), "refresh_tokens", ["token_hash"], unique=True)
+    op.create_index(op.f("ix_refresh_tokens_user_id"), "refresh_tokens", ["user_id"], unique=False)
+    op.create_table(
+        "totp_secrets",
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("secret", sa.String(length=128), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("user_id"),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Reverse the generated schema change."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("totp_secrets")
+    op.drop_index(op.f("ix_refresh_tokens_user_id"), table_name="refresh_tokens")
+    op.drop_index(op.f("ix_refresh_tokens_token_hash"), table_name="refresh_tokens")
+    op.drop_table("refresh_tokens")
+    op.drop_table("password_resets")
+    op.drop_table("email_verifications")
+    op.drop_index(op.f("ix_users_email"), table_name="users")
+    op.drop_table("users")
+    op.drop_index(op.f("ix_products_name"), table_name="products")
+    op.drop_table("products")
+    # ### end Alembic commands ###

app/db/session.py

@@ -0,0 +1,11 @@
+"""FastAPI dependency that yields and closes one async DB session."""
+
+from collections.abc import AsyncGenerator
+
+from app.core.config.database import SessionLocal
+
+
+async def get_db() -> AsyncGenerator:
+    """Yield a request-scoped SQLAlchemy session and always close it."""
+    async with SessionLocal() as session:
+        yield session

app/main.py

@@ -0,0 +1,50 @@
+"""Create the FastAPI application and assemble cross-cutting concerns.
+
+The factory pattern keeps imports side-effect-light for tests, workers, and CLI
+scripts. Customize middleware and router registration here; business logic
+belongs in services rather than in this composition module.
+"""
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from slowapi.middleware import SlowAPIMiddleware
+
+from app.api.v1.routers.api_router import api_router
+from app.core.config.settings import get_settings
+from app.core.middleware.error_handler import register_exception_handlers
+from app.core.middleware.logging import RequestLoggingMiddleware
+from app.core.middleware.rate_limit import limiter, register_rate_limit
+
+
+def create_app() -> FastAPI:
+    """Build and configure the application.
+
+    Returns:
+        A configured FastAPI instance with OpenAPI documentation enabled.
+    """
+    settings = get_settings()
+    application = FastAPI(title=settings.app_name, version="0.1.0")
+    application.state.limiter = limiter
+    application.add_middleware(SlowAPIMiddleware)
+    application.add_middleware(RequestLoggingMiddleware)
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+        allow_headers=["Authorization", "Content-Type"],
+    )
+    application.include_router(api_router, prefix=settings.api_prefix)
+    register_exception_handlers(application)
+    register_rate_limit(application)
+
+    @application.get("/health", tags=["health"])
+    @limiter.limit("120/minute")
+    async def health(request: Request) -> dict[str, str]:
+        """Return a lightweight liveness response for load balancers and probes."""
+        return {"status": "ok"}
+
+    return application
+
+
+app = create_app()

app/models/__init__.py

@@ -0,0 +1,10 @@
+"""Public data-model namespace; import concrete models here for Alembic discovery."""
+
+from app.models.domain.email_verification import EmailVerification
+from app.models.domain.password_reset import PasswordReset
+from app.models.domain.product import Product
+from app.models.domain.refresh_token import RefreshToken
+from app.models.domain.totp_secret import TotpSecret
+from app.models.domain.user import User
+
+__all__ = ["EmailVerification", "PasswordReset", "Product", "RefreshToken", "TotpSecret", "User"]

app/models/domain/__init__.py

@@ -0,0 +1 @@
+"""SQLAlchemy domain model namespace."""

app/models/domain/base.py

@@ -0,0 +1,20 @@
+"""Reusable UUID primary key and UTC audit timestamps."""
+
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import DateTime
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class TimestampedModel(Base):
+    """Abstract table mixin providing stable IDs and audit timestamps."""
+
+    __abstract__ = True
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+    )

app/models/domain/email_verification.py

@@ -0,0 +1,24 @@
+"""Hashed, expiring email verification tokens."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.domain.base import TimestampedModel
+
+if TYPE_CHECKING:
+    from app.models.domain.user import User
+
+
+class EmailVerification(TimestampedModel):
+    """Single-use verification token linked to a user."""
+
+    __tablename__ = "email_verifications"
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    user: Mapped["User"] = relationship(back_populates="email_verifications")

app/models/domain/password_reset.py

@@ -0,0 +1,24 @@
+"""Password reset token persistence boundary."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.domain.base import TimestampedModel
+
+if TYPE_CHECKING:
+    from app.models.domain.user import User
+
+
+class PasswordReset(TimestampedModel):
+    """Document the reset-token contract; use a dedicated table in migrations."""
+
+    __tablename__ = "password_resets"
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    user: Mapped["User"] = relationship(back_populates="password_resets")

app/models/domain/product.py

@@ -0,0 +1,22 @@
+"""Product table used by the example CRUD surface."""
+
+from decimal import Decimal
+from uuid import UUID
+
+from sqlalchemy import ForeignKey, Numeric, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.domain.base import TimestampedModel
+
+
+class Product(TimestampedModel):
+    """Sellable product with indexed name and exact numeric price."""
+
+    __tablename__ = "products"
+    name: Mapped[str] = mapped_column(String(200), index=True)
+    description: Mapped[str] = mapped_column(Text, default="")
+    price: Mapped[Decimal] = mapped_column(Numeric(12, 2))
+    category: Mapped[str] = mapped_column(String(100), default="general", index=True)
+    owner_id: Mapped[UUID | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )

app/models/domain/refresh_token.py

@@ -0,0 +1,24 @@
+"""Refresh-token allowlist storing only SHA-256 digests."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.domain.base import TimestampedModel
+
+if TYPE_CHECKING:
+    from app.models.domain.user import User
+
+
+class RefreshToken(TimestampedModel):
+    """Revocable refresh session; raw bearer tokens never enter the database."""
+
+    __tablename__ = "refresh_tokens"
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    user: Mapped["User"] = relationship(back_populates="refresh_tokens")