messy logout fixing

logout-solution.md

@@ -0,0 +1,215 @@
+# 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.
+
+---