'code'

README.md

@@ -19,4 +19,53 @@ If your backend is hosted on a different domain (e.g., Hugging Face Spaces) than
 - Frontend fetch calls that rely on cookies must use `credentials: 'include'` (e.g. `fetch(url, { method, credentials: 'include' })`).
 - Backend CORS must have `allow_credentials=True` and the exact frontend origin (not `*`) in allowed origins. This project reads `FRONTEND_URL` for that purpose.
 
-If cookies are still not sent/received, open DevTools network tab and inspect the `Set-Cookie` response header and browser cookie/journal to see why it was blocked (e.g., SameSite/Secure/Domain issues).
+### Refresh token flow (implemented)
+- On login the backend now returns a **short-lived access token** (in the response) and sets a **HttpOnly refresh cookie** (`/api/auth` path).
+- To get a new access token, call `POST /api/auth/refresh` with `credentials: 'include'`. The server validates and rotates the refresh token and returns a new access token in the response body.
+- On logout the server revokes the refresh token and clears the refresh cookie.
+
+Client example (login + using refresh) — Vercel frontend:
+
+1) Login (receives access token in response body and a HttpOnly refresh cookie):
+
+```js
+const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/auth/login`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  credentials: 'include',
+  body: JSON.stringify({ email, password }),
+})
+const data = await res.json()
+const accessToken = data.access_token
+// Store accessToken in memory (React state)
+```
+
+2) Use access token for protected calls (in memory, sent in Authorization header):
+
+```js
+await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/tasks`, {
+  headers: { 'Authorization': `Bearer ${accessToken}` }
+})
+```
+
+3) Obtain a fresh access token when it expires:
+
+```js
+const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/auth/refresh`, {
+  method: 'POST',
+  credentials: 'include', // sends HttpOnly refresh cookie
+})
+const data = await res.json()
+const accessToken = data.access_token
+```
+
+If cookies are still not sent/received, open DevTools network tab and inspect the `Set-Cookie` response header and browser cookie/journal to see why it was blocked (e.g., SameSite/Secure/Domain issues).
+
+Database migration note:
+- After pulling these changes, run Alembic migrations to create the `refreshtoken` table:
+
+```bash
+alembic upgrade head
+```
+
+(If you deploy to Spaces, ensure your deployment runs the migration step or create the table manually.)

alembic/env.py

@@ -14,6 +14,7 @@ sys.path.append(os.path.dirname(os.path.dirname(__file__)))
 from src.models.user import User  # Import your models
 from src.models.task import Task  # Import your models
 from src.models.project import Project  # Import your models
+from src.models.refresh_token import RefreshToken  # Add RefreshToken model for migrations
 
 
 # this is the Alembic Config object, which provides

alembic/versions/20251222_add_refresh_token_table.py

@@ -0,0 +1,35 @@
+"""add refresh token table
+
+Revision ID: 20251222_add_refresh_token_table
+Revises: 
+Create Date: 2025-12-22 00:00:00.000000
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '20251222_add_refresh_token_table'
+down_revision = '4ac448e3f100'  # depends on last migration in the main chain
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'refreshtoken',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, nullable=False),
+        sa.Column('token_hash', sa.String(length=128), nullable=False),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('user.id'), nullable=True),
+        sa.Column('revoked', sa.Boolean(), nullable=False, server_default=sa.text('false')),
+        sa.Column('created_at', sa.DateTime(), nullable=True),
+        sa.Column('expires_at', sa.DateTime(), nullable=True),
+    )
+    # create index separately (SQLAlchemy/Alembic prefers explicit index creation)
+    op.create_index('ix_refreshtoken_token_hash', 'refreshtoken', ['token_hash'])
+
+
+def downgrade() -> None:
+    # drop index then table
+    op.drop_index('ix_refreshtoken_token_hash', table_name='refreshtoken')
+    op.drop_table('refreshtoken')

src/models/refresh_token.py

@@ -0,0 +1,17 @@
+from sqlmodel import SQLModel, Field, Relationship
+from typing import Optional
+import uuid
+from datetime import datetime
+from sqlalchemy import Column, DateTime, Boolean, String, ForeignKey
+
+
+class RefreshToken(SQLModel, table=True):
+    id: Optional[uuid.UUID] = Field(default_factory=uuid.uuid4, primary_key=True)
+    # Use a plain sa_column without `index=True` (SQLModel does not allow index=True when sa_column is provided)
+    token_hash: str = Field(sa_column=Column(String(length=128)))
+    user_id: Optional[uuid.UUID] = Field(foreign_key="user.id")
+    revoked: bool = Field(default=False, sa_column=Column(Boolean, default=False))
+    created_at: datetime = Field(sa_column=Column(DateTime, default=datetime.utcnow))
+    expires_at: datetime = Field(sa_column=Column(DateTime))
+
+    # Relationship back to user is optional and not required for our use-case

src/routers/auth.py

@@ -4,8 +4,10 @@ from typing import Annotated
 from datetime import datetime, timedelta
 from uuid import uuid4
 import secrets
+import hashlib
 
 from ..models.user import User, UserCreate, UserRead
+from ..models.refresh_token import RefreshToken
 from ..schemas.auth import RegisterRequest, RegisterResponse, LoginRequest, LoginResponse, ForgotPasswordRequest, ResetPasswordRequest
 from ..utils.security import hash_password, create_access_token, verify_password
 from ..utils.deps import get_current_user
@@ -15,6 +17,10 @@ from ..config import settings
 
 router = APIRouter(prefix="/api/auth", tags=["auth"])
 
+# Refresh token settings
+REFRESH_TOKEN_EXPIRE_DAYS = 30
+REFRESH_TOKEN_COOKIE_NAME = "refresh_token"
+
 # NOTE: For cross-site cookie auth to work (backend on a different domain than the frontend):
 # - The frontend must call login/register endpoints with `fetch(..., credentials: 'include')`
 # - The backend must have CORS allow_credentials=True and the exact frontend origin in allow_origins
@@ -24,7 +30,10 @@ router = APIRouter(prefix="/api/auth", tags=["auth"])
 
 @router.post("/register", response_model=RegisterResponse, status_code=status.HTTP_201_CREATED)
 def register(user_data: RegisterRequest, response: Response, session: Session = Depends(get_session_dep)):
-    """Register a new user with email and password."""
+    """Register a new user with email and password.
+
+    This returns a short-lived access token in the response and sets a HttpOnly refresh cookie.
+    """
 
     # Check if user already exists
     existing_user = session.exec(select(User).where(User.email == user_data.email)).first()
@@ -54,21 +63,29 @@ def register(user_data: RegisterRequest, response: Response, session: Session =
     session.commit()
     session.refresh(user)
 
-    # Create access token
-    access_token = create_access_token(data={"sub": str(user.id)})
-    
-    # Set the token as an httpOnly cookie
+    # Issue short-lived access token and refresh token
+    access_token = create_access_token(data={"sub": str(user.id)}, expires_delta=timedelta(minutes=15))
+
+    # Create refresh token, store hashed token in DB
+    raw_refresh = secrets.token_urlsafe(64)
+    token_hash = hashlib.sha256(raw_refresh.encode()).hexdigest()
+    expires_at = datetime.utcnow() + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
+
+    refresh_record = RefreshToken(token_hash=token_hash, user_id=user.id, expires_at=expires_at)
+    session.add(refresh_record)
+    session.commit()
+
+    # Set HttpOnly refresh cookie
     response.set_cookie(
-        key="access_token",
-        value=access_token,
+        key=REFRESH_TOKEN_COOKIE_NAME,
+        value=raw_refresh,
         httponly=True,
-        secure=settings.JWT_COOKIE_SECURE,  # True in production, False in development
-        samesite="none",  # Allow cross-site cookies; browsers require Secure for SameSite=None
-        max_age=settings.ACCESS_TOKEN_EXPIRE_DAYS * 24 * 60 * 60,  # Convert days to seconds
-        path="/"
+        secure=settings.JWT_COOKIE_SECURE,
+        samesite="none",
+        max_age=REFRESH_TOKEN_EXPIRE_DAYS * 24 * 60 * 60,
+        path="/api/auth"
     )
 
-    # Return response
     return RegisterResponse(
         id=user.id,
         email=user.email,
@@ -78,7 +95,11 @@ def register(user_data: RegisterRequest, response: Response, session: Session =
 
 @router.post("/login", response_model=LoginResponse)
 def login(login_data: LoginRequest, response: Response, session: Session = Depends(get_session_dep)):
-    """Authenticate user with email and password, return JWT token."""
+    """Authenticate user with email and password.
+
+    Returns a short-lived access token in the response body and sets a HttpOnly refresh cookie.
+    Frontend should store access token in memory and call protected APIs with Authorization header, or let frontend call `/api/auth/refresh` (with `credentials: 'include'`) to obtain a new access token.
+    """
 
     # Find user by email
     user = session.exec(select(User).where(User.email == login_data.email)).first()
@@ -90,24 +111,32 @@ def login(login_data: LoginRequest, response: Response, session: Session = Depen
             headers={"WWW-Authenticate": "Bearer"},
         )
 
-    # Create access token
-    access_token = create_access_token(data={"sub": str(user.id)})
-    
-    # Set the token as an httpOnly cookie
+    # Create short-lived access token (e.g., 15 minutes)
+    access_token = create_access_token(data={"sub": str(user.id)}, expires_delta=timedelta(minutes=15))
+
+    # Create refresh token, store hashed token in DB
+    raw_refresh = secrets.token_urlsafe(64)
+    token_hash = hashlib.sha256(raw_refresh.encode()).hexdigest()
+    expires_at = datetime.utcnow() + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
+
+    refresh_record = RefreshToken(token_hash=token_hash, user_id=user.id, expires_at=expires_at)
+    session.add(refresh_record)
+    session.commit()
+
+    # Set HttpOnly refresh cookie (sent to frontend with credentials: 'include')
     response.set_cookie(
-        key="access_token",
-        value=access_token,
+        key=REFRESH_TOKEN_COOKIE_NAME,
+        value=raw_refresh,
         httponly=True,
-        secure=settings.JWT_COOKIE_SECURE,  # True in production, False in development
-        samesite="none",  # Allow cross-site cookies; browsers require Secure for SameSite=None
-        max_age=settings.ACCESS_TOKEN_EXPIRE_DAYS * 24 * 60 * 60,  # Convert days to seconds
-        path="/"
+        secure=settings.JWT_COOKIE_SECURE,
+        samesite="none",
+        max_age=REFRESH_TOKEN_EXPIRE_DAYS * 24 * 60 * 60,
+        path="/api/auth"
     )
-    
-    # Debug: Print cookie attributes (do NOT log token value in production)
-    print(f"Cookie set (httponly={True}, secure={settings.JWT_COOKIE_SECURE}, samesite=none, max_age={settings.ACCESS_TOKEN_EXPIRE_DAYS * 24 * 60 * 60})")
 
-    # Return response
+    print(f"Refresh cookie set (httponly={True}, secure={settings.JWT_COOKIE_SECURE}, samesite=none, max_age={REFRESH_TOKEN_EXPIRE_DAYS * 24 * 60 * 60})")
+
+    # Return short-lived access token in response body for immediate use
     return LoginResponse(
         access_token=access_token,
         token_type="bearer",
@@ -119,29 +148,93 @@ def login(login_data: LoginRequest, response: Response, session: Session = Depen
     )
 
 
+@router.post("/refresh")
+def refresh_token(request: Request, response: Response, session: Session = Depends(get_session_dep)):
+    """Rotate refresh token and return a new short-lived access token.
+
+    This endpoint reads the HttpOnly refresh cookie, validates it, rotates it (revokes old),
+    and sets a new refresh cookie (cookie rotation) and returns a fresh access token.
+    Frontend must call this with `credentials: 'include'`.
+    """
+    raw_refresh = request.cookies.get(REFRESH_TOKEN_COOKIE_NAME)
+    if not raw_refresh:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="No refresh token provided")
+
+    token_hash = hashlib.sha256(raw_refresh.encode()).hexdigest()
+    token_record = session.exec(select(RefreshToken).where(RefreshToken.token_hash == token_hash)).first()
+
+    if not token_record or token_record.revoked:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token")
+
+    if token_record.expires_at < datetime.utcnow():
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Refresh token expired")
+
+    # Get user
+    user = session.get(User, token_record.user_id)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found")
+
+    # Revoke old token and rotate
+    token_record.revoked = True
+    session.add(token_record)
+
+    # Create new refresh token
+    new_raw_refresh = secrets.token_urlsafe(64)
+    new_token_hash = hashlib.sha256(new_raw_refresh.encode()).hexdigest()
+    new_expires_at = datetime.utcnow() + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
+
+    new_refresh_record = RefreshToken(token_hash=new_token_hash, user_id=user.id, expires_at=new_expires_at)
+    session.add(new_refresh_record)
+    session.commit()
+
+    # Set new refresh cookie
+    response.set_cookie(
+        key=REFRESH_TOKEN_COOKIE_NAME,
+        value=new_raw_refresh,
+        httponly=True,
+        secure=settings.JWT_COOKIE_SECURE,
+        samesite="none",
+        max_age=REFRESH_TOKEN_EXPIRE_DAYS * 24 * 60 * 60,
+        path="/api/auth"
+    )
+
+    # Create new short-lived access token and return it
+    access_token = create_access_token(data={"sub": str(user.id)}, expires_delta=timedelta(minutes=15))
+
+    return {"access_token": access_token, "token_type": "bearer"}
+
+
 @router.post("/logout")
-def logout(response: Response):
-    """Logout user by clearing the access token cookie."""
-    # Clear the access_token cookie
+def logout(request: Request, response: Response, session: Session = Depends(get_session_dep)):
+    """Logout user by revoking the refresh token cookie and clearing the cookie."""
+    raw_refresh = request.cookies.get(REFRESH_TOKEN_COOKIE_NAME)
+    if raw_refresh:
+        token_hash = hashlib.sha256(raw_refresh.encode()).hexdigest()
+        token_record = session.exec(select(RefreshToken).where(RefreshToken.token_hash == token_hash)).first()
+        if token_record:
+            token_record.revoked = True
+            session.add(token_record)
+            session.commit()
+
+    # Clear the refresh cookie
     response.set_cookie(
-        key="access_token",
+        key=REFRESH_TOKEN_COOKIE_NAME,
         value="",
         httponly=True,
         secure=settings.JWT_COOKIE_SECURE,
-        samesite="none",  # Allow cross-site cookies; browsers require Secure for SameSite=None
+        samesite="none",
         max_age=0,  # Expire immediately
-        path="/"
+        path="/api/auth"
     )
-    
+
     return {"message": "Logged out successfully"}
 
 
 @router.get("/me", response_model=RegisterResponse)
 def get_current_user_profile(request: Request, current_user: User = Depends(get_current_user)):
     """Get the current authenticated user's profile."""
-    # Debug: Print the cookies received
-    print(f"Received cookies: {request.cookies}")
-    print(f"Access token cookie: {request.cookies.get('access_token')}")
+    # Debug: Print the cookies received (do not print token values)
+    print(f"Received cookies: { {k: '***' for k in request.cookies.keys()} }")
     
     return RegisterResponse(
         id=current_user.id,