SPB Git

Repository Public

25 entries at the root
History

Latest commit chore: standardize SP Boucher source headers and attribution 9aa92eb

NameLast commitUpdated
app chore: standardize SP Boucher source headers and attribution
components chore: standardize SP Boucher source headers and attribution
docs docs: legendary README — icon, logo, live spbgit badges, author
lib chore: standardize SP Boucher source headers and attribution
prisma chore: standardize SP Boucher source headers and attribution
public feat(v3): refonte Aurora — design system, shell repliable, palette ⌘K, DnD, accueil analytique,...
scripts chore: standardize SP Boucher source headers and attribution
types chore: standardize SP Boucher source headers and attribution
.env.example feat(v3.1): connexion par code courriel (Resend), audit fonctionnel (corbeille récursive,...
.gitignore chore: fichiers d'exécution (db/wal/shm/log) retirés du suivi git (remote-first, 2026-10-02)
.spb-source-governance.toml chore: standardize SP Boucher source headers and attribution
CLAUDE.md chore: standardize SP Boucher source headers and attribution
middleware.ts chore: standardize SP Boucher source headers and attribution
next-env.d.ts SPB Private Cloud v2.0 - Full-featured personal cloud
next.config.mjs chore: standardize SP Boucher source headers and attribution
package-lock.json feat: Excel/Word edit, PDF annotations, FileCard redesign & AI fixes
package.json chore: checkpoint v2 WIP before v3 redesign (2026-09-07)
postcss.config.mjs chore: standardize SP Boucher source headers and attribution
README.md docs: legendary README — icon, logo, live spbgit badges, author
server.ts chore: standardize SP Boucher source headers and attribution
spb.sh chore: standardize SP Boucher source headers and attribution
start-cloud.sh chore: standardize SP Boucher source headers and attribution
tailwind.config.ts chore: standardize SP Boucher source headers and attribution
TODO.md SPB Private Cloud v2.0 - Full-featured personal cloud
tsconfig.json SPB Private Cloud v2.0 - Full-featured personal cloud
README.md View source
SPB Cloud logo



SPB Cloud icon

# 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

cloud.spboucher.ai version plateforme licence author

Next.js React TypeScript Tailwind CSS Framer Motion Prisma SQLite iron-session Anthropic SDK Claude sharp pdf.js Tiptap CodeMirror tsx Resend

commits last commit activity language languages size branches tags clones

fichiers TS routes API pages composants modèles plugins IA WebDAV accents dépendances chiffrement auth

nœud port PM2 deploy tunnel


# Sommaire


# 🎯 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 Google 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 en localStorage et appliquées avant le premier rendu (script inline dans app/layout.tsx, clés dans lib/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/stats enrichi (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 /raw inexistante.
  • Route /admin/snapshots manquante (404) ; app/api/snapshots n'était pas versionné (.gitignore trop large).
  • SNAPSHOT_DISABLED=1 dé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çu mammoth, é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

text
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

bash
# 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 dev

L'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

bash
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 :

bash
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

  1. Connectez-vous en tant qu'admin
  2. Allez dans Administration > Clés API
  3. Cliquez Nouvelle clé
  4. 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)

bash
# Build de production
npm run build

# Lancer en production
PORT=5001 NODE_ENV=production npx tsx server.ts

# VPS (avec Nginx)

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) :

dockerfile
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.dev est autorisé et il ne livre qu'au propriétaire du compte. Vérifier le domaine puis régler MAIL_FROM.
  • npx prisma generate dans le dossier de l'app : le client Prisma mémorise le dossier prisma/ 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=1 pour ne pas créer de snapshot quotidien ; AUTH_DEBUG_CODES pour lire les codes dans les journaux (ignoré en production).
  • .gitignore : la règle sur les snapshots est ancrée à la racine (/snapshots/) pour que app/api/snapshots reste versionné.
  • Agent IA de sécurité : fail-open — si l'API Anthropic est indisponible, la connexion est autorisée.
  • Secret de session : lib/session.ts lit SESSION_SECRET et retombe sur une valeur par défaut codée en dur s'il est absent — toujours le définir en production.
  • CLAUDE.md est 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.

Clone spb-cloud

Anonymous clone and fetch. Pushing requires the owner's personal access token.

Snapshot of main

Files main
Menu

Theme