Drive-Sync-Architektur: URLs, Scopes und Audit

Dies ist die Entwicklerreferenz für Drive Sync. Sie richtet sich an alle, die den Synchronisierungszugriff neben der REST API oder dem MCP-Server integrieren, Werkzeuge auf Basis von TrekMail Drive entwickeln oder prüfen, wie die WebDAV-Schnittstelle Berechtigungen durchsetzt.

Wenn du lediglich rclone oder Finder mit Drive verbinden möchtest, beginne mit der Drive-Sync-Übersicht.

Was ist Drive Sync?

Drive Sync ist eine WebDAV-Schnittstelle für TrekMail Drive. Eine kompatible Synchronisierungs-App erhält damit Zugriff auf dieselben Dateien, die du im Dashboard und in Webmail siehst. Dafür verwendet sie ein eigenes Gerätepasswort mit ausgewählten Berechtigungen.

Die Schnittstelle nutzt standardmäßige WebDAV-Methoden unter einem festen Präfix. Die Clientunterstützung ist unterschiedlich. Teste deshalb die benötigten Vorgänge zunächst mit einem entbehrlichen Ordner, bevor du den Client für eine Migration oder Sicherung in der Produktion verwendest.

URL-Struktur

Die Drive-URL wird für die Bereitstellung erzeugt und unter Sync devices angezeigt. Kopiere diese URL, statt sie aus der Domain deines Dashboards zusammenzusetzen. Der Pfad beginnt mit /dav/files/:

https://YOUR-DRIVE-HOST/dav/files/

Unter diesem Stamm liegen eine Kontostruktur und Strukturen für die Postfächer. Welche Bereiche ein Passwort öffnen kann, hängt sowohl von seiner Bindung an ein Postfach als auch von den ausgewählten Berechtigungen ab:

Kontoübergreifende Struktur

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

Dies ist das Account Drive des Dashboards. Ein Passwort, das nicht auf ein einzelnes Postfach beschränkt ist, kann diese Struktur sehen, wenn es eine Account-Drive-Berechtigung besitzt.

Auf ein Postfach beschränkte Struktur

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

Wenn ein Gerätepasswort auf ein Postfach beschränkt ist, sieht es nur die persönliche Struktur dieses Postfachs. Hat das Postfach persönlichen Drive-Zugriff und besitzt das Konto freigegebene Ordner, zeigt die Sammlung Shared/ die für alle Postfächer freigegebenen Kontoordner.

Ein auf ein Postfach beschränktes Passwort kann weder Account Drive noch ein anderes Postfach sehen. Ein Passwort ohne Postfachbeschränkung kann die Drive-Bereiche des Kontos auflisten, jeder Pfad erfordert jedoch weiterhin die passende Konto- oder Postfachberechtigung.

Gerätepasswort erstellen

Du kannst ein Passwort im Dashboard unter Sync devices oder für das aktuell verwendete Postfach in Webmail erstellen. Das Dashboard kann ein kontoübergreifendes Passwort erstellen oder es auf ein Postfach beschränken. Webmail erstellt ein Passwort ausschließlich für das angemeldete Postfach.

Wähle eine eindeutige Bezeichnung, nur die von der App benötigten Berechtigungen und bei einer temporären Verbindung ein Ablaufdatum. Das Geheimnis wird einmal angezeigt. Speichere es in der App oder einem Passwortmanager, bevor du die Bestätigungsseite schließt.

Du kannst ein Gerätepasswort jederzeit widerrufen, ohne dein normales TrekMail-Anmeldepasswort zu ändern. Ein widerrufenes oder abgelaufenes Passwort funktioniert sofort nicht mehr.

Mit einem Gerätepasswort anmelden

Die Synchronisierung verwendet HTTP Basic über HTTPS. Gib den unter Sync devices angezeigten Benutzernamen und das erzeugte Gerätepasswort ein. Verwende in einer Synchronisierungs-App nicht dein Passwort für das TrekMail-Dashboard.

Wenn das Passwort widerrufen wird oder abläuft, fragt die App normalerweise erneut nach Anmeldedaten. Bei jeder Anfrage werden Kontostatus, Postfachzugriff, Drive-Zugriff und die ausgewählten Berechtigungen geprüft.

Scope-Modell

Drive Sync verwendet dieselben Scope-Zeichenfolgen wie die REST API im Format drive:{family}:{action}. Diese acht gelten für Gerätepasswörter:

Zum Lesen eines Pfades ist die passende :read-Berechtigung erforderlich. Erstellen, Ändern, Verschieben, Kopieren oder Löschen erfordert :write. Der Pfad bestimmt, ob die App Konto- oder Postfachzugriff anfordert. Daher kann ein auf ein Postfach beschränktes Passwort weder Account Drive noch ein anderes Postfach erreichen.

Der Bildschirm Sync devices bietet nur Berechtigungen an, die für eine Synchronisierungs-App sinnvoll sind. Abrechnungsberechtigungen sind nicht Bestandteil eines Gerätepassworts.

Berechtigungen zum Teilen und endgültigen Löschen

Das Formular für Gerätepasswörter kann die Berechtigungen :share und :purge anzeigen, wenn das Konto dazu berechtigt ist. Der aktuelle Schutz der WebDAV-Routen ordnet Dateivorgänge nur :read und :write zu. Gehe deshalb nicht davon aus, dass eine dieser Berechtigungen einen WebDAV-Befehl für Freigabelinks oder dauerhaftes Löschen hinzufügt.

Bei WebDAV erfordert ein normales DELETE die Berechtigung :write und verschiebt die Datei in den Papierkorb. WebDAV bietet weder das direkte Ersetzen einer vorhandenen Datei noch einen Vorgang zum dauerhaften Löschen. Verwende dafür die Drive-Oberfläche.

Sichere Dateinamen

Datei- und Ordnernamen müssen auf verschiedenen Betriebssystemen sicher sein. Leere Namen, Pfadtrennzeichen, Steuerzeichen, irreführende Dateinamenzeichen und Namen, die nach der Windows- oder Unicode-Normalisierung kollidieren würden, werden abgelehnt. Namen dürfen bis zu 255 sichtbare Zeichen enthalten.

Wenn eine App einen Validierungsfehler erhält, benenne das Element in der App um und versuche es erneut. Versuche nicht, den Fehler zu umgehen, indem du einen Pfad als Dateinamen verwendest.

Uploads in Blöcken

Kleine Dateien können ein normales PUT verwenden. Clients, die den Nextcloud-Ablauf für Uploads in Blöcken v2 unterstützen, können unter /dav/uploads/{session-uuid}/ eine Upload-Sitzung erstellen, nummerierte Blöcke hochladen und anschließend mit MOVE die Datei am endgültigen Speicherort zusammensetzen.

Uploadlimits können je nach Bereitstellung und Client variieren. Behandle eine fehlgeschlagene oder abgelaufene Sitzung als neuen Uploadversuch. Wenn ein anderer Client das Ziel zuerst erstellt, nutze die Konfliktantwort, um einen neuen Namen zu wählen, oder aktualisiere den Ordner vor dem nächsten Versuch.

Audit-Protokoll

Erfolgreiche Änderungen über Sync erscheinen im Aktivitätsverlauf von Drive. Der Eintrag nennt das betroffene Element, die Aktion, die Zeit und das verwendete Gerätepasswort. So kann ein Administrator unerwartete Änderungen untersuchen und das betreffende Passwort widerrufen.

Clients, die den Drive-Änderungsfeed verwenden, können über WebDAV vorgenommene Änderungen sehen. Wenn der Dienst eine vollständige Neusynchronisierung verlangt, erstelle die lokale Ansicht aus einem neuen Snapshot, bevor du mit dem gespeicherten Cursor fortfährst.

Anfragelimits

Anfragen an Drive Sync werden zum Schutz des Dienstes und deiner Dateien begrenzt. Wenn ein Client 429 erhält, reduziere die Parallelität, beachte Retry-After, sofern es gesendet wird, und wiederhole einen kleinen Vorgang, bevor du den Auftrag fortsetzt.

Verfügbarkeit

Drive Sync ist in der Produktion verfügbar. Konten benötigen Drive-Zugriff. Die verfügbaren Berechtigungen für Gerätepasswörter hängen weiterhin vom Konto, Postfach, Tarif und der Person ab, die das Passwort erstellt. White-Label-Kunden verwenden denselben Drive-Sync-Dienst. Kopiere immer die aktuelle URL aus Sync devices, statt sie selbst zu konstruieren.

Wie geht es weiter?

• Informationen zur Einrichtung für Endbenutzer findest du in der Drive-Sync-Übersicht.
• Informationen zur Dashboard-Oberfläche, die Gerätepasswörter ausstellt, findest du unter Sync devices.
• Die entsprechenden Vorgänge für REST API und MCP beschreiben die Übersicht zur Drive API und Scopes und Berechtigungen der Drive API.
• Das Speicher- und Kontingentmodell, das die Synchronisierung mit allen anderen Funktionen teilt, erklärt Zusammengefasste Speicherkontingente.