feat: Implement WebUI Token Auto-Renewal (Sliding Window Expiration)

[danielaskdd]

feat: Implement WebUI Token Auto-Renewal (Sliding Window Expiration)

Summary

This PR implements automatic token renewal (sliding window expiration) to prevent active users from being unexpectedly logged out when their JWT tokens expire. The feature works across both backend and frontend with built-in rate limiting and path-based exclusions.

Motivation

Previously, users were forcibly logged out when their JWT token expired, even if they were actively using the application. This created a poor user experience, especially for long sessions. This implementation ensures that active users' tokens are automatically renewed before expiration, while guest users can silently re-authenticate without disruption.

Implementation Details

Backend Changes

Configuration (lightrag/api/config.py)

• Added TOKEN_AUTO_RENEW (default: true) - Enable/disable auto-renewal
• Added TOKEN_RENEW_THRESHOLD (default: 0.5) - Renew when remaining time < 50%
• Changed TOKEN_EXPIRE_HOURS and GUEST_TOKEN_EXPIRE_HOURS from int to float for finer control

Token Renewal Logic (lightrag/api/utils_api.py)

• Automatic token renewal when remaining time < threshold
• Returns new token via X-New-Token response header
• Rate Limiting: Minimum 60 seconds between renewals per user
• Path Exclusions: Skip renewal for /health and /documents/paginated

CORS Support (lightrag/api/lightrag_server.py)

• Added X-New-Token to expose_headers for cross-origin access

Frontend Changes

Token Handling (lightrag_webui/src/api/lightrag.ts)

• Response interceptor detects X-New-Token header and updates stored token
• Guest mode: Silent re-authentication on 401 errors via /auth-status
• Retry mechanism for failed requests after token refresh

State Management (lightrag_webui/src/stores/state.ts)

• Added isGuestMode flag to distinguish guest from authenticated users

Tests

New Test Suite (tests/test_token_auto_renewal.py)

• Token renewal threshold logic
• Rate limiting effectiveness
• Guest mode renewal
• Expiration calculation

User Experience

User Type	Behavior
Active Users	Token auto-renewed via X-New-Token header when < 50% remaining
Guest Mode	Silent re-authentication on 401, automatic retry
Username/Password	Redirect to login on 401 (unchanged behavior)

Configuration

# Enable automatic token renewal (default: true)
TOKEN_AUTO_RENEW=true

# Renewal threshold (default: 0.5 = 50%)
TOKEN_RENEW_THRESHOLD=0.5

# Token expiration can now use decimals for shorter testing periods
GUEST_TOKEN_EXPIRE_HOURS=0.0333  # 2 minutes for testing

Breaking Changes

None. Feature is enabled by default with backward-compatible behavior.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.