Bereinigte Fassung 0.5.0

Stand 21.10.2026. Vor Installation SECURITY-REVIEW.md und die übergeordnete UMSTELLUNG.md lesen. Historische Testangaben im folgenden Text gelten nicht als erneuter Integrationstest dieser Fassung.

saltcorn-owncloud – Saltcorn-Plugin für ownCloud 10.x

Zeigt ownCloud-Dateien direkt in Saltcorn an: je Benutzer (eigenes ownCloud-Konto oder persönlicher Ordner) oder je Datensatz, zum Beispiel den Ordner Kunden/[0667-01] Musterfirma GmbH einer Entity. Der Ordnername wird dabei aus Feldern zusammengesetzt. Hochladen, Herunterladen, Umbenennen, Löschen und Teilen laufen über WebDAV und die OCS-Share-API. Es braucht kein iframe und keine Änderungen an den ownCloud-Headern.

Getestet mit Saltcorn 1.6.2 und Node 20. Das Plugin hat keine Laufzeit-Abhängigkeiten.

Funktionen

| Funktion | ownCloud-Schnittstelle | |---|---| | Dateiliste mit Unterordnern, Pfadleiste, Kennzeichnung geteilter Elemente | PROPFIND (Depth 1, oc:share-types) | | Download, Vorschau im Browser (PDF, Bilder, Text) | GET, gestreamt über Saltcorn | | Upload (Mehrfachauswahl, Drag & Drop), neuer Ordner | PUT, MKCOL | | Umbenennen von Dateien und Ordnern | MOVE (ohne Überschreiben) | | Löschen (landet im ownCloud-Papierkorb) | DELETE | | Teilen: öffentlicher Link (Ablaufdatum, Passwort, bei Ordnern auch Hochladen oder Dateiablage) | OCS shares, shareType=3 | | Teilen: mit ownCloud-Benutzer oder -Gruppe (Lesen/Bearbeiten), mit Benutzersuche | OCS shares (0/1), sharees | | Bestehende Freigaben anzeigen, Link kopieren, Freigabe entfernen | OCS GET/DELETE shares | | Aktionen owncloud_ordner_anlegen, owncloud_link_erzeugen | Trigger, Buttons, Workflows |

View-Typen

| View-Typ | Tabelle | Zeigt | |---|---|---| | ownCloudBenutzerdateien (neu in 0.2.0) | keine (tabellenlos) | Dateien des angemeldeten Saltcorn-Benutzers | | ownCloudDateien | beliebig | Ordner eines Datensatzes, z.B. einer Entity. Der Name kommt aus einer Vorlage mit mehreren Feldern; die Zuordnung ist exakt oder über einen Schlüssel. Konto je View oder aus einem Feld |

Die Benutzeransicht hat zwei Betriebsarten:

| Betriebsart | ownCloud-Konto | Geeignet für | |---|---|---| | Eigenes ownCloud-Konto (Standard) | Jeder Benutzer verbindet sich einmalig mit seinem ownCloud-Benutzernamen und einem App-Passwort. ownCloud sieht den echten Benutzer, Freigaben gehören ihm. | Mitarbeitende mit eigenem ownCloud-Konto | | Benutzerordner im technischen Konto | Technischer Benutzer, Ordner je Benutzer nach Pfadvorlage, z.B. Benutzer/{email} | Benutzer ohne eigenes ownCloud-Konto, z.B. Kunden |

1. ownCloud vorbereiten

Technischer Benutzer (nötig für Datensatz-Ansichten, Aktionen und die Betriebsart „Benutzerordner“):

1. Benutzer anlegen, z.B. service-account.
2. Als dieser Benutzer unter Einstellungen > Sicherheit > App-Passwörter ein App-Passwort „Saltcorn“ erzeugen.
3. Basisordner Saltcorn anlegen.

Eigene Konten: Jeder Benutzer erzeugt sich unter Einstellungen > Sicherheit > App-Passwörter ein App-Passwort „Saltcorn“. Das normale Anmeldepasswort funktioniert ebenfalls, ist aber nicht empfohlen. Bei aktivierter Zwei-Faktor-Anmeldung geht nur das App-Passwort.

Verbindung vom Saltcorn-Server aus testen:

curl -s -u 'service-account:APP-PASSWORT' -X PROPFIND -H 'Depth: 1' \
  https://cloud.example.invalid/remote.php/dav/files/service-account/Saltcorn/ | head -20
curl -s -u 'service-account:APP-PASSWORT' -H 'OCS-APIRequest: true' \
  'https://cloud.example.invalid/ocs/v1.php/cloud/user?format=json'

Die Antworten 207 Multi-Status bzw. "statuscode":100 bedeuten, dass die Verbindung steht.

Freigabe-Richtlinien in ownCloud (Einstellungen > Admin > Freigabe) gelten weiterhin und haben Vorrang. Erzwingt ownCloud zum Beispiel ein Passwort oder ein Ablaufdatum für Links, meldet das Plugin den ownCloud-Fehler im Dialog. Die Benutzersuche beachtet „Autovervollständigung von Benutzernamen erlauben“ und „Nur mit Gruppenmitgliedern teilen“.

2. Plugin installieren

Aus npm (empfohlen): In Saltcorn unter Einstellungen > Module > Hinzufügen: Name saltcorn-owncloud, Quelle npm.

Lokal: Den Ordner nach /opt/saltcorn-plugins/saltcorn-owncloud kopieren und das Modul mit Quelle local und diesem Ort hinzufügen. Führe dort kein npm install aus.

Update von 0.1.x: Es reicht, das Modul zu aktualisieren. Bestehende ownCloudDateien-Views und Trigger laufen unverändert weiter. Die neuen Rechte gelten anfangs so: Umbenennen wie Upload, Teilen mit Benutzern wie öffentliche Links.

Plugin-Konfiguration

| Feld | Bedeutung | |---|---| | ownCloud-URL | https://cloud.example.invalid (bei Unterordner: https://host/owncloud) | | Technischer Benutzer, App-Passwort | Für Datensatz-Ansichten, Aktionen und Benutzerordner. Bleibt leer, wenn nur eigene Konten genutzt werden | | Basisordner | Wurzel für das technische Konto, z.B. Saltcorn | | Schlüssel für Benutzer-Zugangsdaten | Optional. Damit werden die App-Passwörter der Benutzer verschlüsselt (AES-256-GCM). Leer bedeutet: Saltcorns session_secret wird verwendet | | Timeout (ms) | Standard 30000 |

Schritt 2 – Weitere ownCloud-Konten (neu in 0.3.0): eine Liste weiterer technischer Benutzer, genauso aufgebaut wie die Verbindungsliste in saltcorn-samba. Jeder Eintrag hat:

| Feld | Beispiel | |---|---| | Kennung | entity | | ownCloud-Benutzer | service-records | | App-Passwort | aus ownCloud > Einstellungen > Sicherheit | | Basisordner (optional) | leer = ganzes Konto | | Eigene URL (optional) | leer = URL aus Schritt 1 |

Views und Aktionen wählen das Konto über die Kennung. default ist der Benutzer aus Schritt 1, er läuft unverändert weiter. Fehlerhafte Einträge (ungültige oder doppelte Kennung, fehlendes Passwort) zeigt die Seite als Hinweis an und übergeht sie.

Wichtig für eigene Konten: Der Schlüssel muss dauerhaft gleich bleiben. Steht in ~/.config/.saltcorn kein session_secret und ist auch SALTCORN_SESSION_SECRET nicht gesetzt, erzeugt Saltcorn bei jedem Start einen neuen Wert. Dann gilt:

• Folge: Alle Benutzer müssen sich nach jedem Neustart neu verbinden.
• Abhilfe: Einen eigenen Schlüssel im Plugin eintragen, zum Beispiel aus openssl rand -hex 32.

Wird der Schlüssel geändert, zeigt die Ansicht wieder das Verbindungsformular. Ein Fehler entsteht dabei nicht.

3. Ansicht „Meine Dateien“ einrichten

1. Views > Neue View, Typ ownCloudBenutzerdateien. Eine Tabelle wird nicht ausgewählt. Rolle der View: user.
2. Einstellungen:

| Einstellung | Eigenes Konto | Benutzerordner | |---|---|---| | ownCloud-Konto | „Eigenes ownCloud-Konto des Benutzers“ | „Benutzerordner im technischen Konto“ | | Startordner | leer = ganzes Konto, oder z.B. Saltcorn | – | | Anmeldename vorbelegen | E-Mail oder nichts | – | | Pfadvorlage | – | Benutzer/{email} oder z.B. Mitarbeiter/{kuerzel} (Felder der Tabelle users) | | Startordner automatisch anlegen | Ja | Ja |

3. Die View als Seite oder Menüpunkt einbinden, zum Beispiel unter Einstellungen > Seitenstruktur > Menü, Eintrag „Meine Dateien“.

Ablauf beim eigenen Konto:

1. Beim ersten Aufruf fragt die Ansicht den ownCloud-Benutzernamen und das App-Passwort ab.
2. Das Plugin prüft die Daten bei ownCloud und ermittelt dabei auch die interne Benutzer-ID. Die Anmeldung per E-Mail funktioniert also ebenfalls.
3. Das Passwort wird verschlüsselt in users._attributes.owncloud gespeichert, andere Attribute bleiben erhalten.
4. Über das Symbol mit der durchgestrichenen Kette trennt der Benutzer die Verbindung, das Passwort wird dabei gelöscht.
5. Wird das App-Passwort in ownCloud widerrufen, erscheint wieder das Verbindungsformular.

Benutzerordner:

• Leere Platzhalter führen zu einer Fehlermeldung statt zum Zugriff auf den übergeordneten Ordner. Geheime Felder wie password oder api_token sind als Platzhalter gesperrt.
• Mit einem Trigger Insert auf der Tabelle users und der Aktion owncloud_ordner_anlegen (Pfadvorlage Benutzer/{email}) legst du die Ordner schon bei der Registrierung an.

4. Dateien je Datensatz (ownCloudDateien)

Die Ansicht wird in die Detailansicht eines Datensatzes eingebettet, zum Beispiel einer Entity. Sie zeigt den ownCloud-Ordner, dessen Name sich aus den Feldern des Datensatzes ergibt. Wie in saltcorn-samba setzt sich der Pfad so zusammen:

Basisordner des Kontos / View-Basispfad / Ordnername / Zusätzlicher Unterpfad

Einstellungen (Schritt 1 „Konto und Ordnername“)

| Einstellung | Bedeutung | Beispiel Entity | |---|---|---| | ownCloud-Konto | In welchem ownCloud-Benutzer liegen die Ordner: default, ein Konto aus Schritt 2 oder @self (eigenes Konto des angemeldeten Benutzers) | entity | | Konto aus Feld | Optional: ein Textfeld mit der Kontokennung je Datensatz. Ist es im Datensatz leer, gilt das Konto oben. Unbekannte Kennungen erzeugen eine Meldung | – | | View-Basispfad | Fester Ordner, in dem die Datensatz-Ordner liegen | Kunden | | Ordnername bestimmen über | Vorlage aus Feldern oder Feld der Tabelle (wie from_field in saltcorn-samba) | Vorlage | | Vorlage | Platzhalter {feld}; {feld:4} füllt mit Nullen auf 4 Stellen auf. Schrägstriche in Feldwerten werden zu „-“ | [{entity_code:4}-{contact_code:2}] {entity_name} | | Zuordnung | exakt = der Name muss genau stimmen; über Schlüssel = der Ordner muss mit dem Schlüssel beginnen, der Rest darf abweichen | über Schlüssel | | Schlüsselvorlage | Eindeutiger Anfang des Ordnernamens | [{entity_code:4}- | | Zusätzlicher Unterpfad | Optional, auch mit Platzhaltern | Audit | | Wenn der Ordner fehlt | Hinweis anzeigen, Hinweis mit Button „Ordner anlegen“ oder automatisch anlegen | Hinweis mit Button | | Ordnernamen anzeigen | Ordnername als Panel-Titel, bei abweichendem Namen mit dem Hinweis „Name weicht ab“ | ja | | Nur lesen | Kein Upload, Umbenennen oder Löschen. Teilen richtet sich weiter nach den Rollen | – |

Schritt 2 „Rechte und Teilen“ enthält die Mindestrollen und die Einstellungen für Links (siehe Abschnitt 5).

Wie die Zuordnung entscheidet

Ein Beispiel mit Entity 0670, Erstkontakt 02 und dem Namen „Holzhof Alb GmbH & Co. KG“:

| Lage in Kunden | Ergebnis | |---|---| | [0670-02] Holzhof Alb GmbH & Co. KG existiert | wird angezeigt | | nur [0670-02] Holzhof Alb KG (alter Name) | wird angezeigt, mit dem Hinweis „Name weicht ab – laut Datensatz: …“ | | [0670-01] … und [0670-02] … | keine Anzeige. Die Ansicht listet beide Ordner auf, bis die Doppelung in ownCloud bereinigt ist | | kein passender Ordner | Hinweis, je nach Einstellung mit dem Button „Ordner anlegen“. Angelegt wird der vollständige Name aus der Vorlage | | contact_code im Datensatz leer | Meldung „kein Wert für {contact_code}“. Ein übergeordneter oder falscher Ordner wird nie angezeigt |

Weitere Regeln:

• Groß- und Kleinschreibung: Der Schlüssel wird ohne Rücksicht darauf verglichen. Ein exakt passender Name hat immer Vorrang.
• Zwischenspeicher: Die Ordnerliste von Kunden hält das Plugin 30 Sekunden vor. Wird ein Ordner in dieser Zeit umbenannt oder gelöscht, merkt das Plugin das und sucht neu.
• Gleiche Logik wie der Abgleich: Die Regeln entsprechen dem Schema [NNNN-NN] EntityName aus check-consistency-entity. Die Ansicht zeigt dieselben Abweichungen, die das Skript per Mail meldet.

Einrichtung Entity (Beispiel)

1. In ownCloud den Benutzer service-records mit dem Ordner Kunden und einem App-Passwort anlegen. Ihn in der Plugin-Konfiguration, Schritt 2, mit der Kennung entity eintragen.
2. View entity_dateien vom Typ ownCloudDateien auf die Tabelle entity anlegen, mit den Werten aus der Spalte „Beispiel Entity“ oben.
3. In der Show-View der Entity die View entity_dateien einbetten (Beziehung: dieser Datensatz).
4. Optional einen Trigger Insert auf entity mit der Aktion owncloud_ordner_anlegen einrichten. Dort dieselben Werte eintragen: Konto entity, Basispfad Kunden, Vorlage, Schlüsselvorlage, Unterordner wie Audit, Zertifikat. Existiert schon ein Ordner mit dem Schlüssel, nutzt die Aktion diesen und legt keinen zweiten an.

Weiteres Beispiel: Zertifizierungsfälle

Eine Tabelle faelle mit den Feldern fallnummer und oc_pfad:

• Trigger owncloud_ordner_anlegen mit der Vorlage Zertifizierungen/{fallnummer}, den Unterordnern Antrag, Audit, Zertifikat und „Pfad speichern in“ oc_pfad.
• Die View liest den Ordner dann aus dem Feld oc_pfad oder wieder über die Vorlage.

Ansichten aus 0.1.x und 0.2.x laufen unverändert weiter: Konto default, exakte Zuordnung, „automatisch anlegen“ entspricht dem früheren Haken „Ordner automatisch anlegen“.

Lesen: Es gelten die Saltcorn-Rechte des Datensatzes, einschließlich Besitzer-Regeln. Konto und Pfad kommen nur aus der View-Konfiguration und dem Datensatz, nie aus der Anfrage des Browsers.

5. Rechte

Jede View hat eigene Mindestrollen. Der Server prüft sie bei jeder Anfrage, unabhängig davon, welche Buttons angezeigt werden.

| Recht | Vorgabe Benutzeransicht | Vorgabe Datensatz-Ansicht | |---|---|---| | Upload / neuer Ordner | user | staff | | Umbenennen | user | wie Upload | | Löschen | user | admin | | Öffentliche Links | user | staff | | Teilen mit ownCloud-Benutzern/-Gruppen | user | wie Links |

Zusätzliche Einstellungen fürs Teilen:

• Vorgabe-Gültigkeit: z.B. 30 Tage.
• „Ablaufdatum erzwingen“: Ein Ablaufdatum ist Pflicht, höchstens die Vorgabe.
• Passwort für Links: optional, erforderlich oder nicht angeboten.

6. Bedienung

Die Darstellung entspricht dem Dateimanager von saltcorn-samba, damit beide Plugins nebeneinander gleich aussehen.

• Kopfzeile: Panel-Titel links, z.B. der gefundene Ordnername [0667-01] Musterfirma GmbH; bei Abweichung zusätzlich „Name weicht ab“. Rechts steht der Zähler, z.B. 6 Ordner · 1 Dateien. Der Titel lässt sich je View mit „Panel-Titel“ festlegen.
• Werkzeugleiste: ⬆ Übergeordnet, 🏠 (Startordner), ↻ (Aktualisieren), Pfadleiste, „Versteckte Dateien anzeigen“ (Namen mit Punkt am Anfang). Rechts ⬆ Hochladen und + Ordner; mit eigenem Konto zusätzlich Trennen.
• Tabelle: Dateiname, MIME-Typ, Größe, Geändert, Aktionen. Ein Klick auf die Spaltenköpfe sortiert, Ordner stehen immer oben.
• Aktionen je Zeile: Ordner Öffnen, Dateien Anzeigen (neuer Tab) und ⬇ (Herunterladen), dazu ↗ Teilen, ✎ Umbenennen, 🗑 Löschen, jeweils nur mit dem passenden Recht. Geteilte Elemente tragen die Marke „geteilt“. HTML und SVG werden immer heruntergeladen, nie angezeigt.
• Dialoge: Neuer Ordner, Umbenennen und Löschen laufen über einen Dialog. Der Upload-Dialog nimmt Dateien per Drag & Drop oder Auswahl an. Ohne „Vorhandene Dateien überschreiben“ werden bestehende Dateien nicht ersetzt, sondern als Fehler gemeldet.
• Teilen-Dialog: Er ist aufgebaut wie die übrigen Dialoge. Oben stehen die bestehenden Freigaben als Tabelle mit Empfänger/Link, Rechten, Ablaufdatum und den Buttons ⧉ (Link kopieren) und 🗑 (entfernen). Darunter wählt man „🔗 Öffentlicher Link“ oder „👤 Benutzer oder Gruppe“ und bestätigt in der Fußzeile mit „Link erstellen“ bzw. „Teilen“. Bei Benutzern und Gruppen erscheinen ab zwei Zeichen Vorschläge. Ein neuer Link wird automatisch in die Zwischenablage kopiert.
• Handy: Auf schmalen Bildschirmen werden die Spalten MIME-Typ und Geändert ausgeblendet.

7. Routen für eigenes JavaScript

Alle Routen werden als POST /view/<viewname>/<route> aufgerufen, z.B. über view_post(viewname, route, daten, callback). Bei Datensatz-Ansichten kommt immer id dazu. Fehler kommen als {oc_error, status} zurück. Fehlt die Verbindung, steht zusätzlich need_login: true darin; fehlt der Ordner oder ist er mehrdeutig, zusätzlich folder_info.

| Route | Parameter | |---|---| | list | sub | | download | path, inline (Formular-POST mit _csrf) | | upload | FormData file (mehrfach), sub, overwrite (1/0, ohne Angabe 1). Antwort uploaded und results (name, ok, error) | | mkdir | sub, name | | rename | path, name | | remove | path | | shares | path | | share_create | path, type (link/user/group), perm (read/edit/upload/drop), expire (JJJJ-MM-TT), password, share_with | | share_delete | share_id | | sharees | q, is_dir | | connect / disconnect | login, app_password (Benutzeransicht mit eigenem Konto, Datensatz-Ansicht mit Konto @self) | | create_folder | – (nur Datensatz-Ansicht, Modus „Hinweis mit Button“; legt den Ordner aus der Vorlage an) | | share | path. Kompatibel zu 0.1.x: öffentlicher Link, ein bestehender wird wiederverwendet (nur Datensatz-Ansicht) |

8. Sicherheit

• Kein Direktzugriff: Der Browser spricht nie mit ownCloud. Die ownCloud-URL kommt nur aus der Plugin-Konfiguration.
• Ordnergrenzen: Pfade werden in Segmente zerlegt, .. und Steuerzeichen werden abgewiesen. Der Startordner selbst lässt sich nicht umbenennen oder löschen.
• Freigaben entfernen: Vor dem Entfernen prüft das Plugin, ob die Freigabe im erlaubten Ordner liegt. Das ist wichtig bei Benutzerordnern im gemeinsamen Dienstkonto.
• Passwort-Hash: Bei Links liefert ownCloud 10 im Feld share_with den Hash des Link-Passworts. Das Plugin gibt diesen Wert nie aus.
• Protokoll: Beim eigenen Konto protokolliert ownCloud den echten Benutzer. Beim technischen Konto steht der handelnde Benutzer nur im Saltcorn-Log.

9. Grenzen und Hinweise

• Upload-Größe: Zusätzlich zum Plugin-Limit gelten Saltcorns Upload-Limit, client_max_body_size in nginx, die PHP-Limits und das ownCloud-Kontingent.
• Selbst signierte Zertifikate: Die CA über NODE_EXTRA_CA_CERTS=/pfad/ca.pem in der systemd-Unit bekannt machen.
• Nicht enthalten:
  • Verschieben zwischen Ordnern
  • Bearbeiten bestehender Freigaben (stattdessen entfernen und neu anlegen)
  • Föderierte Freigaben
  • Versionen
  • „Mit mir geteilt“-Übersicht (geteilte Ordner erscheinen in ownCloud trotzdem im Konto des Empfängers)
• ownCloud Infinite Scale (oCIS) wird nicht unterstützt, nur ownCloud Classic 10.x.

10. Tests

npm install     # devDependencies @saltcorn/data und @saltcorn/markup, nur zum Testen
npm test        # Port des ownCloud-Nachbaus über OC_TEST_PORT (Standard 18180)

test/ enthält einen ownCloud-Nachbau mit mehreren Konten (WebDAV, OCS-Shares, Sharees, cloud/user) und 80 Tests für Client, beide View-Typen, Ordnerzuordnung (Vorlage, Schlüssel, Abweichung, Mehrdeutigkeit, Anlegen), Kontenliste, Rechte, Verschlüsselung, Pfad- und Freigabegrenzen sowie die Aktionen.

Dateien

saltcorn-owncloud/
├── index.js             Konfiguration, beide View-Typen, Aktionen
├── lib/filebrowser.js   gemeinsame Routen und HTML-Gerüst
├── lib/client.js        Browser-Skript (Liste, Upload, Umbenennen, Teilen, Anmeldung)
├── lib/folder.js        Ordnernamen aus Feldern, Zuordnung über Schlüssel
├── lib/accounts.js      Kontenliste (default + Schritt 2)
├── lib/owncloud.js      WebDAV/OCS-Client
├── lib/secret.js        Verschlüsselung der Benutzer-App-Passwörter
├── lib/xml.js           XML-Leser für WebDAV-Antworten
└── test/                ownCloud-Nachbau und Tests