Samir Boulahtit
0d7915c275
Updated all documentation to use correct authentication dependency names: - HTML pages: get_current_admin_from_cookie_or_header, get_current_vendor_from_cookie_or_header, get_current_customer_from_cookie_or_header - API endpoints: get_current_admin_api, get_current_vendor_api, get_current_customer_api Changes: - Updated authentication flow diagrams with correct dependency names for admin and vendor flows - Added comprehensive customer/shop authentication flow documentation - Updated cookie isolation architecture to show all three contexts (admin, vendor, shop) - Expanded security boundary enforcement diagram to include shop routes - Added customer cross-context prevention examples - Updated all code examples in frontend and backend documentation - Fixed import statements to use app.api.deps instead of app.core.auth Files updated: - docs/api/authentication-flow-diagrams.md (added customer flows) - docs/frontend/admin/page-templates.md - docs/frontend/admin/architecture.md - docs/frontend/shared/ui-components.md - docs/frontend/shared/sidebar.md - docs/development/exception-handling.md - docs/architecture/diagrams/vendor-domain-diagrams.md - docs/backend/admin-integration-guide.md - docs/backend/admin-feature-integration.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
21 KiB
21 KiB
Authentication Flow Diagrams
Cookie Isolation Architecture
┌──────────────────────────────────────────────────────────────────────────────┐
│ Browser │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Admin Area │ │ Vendor Area │ │ Shop Area │ │
│ │ /admin/* │ │ /vendor/* │ │ /shop/* │ │
│ │ │ │ │ │ │ │
│ │ 🍪 admin_token │ │ 🍪 vendor_token │ │ 🍪 customer_ │ │
│ │ Path: /admin │ │ Path: /vendor │ │ token │ │
│ │ │ │ │ │ Path: /shop │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │ │ │
│ ├──────────────────────┼─────────────────────┤ │
│ │ ❌ No Cookie Mixing │ │
│ │ │ │ │
└───────────┼──────────────────────┼─────────────────────┼─────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Admin Backend │ │ Vendor Backend │ │ Shop Backend │
│ /admin/* │ │ /vendor/* │ │ /shop/* │
│ │ │ │ │ │
│ ✅ admin_token │ │ ✅ vendor_token │ │ ✅ customer_ │
│ ❌ vendor_token │ │ ❌ admin_token │ │ token │
│ ❌ customer_ │ │ ❌ customer_ │ │ ❌ admin_token │
│ token │ │ token │ │ ❌ vendor_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/vendors ───────┤
(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 - Vendor
┌──────────┐
│ Browser │
└──────────┘
│
│ POST /api/v1/vendor/auth/login
│ { username, password }
▼
┌─────────────────────────┐
│ Vendor Auth Endpoint │
│ │
│ 1. Validate credentials│
│ 2. Block if admin │──────> ❌ "Admins cannot access vendor portal"
│ 3. Check vendor access │
│ 4. Generate JWT │
└─────────────────────────┘
│
│ Set-Cookie: vendor_token=<JWT>; Path=/vendor; HttpOnly; SameSite=Lax
│ Response: { access_token, user, vendor }
▼
┌──────────┐
│ Browser │──────────────────────────────────────┐
│ │ │
│ 🍪 vendor_token (Path=/vendor) │
│ 💾 localStorage.access_token │
└──────────┘ │
│ │
├── Navigate to /vendor/ACME/dashboard ──────┤
│ (Cookie sent automatically) │
│ │
└── API call to /api/v1/vendor/ACME/products ┤
(Authorization: Bearer <token>) │
│
┌────────────────────────────────────────┐
│ HTML: get_current_vendor_from_ │
│ cookie_or_header() │
│ API: get_current_vendor_api() │
│ │
│ 1. Check Auth header │
│ 2. Check vendor_token cookie (HTML)│
│ 3. Validate JWT │
│ 4. Block if admin │──> ❌ Error
│ 5. Verify vendor access │
│ ✅ Return User │
└────────────────────────────────────┘
Login Flow - Customer (Shop)
┌──────────┐
│ Browser │
└──────────┘
│
│ POST /api/v1/shop/auth/login
│ { email, password }
▼
┌─────────────────────────┐
│ Customer Auth Endpoint │
│ │
│ 1. Validate credentials│
│ 2. Check role = customer│
│ 3. Generate JWT │
└─────────────────────────┘
│
│ Set-Cookie: customer_token=<JWT>; Path=/shop; HttpOnly; SameSite=Lax
│ Response: { access_token, user }
▼
┌──────────┐
│ Browser │──────────────────────────────────────┐
│ │ │
│ 🍪 customer_token (Path=/shop) │
│ 💾 localStorage.access_token │
└──────────┘ │
│ │
├── Navigate to /shop/account/dashboard ─────┤
│ (Cookie sent automatically) │
│ │
└── API call to /api/v1/shop/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/* /vendor/* /shop/* /api/* (public)
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌────────────────┐┌────────────────┐┌────────────────┐┌────────────────┐┌────────────────┐
│ Check for: ││ Check for: ││ Check for: ││ Check for: ││ No Auth │
│ - admin_token ││ - vendor_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 vendor ││ customer ││ (depends on │
│ ││ access ││ ││ endpoint) │
└────────┬───────┘└────────┬───────┘└────────┬───────┘└────────┬───────┘
│ │ │ │
▼ ▼ ▼ ▼
✅ Allowed ✅ Allowed ✅ Allowed ✅ Allowed
Cross-Context Prevention
❌ What's Blocked
Admin trying to access vendor route:
┌──────────────────────────────────────────┐
│ User: admin@example.com (role: admin) │
│ Token: Valid JWT with admin role │
│ Request: GET /vendor/ACME/dashboard │
└──────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ get_current_vendor_ │
│ from_cookie_or_header │
└───────────┬───────────┘
│
▼
Check: role == "admin"?
│
▼ Yes
❌ InsufficientPermissionsException
"Vendor access only - admins cannot use vendor portal"
Vendor trying to access admin route:
┌──────────────────────────────────────────┐
│ User: vendor@acme.com (role: vendor) │
│ Token: Valid JWT with vendor role │
│ Request: GET /admin/dashboard │
└──────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ get_current_admin_ │
│ from_cookie_or_header │
└───────────┬───────────┘
│
▼
Check: role == "admin"?
│
▼ No
❌ AdminRequiredException
"Admin privileges required"
Admin cookie sent to vendor route:
┌──────────────────────────────────────────┐
│ Cookie: admin_token=<JWT> (Path=/admin) │
│ Request: GET /vendor/ACME/dashboard │
└──────────────────────────────────────────┘
│
▼
Browser checks cookie path
│
▼
Path /vendor does NOT match /admin
│
▼
❌ Cookie NOT sent
Request has no authentication
│
▼
❌ InvalidTokenException
"Vendor 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 shop route (allowed):
┌──────────────────────────────────────────┐
│ Cookie: customer_token=<JWT> (Path=/shop)│
│ Request: GET /shop/account/orders │
└──────────────────────────────────────────┘
│
▼
Browser checks cookie path
│
▼
Path /shop matches /shop
│
▼
✅ 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, vendor_token, or customer_token
│ • Value: JWT
│ • Path: /admin, /vendor, or /shop (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
- Cookie Path Isolation = Three separate cookies (admin_token, vendor_token, customer_token) with path-based isolation
- Role Checking = Strict role validation at each boundary (admin, vendor, customer)
- Dual Auth Support = Cookies for HTML pages, headers for API endpoints
- Security First = HttpOnly, Secure, SameSite protection on all cookies
- Clear Boundaries = Each context (admin/vendor/shop) is completely isolated
- Three User Types = Admins manage platform, vendors manage stores, customers shop