# 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.

---