skillguard/.agents/memory/custom-jwt-auth.md
amertensreplit 441c828a17 Replace Clerk with custom email+password authentication
Task: Replace Clerk (Replit-managed) with a standalone JWT/cookie-based auth system.

## What changed

### Backend (api-server)
- Added `admin_users` table (lib/db/src/schema/adminUsers.ts) with id, email (unique), password_hash, created_at; pushed to DB with drizzle-kit push
- Replaced `resolveAuth`/`requireAdmin` in auth.ts middleware: now reads a signed HS256 JWT from the `session` httpOnly cookie (via `jose`) instead of Clerk tokens
- Added `POST /api/auth/login` (bcrypt password check → sets httpOnly cookie), `POST /api/auth/logout` (clears cookie), `GET /api/me` (unchanged contract)
- Added `seedAdminUser()` in lib/seedAdmin.ts: on startup, if no admin exists, creates one from ADMIN_EMAIL + ADMIN_PASSWORD env vars (bcrypt-hashed)
- Removed all Clerk imports from app.ts: clerkMiddleware, publishableKeyFromHost, clerkProxyMiddleware deleted
- Deleted clerkProxyMiddleware.ts entirely
- Added cookie-parser middleware to app.ts
- Removed @clerk/express, @clerk/shared from package.json; added jose, bcryptjs, @types/bcryptjs

### Frontend (skillguard)
- Removed ClerkProvider, SignIn, SignUp, ClerkQueryClientCacheInvalidator from App.tsx; replaced with plain wouter routes
- Replaced /sign-in and /sign-up routes with a single /sign-in route pointing to new LoginPage
- New LoginPage (src/pages/login.tsx): email+password form using shadcn Input/Button/Card, calls POST /api/auth/login, redirects to /admin on success
- layout.tsx: replaced useClerk/useUser with useGetMe() + fetch POST /api/auth/logout
- require-admin.tsx: unchanged logic (already used useGetMe()), updated comment
- Removed @clerk/react, @clerk/localizations, @clerk/themes from package.json
- Added signInButton + loginError i18n keys to all 3 locales (de/en/es)

## New secrets required
- SESSION_SECRET (already existed)
- ADMIN_EMAIL (new — first admin email)
- ADMIN_PASSWORD (new — first admin password, stored as bcrypt hash)

## Removed env vars
- CLERK_SECRET_KEY, CLERK_PUBLISHABLE_KEY, VITE_CLERK_PUBLISHABLE_KEY, VITE_CLERK_PROXY_URL (can be deleted from secrets)

## Test results
All 79 tests pass.

Replit-Task-Id: 41d32d48-8f20-44bc-b665-a2becb83e503
2026-06-16 21:22:55 +00:00

20 lines
1.1 KiB
Markdown

---
name: Custom JWT cookie auth
description: How SkillGuard's custom email+password authentication works after replacing Clerk.
---
# Custom JWT Cookie Auth
Clerk was replaced with a standalone auth system.
**Rule:** Use `jose` (HS256) for JWT signing/verification. The token lives in an httpOnly `session` cookie. `SESSION_SECRET` env var must be set.
**Why:** Removed Clerk dependency for self-contained auth with no external service or Replit binding.
**How to apply:**
- `artifacts/api-server/src/middlewares/auth.ts``resolveAuth()` reads the cookie; `signToken()` creates JWTs
- `artifacts/api-server/src/routes/auth.ts``POST /api/auth/login` (bcrypt check → set cookie), `POST /api/auth/logout` (clear cookie), `GET /api/me`
- `lib/db/src/schema/adminUsers.ts``admin_users` table with email (unique) + password_hash
- `artifacts/api-server/src/lib/seedAdmin.ts` — seeds one admin from `ADMIN_EMAIL`+`ADMIN_PASSWORD` on startup if table is empty
- Cookie is `sameSite: lax`, `secure: true` in production, `httpOnly: true`, 30-day expiry
- All authenticated users in the cookie are considered admins (no separate role check needed)