121 lines
6.0 KiB
Markdown
121 lines
6.0 KiB
Markdown
# Login Authentication Design (Next.js, PostgreSQL, Brevo SMTP)
|
||
|
||
## 1. Overview & Tech Stack
|
||
| Component | Technology | Reason |
|
||
|-----------|------------|--------|
|
||
| Frontend / SSR | Next.js 13 (App Router) | File‑based routing, SSR/SSG, built‑in API routes |
|
||
| Database | PostgreSQL (self‑hosted, EU datacenter) | ACID, at‑rest encryption, works with Prisma |
|
||
| ORM | Prisma 2 | Type‑safe queries, easy migrations |
|
||
| Password hashing | bcrypt (cost = 12) | Industry‑standard, slow enough to deter brute‑force |
|
||
| Tokens | JWT (HS256) | Access token ~15 min, Refresh token ~7 days |
|
||
| Session cookies | HttpOnly + Secure + SameSite=Lax (chosen by user) | XSS/CSRF protection |
|
||
| Email service | Brevo SMTP | GDPR‑compatible, simple configuration |
|
||
| Deployment | Vercel (server‑less API routes) | Automatic builds, EU region, zero‑config |
|
||
| Testing | Jest + React Testing Library, Supertest for API | Unit & integration coverage |
|
||
|
||
## 2. Database Schema (Prisma)
|
||
```prisma
|
||
model User {
|
||
id String @id @default(cuid())
|
||
email String @unique
|
||
passwordHash String
|
||
role Role @default(USER)
|
||
emailVerified Boolean @default(false)
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
|
||
verificationTokens VerificationToken[]
|
||
passwordResetTokens PasswordResetToken[]
|
||
}
|
||
|
||
model VerificationToken {
|
||
id String @id @default(cuid())
|
||
token String @unique
|
||
expiresAt DateTime
|
||
userId String
|
||
user User @relation(fields: [userId], references: [id])
|
||
createdAt DateTime @default(now())
|
||
}
|
||
|
||
model PasswordResetToken {
|
||
id String @id @default(cuid())
|
||
token String @unique
|
||
expiresAt DateTime
|
||
used Boolean @default(false)
|
||
userId String
|
||
user User @relation(fields: [userId], references: [id])
|
||
createdAt DateTime @default(now())
|
||
}
|
||
|
||
enum Role {
|
||
ADMIN
|
||
USER
|
||
}
|
||
```
|
||
|
||
## 3. API Routes (Next.js `/pages/api/...`)
|
||
| Route | Method | Purpose | Input | Output |
|
||
|------|--------|---------|-------|--------|
|
||
| `/api/auth/register` | POST | Create user, hash password, send verification mail | `{ email, password }` | 201 Created, message "Verification mail sent" |
|
||
| `/api/auth/verify-email` | GET | Validate verification token, set `emailVerified` | `?token=` | 200 OK, "Email verified" |
|
||
| `/api/auth/login` | POST | Check credentials, issue access & refresh JWT, set cookies | `{ email, password, rememberMe? }` | 200 OK, cookies set |
|
||
| `/api/auth/logout` | POST | Clear cookies, optionally blacklist refresh token | – | 200 OK |
|
||
| `/api/auth/refresh-token` | POST | Verify refresh JWT, issue new access JWT (rotate refresh if >2 days) | – (refresh cookie) | 200 OK, new cookies |
|
||
| `/api/auth/request-password-reset` | POST | Create reset token, send mail | `{ email }` | 200 OK, message "Mail sent" |
|
||
| `/api/auth/reset-password` | POST | Validate reset token, store new bcrypt hash, invalidate token | `{ token, newPassword }` | 200 OK |
|
||
| `/api/auth/me` | GET | Return current user data (no password) | – | 200 OK, `{ email, role, emailVerified }` |
|
||
|
||
All endpoints enforce `Content-Type: application/json` and `Cache-Control: no-store`.
|
||
|
||
## 4. Email Workflow (Brevo SMTP)
|
||
1. Registration creates a `VerificationToken` (UUID + HMAC) stored with an expiry (24 h).
|
||
2. Email template (HTML + text) contains a link:
|
||
`https://<your‑app>.vercel.app/api/auth/verify-email?token=<<token>>`
|
||
3. The verification endpoint validates the token, marks the user as verified and deletes the token.
|
||
4. Password‑reset works analogously with a one‑hour token and a `used` flag.
|
||
|
||
SMTP credentials (`BREVO_SMTP_HOST`, `BREVO_SMTP_USER`, `BREVO_SMTP_PASS`) are stored as Vercel environment variables.
|
||
|
||
## 5. Session & Cookie Settings
|
||
| Cookie | Content | Max Age | SameSite | Secure | HttpOnly |
|
||
|--------|---------|---------|----------|--------|----------|
|
||
| `accessToken` | JWT (`sub`, `role`, `exp`) | 15 min | Lax (as requested) | true | true |
|
||
| `refreshToken` | JWT (`sub`, `exp`) | 7 days (user chose "remember me") | Lax | true | true |
|
||
|
||
Refresh token is only set when the front‑end sends `rememberMe: true`.
|
||
|
||
## 6. Role & Permission System
|
||
- `requireAuth` middleware validates the access token and attaches `req.user`.
|
||
- `requireRole('ADMIN')` middleware checks `req.user.role`.
|
||
- Roles are stored in the `role` column of `User` and encoded into the JWT payload.
|
||
|
||
## 7. GDPR & Data‑Minimisation
|
||
| Measure | Implementation |
|
||
|---------|----------------|
|
||
| Minimal data | Store only email, hashed password, role, verification flag. |
|
||
| Consent | Registration form includes a mandatory "I accept the privacy policy" checkbox. |
|
||
| Right to be forgotten | `DELETE /api/users/me` removes the user row and all related tokens. |
|
||
| Data retention | Verification and reset tokens have explicit `expiresAt`; nightly Prisma job deletes expired rows. |
|
||
| Transport security | All traffic forced via HTTPS (Vercel provides TLS). |
|
||
| At‑rest encryption | PostgreSQL instance encrypted by the managed provider (EU region). |
|
||
| Audit log | Optional `AuditLog` table with pseudonymised entries, retained 30 days. |
|
||
|
||
## 8. Deployment Pipeline (Vercel)
|
||
1. Connect the GitHub repo to Vercel.
|
||
2. Vercel runs `npm install && npm run build && npm test` on each push.
|
||
3. Preview deployments for PRs (`pr‑<num>--<repo>.vercel.app`).
|
||
4. Production deploy on merge to `main` (`https://<app>.vercel.app`).
|
||
5. Environment variables (`DATABASE_URL`, `NEXTAUTH_SECRET`, Brevo SMTP creds) are configured in Vercel > Settings > Environment Variables – same values for Preview and Production.
|
||
|
||
## 9. Security Checklist
|
||
- ✅ bcrypt cost = 12
|
||
- ✅ HttpOnly + Secure + SameSite Lax cookies
|
||
- ✅ Refresh‑token rotation on each refresh
|
||
- ✅ Rate limiting on `/login` and `/request-password-reset`
|
||
- ✅ CSP, X‑Content‑Type‑Options, Referrer‑Policy headers via `next.config.js`
|
||
- ✅ Helmet‑like security headers
|
||
- ✅ Regular dependency audit (`npm audit`) and CI fail on high severity issues
|
||
|
||
---
|
||
*This spec is ready for review. Once approved, the next step will be to create a detailed implementation plan.*
|