Files
CoHaiSe-CLOUD/backend
Gitea ActionsandEsiah 599784eec7
CD — Deployment / deploy (push) Failing after 0s
ci(pr): pipe PR payload to curl instead of writing /tmp/pr.json (#11)
PR automatique de fix/folder-traversal-user-rehome vers main.

---------

Co-authored-by: xEsiah <[email protected]>
Reviewed-on: #11
Reviewed-by: Esiah <[email protected]>
Co-authored-by: Gitea Actions <-[email protected]>
2026-10-19 11:26:21 +00:00
..

Cloud — modèle de données

Stockage privé de fichiers. Le contenu ne vit jamais dans la base : MariaDB ne décrit que des métadonnées, les octets restent sur le disque sous storage_locations.mount_path.

Le service existe et sert ce modèle : 10 routes sous /api/cloud (src/routes/{auth,folders,files}.ts). Le détail des endpoints, des droits et du déploiement est dans ../../docs/api.md, ../../docs/security.md et ../../docs/architecture.md.

Modèle de données

erDiagram
    roles ||--o{ users : "attribue"
    users ||--o{ user_sessions : "ouvre"
    users ||--o{ user_avatars : "a pour photo"
    users ||--o{ password_reset_tokens : "demande"
    users ||--o{ email_change_requests : "demande"
    users ||--o{ folders : "proprietaire"
    users ||--o{ files : "proprietaire"
    users ||--o{ folder_permissions : "beneficie"
    users ||--o{ chat_messages : "ecrit"
    users ||--o{ audit_logs : "trace"
    storage_locations ||--o{ folders : "contient"
    storage_locations ||--o{ files : "contient"
    storage_locations ||--o{ user_avatars : "contient"
    folders ||--o{ folders : "parent de"
    folders ||--o{ files : "contient"
    folders ||--o{ folder_permissions : "accede"
    files ||--o{ media_metadata : "decrit"
    files ||--o{ file_variants : "derive"

Tables

16 tables en base après 007 (share_links ayant été supprimée par 004). Seules celles marquées « /… » sont atteignables depuis le front.

Table Rôle Exposée par l'API
roles admin et user (le readonly de 002 a été retiré par 004) indirectement (users.role_slug)
users Comptes : prénom, nom, e-mail, mot de passe, quotas /auth/*
user_sessions Appareils connectés, révocation, expiration session interne
user_avatars Photo de profil, une ligne par compte non
password_reset_tokens Réinitialisation de mot de passe, hachée non (aucune route)
email_change_requests Validation du nouvel e-mail d'un compte non (aucune route)
storage_locations Volumes de stockage et quotas globaux non (interne à storage.ts)
folders Arborescence, avec access_type /folders
folder_permissions Droits nominatifs sur un dossier shared non (aucune route)
files Métadonnées de l'original, jamais ré-écrit /files
media_metadata Dimensions, durée, codecs, EXIF, couleur dominante non (galerie non exposée)
file_variants Miniatures et aperçus WebP dérivés non
chat_messages Salon d'un dossier : dossier (ON DELETE CASCADE), auteur (ON DELETE SET NULL), soft-delete /folders/:id/chat
settings Configuration clé-valeur non
audit_logs Piste d'audit non (écrit par audit())
schema_migrations Versions appliquées non

Trois notions à ne pas confondre

Notion Où elle vit Ce que c'est
Le fichier le disque les octets d'origine, jamais ré-encodés
La ligne files la base le nom, la taille, la somme de contrôle, le chemin
La ligne media_metadata la base ce qu'un lecteur sait du fichier : dimensions, durée, appareil

Un fichier dénué de media_metadata reste valide : un PDF ou un ZIP n'ont pas de dimensions. C'est le comportement voulu, une entrée de galerie non encore analysée doit rester listable.

Originaux intacts, aperçus dérivés

Aucun fichier téléversé n'est ré-encodé. Le contenu reçu est écrit tel quel et sa somme SHA-256 est mémorisée, ce qui sert à la fois de preuve d'intégrité et de détection de doublon. Les WebP d'aperçu sont des fichiers supplémentaires décrits par file_variants, avec un purpose valant thumbnail ou preview ; un UNIQUE sur (file_id, purpose) interdit d'en empiler deux du même type.

La conséquence assumée : une photo contient ses coordonnées GPS, et puisqu'aucun fichier n'est modifié, ces coordonnées restent lisibles dans l'original. Les aperçus WebP sont ré-encodés et ne les portent pas.

Trois types d'accès aux dossiers

folders.access_type porte l'intention, et non une garde :

Valeur Qui accède Écriture
private le propriétaire seul le propriétaire
shared le propriétaire et les comptes listés dans folder_permissions selon le niveau read, write ou admin
public tous les comptes de l'installation tous peuvent ajouter, personne ne supprime les fichiers d'autrui

Un seul dossier de l'instance porte is_system = 1, et l'unicité est réelle en base : la colonne générée system_marker vaut 1 pour lui et NULL pour tous les autres, donc un second dossier système viole uq_folders_system. chk_folders_system impose en outre qu'un dossier système soit public.

Les dossiers enfants d'un dossier public restent soumis à l'unicité de nom : deux enfants ne peuvent pas s'appeler pareil, puisque leur parent_id n'est pas NULL. La limite ne concerne que la racine, dont les éléments ont parent_id IS NULL.

Le niveau d'accès est vérifié à chaque requête en base, depuis la session : voir ../../docs/api.md.

Budget et plafond par utilisateur

Deux réglages distincts, tous deux portés par users :

Colonne Effet
quota_bytes volume total que le compte peut occuper, borné par chk_users_quota
max_file_bytes taille maximale d'un dépôt unique

used_bytes est maintenu par l'application et borné en base : impossible d'écrire used_bytes > quota_bytes, quelle que soit la requête. Le quota est en outre re-vérifié en transaction au moment de l'écriture. max_file_bytes, en revanche, ne peut pas être garanti par une contrainte, car il compare une ligne de files à une ligne d'users : c'est à l'application de le vérifier, sur la taille déclarée et sur la taille réellement reçue.

default_quota_bytes et max_upload_bytes dans settings ne sont pas des plafonds globaux, seulement les valeurs proposées à la création d'un compte.

Unicité après suppression logique

Un nom ou une adresse peut être réutilisé après une suppression logique, grâce à des colonnes générées :

active_email VARCHAR(255) GENERATED ALWAYS AS (IF(deleted_at IS NULL, email, NULL)) STORED,
UNIQUE KEY uq_users_email (active_email)

La ligne supprimée produit NULL, et en SQL plusieurs NULL ne sont pas égaux : l'index ne la voit plus. C'est cette propriété qui sert deux fois, pour libérer une adresse de compte et pour autoriser la réimportation d'un fichier au même nom.

Métadonnées : la part utile et le reste

Ce que la galerie filtre ou affiche est mis en colonnes indexées : taken_at, width, height, duration_ms, kind, video_codec, camera_make, camera_model, dominant_color. Le reste des EXIF, qui peut représenter une trentaine de réglages d'objectif pour quelques kilo-octets et n'est jamais lu, est facultatif et compressé dans extra_metadata. Rien n'oblige à le remplir.

Chemin physique

Le nom affiché n'entre jamais dans le chemin : ${MEDIA_DIR}/<slug>/<uuid><ext>, avec resolveInside() qui refuse toute cible hors base. Le choix de l'emplacement se fait parmi les storage_locations actifs, en privilégiant la plus grande marge disponible.

Migrations

Fichier Contenu
000_schema_migrations.sql table de suivi des versions
001_initial_schema.sql 11 tables, 17 clés étrangères, 14 CHECK
002_reference_data.sql rôles, emplacement principal, réglages
003_integrity_backstop.sql CHECK d'audit, interdiction du dossier parent de lui-même
004_cloud_requirements.sql identité complète, sessions, validation d'e-mail, avatar, access_type, médias, variantes, budget par compte, suppression des liens publics
005_storage_location_realign.sql mount_path réaligné sur /data/media, quota 400 Go, garde-fou sur les emplacements sans quota
006_public_folder.sql crée le dossier système « Public », retire les réglages devenus morts
007_chat.sql crée chat_messages, le salon d'un dossier (FK dossier ON DELETE CASCADE)

004 porte le passage d'un modèle de partage public vers un stockage privé : elle supprime share_links, scinde display_name en first_name et last_name, et remplace le plafond global max_upload_bytes par les deux colonnes portées par users. Elle a aussi supprimé le rôle readonly, qui venait d'une supposition et non d'un besoin formulé.

Une migration appliquée ne se modifie jamais : le checksum la fige. Voir ../../docs/deployment.md.

Sécurité (couche modèle)

  • Suppression d'un rôle encore attribué, ou d'un emplacement contenant des données : refusée par la base (ON DELETE RESTRICT).
  • Sessions et jetons stockés hachés en CHAR(64) ; password_changed_at permet de dater un changement.
  • Les identifiants de dossier et de fichier sont des UUID, non devinables.
  • audit_logs survit à la suppression d'un utilisateur (ON DELETE SET NULL) plus un instantané user_email, ip_address, user_agent.

En-têtes (CSP/HSTS), CORS et limitation de débit sont décrits dans ../../docs/security.md. Il n'y a pas de jeton CSRF : les écritures sont des POST/PUT/DELETE et le cookie de session est SameSite=Lax, ce qui bloque les écritures inter-origines.

Limites actuelles

  • La règle « ne pas supprimer les fichiers d'autrui » n'est pas en base. Aucune contrainte SQL ne peut exprimer « le propriétaire ou un administrateur » : elle ne vit que dans l'API, et une personne ouvrant un client SQL la contourne. audit_logs est le seul rempart réel.
  • max_file_bytes n'est pas appliqué en base (voir plus haut).
  • Les cycles profonds ne sont pas empêchés. chk_folders_not_self_parent bloque le parent direct de lui-même, mais A → B → A reste possible et demande un parcours WITH RECURSIVE au moment d'un déplacement.
  • Deux éléments racine peuvent porter le même nom, dossier ou fichier, puisque leur clé étrangère de parent vaut NULL.
  • extra_metadata n'est pas contraint en taille.
  • Partages publics par lien : retirés par 004 ; le seul espace partagé est le dossier système « Public » (006), ouvert à tout compte authentifié.
  • Les réglages allow_public_shares et default_share_expiry_days ont été supprimés par 006 (données mortes).