orion/docs/development/customer-auth-summary.md

Customer Authentication - Quick Summary

Date: 2025-11-24 Full Documentation: customer-authentication-implementation.md

What Was Implemented

✅ Customer login, registration, and forgot password pages ✅ Customer dashboard with account overview ✅ Complete customer authentication system separate from admin/store ✅ Multi-access routing support (domain, subdomain, path-based) ✅ Secure cookie management with proper path restrictions ✅ Theme integration and responsive design ✅ Custom logout confirmation modal (Tailwind CSS + Alpine.js)

Key Files

Created

• app/templates/storefront/account/login.html
• app/templates/storefront/account/register.html
• app/templates/storefront/account/forgot-password.html
• app/templates/storefront/account/dashboard.html

Modified

• app/api/v1/storefront/auth.py - Dynamic cookie paths
• app/api/deps.py - Customer authentication dependency
• app/services/customer_service.py - Direct JWT token creation
• app/routes/storefront_pages.py - Customer type hints
• middleware/store_context.py - Harmonized detection methods

Critical Architecture Decision

Customers ≠ Users

• Users (admin/store): Have role, username, managed by auth_service
• Customers: Store-scoped, have customer_number, managed by customer_service

JWT tokens have type: "customer" to distinguish them.

Cookie Path Logic

# Domain/Subdomain access
cookie_path = "/storefront"

# Path-based access (/storefront/orion)
cookie_path = f"/storefront/{store_code}"

Authentication Flow

1. Login → Create JWT with type: "customer"
2. Set cookie with store-aware path
3. Dashboard request → Cookie sent (path matches!)
4. Dependency decodes JWT, validates type, loads Customer
5. Render dashboard with customer data

Logout Flow

1. User clicks "Logout" button → Custom Tailwind modal appears
2. User confirms → API call to /api/v1/storefront/auth/logout
3. Cookie deleted, localStorage cleared
4. Success toast shown, redirect to login page

Note: Uses custom modal instead of browser's confirm() for better UX and styling consistency.

Testing URLs

# Path-based access
http://localhost:8000/storefront/orion/account/login
http://localhost:8000/storefront/orion/account/register
http://localhost:8000/storefront/orion/account/dashboard

Next Steps (TODO)

• Implement password reset functionality
• Add email verification
• Build account management pages (orders, profile, addresses)
• Add refresh tokens for longer sessions
• Implement rate limiting on auth endpoints