webmanager-mvp/project_docs/UI_VOLUMES_DIRECTORY_VIEW_V1.md

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