feat(auth): migrate user identities from integer to UUIDv4

.env.example

@@ -14,7 +14,7 @@ POSTGRES_SERVER=localhost
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=postgres
 POSTGRES_DB=fluentmeet
-DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/fluentmeet"
+DATABASE_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/fluentmeet
 
 # Redis
 REDIS_HOST=localhost

README.md

@@ -130,6 +130,10 @@ Ensure your models are imported in `app/models/init.py` for Alembic to detect th
 ```bash
 python -m alembic revision --autogenerate -m "Add Meeting model"
 ```
+### **Migrate Head**
+```bash
+alembic upgrade head
+```
 
 ### **Applying Migrations**
 ```bash

alembic/versions/7f066a8213a8_change_user_id_to_uuid.py

@@ -0,0 +1,73 @@
+"""Change User.id to UUID
+
+Revision ID: 7f066a8213a8
+Revises: e1a664780dc6
+Create Date: 2026-03-27 22:35:06.005762
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "7f066a8213a8"
+down_revision: Union[str, Sequence[str], None] = "e1a664780dc6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    # Setup extension for UUID generation if needed
+    op.execute('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"')
+
+    # We truncate because casting int -> uuid with a random function would break existing foreign key relations.
+    op.execute("TRUNCATE TABLE users CASCADE")
+
+    # Drop foreign key constraint on verification_tokens
+    op.drop_constraint(
+        "verification_tokens_user_id_fkey", "verification_tokens", type_="foreignkey"
+    )
+
+    # Alter the columns
+    # Alter the columns. First drop the integer default from the id column to allow cast.
+    op.execute("ALTER TABLE users ALTER COLUMN id DROP DEFAULT")
+    op.execute(
+        "ALTER TABLE users ALTER COLUMN id SET DATA TYPE UUID USING (uuid_generate_v4())"
+    )
+    op.execute(
+        "ALTER TABLE verification_tokens ALTER COLUMN user_id SET DATA TYPE UUID USING (uuid_generate_v4())"
+    )
+
+    # Re-add foreign key constraint
+    op.create_foreign_key(
+        "verification_tokens_user_id_fkey",
+        "verification_tokens",
+        "users",
+        ["user_id"],
+        ["id"],
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column(
+        "verification_tokens",
+        "user_id",
+        existing_type=sa.Uuid(),
+        type_=sa.INTEGER(),
+        existing_nullable=False,
+    )
+    op.alter_column(
+        "users",
+        "id",
+        existing_type=sa.Uuid(),
+        type_=sa.INTEGER(),
+        existing_nullable=False,
+    )
+    # ### end Alembic commands ###

alembic/versions/e1a664780dc6_add_meeting_model.py

@@ -0,0 +1,32 @@
+"""Add Meeting model
+
+Revision ID: e1a664780dc6
+Revises: 19dc9714d9ea
+Create Date: 2026-03-27 22:18:35.070453
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "e1a664780dc6"
+down_revision: Union[str, Sequence[str], None] = "19dc9714d9ea"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    pass
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    pass
+    # ### end Alembic commands ###

alembic_output.txt

@@ -0,0 +1,3 @@
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.runtime.migration] Running upgrade 19dc9714d9ea -> e1a664780dc6, Add Meeting model

app/api/v1/endpoints/auth.py

@@ -2,33 +2,46 @@
 from uuid import uuid4
 
 from fastapi import APIRouter, Depends, Query, Request, status
+from fastapi.responses import JSONResponse
 from sqlalchemy.orm import Session
 
 from app.core.config import settings
+from app.core.exceptions import ForbiddenException, UnauthorizedException
 from app.core.rate_limiter import limiter
 from app.core.sanitize import sanitize_log_args
+from app.core.security import SecurityService, get_security_service
 from app.crud.user.user import create_user, get_user_by_email
 from app.db.session import get_db
 from app.schemas.auth import (
     ActionAcknowledgement,
     ForgotPasswordRequest,
+    LoginRequest,
+    LoginResponse,
     ResendVerificationRequest,
     SignupResponse,
     VerifyEmailResponse,
 )
 from app.schemas.user import UserCreate
+from app.services.account_lockout import (
+    AccountLockoutService,
+    get_account_lockout_service,
+)
 from app.services.auth_verification import (
     AuthVerificationService,
     get_auth_verification_service,
 )
 from app.services.email_producer import EmailProducerService, get_email_producer_service
+from app.services.token_store import TokenStoreService, get_token_store_service
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/auth", tags=["auth"])
 DB_SESSION_DEPENDENCY = Depends(get_db)
 EMAIL_PRODUCER_DEPENDENCY = Depends(get_email_producer_service)
 AUTH_VERIFICATION_SERVICE_DEPENDENCY = Depends(get_auth_verification_service)
+SECURITY_SERVICE_DEPENDENCY = Depends(get_security_service)
+TOKEN_STORE_SERVICE_DEPENDENCY = Depends(get_token_store_service)
+ACCOUNT_LOCKOUT_SERVICE_DEPENDENCY = Depends(get_account_lockout_service)
 
 
 @router.post(
@@ -216,3 +229,160 @@ async def resend_verification(
             "If an account with that email exists, we have sent a verification email."
         )
     )
+
+
+@router.post(
+    "/login",
+    response_model=LoginResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Authenticate a registered user",
+    description=(
+        "Validates email and password, issues a JWT access token (returned "
+        "in the body) and a JWT refresh token (set as an HttpOnly cookie). "
+        "Rate-limited to 10 requests/minute per IP. The account is locked "
+        "after 5 consecutive failed attempts for 5 days."
+    ),
+    responses={
+        401: {
+            "description": "Invalid credentials",
+            "content": {
+                "application/json": {
+                    "example": {
+                        "status": "error",
+                        "code": "INVALID_CREDENTIALS",
+                        "message": "Invalid email or password.",
+                        "details": [],
+                    }
+                }
+            },
+        },
+        403: {
+            "description": "Account not verified, deleted, or locked",
+            "content": {
+                "application/json": {
+                    "examples": {
+                        "not_verified": {
+                            "value": {
+                                "status": "error",
+                                "code": "EMAIL_NOT_VERIFIED",
+                                "message": (
+                                    "Please verify your email before logging in."
+                                ),
+                                "details": [],
+                            }
+                        },
+                        "deleted": {
+                            "value": {
+                                "status": "error",
+                                "code": "ACCOUNT_DELETED",
+                                "message": "This account has been deleted.",
+                                "details": [],
+                            }
+                        },
+                        "locked": {
+                            "value": {
+                                "status": "error",
+                                "code": "ACCOUNT_LOCKED",
+                                "message": (
+                                    "Account is temporarily locked due to "
+                                    "too many failed login attempts. "
+                                    "Please try again later."
+                                ),
+                                "details": [],
+                            }
+                        },
+                    }
+                }
+            },
+        },
+    },
+)
+@limiter.limit("10/minute")
+async def login(
+    request: Request,
+    payload: LoginRequest,
+    db: Session = DB_SESSION_DEPENDENCY,
+    security_svc: SecurityService = SECURITY_SERVICE_DEPENDENCY,
+    token_store: TokenStoreService = TOKEN_STORE_SERVICE_DEPENDENCY,
+    lockout_svc: AccountLockoutService = ACCOUNT_LOCKOUT_SERVICE_DEPENDENCY,
+) -> JSONResponse:
+    del request  # consumed by slowapi
+    email = payload.email.lower()
+
+    # Check lockout
+    if await lockout_svc.is_locked(email):
+        raise ForbiddenException(
+            code="ACCOUNT_LOCKED",
+            message=(
+                "Account is temporarily locked due to too many failed "
+                "login attempts. Please try again later."
+            ),
+        )
+
+    # Lookup user
+    user = get_user_by_email(db, email)
+    if user is None:
+        # Record a failed attempt even for non-existent emails so that
+        # timing is indistinguishable from a wrong-password attempt.
+        await lockout_svc.record_failed_attempt(email)
+        raise UnauthorizedException(
+            code="INVALID_CREDENTIALS",
+            message="Invalid email or password.",
+        )
+
+    # Verify password
+    if not security_svc.verify_password(payload.password, user.hashed_password):
+        await lockout_svc.record_failed_attempt(email)
+        raise UnauthorizedException(
+            code="INVALID_CREDENTIALS",
+            message="Invalid email or password.",
+        )
+
+    # Guard: email verified?
+    if not user.is_verified:
+        raise ForbiddenException(
+            code="EMAIL_NOT_VERIFIED",
+            message="Please verify your email before logging in.",
+        )
+
+    # Guard: soft-deleted?
+    if user.deleted_at is not None:
+        raise ForbiddenException(
+            code="ACCOUNT_DELETED",
+            message="This account has been deleted.",
+        )
+
+    # Reset failed-login counter on success
+    await lockout_svc.reset_attempts(email)
+
+    # Issue tokens
+    access_token, expires_in = security_svc.create_access_token(email=email)
+    refresh_token, refresh_jti, refresh_ttl = security_svc.create_refresh_token(
+        email=email,
+    )
+
+    # Persist refresh JTI in Redis
+    await token_store.save_refresh_token(jti=refresh_jti, ttl_seconds=refresh_ttl)
+
+    # Build JSON body
+    body = LoginResponse(
+        access_token=access_token,
+        user_id=user.id,
+        token_type="bearer",
+        expires_in=expires_in,
+    )
+
+    response = JSONResponse(content=body.model_dump(mode="json"), status_code=200)
+
+    # Set HttpOnly refresh-token cookie
+    response.set_cookie(
+        key="refresh_token",
+        value=refresh_token,
+        httponly=True,
+        secure=True,
+        samesite="strict",
+        path=f"{settings.API_V1_STR}/auth",
+        max_age=refresh_ttl,
+    )
+
+    return response

app/core/config.py

@@ -20,10 +20,15 @@ class Settings(BaseSettings):
 
     # Security
     SECRET_KEY: str = "placeholder_secret_key"
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 15
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
     REFRESH_TOKEN_EXPIRE_DAYS: int = 7
     VERIFICATION_TOKEN_EXPIRE_HOURS: int = 24
 
+    # Account Lockout
+    MAX_FAILED_LOGIN_ATTEMPTS: int = 5
+    ACCOUNT_LOCKOUT_DAYS: int = 5
+
     # Database
     POSTGRES_SERVER: str = "localhost"
     POSTGRES_USER: str = "postgres"