Music SP
Lecteur musical privé : la bibliothèque audio personnelle de son propriétaire, hébergée sur son propre cluster, protégée par des clés d'accès, diffusée en HTTP Range et accompagnée de paroles synchronisées mot à mot.
Author: Simon-Pierre Boucher
Sommaire
- Vue d'ensemble
- Fonctionnalités
- Architecture
- Pile technique
- Arborescence du dépôt
- Démarrage local
- Configuration
- Pages
- API
- Pipeline d'import
- Diffusion audio
- Paroles synchronisées (karaoké)
- Clients natifs
- Modèle de données
- Sécurité et vie privée
- Vérifications et tests
- Déploiement et exploitation
- Sauvegarde et restauration
- Dépannage et pièges connus
- Limites connues
- Documentation
- Auteur
- Licence
🎯 Vue d'ensemble
Music SP est un lecteur musical privé : il lit la bibliothèque audio personnelle de son propriétaire, hébergée sur son cluster. Production : https://music.spboucher.ai.
Ce n'est pas un service de catalogue : la bibliothèque ne contient que des fichiers téléversés par un administrateur (achats numériques, CD personnels numérisés, créations, licences appropriées). Rien n'est extrait d'un service de streaming.
- Écoute — accueil, recherche, pages album / artiste, file d'attente, favoris, listes de lecture, reprise de lecture par compte, paroles synchronisées, PWA installable.
- Administration — import par glisser-déposer avec reprise, détection des doublons, correction des tags, pochettes, comptes, santé du système, journal d'audit.
- Accès — clés d'accès WebAuthn uniquement (Face ID / Touch ID / code de l'appareil). Aucun mot de passe, aucune inscription publique. Deux rôles : administrateur et auditeur.
Famille SP Music
| Dépôt | Plateforme | Rôle |
|---|---|---|
| sp-music (ce dépôt) | Web · PWA | Serveur : site, API /api/v1, worker d'import, diffusion audio, paroles |
| sp-music-macos | macOS | Client natif : copie locale du catalogue, lecture hors ligne |
| sp-music-ios | iOS · iPadOS | Client natif : même API, lecture hors ligne |
Les deux applications natives utilisent les mêmes surfaces d'API que le site, plus la synchronisation incrémentale, l'association d'appareil et l'historique d'écoute décrits dans Clients natifs.
✨ Fonctionnalités
| Domaine | Ce que fait le code |
|---|---|
| Écoute | accueil, recherche (titre, artiste, album, genre — index trigrammes), pages album et artiste, bibliothèque triable |
| Lecteur | file d'attente modifiable, « À suivre », aléatoire, répétition, écran « En cours de lecture », commandes média du système ; le lecteur vit dans le layout et survit à la navigation |
| Compte | favoris (pistes et albums), listes de lecture ordonnables, reprise de lecture par compte, langue et couleur d'accent (6 accents : ember, violet, ocean, forest, rose, gold) |
| Paroles | vue karaoké : transcription locale Whisper avec horodatage par mot, correction ligne par ligne par un administrateur |
Import (/admin) |
glisser-déposer de fichiers, dossiers ou ZIP ; envoi par morceaux avec reprise ; validation sur les octets ; doublons ; remplacement confirmé et journalisé |
Bibliothèque (/admin) |
correction des tags et de l'ordre des pistes, pochettes, réanalyse, suppression auditée |
Comptes (/admin) |
invitation par lien à usage unique, rôles, suspension, révocation des sessions |
Système (/admin) |
santé (base, stockage, worker), dernière sauvegarde, journal d'audit |
| Accès | clés d'accès WebAuthn seulement, huit codes de récupération, sessions révocables, CSRF, limitation de débit |
| Formats | FLAC, MP3, AAC / M4A, WAV, ALAC, AIFF, Ogg, DSD (DSF / DFF) — l'original est toujours conservé |
| Clients natifs | catalogue incrémental par révisions, association d'appareil par code court, historique d'écoute, fichier apple-app-site-association |
| PWA | manifeste et icônes (installable sur l'écran d'accueil ; en ligne seulement) |
| Langues | français (défaut) et anglais — 449 chaînes, une ligne par chaîne dans src/i18n/messages.ts |
🏗 Architecture
flowchart TB
B["Navigateur · PWA<br/>music.spboucher.ai"]
N["Apps natives<br/>SP Music macOS · iOS"]
subgraph GW["Passerelle MacLustr Tunnel"]
C["Caddy · TLS"]
end
subgraph NODE["Nœud m5ma"]
S["sp-music-web · server.ts · port 8690"]
MH["media-http.ts<br/>/api/v1/stream · /api/v1/art<br/>Node natif, Range exact"]
NX["Next.js 16<br/>pages + API JSON"]
W["sp-music-worker<br/>import · rendus · paroles · ménage"]
BK["sp-music-backup<br/>PM2 cron 03:45"]
DB[("PostgreSQL 17<br/>base sp_music")]
ST[("STORAGE_ROOT<br/>originaux · pochettes · rendus")]
FF["ffprobe / ffmpeg"]
WH["mlx-whisper<br/>scripts/transcribe.py"]
end
B -->|HTTPS| C
N -->|HTTPS| C
C -->|WireGuard| S
S --> MH
S --> NX
NX <--> DB
MH --> DB
MH --> ST
W <--> DB
W --> FF
W --> WH
W --> ST
BK -->|"pg_dump chiffré + rsync"| DB
BK --> ST
Séparation des responsabilités
- Interface et lecteur —
src/app,src/components. - API — quatre surfaces, une route attrape-tout chacune ; le garde s'exécute avant la recherche du
gestionnaire (
src/lib/api/router.ts). Un gestionnaire d'administration ne peut pas être atteint sans le contrôle de rôle : il n'est même pas recherché avant. - Métadonnées — PostgreSQL. La base ne contient que des métadonnées et des clés de stockage.
- Originaux —
STORAGE_ROOT/originals/<aa>/<sha256>.<ext>, jamais modifiés, jamais souspublic/. - Pochettes et rendus —
art/<aa>/<sha256>/{orig.*,96.jpg,320.jpg,640.jpg},renditions/<aa>/<track>.m4a. - Traitement asynchrone —
src/worker/index.ts; la file est la tableuploadselle-même (FOR UPDATE SKIP LOCKED) : rien n'est perdu à un redémarrage.
Connexion par clé d'accès
sequenceDiagram
autonumber
participant U as Utilisateur
participant B as Navigateur
participant A as /api/v1/auth
participant D as PostgreSQL
U->>B: « Se connecter »
B->>A: POST login/options
A->>D: challenge à usage unique (5 min)
A-->>B: options WebAuthn (clés découvrables)
B->>U: Face ID / Touch ID
U-->>B: vérification locale
B->>A: POST login/verify (signature)
A->>D: lit et supprime le challenge
A->>A: vérifie signature, origine, RP ID, UV, compteur
A->>D: nouvelle session (SHA-256 du jeton)
A-->>B: cookie spmusic_session + jeton CSRF
🧱 Pile technique
| Couche | Technologie | Version | Rôle |
|---|---|---|---|
| Interface + API | Next.js (App Router) | 16.4.6 | pages et API JSON |
| UI | React · React DOM | 19.3.1 | composants, lecteur persistant |
| Styles | Tailwind CSS (@tailwindcss/postcss) |
4.3.5 | thème, accents |
| Langage | TypeScript | 6.0.3 | tout le code applicatif |
| Processus web | server.ts (HTTP Node via tsx 4.23.15) |
— | sert l'audio et les pochettes nativement (Range, Content-Length exacts) et délègue le reste à Next |
| Métadonnées | PostgreSQL + postgres |
17 · 4.1.0 | db/migrations/*.sql, appliquées une fois, sommes de contrôle |
| Fichiers | volume privé du nœud (STORAGE_ROOT) |
— | derrière l'interface Storage (src/server/storage.ts) |
| Traitement asynchrone | worker tsx |
— | la file est la table uploads |
| Audio | ffprobe / ffmpeg |
Homebrew | appelés avec un vecteur d'arguments (jamais de shell) |
| Paroles | mlx-whisper, modèle mlx-community/whisper-large-v3-turbo |
— | transcription locale, horodatage par mot |
| WebAuthn | @simplewebauthn/server · @simplewebauthn/browser |
14.1.0 · ^14.0.0 | clés d'accès |
| Validation | Zod | 4.6.7 | schémas stricts de chaque corps de requête |
| Archives | yauzl | 3.2.0 | lecture des ZIP |
| Tests | Vitest | 5.1.0 | tests HTTP sur un build de production |
| Lint | ESLint + eslint-config-next |
10.14.0 · 16.4.6 | src scripts tests server.ts |
| Orchestration | PM2 via mld (MacLustr) |
— | HTTPS par Caddy sur la passerelle du MacLustr Tunnel |
Versions lues dans package.json (plancher des plages ^).
🗂 Arborescence du dépôt
sp-music/
├── server.ts processus web : HTTP Node → media-http, sinon Next.js
├── next.config.ts CSP statique, en-têtes de sécurité, compress: false
├── db/migrations/
│ ├── 001_init.sql comptes, clés d'accès, sessions, catalogue, imports, listes, favoris
│ ├── 002_lyrics.sql paroles synchronisées
│ └── 003_native_clients.sql révisions, pierres tombales, association d'appareil, historique
├── src/
│ ├── app/
│ │ ├── (app)/ accueil, bibliothèque, recherche, album, artiste, favoris, listes, compte, admin
│ │ ├── (auth)/ login, setup, appareil
│ │ └── api/ health + 4 routes attrape-tout /api/v1/{auth,library,me,admin}
│ ├── components/ lecteur (player, player-ui, lyrics-view), shell, admin/*, auth-forms
│ ├── i18n/ messages.ts : [français, English]
│ ├── lib/
│ │ ├── api/ router.ts (garde avant gestionnaire), schemas.ts, *routes.ts
│ │ └── … auth, session, session-store, crypto, ratelimit, audit, env, db, http
│ ├── server/ catalog, ingest, media, media-http, range, storage, lyrics, sync, admin
│ └── worker/index.ts file d'import, rendus AAC, réanalyse, paroles, ménage, battement
├── scripts/
│ ├── migrate.ts applique les migrations (transactionnelles, sommes de contrôle)
│ ├── bootstrap.ts crée le propriétaire, écrit son lien d'inscription
│ ├── setup-token.ts réémet un lien d'inscription (--recovery)
│ ├── import.ts import côté serveur par le pipeline normal
│ ├── lyrics.ts met des pistes en file pour la transcription
│ ├── transcribe.py mlx-whisper, horodatage par mot
│ ├── rebuild-derived.ts vérifie les originaux, refait miniatures et rendus
│ ├── backup.sh · restore.sh sauvegarde chiffrée et restauration
│ ├── secrets-scan.ts recherche de secrets dans le dépôt
│ └── test.sh suite d'intégration complète
├── tests/ unit, api, restart + authentificateur WebAuthn logiciel (webauthn.ts)
├── public/ icônes, manifeste PWA, robots.txt
└── docs/ ARCHITECTURE.md · SECURITY.md · OPERATIONS.md · brand/🚀 Démarrage local
Prérequis : Node.js, pnpm, PostgreSQL 17 (extensions citext et pg_trgm), ffmpeg + ffprobe.
pnpm install
createdb sp_music_dev
cp .env.example .env # APP_URL=http://localhost:8690, DATABASE_URL, STORAGE_ROOT, APP_SECRET…
pnpm migrate && node_modules/.bin/tsx scripts/bootstrap.ts # affiche le lien d'inscription du propriétaire
pnpm dev # http://localhost:8690 (localhost est un contexte sûr : les clés d'accès y fonctionnent)
pnpm worker # dans un second terminalScript pnpm |
Commande | Rôle |
|---|---|---|
dev |
tsx server.ts |
serveur de développement |
build |
next build |
build de production |
start |
NODE_ENV=production tsx server.ts |
serveur de production |
worker |
tsx src/worker/index.ts |
worker d'arrière-plan |
migrate |
tsx scripts/migrate.ts |
migrations |
typecheck |
tsc --noEmit |
types |
lint |
eslint src scripts tests server.ts |
lint |
test |
bash scripts/test.sh |
suite d'intégration |
secrets:scan |
tsx scripts/secrets-scan.ts |
recherche de secrets |
⚙️ Configuration
Tout passe par .env (jamais commité ; modèle : .env.example). Noms seulement :
| Variable | Rôle | Défaut |
|---|---|---|
APP_URL |
origine publique exacte ; WebAuthn la compare octet pour octet | http://localhost:8690 |
WEBAUTHN_RP_ID |
RP ID ; par défaut l'hôte de APP_URL. Le changer invalide toutes les clés inscrites |
hôte de APP_URL |
APP_SECRET |
secret applicatif, 32 caractères au moins | requis |
PORT · HOST |
écoute du processus web | 8690 · 0.0.0.0 |
OWNER_EMAIL · OWNER_NAME |
premier administrateur créé par scripts/bootstrap.ts |
— |
SETUP_URL_FILE |
fichier (0600) où est écrit le lien d'inscription du propriétaire | — |
DATABASE_URL |
PostgreSQL (métadonnées seulement) | requis |
STORAGE_DRIVER |
local (seul pilote livré) |
local |
STORAGE_ROOT |
point de montage de la bibliothèque, hors du dossier de l'application | requis |
TMP_DIR |
espace de travail des envois en cours | $STORAGE_ROOT/.tmp |
UPLOAD_MAX_FILE_MB |
taille maximale d'un fichier | 2048 |
UPLOAD_MAX_CHUNK_MB |
taille maximale d'un corps de requête | 16 |
UPLOAD_MAX_FILES |
fichiers en cours simultanés (et fichiers audio par archive) | 500 |
LIBRARY_QUOTA_GB |
quota total de la bibliothèque ; 0 = aucun |
0 |
ARCHIVE_MAX_ENTRIES · ARCHIVE_MAX_TOTAL_MB · ARCHIVE_MAX_RATIO |
bornes des ZIP | 2000 · 20480 · 100 |
UPLOAD_RETENTION_DAYS |
purge des imports terminés ou abandonnés | 30 |
RENDITIONS |
auto (rendu AAC à l'import et à la demande) ou never |
auto |
RENDITION_BITRATE_KBPS |
débit du rendu AAC | 256 |
TRANSCODE_DSD |
produire aussi un rendu lisible pour le DSD | false |
FFMPEG_PATH · FFPROBE_PATH |
chemins des binaires | ffmpeg · ffprobe |
LYRICS |
off, manual ou auto |
off |
LYRICS_PYTHON |
Python d'un environnement virtuel avec mlx-whisper |
— |
LYRICS_MODEL |
modèle Whisper | mlx-community/whisper-large-v3-turbo |
BACKUP_DIR · BACKUP_PASSPHRASE_FILE · BACKUP_TRASH_DAYS |
sauvegardes (scripts/backup.sh) |
— · — · 30 |
APPLE_APP_IDS |
applications natives autorisées à utiliser les clés d'accès du site (TeamID.bundleId, séparées par des virgules) |
SP Music macOS et iOS |
🧭 Pages
13 pages (page.tsx) : 10 dans l'application, 3 d'authentification.
| Route | Groupe | Contenu |
|---|---|---|
/ |
app | accueil |
/bibliotheque |
app | albums, artistes, pistes |
/recherche |
app | recherche |
/album/[id] · /artiste/[id] |
app | fiches album et artiste |
/favoris |
app | favoris |
/listes · /listes/[id] |
app | listes de lecture |
/compte |
app | clés d'accès, sessions, préférences |
/admin |
app | import, bibliothèque, comptes, système |
/login |
auth | connexion par clé d'accès, code de récupération |
/setup |
auth | inscription par lien à usage unique |
/appareil |
auth | approbation d'une application native |
🔌 API
Préfixe /api/v1. Quatre surfaces, 73 routes JSON, plus trois routes servies nativement par server.ts et
GET /api/health.
| Surface | Garde | Routes | Contenu |
|---|---|---|---|
/api/v1/auth/* |
aucun (limité en débit par adresse) | 12 | session, options / vérification WebAuthn, code de récupération, association d'appareil, déconnexion |
/api/v1/library/* |
requireUser |
26 | catalogue, recherche, favoris, listes, état de lecture, synchronisation, historique, rendu AAC, paroles |
/api/v1/me/* |
requireUser |
8 | clés d'accès, sessions, préférences du compte, codes de récupération |
/api/v1/admin/* |
requireAdmin |
27 | import, édition, suppression, paroles, comptes, santé, journal |
auth — 12 routes
| Méthode | Chemin |
|---|---|
| GET | session |
| POST | setup/info |
| POST | register/options · register/verify |
| POST | login/options · login/verify |
| POST | recovery |
| POST | device/start · device/poll · device/info · device/decide |
| POST | logout |
library — 26 routes
| Méthode | Chemin | Notes |
|---|---|---|
| GET | home |
accueil du compte |
| GET | albums · albums/:id |
tri recent, title, artist, year |
| GET | artists · artists/:id |
|
| GET | tracks · tracks/:id |
tri title, recent, artist |
| GET | search?q= |
100 caractères au plus |
| GET | favorites |
|
| PUT · DELETE | favorites/:kind/:id |
kind = track ou album |
| GET · POST | playlists |
|
| GET · PATCH · DELETE | playlists/:id |
baseUpdatedAt facultatif → 409 conflict |
| POST | playlists/:id/tracks |
|
| PUT | playlists/:id/order |
|
| GET | sync?since=<rev> · sync/me |
clients natifs |
| GET · POST | history |
historique d'écoute |
| GET · PUT | playback |
état de lecture |
| POST | tracks/:id/compat |
demande de rendu AAC |
| GET | tracks/:id/lyrics |
me — 8 routes
| Méthode | Chemin |
|---|---|
| PATCH | preferences (langue fr / en, accent, nom affiché) |
| GET | passkeys |
| PATCH · DELETE | passkeys/:id |
| GET | sessions |
| DELETE | sessions/:id |
| POST | sessions/revoke-others |
| GET | recovery-codes |
admin — 27 routes
| Méthode | Chemin |
|---|---|
| GET | uploads/limits |
| GET · POST | uploads (filtre all, active, error, duplicate, ready) |
| GET · PATCH · DELETE | uploads/:id (PATCH ?offset=N = un morceau) |
| POST | uploads/:id/retry · uploads/:id/replace · uploads/clear |
| PATCH | tracks |
| POST | tracks/delete · tracks/reanalyse |
| PATCH | albums/:id |
| PUT | albums/:id/order · albums/:id/artwork |
| POST | albums/:id/delete |
| POST | lyrics/generate (langues fr, en, es, it, de, pt) |
| PUT · DELETE | tracks/:id/lyrics |
| GET · POST | users |
| PATCH · DELETE | users/:id |
| POST | users/:id/invite · users/:id/revoke-sessions |
| GET | health · audit |
Les suppressions de pistes et d'albums exigent confirm: true dans le corps.
Routes natives (src/server/media-http.ts)
| Méthode | Chemin | Rôle |
|---|---|---|
| GET · HEAD | /api/v1/stream/<uuid piste>[?v=compat] |
audio, HTTP Range (206) |
| GET · HEAD | /api/v1/art/<uuid pochette>[?s=96|320|640|orig] |
pochettes |
| GET | /.well-known/apple-app-site-association |
autorise les applications natives à utiliser les clés d'accès du site |
Santé : GET /api/health → {ok, db, storage, worker} (503 si la base ou le stockage ne répond pas ; le
worker est sain si son battement a moins de 120 s).
📥 Pipeline d'import
navigateur : POST /admin/uploads {nom, taille} → PATCH /admin/uploads/<id>?offset=N (morceaux de 8 Mo, écrits en flux)
uploading → received → validating → extracting → ready | duplicate | error | cancelled- Reprise : un morceau envoyé au mauvais décalage reçoit
409avec le décalage attendu ; le client reprend là. - Validation : type déterminé par les premiers octets (
sniff), jamais par l'extension ; puisffprobedoit trouver un flux audio mesurable. Exécutables, textes, vidéos : refusés. - Doublons :
same_file(même SHA-256) ousame_track(même artiste d'album, album, disque, numéro, titre). Rien n'est remplacé sans confirmation explicite ; le remplacement garde l'identifiant de la piste (listes et favoris intacts) et est journalisé. - ZIP : chaque entrée audio est écrite sous un nom généré par le serveur ; limites sur le nombre d'entrées, la
taille par entrée, la taille totale et le taux de compression, mesurées sur les octets produits ; archives
chiffrées, imbriquées ou contenant un chemin
../: refusées. - Tags : titre, artiste, album, artiste d'album, piste, disque, année, genre ; à défaut, le nom du fichier (« 03 Titre.wav »).
- Pochette : extraite du fichier sans réencodage, dédupliquée par empreinte ; miniatures carrées JPEG générées à part.
- Reprise après panne : un travail interrompu retourne dans la file (trois tentatives, puis une erreur visible).
Import côté serveur (administrateur avec accès shell au nœud, sans session) — même pipeline que l'interface :
node_modules/.bin/tsx scripts/import.ts <dossier> --wait🎧 Diffusion audio
-
GET /api/v1/stream/<uuid>exige la session ;Range→206avecContent-RangeetContent-Lengthexacts ;416si la plage est hors fichier ;ETag= identifiant de l'asset,Cache-Control: private, no-cache(un fichier remplacé change d'asset, donc d'ETag). -
Lecture depuis le disque par
createReadStream({start, end}): un morceau n'est jamais chargé en mémoire. -
Original d'abord.
tracks.web_playable:Valeur Formats Comportement yesFLAC, MP3, AAC, WAV original servi tel quel someALAC, AIFF, Ogg rendu AAC préparé à l'import noDSD original conservé, rendu seulement si TRANSCODE_DSD=true -
Le lecteur choisit avec
canPlayType; si le navigateur échoue à décoder un original, il demande le rendu (POST /library/tracks/<id>/compat) et reprend à la même position. -
Aucun transcodage haute résolution : le rendu de compatibilité est un AAC (
RENDITION_BITRATE_KBPS, 44,1 / 48 kHz).
Stockage. src/server/storage.ts définit Storage (putFile, put, read(range), size, delete,
localPath, health). Seul le pilote local est livré : le cluster n'a pas de stockage objet. Un pilote S3
s'ajoute en implémentant cette interface (localPath devant alors télécharger vers un fichier temporaire pour
ffmpeg) ; STORAGE_DRIVER=s3 échoue aujourd'hui explicitement plutôt que de faire semblant.
🎤 Paroles synchronisées (karaoké)
Les paroles sont transcrites sur le nœud à partir de l'audio (mlx-whisper, modèle whisper-large-v3-turbo),
avec un horodatage par mot ; rien n'est envoyé à un service externe et aucun site de paroles n'est interrogé.
uv venv ~/.venvs/whisper --python 3.12 && uv pip install -p ~/.venvs/whisper mlx-whisper # une fois
# .env : LYRICS=auto (ou manual), LYRICS_PYTHON=$HOME/.venvs/whisper/bin/python
node_modules/.bin/tsx scripts/lyrics.ts --missing --wait # toute la bibliothèque
node_modules/.bin/tsx scripts/lyrics.ts --album "Thriller" --lang en --overwriteLYRICS=automet aussi en file chaque nouvel import ;manuallaisse l'administrateur décider (/admin→ Bibliothèque → sélection → Paroles).- La transcription d'une voix chantée sur de la musique reste imparfaite (mots mal entendus, langue mal détectée
quand une piste commence par une longue intro : préciser la langue). Chaque ligne se corrige dans
/admin→ Bibliothèque → icône Paroles de la piste ; une correction manuelle n'est jamais écrasée sans demande explicite. - Une piste sans voix est marquée « instrumental ». Les phrases inventées par le modèle sur du silence
(« Thank you », « Sous-titrage… ») sont filtrées (
src/server/lyrics.ts). - Les scores non finis renvoyés par Whisper sur les passages instrumentaux ne cassent plus la sortie JSON
(
scripts/transcribe.py, commitb475a70).
📱 Clients natifs
Les applications macOS et iOS gardent leur propre copie du catalogue et lisent hors ligne. Elles utilisent les mêmes
surfaces que le site, plus ceci (migration 003_native_clients.sql) :
| Route | Rôle |
|---|---|
GET /api/v1/library/sync?since=<rev> |
Catalogue incrémental : artistes, albums, pistes dont la révision dépasse since, et pierres tombales des suppressions. Chaque piste porte son fichier (assetId, sha256, sizeBytes, mime) pour le téléchargement vérifié. more: true = redemander avec le rev reçu. |
GET /api/v1/library/sync/me |
Listes (avec leurs entrées), favoris et état de lecture du compte, en une réponse. |
GET / POST /api/v1/library/history |
Historique d'écoute ; l'identifiant de chaque événement vient du client (renvoi sans doublon). |
PATCH playlists/:id, PUT playlists/:id/order |
Champ facultatif baseUpdatedAt : 409 conflict si la liste a changé depuis la copie du client (modification faite hors ligne). |
POST /api/v1/auth/device/{start,poll,info,decide} |
Association d'appareil. Page d'approbation : /appareil. |
GET /.well-known/apple-app-site-association |
Autorise les applications (APPLE_APP_IDS) à utiliser les clés d'accès du site. |
Révisions. artists, albums et tracks portent une colonne rev tirée d'une seule séquence par un
déclencheur ; un verrou consultatif de transaction est pris avant le tirage, donc les révisions sont validées dans
l'ordre croissant et la plus haute révision d'une réponse est un curseur sûr. Un changement de fichier
(media_assets) ou de paroles (lyrics) fait avancer la révision de la piste. La lecture se fait dans un seul
instantané (REPEATABLE READ).
sequenceDiagram
autonumber
participant App as Application native
participant API as /api/v1/auth/device
participant Web as Navigateur déjà connecté
App->>API: POST start
API-->>App: code XXXX-XXXX (10 min)
App->>Web: ouvre /appareil?code=…
Web->>API: POST info (session + CSRF + origine)
Web->>API: POST decide (approuver / refuser)
loop jusqu'à la décision
App->>API: POST poll (secret de l'application)
end
API-->>App: session propre (méthode device, 90 jours)
🗃 Modèle de données
25 tables, 3 migrations (db/migrations/). Une migration appliquée n'est jamais modifiée (somme de contrôle
vérifiée) : on en ajoute une.
| Groupe | Tables |
|---|---|
| Comptes et accès | users (rôle admin / listener, un seul is_owner), authenticators, sessions, setup_tokens, recovery_codes, webauthn_challenges, device_links |
| Protection et journal | rate_limits, audit_events, worker_heartbeat |
| Catalogue | artists, genres, albums, tracks, artworks, media_assets (original, rendu, pochette, miniature), lyrics, library_tombstones |
| Import | uploads (import + file de traitement) |
| Données personnelles | playlists, playlist_tracks, favorites, favorite_albums, playback_state, play_events |
Contraintes notables : un seul original par piste ; un même fichier (SHA-256) ne peut pas être stocké deux fois ; un album est unique par (artiste d'album, titre normalisé) ; index trigrammes pour la recherche.
erDiagram
users ||--o{ authenticators : possede
users ||--o{ sessions : ouvre
users ||--o{ recovery_codes : detient
users ||--o{ setup_tokens : recoit
users ||--o{ device_links : approuve
users ||--o{ playlists : cree
users ||--o{ favorites : aime
users ||--o{ favorite_albums : aime
users ||--o| playback_state : reprend
users ||--o{ play_events : ecoute
users ||--o{ uploads : televerse
artists ||--o{ albums : signe
artists ||--o{ tracks : interprete
genres ||--o{ albums : classe
genres ||--o{ tracks : classe
artworks ||--o{ albums : illustre
albums ||--o{ tracks : contient
tracks ||--o{ media_assets : stocke
artworks ||--o{ media_assets : stocke
tracks ||--o| lyrics : transcrit
tracks ||--o{ playlist_tracks : figure
playlists ||--o{ playlist_tracks : ordonne
tracks ||--o{ favorites : aimee
albums ||--o{ favorite_albums : aime
tracks ||--o{ play_events : jouee
tracks ||--o{ uploads : produit
🔐 Sécurité et vie privée
Détail complet : docs/SECURITY.md.
Clés d'accès (WebAuthn)
- RP ID :
music.spboucher.ai(hôte deAPP_URL;WEBAUTHN_RP_IDpermet un domaine parent). Origine attendue :https://music.spboucher.ai, comparée à l'identique. Le développement utilisehttp://localhost:8690(RP IDlocalhost), dans une base distincte. - Vérifié côté serveur à chaque opération : challenge à usage unique (la ligne est supprimée à sa lecture, 5 minutes de validité), signature, origine, RP ID, présence et vérification de l'utilisateur, compteur.
- Stocké : identifiant de la clé, clé publique, compteur, transports, type d'appareil, indicateur de synchronisation, nom, dates. Jamais de clé privée ni de donnée biométrique.
- Plusieurs clés par compte, renommables et révocables (
/compte). La dernière clé ne peut pas être retirée depuis l'interface. - Clés découvrables : la connexion n'envoie aucune liste de comptes ; une clé inconnue et une signature fausse produisent la même réponse.
| Adresse ouverte | Effet |
|---|---|
http://music.spboucher.ai |
redirigé en HTTPS par Caddy |
adresse IP, nœud:8690, autre sous-domaine |
pas de contexte sûr ou RP ID différent : le navigateur refuse WebAuthn ; la page de connexion l'explique |
http://localhost:8690 |
développement seulement (contexte sûr par exception) |
Comptes et récupération
scripts/bootstrap.tscrée l'unique compte propriétaire depuisOWNER_EMAILet, tant qu'il n'a aucune clé d'accès, écrit un lien d'inscription à usage unique (24 h) dansSETUP_URL_FILE(mode 0600) — jamais dans un journal. Dès qu'une clé existe, plus aucun lien n'est émis. Il n'y a niadmin/admin, ni mot de passe, ni secret par défaut.- Seul le SHA-256 des jetons est en base ; le jeton voyage dans le fragment d'URL (
#…), qui n'apparaît ni dans les requêtes, ni dans les journaux du proxy, ni dansReferer. - Aucune inscription publique. Un compte n'existe que parce qu'un administrateur l'a créé ; il reçoit un lien d'inscription à usage unique, affiché une seule fois (72 h).
- Récupération : (1) huit codes à usage unique, affichés une fois à la première clé, stockés hachés ; (2) pour le
propriétaire, depuis le shell du nœud :
tsx scripts/setup-token.ts [--recovery](--recoveryremplace toutes les clés et ferme toutes les sessions) ; (3) pour les autres comptes, un nouveau lien émis par un administrateur. Il n'existe aucune autre voie.
Association d'appareil. L'application affiche un code court (XXXX-XXXX, 10 minutes) et ouvre
/appareil?code=… ; un navigateur déjà connecté par clé d'accès l'approuve (session + jeton CSRF + origine exigés) ;
l'application, qui interroge device/poll avec son propre secret (seul son SHA-256 est en base), reçoit alors sa
propre session (méthode device, 90 jours), visible et révocable dans « Compte ». Une association ne sert qu'une
fois ; refusée, expirée ou inconnue, elle ne donne rien. Débit limité : création 10 / 10 min par adresse, saisie de
codes 30 / 10 min par compte. L'application peut aussi se connecter directement par clé d'accès
(AuthenticationServices) : même vérification serveur que le navigateur.
Sessions et CSRF. Cookie spmusic_session : jeton aléatoire de 256 bits (seul son SHA-256 est en base),
HttpOnly, Secure en production, SameSite=Lax, sans attribut Domain, 30 jours. Un nouveau jeton à chaque
authentification. Révocation côté serveur par l'utilisateur, par un administrateur, par la suspension du compte, par
la récupération. Toute requête modifiante doit venir de l'origine du site (Origin, Sec-Fetch-Site) et porter le
jeton CSRF de la session dans X-CSRF-Token.
Autorisation. Rôle lu en base à chaque requête ; masquer un bouton n'est jamais l'autorisation. Les données
personnelles sont filtrées par user_id : l'identifiant d'un autre compte répond 404. Le propriétaire ne peut être
ni rétrogradé, ni suspendu, ni supprimé.
Téléversement. Type vérifié sur le contenu ; tailles bornées à la création, à chaque morceau et à l'analyse ; quota optionnel ; espace disque vérifié. Les chemins de stockage sont construits par le serveur à partir d'empreintes et d'UUID, et le pilote refuse toute clé hors de sa racine. Images : JPEG / PNG / WebP, 25 Mo et 8000 px par côté au plus.
En-têtes. CSP (default-src 'self', frame-ancestors 'none', object-src 'none', aucune origine tierce),
Strict-Transport-Security, X-Content-Type-Options: nosniff, Referrer-Policy, X-Frame-Options: DENY,
Permissions-Policy. Les réponses audio et image ajoutent Cross-Origin-Resource-Policy: same-origin et un cache
strictement privé. Aucune ressource externe n'est chargée ; aucun titre écouté ni fichier n'est transmis à un service
tiers.
Limitation de débit et journal. Compteurs en base par adresse : authentification 30 / 10 min, codes de
récupération 5 / 15 min. audit_events consigne les actions d'administration ; jamais de contenu audio, de cookie,
de jeton, de code ni de challenge. Les erreurs renvoyées au client ne contiennent ni trace, ni chemin.
✅ Vérifications et tests
pnpm typecheck && pnpm lint
pnpm test # scripts/test.sh : base et stockage neufs, build de production, worker réel, ffmpeg réel
pnpm secrets:scan| Fichier | Tests | Portée |
|---|---|---|
tests/unit.test.ts |
5 | analyse de Range, noms, détection de type sur les octets |
tests/api.test.ts |
38 | visiteurs anonymes, inscription du propriétaire, connexion, import, diffusion privée, rôle auditeur, clés et sessions, gestion de la bibliothèque, clients natifs, paroles |
tests/restart.test.ts |
1 | les données survivent à un redémarrage |
| Total | 44 | puis sauvegarde → restauration dans une base et un stockage neufs |
pnpm test génère ses propres fichiers audio (ondes sinusoïdales, voix de synthèse say pour les paroles) : aucun
enregistrement commercial n'est dans le dépôt. Il couvre : accès anonyme refusé, rôles côté serveur, WebAuthn
(origine, RP ID, signature, vérification utilisateur, challenge rejoué ou expiré, jeton à usage unique), CSRF, import
par morceaux et reprise, doublons, fichiers piégés, archives (traversée de chemin, bombe), Range / 206 / 416 / 304,
édition, suppression auditée, redémarrage, sauvegarde → restauration.
- L'authentificateur WebAuthn est logiciel (
tests/webauthn.ts). - Les tests de paroles exigent un environnement
mlx-whisperlocal ; sans lui ils sont sautés et le disent. SKIP_BUILD=1réutilise.next;TEST_PORTchange le port (8691 par défaut).
🚢 Déploiement et exploitation
Détail complet : docs/OPERATIONS.md.
| Site | https://music.spboucher.ai |
App mld |
sp-music, épinglée sur son nœud (mld status), port 8690 |
| Dépôt (source de vérité) | sur le nœud : ~/apps/sp-music ; origin spbgit sp-music.git |
| Processus PM2 | sp-music-web (tsx server.ts), sp-music-worker, sp-music-backup (cron 03:45) |
| Base | PostgreSQL 17 local, base sp_music, rôle spmusic_app |
| Bibliothèque | ~/data/sp-music/library (originaux, pochettes, rendus), mode 0700 |
| Sauvegardes | ~/backups/sp-music |
| Secrets | ~/apps/sp-music/.env (0600), ~/.config/sp-music/backup-passphrase |
Prérequis du domaine
- DNS : enregistrement
Ademusic.spboucher.aivers la passerelle du MacLustr Tunnel. - HTTPS : certificat obtenu et renouvelé par Caddy ; HTTP redirigé vers HTTPS. Route posée par
mld deploy(tunnel.domain). - Le proxy transmet les corps en flux ; un morceau d'envoi fait 8 Mo (
UPLOAD_MAX_CHUNK_MBborne le serveur) : garder la limite de corps du proxy au-dessus. APP_URLdoit être exactementhttps://music.spboucher.ai: c'est l'origine que WebAuthn vérifie.
Première installation (faite par le déploiement, pour mémoire)
# sur le nœud
brew install ffmpeg # ffmpeg + ffprobe
createuser spmusic_app --pwprompt ; createdb -O spmusic_app sp_music
psql -d sp_music -c 'CREATE EXTENSION IF NOT EXISTS citext; CREATE EXTENSION IF NOT EXISTS pg_trgm;'
mkdir -p ~/data/sp-music/library ~/backups/sp-music ~/.config/sp-music && chmod 700 ~/data/sp-music ~/backups/sp-music ~/.config/sp-music
openssl rand -base64 48 > ~/.config/sp-music/backup-passphrase && chmod 600 ~/.config/sp-music/backup-passphrase
cp .env.example .env && chmod 600 .env # remplir APP_SECRET, DATABASE_URL, OWNER_EMAIL, chemins
# depuis le poste opérateur
mld stage <dossier> sp-music && mld deploy sp-music # pnpm install, migrations, bootstrap, build, PM2, route HTTPSCréer le propriétaire et inscrire Face ID / Touch ID
- Le déploiement a créé le compte propriétaire et écrit un lien à usage unique (24 h) :
ssh <nœud> cat ~/data/sp-music/setup-url.txt. Lien expiré ?ssh <nœud>puiscd ~/apps/sp-music && node_modules/.bin/tsx scripts/setup-token.ts. - Ouvrir ce lien sur l'appareil à inscrire (iPhone, iPad ou Mac), dans Safari.
- « Créer la clé d'accès » : iOS / macOS affiche sa propre boîte de dialogue et demande Face ID ou Touch ID. Avec le trousseau iCloud activé, la clé est synchronisée sur les autres appareils Apple.
- Noter les huit codes de récupération (affichés une seule fois) hors ligne.
- Autres appareils :
/compte→ Clés d'accès → Ajouter, depuis une session ouverte ; sur un appareil sans session, le navigateur propose d'utiliser un iPhone à proximité (QR code). - Installer en PWA : Safari → Partager → « Sur l'écran d'accueil ».
Auditeurs : /admin → Comptes → Nouveau compte → transmettre le lien (72 h, usage unique).
Mettre à jour (sur le nœud — remote-first)
ssh <nœud> ; cd ~/apps/sp-music
git pull --ff-only # ou éditer sur place
pnpm install --frozen-lockfile
node_modules/.bin/tsx scripts/migrate.ts
node_modules/.bin/next build
pm2 restart sp-music-web sp-music-worker
git add -A && git commit -m "…" && git push origin mainLes migrations sont transactionnelles et ne s'appliquent qu'une fois ; une migration appliquée puis modifiée fait
échouer le déploiement (somme de contrôle). Ne jamais mld move sp-music sans déplacer la base et la bibliothèque
(voir Sauvegarde et restauration).
Journaux : pm2 logs sp-music-web|sp-music-worker|sp-music-backup (aucun secret ni contenu audio n'y est écrit).
💾 Sauvegarde et restauration
scripts/backup.sh, chaque nuit (PM2 sp-music-backup) :
- Base :
pg_dumpchiffré AES-256 →~/backups/sp-music/db/sp-music-AAAAmmjj-HHMMSS.dump.enc(30 jours), relu parpg_restore --listà chaque exécution. - Bibliothèque : miroir
rsyncdes originaux et des pochettes →~/backups/sp-music/library/; ce qui disparaît de la bibliothèque va danstrash/<date>/pendantBACKUP_TRASH_DAYS(30). Les rendus et miniatures, dérivés, ne sont pas sauvegardés. last-backup.jsonalimente « Dernière sauvegarde » dans/admin→ Système.
À faire par le propriétaire : cette sauvegarde est sur le même disque que la bibliothèque. Elle protège d'une suppression accidentelle, pas d'une panne du disque. Copie hors nœud, depuis une autre machine :
rsync -a <nœud>:backups/sp-music/ /chemin/de/sauvegarde/sp-music/(planifiable ; les processus PM2 du nœud ne peuvent pas joindre le réseau local). Conserver aussibackup-passphraseailleurs : sans elle les dumps sont illisibles.
createdb -O spmusic_app sp_music # base vide
scripts/restore.sh db ~/backups/sp-music/db/<fichier>.dump.enc "$DATABASE_URL"
scripts/restore.sh library ~/backups/sp-music/library ~/data/sp-music/library
node_modules/.bin/tsx scripts/rebuild-derived.ts # vérifie chaque original, refait les miniatures, remet les rendus en file
pm2 restart sp-music-web sp-music-workerrebuild-derived.ts sort en erreur et liste tout original manquant. Les clés d'accès sont liées au domaine, pas au
nœud : elles restent valides après une restauration tant que APP_URL / RP ID ne changent pas. La procédure est
exécutée par pnpm test à chaque passage.
🩺 Dépannage et pièges connus
| Symptôme | Cause probable / remède |
|---|---|
| « Clés d'accès indisponibles ici » | page ouverte en HTTP, par IP ou sur un autre hôte → ouvrir https://music.spboucher.ai |
| La boîte Face ID n'apparaît pas, « demande annulée » | aucune clé de ce site sur l'appareil (trousseau iCloud désactivé ?) → utiliser un autre appareil, un code de récupération, ou un nouveau lien |
| Connexion refusée après un changement de domaine | APP_URL ou WEBAUTHN_RP_ID modifiés : les clés existantes ne valent que pour l'ancien RP ID |
| Plus aucune clé ni code | sur le nœud : tsx scripts/setup-token.ts --recovery |
| Import bloqué sur « reçu » | worker arrêté : pm2 logs sp-music-worker, pm2 restart sp-music-worker ; /admin → Système indique « Traitement » |
| Import en erreur « type refusé » | le contenu n'est pas un format audio accepté (vérifié sur les octets, pas l'extension) |
| « Non lisible ici » sur une piste | DSD sans TRANSCODE_DSD=true, ou rendu AAC en préparation / en échec (/admin → Bibliothèque → Réanalyser) |
| La lecture ne démarre pas sur iPhone | iOS exige un geste : toucher Lecture. En arrière-plan, iOS garde la lecture d'un <audio> et les commandes de l'écran verrouillé ; le volume se règle par les boutons de l'appareil |
| 413 à l'envoi | fichier au-dessus de UPLOAD_MAX_FILE_MB, ou morceau au-dessus de la limite du proxy |
| Santé | curl https://music.spboucher.ai/api/health → {ok, db, storage, worker} |
Pièges visibles dans le code
- Pourquoi
server.ts: l'audio et les pochettes sont servis par un serveur HTTP Node natif (src/server/media-http.ts) pour garder unContent-Lengthet un cadrageRangeexacts ;next.config.tsfixecompress: false(la passerelle compresse le texte, l'audio doit garder ses octets intacts). - Session hors Next : la recherche de session utilisée par le serveur natif est dans
src/lib/session-store.ts. - IPv4 d'abord :
scripts/_env.tsforceipv4first(les nœuds du cluster n'ont pas de route IPv6). - pnpm :
pnpm-workspace.yamlporte à la foisallowBuilds(pnpm 12, nœud) etonlyBuiltDependencies(pnpm 11). - CSP et tests : pas de
upgrade-insecure-requests(casse WebKit surhttp://127.0.0.1dans les tests). - Next.js 16 : lire
AGENTS.mdavant de modifier le code — les conventions diffèrent des versions antérieures.
⚠️ Limites connues
script-srcetstyle-srcautorisent'unsafe-inline'(amorçage de Next.js sans nonce). Aucun contenu tiers n'est chargé.- Le port 8690 du nœud est joignable depuis le réseau local sans TLS ; l'en-tête
X-Forwarded-Fory est falsifiable (seule la limitation de débit en dépend). L'accès prévu passe par la passerelle. - Les originaux ne sont pas chiffrés au repos par l'application (dossier en mode 0700 sur le nœud) ; les sauvegardes de la base le sont.
- La sauvegarde quotidienne est sur le même disque que la bibliothèque tant qu'une copie hors nœud n'est pas mise en place.
- Pas de service worker : pas de lecture hors ligne sur le web (les applications natives la fournissent).
- Seul le pilote de stockage
localexiste.
📚 Documentation
docs/ARCHITECTURE.md— composants, schéma, pipeline d'import, diffusion, API, clients natifsdocs/SECURITY.md— WebAuthn, sessions, domaine, en-têtes, menaces traitées, limites connuesdocs/OPERATIONS.md— installation, propriétaire, Face ID / Touch ID, déploiement, sauvegarde, restauration, dépannageAGENTS.md— règles pour les agents de code (Next.js 16)
👤 Auteur
Simon-Pierre Boucher — conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 Licence
Le dépôt ne contient pas de fichier de licence. Tous droits réservés © 2026 Simon-Pierre Boucher.