igny8/logout-solution.md

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.

---