Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/guides/eerste-installatie-en-aanmelden.md

@@ -0,0 +1,77 @@
+# Eerste installatie, aanmelden en wachtwoordherstel
+
+Deze gids beschrijft de M1-functionaliteit: de eenmalige eerste installatie, aanmelden
+en afmelden, rolbeheer en operator-herstel van een vergeten wachtwoord. Geschreven voor
+de beheerder die de installatie uitvoert.
+
+## Eerste installatie (eenmalig)
+
+Wanneer de toepassing voor het eerst opstart, bestaat er nog geen beheerdersaccount.
+Elke bezoeker ziet dan het installatiescherm.
+
+1. **Vul het installatieformulier in:** een naam voor de werkruimte, uw naam,
+   e-mailadres en een wachtwoord van minimaal 12 tekens.
+2. Na een geslaagde installatie bent u automatisch aangemeld als beheerder en kan het
+   installatiescherm nooit meer opnieuw gebruikt worden.
+
+Er is geen "installatie ongedaan maken"-knop in de toepassing. Dat is opzettelijk: een
+volledige nieuwe installatie vereist een operator die de database opnieuw opzet volgens
+`docs/18-backup-restore.md` (M7).
+
+## Aanmelden en afmelden
+
+- Meld aan met e-mailadres en wachtwoord op het aanmeldscherm.
+- Na 5 mislukte pogingen wordt het account tijdelijk vergrendeld (15 minuten). De
+  toepassing geeft dezelfde generieke foutmelding voor een onbekend account, een
+  verkeerd wachtwoord én een vergrendeld account, zodat een aanvaller niet kan afleiden
+  welk geval van toepassing is — behalve bij een vergrendeling, die wel expliciet als
+  "te veel pogingen" wordt gemeld zodat een legitieme gebruiker weet dat hij moet
+  wachten.
+- Een sessie duurt maximaal 12 uur, ongeacht activiteit.
+- "Afmelden" beëindigt de sessie onmiddellijk.
+
+## Gebruikers en rollen beheren
+
+Alleen een beheerder kan andere gebruikers aanmaken via `POST /api/v1/admin/users` (de
+webinterface hiervoor volgt in een latere milestone; de API is al volledig functioneel
+en getest). Beschikbare rollen:
+
+| Rol | Rechten |
+|---|---|
+| Lezer | Bekijken en zoeken van toegestane inhoud. |
+| Redacteur | Lezer-rechten plus inhoud aanmaken en bewerken. |
+| Beheerder | Redacteur-rechten plus gebruikers, herstelcodes, imports en systeeminstellingen. |
+
+Er moet altijd minstens één ingeschakelde beheerder overblijven: de toepassing weigert
+een wijziging die dat zou doorbreken (bijvoorbeeld de laatste beheerder degraderen of
+uitschakelen).
+
+Een gebruiker uitschakelen (`enabled: false`) maakt **bestaande** aanmeldsessies van die
+gebruiker onmiddellijk ongeldig — niet pas bij een volgende aanmeldpoging.
+
+## Wachtwoord vergeten (operator-herstel)
+
+Er is geen e-mailprovider nodig. Een beheerder geeft een eenmalige herstelcode uit:
+
+1. Beheerder roept `POST /api/v1/admin/users/{userId}/recovery-tokens` aan (via de
+   webinterface in een latere milestone, of rechtstreeks via de API met een geldige
+   beheerderssessie).
+2. De ruwe herstelcode wordt **precies één keer** getoond, in het antwoord van die
+   aanroep. Ze wordt nergens anders opgeslagen — alleen een niet-omkeerbare
+   verificatiewaarde blijft bewaard.
+3. Geef de code veilig door aan de gebruiker (bijvoorbeeld persoonlijk of via een
+   bestaand vertrouwd kanaal — nooit via een onbeveiligd kanaal).
+4. De gebruiker dient de code en een nieuw wachtwoord in bij
+   `POST /api/v1/auth/recovery/redeem`.
+5. De code werkt maar één keer en verloopt na 1 uur. Na een geslaagd herstel worden alle
+   bestaande sessies van die gebruiker ongeldig — de gebruiker moet opnieuw aanmelden
+   met het nieuwe wachtwoord.
+
+## Wat een gewone gebruiker nooit kan zien
+
+- Of een bepaald e-mailadres al dan niet een account heeft (aanmeldfoutmeldingen zijn
+  altijd generiek).
+- Of de installatie al dan niet is voltooid, verder dan het installatiescherm tonen of
+  verbergen.
+- Inhoud, gebruikers of instellingen van een andere werkruimte (de eerste uitgave
+  gebruikt één werkruimte, maar de autorisatie is daar al op voorbereid).