340 lines
14 KiB
Markdown
340 lines
14 KiB
Markdown
# Sub-project A — Authentication & Roles
|
|
|
|
**Datum:** 2026-05-20
|
|
**Status:** Draft, ready for review
|
|
**Parent app:** Flashcard webapplicatie (zie `2026-05-20-flashcard-app-design.md`)
|
|
**Scope:** Eerste van drie subprojecten in de multi-user uitbreiding (A→B→C).
|
|
|
|
---
|
|
|
|
## 1. Doel
|
|
|
|
De applicatie achter een login zetten en een systeembeheerder-rol introduceren. Lessen, kaarten, sessies en statistieken blijven in deze fase ongewijzigd qua eigenaarschap — dat komt in sub-project B. Sub-project A levert:
|
|
|
|
- Self-service registratie + admin-invites
|
|
- E-mailverificatie verplicht voor login
|
|
- Wachtwoord-reset
|
|
- Profielbeheer (naam, email, wachtwoord)
|
|
- Sysadmin-rol met gebruikersbeheer
|
|
- Alle bestaande endpoints achter `requireAuth`
|
|
|
|
## 2. Uitgangspunten
|
|
|
|
- **Single-source-of-truth blijft SQLite (better-sqlite3).** Drizzle wordt uitgebreid met `users`, `sessions_auth`, `auth_tokens`.
|
|
- **Schone start:** bij introductie wordt de bestaande database gewist en opnieuw gemigreerd; geen migratiepad nodig voor bestaande lessen/kaarten/sessies (die hebben nog geen eigenaar).
|
|
- **Eerste registratie** wordt automatisch sysadmin. Daarna ook open self-service, maar nieuwe accounts hebben rol `user`.
|
|
- **Geen 2FA**, geen social login, geen audit log (v1).
|
|
- Alle authentication state is **server-side** via DB-backed sessions + HttpOnly cookies. Geen JWT.
|
|
|
|
## 3. Functionele eisen
|
|
|
|
### 3.1 Self-service registratie
|
|
|
|
- `/register` accepteert `email` (uniek, normaliseerd lowercase), `displayName`, `password` (min 8 chars).
|
|
- Systeem maakt user-row met `password_hash`, `email_verified_at = null`, `is_active = true`.
|
|
- Als er nog geen users zijn: rol = `sysadmin`. Anders rol = `user`.
|
|
- Verificatie-token wordt gegenereerd en per e-mail verzonden.
|
|
- Login is geblokkeerd tot `email_verified_at` is gezet.
|
|
|
|
### 3.2 Email verificatie
|
|
|
|
- `/verify-email?token=…` accepteert het token.
|
|
- Token is single-use, geldig 24 uur.
|
|
- Bij succes: `email_verified_at = now()`; token wordt gemarkeerd als gebruikt.
|
|
- "Resend verification" beschikbaar vanaf de login-pagina als de gebruiker probeert in te loggen zonder verificatie.
|
|
|
|
### 3.3 Login / logout
|
|
|
|
- `/login` accepteert `email` + `password`.
|
|
- Bij succes: server maakt `sessions_auth` row + zet `flashcard_sid` cookie (HttpOnly, SameSite=Lax, Secure in prod). 30 dagen geldig met rolling `last_used_at` update.
|
|
- Bij ontbrekende verificatie: 403 met code `EMAIL_NOT_VERIFIED`.
|
|
- Bij `is_active = false`: 403 met code `ACCOUNT_DISABLED`.
|
|
- `/logout` invalidatert de sessie in de DB en wist de cookie.
|
|
|
|
### 3.4 Wachtwoord vergeten / resetten
|
|
|
|
- `/forgot-password` accepteert `email`. Response is **altijd** `200 OK` met generieke melding (geen account-enumeration).
|
|
- Als de user bestaat én actief is: reset-token aanmaken, mail sturen.
|
|
- Token TTL: 1 uur. Single-use.
|
|
- `/reset-password?token=…&password=…` zet nieuw `password_hash` en markeert token gebruikt. Alle bestaande `sessions_auth` van de user worden geïnvalideerd (alle apparaten uitloggen).
|
|
|
|
### 3.5 Profiel
|
|
|
|
- `GET /api/auth/me` retourneert huidige user (zonder hash).
|
|
- `PATCH /api/auth/profile` met `{ displayName?, email? }`. E-mail wijzigen vereist verificatie van het nieuwe adres (token + mail naar nieuwe adres; `email_verified_at` blijft op oud adres tot bevestiging — eenvoudigste flow: zet `pending_email` veld en wissel pas bij verificatie).
|
|
- `POST /api/auth/change-password` met `{ currentPassword, newPassword }`. Bij succes: invalideer alle andere sessies behalve de huidige.
|
|
|
|
### 3.6 Invite door admin
|
|
|
|
- Admin gaat naar `/admin/users`, kiest "Uitnodigen", vult `email` + `role` in.
|
|
- Systeem maakt user-row met `password_hash = null`, `email_verified_at = null`, `is_active = true`, en genereert een invite-token (TTL 24u, mailtype `invite`).
|
|
- E-mail verstuurt naar het opgegeven adres met link naar `/accept-invite?token=…`.
|
|
- Acceptatie: gebruiker vult `displayName` + `password` in. Bij succes: `password_hash` gezet, `email_verified_at = now()`, token gebruikt. Gebruiker wordt automatisch ingelogd.
|
|
- Admin kan een open invite intrekken (DELETE op user die nog geen `password_hash` heeft).
|
|
|
|
### 3.7 Sysadmin: gebruikersbeheer
|
|
|
|
- `GET /api/admin/users` met query `?q=` (zoeken op email/displayName), `?role=`, `?active=`, paginatie.
|
|
- `PATCH /api/admin/users/:id` met `{ role?, isActive?, displayName? }`. Sysadmin kan rollen wijzigen, accounts (de)activeren, naam corrigeren.
|
|
- `POST /api/admin/users/:id/send-reset` triggert een reset-mail.
|
|
- Sysadmin kan niet zichzelf op `is_active=false` zetten of zijn eigen rol verlagen tenzij er minstens één andere actieve sysadmin is. Dit voorkomt lock-out.
|
|
|
|
### 3.8 Rate limiting
|
|
|
|
- `express-rate-limit` (in-memory, per IP):
|
|
- `/login` — 10 per 15 min
|
|
- `/register` — 5 per 15 min
|
|
- `/forgot-password` — 5 per 15 min
|
|
- `/verify-email`, `/reset-password`, `/accept-invite` — 20 per 15 min (genoeg voor user die per ongeluk dubbelklikt)
|
|
- Headers `RateLimit-*` worden meegestuurd voor zichtbaarheid.
|
|
|
|
### 3.9 CSRF
|
|
|
|
- Double-submit cookie pattern:
|
|
- Bij login wordt naast `flashcard_sid` ook een `flashcard_csrf` cookie gezet (zelfde TTL, niet HttpOnly).
|
|
- Mutatie-endpoints (POST/PATCH/DELETE) eisen header `X-CSRF-Token` met dezelfde waarde.
|
|
- SameSite=Lax dekt het meeste; CSRF-token is extra defense-in-depth.
|
|
- API client haalt de waarde uit de cookie en stuurt hem standaard mee.
|
|
|
|
## 4. Datamodel (Drizzle / SQLite)
|
|
|
|
```ts
|
|
users {
|
|
id: integer pk autoIncrement
|
|
email: text not null unique // lowercase, normalized
|
|
display_name: text not null
|
|
password_hash: text // nullable: invite-pending users hebben nog geen hash
|
|
role: text ('user' | 'sysadmin') not null default 'user'
|
|
is_active: integer (boolean) not null default true
|
|
email_verified_at: integer (unix sec)
|
|
pending_email: text // nullable; gebruikt bij email-wijziging
|
|
created_at: integer not null default unixepoch()
|
|
updated_at: integer not null default unixepoch()
|
|
}
|
|
|
|
sessions_auth {
|
|
id: text pk // 32-byte hex random
|
|
user_id: integer fk → users.id on delete cascade not null
|
|
created_at: integer not null default unixepoch()
|
|
expires_at: integer not null
|
|
last_used_at: integer not null
|
|
user_agent: text
|
|
ip: text
|
|
}
|
|
INDEX sessions_auth (user_id), (expires_at)
|
|
|
|
auth_tokens {
|
|
id: integer pk autoIncrement
|
|
user_id: integer fk → users.id on delete cascade not null
|
|
token_hash: text not null // sha256 hex
|
|
purpose: text ('verify_email' | 'password_reset' | 'invite' | 'change_email') not null
|
|
payload: text // bv. nieuw email-adres bij change_email
|
|
expires_at: integer not null
|
|
used_at: integer
|
|
created_at: integer not null default unixepoch()
|
|
}
|
|
INDEX auth_tokens (token_hash), (user_id, purpose)
|
|
```
|
|
|
|
## 5. Backend architectuur
|
|
|
|
### 5.1 Bibliotheken (toevoegingen)
|
|
|
|
| Lib | Reden |
|
|
|---|---|
|
|
| `bcryptjs` | Password hashing, geen native build deps |
|
|
| `nodemailer` | SMTP transport (Mailpit dev, SES prod) |
|
|
| `cookie-parser` | Cookies parsen in express middleware |
|
|
| `express-rate-limit` | Brute-force preventie |
|
|
|
|
### 5.2 Mappenstructuur
|
|
|
|
```
|
|
packages/backend/src/
|
|
services/
|
|
auth/
|
|
passwords.ts # hash, verify
|
|
tokens.ts # random, sha256, lookup, mark-used
|
|
sessions.ts # create, validate, invalidate, rolling-refresh
|
|
email.ts # nodemailer transport + send helpers
|
|
templates.ts # html strings: verify, reset, invite, change-email
|
|
users.ts # CRUD voor admin user-management
|
|
middleware/
|
|
auth.ts # requireAuth, requireRole, currentUserOrNull
|
|
csrf.ts # ensureCsrfToken, verifyCsrf
|
|
rate-limit.ts # named limiters
|
|
routes/
|
|
auth.ts # register, login, logout, verify, forgot, reset, profile, change-pw, accept-invite, me
|
|
admin-users.ts # sysadmin user management
|
|
lib/
|
|
cookies.ts # naming + options helpers (sid + csrf)
|
|
```
|
|
|
|
### 5.3 Configuratie (env-vars)
|
|
|
|
```
|
|
DB_PATH=./data/flashcard.db
|
|
PORT=3000
|
|
SESSION_SECRET=<32-byte hex> # NOTE: ook met server-side sessions houden we een secret aan voor toekomstige uitbreiding (signed cookies)
|
|
COOKIE_SECURE=true # false in dev
|
|
COOKIE_DOMAIN= # leeg = host-only
|
|
APP_URL=http://localhost:5173 # gebruikt in mailtemplates
|
|
SMTP_HOST=localhost
|
|
SMTP_PORT=1025
|
|
SMTP_USER=
|
|
SMTP_PASS=
|
|
SMTP_FROM="Flashcard <noreply@example.com>"
|
|
```
|
|
|
|
### 5.4 Middleware-volgorde
|
|
|
|
```
|
|
1. cookie-parser
|
|
2. body-parser (express.json)
|
|
3. csrf.ensureCsrfToken (zet cookie bij eerste GET)
|
|
4. auth.currentUserOrNull (alleen leest; geen redirect)
|
|
5. routes
|
|
- /api/auth/* public except /logout (requireAuth)
|
|
- /api/admin/* requireAuth + requireRole('sysadmin') + verifyCsrf op mutaties
|
|
- /api/lessons|cards|sessions|stats/* requireAuth + verifyCsrf op mutaties
|
|
6. error handler
|
|
```
|
|
|
|
### 5.5 Bootstrap van eerste sysadmin
|
|
|
|
Geen aparte bootstrap-script. De allereerste `POST /api/auth/register` op een lege users-tabel krijgt automatisch `role='sysadmin'`. Wel: verificatie-email moet alsnog bevestigd worden. Voor het oplossen van "geen sysadmin meer" bestaat een CLI-script `npm -w @flashcard/backend run promote -- <email>` (klein, optioneel).
|
|
|
|
## 6. Frontend
|
|
|
|
### 6.1 Nieuwe routes
|
|
|
|
| Route | Pagina | Toegang |
|
|
|---|---|---|
|
|
| `/login` | LoginPage | publiek |
|
|
| `/register` | RegisterPage | publiek |
|
|
| `/verify-email` | VerifyEmailPage (leest `?token=` uit URL) | publiek |
|
|
| `/forgot-password` | ForgotPasswordPage | publiek |
|
|
| `/reset-password` | ResetPasswordPage (`?token=`) | publiek |
|
|
| `/accept-invite` | AcceptInvitePage (`?token=`) | publiek |
|
|
| `/profile` | ProfilePage | auth |
|
|
| `/admin/users` | AdminUsersPage | sysadmin |
|
|
|
|
### 6.2 Bestaande routes
|
|
|
|
Alle bestaande routes (dashboard, admin/lessons, practice, stats, settings) staan achter een nieuwe `<AuthBoundary>` wrapper. Niet ingelogd → redirect naar `/login?next=<originele path>`. Sysadmin-only routes worden bewaakt door `<RoleGuard role="sysadmin">`.
|
|
|
|
### 6.3 Layout-uitbreidingen
|
|
|
|
- **User menu** rechtsboven (initialen-avatar). Dropdown bevat:
|
|
- Naam + email (read-only)
|
|
- "Profiel" link
|
|
- "Systeembeheer" (alleen voor sysadmin)
|
|
- "Uitloggen"
|
|
- Sysadmin krijgt extra link "👑 Systeem" in de top-nav.
|
|
|
|
### 6.4 Stores (Zustand)
|
|
|
|
Nieuwe `authStore`:
|
|
- `user: User | null`
|
|
- `csrfToken: string | null`
|
|
- `loading: boolean`
|
|
- `hydrate()` — eenmalig bij app-boot: `GET /api/auth/me`
|
|
- `login(email, password)` / `logout()` / `register(...)`
|
|
- `refreshMe()`
|
|
|
|
API-client wordt aangepast om bij elke mutatie de CSRF-header mee te sturen vanuit `document.cookie`.
|
|
|
|
### 6.5 UI-stijl
|
|
|
|
We blijven bij de huidige design system (brand-purple primary, success-green, glassmorphic surfaces). Auth-pagina's gebruiken de bestaande `.btn-primary`, `.input-field`, `.surface` utility classes. Geen aparte styling.
|
|
|
|
## 7. E-mailtemplates
|
|
|
|
Vier templates (HTML + plaintext):
|
|
|
|
1. **verify_email** — onderwerp "Bevestig je e-mailadres", link `${APP_URL}/verify-email?token=…`
|
|
2. **password_reset** — "Reset je wachtwoord", link `${APP_URL}/reset-password?token=…`, TTL 1u in tekst
|
|
3. **invite** — "Je bent uitgenodigd voor Flashcard", link `${APP_URL}/accept-invite?token=…`
|
|
4. **change_email_confirm** — "Bevestig je nieuwe e-mailadres", link `${APP_URL}/verify-email?token=…`
|
|
|
|
Alle templates leesbaar zonder HTML rendering (plaintext alt).
|
|
|
|
## 8. Foutafhandeling
|
|
|
|
Naast bestaande error codes:
|
|
|
|
| Code | Status | Wanneer |
|
|
|---|---|---|
|
|
| `EMAIL_TAKEN` | 409 | Registreren met bestaand e-mail |
|
|
| `EMAIL_NOT_VERIFIED` | 403 | Login zonder bevestiging |
|
|
| `ACCOUNT_DISABLED` | 403 | Login op gedeactiveerd account |
|
|
| `INVALID_CREDENTIALS` | 401 | Verkeerd wachtwoord of niet-bestaand e-mail (zelfde generieke message naar buiten) |
|
|
| `INVALID_TOKEN` | 400 | Verlopen of onbestaand token (verify/reset/invite) |
|
|
| `RATE_LIMITED` | 429 | Rate limit overschreden |
|
|
| `CSRF_MISMATCH` | 403 | CSRF-token ontbreekt of klopt niet |
|
|
| `LAST_SYSADMIN` | 409 | Poging zichzelf te verlagen/deactiveren als enige sysadmin |
|
|
|
|
## 9. Test-strategie
|
|
|
|
### 9.1 Backend unit (Vitest)
|
|
|
|
- `passwords.ts`: hash + verify roundtrip; verkeerde hash faalt
|
|
- `tokens.ts`: generate, lookup, used/expired afgewezen, single-use
|
|
- `sessions.ts`: create, validate, expired, rolling-refresh, invalidate
|
|
- `email.ts`: stub transport, assert template + recipient
|
|
|
|
### 9.2 Backend integration (Vitest + supertest)
|
|
|
|
Volledige flows met in-memory DB en mail-stub:
|
|
|
|
- register → verify → login → /me
|
|
- register → login zonder verify → 403
|
|
- forgot → reset → login met nieuw wachtwoord
|
|
- invite → accept-invite → login
|
|
- admin invite + admin send-reset
|
|
- admin promote/demote user
|
|
- last-sysadmin guard
|
|
- rate limit triggert na N pogingen
|
|
|
|
### 9.3 E2E (Playwright, Mailpit-gebaseerd)
|
|
|
|
- **Registreer**: vul form in, lees verificatielink uit Mailpit HTTP API, klik, log in, zie dashboard
|
|
- **Forgot password**: vul email in, lees mail, reset, log in met nieuw wachtwoord
|
|
- **Admin invite**: log in als sysadmin, nodig user uit, lees mail, accepteer, log in als nieuwe user
|
|
|
|
Mailpit draait in dev in docker-compose; tests hebben aparte port (1026/8026) of gebruiken dev-mailpit.
|
|
|
|
## 10. Deployment / dev setup
|
|
|
|
### 10.1 docker-compose voor Mailpit (dev)
|
|
|
|
Nieuwe `docker-compose.yml` in repo-root:
|
|
|
|
```yaml
|
|
services:
|
|
mailpit:
|
|
image: axllent/mailpit:latest
|
|
ports:
|
|
- "1025:1025" # SMTP
|
|
- "8025:8025" # web UI
|
|
restart: unless-stopped
|
|
```
|
|
|
|
Niet verplicht (auth werkt ook zonder, het is een SMTP-server), maar `npm run dev` gaat aanvragen dat Mailpit draait. Of dev mailtransport faalt zacht — we kiezen voor **stub-mailer fallback**: als `SMTP_HOST` ontbreekt of onbereikbaar is, loggen we de e-mail content + link naar console.
|
|
|
|
### 10.2 Productie
|
|
|
|
In productie zet `SMTP_HOST=email-smtp.eu-west-1.amazonaws.com` (of relevante region), `SMTP_PORT=587`, `SMTP_USER`/`SMTP_PASS` = SES SMTP credentials. `COOKIE_SECURE=true`.
|
|
|
|
## 11. Out of scope (volgt in B en C)
|
|
|
|
- Ownership op lessen/kaarten/sessies (user_id, visibility)
|
|
- Marketplace / sharing
|
|
- Avatar uploads
|
|
- 2FA / TOTP
|
|
- OAuth (Google/etc.)
|
|
- Audit log
|
|
- Email-changing met dubbele confirmatie via beide mailadressen (alleen single-confirmation naar nieuw adres in v1)
|
|
- Profielfoto's
|
|
- User self-delete (alleen admin-deactivate)
|