cmap functions, email, architecture documentation.

2026-08-18 03:33:10 +02:00
parent 12f1ed2764
commit 63b7ca0853
33 changed files with 3974 additions and 80 deletions
@@ -0,0 +1,60 @@
+# Beveiliging en vertrouwen
+
+## Vertrouwensgrenzen
+
+De browser, requestparameters, Markdown, CMap-JSON, bestandsnamen en SMTP-serverreacties zijn onbetrouwbare invoer. De Racket-backend bewaakt identiteit, rol, CSRF en domeinvalidatie. PostgreSQL bewaakt relationele constraints en transacties. Een reverse proxy bewaakt in een productieopstelling doorgaans de externe TLS-verbinding.
+
+Een verborgen knop is geen autorisatie. Een door DOMPurify gesaneerde preview is geen reden om raw HTML elders ongesaneerd in te voegen. Een client-side versienummer is geen waarheid totdat de backend het onder rijlocking met PostgreSQL heeft vergeleken.
+
+## Authenticatie en sessies
+
+Wachtwoorden worden met PBKDF2-HMAC-SHA256 en een hoge iteratiewaarde gehasht. Sessietokens zijn willekeurig; alleen hun SHA-256-hash wordt opgeslagen. Een sessie bevat daarnaast een apart CSRF-token en vervaltijd. Uitgeschakelde gebruikers en verlopen sessies worden niet geaccepteerd.
+
+De sessiecookie moet `Secure` zijn wanneer de externe site HTTPS gebruikt. Cookiebeleid en reverse-proxyheaders moeten bij deployment samen worden getest.
+
+## Rollen
+
+De rangorde is `reader < editor < admin`. Iedere beschermde handler gebruikt server-side rolcontrole. Schrijvende handlers vereisen bovendien CSRF. Nieuwe endpoints krijgen een expliciete minimale rol; zij erven niet toevallig veiligheid doordat de frontend de route niet toont.
+
+## Inhoud en rendering
+
+Markdown wordt door EasyMDE/Marked gerenderd en daarna door DOMPurify gesaneerd. Interne WikiWords, namespaced links, todo-markeringen en CMap-embeds worden via gecontroleerde transformaties toegevoegd. Attributen die na sanering programmatisch worden gemaakt, krijgen alleen gevalideerde slugs en lokaal opgebouwde routes.
+
+Uploads krijgen een server-side veilige opgeslagen naam en MIME-type op basis van bekende extensies. Downloadroutes verwerpen padseparators. Bij uitbreiding met inline actieve formaten zoals SVG of HTML moet afzonderlijk worden beoordeeld of download, sandboxing of sanering nodig is.
+
+## Database en geheimen
+
+SQL gebruikt parameters voor inhoudelijke waarden. Databasecredentials staan in `wiki-data/database.rktd`; de code probeert de bestandsrechten te beperken. De datamap is daarmee geheim en hoort niet in een ZIP, publieke repository of statische webroot.
+
+Ook SMTP-wachtwoorden kunnen in `wiki_settings` of omgevingsvariabelen staan. Zij mogen niet via het beheer-API worden teruggegeven en niet in logregels verschijnen. Een lege wachtwoordinvoer bij de testmail betekent: gebruik het reeds opgeslagen geheim.
+
+## Wachtwoordherstel
+
+De publieke aanvraag meldt niet of gebruiker of e-mailadres bestaat. Herstelcodes zijn willekeurig, alleen gehasht opgeslagen, één uur geldig en eenmalig. Rate limiting begrenst aanvragen per gebruiker. Een succesvolle reset trekt bestaande sessies in.
+
+De publieke basis-URL voor e-mail moet expliciet worden ingesteld; een door de request aangeleverde Host-header is geen betrouwbare basis voor beveiligingslinks.
+
+## SMTP en STARTTLS
+
+Met STARTTLS en **Onvertrouwde certificaten accepteren** uit gebruikt de wiki `ssl-secure-client-context`: certificaatketen en SMTP-hostnaam worden gecontroleerd. Met het vinkje aan gebruikt de wiki `ssl-make-client-context 'auto`: verkeer is versleuteld, maar de serveridentiteit is niet bewezen.
+
+De uitzonderingsoptie is uitsluitend bedoeld voor een bewust vertrouwde lokale mailserver. Een eigen lokale CA toevoegen aan de trust store is veiliger dan verificatie uitschakelen.
+
+## Beschikbaarheid en misbruik
+
+Er gelden al document- en veldvalidaties, maar een algemeen uploadmaximum en request-rate limiting zijn toekomstige versterkingen. De CMap-opslag begrenst het JSON-document tot 10 MiB. Grote Markdown, bijlagen, graph-opbouw en dure zoekvragen kunnen anders geheugen of verwerkingstijd gebruiken.
+
+Voor een publiek bereikbare installatie horen reverse-proxylimits, databaseback-ups, logrotatie en monitoring bij het beveiligingsmodel. Beschikbaarheid is ook een beveiligingseigenschap.
+
+## Beveiligingsregels voor wijzigingen
+
+1. Behoud parametrische SQL.
+2. Valideer opnieuw aan de servergrens, ook als de browser valideert.
+3. Log nooit geheimen of ruwe tokens.
+4. Gebruik veilige standaardinstellingen; een uitzondering vereist een expliciete keuze en uitleg.
+5. Maak accountenumeratie niet mogelijk via tekst, statuscode of meetbaar afwijkend gedrag waar praktisch.
+6. Test iedere nieuwe write-route op sessie, rol en CSRF.
+7. Houd vendorversies vastgepind en controleer downloads via HTTPS.
+8. Behandel archiveren, herstellen en importeren als mutaties met auditinformatie.
+
+Zie [Data en versies](racket-wiki:data-en-versies) voor opslaginvarianten en [Testbaarheid](racket-wiki:testbaarheid) voor de noodzakelijke securitytests.