hinbert-fastapi 0.1.0__py3-none-any.whl

app/models/domain/totp_secret.py

@@ -0,0 +1,44 @@
+"""Encrypted-at-rest TOTP secret ownership boundary."""
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from cryptography.fernet import Fernet, InvalidToken
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.config.settings import get_settings
+from app.db.base import Base
+
+if TYPE_CHECKING:
+    from app.models.domain.user import User
+
+
+class TotpSecret(Base):
+    """One TOTP secret per user; production deployments should encrypt its value."""
+
+    __tablename__ = "totp_secrets"
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), primary_key=True)
+    encrypted_secret: Mapped[str] = mapped_column(String(512))
+    user: Mapped["User"] = relationship(back_populates="totp_secret")
+
+    @property
+    def secret(self) -> str:
+        """Decrypt the secret only at the point where TOTP verification needs it."""
+        try:
+            return Fernet(_fernet_key()).decrypt(self.encrypted_secret.encode()).decode()
+        except InvalidToken as exc:
+            raise ValueError("Stored TOTP secret cannot be decrypted") from exc
+
+    @secret.setter
+    def secret(self, value: str) -> None:
+        """Encrypt a plaintext secret before SQLAlchemy persists it."""
+        self.encrypted_secret = Fernet(_fernet_key()).encrypt(value.encode()).decode()
+
+
+def _fernet_key() -> bytes:
+    """Return a Fernet key derived from the configured secret key."""
+    import base64
+    import hashlib
+
+    return base64.urlsafe_b64encode(hashlib.sha256(get_settings().jwt_secret_key.get_secret_value().encode()).digest())

app/models/domain/user.py

@@ -0,0 +1,34 @@
+"""User table storing identity, authorization, and password state."""
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Boolean, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.domain.base import TimestampedModel
+
+if TYPE_CHECKING:
+    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
+
+
+class User(TimestampedModel):
+    """Application user; email is unique and password hashes are never exposed."""
+
+    __tablename__ = "users"
+    email: Mapped[str] = mapped_column(String(320), unique=True, index=True)
+    full_name: Mapped[str] = mapped_column(String(200))
+    password_hash: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    is_admin: Mapped[bool] = mapped_column(Boolean, default=False)
+    is_verified: Mapped[bool] = mapped_column(Boolean, default=False)
+    refresh_tokens: Mapped[list["RefreshToken"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    email_verifications: Mapped[list["EmailVerification"]] = relationship(
+        back_populates="user", cascade="all, delete-orphan"
+    )
+    password_resets: Mapped[list["PasswordReset"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    totp_secret: Mapped["TotpSecret | None"] = relationship(
+        back_populates="user", uselist=False, cascade="all, delete-orphan"
+    )

app/models/schemas/__init__.py

@@ -0,0 +1 @@
+"""Pydantic request and response schemas."""

app/models/schemas/auth.py

@@ -0,0 +1,30 @@
+"""Authentication request schemas."""
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class SignupRequest(BaseModel):
+    """Signup data with a deliberately strong minimum password length."""
+
+    email: EmailStr
+    full_name: str = Field(min_length=1, max_length=200)
+    password: str = Field(min_length=12, max_length=72)
+
+
+class LoginRequest(BaseModel):
+    """Credential login payload."""
+
+    email: EmailStr
+    password: str
+
+
+class EmailTokenRequest(BaseModel):
+    """Single-use email verification token payload."""
+
+    token: str = Field(min_length=20)
+
+
+class SocialAuthRequest(BaseModel):
+    """OAuth callback data returned by a supported provider."""
+
+    code: str = Field(min_length=1)

app/models/schemas/password.py

@@ -0,0 +1,16 @@
+"""Password recovery payloads."""
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class ForgotPassword(BaseModel):
+    """Email address used to request a reset link."""
+
+    email: EmailStr
+
+
+class ResetPassword(BaseModel):
+    """Single-use reset token and replacement password."""
+
+    token: str
+    password: str = Field(min_length=12, max_length=72)

app/models/schemas/product.py

@@ -0,0 +1,31 @@
+"""Product CRUD schemas."""
+
+from decimal import Decimal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProductCreate(BaseModel):
+    """Validated product creation payload."""
+
+    name: str = Field(min_length=1, max_length=200)
+    description: str = ""
+    price: Decimal = Field(ge=0, decimal_places=2)
+    category: str = Field(default="general", max_length=100)
+
+
+class ProductOut(ProductCreate):
+    """Product response including database identity."""
+
+    model_config = ConfigDict(from_attributes=True)
+    id: UUID
+
+
+class ProductPage(BaseModel):
+    """Paginated product collection with stable client-facing metadata."""
+
+    items: list[ProductOut]
+    total_count: int
+    page: int
+    limit: int

app/models/schemas/response.py

@@ -0,0 +1,17 @@
+"""Standard API envelope for predictable clients and observability."""
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+DataT = TypeVar("DataT")
+
+
+class APIResponse(BaseModel, Generic[DataT]):
+    """Envelope containing success state, data, errors, and HTTP status."""
+
+    success: bool = True
+    message: str = "OK"
+    data: DataT | None = None
+    errors: list[str] = Field(default_factory=list)
+    status_code: int = 200

app/models/schemas/token.py

@@ -0,0 +1,17 @@
+"""Token exchange schemas."""
+
+from pydantic import BaseModel
+
+
+class TokenResponse(BaseModel):
+    """Bearer access token plus opaque refresh token."""
+
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+
+
+class RefreshRequest(BaseModel):
+    """Raw refresh token accepted only over TLS."""
+
+    refresh_token: str

app/models/schemas/totp.py

@@ -0,0 +1,16 @@
+"""Two-factor setup and verification payloads."""
+
+from pydantic import BaseModel, Field
+
+
+class TotpVerify(BaseModel):
+    """Six-digit current TOTP code."""
+
+    code: str = Field(pattern=r"^\d{6}$")
+
+
+class TotpSetupResponse(BaseModel):
+    """TOTP secret and provisioning URI for authenticator applications."""
+
+    secret: str
+    provisioning_uri: str

app/models/schemas/user.py

@@ -0,0 +1,37 @@
+"""User input/output schemas that exclude password hashes."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+
+class UserCreate(BaseModel):
+    """Validated signup payload."""
+
+    email: EmailStr
+    full_name: str = Field(min_length=1, max_length=200)
+    password: str = Field(min_length=12, max_length=128)
+
+
+class UserUpdate(BaseModel):
+    """Partial profile update payload."""
+
+    full_name: str | None = Field(default=None, min_length=1, max_length=200)
+
+
+class AdminUserUpdate(UserUpdate):
+    """Administrator-only profile and role update payload."""
+
+    is_active: bool | None = None
+    is_admin: bool | None = None
+
+
+class UserOut(BaseModel):
+    """Safe public user representation."""
+
+    model_config = ConfigDict(from_attributes=True)
+    id: UUID
+    email: EmailStr
+    full_name: str
+    is_active: bool
+    is_verified: bool

app/repositories/__init__.py

@@ -0,0 +1 @@
+"""Repository layer encapsulates all database queries."""

app/repositories/base/__init__.py

@@ -0,0 +1 @@
+"""Generic data-access abstractions."""

app/repositories/base/base_repository.py

@@ -0,0 +1,51 @@
+"""Generic async CRUD repository using SQLAlchemy expressions."""
+
+from typing import Generic, TypeVar
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.base import Base
+
+ModelT = TypeVar("ModelT", bound=Base)
+
+
+class BaseRepository(Generic[ModelT]):
+    """Provide safe parameterized lookup and paginated listing primitives."""
+
+    def __init__(self, session: AsyncSession, model: type[ModelT]):
+        self.session, self.model = session, model
+
+    async def get(self, item_id: UUID) -> ModelT | None:
+        """Fetch by primary key using SQLAlchemy's bound parameters."""
+        return await self.session.get(self.model, item_id)
+
+    async def get_by_id(self, item_id: UUID) -> ModelT | None:
+        """Alias with an explicit name for service and endpoint callers."""
+        return await self.get(item_id)
+
+    async def create(self, instance: ModelT) -> ModelT:
+        """Persist, commit, and refresh a new model instance."""
+        self.session.add(instance)
+        await self.session.commit()
+        await self.session.refresh(instance)
+        return instance
+
+    async def update(self, instance: ModelT, values: dict[str, object]) -> ModelT:
+        """Apply a whitelist prepared by the caller and persist the model."""
+        for field, value in values.items():
+            setattr(instance, field, value)
+        await self.session.commit()
+        await self.session.refresh(instance)
+        return instance
+
+    async def delete(self, instance: ModelT) -> None:
+        """Delete an instance and commit the transaction."""
+        await self.session.delete(instance)
+        await self.session.commit()
+
+    async def list(self, offset: int = 0, limit: int = 50) -> list[ModelT]:
+        """Return a bounded page, preventing unbounded database reads."""
+        result = await self.session.scalars(select(self.model).offset(offset).limit(min(limit, 100)))
+        return list(result)

app/repositories/email_verification_repository.py

@@ -0,0 +1,37 @@
+"""Email verification token query boundary."""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.domain.email_verification import EmailVerification
+
+
+async def save(session: AsyncSession, token: EmailVerification) -> EmailVerification:
+    """Persist a pre-hashed verification token."""
+    session.add(token)
+    await session.commit()
+    return token
+
+
+async def create(session: AsyncSession, token: EmailVerification) -> EmailVerification:
+    """Persist a verification token using the repository naming convention."""
+    return await save(session, token)
+
+
+async def get_by_token(session: AsyncSession, token_hash: str) -> EmailVerification | None:
+    """Find an unused and unexpired verification token by digest."""
+    return await session.scalar(
+        select(EmailVerification).where(
+            EmailVerification.token_hash == token_hash,
+            EmailVerification.used_at.is_(None),
+            EmailVerification.expires_at > datetime.now(UTC),
+        )
+    )
+
+
+async def mark_used(session: AsyncSession, token: EmailVerification) -> None:
+    """Mark a verification token as consumed."""
+    token.used_at = datetime.now(UTC)
+    await session.commit()

app/repositories/password_reset_repository.py

@@ -0,0 +1,33 @@
+"""Password-reset token persistence and single-use lookup operations."""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.domain.password_reset import PasswordReset
+
+
+async def create(session: AsyncSession, token: PasswordReset) -> PasswordReset:
+    """Persist a hashed, expiring reset token."""
+    session.add(token)
+    await session.commit()
+    await session.refresh(token)
+    return token
+
+
+async def get_by_token(session: AsyncSession, token_hash: str) -> PasswordReset | None:
+    """Find an unused and unexpired reset token by digest."""
+    return await session.scalar(
+        select(PasswordReset).where(
+            PasswordReset.token_hash == token_hash,
+            PasswordReset.used_at.is_(None),
+            PasswordReset.expires_at > datetime.now(UTC),
+        )
+    )
+
+
+async def mark_used(session: AsyncSession, token: PasswordReset) -> None:
+    """Mark a reset token unusable after a successful password change."""
+    token.used_at = datetime.now(UTC)
+    await session.commit()

app/repositories/product_repository.py

@@ -0,0 +1,40 @@
+"""Product-specific query repository."""
+
+from decimal import Decimal
+
+from sqlalchemy import select
+
+from app.models.domain.product import Product
+from app.repositories.base.base_repository import BaseRepository
+
+
+class ProductRepository(BaseRepository[Product]):
+    """Repository configured for product queries."""
+
+    def __init__(self, session):
+        super().__init__(session, Product)
+
+    async def get_all(
+        self,
+        offset: int = 0,
+        limit: int = 50,
+        category: str | None = None,
+        min_price: Decimal | None = None,
+        max_price: Decimal | None = None,
+        sort_by: str = "created_at",
+    ) -> list[Product]:
+        """Return a bounded, filtered, allowlisted-sorted product page."""
+        columns = {"name": Product.name, "price": Product.price, "created_at": Product.created_at}
+        query = select(Product)
+        if category:
+            query = query.where(Product.category == category)
+        if min_price is not None:
+            query = query.where(Product.price >= min_price)
+        if max_price is not None:
+            query = query.where(Product.price <= max_price)
+        query = query.order_by(columns.get(sort_by, Product.created_at)).offset(offset).limit(min(limit, 100))
+        return list(await self.session.scalars(query))
+
+    async def get_by_id(self, product_id):
+        """Return a product by UUID."""
+        return await self.get(product_id)

app/repositories/refresh_token_repository.py

@@ -0,0 +1,40 @@
+"""Refresh-token persistence and revocation queries."""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.domain.refresh_token import RefreshToken
+
+
+async def find_active(session: AsyncSession, token_hash: str) -> RefreshToken | None:
+    """Find a non-revoked, non-expired hashed token."""
+    return await session.scalar(
+        select(RefreshToken).where(
+            RefreshToken.token_hash == token_hash,
+            RefreshToken.revoked_at.is_(None),
+            RefreshToken.expires_at > datetime.now(UTC),
+        )
+    )
+
+
+async def create(session: AsyncSession, token: RefreshToken) -> RefreshToken:
+    """Persist a hashed refresh token and its expiry."""
+    session.add(token)
+    await session.commit()
+    await session.refresh(token)
+    return token
+
+
+async def revoke(session: AsyncSession, token: RefreshToken) -> None:
+    """Revoke a refresh token without deleting its audit record."""
+    token.revoked_at = datetime.now(UTC)
+    await session.commit()
+
+
+async def delete_expired(session: AsyncSession) -> int:
+    """Delete expired refresh tokens and return the affected row count."""
+    result = await session.execute(delete(RefreshToken).where(RefreshToken.expires_at <= datetime.now(UTC)))
+    await session.commit()
+    return result.rowcount or 0

app/repositories/totp_secret_repository.py

@@ -0,0 +1,23 @@
+"""Encrypted TOTP-secret persistence operations."""
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.domain.totp_secret import TotpSecret
+
+
+async def get(session: AsyncSession, user_id) -> TotpSecret | None:
+    """Load the encrypted secret belonging to a user."""
+    return await session.get(TotpSecret, user_id)
+
+
+async def create_or_replace(session: AsyncSession, secret: TotpSecret) -> TotpSecret:
+    """Insert or replace a user's encrypted TOTP secret."""
+    existing = await session.get(TotpSecret, secret.user_id)
+    if existing is not None:
+        existing.secret = secret.secret
+        secret = existing
+    else:
+        session.add(secret)
+    await session.commit()
+    await session.refresh(secret)
+    return secret

app/repositories/user_repository.py

@@ -0,0 +1,44 @@
+"""User-specific query repository."""
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.domain.user import User
+
+
+async def get_by_email(session: AsyncSession, email: str) -> User | None:
+    """Find a user by normalized email using a bound SQL expression."""
+    return await session.scalar(select(User).where(User.email == email.lower()))
+
+
+async def get_by_id(session: AsyncSession, user_id) -> User | None:
+    """Return a user by UUID."""
+    return await session.get(User, user_id)
+
+
+async def get_all(session: AsyncSession, offset: int = 0, limit: int = 50) -> list[User]:
+    """Return a bounded user page."""
+    return list(await session.scalars(select(User).offset(offset).limit(min(limit, 100))))
+
+
+async def create(session: AsyncSession, user: User) -> User:
+    """Persist a user and refresh generated fields."""
+    session.add(user)
+    await session.commit()
+    await session.refresh(user)
+    return user
+
+
+async def update(session: AsyncSession, user: User, values: dict[str, object]) -> User:
+    """Update approved user fields and commit."""
+    for field, value in values.items():
+        setattr(user, field, value)
+    await session.commit()
+    await session.refresh(user)
+    return user
+
+
+async def delete(session: AsyncSession, user: User) -> None:
+    """Delete a user and dependent owned records."""
+    await session.delete(user)
+    await session.commit()

app/services/__init__.py

@@ -0,0 +1 @@
+"""Business services coordinate repositories and enforce domain rules."""

app/services/auth_service.py

@@ -0,0 +1,32 @@
+"""Authentication orchestration and secure refresh-token rotation."""
+
+import hashlib
+import secrets
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from app.core.config.settings import get_settings
+from app.core.security.jwt import create_token
+from app.core.security.password import hash_password
+
+
+def hash_refresh_token(token: str) -> str:
+    """Return the SHA-256 digest persisted for a raw refresh bearer token."""
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def issue_tokens(user_id: UUID) -> tuple[str, str, str, datetime]:
+    """Issue short-lived access and opaque refresh credentials.
+
+    The returned digest is the only refresh value suitable for persistence.
+    """
+    settings = get_settings()
+    raw_refresh = secrets.token_urlsafe(48)
+    expiry = datetime.now(UTC) + timedelta(days=settings.refresh_token_days)
+    access = create_token(user_id, "access", timedelta(minutes=settings.access_token_minutes))
+    return access, raw_refresh, hash_refresh_token(raw_refresh), expiry
+
+
+def issue_password_hash(password: str) -> str:
+    """Hash a password for reset and social-account provisioning workflows."""
+    return hash_password(password)

app/services/base/__init__.py

@@ -0,0 +1 @@
+"""Reusable service abstractions."""

app/services/base/base_service.py

@@ -0,0 +1,21 @@
+"""Generic service helpers that keep endpoint code thin."""
+
+from typing import Generic, TypeVar
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.base import Base
+
+ModelT = TypeVar("ModelT", bound=Base)
+
+
+class BaseService(Generic[ModelT]):
+    """Provide common async lookup behavior for a model service."""
+
+    def __init__(self, model: type[ModelT], session: AsyncSession):
+        self.model, self.session = model, session
+
+    async def get(self, item_id: UUID) -> ModelT | None:
+        """Fetch one row by primary key, returning None when absent."""
+        return await self.session.get(self.model, item_id)

app/services/email_service.py

@@ -0,0 +1,32 @@
+"""SMTP email boundary with no credential or token logging."""
+
+import smtplib
+from email.message import EmailMessage
+
+from app.core.config.settings import get_settings
+from app.models.domain.user import User
+
+
+def send_email(recipient: str, subject: str, body: str) -> None:
+    """Send a plain-text email through configured SMTP; replace with a provider SDK as needed."""
+    settings = get_settings()
+    if settings.environment == "development" and not settings.smtp_username:
+        return
+    message = EmailMessage()
+    message["From"], message["To"], message["Subject"] = settings.smtp_from, recipient, subject
+    message.set_content(body)
+    with smtplib.SMTP(settings.smtp_host, settings.smtp_port) as smtp:
+        smtp.starttls()
+        if settings.smtp_username:
+            smtp.login(settings.smtp_username, settings.smtp_password.get_secret_value())
+        smtp.send_message(message)
+
+
+def send_verification_email(user: User, token: str) -> None:
+    """Send a verification link containing the one-time raw token."""
+    send_email(str(user.email), "Verify your email", f"Use this verification token: {token}")
+
+
+def send_reset_email(user: User, token: str) -> None:
+    """Send a password-reset link containing the one-time raw token."""
+    send_email(str(user.email), "Reset your password", f"Use this password reset token: {token}")

app/services/product_service.py

@@ -0,0 +1,24 @@
+"""Product creation and query rules."""
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.domain.product import Product
+from app.models.schemas.product import ProductCreate
+
+
+async def create_product(session: AsyncSession, payload: ProductCreate) -> Product:
+    """Create and return a product after transaction commit."""
+    product = Product(**payload.model_dump())
+    session.add(product)
+    await session.commit()
+    await session.refresh(product)
+    return product
+
+
+async def update_product(session: AsyncSession, product: Product, payload: ProductCreate) -> Product:
+    """Replace editable product fields and persist the result."""
+    for field, value in payload.model_dump().items():
+        setattr(product, field, value)
+    await session.commit()
+    await session.refresh(product)
+    return product