feat: implement long-term user login with refresh tokens

- Introduced a dual-token system for user authentication: a short-lived access token and a long-lived rotating refresh token.
- Created a new RefreshToken model to manage refresh tokens securely.
- Updated auth_api.py to handle login, refresh, and logout processes with the new token system.
- Enhanced security measures including token rotation and theft detection.
- Updated frontend to handle token refresh on 401 errors and adjusted SSE authentication.
- Removed CORS middleware as it's unnecessary behind the nginx proxy.
- Added tests to ensure functionality and security of the new token system.

backend/api/admin_api.py

@@ -1,11 +1,10 @@
 from flask import Blueprint, request, jsonify
 from datetime import datetime, timedelta
 from tinydb import Query
-import jwt
-from functools import wraps
 
 from db.db import users_db
 from models.user import User
+from api.utils import admin_required
 from config.deletion_config import (
     ACCOUNT_DELETION_THRESHOLD_HOURS,
     MIN_THRESHOLD_HOURS,
@@ -16,49 +15,6 @@ from utils.account_deletion_scheduler import trigger_deletion_manually
 
 admin_api = Blueprint('admin_api', __name__)
 
-def admin_required(f):
-    """
-    Decorator to require admin role for endpoints.
-    """
-    @wraps(f)
-    def decorated_function(*args, **kwargs):
-        # Get JWT token from cookie
-        token = request.cookies.get('token')
-        if not token:
-            return jsonify({'error': 'Authentication required', 'code': 'AUTH_REQUIRED'}), 401
-        
-        try:
-            # Verify JWT token
-            payload = jwt.decode(token, 'supersecretkey', algorithms=['HS256'])
-            user_id = payload.get('user_id')
-            
-            if not user_id:
-                return jsonify({'error': 'Invalid token', 'code': 'INVALID_TOKEN'}), 401
-            
-            # Get user from database
-            Query_ = Query()
-            user_dict = users_db.get(Query_.id == user_id)
-            
-            if not user_dict:
-                return jsonify({'error': 'User not found', 'code': 'USER_NOT_FOUND'}), 404
-            
-            user = User.from_dict(user_dict)
-            
-            # Check if user has admin role
-            if user.role != 'admin':
-                return jsonify({'error': 'Admin access required', 'code': 'ADMIN_REQUIRED'}), 403
-            
-            # Pass user to the endpoint
-            request.current_user = user
-            
-        except jwt.ExpiredSignatureError:
-            return jsonify({'error': 'Token expired', 'code': 'TOKEN_EXPIRED'}), 401
-        except jwt.InvalidTokenError:
-            return jsonify({'error': 'Invalid token', 'code': 'INVALID_TOKEN'}), 401
-        
-        return f(*args, **kwargs)
-    
-    return decorated_function
 
 @admin_api.route('/admin/deletion-queue', methods=['GET'])
 @admin_required

backend/api/auth_api.py

@@ -1,7 +1,11 @@
+import hashlib
 import logging
-import secrets, jwt
+import secrets
+import uuid
+import jwt
 from datetime import datetime, timedelta, timezone
 from models.user import User
+from models.refresh_token import RefreshToken
 from flask import Blueprint, request, jsonify, current_app
 from tinydb import Query
 import os
@@ -11,17 +15,22 @@ from werkzeug.security import generate_password_hash, check_password_hash
 from api.utils import sanitize_email
 from config.paths import get_user_image_dir
 
-from api.error_codes import MISSING_FIELDS, EMAIL_EXISTS, MISSING_TOKEN, INVALID_TOKEN, TOKEN_TIMESTAMP_MISSING, \
-    TOKEN_EXPIRED, ALREADY_VERIFIED, MISSING_EMAIL, USER_NOT_FOUND, MISSING_EMAIL_OR_PASSWORD, INVALID_CREDENTIALS, \
-    NOT_VERIFIED, ACCOUNT_MARKED_FOR_DELETION
-from db.db import users_db
+from api.error_codes import (
+    MISSING_FIELDS, EMAIL_EXISTS, MISSING_TOKEN, INVALID_TOKEN, TOKEN_TIMESTAMP_MISSING,
+    TOKEN_EXPIRED, ALREADY_VERIFIED, MISSING_EMAIL, USER_NOT_FOUND, MISSING_EMAIL_OR_PASSWORD,
+    INVALID_CREDENTIALS, NOT_VERIFIED, ACCOUNT_MARKED_FOR_DELETION,
+    REFRESH_TOKEN_REUSE, REFRESH_TOKEN_EXPIRED, MISSING_REFRESH_TOKEN,
+)
+from db.db import users_db, refresh_tokens_db
 from api.utils import normalize_email
 
 logger = logging.getLogger(__name__)
 auth_api = Blueprint('auth_api', __name__)
 UserQuery = Query()
-TOKEN_EXPIRY_MINUTES = 60*4
+TokenQuery = Query()
+TOKEN_EXPIRY_MINUTES = 60 * 4
 RESET_PASSWORD_TOKEN_EXPIRY_MINUTES = 10
+ACCESS_TOKEN_EXPIRY_MINUTES = 15
 
 
 def send_verification_email(to_email, token):
@@ -30,6 +39,77 @@ def send_verification_email(to_email, token):
 def send_reset_password_email(to_email, token):
     email_sender.send_reset_password_email(to_email, token)
 
+
+def _hash_token(raw_token: str) -> str:
+    """SHA-256 hash a raw refresh token for secure storage."""
+    return hashlib.sha256(raw_token.encode('utf-8')).hexdigest()
+
+
+def _create_access_token(user: User) -> str:
+    """Create a short-lived JWT access token."""
+    payload = {
+        'email': user.email,
+        'user_id': user.id,
+        'token_version': user.token_version,
+        'exp': datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRY_MINUTES),
+    }
+    return jwt.encode(payload, current_app.config['SECRET_KEY'], algorithm='HS256')
+
+
+def _create_refresh_token(user_id: str, token_family: str | None = None) -> tuple[str, RefreshToken]:
+    """
+    Create a refresh token: returns (raw_token, RefreshToken record).
+    If token_family is None, a new family is created (login).
+    Otherwise, the existing family is reused (rotation).
+    """
+    raw_token = secrets.token_urlsafe(32)
+    expiry_days = current_app.config['REFRESH_TOKEN_EXPIRY_DAYS']
+    expires_at = (datetime.now(timezone.utc) + timedelta(days=expiry_days)).isoformat()
+    family = token_family or str(uuid.uuid4())
+
+    record = RefreshToken(
+        user_id=user_id,
+        token_hash=_hash_token(raw_token),
+        token_family=family,
+        expires_at=expires_at,
+        is_used=False,
+    )
+    refresh_tokens_db.insert(record.to_dict())
+    return raw_token, record
+
+
+def _set_auth_cookies(resp, access_token: str, raw_refresh_token: str):
+    """Set both access and refresh token cookies on a response."""
+    expiry_days = current_app.config['REFRESH_TOKEN_EXPIRY_DAYS']
+    resp.set_cookie('access_token', access_token, httponly=True, secure=True, samesite='Strict')
+    resp.set_cookie(
+        'refresh_token', raw_refresh_token,
+        httponly=True, secure=True, samesite='Strict',
+        max_age=expiry_days * 24 * 3600,
+        path='/auth',
+    )
+
+
+def _clear_auth_cookies(resp):
+    """Clear both access and refresh token cookies."""
+    resp.set_cookie('access_token', '', expires=0, httponly=True, secure=True, samesite='Strict')
+    resp.set_cookie('refresh_token', '', expires=0, httponly=True, secure=True, samesite='Strict', path='/auth')
+
+
+def _purge_expired_tokens(user_id: str):
+    """Remove expired refresh tokens for a user to prevent unbounded DB growth."""
+    now = datetime.now(timezone.utc)
+    all_tokens = refresh_tokens_db.search(TokenQuery.user_id == user_id)
+    for t in all_tokens:
+        try:
+            exp = datetime.fromisoformat(t['expires_at'])
+            if exp.tzinfo is None:
+                exp = exp.replace(tzinfo=timezone.utc)
+            if now > exp:
+                refresh_tokens_db.remove(TokenQuery.id == t['id'])
+        except (ValueError, KeyError):
+            refresh_tokens_db.remove(TokenQuery.id == t['id'])
+
 @auth_api.route('/signup', methods=['POST'])
 def signup():
     data = request.get_json()
@@ -159,21 +239,22 @@ def login():
     if user.marked_for_deletion:
         return jsonify({'error': 'This account has been marked for deletion and cannot be accessed.', 'code': ACCOUNT_MARKED_FOR_DELETION}), 403
 
-    payload = {
-        'email': norm_email,
-        'user_id': user.id,
-        'token_version': user.token_version,
-        'exp': datetime.utcnow() + timedelta(days=62)
-    }
-    token = jwt.encode(payload, current_app.config['SECRET_KEY'], algorithm='HS256')
+    # Purge expired refresh tokens for this user
+    _purge_expired_tokens(user.id)
+
+    # Create access token (short-lived JWT)
+    access_token = _create_access_token(user)
+
+    # Create refresh token (long-lived, new family for fresh login)
+    raw_refresh, _ = _create_refresh_token(user.id)
 
     resp = jsonify({'message': 'Login successful'})
-    resp.set_cookie('token', token, httponly=True, secure=True, samesite='Strict')
+    _set_auth_cookies(resp, access_token, raw_refresh)
     return resp, 200
 
 @auth_api.route('/me', methods=['GET'])
 def me():
-    token = request.cookies.get('token')
+    token = request.cookies.get('access_token')
     if not token:
         return jsonify({'error': 'Missing token', 'code': MISSING_TOKEN}), 401
 
@@ -275,13 +356,100 @@ def reset_password():
     user.token_version += 1
     users_db.update(user.to_dict(), UserQuery.email == user.email)
 
+    # Invalidate ALL refresh tokens for this user
+    refresh_tokens_db.remove(TokenQuery.user_id == user.id)
+
     resp = jsonify({'message': 'Password has been reset'})
-    resp.set_cookie('token', '', expires=0, httponly=True, secure=True, samesite='Strict')
+    _clear_auth_cookies(resp)
     return resp, 200
 
+
+@auth_api.route('/refresh', methods=['POST'])
+def refresh():
+    raw_token = request.cookies.get('refresh_token')
+    if not raw_token:
+        return jsonify({'error': 'Missing refresh token', 'code': MISSING_REFRESH_TOKEN}), 401
+
+    token_hash = _hash_token(raw_token)
+    token_dict = refresh_tokens_db.get(TokenQuery.token_hash == token_hash)
+
+    if not token_dict:
+        # Token not found — could be invalid or already purged
+        resp = jsonify({'error': 'Invalid token', 'code': INVALID_TOKEN})
+        _clear_auth_cookies(resp)
+        return resp, 401
+
+    token_record = RefreshToken.from_dict(token_dict)
+
+    # THEFT DETECTION: token was already used (rotated out) but replayed
+    if token_record.is_used:
+        logger.warning(
+            'Refresh token reuse detected! user_id=%s, family=%s, ip=%s — killing all sessions',
+            token_record.user_id, token_record.token_family, request.remote_addr,
+        )
+        # Nuke ALL refresh tokens for this user
+        refresh_tokens_db.remove(TokenQuery.user_id == token_record.user_id)
+        resp = jsonify({'error': 'Token reuse detected, all sessions invalidated', 'code': REFRESH_TOKEN_REUSE})
+        _clear_auth_cookies(resp)
+        return resp, 401
+
+    # Check expiry
+    try:
+        exp = datetime.fromisoformat(token_record.expires_at)
+        if exp.tzinfo is None:
+            exp = exp.replace(tzinfo=timezone.utc)
+        if datetime.now(timezone.utc) > exp:
+            refresh_tokens_db.remove(TokenQuery.id == token_record.id)
+            resp = jsonify({'error': 'Refresh token expired', 'code': REFRESH_TOKEN_EXPIRED})
+            _clear_auth_cookies(resp)
+            return resp, 401
+    except ValueError:
+        refresh_tokens_db.remove(TokenQuery.id == token_record.id)
+        resp = jsonify({'error': 'Invalid token', 'code': INVALID_TOKEN})
+        _clear_auth_cookies(resp)
+        return resp, 401
+
+    # Look up the user
+    user_dict = users_db.get(UserQuery.id == token_record.user_id)
+    user = User.from_dict(user_dict) if user_dict else None
+    if not user:
+        refresh_tokens_db.remove(TokenQuery.id == token_record.id)
+        resp = jsonify({'error': 'User not found', 'code': USER_NOT_FOUND})
+        _clear_auth_cookies(resp)
+        return resp, 401
+
+    if user.marked_for_deletion:
+        refresh_tokens_db.remove(TokenQuery.user_id == user.id)
+        resp = jsonify({'error': 'Account marked for deletion', 'code': ACCOUNT_MARKED_FOR_DELETION})
+        _clear_auth_cookies(resp)
+        return resp, 403
+
+    # ROTATION: mark old token as used, create new one in same family
+    refresh_tokens_db.update({'is_used': True}, TokenQuery.id == token_record.id)
+    raw_new_refresh, _ = _create_refresh_token(user.id, token_family=token_record.token_family)
+
+    # Issue new access token
+    access_token = _create_access_token(user)
+
+    resp = jsonify({
+        'email': user.email,
+        'id': user.id,
+        'first_name': user.first_name,
+        'last_name': user.last_name,
+        'verified': user.verified,
+    })
+    _set_auth_cookies(resp, access_token, raw_new_refresh)
+    return resp, 200
+
+
 @auth_api.route('/logout', methods=['POST'])
 def logout():
+    # Delete the refresh token from DB if present
+    raw_token = request.cookies.get('refresh_token')
+    if raw_token:
+        token_hash = _hash_token(raw_token)
+        refresh_tokens_db.remove(TokenQuery.token_hash == token_hash)
+
     resp = jsonify({'message': 'Logged out'})
-    # Remove the token cookie by setting it to empty and expiring it
-    resp.set_cookie('token', '', expires=0, httponly=True, secure=True, samesite='Strict')
+    _clear_auth_cookies(resp)
     return resp, 200

backend/api/error_codes.py

@@ -12,6 +12,9 @@ INVALID_CREDENTIALS = "INVALID_CREDENTIALS"
 NOT_VERIFIED = "NOT_VERIFIED"
 ACCOUNT_MARKED_FOR_DELETION = "ACCOUNT_MARKED_FOR_DELETION"
 ALREADY_MARKED = "ALREADY_MARKED"
+REFRESH_TOKEN_REUSE = "REFRESH_TOKEN_REUSE"
+REFRESH_TOKEN_EXPIRED = "REFRESH_TOKEN_EXPIRED"
+MISSING_REFRESH_TOKEN = "MISSING_REFRESH_TOKEN"
 
 
 class ErrorCodes:

backend/api/tracking_api.py

@@ -1,61 +1,12 @@
 from flask import Blueprint, request, jsonify
-from api.utils import get_validated_user_id
+from api.utils import get_validated_user_id, admin_required
 from db.tracking import get_tracking_events_by_child, get_tracking_events_by_user
 from models.tracking_event import TrackingEvent
-from functools import wraps
-import jwt
-from tinydb import Query
-from db.db import users_db
-from models.user import User
 
 
 tracking_api = Blueprint('tracking_api', __name__)
 
 
-def admin_required(f):
-    """
-    Decorator to require admin role for endpoints.
-    """
-    @wraps(f)
-    def decorated_function(*args, **kwargs):
-        # Get JWT token from cookie
-        token = request.cookies.get('token')
-        if not token:
-            return jsonify({'error': 'Authentication required', 'code': 'AUTH_REQUIRED'}), 401
-        
-        try:
-            # Verify JWT token
-            payload = jwt.decode(token, 'supersecretkey', algorithms=['HS256'])
-            user_id = payload.get('user_id')
-            
-            if not user_id:
-                return jsonify({'error': 'Invalid token', 'code': 'INVALID_TOKEN'}), 401
-            
-            # Get user from database
-            Query_ = Query()
-            user_dict = users_db.get(Query_.id == user_id)
-            
-            if not user_dict:
-                return jsonify({'error': 'User not found', 'code': 'USER_NOT_FOUND'}), 404
-            
-            user = User.from_dict(user_dict)
-            
-            # Check if user has admin role
-            if user.role != 'admin':
-                return jsonify({'error': 'Admin access required', 'code': 'ADMIN_REQUIRED'}), 403
-            
-            # Store user_id in request context
-            request.admin_user_id = user_id
-            return f(*args, **kwargs)
-        
-        except jwt.ExpiredSignatureError:
-            return jsonify({'error': 'Token expired', 'code': 'TOKEN_EXPIRED'}), 401
-        except jwt.InvalidTokenError:
-            return jsonify({'error': 'Invalid token', 'code': 'INVALID_TOKEN'}), 401
-    
-    return decorated_function
-
-
 @tracking_api.route('/admin/tracking', methods=['GET'])
 @admin_required
 def get_tracking():

backend/api/user_api.py

@@ -21,7 +21,7 @@ user_api = Blueprint('user_api', __name__)
 UserQuery = Query()
 
 def get_current_user():
-    token = request.cookies.get('token')
+    token = request.cookies.get('access_token')
     if not token:
         return None
     try:

backend/api/utils.py

@@ -1,10 +1,12 @@
 import jwt
 import re
+from functools import wraps
 from db.db import users_db
 from tinydb import Query
 from flask import request, current_app, jsonify
 
 from events.sse import send_event_to_user
+from models.user import User
 
 
 def normalize_email(email: str) -> str:
@@ -21,7 +23,7 @@ def sanitize_email(email):
     return email.replace('@', '_at_').replace('.', '_dot_')
 
 def get_current_user_id():
-    token = request.cookies.get('token')
+    token = request.cookies.get('access_token')
     if not token:
         return None
     try:
@@ -50,4 +52,46 @@ def send_event_for_current_user(event):
     if not user_id:
         return jsonify({'error': 'Unauthorized'}), 401
     send_event_to_user(user_id, event)
-    return None
+    return None
+
+
+def admin_required(f):
+    """
+    Decorator to require admin role for endpoints.
+    Validates JWT from access_token cookie and checks admin role.
+    """
+    @wraps(f)
+    def decorated_function(*args, **kwargs):
+        token = request.cookies.get('access_token')
+        if not token:
+            return jsonify({'error': 'Authentication required', 'code': 'AUTH_REQUIRED'}), 401
+
+        try:
+            payload = jwt.decode(token, current_app.config['SECRET_KEY'], algorithms=['HS256'])
+            user_id = payload.get('user_id')
+
+            if not user_id:
+                return jsonify({'error': 'Invalid token', 'code': 'INVALID_TOKEN'}), 401
+
+            user_dict = users_db.get(Query().id == user_id)
+
+            if not user_dict:
+                return jsonify({'error': 'User not found', 'code': 'USER_NOT_FOUND'}), 404
+
+            user = User.from_dict(user_dict)
+
+            if user.role != 'admin':
+                return jsonify({'error': 'Admin access required', 'code': 'ADMIN_REQUIRED'}), 403
+
+            # Store user info in request context for the endpoint
+            request.current_user = user
+            request.admin_user_id = user_id
+
+        except jwt.ExpiredSignatureError:
+            return jsonify({'error': 'Token expired', 'code': 'TOKEN_EXPIRED'}), 401
+        except jwt.InvalidTokenError:
+            return jsonify({'error': 'Invalid token', 'code': 'INVALID_TOKEN'}), 401
+
+        return f(*args, **kwargs)
+
+    return decorated_function