# Authentication Flow Diagrams

## Cookie Isolation Architecture

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                               Browser                                         │
│                                                                               │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │  Admin Area      │  │  Store Area     │  │  Storefront Area       │          │
│  │  /admin/*        │  │  /store/*       │  │  /storefront/*         │          │
│  │                  │  │                  │  │                  │          │
│  │  🍪 admin_token  │  │  🍪 store_token │  │  🍪 customer_    │          │
│  │  Path: /admin    │  │  Path: /store   │  │     token        │          │
│  │                  │  │                  │  │  Path: /storefront     │          │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
│           │                      │                     │                     │
│           ├──────────────────────┼─────────────────────┤                     │
│           │          ❌ No Cookie Mixing               │                     │
│           │                      │                     │                     │
└───────────┼──────────────────────┼─────────────────────┼─────────────────────┘
            │                      │                     │
            ▼                      ▼                     ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│  Admin Backend   │  │  Store Backend  │  │  Storefront Backend    │
│  /admin/*        │  │  /store/*       │  │  /storefront/*         │
│                  │  │                  │  │                  │
│  ✅ admin_token  │  │  ✅ store_token │  │  ✅ customer_    │
│  ❌ store_token │  │  ❌ admin_token  │  │     token        │
│  ❌ customer_    │  │  ❌ customer_    │  │  ❌ admin_token  │
│     token        │  │     token        │  │  ❌ store_token │
└──────────────────┘  └──────────────────┘  └──────────────────┘
```

## Login Flow - Admin

```
┌──────────┐
│  Browser │
└──────────┘
     │
     │ POST /api/v1/admin/auth/login
     │ { username, password }
     ▼
┌─────────────────────────┐
│  Admin Auth Endpoint    │
│                         │
│  1. Validate credentials│
│  2. Check role == admin │
│  3. Generate JWT        │
└─────────────────────────┘
     │
     │ Set-Cookie: admin_token=<JWT>; Path=/admin; HttpOnly; SameSite=Lax
     │ Response: { access_token, user }
     ▼
┌──────────┐
│  Browser │──────────────────────────────────────┐
│          │                                       │
│  🍪 admin_token (Path=/admin)                   │
│  💾 localStorage.access_token                   │
└──────────┘                                       │
     │                                             │
     ├── Navigate to /admin/dashboard ────────────┤
     │   (Cookie sent automatically)              │
     │                                             │
     └── API call to /api/v1/admin/stores ───────┤
         (Authorization: Bearer <token>)          │
                                                   │
                                    ┌────────────────────────────────────────┐
                                    │  HTML: get_current_admin_from_     │
                                    │        cookie_or_header()          │
                                    │  API:  get_current_admin_api()     │
                                    │                                    │
                                    │  1. Check Auth header              │
                                    │  2. Check admin_token cookie (HTML)│
                                    │  3. Validate JWT                   │
                                    │  4. Verify role == admin           │
                                    │  ✅ Return User                    │
                                    └────────────────────────────────────┘
```

## Login Flow - Store

```
┌──────────┐
│  Browser │
└──────────┘
     │
     │ POST /api/v1/store/auth/login
     │ { username, password }
     ▼
┌─────────────────────────┐
│  Store Auth Endpoint   │
│                         │
│  1. Validate credentials│
│  2. Block if admin      │──────> ❌ "Admins cannot access store portal"
│  3. Check store access │
│  4. Generate JWT        │
└─────────────────────────┘
     │
     │ Set-Cookie: store_token=<JWT>; Path=/store; HttpOnly; SameSite=Lax
     │ Response: { access_token, user, store }
     ▼
┌──────────┐
│  Browser │──────────────────────────────────────┐
│          │                                       │
│  🍪 store_token (Path=/store)                 │
│  💾 localStorage.access_token                   │
└──────────┘                                       │
     │                                             │
     ├── Navigate to /store/ACME/dashboard ──────┤
     │   (Cookie sent automatically)              │
     │                                             │
     └── API call to /api/v1/store/ACME/products ┤
         (Authorization: Bearer <token>)          │
                                                   │
                                    ┌────────────────────────────────────────┐
                                    │  HTML: get_current_store_from_    │
                                    │        cookie_or_header()          │
                                    │  API:  get_current_store_api()    │
                                    │                                    │
                                    │  1. Check Auth header              │
                                    │  2. Check store_token cookie (HTML)│
                                    │  3. Validate JWT                   │
                                    │  4. Block if admin           │──> ❌ Error
                                    │  5. Verify store access           │
                                    │  ✅ Return User                    │
                                    └────────────────────────────────────┘
```

## Login Flow - Customer (Storefront)

```
┌──────────┐
│  Browser │
└──────────┘
     │
     │ POST /api/v1/storefront/auth/login
     │ { email, password }
     ▼
┌─────────────────────────┐
│  Customer Auth Endpoint │
│                         │
│  1. Validate credentials│
│  2. Check role = customer│
│  3. Generate JWT        │
└─────────────────────────┘
     │
     │ Set-Cookie: customer_token=<JWT>; Path=/storefront; HttpOnly; SameSite=Lax
     │ Response: { access_token, user }
     ▼
┌──────────┐
│  Browser │──────────────────────────────────────┐
│          │                                       │
│  🍪 customer_token (Path=/storefront)                 │
│  💾 localStorage.access_token                   │
└──────────┘                                       │
     │                                             │
     ├── Navigate to /storefront/account/dashboard ─────┤
     │   (Cookie sent automatically)              │
     │                                             │
     └── API call to /api/v1/storefront/orders ─────────┤
         (Authorization: Bearer <token>)          │
                                                   │
                                    ┌────────────────────────────────────────┐
                                    │  HTML: get_current_customer_from_  │
                                    │        cookie_or_header()          │
                                    │  API:  get_current_customer_api()  │
                                    │                                    │
                                    │  1. Check Auth header              │
                                    │  2. Check customer_token cookie (HTML)│
                                    │  3. Validate JWT                   │
                                    │  4. Verify role = customer         │
                                    │  ✅ Return User                    │
                                    └────────────────────────────────────┘
```

## Security Boundary Enforcement

```
                          ┌─────────────────────┐
                          │   Request Comes In  │
                          └──────────┬──────────┘
                                     │
                          ┌──────────▼──────────┐
                          │  What's the path?   │
                          └──────────┬──────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │               │           │           │               │
   Starts with     Starts with  Starts with Starts with   Starts with
   /admin/*        /store/*     /storefront/*      /api/*      (public)
         │               │           │           │               │
         ▼               ▼           ▼           ▼               ▼
┌────────────────┐┌────────────────┐┌────────────────┐┌────────────────┐┌────────────────┐
│ Check for:     ││ Check for:     ││ Check for:     ││ Check for:     ││ No Auth        │
│ - admin_token  ││ - store_token ││ - customer_    ││ - Authorization││ Required       │
│   cookie       ││   cookie       ││   token cookie ││   header       ││                │
│ - OR Auth      ││ - OR Auth      ││ - OR Auth      ││   (required)   ││ Public pages   │
│   header       ││   header       ││   header       ││                ││ & assets       │
└────────┬───────┘└────────┬───────┘└────────┬───────┘└────────┬───────┘└────────────────┘
         │                 │                 │                 │
         ▼                 ▼                 ▼                 ▼
┌────────────────┐┌────────────────┐┌────────────────┐┌────────────────┐
│ Validate:      ││ Validate:      ││ Validate:      ││ Validate:      │
│ - JWT valid    ││ - JWT valid    ││ - JWT valid    ││ - JWT valid    │
│ - User active  ││ - User active  ││ - User active  ││ - User active  │
│ - Role = admin ││ - Role != admin││ - Role =       ││ - Any role     │
│                ││ - Has store   ││   customer     ││   (depends on  │
│                ││   access       ││                ││    endpoint)   │
└────────┬───────┘└────────┬───────┘└────────┬───────┘└────────┬───────┘
         │                 │                 │                 │
         ▼                 ▼                 ▼                 ▼
    ✅ Allowed        ✅ Allowed        ✅ Allowed        ✅ Allowed
```

## Cross-Context Prevention

### ❌ What's Blocked

```
Admin trying to access store route:
┌──────────────────────────────────────────┐
│ User: admin@example.com (role: admin)    │
│ Token: Valid JWT with admin role         │
│ Request: GET /store/ACME/dashboard      │
└──────────────────────────────────────────┘
                    │
                    ▼
        ┌───────────────────────┐
        │ get_current_store_   │
        │ from_cookie_or_header │
        └───────────┬───────────┘
                    │
                    ▼
            Check: role == "admin"?
                    │
                    ▼ Yes
            ❌ InsufficientPermissionsException
            "Store access only - admins cannot use store portal"
```

```
Store trying to access admin route:
┌──────────────────────────────────────────┐
│ User: store@acme.com (role: store)     │
│ Token: Valid JWT with store role        │
│ Request: GET /admin/dashboard            │
└──────────────────────────────────────────┘
                    │
                    ▼
        ┌───────────────────────┐
        │ get_current_admin_    │
        │ from_cookie_or_header │
        └───────────┬───────────┘
                    │
                    ▼
            Check: role == "admin"?
                    │
                    ▼ No
            ❌ AdminRequiredException
            "Admin privileges required"
```

```
Admin cookie sent to store route:
┌──────────────────────────────────────────┐
│ Cookie: admin_token=<JWT> (Path=/admin)  │
│ Request: GET /store/ACME/dashboard      │
└──────────────────────────────────────────┘
                    │
                    ▼
            Browser checks cookie path
                    │
                    ▼
        Path /store does NOT match /admin
                    │
                    ▼
            ❌ Cookie NOT sent
            Request has no authentication
                    │
                    ▼
            ❌ InvalidTokenException
            "Store authentication required"
```

```
Customer trying to access admin route:
┌──────────────────────────────────────────┐
│ User: customer@example.com (role: customer)│
│ Token: Valid JWT with customer role      │
│ Request: GET /admin/dashboard            │
└──────────────────────────────────────────┘
                    │
                    ▼
        ┌───────────────────────┐
        │ get_current_admin_    │
        │ from_cookie_or_header │
        └───────────┬───────────┘
                    │
                    ▼
            Check: role == "admin"?
                    │
                    ▼ No
            ❌ AdminRequiredException
            "Admin privileges required"
```

```
Customer cookie sent to storefront route (allowed):
┌──────────────────────────────────────────┐
│ Cookie: customer_token=<JWT> (Path=/storefront)│
│ Request: GET /storefront/account/orders        │
└──────────────────────────────────────────┘
                    │
                    ▼
            Browser checks cookie path
                    │
                    ▼
        Path /storefront matches /storefront
                    │
                    ▼
            ✅ Cookie SENT automatically
                    │
                    ▼
        ┌───────────────────────┐
        │ get_current_customer_ │
        │ from_cookie_or_header │
        └───────────┬───────────┘
                    │
                    ▼
            ✅ Customer authenticated
            Page loads successfully
```

## Cookie Lifecycle

```
LOGIN
  │
  ├── Server generates JWT
  ├── Server sets cookie:
  │   • Name: admin_token, store_token, or customer_token
  │   • Value: JWT
  │   • Path: /admin, /store, or /storefront (context-specific)
  │   • HttpOnly: true
  │   • Secure: true (production)
  │   • SameSite: Lax
  │   • Max-Age: matches JWT expiry
  │
  └── Server returns JWT in response body
      └── Client stores in localStorage (optional)

PAGE NAVIGATION
  │
  ├── Browser automatically includes cookie
  │   if path matches
  │
  ├── Server reads cookie
  ├── Server validates JWT
  └── Server returns page or 401

API CALL
  │
  ├── Client reads token from localStorage
  ├── Client adds Authorization header
  │   Authorization: Bearer <JWT>
  │
  ├── Server reads header
  ├── Server validates JWT
  └── Server returns data or 401

LOGOUT
  │
  ├── Client calls logout endpoint
  ├── Server clears cookie:
  │   response.delete_cookie(name, path)
  │
  └── Client clears localStorage
      localStorage.removeItem('access_token')
```

## Key Takeaways

1. **Cookie Path Isolation** = Three separate cookies (admin_token, store_token, customer_token) with path-based isolation
2. **Role Checking** = Strict role validation at each boundary (admin, store, customer)
3. **Dual Auth Support** = Cookies for HTML pages, headers for API endpoints
4. **Security First** = HttpOnly, Secure, SameSite protection on all cookies
5. **Clear Boundaries** = Each context (admin/store/storefront) is completely isolated
6. **Three User Types** = Admins manage platform, stores manage stores, customers shop
