feat: enhance refresh token handling with grace period and rotation detection

backend/api/auth_api.py

@@ -43,6 +43,12 @@ try:
     ACCESS_TOKEN_EXPIRY_MINUTES = int(os.environ.get('ACCESS_TOKEN_EXPIRY_MINUTES', '15'))
 except ValueError:
     ACCESS_TOKEN_EXPIRY_MINUTES = 15
+try:
+    REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS = int(
+        os.environ.get('REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS', '30')
+    )
+except ValueError:
+    REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS = 30
 E2E_TEST_EMAIL = 'e2e@test.com'
 E2E_TEST_PASSWORD = 'E2eTestPass1!'
 E2E_TEST_PIN = '1234'
@@ -412,18 +418,21 @@ def refresh():
 
     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})
+    # Look up the user early (needed for both legitimate rotation and grace-period handling)
+    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
+
     # Check expiry
     try:
         exp = datetime.fromisoformat(token_record.expires_at)
@@ -440,23 +449,59 @@ def refresh():
         _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})
+    # THEFT DETECTION: token was already used (rotated out) but replayed
+    if token_record.is_used:
+        # Grace period: tolerate a very recent rotation to avoid false positives
+        # from legitimate concurrent refresh requests (race conditions).
+        grace_period = current_app.config.get(
+            'REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS', REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS
+        )
+        rotated_at = token_record.rotated_at
+        is_race_condition = False
+        if rotated_at:
+            try:
+                rotated_dt = datetime.fromisoformat(rotated_at)
+                if rotated_dt.tzinfo is None:
+                    rotated_dt = rotated_dt.replace(tzinfo=timezone.utc)
+                if (datetime.now(timezone.utc) - rotated_dt).total_seconds() <= grace_period:
+                    is_race_condition = True
+            except ValueError:
+                pass
+
+        if is_race_condition:
+            logger.info(
+                'Refresh token replay within grace period treated as race condition. user_id=%s, family=%s, ip=%s',
+                token_record.user_id, token_record.token_family, request.remote_addr,
+            )
+            raw_new_refresh, _ = _create_refresh_token(user.id, token_family=token_record.token_family)
+            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
+
+        logger.warning(
+            'Refresh token reuse detected! user_id=%s, family=%s, ip=%s — killing family sessions',
+            token_record.user_id, token_record.token_family, request.remote_addr,
+        )
+        # Invalidate only the affected family, not every session for the user.
+        refresh_tokens_db.remove(
+            (TokenQuery.user_id == token_record.user_id) & (TokenQuery.token_family == token_record.token_family)
+        )
+        resp = jsonify({'error': 'Token reuse detected, family sessions invalidated', 'code': REFRESH_TOKEN_REUSE})
         _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)
+    refresh_tokens_db.update(
+        {'is_used': True, 'rotated_at': datetime.now(timezone.utc).isoformat()},
+        TokenQuery.id == token_record.id,
+    )
     raw_new_refresh, _ = _create_refresh_token(user.id, token_family=token_record.token_family)
 
     # Issue new access token