Arquitectura de Drive Sync: URL, scopes y auditoría

Esta es la referencia para desarrolladores de Drive Sync. Si integras el acceso de sincronización junto con la API REST o el servidor MCP, creas herramientas sobre TrekMail Drive o auditas cómo la interfaz WebDAV aplica los permisos, esta página es para ti.

Si solo quieres conectar rclone o Finder a Drive, empieza por la descripción general de Drive Sync.

Qué es Drive Sync

Drive Sync es una interfaz WebDAV para TrekMail Drive. Permite que una aplicación de sincronización compatible acceda a los mismos archivos que ves en el panel y en webmail, con su propia contraseña de dispositivo y los permisos seleccionados.

La interfaz utiliza métodos WebDAV estándar en un prefijo fijo. La compatibilidad varía según el cliente, así que prueba las operaciones que necesites con una carpeta desechable antes de usarlo para una migración o copia de seguridad en producción.

Estructura de URL

La URL de Drive se genera para cada implementación y aparece en Sync devices. Copia esa URL en lugar de crearla a partir del dominio del panel. Su ruta comienza con /dav/files/:

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

Bajo esa raíz se encuentran un árbol de cuenta y árboles de buzones. Lo que una contraseña puede abrir depende tanto de su asociación a un buzón como de los permisos seleccionados:

Árbol de toda la cuenta

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

Este es el Drive de cuenta del panel. Una contraseña que no esté limitada a un buzón puede ver este árbol si cuenta con un permiso de Account Drive.

Árbol limitado a un buzón

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

Cuando una contraseña de dispositivo está limitada a un buzón, solo puede ver el árbol personal de ese buzón. Si el buzón tiene acceso al Drive personal y la cuenta tiene carpetas compartidas, la colección Shared/ muestra las carpetas de la cuenta compartidas con todos los buzones.

Una contraseña limitada a un buzón no puede ver Account Drive ni otro buzón. Una contraseña sin límite de buzón puede enumerar los espacios de Drive de la cuenta, pero cada ruta sigue exigiendo el permiso de cuenta o buzón correspondiente.

Crear una contraseña de dispositivo

Puedes crear una contraseña desde Sync devices en el panel o, para el buzón que utilizas en ese momento, desde webmail. El panel permite crear una contraseña para toda la cuenta o limitarla a un buzón. Webmail solo crea una contraseña para el buzón con la sesión iniciada.

Elige una etiqueta clara, selecciona solo los permisos que necesita la aplicación y establece una caducidad si la conexión es temporal. El secreto se muestra una sola vez. Guárdalo en la aplicación o en un gestor de contraseñas antes de cerrar la pantalla de confirmación.

Puedes revocar una contraseña de dispositivo en cualquier momento sin cambiar tu contraseña habitual de acceso a TrekMail. Una contraseña revocada o caducada deja de funcionar de inmediato.

Iniciar sesión con una contraseña de dispositivo

La sincronización usa HTTP Basic sobre HTTPS. Introduce el nombre de usuario que aparece en Sync devices y la contraseña de dispositivo generada. No uses la contraseña del panel de TrekMail en una aplicación de sincronización.

Si la contraseña se revoca o caduca, la aplicación suele volver a solicitar las credenciales. En cada solicitud se comprueban el estado de la cuenta, el acceso al buzón, el acceso a Drive y los permisos seleccionados.

Modelo de scopes

Drive Sync utiliza las mismas cadenas de scope que la API REST, con el formato drive:{family}:{action}. Estas son las ocho que se aplican a las contraseñas de dispositivo:

Leer una ruta requiere el permiso :read correspondiente. Crear, modificar, mover, copiar o eliminar requiere :write. La ruta determina si la aplicación solicita acceso de cuenta o buzón, por lo que una contraseña limitada a un buzón no puede acceder a Account Drive ni a otro buzón.

La pantalla Sync devices ofrece únicamente permisos adecuados para una aplicación de sincronización. Los permisos de facturación no forman parte de una contraseña de dispositivo.

Permisos para compartir y purgar

El formulario de contraseña de dispositivo puede mostrar los permisos :share y :purge cuando la cuenta tiene derecho a ellos. La protección actual de rutas WebDAV solo asigna operaciones de archivo a :read y :write, así que no supongas que seleccionar uno de esos permisos añade a WebDAV un comando para crear enlaces compartidos o eliminar de forma permanente.

En WebDAV, un DELETE normal requiere :write y mueve el archivo a la papelera. WebDAV no permite sustituir un archivo en su ubicación ni realizar un purgado permanente. Utiliza la interfaz de Drive para esas tareas.

Seguridad de los nombres de archivo

Los nombres de archivos y carpetas deben ser seguros en distintos sistemas operativos. Se rechazan los nombres vacíos, separadores de ruta, caracteres de control, caracteres de nombre engañosos y nombres que entrarían en conflicto tras la normalización de Windows o Unicode. Los nombres pueden tener hasta 255 caracteres visibles.

Si una aplicación recibe un error de validación, cambia el nombre del elemento en la aplicación e inténtalo de nuevo. No intentes eludir el error colocando una ruta dentro de un nombre de archivo.

Cargas por fragmentos

Los archivos pequeños pueden usar un PUT normal. Los clientes compatibles con el flujo de carga por fragmentos v2 de Nextcloud pueden crear una sesión de carga en /dav/uploads/{session-uuid}/, subir fragmentos numerados y usar después MOVE para ensamblar el archivo en su ubicación final.

Los límites de carga pueden variar según la implementación y el cliente. Trata una sesión fallida o caducada como un nuevo intento de carga. Si otro cliente crea primero el destino, utiliza la respuesta de conflicto para elegir otro nombre o actualiza la carpeta antes de reintentarlo.

Registro de auditoría

Los cambios realizados correctamente mediante Sync aparecen en el historial de actividad de Drive. El registro identifica el elemento afectado, la acción, la hora y la contraseña de dispositivo utilizada, para que un administrador pueda investigar cambios inesperados y revocar la contraseña correspondiente.

Los clientes que utilizan el feed de cambios de Drive pueden ver los cambios realizados mediante WebDAV. Si el servicio solicita una resincronización completa, reconstruye la vista local a partir de una instantánea nueva antes de continuar con el cursor guardado.

Límites de frecuencia

Las solicitudes de Drive Sync están limitadas para proteger el servicio y tus archivos. Si un cliente recibe 429, reduce la concurrencia, respeta Retry-After cuando se proporcione y vuelve a intentar una operación pequeña antes de reanudar el trabajo.

Disponibilidad

Drive Sync está disponible en producción. Las cuentas necesitan acceso a Drive, y los permisos disponibles para las contraseñas de dispositivo siguen dependiendo de la cuenta, el buzón, el plan y la persona que crea la contraseña. Los clientes de White Label utilizan el mismo servicio Drive Sync. Copia siempre la URL actual desde Sync devices en vez de construirla.

Siguientes pasos

• Para la configuración de usuarios finales, consulta la descripción general de Drive Sync.
• Para la interfaz del panel que emite contraseñas de dispositivo, consulta Sync devices.
• Para los equivalentes de estas operaciones en la API REST y MCP, consulta Descripción general de la API de Drive y Scopes y permisos de la API de Drive.
• Para el modelo de almacenamiento y cuotas que la sincronización comparte con el resto del sistema, consulta Explicación de las cuotas de almacenamiento agrupado.