Architecture Drive Sync : URL, scopes et audit

Cette page est la référence destinée aux développeurs de Drive Sync. Elle s’adresse à vous si vous intégrez l’accès synchronisé avec l’API REST ou le serveur MCP, créez des outils basés sur TrekMail Drive ou vérifiez comment la façade WebDAV applique les autorisations.

Si vous souhaitez simplement connecter rclone ou Finder à Drive, commencez par la présentation de Drive Sync.

Qu’est-ce que Drive Sync ?

Drive Sync est une interface WebDAV pour TrekMail Drive. Elle donne à une application de synchronisation compatible l’accès aux mêmes fichiers que ceux visibles dans le tableau de bord et le webmail, avec son propre mot de passe d’appareil et les autorisations sélectionnées.

L’interface utilise les méthodes WebDAV standard sous un préfixe fixe. La prise en charge varie selon le client. Testez donc les opérations nécessaires dans un dossier temporaire avant de l’utiliser pour une migration ou une sauvegarde en production.

Structure des URL

L’URL Drive est générée pour le déploiement et affichée dans Sync devices. Copiez cette URL au lieu d’en construire une à partir du domaine de votre tableau de bord. Son chemin commence par /dav/files/ :

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

Cette racine contient une arborescence de compte et des arborescences de boîtes mail. Les emplacements qu’un mot de passe peut ouvrir dépendent à la fois de son association à une boîte mail et des autorisations sélectionnées :

Arborescence du compte entier

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

Il s’agit de l’Account Drive du tableau de bord. Un mot de passe qui n’est pas limité à une boîte mail peut voir cette arborescence s’il dispose d’une autorisation Account Drive.

Arborescence limitée à une boîte mail

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

Lorsqu’un mot de passe d’appareil est limité à une boîte mail, il ne peut voir que l’arborescence personnelle de cette boîte. Si celle-ci a accès au Drive personnel et que le compte possède des dossiers partagés, la collection Shared/ affiche les dossiers du compte partagés avec toutes les boîtes mail.

Un mot de passe limité à une boîte ne peut voir ni Account Drive ni une autre boîte. Un mot de passe sans restriction de boîte peut répertorier les espaces Drive du compte, mais chaque chemin exige toujours l’autorisation de compte ou de boîte correspondante.

Créer un mot de passe d’appareil

Vous pouvez créer un mot de passe depuis Sync devices dans le tableau de bord ou, pour la boîte mail actuellement utilisée, depuis le webmail. Le tableau de bord permet de créer un mot de passe pour tout le compte ou de le limiter à une boîte. Le webmail crée uniquement un mot de passe pour la boîte connectée.

Choisissez un libellé clair, sélectionnez uniquement les autorisations nécessaires à l’application et définissez une expiration pour une connexion temporaire. Le secret n’est affiché qu’une fois. Enregistrez-le dans l’application ou dans un gestionnaire de mots de passe avant de fermer l’écran de confirmation.

Vous pouvez révoquer un mot de passe d’appareil à tout moment sans modifier votre mot de passe de connexion TrekMail habituel. Un mot de passe révoqué ou expiré cesse immédiatement de fonctionner.

Se connecter avec un mot de passe d’appareil

La synchronisation utilise HTTP Basic via HTTPS. Saisissez le nom d’utilisateur affiché dans Sync devices et le mot de passe d’appareil généré. N’utilisez pas le mot de passe de votre tableau de bord TrekMail dans une application de synchronisation.

Si le mot de passe est révoqué ou expire, l’application redemande généralement les identifiants. L’état du compte, l’accès à la boîte mail, l’accès à Drive et les autorisations sélectionnées sont vérifiés à chaque requête.

Modèle de scopes

Drive Sync utilise les mêmes chaînes de scope que l’API REST, au format drive:{family}:{action}. Huit d’entre elles s’appliquent aux mots de passe d’appareil :

La lecture d’un chemin nécessite l’autorisation :read correspondante. La création, la modification, le déplacement, la copie ou la suppression nécessitent :write. Le chemin détermine si l’application demande un accès au compte ou à la boîte mail. Un mot de passe limité à une boîte ne peut donc atteindre ni Account Drive ni une autre boîte.

L’écran Sync devices propose uniquement les autorisations pertinentes pour une application de synchronisation. Les autorisations de facturation ne font pas partie d’un mot de passe d’appareil.

Autorisations de partage et de purge

Le formulaire de mot de passe d’appareil peut afficher les autorisations :share et :purge lorsque le compte y a droit. La protection actuelle des routes WebDAV associe uniquement les opérations sur les fichiers à :read et :write. Ne supposez donc pas que la sélection de l’une de ces autorisations ajoute à WebDAV une commande de lien de partage ou de suppression définitive.

Avec WebDAV, un DELETE ordinaire nécessite :write et déplace le fichier vers la corbeille. WebDAV ne permet ni de remplacer un fichier sur place ni d’effectuer une purge définitive. Utilisez l’interface Drive pour ces tâches.

Sécurité des noms de fichiers

Les noms de fichiers et de dossiers doivent être sûrs sur différents systèmes d’exploitation. Les noms vides, les séparateurs de chemin, les caractères de contrôle, les caractères de nom trompeurs et les noms qui entreraient en conflit après normalisation Windows ou Unicode sont refusés. Un nom peut contenir jusqu’à 255 caractères visibles.

Si une application reçoit une erreur de validation, renommez l’élément dans l’application et réessayez. Ne tentez pas de contourner l’erreur en insérant un chemin dans un nom de fichier.

Téléversements par fragments

Les petits fichiers peuvent utiliser une requête PUT normale. Les clients compatibles avec le flux de téléversement par fragments v2 de Nextcloud peuvent créer une session sous /dav/uploads/{session-uuid}/, téléverser des fragments numérotés, puis utiliser MOVE pour assembler le fichier à son emplacement final.

Les limites de téléversement peuvent varier selon le déploiement et le client. Considérez une session échouée ou expirée comme une nouvelle tentative de téléversement. Si un autre client crée d’abord la destination, utilisez la réponse de conflit pour choisir un nouveau nom ou actualisez le dossier avant de réessayer.

Piste d’audit

Les modifications réussies effectuées via Sync apparaissent dans l’historique d’activité de Drive. L’enregistrement indique l’élément concerné, l’action, l’heure et le mot de passe d’appareil utilisé. Un administrateur peut ainsi analyser les changements inattendus et révoquer le mot de passe concerné.

Les clients qui utilisent le flux de modifications de Drive peuvent voir les changements effectués via WebDAV. Si le service demande une resynchronisation complète, reconstruisez la vue locale à partir d’un nouvel instantané avant de continuer avec le curseur enregistré.

Limites de débit

Les requêtes Drive Sync sont soumises à des limites afin de protéger le service et vos fichiers. Si un client reçoit 429, réduisez les accès simultanés, respectez Retry-After lorsqu’il est fourni et réessayez une petite opération avant de reprendre la tâche.

Disponibilité

Drive Sync est disponible en production. Les comptes doivent avoir accès à Drive, et les autorisations disponibles pour les mots de passe d’appareil dépendent toujours du compte, de la boîte mail, de l’offre et de la personne qui crée le mot de passe. Les clients White Label utilisent le même service Drive Sync. Copiez toujours l’URL actuelle depuis Sync devices au lieu de la construire.

Pour aller plus loin

• Pour la configuration destinée aux utilisateurs, consultez la présentation de Drive Sync.
• Pour l’interface du tableau de bord qui génère les mots de passe d’appareil, consultez Sync devices.
• Pour les équivalents de ces opérations dans l’API REST et MCP, consultez la présentation de l’API Drive et les scopes et autorisations de l’API Drive.
• Pour le modèle de stockage et de quota commun à la synchronisation et aux autres fonctions, consultez l’explication des quotas de stockage mutualisé.