# Session Revocation Cookie Invalidation Design

## Goals
- Ensure revoked session tokens clear stale browser cookies for affected clients.
- Apply the same self-revoke cookie-clearing rule to both user and admin revoke flows.
- Keep API response bodies unchanged; only `Set-Cookie` header behavior changes.
- Add a fallback `401` cleanup path when a revoked cookie is used later.

## Component UML

```mermaid
flowchart LR
    A["Browser Client"] --> B["Session Management Routes<br/>/revoke-session<br/>/revoke-sessions<br/>/revoke-other-sessions"]
    A --> C["Admin Revoke Routes<br/>/admin/revoke-user-session<br/>/admin/revoke-user-sessions"]
    A --> D["General Auth Request Path"]

    B --> E["Session Revocation Core"]
    C --> E
    E --> F["SessionManager + DatabaseAdapter"]

    D --> G["AthenaAuth::handle_request"]
    G --> H["Session token extraction<br/>(bearer + cookie)"]
    H --> F
    G --> I["AuthError -> AuthResponse mapper"]

    E --> J["Cookie utils<br/>create_clear_session_cookie(...)"]
    I --> J
    J --> K["Set-Cookie: clear session token cookie"]

    K --> A
```

## Sequence UML

### Before Flow: Revoke Succeeds but Cookie Can Stay Stale

```mermaid
sequenceDiagram
    participant Client as Browser Client
    participant Route as Session Revoke Route
    participant DB as SessionManager + DB

    Client->>Route: POST /revoke-session (target token)
    Route->>DB: delete_session(target token)
    DB-->>Route: success
    Route-->>Client: 200 { status: true } (no clear Set-Cookie)
    Note over Client: Stale session-token cookie may remain until a later request.
```

### After Flow A: Self-Revoke Returns Clear Set-Cookie Immediately

```mermaid
sequenceDiagram
    participant Client as Browser Client
    participant Route as Session Revoke Route
    participant DB as SessionManager + DB
    participant Cookie as Cookie utils

    Client->>Route: POST /revoke-session (target token == current token)
    Route->>DB: delete_session(current token)
    DB-->>Route: success
    Route->>Cookie: create_clear_session_cookie(...)
    Cookie-->>Route: clear Set-Cookie value
    Route-->>Client: 200 { status: true } + clear Set-Cookie
```

### After Flow B: Later Revoked-Cookie Request Gets 401 + Clear Set-Cookie

```mermaid
sequenceDiagram
    participant Client as Browser Client
    participant Pipeline as AthenaAuth::handle_request
    participant Extract as Session token extraction
    participant DB as SessionManager + DB
    participant Cookie as Cookie utils

    Client->>Pipeline: Request with revoked session-token cookie
    Pipeline->>Extract: read bearer/cookie token
    Extract->>DB: get_session(cookie token)
    DB-->>Extract: not found (revoked/expired)
    Extract-->>Pipeline: AuthError::SessionNotFound
    Pipeline->>Cookie: create_clear_session_cookie(...)
    Cookie-->>Pipeline: clear Set-Cookie value
    Pipeline-->>Client: 401 { message: ... } + clear Set-Cookie
```

### Admin Self-Revoke Flow: Same Cookie-Clearing Behavior

```mermaid
sequenceDiagram
    participant AdminClient as Admin Browser Client
    participant AdminRoute as Admin Revoke Route
    participant DB as SessionManager + DB
    participant Cookie as Cookie utils

    AdminClient->>AdminRoute: POST /admin/revoke-user-session or /admin/revoke-user-sessions (self target)
    AdminRoute->>DB: revoke current admin session(s)
    DB-->>AdminRoute: success
    AdminRoute->>Cookie: create_clear_session_cookie(...)
    Cookie-->>AdminRoute: clear Set-Cookie value
    AdminRoute-->>AdminClient: 200 { success: true } + clear Set-Cookie
```

## Decision Table

| Scenario | Endpoint | Status | Set-Cookie Behavior | Notes |
|---|---|---|---|---|
| Self-revoke single session | `/revoke-session` | `200` | Clear session-token cookie | Immediate client cleanup |
| Revoke other session only | `/revoke-session` | `200` | No clear cookie | Current caller session stays valid |
| Revoke all user sessions | `/revoke-sessions` | `200` | Clear session-token cookie | Caller session is revoked too |
| Admin self-revoke (single/all) | `/admin/revoke-user-session`, `/admin/revoke-user-sessions` | `200` | Clear session-token cookie | Mirrors user self-revoke behavior |
| Revoked cookie follow-up request | Any auth-protected route | `401` | Clear session-token cookie | Fallback cleanup path |

## Design Choices
- Use one shared clear-cookie builder (`create_clear_session_cookie`) so cookie attributes remain consistent.
- Keep body schemas intact (`{ status: true }`, `{ success: true }`, `401 { message: ... }`) and scope the change to headers.
- Keep fallback cleanup in the common auth pipeline so revoked-cookie clients are repaired even when revocation was initiated elsewhere.
