archetecture security fix

memory/MEMORY.md

@@ -0,0 +1,3 @@
+# Memory Index
+
+- [Auth Architecture](project_auth_architecture.md) — Multi-app auth: employee JWT + Clerk + admin JWT, unified login page in dashboard app

memory/project_auth_architecture.md

@@ -0,0 +1,27 @@
+---
+name: Auth Architecture
+description: Multi-app auth system with unified login - employee JWT + Clerk + admin JWT
+type: 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.