sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update authentication dependency names across documentation

Browse Source 
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>
This commit is contained in:
Samir Boulahtit
2025-11-22 18:21:23 +01:00
parent 7a9c12dcdf
commit 0d7915c275
9 changed files with 213 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

269
docs/api/authentication-flow-diagrams.md
View File

@@ -3,30 +3,33 @@
## Cookie Isolation Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Browser │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Admin Area │ │ Vendor Area │ │
│ │ /admin/* │ │ /vendor/* │ │
│ │ │ │ │ │
│ │ 🍪 admin_token │ │ 🍪 vendor_token │ │
│ │ Path: /admin │ │ Path: /vendor │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │ │ │
│ ├───────────────────────────┤ │
│ │ ❌ No Cookie Mixing │ │
│ │ │ │
└───────────┼───────────────────────────┼──────────────────────┘
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ Admin Backend │ │ Vendor Backend │
│ /admin/* │ │ /vendor/* │
│ │ │ │
│ ✅ admin_token │ │ ✅ vendor_token │
│ ❌ vendor_token │ │ ❌ admin_token │
└───────────────────────┘ └───────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ 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
@@ -63,15 +66,17 @@
└── API call to /api/v1/admin/vendors ───────┤
(Authorization: Bearer <token>) │
│
┌──────────────▼──────────────┐
│ get_current_admin_user() │
│ │
│ 1. Check Auth header │
│ 2. Check admin_token cookie │
│ 3. Validate JWT │
│ 4. Verify role == admin │
│ ✅ Return User │
└──────────────────────────────┘
┌────────────────────────────────────────┐
│ 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
@@ -109,54 +114,104 @@
└── API call to /api/v1/vendor/ACME/products ┤
(Authorization: Bearer <token>) │
│
┌──────────────▼──────────────┐
│ get_current_vendor_user() │
│ │
│ 1. Check Auth header │
│ 2. Check vendor_token cookie│
│ 3. Validate JWT │
┌────────────────────────────────────────┐
│ 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 │
└──────────────────────────────┘
│ 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
/admin/* /vendor/* /api/*
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Check for: │ │ Check for: │ │ Check for: │
│ - admin_token │ │ - vendor_token │ │ - Authorization │
│ cookie │ │ cookie │ │ header │
│ - OR Auth header │ │ - OR Auth header │ │ (required) │
└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Validate: │ │ Validate: │ │ Validate: │
│ - JWT valid │ │ - JWT valid │ │ - JWT valid │
│ - User active │ │ - User active │ │ - User active │
│ - Role = admin │ │ - Role != admin │ │ - Any role │
│ │ │ - Has vendor │ │ (depends on │
│ │ │ access │ │ endpoint) │
└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
│ │ │
▼ ▼ ▼
✅ Allowed ✅ Allowed ✅ Allowed
┌─────────────────────┐
│ 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
@@ -229,6 +284,55 @@ Admin cookie sent to vendor route:
"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
```
@@ -236,9 +340,9 @@ LOGIN
│
├── Server generates JWT
├── Server sets cookie:
│ • Name: admin_token or vendor_token
│ • Name: admin_token, vendor_token, or customer_token
│ • Value: JWT
│ • Path: /admin or /vendor
│ • Path: /admin, /vendor, or /shop (context-specific)
│ • HttpOnly: true
│ • Secure: true (production)
│ • SameSite: Lax
@@ -278,8 +382,9 @@ LOGOUT
## Key Takeaways
1. **Cookie Path Isolation** = No cross-context cookies
2. **Role Checking** = Admins blocked from vendor routes
3. **Dual Auth Support** = Cookies for pages, headers for API
4. **Security First** = HttpOnly, Secure, SameSite protection
5. **Clear Boundaries** = Each context is completely isolated
1. **Cookie Path Isolation** = Three separate cookies (admin_token, vendor_token, customer_token) with path-based isolation
2. **Role Checking** = Strict role validation at each boundary (admin, vendor, 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/vendor/shop) is completely isolated
6. **Three User Types** = Admins manage platform, vendors manage stores, customers shop