216 lines
5.5 KiB
Markdown
216 lines
5.5 KiB
Markdown
# AUTHENTICATION SYSTEM OVERHAUL
|
||
|
||
Designed specifically for **Django 5.2 + DRF + Redis + JWT + SPA frontend** and your requirement that **“Remember me = 20 days, zero random logouts”**.
|
||
|
||
---
|
||
|
||
# MASTER SYSTEM PROMPT
|
||
|
||
## Objective: Eliminate Random Logouts and Guarantee 20-Day Persistent Login
|
||
|
||
### Context
|
||
|
||
You are working inside a production Django 5.2 backend with DRF, Redis, JWT authentication, Celery, Stripe, and a SPA frontend.
|
||
The system currently suffers from random user logouts caused by auth state desynchronization.
|
||
|
||
Your task is to **stabilize authentication without breaking any existing functionality**.
|
||
|
||
You must not introduce behavioral regressions.
|
||
|
||
---
|
||
|
||
## CORE REQUIREMENTS (NON-NEGOTIABLE)
|
||
|
||
1. If a user selects “Remember me” at login, they must remain logged in for **20 full days**, including idle time.
|
||
2. Users must **never be logged out due to**:
|
||
|
||
* Network failures
|
||
* Permission errors
|
||
* Plan or account state changes
|
||
* Temporary backend errors
|
||
* Multi-tab usage
|
||
3. Logout may occur **only** when:
|
||
|
||
* The user explicitly logs out
|
||
* The refresh token expires
|
||
* The refresh token is revoked (password change or admin action)
|
||
|
||
---
|
||
|
||
## PRIMARY DESIGN PRINCIPLES
|
||
|
||
* Authentication authority must be **single-source**.
|
||
* Refresh token validity is the only indicator of login state.
|
||
* Access tokens are disposable and replaceable.
|
||
* The frontend must never decide to log out based on generic API failures.
|
||
* Authentication and authorization must be treated as separate concerns.
|
||
|
||
---
|
||
|
||
## AUTHENTICATION ARCHITECTURE YOU MUST ENFORCE
|
||
|
||
### Token Model
|
||
|
||
* Access token: short-lived, used only for API authorization
|
||
* Refresh token: long-lived, stored server-side, revocable, authoritative
|
||
* Refresh token lifetime:
|
||
|
||
* 20 days if “Remember me” is selected
|
||
* Short duration otherwise
|
||
|
||
### Storage
|
||
|
||
* Refresh token must be stored:
|
||
|
||
* Server-side (database or Redis)
|
||
* As an HttpOnly cookie on the client
|
||
* Access token must:
|
||
|
||
* Be stored only in memory
|
||
* Never be persisted to localStorage or cookies
|
||
|
||
---
|
||
|
||
## BACKEND RULES (CRITICAL)
|
||
|
||
### Session Handling
|
||
|
||
* Redis must be used for Django sessions
|
||
* Django sessions must NOT be used as SPA auth authority
|
||
* Sessions may remain for Django Admin only
|
||
|
||
### Refresh Token Rules
|
||
|
||
* Refresh tokens must be:
|
||
|
||
* Uniquely identifiable
|
||
* Revocable
|
||
* Rotated on every successful refresh
|
||
* Refresh operations must be atomic
|
||
* Old refresh tokens must be invalidated only after a new one is safely issued
|
||
|
||
### Logout Rules
|
||
|
||
The backend must NEVER:
|
||
|
||
* Call logout inside middleware
|
||
* Invalidate sessions during request processing
|
||
* Log users out due to validation or entitlement changes
|
||
|
||
The backend MAY:
|
||
|
||
* Return structured error codes
|
||
* Block access with 403 or domain-specific errors
|
||
* Revoke refresh tokens only via explicit actions
|
||
|
||
---
|
||
|
||
## FRONTEND RULES (ABSOLUTE)
|
||
|
||
### Logout Triggers
|
||
|
||
The frontend may log out ONLY when:
|
||
|
||
* The refresh endpoint returns a hard authentication failure
|
||
* The backend explicitly signals session revocation
|
||
* The user clicks logout
|
||
|
||
The frontend must NEVER log out due to:
|
||
|
||
* 403 errors
|
||
* 402 errors
|
||
* Network failures
|
||
* Timeouts
|
||
* 5xx errors
|
||
* Permission or plan restrictions
|
||
|
||
### Token Refresh Behavior
|
||
|
||
* Only one refresh operation may occur at a time
|
||
* All concurrent API calls must wait for the same refresh promise
|
||
* Refresh failures due to network issues must retry
|
||
* Only an explicit refresh authentication failure may trigger logout
|
||
|
||
### Multi-Tab Coordination
|
||
|
||
* Token refresh must be coordinated across tabs
|
||
* When one tab refreshes successfully, all tabs must update state
|
||
* Multiple tabs must never overwrite or invalidate each other’s tokens
|
||
|
||
---
|
||
|
||
## COOKIE AND SECURITY CONSTRAINTS
|
||
|
||
* Refresh token cookie:
|
||
|
||
* HttpOnly = true
|
||
* Secure = true (production)
|
||
* SameSite = Lax
|
||
* Path limited to refresh endpoint
|
||
* Max-Age reflects 20-day remember-me duration
|
||
|
||
* Access tokens must never be placed in cookies
|
||
|
||
---
|
||
|
||
## ERROR HANDLING AND CLASSIFICATION
|
||
|
||
You must enforce strict error classification:
|
||
|
||
* Authentication failure: invalid or expired refresh token
|
||
* Authorization failure: permissions, plan, entitlement
|
||
* Transport failure: network, timeout, 5xx
|
||
|
||
Only authentication failure may cause logout.
|
||
|
||
---
|
||
|
||
## ROLLOUT STRATEGY (MUST FOLLOW ORDER)
|
||
|
||
1. Add observability for refresh success, failure, retries, and logout reasons
|
||
2. Remove frontend logout on non-auth errors
|
||
3. Implement refresh deduplication
|
||
4. Remove backend middleware logout behavior
|
||
5. Introduce refresh token persistence and rotation
|
||
6. Implement remember-me expiry logic
|
||
7. Add multi-tab coordination
|
||
8. Validate stability before tightening security
|
||
|
||
Each step must be backward-compatible.
|
||
|
||
---
|
||
|
||
## SUCCESS CRITERIA
|
||
|
||
The system is considered successful only if:
|
||
|
||
* A remembered user remains logged in for 20 days without activity
|
||
* Multi-tab usage never causes logout
|
||
* Network disruptions do not affect login state
|
||
* Access tokens may expire repeatedly without user impact
|
||
* Auth and entitlement failures are fully decoupled
|
||
* Logout events are deliberate and explainable
|
||
|
||
---
|
||
|
||
## FAILURE CONDITIONS (DO NOT SHIP IF ANY OCCUR)
|
||
|
||
* Any logout triggered by 403 or 5xx
|
||
* Any middleware-initiated logout
|
||
* Any auth state stored in more than one authoritative place
|
||
* Any refresh race condition
|
||
* Any token overwrite across tabs
|
||
|
||
---
|
||
|
||
## FINAL DIRECTIVE
|
||
|
||
Your priority is **stability over cleverness**.
|
||
If any optimization increases complexity or fragility, it must be rejected.
|
||
|
||
The system must behave predictably, quietly, and invisibly to the user.
|
||
|
||
No random logouts. No surprises. No exceptions.
|
||
|
||
---
|