Volumes

project_docs/UI_VOLUMES_DIRECTORY_VIEW_V1.md

@@ -0,0 +1,151 @@
+# UI_VOLUMES_DIRECTORY_VIEW_V1
+
+## 1. Doel
+
+Doel van deze stap is om de webui een host-achtige navigatiestructuur te geven waarbij de gebruiker eerst `/Volumes` ziet en daarna daarbinnen de beschikbare mounts kan openen, zoals:
+
+- `/Volumes/8TB`
+- `/Volumes/8TB_RAID1`
+
+Waarom dit gewenst is:
+- het sluit beter aan op de werkelijke host- en containerstructuur
+- het voorkomt dat technische aliasnamen zoals `storage1` en `storage2` het primaire navigatiemodel bepalen
+- het maakt de UI begrijpelijker voor gebruikers die denken in echte mountpunten en directories, niet in app-specifieke labels
+
+---
+
+## 2. Gewenste UI-weergave
+
+Gewenst gedrag in beide panelen:
+- een paneel kan op `/Volumes` staan als huidige directoryweergave
+- in die weergave ziet de gebruiker de toegestane submappen als normale directory entries
+- voor deze case moeten daar minimaal zichtbaar zijn:
+  - `8TB`
+  - `8TB_RAID1`
+
+Navigatieflow:
+- gebruiker opent of kiest `/Volumes`
+- de lijst toont `8TB` en `8TB_RAID1` als directories
+- klikken of `Enter` op `8TB` opent `/Volumes/8TB`
+- klikken of `Enter` op `8TB_RAID1` opent `/Volumes/8TB_RAID1`
+
+Voor dual-pane gedrag:
+- beide panelen moeten onafhankelijk op `/Volumes` of op een onderliggende mount kunnen staan
+- er is geen speciaal verschillend gedrag nodig tussen links en rechts
+- breadcrumbs moeten `/Volumes` en daarna de mountnaam tonen
+
+---
+
+## 3. Relatie met huidige whitelist/root-configuratie
+
+Huidige situatie:
+- de backend werkt met expliciete toegestane roots via aliases
+- defaults zijn nu:
+  - `storage1 -> /Volumes/8TB`
+  - `storage2 -> /Volumes/8TB_RAID1`
+
+Belangrijk verschil:
+- de huidige whitelist geeft alleen directe toegang tot specifieke roots
+- `/Volumes` zelf is op dit moment conceptueel geen browsebare root in het bestaande model
+
+Voor het gewenste gedrag is een extra browsebaar niveau nodig:
+- niet als volledig vrije root over het hele filesystem
+- maar als gecontroleerde containerdirectory die alleen als bovenliggende presentatie-laag dient voor de whitelisted mounts
+
+Cruciale eis:
+- als `/Volumes` zichtbaar wordt, mag niet automatisch alle andere inhoud van `/Volumes` browsebaar worden
+- alleen de expliciet toegestane mounts onder `/Volumes` mogen zichtbaar zijn
+
+---
+
+## 4. Veiligheidsmodel
+
+Aanbevolen veiligheidsmodel:
+- `/Volumes` wordt niet behandeld als een normale vrije root
+- `/Volumes` wordt behandeld als een virtuele of gecontroleerde container-directoryweergave boven de bestaande whitelisted roots
+
+Veilige semantiek:
+- de UI/backend toont in `/Volumes` alleen de mountnamen die corresponderen met toegestane roots
+- voor deze case dus alleen:
+  - `8TB`
+  - `8TB_RAID1`
+- andere directories onder de echte `/Volumes` mogen niet automatisch zichtbaar worden
+
+Concreet:
+- browse van `/Volumes` retourneert een samengestelde directorylisting op basis van toegestane roots
+- navigatie naar `/Volumes/<naam>` is alleen geldig als die volledige path overeenkomt met een geconfigureerde root of daarbinnen valt
+
+Passend bij bestaand model:
+- alle verdere padresolutie onder `/Volumes/8TB/...` en `/Volumes/8TB_RAID1/...` blijft via bestaand `path_guard`
+- traversal en whitelistcontrole blijven dus centraal gehandhaafd
+
+---
+
+## 5. Backend-impact
+
+Dit kan niet netjes alleen frontend-side worden opgelost.
+
+Waarom niet frontend-only:
+- de bestaande browse-API verwacht een pad dat door de backend gevalideerd en opgelijst wordt
+- als de backend `/Volumes` niet kent als geldige browsecontext, kan de frontend die laag niet betrouwbaar simuleren zonder speciale hardcoded clientlogica
+- frontend-only zou ook de securitygrenzen vertroebelen, omdat de UI dan zelf een deel van de directorystructuur zou moeten faken
+
+Backend-aanpassing is dus nodig.
+
+Veiligste en simpelste richting:
+- een kleine backend-uitbreiding in de browse-service/path-interpretatie
+- introduceer een gecontroleerd browse-niveau voor `/Volumes`
+- behandel dat niveau als speciale, beperkte listing van geconfigureerde roots
+- behoud voor alle onderliggende operaties het bestaande whitelist/path_guard-model
+
+Pragmatische v1-richting:
+- voeg een expliciete conceptuele container-root toe, bijvoorbeeld browsepad `/Volumes`
+- browse op `/Volumes` retourneert alleen directory-entries voor de toegestane mount-roots
+- browse op `/Volumes/<mount>` mapt naar de bestaande geconfigureerde root
+
+Dat is veiliger dan `/Volumes` volledig als nieuwe whitelist-root toevoegen.
+
+---
+
+## 6. Risico's
+
+### Regressierisico
+- browse-contract moet duidelijk blijven voor bestaande paden zoals `storage1/...`
+- bestaande UI- en golden-tests zijn nu alias-gebaseerd; die mogen niet onbedoeld breken
+- copy/move/rename/delete/bookmarks werken nu op bestaande padrepresentaties; migratie naar `/Volumes/...` moet doordacht gebeuren
+
+### Securitygevolgen
+- een onzorgvuldige implementatie zou per ongeluk meer van `/Volumes` kunnen tonen dan toegestaan
+- een onzorgvuldige mapping van `/Volumes/<naam>` naar echte paden kan whitelistcontroles verzwakken
+
+### UX-verwarring
+- tijdelijke co-existentie van aliaspaden (`storage1/...`) en hostachtige paden (`/Volumes/8TB/...`) kan verwarrend zijn
+- zonder heldere keuze ontstaat een hybride model dat lastig te begrijpen en te testen is
+
+---
+
+## 7. Aanbeveling
+
+Aanbevolen implementatierichting voor v1:
+
+1. Niet frontend-only doen.
+2. Geen vrije browse-root van heel `/Volumes` toevoegen.
+3. Wel een gecontroleerde backend-browseweergave voor `/Volumes` introduceren.
+4. Laat die weergave alleen expliciet geconfigureerde mountdirectories tonen.
+5. Houd alle echte padvalidatie en verdere navigatie onder die mounts via bestaand `path_guard`-model.
+
+Concreet aanbevolen model:
+- `/Volumes` wordt een speciale browse-entrypoint
+- listing van `/Volumes` bevat alleen de whitelisted mountnamen
+- `/Volumes/8TB/...` en `/Volumes/8TB_RAID1/...` worden daarna normaal browsebaar binnen de bestaande veiligheidsgrenzen
+
+Waarom dit de beste v1-richting is:
+- sluit aan op de echte hoststructuur
+- behoudt securitycontrole centraal in backend
+- vermijdt frontend-hardcoding als primaire oplossing
+- is beperkt, uitlegbaar en testbaar
+
+Niet aanbevolen voor v1:
+- puur frontend-aliasing
+- volledig openstellen van `/Volumes` als generieke root
+- tegelijk zowel aliasmodel als hostpathmodel als primaire UX blijven promoten zonder expliciete migratiekeuze