SPB Private Cloud
Cloud personnel privé, souverain, sécurisé et mobile-first.
Plus clean que Dropbox. Plus privé que Google Drive. 100 % local-first.
Author: Simon-Pierre Boucher
Sommaire
- 🎯 Qu'est-ce que SPB Cloud ?
- 📰 Journal des versions
- ✨ Fonctionnalités
- 🏗 Architecture
- 🧱 Stack technique
- 🗂 Arborescence du dépôt
- 🚀 Installation
- 🔧 Configuration
- 🖥 Pages
- 🔌 API
- 🗄 Base de données
- 🔐 Sécurité
- 🧪 Tests et vérifications
- 📦 Déploiement
- 🩺 Pièges connus
- 🗺 Roadmap
- 📊 Statistiques du projet
- 👤 Auteur
- 📄 Licence
🎯 Qu'est-ce que SPB Cloud ?
SPB Private Cloud est un cloud personnel auto-hébergé conçu pour offrir un contrôle total sur vos données. Aucune dépendance à Google, Dropbox ou iCloud. Vos fichiers restent chez vous, chiffrés, accessibles depuis n'importe quel appareil — navigateur, PWA installable sur iPhone, lecteur réseau WebDAV ou ligne de commande.
Production : https://cloud.spboucher.ai (nœud M2U64 du cluster MacLustr, port 5001, processus PM2 cloud).
Pourquoi SPB Cloud ?
| SPB Cloud | Google Drive | Dropbox | |
|---|---|---|---|
| Propriété des données | Vous | Dropbox | |
| Chiffrement at-rest | AES-256-GCM | Oui (leur clé) | Oui (leur clé) |
| IA intégrée | Claude (Anthropic) | Gemini (limité) | Non |
| OCR intelligent | Oui (Vision IA) | Basique | Non |
| Coût mensuel | 0 $ (auto-hébergé) | 2,99 $/mois+ | 11,99 $/mois+ |
| Code source | Accès complet | Fermé | Fermé |
| Multi-utilisateur | Oui (rôles) | Oui | Oui |
| 2FA TOTP | Oui | Oui | Oui |
| API REST | Oui | Oui | Oui |
Famille
SPB Cloud est une application seule : pas de client macOS ou iOS dédié. L'accès natif passe par la PWA
(public/manifest.webmanifest), par WebDAV (https://cloud.spboucher.ai/dav, montable dans le Finder) et par la
CLI spb.sh. Dépôt : git.spboucher.ai/spb-cloud.
📰 Journal des versions
v3.1 — Connexion par code courriel, audit fonctionnel, réorganisation IA (2026-09-07)
Connexion par code courriel (Resend) — méthode par défaut : saisir son adresse, recevoir un code à 6 chiffres
(10 min, 5 essais, renvoi 30 s), le saisir. Le code est stocké haché dans le cookie de session chiffré (aucune
table). Routes POST /api/auth/otp/request et /verify ; envoi via lib/mailer.ts (Resend REST,
RESEND_API_KEY, MAIL_FROM). ⚠ Sans domaine vérifié dans Resend, seul onboarding@resend.dev est autorisé et il
ne livre qu'au propriétaire du compte : vérifier spboucher.ai dans Resend puis mettre
MAIL_FROM="SPB Cloud <no-reply@spboucher.ai>" pour que les autres utilisateurs reçoivent leurs codes. Connexion
par mot de passe conservée (administration).
Audit fonctionnel (11 correctifs) — suppression de dossier = corbeille récursive (plus de fichiers orphelins ni
de contenu effacé du disque), restauration fidèle (dossier d'origine recréé), purge réelle (contenu + versions +
vignettes) et purge horaire des > 30 j (server.ts), partage de dossier (POST /api/shares {folderId}, page
publique avec navigation, ZIP, mot de passe via cookie signé), sous-dossiers héritant de l'espace partagé, quotas
cohérents (chunks, duplication, corbeille exclue), duplication conservant l'extension, validations 404/400,
notifications d'upload, WebDAV DELETE → corbeille. Migration : scripts/migrations/apply-2026-09-07-audit.ts
(idempotente) puis npx prisma generate dans le dossier de l'app (le client Prisma mémorise le dossier
prisma/ au moment de la génération).
Réorganisation IA des espaces partagés (scripts/organize/) — extract.ts (Claude Opus 5 : vision pour les
photos, PDF natif, texte/Office), dupes.ts (SHA-256), plan.ts (arborescence + noms par espace, albums photo par
ordre de numérisation), apply.ts --dry-run puis apply.ts (sauvegarde VACUUM INTO, journal
data/applied.jsonl), verify.ts, rollback.ts. Appliqué le 2026-09-07 : 9 espaces, 1 171 fichiers
renommés/déplacés, 85 dossiers créés, 44 anciens supprimés, 78 doublons identiques isolés dans « 99 Doublons
identiques ». data/ est ignoré par git (métadonnées personnelles).
Après la v3.1 (journal git) : dossiers racine regroupés par espace partagé dans l'explorateur, la grille et
l'arbre latéral (0038527) ; état déployé sur M2U64 adopté comme source de vérité, fichiers d'exécution
(db/wal/shm/log) retirés du suivi git (remote-first, 2026-10-02).
Nouveautés v3 « Aurora » (2026-09-07)
Refonte complète du front-end, déployée sur cloud.spboucher.ai (M2U64, PM2 cloud).
Design system
- Tokens sémantiques (
canvas,surface,elevated,line), thème clair / sombre / système, 7 couleurs d'accent au choix (Aurore, Océan, Glacier, Forêt, Corail, Ambre, Améthyste) appliquées à toute l'interface via--accent-*. - Police Geist locale (plus d'appel à Google Fonts), verre dépoli, ombres douces, animations réductibles (préférence « Réduire les animations »).
- Densité des listes (confortable / compacte). Préférences dans
⌘,— persistées enlocalStorageet appliquées avant le premier rendu (script inline dansapp/layout.tsx, clés danslib/prefs.ts).
Coquille
- Barre latérale repliable en rail (
⌘B), sections Dossiers / Espaces / Outils / Administration / Tags, jauge de stockage, menu utilisateur. - Barre supérieure avec fil d'Ariane (cible de dépôt), bouton Envoyer, assistant IA, notifications, thème.
- Palette de commandes
⌘K(ou/) : recherche de fichiers et dossiers en direct, navigation, actions (envoyer, nouveau dossier, thème, préférences, déconnexion), historique des commandes. - Mobile : barre d'onglets iOS-like, tiroir glissable, PWA installable (
manifest.webmanifest, icônes,viewport-fit=cover).
Explorateur
- Liste avec en-tête collant et colonnes triables, grille avec vignettes et actions rapides, sélection par plage (⇧-clic), clic droit → menu contextuel, navigation clavier complète.
- Glisser-déposer : fichiers du bureau (overlay plein écran), déplacement interne vers dossiers, arbre latéral (auto-expansion) et fil d'Ariane ; déplacement multiple.
- Liens profonds
?file=,?upload=1,?new=1(utilisés par la palette, la barre supérieure et l'accueil). - Aperçu : plein écran réel, balayage tactile, panneau d'informations et versions refaits.
Accueil et administration
- Bandeau vivant, anneau de stockage par catégorie, activité sur 14 jours, KPI, « Reprendre », favoris, fichiers volumineux.
GET /api/admin/statsenrichi (rétro-compatible) :byCategory,activityByDay,favoriteCount,trashCount,versionCount,largestFiles.
Correctifs
- Recherche
/api/files?search=:mode: "insensitive"(non supporté par Prisma/SQLite) renvoyait 500. - Limiteur de débit : 600 req/min/IP et exemption des aperçus/flux (une grille de 50 vignettes dépassait l'ancien plafond de 100).
- Vignettes de l'accueil pointaient vers une route
/rawinexistante. - Route
/admin/snapshotsmanquante (404) ;app/api/snapshotsn'était pas versionné (.gitignoretrop large). SNAPSHOT_DISABLED=1désactive le snapshot quotidien (utile pour un serveur de staging).
✨ Fonctionnalités
Gestion de fichiers
- Upload multi-fichiers avec drag & drop ; upload par morceaux (
POST /api/files/upload-chunk) - Upload depuis caméra mobile
- Rename, delete, move, duplicate
- Organisation en dossiers imbriqués
- Breadcrumb navigation
- Vue grille et liste
- Sélection multiple + actions en lot
- Téléchargement de dossiers en ZIP
- Progress bar d'upload
- Corbeille avec restauration fidèle et purge automatique après 30 jours
- Favoris, récents, commentaires, métadonnées étendues, annotations
- Versions de fichiers avec diff et restauration (10 versions par fichier par défaut,
MAX_VERSIONS_PER_FILE)
Preview de fichiers
- Images (JPG, PNG, GIF, WebP, SVG)
- Vidéos (MP4, WebM, MOV)
- Audio (MP3, WAV, OGG) avec waveform (wavesurfer.js)
- PDF avec navigation de pages et annotations (pdf.js, pdf-lib)
- Code source avec syntax highlighting (20+ langages) et éditeur CodeMirror
- Markdown avec rendu
- CSV/JSON avec tableau interactif
- Archives ZIP (exploration du contenu)
- Excel (lecture et édition,
xlsx) et Word (aperçumammoth, édition Tiptap)
Intelligence artificielle (Claude)
Modèle appelé par le code : claude-opus-4-6 (lib/ai.ts, app/api/ai/*, lib/ai-security.ts) ; les scripts de
réorganisation utilisent claude-opus-5 (scripts/organize/common.ts).
- Recherche sémantique : trouvez des fichiers par description naturelle
- Chat IA et agent IA : posez des questions sur vos fichiers
- Auto-tagging : classification automatique par contenu
- OCR intelligent : extraction de texte depuis images et PDFs
- Description IA : génération automatique de descriptions
- Agent de sécurité des connexions : chaque connexion est analysée (adresse, pays, appareil, historique des 30 dernières sessions) et peut être refusée ; en cas d'indisponibilité de l'API, la connexion est autorisée (fail-open)
Sécurité
- Connexion par code courriel à 6 chiffres (méthode par défaut) ou par mot de passe
- Hash bcrypt pour les mots de passe
- Authentification 2FA TOTP (Google Authenticator, Authy)
- Chiffrement AES-256-GCM at-rest
- Sessions HTTP-only cookies (iron-session)
- Rate limiting sur le login
- CSRF protection
- Validation des types de fichiers
- Appareils et sessions de connexion consultables et révocables (
/dashboard/security)
Multi-utilisateur et espaces partagés
- Système de rôles : Admin, User, Viewer
- Gestion CRUD des utilisateurs, profil et avatar
- Permissions par rôle
- Logs d'activité par utilisateur
- Espaces partagés avec membres et quota (500 Go par défaut), sous-dossiers héritant de l'espace
Partage sécurisé
- Liens de partage avec token unique, pour un fichier ou un dossier (navigation, ZIP)
- Protection par mot de passe optionnel
- Date d'expiration configurable
- Mode téléchargement ou aperçu seul
- Désactivation instantanée
- Gestion centralisée des liens
Sauvegardes et snapshots
- Backup complet (DB + fichiers) en ZIP
- Backup incrémental
- Historique des backups avec statut
- Suppression des anciens backups
- Snapshot quotidien automatique (7 conservés), restauration depuis l'administration
Gestionnaire de mots de passe
- Coffre personnel (
/dashboard/passwords), entrées chiffrées en AES-256-GCM
Notifications
- Notifications en temps réel (polling 30 s)
- Badge avec compteur non-lus
- Types : upload, backup, IA, partage
- Marquer comme lu / tout lire
API REST publique, WebDAV, CLI
- Authentification par clé API (Bearer token)
- Génération et révocation de clés
- Permissions configurables (read, write, admin)
- Expiration optionnelle des clés
- Endpoints :
GET/POST /api/v1/files,GET/POST /api/v1/folders - WebDAV sur
/dav(authentification Basic, dossier virtuel « Shared Spaces ») - CLI
spb.sh:config,upload,upload-dir,ls,folders
Interface
- Design mobile-first (iPhone optimisé)
- Mode clair / sombre / système avec persistance, 7 couleurs d'accent
- Touch targets 44 px minimum
- Bottom sheet modals sur mobile
- Safe area support (notch iPhone)
- Sidebar collapsible
- Animations Framer Motion
- Typographie Geist locale
- Vue graphe des fichiers (
/dashboard/graph)
🏗 Architecture
flowchart TB
subgraph clients["Clients"]
browser["Navigateur / PWA"]
finder["Finder, clients WebDAV"]
cli["CLI spb.sh"]
visitor["Visiteur d'un lien partagé"]
end
tunnel["MacLustr Tunnel<br/>(Caddy TLS + WireGuard)"]
subgraph node["M2U64 — PM2 « cloud » :5001"]
server["server.ts (tsx)<br/>HTTP + tâches horaires"]
dav["lib/webdav.ts<br/>/dav"]
mw["middleware.ts<br/>session · CSRF · 600 req/min/IP · en-têtes"]
next["Next.js 14 (App Router)<br/>pages + /api"]
libs["lib/ : auth, otp, storage, trash,<br/>filecrypto, snapshot, backup, ai"]
db[("SQLite<br/>Prisma 5")]
disk[/"uploads/ · snapshots/ · backups/"/]
end
resend["Resend (codes courriel)"]
claude["API Anthropic (Claude)"]
browser --> tunnel
finder --> tunnel
cli --> tunnel
visitor --> tunnel
tunnel --> server
server -- "/dav" --> dav
server -- "le reste" --> mw --> next --> libs
dav --> libs
libs --> db
libs --> disk
libs -. "codes" .-> resend
libs -. "IA, sécurité des connexions" .-> claude
server.ts est le point d'entrée : un serveur HTTP qui confie /dav au gestionnaire WebDAV et tout le reste à
Next.js. Au démarrage et toutes les heures, il lance le snapshot quotidien (sauf SNAPSHOT_DISABLED=1), la purge
de la corbeille (> 30 jours) et le nettoyage des morceaux d'upload orphelins.
Connexion par code courriel
sequenceDiagram
participant U as Utilisateur
participant A as /api/auth/otp
participant R as Resend
participant S as Agent IA de sécurité
participant D as SQLite
U->>A: POST /request (adresse)
A->>A: code à 6 chiffres, haché (SHA-256 + sel) dans le cookie chiffré
A->>R: envoi du code (MAIL_FROM)
R-->>U: courriel (valide 10 min)
U->>A: POST /verify (code, 5 essais au plus)
A->>S: completeLogin : IP, pays, appareil, 30 dernières sessions
alt décision « refuse »
S-->>A: refus motivé
A->>D: LoginSession refused_by_ai + journal d'activité
A-->>U: 403
else décision « allow » (ou API indisponible)
A->>D: LoginSession active
A-->>U: session iron-session (24 h) + jeton CSRF
end
🧱 Stack technique
| Couche | Technologie | Version (lockfile) | Rôle |
|---|---|---|---|
| Framework | Next.js (App Router) + serveur personnalisé server.ts |
14.2.35 | pages, API, point d'entrée |
| UI | React, Tailwind CSS, Framer Motion, lucide-react | 18.3.1 · 3.4.19 · 12.34.0 | interface, animations, icônes |
| Langage | TypeScript, exécuté par tsx |
5.9.3 · 4.21.0 | — |
| Données | Prisma ORM + SQLite | 5.22.0 | 19 modèles |
| Sessions | iron-session (cookie spb-cloud-session) |
8.0.4 | sessions chiffrées HTTP-only |
| Auth | bcryptjs, otplib (TOTP), qrcode | 3.0.3 · 13.3 · 1.5.4 | mots de passe, 2FA |
| Courriel | Resend (API REST, lib/mailer.ts) |
— | codes de connexion |
| IA | @anthropic-ai/sdk |
0.75.0 | recherche, chat, agent, tags, OCR, sécurité |
| Fichiers | sharp, archiver, jszip, mime-types | 0.34.5 · 7.0 · 3.10 | vignettes, ZIP |
| Aperçus | pdfjs-dist, pdf-lib, mammoth, xlsx, papaparse, wavesurfer.js, react-markdown | 5.4.624 · 1.17 · 1.11 · 0.18 · 5.5 · 7.12 | PDF, Word, Excel, CSV, audio, Markdown |
| Éditeurs | CodeMirror 6 (13 langages), Tiptap | 6 · 3.20 | code, Word |
| Débit | rate-limiter-flexible + limiteur Edge du middleware | 9.1.1 | login 5/min, global 600/min/IP |
| Exploitation | PM2, mld, MacLustr Tunnel |
— | processus, déploiement, exposition |
🗂 Arborescence du dépôt
spb-cloud/ 242 fichiers suivis
├── server.ts serveur HTTP : Next.js + WebDAV (/dav) + snapshot quotidien + entretien horaire
├── middleware.ts session, CSRF, limiteur 600 req/min/IP, en-têtes de sécurité
├── app/
│ ├── admin/ 9 pages : accueil, activité, clés API, backup, réglages (2FA), espaces partagés,
│ │ liens partagés, snapshots, utilisateurs
│ ├── api/ 74 fichiers route.ts (108 handlers)
│ │ ├── admin/ activity, stats
│ │ ├── ai/ agent, chat, describe, files, ocr, search, tag
│ │ ├── auth/ login, logout, session, otp (request, verify), 2fa (setup, verify, disable),
│ │ │ change-password, devices
│ │ ├── backup/ CRUD backups
│ │ ├── files/ CRUD + bulk + upload-chunk + versions (diff, restore) + annotations, comments,
│ │ │ content, download, duplicate, favorite, metadata, preview, save-edit, stream, tags
│ │ ├── folders/ CRUD dossiers + ZIP download
│ │ ├── graph/ vue graphe
│ │ ├── keys/ CRUD clés API
│ │ ├── notifications/ notifications
│ │ ├── passwords/ gestionnaire de mots de passe
│ │ ├── shared-spaces/ espaces partagés, membres, stockage
│ │ ├── shared/ · shares/ page publique d'un lien · gestion des liens
│ │ ├── snapshots/ liste, création, restauration, suppression
│ │ ├── tags/ · trash/ · users/
│ │ └── v1/ API REST publique (files, folders)
│ ├── dashboard/ 11 pages : accueil, fichiers, dossier, favoris, récents, corbeille, graphe,
│ │ mots de passe, sécurité, espace partagé, partagés avec moi
│ ├── login/ · shared/[token]/ connexion · page de partage public
│ ├── fonts/ Geist (locale)
│ └── layout.tsx · globals.css
├── components/ 72 composants : admin, ai, auth, dashboard, files, folders, layout, preview
│ │ (11 plugins + éditeurs), tags, theme, ui
├── lib/ 25 modules : activity, ai, ai-security, auth, backup, config, crypto, encryption,
│ filecrypto, geo, login-complete, mailer, notifications, otp, prefs, prisma,
│ rate-limit, session, shareAccess, snapshot, storage, trash, ua-parser, utils, webdav
├── prisma/
│ ├── schema.prisma 19 modèles (SQLite)
│ └── seed.ts création du compte admin initial
├── scripts/
│ ├── migrations/ 2026-09-07-audit.sql + apply-2026-09-07-audit.ts (idempotente)
│ ├── organize/ extract, dupes, plan, apply, verify, rollback, common (réorganisation IA)
│ └── encrypt-migrate.ts migration vers le chiffrement des fichiers
├── public/ icônes PWA, manifest.webmanifest, pdf.js
├── types/ types TypeScript
├── spb.sh CLI (clé API)
├── start-cloud.sh lanceur de production (build si absent, puis tsx server.ts)
├── TODO.md · CLAUDE.md liste de travail · cahier des charges d'origine
└── uploads/ stockage des fichiers (ignoré par git)🚀 Installation
Prérequis
- Node.js 18+ (le lanceur de production utilise Node 22)
- npm 9+
- Clé API Anthropic (pour les fonctionnalités IA)
- Clé API Resend et domaine vérifié (pour la connexion par code courriel)
Installation rapide
# 1. Cloner le dépôt
git clone gitsrv:srv/git/spb-cloud.git
cd spb-cloud
# 2. Installer les dépendances (postinstall : prisma generate)
npm install
# 3. Configurer l'environnement
cp .env.example .env
# Éditer .env avec vos valeurs
# 4. Initialiser la base de données
npx prisma db push
npx tsx prisma/seed.ts # ou : npm run db:setup (les deux à la fois)
# 5. Lancer l'application
npm run devL'application est accessible sur http://localhost:5001 (PORT=5001 dans les scripts npm),
le point WebDAV sur http://localhost:5001/dav.
| Script npm | Commande |
|---|---|
npm run dev |
PORT=5001 tsx server.ts |
npm run build |
next build |
npm start |
next build && PORT=5001 NODE_ENV=production tsx server.ts |
npm run lint |
next lint |
npm run db:generate · db:push · db:seed · db:studio · db:setup |
Prisma |
Compte initial
prisma/seed.ts crée un compte admin (rôle Admin) avec un mot de passe initial défini dans ce fichier.
Important : changez le mot de passe après la première connexion via Admin > Utilisateurs, et activez la 2FA dans Admin > Réglages.
CLI spb.sh
cp spb.sh ~/bin/spb && chmod +x ~/bin/spb
spb config # URL du serveur (défaut https://cloud.spboucher.ai) + clé API → ~/.spb/config (0600)
spb upload <fichier> [folder_id]
spb upload-dir <dossier> [folder_id]
spb ls [folder_id]
spb folders🔧 Configuration
Noms des variables seulement (.env.example et variables lues par le code) :
| Variable | Rôle |
|---|---|
DATABASE_URL |
base SQLite (file:./dev.db) |
SESSION_SECRET (lu par lib/session.ts ; .env.example nomme SESSION_PASSWORD) |
secret des cookies iron-session (32 caractères minimum) |
ENCRYPTION_KEY, FILE_ENCRYPTION_KEY |
clés de chiffrement AES-256-GCM (données, fichiers) |
ANTHROPIC_API_KEY |
fonctionnalités IA et agent de sécurité des connexions |
RESEND_API_KEY, MAIL_FROM |
envoi des codes de connexion ; MAIL_FROM doit appartenir à un domaine vérifié dans Resend |
AUTH_DEBUG_CODES |
staging uniquement : journalise les codes côté serveur (ignoré en production) |
UPLOAD_DIR, BACKUP_DIR, SNAPSHOT_DIR |
répertoires de stockage (./uploads, ./backups, ./snapshots) |
MAX_FILE_SIZE, NEXT_PUBLIC_MAX_FILE_SIZE |
taille maximale d'un fichier (octets) |
MAX_VERSIONS_PER_FILE |
versions conservées par fichier (10 par défaut) |
SNAPSHOT_DISABLED |
1 désactive le snapshot quotidien |
CORS_ORIGIN |
origine autorisée |
PORT, NODE_ENV |
port d'écoute (5001), mode |
ORG_CONCURRENCY |
parallélisme des scripts scripts/organize/ |
🖥 Pages
| Zone | Routes |
|---|---|
| Public | /login, /shared/[token] |
| Tableau de bord | /dashboard, /dashboard/files, /dashboard/folder/[id], /dashboard/favorites, /dashboard/recent, /dashboard/trash, /dashboard/graph, /dashboard/passwords, /dashboard/security, /dashboard/shared-space/[id], /dashboard/shared-with-me |
| Administration | /admin, /admin/activity, /admin/api-keys, /admin/backup, /admin/settings, /admin/shared-spaces, /admin/shares, /admin/snapshots, /admin/users |
Raccourcis : ⌘K ou / (palette), ⌘B (barre latérale), ⌘, (préférences). Liens profonds ?file=,
?upload=1, ?new=1.
🔌 API
API REST publique (/api/v1)
Toutes les requêtes à l'API publique nécessitent un header Authorization :
curl -H "Authorization: Bearer spb_votre_cle_api" \
https://cloud.spboucher.ai/api/v1/files| Méthode | Endpoint | Description |
|---|---|---|
GET |
/api/v1/files |
Lister les fichiers de la racine (100 au plus, du plus récent au plus ancien) |
GET |
/api/v1/files?folderId=xxx |
Fichiers d'un dossier |
POST |
/api/v1/files |
Envoyer un fichier |
GET |
/api/v1/folders |
Lister les dossiers |
POST |
/api/v1/folders |
Créer un dossier |
Générer une clé API
- Connectez-vous en tant qu'admin
- Allez dans Administration > Clés API
- Cliquez Nouvelle clé
- Copiez la clé générée (affichée une seule fois ; seul son hash SHA-256 est stocké)
WebDAV (/dav)
Authentification Basic (nom d'utilisateur ou courriel + mot de passe). Méthodes gérées : OPTIONS, PROPFIND,
PROPPATCH, GET, HEAD, PUT, DELETE (→ corbeille), MKCOL, MOVE, COPY, LOCK, UNLOCK. Les espaces
partagés apparaissent dans le dossier virtuel « Shared Spaces ».
API interne (session + CSRF)
Les 74 fichiers de routes et leurs méthodes
Route (/api/…) |
Méthodes |
|---|---|
admin/activity · admin/stats |
GET |
ai/agent · ai/chat · ai/describe · ai/ocr · ai/search · ai/tag |
POST |
ai/files |
GET |
auth/login · auth/logout · auth/change-password |
POST |
auth/otp/request · auth/otp/verify |
POST |
auth/2fa/setup · auth/2fa/verify · auth/2fa/disable |
POST |
auth/session |
GET |
auth/devices · auth/devices/[id] |
GET · DELETE |
backup |
GET, POST, DELETE |
files |
GET, POST |
files/bulk · files/upload-chunk |
POST |
files/[id] |
GET, PATCH, DELETE |
files/[id]/annotations |
GET, PUT |
files/[id]/comments · files/[id]/comments/[commentId] |
GET, POST · PATCH, DELETE |
files/[id]/content |
PUT |
files/[id]/download · files/[id]/preview · files/[id]/stream |
GET |
files/[id]/duplicate · files/[id]/favorite · files/[id]/save-edit |
POST |
files/[id]/metadata |
GET, PATCH |
files/[id]/tags · files/[id]/tags/[tagId] |
GET, POST · DELETE |
files/[id]/versions |
GET, POST |
files/[id]/versions/[versionId] · …/diff · …/restore |
GET · GET · POST |
folders · folders/[id] · folders/[id]/download |
GET, POST · GET, PATCH, DELETE · GET |
graph |
GET |
keys · keys/[id] |
GET, POST · DELETE |
notifications · notifications/[id] |
GET, POST · PATCH |
passwords · passwords/[id] |
GET, POST · GET, PATCH, DELETE |
shared-spaces · shared-spaces/mine |
GET, POST · GET |
shared-spaces/[id] · …/members · …/storage |
GET, PATCH, DELETE · POST, DELETE · GET |
shared/[token] · shared/[token]/verify |
GET · POST |
shares · shares/[id] |
GET, POST · PATCH, DELETE |
snapshots · snapshots/[id] · snapshots/[id]/restore |
GET, POST · DELETE · POST |
tags · tags/[id] |
GET, POST · PATCH, DELETE |
trash |
GET, POST |
users · users/[id] · users/[id]/avatar |
GET, POST · PATCH, DELETE · GET |
users/profile · users/public |
GET, PATCH · GET |
v1/files · v1/folders |
GET, POST |
Chemins publics (sans session, middleware.ts) : /login, /api/auth/login, /api/auth/2fa/verify,
/api/auth/otp/, /shared, /api/shared, /api/v1/, ressources statiques et icônes.
🗄 Base de données
SQLite via Prisma (prisma/schema.prisma, 19 modèles).
| Modèle | Description |
|---|---|
User |
Utilisateurs avec rôles (admin, user, viewer) et 2FA |
File |
Fichiers avec métadonnées, IA, chiffrement, corbeille (deletedAt) |
Folder |
Dossiers imbriqués (arbre récursif) |
SharedLink |
Liens de partage sécurisés (fichier ou dossier) |
Permission |
Permissions par dossier/utilisateur |
ActivityLog |
Journal d'activité |
FileMetadata |
Métadonnées étendues (favoris, annotations) |
Tag / FileTag |
Système de tags |
FileVersion |
Versioning de fichiers |
Comment |
Commentaires sur les fichiers |
Notification |
Notifications utilisateur |
ApiKey |
Clés API REST (hash SHA-256) |
BackupLog |
Historique des backups |
Snapshot |
Snapshots quotidiens |
PasswordEntry |
Entrées du gestionnaire de mots de passe (chiffrées) |
SharedSpace / SharedSpaceMember |
Espaces partagés, membres, quota |
LoginSession |
Sessions de connexion : appareil, navigateur, pays, décision de l'agent IA |
erDiagram
User ||--o{ File : "possède"
User ||--o{ Folder : "possède"
Folder ||--o{ Folder : "contient"
Folder ||--o{ File : "contient"
File ||--o{ FileVersion : "versions"
File ||--o{ FileTag : "étiquettes"
Tag ||--o{ FileTag : "étiquette"
File ||--o{ Comment : "commentaires"
File ||--o| FileMetadata : "métadonnées"
File ||--o{ SharedLink : "partagé par"
Folder ||--o{ SharedLink : "partagé par"
SharedSpace ||--o{ SharedSpaceMember : "membres"
SharedSpace ||--o{ Folder : "dossiers"
User ||--o{ SharedSpaceMember : "membre de"
User ||--o{ LoginSession : "connexions"
User ||--o{ ApiKey : "clés"
User ||--o{ PasswordEntry : "coffre"
User ||--o{ Notification : "reçoit"
Le diagramme est un résumé de lecture ; la référence est prisma/schema.prisma.
🔐 Sécurité
SPB Cloud est conçu avec la sécurité en priorité :
| Mesure | Détail |
|---|---|
| Mots de passe | Hash bcrypt (12 rounds) ; mots de passe de liens partagés : bcrypt (10 rounds) |
| Code courriel | 6 chiffres, 10 minutes, 5 essais, renvoi après 30 s ; haché (SHA-256 + sel) dans le cookie chiffré |
| 2FA | TOTP RFC 6238 (Google Authenticator) |
| Sessions | Cookies HTTP-only, SameSite=Lax, secure en production, expiration 24 h (spb-cloud-session), liées à un enregistrement LoginSession |
| CSRF | cookies SameSite=Lax + jeton de session x-csrf-token validé par middleware.ts lorsqu'il est présent ; exemptions limitées aux points publics |
| Chiffrement | AES-256-GCM avec clé dérivée (scrypt) |
| Rate limiting | 5 tentatives/min sur login ; 600 requêtes/min/IP globalement (aperçus et flux exemptés) |
| En-têtes | X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, X-XSS-Protection |
| Agent IA de sécurité | analyse de chaque connexion, refus possible, journalisation dans LoginSession |
| API Keys | SHA-256 hash, jamais stockées en clair |
| Upload | Limite de taille configurable |
| Données personnelles | uploads/, backups/, /snapshots/, .env* et scripts/organize/data/ sont ignorés par git |
🧪 Tests et vérifications
Le dépôt ne contient pas de suite de tests automatisés (aucun fichier *.test.*, aucun script test dans
package.json). Vérifications disponibles :
| Commande | Rôle |
|---|---|
npm run lint |
ESLint (next lint) |
npm run build |
compilation et vérification des types par next build |
npx tsx scripts/organize/verify.ts |
contrôle d'une réorganisation IA appliquée |
npx tsx scripts/organize/apply.ts --dry-run |
simulation avant application |
📦 Déploiement
Production (MacLustr)
| Élément | Valeur |
|---|---|
| Domaine | https://cloud.spboucher.ai (WebDAV public : https://cloud.spboucher.ai/dav) |
| Nœud · port | M2U64 · 5001 |
| Processus | PM2 cloud |
| Lanceur | start-cloud.sh : NODE_ENV=production, PORT=5001, next build si .next/BUILD_ID est absent, puis npx tsx server.ts |
| Orchestration | mld (passerelle M1M32) ; le dossier déployé est un clone git de ce dépôt (remote-first depuis le 2026-10-02) |
| Exposition | MacLustr Tunnel (Caddy + WireGuard, passerelle OVH BHS64) |
Modifier l'application : sur le nœud, dans le dossier déployé — build, pm2 restart cloud, puis
git commit / git push depuis le nœud.
Mac Studio / NAS (local)
# Build de production
npm run build
# Lancer en production
PORT=5001 NODE_ENV=production npx tsx server.tsVPS (avec Nginx)
server {
listen 443 ssl;
server_name cloud.votredomaine.com;
ssl_certificate /etc/letsencrypt/live/cloud.votredomaine.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/cloud.votredomaine.com/privkey.pem;
client_max_body_size 500M;
location / {
proxy_pass http://127.0.0.1:5001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
}Docker (optionnel)
Exemple indicatif (aucun Dockerfile n'est versionné dans le dépôt) :
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate
RUN npm run build
EXPOSE 5001
CMD ["npm", "start"]🩺 Pièges connus
- Resend sans domaine vérifié : seul
onboarding@resend.devest autorisé et il ne livre qu'au propriétaire du compte. Vérifier le domaine puis réglerMAIL_FROM. npx prisma generatedans le dossier de l'app : le client Prisma mémorise le dossierprisma/au moment de la génération.- Prisma + SQLite :
mode: "insensitive"n'est pas supporté (la recherche renvoyait 500). - Limiteur de débit : une grille de 50 vignettes = 50 requêtes ; d'où 600 req/min/IP et l'exemption des aperçus/flux.
- Staging :
SNAPSHOT_DISABLED=1pour ne pas créer de snapshot quotidien ;AUTH_DEBUG_CODESpour lire les codes dans les journaux (ignoré en production). .gitignore: la règle sur les snapshots est ancrée à la racine (/snapshots/) pour queapp/api/snapshotsreste versionné.- Agent IA de sécurité : fail-open — si l'API Anthropic est indisponible, la connexion est autorisée.
- Secret de session :
lib/session.tslitSESSION_SECRETet retombe sur une valeur par défaut codée en dur s'il est absent — toujours le définir en production. CLAUDE.mdest le cahier des charges d'origine (il mentionne PostgreSQL) ; le code utilise SQLite.
🗺 Roadmap
Fait
- Upload multi-fichiers + drag & drop
- Organisation en dossiers imbriqués
- Preview 10+ formats (PDF, images, vidéo, audio, code, markdown...)
- Partage sécurisé avec expiration et mot de passe
- Mode clair / sombre
- Multi-utilisateur avec rôles
- 2FA TOTP
- Recherche IA (Claude)
- Chat IA intégré
- Auto-tagging IA
- OCR intelligent (images + PDF)
- Chiffrement AES-256-GCM
- Système de backup
- Notifications
- API REST avec clés
- Actions en lot (supprimer, déplacer, ZIP, chiffrer)
- Interface mobile-first (iPhone optimisé)
- Corbeille (soft delete, purge à 30 jours) — v3.1
- Vignettes — v3
- WebDAV (
lib/webdav.ts) - Upload par morceaux (
/api/files/upload-chunk) - Couleurs d'accent, raccourcis clavier, glisser-déposer global et vers les dossiers, tri par colonnes — v3
- Connexion par code courriel, partage de dossier, espaces partagés, snapshots quotidiens
À venir
- Migration PostgreSQL
- HTTPS / SSL intégré
- Video streaming HLS
- Infinite scroll
- Docker Compose
- Sync multi-device
Liste de travail détaillée (non remise à jour depuis la v3) : TODO.md.
📊 Statistiques du projet
Comptées dans le dépôt au commit f09d3d7 :
| Mesure | Valeur |
|---|---|
| Fichiers suivis | 242 |
| Fichiers TypeScript / TSX | 215 (26 890 lignes) |
| Fichiers de routes API | 74 (108 handlers HTTP) |
| Pages | 23 |
| Composants | 72 |
| Plugins d'aperçu | 11 (archive, audio, code, CSV/JSON, Excel, image, Markdown, PDF, vidéo, Word, repli) |
| Modèles Prisma | 19 |
| Endpoints IA | 7 |
Modules lib/ |
25 |
| Dépendances | 57 (+ 19 de développement) |
👤 Auteur
Simon-Pierre Boucher — créateur et propriétaire ; conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
Développement assisté par Claude (Anthropic) : architecture, code, optimisation mobile. GitHub : github.com/simonpierreboucher02.
📄 Licence
Privée. © 2024-2026 SPB Private Cloud — Simon-Pierre Boucher. Tous droits réservés.