carmanagement/memory/project_auth_architecture.md

name, description, type

name	description	type
Auth Architecture	Multi-app auth system with unified login - employee JWT + Clerk + admin JWT	project

Three-tier SaaS auth system (RentalDriveGo car management monorepo):

1. Admins — JWT auth (type: 'admin') issued into the HttpOnly admin_session cookie in the admin app (port 3002)
2. Employees (Owner/Manager/Agent) — Clerk OAuth when configured, local JWT (type: 'employee') when Clerk is not configured. The API stores the session in the HttpOnly employee_session cookie; browser code may cache profile/preferences, but not auth tokens.
3. Renters — JWT infrastructure exists but login is currently disabled (returns 403)

Unified login page: apps/dashboard/src/app/sign-in/[[...sign-in]]/page.tsx

• Shows Clerk component when NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is a real key
• Otherwise shows local form that tries employee login, then admin login
• Admin users are redirected after the API sets admin_session; URL-fragment token handoff is legacy and should not return

Key API endpoints:

• POST /api/v1/auth/employee/login — local employee auth (email + password → HttpOnly session cookie)
• POST /api/v1/admin/auth/login — admin auth (email + password + TOTP or recovery code when enabled → HttpOnly session cookie)
• POST /api/v1/auth/company/signup — company signup (accepts optional password field)

requireCompanyAuth middleware — accepts the employee_session HttpOnly cookie, and still supports trusted Bearer tokens for server/mobile/integration contexts.

Why: Clerk keys were placeholder values (pk_test_your_real_publishable_key_here), making the login page non-functional. Added local JWT auth as a fully working fallback.

How to apply: When working on auth or protected routes, check if Clerk is actually configured (real keys) vs local JWT mode. The clerkFrontendEnabled/clerkBackendEnabled flags in apps/dashboard/src/lib/clerk.ts detect this.