SPB Git

Repository Public

README.md 49.5 KB 867 lines markdown

1<div align="center">23<img src="docs/brand/logo.svg" alt="Music SP logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="Music SP icon" width="112" height="112">89# Music SP1011**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.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1415[![music.spboucher.ai](https://img.shields.io/website?url=https%3A%2F%2Fmusic.spboucher.ai%2Fapi%2Fhealth&label=music.spboucher.ai&style=for-the-badge&up_message=en%20ligne&down_message=hors%20ligne)](https://music.spboucher.ai)16![version](https://img.shields.io/badge/version-1.0.0-blue?style=for-the-badge)17![plateforme](https://img.shields.io/badge/plateforme-web%20%C2%B7%20PWA-FF7043?style=for-the-badge)18![langues](https://img.shields.io/badge/langues-FR%20%C2%B7%20EN-8A2BE2?style=for-the-badge)19![licence](https://img.shields.io/badge/licence-tous%20droits%20r%C3%A9serv%C3%A9s-lightgrey?style=for-the-badge)20![author](https://img.shields.io/badge/author-Simon--Pierre%20Boucher-0A66C2?style=for-the-badge)2122![Next.js](https://img.shields.io/badge/Next.js-16.4.6-000000?style=flat-square&logo=nextdotjs&logoColor=white)23![React](https://img.shields.io/badge/React-19.3.1-20232A?style=flat-square&logo=react&logoColor=white)24![TypeScript](https://img.shields.io/badge/TypeScript-6.0.3-3178C6?style=flat-square&logo=typescript&logoColor=white)25![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS-4.3.5-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white)26![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?style=flat-square&logo=postgresql&logoColor=white)27![postgres.js](https://img.shields.io/badge/postgres.js-4.1.0-336791?style=flat-square)28![WebAuthn](https://img.shields.io/badge/WebAuthn-SimpleWebAuthn%2014.1.0-3423A6?style=flat-square&logo=webauthn&logoColor=white)29![Zod](https://img.shields.io/badge/Zod-4.6.7-3E67B1?style=flat-square&logo=zod&logoColor=white)30![yauzl](https://img.shields.io/badge/yauzl-3.2.0-555555?style=flat-square)31![tsx](https://img.shields.io/badge/tsx-4.23.15-3178C6?style=flat-square)32![FFmpeg](https://img.shields.io/badge/FFmpeg-ffprobe%20%2B%20ffmpeg-007808?style=flat-square&logo=ffmpeg&logoColor=white)33![Whisper](https://img.shields.io/badge/mlx--whisper-large--v3--turbo-111111?style=flat-square&logo=apple&logoColor=white)34![Vitest](https://img.shields.io/badge/Vitest-5.1.0-6E9F18?style=flat-square&logo=vitest&logoColor=white)35![ESLint](https://img.shields.io/badge/ESLint-10.14.0-4B32C3?style=flat-square&logo=eslint&logoColor=white)36![pnpm](https://img.shields.io/badge/pnpm-workspace-F69220?style=flat-square&logo=pnpm&logoColor=white)3738[![commits](https://git.spboucher.ai/badge/sp-music/commits.svg?style=flat-square)](https://git.spboucher.ai/sp-music/commits)39[![last commit](https://git.spboucher.ai/badge/sp-music/last-commit.svg?style=flat-square)](https://git.spboucher.ai/sp-music/commits)40[![activity](https://git.spboucher.ai/badge/sp-music/activity.svg?style=flat-square)](https://git.spboucher.ai/sp-music/insights)41[![language](https://git.spboucher.ai/badge/sp-music/language.svg?style=flat-square)](https://git.spboucher.ai/sp-music)42[![languages](https://git.spboucher.ai/badge/sp-music/languages.svg?style=flat-square)](https://git.spboucher.ai/sp-music/insights)43[![size](https://git.spboucher.ai/badge/sp-music/size.svg?style=flat-square)](https://git.spboucher.ai/sp-music)44[![branches](https://git.spboucher.ai/badge/sp-music/branches.svg?style=flat-square)](https://git.spboucher.ai/sp-music/branches)45[![tags](https://git.spboucher.ai/badge/sp-music/tags.svg?style=flat-square)](https://git.spboucher.ai/sp-music/tags)46[![clones](https://git.spboucher.ai/badge/sp-music/clones.svg?style=flat-square)](https://git.spboucher.ai/sp-music)4748![routes API](https://img.shields.io/badge/routes%20API%20JSON-73-blue?style=flat-square)49![routes média](https://img.shields.io/badge/routes%20m%C3%A9dia%20natives-3-blue?style=flat-square)50![pages](https://img.shields.io/badge/pages-13-blue?style=flat-square)51![tables](https://img.shields.io/badge/tables-25-blue?style=flat-square)52![migrations](https://img.shields.io/badge/migrations-3-blue?style=flat-square)53![tests](https://img.shields.io/badge/tests-44-brightgreen?style=flat-square)54![fichiers TypeScript](https://img.shields.io/badge/fichiers%20TypeScript-80-informational?style=flat-square)55![lignes TypeScript](https://img.shields.io/badge/lignes%20TypeScript-6%20859-informational?style=flat-square)56![chaînes traduites](https://img.shields.io/badge/cha%C3%AEnes%20traduites-449%20%C3%97%202-informational?style=flat-square)5758![nœud](https://img.shields.io/badge/n%C5%93ud-m5ma-8A2BE2?style=flat-square)59![port](https://img.shields.io/badge/port-8690-informational?style=flat-square)60![PM2](https://img.shields.io/badge/PM2-web%20%C2%B7%20worker%20%C2%B7%20backup-2B037A?style=flat-square&logo=pm2&logoColor=white)61![déploiement](https://img.shields.io/badge/d%C3%A9ploiement-mld-orange?style=flat-square)62![tunnel](https://img.shields.io/badge/tunnel-MacLustr%20Tunnel%20%C2%B7%20Caddy%20%2B%20WireGuard-1F8B4C?style=flat-square&logo=wireguard&logoColor=white)6364</div>6566---6768## Sommaire6970- [Vue d'ensemble](#-vue-densemble)71- [Fonctionnalités](#-fonctionnalités)72- [Architecture](#-architecture)73- [Pile technique](#-pile-technique)74- [Arborescence du dépôt](#-arborescence-du-dépôt)75- [Démarrage local](#-démarrage-local)76- [Configuration](#-configuration)77- [Pages](#-pages)78- [API](#-api)79- [Pipeline d'import](#-pipeline-dimport)80- [Diffusion audio](#-diffusion-audio)81- [Paroles synchronisées (karaoké)](#-paroles-synchronisées-karaoké)82- [Clients natifs](#-clients-natifs)83- [Modèle de données](#-modèle-de-données)84- [Sécurité et vie privée](#-sécurité-et-vie-privée)85- [Vérifications et tests](#-vérifications-et-tests)86- [Déploiement et exploitation](#-déploiement-et-exploitation)87- [Sauvegarde et restauration](#-sauvegarde-et-restauration)88- [Dépannage et pièges connus](#-dépannage-et-pièges-connus)89- [Limites connues](#-limites-connues)90- [Documentation](#-documentation)91- [Auteur](#-auteur)92- [Licence](#-licence)9394---9596## 🎯 Vue d'ensemble9798Music SP est un **lecteur musical privé** : il lit la bibliothèque audio personnelle de son propriétaire, hébergée99sur son cluster. Production : **https://music.spboucher.ai**.100101Ce n'est **pas un service de catalogue** : la bibliothèque ne contient que des fichiers téléversés par un102administrateur (achats numériques, CD personnels numérisés, créations, licences appropriées). Rien n'est extrait d'un103service de streaming.104105- **Écoute** — accueil, recherche, pages album / artiste, file d'attente, favoris, listes de lecture, reprise de106  lecture par compte, paroles synchronisées, PWA installable.107- **Administration** — import par glisser-déposer avec reprise, détection des doublons, correction des tags,108  pochettes, comptes, santé du système, journal d'audit.109- **Accès** — clés d'accès WebAuthn uniquement (Face ID / Touch ID / code de l'appareil). Aucun mot de passe, aucune110  inscription publique. Deux rôles : administrateur et auditeur.111112### Famille SP Music113114| Dépôt | Plateforme | Rôle |115|---|---|---|116| **[sp-music](https://git.spboucher.ai/sp-music)** (ce dépôt) | Web · PWA | Serveur : site, API `/api/v1`, worker d'import, diffusion audio, paroles |117| [sp-music-macos](https://git.spboucher.ai/sp-music-macos) | macOS | Client natif : copie locale du catalogue, lecture hors ligne |118| [sp-music-ios](https://git.spboucher.ai/sp-music-ios) | iOS · iPadOS | Client natif : même API, lecture hors ligne |119120Les deux applications natives utilisent les mêmes surfaces d'API que le site, plus la synchronisation incrémentale,121l'association d'appareil et l'historique d'écoute décrits dans [Clients natifs](#-clients-natifs).122123## ✨ Fonctionnalités124125| Domaine | Ce que fait le code |126|---|---|127| Écoute | accueil, recherche (titre, artiste, album, genre — index trigrammes), pages album et artiste, bibliothèque triable |128| 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 |129| 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`) |130| Paroles | vue karaoké : transcription locale Whisper avec horodatage par mot, correction ligne par ligne par un administrateur |131| Import (`/admin`) | glisser-déposer de fichiers, dossiers ou ZIP ; envoi par morceaux avec reprise ; validation sur les octets ; doublons ; remplacement confirmé et journalisé |132| Bibliothèque (`/admin`) | correction des tags et de l'ordre des pistes, pochettes, réanalyse, suppression auditée |133| Comptes (`/admin`) | invitation par lien à usage unique, rôles, suspension, révocation des sessions |134| Système (`/admin`) | santé (base, stockage, worker), dernière sauvegarde, journal d'audit |135| Accès | clés d'accès WebAuthn seulement, huit codes de récupération, sessions révocables, CSRF, limitation de débit |136| Formats | FLAC, MP3, AAC / M4A, WAV, ALAC, AIFF, Ogg, DSD (DSF / DFF) — l'original est toujours conservé |137| Clients natifs | catalogue incrémental par révisions, association d'appareil par code court, historique d'écoute, fichier `apple-app-site-association` |138| PWA | manifeste et icônes (installable sur l'écran d'accueil ; en ligne seulement) |139| Langues | français (défaut) et anglais — 449 chaînes, une ligne par chaîne dans `src/i18n/messages.ts` |140141## 🏗 Architecture142143```mermaid144flowchart TB145    B["Navigateur · PWA<br/>music.spboucher.ai"]146    N["Apps natives<br/>SP Music macOS · iOS"]147    subgraph GW["Passerelle MacLustr Tunnel"]148        C["Caddy · TLS"]149    end150    subgraph NODE["Nœud m5ma"]151        S["sp-music-web · server.ts · port 8690"]152        MH["media-http.ts<br/>/api/v1/stream · /api/v1/art<br/>Node natif, Range exact"]153        NX["Next.js 16<br/>pages + API JSON"]154        W["sp-music-worker<br/>import · rendus · paroles · ménage"]155        BK["sp-music-backup<br/>PM2 cron 03:45"]156        DB[("PostgreSQL 17<br/>base sp_music")]157        ST[("STORAGE_ROOT<br/>originaux · pochettes · rendus")]158        FF["ffprobe / ffmpeg"]159        WH["mlx-whisper<br/>scripts/transcribe.py"]160    end161    B -->|HTTPS| C162    N -->|HTTPS| C163    C -->|WireGuard| S164    S --> MH165    S --> NX166    NX <--> DB167    MH --> DB168    MH --> ST169    W <--> DB170    W --> FF171    W --> WH172    W --> ST173    BK -->|"pg_dump chiffré + rsync"| DB174    BK --> ST175```176177### Séparation des responsabilités1781791. **Interface et lecteur** — `src/app`, `src/components`.1802. **API** — quatre surfaces, une route attrape-tout chacune ; le garde s'exécute *avant* la recherche du181   gestionnaire (`src/lib/api/router.ts`). Un gestionnaire d'administration ne peut pas être atteint sans le contrôle182   de rôle : il n'est même pas recherché avant.1833. **Métadonnées** — PostgreSQL. La base ne contient que des métadonnées et des clés de stockage.1844. **Originaux** — `STORAGE_ROOT/originals/<aa>/<sha256>.<ext>`, jamais modifiés, jamais sous `public/`.1855. **Pochettes et rendus** — `art/<aa>/<sha256>/{orig.*,96.jpg,320.jpg,640.jpg}`, `renditions/<aa>/<track>.m4a`.1866. **Traitement asynchrone** — `src/worker/index.ts` ; la file est la table `uploads` elle-même187   (`FOR UPDATE SKIP LOCKED`) : rien n'est perdu à un redémarrage.188189### Connexion par clé d'accès190191```mermaid192sequenceDiagram193    autonumber194    participant U as Utilisateur195    participant B as Navigateur196    participant A as /api/v1/auth197    participant D as PostgreSQL198    U->>B: « Se connecter »199    B->>A: POST login/options200    A->>D: challenge à usage unique (5 min)201    A-->>B: options WebAuthn (clés découvrables)202    B->>U: Face ID / Touch ID203    U-->>B: vérification locale204    B->>A: POST login/verify (signature)205    A->>D: lit et supprime le challenge206    A->>A: vérifie signature, origine, RP ID, UV, compteur207    A->>D: nouvelle session (SHA-256 du jeton)208    A-->>B: cookie spmusic_session + jeton CSRF209```210211## 🧱 Pile technique212213| Couche | Technologie | Version | Rôle |214|---|---|---|---|215| Interface + API | Next.js (App Router) | 16.4.6 | pages et API JSON |216| UI | React · React DOM | 19.3.1 | composants, lecteur persistant |217| Styles | Tailwind CSS (`@tailwindcss/postcss`) | 4.3.5 | thème, accents |218| Langage | TypeScript | 6.0.3 | tout le code applicatif |219| 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 |220| Métadonnées | PostgreSQL + `postgres` | 17 · 4.1.0 | `db/migrations/*.sql`, appliquées une fois, sommes de contrôle |221| Fichiers | volume privé du nœud (`STORAGE_ROOT`) | — | derrière l'interface `Storage` (`src/server/storage.ts`) |222| Traitement asynchrone | worker `tsx` | — | la file est la table `uploads` |223| Audio | `ffprobe` / `ffmpeg` | Homebrew | appelés avec un vecteur d'arguments (jamais de shell) |224| Paroles | `mlx-whisper`, modèle `mlx-community/whisper-large-v3-turbo` | — | transcription locale, horodatage par mot |225| WebAuthn | `@simplewebauthn/server` · `@simplewebauthn/browser` | 14.1.0 · ^14.0.0 | clés d'accès |226| Validation | Zod | 4.6.7 | schémas stricts de chaque corps de requête |227| Archives | yauzl | 3.2.0 | lecture des ZIP |228| Tests | Vitest | 5.1.0 | tests HTTP sur un build de production |229| Lint | ESLint + `eslint-config-next` | 10.14.0 · 16.4.6 | `src scripts tests server.ts` |230| Orchestration | PM2 via `mld` (MacLustr) | — | HTTPS par Caddy sur la passerelle du MacLustr Tunnel |231232Versions lues dans `package.json` (plancher des plages `^`).233234## 🗂 Arborescence du dépôt235236```237sp-music/238├── server.ts                    processus web : HTTP Node → media-http, sinon Next.js239├── next.config.ts               CSP statique, en-têtes de sécurité, compress: false240├── db/migrations/241│   ├── 001_init.sql             comptes, clés d'accès, sessions, catalogue, imports, listes, favoris242│   ├── 002_lyrics.sql           paroles synchronisées243│   └── 003_native_clients.sql   révisions, pierres tombales, association d'appareil, historique244├── src/245│   ├── app/246│   │   ├── (app)/               accueil, bibliothèque, recherche, album, artiste, favoris, listes, compte, admin247│   │   ├── (auth)/              login, setup, appareil248│   │   └── api/                 health + 4 routes attrape-tout /api/v1/{auth,library,me,admin}249│   ├── components/              lecteur (player, player-ui, lyrics-view), shell, admin/*, auth-forms250│   ├── i18n/                    messages.ts : [français, English]251│   ├── lib/252│   │   ├── api/                 router.ts (garde avant gestionnaire), schemas.ts, *routes.ts253│   │   └── …                    auth, session, session-store, crypto, ratelimit, audit, env, db, http254│   ├── server/                  catalog, ingest, media, media-http, range, storage, lyrics, sync, admin255│   └── worker/index.ts          file d'import, rendus AAC, réanalyse, paroles, ménage, battement256├── scripts/257│   ├── migrate.ts               applique les migrations (transactionnelles, sommes de contrôle)258│   ├── bootstrap.ts             crée le propriétaire, écrit son lien d'inscription259│   ├── setup-token.ts           réémet un lien d'inscription (--recovery)260│   ├── import.ts                import côté serveur par le pipeline normal261│   ├── lyrics.ts                met des pistes en file pour la transcription262│   ├── transcribe.py            mlx-whisper, horodatage par mot263│   ├── rebuild-derived.ts       vérifie les originaux, refait miniatures et rendus264│   ├── backup.sh · restore.sh   sauvegarde chiffrée et restauration265│   ├── secrets-scan.ts          recherche de secrets dans le dépôt266│   └── test.sh                  suite d'intégration complète267├── tests/                       unit, api, restart + authentificateur WebAuthn logiciel (webauthn.ts)268├── public/                      icônes, manifeste PWA, robots.txt269└── docs/                        ARCHITECTURE.md · SECURITY.md · OPERATIONS.md · brand/270```271272## 🚀 Démarrage local273274Prérequis : Node.js, pnpm, PostgreSQL 17 (extensions `citext` et `pg_trgm`), `ffmpeg` + `ffprobe`.275276```bash277pnpm install278createdb sp_music_dev279cp .env.example .env          # APP_URL=http://localhost:8690, DATABASE_URL, STORAGE_ROOT, APP_SECRET…280pnpm migrate && node_modules/.bin/tsx scripts/bootstrap.ts   # affiche le lien d'inscription du propriétaire281pnpm dev                      # http://localhost:8690  (localhost est un contexte sûr : les clés d'accès y fonctionnent)282pnpm worker                   # dans un second terminal283```284285| Script `pnpm` | Commande | Rôle |286|---|---|---|287| `dev` | `tsx server.ts` | serveur de développement |288| `build` | `next build` | build de production |289| `start` | `NODE_ENV=production tsx server.ts` | serveur de production |290| `worker` | `tsx src/worker/index.ts` | worker d'arrière-plan |291| `migrate` | `tsx scripts/migrate.ts` | migrations |292| `typecheck` | `tsc --noEmit` | types |293| `lint` | `eslint src scripts tests server.ts` | lint |294| `test` | `bash scripts/test.sh` | suite d'intégration |295| `secrets:scan` | `tsx scripts/secrets-scan.ts` | recherche de secrets |296297## ⚙️ Configuration298299Tout passe par `.env` (jamais commité ; modèle : [`.env.example`](.env.example)). Noms seulement :300301| Variable | Rôle | Défaut |302|---|---|---|303| `APP_URL` | origine publique exacte ; WebAuthn la compare octet pour octet | `http://localhost:8690` |304| `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` |305| `APP_SECRET` | secret applicatif, 32 caractères au moins | requis |306| `PORT` · `HOST` | écoute du processus web | `8690` · `0.0.0.0` |307| `OWNER_EMAIL` · `OWNER_NAME` | premier administrateur créé par `scripts/bootstrap.ts` | — |308| `SETUP_URL_FILE` | fichier (0600) où est écrit le lien d'inscription du propriétaire | — |309| `DATABASE_URL` | PostgreSQL (métadonnées seulement) | requis |310| `STORAGE_DRIVER` | `local` (seul pilote livré) | `local` |311| `STORAGE_ROOT` | point de montage de la bibliothèque, hors du dossier de l'application | requis |312| `TMP_DIR` | espace de travail des envois en cours | `$STORAGE_ROOT/.tmp` |313| `UPLOAD_MAX_FILE_MB` | taille maximale d'un fichier | `2048` |314| `UPLOAD_MAX_CHUNK_MB` | taille maximale d'un corps de requête | `16` |315| `UPLOAD_MAX_FILES` | fichiers en cours simultanés (et fichiers audio par archive) | `500` |316| `LIBRARY_QUOTA_GB` | quota total de la bibliothèque ; `0` = aucun | `0` |317| `ARCHIVE_MAX_ENTRIES` · `ARCHIVE_MAX_TOTAL_MB` · `ARCHIVE_MAX_RATIO` | bornes des ZIP | `2000` · `20480` · `100` |318| `UPLOAD_RETENTION_DAYS` | purge des imports terminés ou abandonnés | `30` |319| `RENDITIONS` | `auto` (rendu AAC à l'import et à la demande) ou `never` | `auto` |320| `RENDITION_BITRATE_KBPS` | débit du rendu AAC | `256` |321| `TRANSCODE_DSD` | produire aussi un rendu lisible pour le DSD | `false` |322| `FFMPEG_PATH` · `FFPROBE_PATH` | chemins des binaires | `ffmpeg` · `ffprobe` |323| `LYRICS` | `off`, `manual` ou `auto` | `off` |324| `LYRICS_PYTHON` | Python d'un environnement virtuel avec `mlx-whisper` | — |325| `LYRICS_MODEL` | modèle Whisper | `mlx-community/whisper-large-v3-turbo` |326| `BACKUP_DIR` · `BACKUP_PASSPHRASE_FILE` · `BACKUP_TRASH_DAYS` | sauvegardes (`scripts/backup.sh`) | — · — · `30` |327| `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 |328329## 🧭 Pages33033113 pages (`page.tsx`) : 10 dans l'application, 3 d'authentification.332333| Route | Groupe | Contenu |334|---|---|---|335| `/` | app | accueil |336| `/bibliotheque` | app | albums, artistes, pistes |337| `/recherche` | app | recherche |338| `/album/[id]` · `/artiste/[id]` | app | fiches album et artiste |339| `/favoris` | app | favoris |340| `/listes` · `/listes/[id]` | app | listes de lecture |341| `/compte` | app | clés d'accès, sessions, préférences |342| `/admin` | app | import, bibliothèque, comptes, système |343| `/login` | auth | connexion par clé d'accès, code de récupération |344| `/setup` | auth | inscription par lien à usage unique |345| `/appareil` | auth | approbation d'une application native |346347## 🔌 API348349Préfixe `/api/v1`. Quatre surfaces, 73 routes JSON, plus trois routes servies nativement par `server.ts` et350`GET /api/health`.351352| Surface | Garde | Routes | Contenu |353|---|---|---|---|354| `/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 |355| `/api/v1/library/*` | `requireUser` | 26 | catalogue, recherche, favoris, listes, état de lecture, synchronisation, historique, rendu AAC, paroles |356| `/api/v1/me/*` | `requireUser` | 8 | clés d'accès, sessions, préférences du compte, codes de récupération |357| `/api/v1/admin/*` | `requireAdmin` | 27 | import, édition, suppression, paroles, comptes, santé, journal |358359<details>360<summary><b>auth — 12 routes</b></summary>361362| Méthode | Chemin |363|---|---|364| GET | `session` |365| POST | `setup/info` |366| POST | `register/options` · `register/verify` |367| POST | `login/options` · `login/verify` |368| POST | `recovery` |369| POST | `device/start` · `device/poll` · `device/info` · `device/decide` |370| POST | `logout` |371372</details>373374<details>375<summary><b>library — 26 routes</b></summary>376377| Méthode | Chemin | Notes |378|---|---|---|379| GET | `home` | accueil du compte |380| GET | `albums` · `albums/:id` | tri `recent`, `title`, `artist`, `year` |381| GET | `artists` · `artists/:id` | |382| GET | `tracks` · `tracks/:id` | tri `title`, `recent`, `artist` |383| GET | `search?q=` | 100 caractères au plus |384| GET | `favorites` | |385| PUT · DELETE | `favorites/:kind/:id` | `kind` = `track` ou `album` |386| GET · POST | `playlists` | |387| GET · PATCH · DELETE | `playlists/:id` | `baseUpdatedAt` facultatif → `409 conflict` |388| POST | `playlists/:id/tracks` | |389| PUT | `playlists/:id/order` | |390| GET | `sync?since=<rev>` · `sync/me` | clients natifs |391| GET · POST | `history` | historique d'écoute |392| GET · PUT | `playback` | état de lecture |393| POST | `tracks/:id/compat` | demande de rendu AAC |394| GET | `tracks/:id/lyrics` | |395396</details>397398<details>399<summary><b>me — 8 routes</b></summary>400401| Méthode | Chemin |402|---|---|403| PATCH | `preferences` (langue `fr` / `en`, accent, nom affiché) |404| GET | `passkeys` |405| PATCH · DELETE | `passkeys/:id` |406| GET | `sessions` |407| DELETE | `sessions/:id` |408| POST | `sessions/revoke-others` |409| GET | `recovery-codes` |410411</details>412413<details>414<summary><b>admin — 27 routes</b></summary>415416| Méthode | Chemin |417|---|---|418| GET | `uploads/limits` |419| GET · POST | `uploads` (filtre `all`, `active`, `error`, `duplicate`, `ready`) |420| GET · PATCH · DELETE | `uploads/:id` (`PATCH ?offset=N` = un morceau) |421| POST | `uploads/:id/retry` · `uploads/:id/replace` · `uploads/clear` |422| PATCH | `tracks` |423| POST | `tracks/delete` · `tracks/reanalyse` |424| PATCH | `albums/:id` |425| PUT | `albums/:id/order` · `albums/:id/artwork` |426| POST | `albums/:id/delete` |427| POST | `lyrics/generate` (langues `fr`, `en`, `es`, `it`, `de`, `pt`) |428| PUT · DELETE | `tracks/:id/lyrics` |429| GET · POST | `users` |430| PATCH · DELETE | `users/:id` |431| POST | `users/:id/invite` · `users/:id/revoke-sessions` |432| GET | `health` · `audit` |433434Les suppressions de pistes et d'albums exigent `confirm: true` dans le corps.435436</details>437438**Routes natives (`src/server/media-http.ts`)**439440| Méthode | Chemin | Rôle |441|---|---|---|442| GET · HEAD | `/api/v1/stream/<uuid piste>[?v=compat]` | audio, HTTP Range (206) |443| GET · HEAD | `/api/v1/art/<uuid pochette>[?s=96\|320\|640\|orig]` | pochettes |444| GET | `/.well-known/apple-app-site-association` | autorise les applications natives à utiliser les clés d'accès du site |445446**Santé** : `GET /api/health` → `{ok, db, storage, worker}` (503 si la base ou le stockage ne répond pas ; le447worker est sain si son battement a moins de 120 s).448449## 📥 Pipeline d'import450451```452navigateur : POST /admin/uploads {nom, taille}  →  PATCH /admin/uploads/<id>?offset=N (morceaux de 8 Mo, écrits en flux)453uploading → received → validating → extracting → ready | duplicate | error | cancelled454```455456- **Reprise** : un morceau envoyé au mauvais décalage reçoit `409` avec le décalage attendu ; le client reprend là.457- **Validation** : type déterminé par les premiers octets (`sniff`), jamais par l'extension ; puis `ffprobe` doit458  trouver un flux audio mesurable. Exécutables, textes, vidéos : refusés.459- **Doublons** : `same_file` (même SHA-256) ou `same_track` (même artiste d'album, album, disque, numéro, titre).460  Rien n'est remplacé sans confirmation explicite ; le remplacement garde l'identifiant de la piste (listes et461  favoris intacts) et est journalisé.462- **ZIP** : chaque entrée audio est écrite sous un nom généré par le serveur ; limites sur le nombre d'entrées, la463  taille par entrée, la taille totale et le taux de compression, mesurées sur les octets produits ; archives464  chiffrées, imbriquées ou contenant un chemin `../` : refusées.465- **Tags** : titre, artiste, album, artiste d'album, piste, disque, année, genre ; à défaut, le nom du fichier466  (« 03 Titre.wav »).467- **Pochette** : extraite du fichier sans réencodage, dédupliquée par empreinte ; miniatures carrées JPEG générées à468  part.469- **Reprise après panne** : un travail interrompu retourne dans la file (trois tentatives, puis une erreur visible).470471**Import côté serveur** (administrateur avec accès shell au nœud, sans session) — même pipeline que l'interface :472473```bash474node_modules/.bin/tsx scripts/import.ts <dossier> --wait475```476477## 🎧 Diffusion audio478479- `GET /api/v1/stream/<uuid>` exige la session ; `Range` → `206` avec `Content-Range` et `Content-Length` exacts ;480  `416` si la plage est hors fichier ; `ETag` = identifiant de l'asset, `Cache-Control: private, no-cache` (un481  fichier remplacé change d'asset, donc d'ETag).482- Lecture depuis le disque par `createReadStream({start, end})` : un morceau n'est jamais chargé en mémoire.483- **Original d'abord.** `tracks.web_playable` :484485  | Valeur | Formats | Comportement |486  |---|---|---|487  | `yes` | FLAC, MP3, AAC, WAV | original servi tel quel |488  | `some` | ALAC, AIFF, Ogg | rendu AAC préparé à l'import |489  | `no` | DSD | original conservé, rendu seulement si `TRANSCODE_DSD=true` |490491- Le lecteur choisit avec `canPlayType` ; si le navigateur échoue à décoder un original, il demande le rendu492  (`POST /library/tracks/<id>/compat`) et reprend à la même position.493- Aucun transcodage haute résolution : le rendu de compatibilité est un AAC (`RENDITION_BITRATE_KBPS`, 44,1 / 48 kHz).494495**Stockage.** `src/server/storage.ts` définit `Storage` (`putFile`, `put`, `read(range)`, `size`, `delete`,496`localPath`, `health`). Seul le pilote `local` est livré : le cluster n'a pas de stockage objet. Un pilote S3497s'ajoute en implémentant cette interface (`localPath` devant alors télécharger vers un fichier temporaire pour498ffmpeg) ; `STORAGE_DRIVER=s3` échoue aujourd'hui explicitement plutôt que de faire semblant.499500## 🎤 Paroles synchronisées (karaoké)501502Les paroles sont transcrites **sur le nœud** à partir de l'audio (mlx-whisper, modèle `whisper-large-v3-turbo`),503avec un horodatage par mot ; rien n'est envoyé à un service externe et aucun site de paroles n'est interrogé.504505```bash506uv venv ~/.venvs/whisper --python 3.12 && uv pip install -p ~/.venvs/whisper mlx-whisper     # une fois507# .env : LYRICS=auto (ou manual), LYRICS_PYTHON=$HOME/.venvs/whisper/bin/python508node_modules/.bin/tsx scripts/lyrics.ts --missing --wait            # toute la bibliothèque509node_modules/.bin/tsx scripts/lyrics.ts --album "Thriller" --lang en --overwrite510```511512- `LYRICS=auto` met aussi en file chaque nouvel import ; `manual` laisse l'administrateur décider (`/admin` →513  Bibliothèque → sélection → Paroles).514- La transcription d'une voix chantée sur de la musique reste imparfaite (mots mal entendus, langue mal détectée515  quand une piste commence par une longue intro : préciser la langue). Chaque ligne se corrige dans `/admin` →516  Bibliothèque → icône Paroles de la piste ; une correction manuelle n'est jamais écrasée sans demande explicite.517- Une piste sans voix est marquée « instrumental ». Les phrases inventées par le modèle sur du silence518  (« Thank you », « Sous-titrage… ») sont filtrées (`src/server/lyrics.ts`).519- Les scores non finis renvoyés par Whisper sur les passages instrumentaux ne cassent plus la sortie JSON520  (`scripts/transcribe.py`, commit `b475a70`).521522## 📱 Clients natifs523524Les applications macOS et iOS gardent leur propre copie du catalogue et lisent hors ligne. Elles utilisent les mêmes525surfaces que le site, plus ceci (migration `003_native_clients.sql`) :526527| Route | Rôle |528|---|---|529| `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. |530| `GET /api/v1/library/sync/me` | Listes (avec leurs entrées), favoris et état de lecture du compte, en une réponse. |531| `GET` / `POST /api/v1/library/history` | Historique d'écoute ; l'identifiant de chaque événement vient du client (renvoi sans doublon). |532| `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). |533| `POST /api/v1/auth/device/{start,poll,info,decide}` | Association d'appareil. Page d'approbation : `/appareil`. |534| `GET /.well-known/apple-app-site-association` | Autorise les applications (`APPLE_APP_IDS`) à utiliser les clés d'accès du site. |535536**Révisions.** `artists`, `albums` et `tracks` portent une colonne `rev` tirée d'une seule séquence par un537déclencheur ; un verrou consultatif de transaction est pris *avant* le tirage, donc les révisions sont validées dans538l'ordre croissant et la plus haute révision d'une réponse est un curseur sûr. Un changement de fichier539(`media_assets`) ou de paroles (`lyrics`) fait avancer la révision de la piste. La lecture se fait dans un seul540instantané (`REPEATABLE READ`).541542```mermaid543sequenceDiagram544    autonumber545    participant App as Application native546    participant API as /api/v1/auth/device547    participant Web as Navigateur déjà connecté548    App->>API: POST start549    API-->>App: code XXXX-XXXX (10 min)550    App->>Web: ouvre /appareil?code=…551    Web->>API: POST info (session + CSRF + origine)552    Web->>API: POST decide (approuver / refuser)553    loop jusqu'à la décision554        App->>API: POST poll (secret de l'application)555    end556    API-->>App: session propre (méthode device, 90 jours)557```558559## 🗃 Modèle de données56056125 tables, 3 migrations (`db/migrations/`). Une migration appliquée n'est jamais modifiée (somme de contrôle562vérifiée) : on en ajoute une.563564| Groupe | Tables |565|---|---|566| Comptes et accès | `users` (rôle `admin` / `listener`, un seul `is_owner`), `authenticators`, `sessions`, `setup_tokens`, `recovery_codes`, `webauthn_challenges`, `device_links` |567| Protection et journal | `rate_limits`, `audit_events`, `worker_heartbeat` |568| Catalogue | `artists`, `genres`, `albums`, `tracks`, `artworks`, `media_assets` (original, rendu, pochette, miniature), `lyrics`, `library_tombstones` |569| Import | `uploads` (import + file de traitement) |570| Données personnelles | `playlists`, `playlist_tracks`, `favorites`, `favorite_albums`, `playback_state`, `play_events` |571572Contraintes notables : un seul original par piste ; un même fichier (SHA-256) ne peut pas être stocké deux fois ; un573album est unique par (artiste d'album, titre normalisé) ; index trigrammes pour la recherche.574575```mermaid576erDiagram577    users ||--o{ authenticators : possede578    users ||--o{ sessions : ouvre579    users ||--o{ recovery_codes : detient580    users ||--o{ setup_tokens : recoit581    users ||--o{ device_links : approuve582    users ||--o{ playlists : cree583    users ||--o{ favorites : aime584    users ||--o{ favorite_albums : aime585    users ||--o| playback_state : reprend586    users ||--o{ play_events : ecoute587    users ||--o{ uploads : televerse588    artists ||--o{ albums : signe589    artists ||--o{ tracks : interprete590    genres ||--o{ albums : classe591    genres ||--o{ tracks : classe592    artworks ||--o{ albums : illustre593    albums ||--o{ tracks : contient594    tracks ||--o{ media_assets : stocke595    artworks ||--o{ media_assets : stocke596    tracks ||--o| lyrics : transcrit597    tracks ||--o{ playlist_tracks : figure598    playlists ||--o{ playlist_tracks : ordonne599    tracks ||--o{ favorites : aimee600    albums ||--o{ favorite_albums : aime601    tracks ||--o{ play_events : jouee602    tracks ||--o{ uploads : produit603```604605## 🔐 Sécurité et vie privée606607Détail complet : [`docs/SECURITY.md`](docs/SECURITY.md).608609**Clés d'accès (WebAuthn)**610611- **RP ID** : `music.spboucher.ai` (hôte de `APP_URL` ; `WEBAUTHN_RP_ID` permet un domaine parent). **Origine612  attendue** : `https://music.spboucher.ai`, comparée à l'identique. Le développement utilise613  `http://localhost:8690` (RP ID `localhost`), dans une base distincte.614- **Vérifié côté serveur à chaque opération** : challenge à usage unique (la ligne est supprimée à sa lecture,615  5 minutes de validité), signature, origine, RP ID, présence **et vérification** de l'utilisateur, compteur.616- **Stocké** : identifiant de la clé, clé publique, compteur, transports, type d'appareil, indicateur de617  synchronisation, nom, dates. **Jamais** de clé privée ni de donnée biométrique.618- Plusieurs clés par compte, renommables et révocables (`/compte`). La dernière clé ne peut pas être retirée depuis619  l'interface.620- Clés découvrables : la connexion n'envoie aucune liste de comptes ; une clé inconnue et une signature fausse621  produisent la même réponse.622623| Adresse ouverte | Effet |624|---|---|625| `http://music.spboucher.ai` | redirigé en HTTPS par Caddy |626| 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 |627| `http://localhost:8690` | développement seulement (contexte sûr par exception) |628629**Comptes et récupération**630631- `scripts/bootstrap.ts` crée l'unique compte propriétaire depuis `OWNER_EMAIL` et, tant qu'il n'a aucune clé632  d'accès, écrit un lien d'inscription à usage unique (24 h) dans `SETUP_URL_FILE` (mode 0600) — jamais dans un633  journal. Dès qu'une clé existe, plus aucun lien n'est émis. Il n'y a ni `admin/admin`, ni mot de passe, ni secret634  par défaut.635- Seul le SHA-256 des jetons est en base ; le jeton voyage dans le fragment d'URL (`#…`), qui n'apparaît ni dans les636  requêtes, ni dans les journaux du proxy, ni dans `Referer`.637- **Aucune inscription publique.** Un compte n'existe que parce qu'un administrateur l'a créé ; il reçoit un lien638  d'inscription à usage unique, affiché une seule fois (72 h).639- **Récupération** : (1) huit codes à usage unique, affichés une fois à la première clé, stockés hachés ; (2) pour le640  propriétaire, depuis le shell du nœud : `tsx scripts/setup-token.ts [--recovery]` (`--recovery` remplace toutes les641  clés et ferme toutes les sessions) ; (3) pour les autres comptes, un nouveau lien émis par un administrateur. Il642  n'existe aucune autre voie.643644**Association d'appareil.** L'application affiche un code court (`XXXX-XXXX`, 10 minutes) et ouvre645`/appareil?code=…` ; un navigateur déjà connecté par clé d'accès l'approuve (session + jeton CSRF + origine exigés) ;646l'application, qui interroge `device/poll` avec son propre secret (seul son SHA-256 est en base), reçoit alors sa647propre session (méthode `device`, 90 jours), visible et révocable dans « Compte ». Une association ne sert qu'une648fois ; refusée, expirée ou inconnue, elle ne donne rien. Débit limité : création 10 / 10 min par adresse, saisie de649codes 30 / 10 min par compte. L'application peut aussi se connecter directement par clé d'accès650(AuthenticationServices) : même vérification serveur que le navigateur.651652**Sessions et CSRF.** Cookie `spmusic_session` : jeton aléatoire de 256 bits (seul son SHA-256 est en base),653`HttpOnly`, `Secure` en production, `SameSite=Lax`, sans attribut `Domain`, 30 jours. Un nouveau jeton à chaque654authentification. Révocation côté serveur par l'utilisateur, par un administrateur, par la suspension du compte, par655la récupération. Toute requête modifiante doit venir de l'origine du site (`Origin`, `Sec-Fetch-Site`) et porter le656jeton CSRF de la session dans `X-CSRF-Token`.657658**Autorisation.** Rôle lu en base à chaque requête ; masquer un bouton n'est jamais l'autorisation. Les données659personnelles sont filtrées par `user_id` : l'identifiant d'un autre compte répond `404`. Le propriétaire ne peut être660ni rétrogradé, ni suspendu, ni supprimé.661662**Téléversement.** Type vérifié sur le contenu ; tailles bornées à la création, à chaque morceau et à l'analyse ;663quota optionnel ; espace disque vérifié. Les chemins de stockage sont construits par le serveur à partir d'empreintes664et d'UUID, et le pilote refuse toute clé hors de sa racine. Images : JPEG / PNG / WebP, 25 Mo et 8000 px par côté au665plus.666667**En-têtes.** CSP (`default-src 'self'`, `frame-ancestors 'none'`, `object-src 'none'`, aucune origine tierce),668`Strict-Transport-Security`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `X-Frame-Options: DENY`,669`Permissions-Policy`. Les réponses audio et image ajoutent `Cross-Origin-Resource-Policy: same-origin` et un cache670strictement privé. Aucune ressource externe n'est chargée ; aucun titre écouté ni fichier n'est transmis à un service671tiers.672673**Limitation de débit et journal.** Compteurs en base par adresse : authentification 30 / 10 min, codes de674récupération 5 / 15 min. `audit_events` consigne les actions d'administration ; jamais de contenu audio, de cookie,675de jeton, de code ni de challenge. Les erreurs renvoyées au client ne contiennent ni trace, ni chemin.676677## ✅ Vérifications et tests678679```bash680pnpm typecheck && pnpm lint681pnpm test          # scripts/test.sh : base et stockage neufs, build de production, worker réel, ffmpeg réel682pnpm secrets:scan683```684685| Fichier | Tests | Portée |686|---|---|---|687| `tests/unit.test.ts` | 5 | analyse de `Range`, noms, détection de type sur les octets |688| `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 |689| `tests/restart.test.ts` | 1 | les données survivent à un redémarrage |690| **Total** | **44** | puis sauvegarde → restauration dans une base et un stockage neufs |691692`pnpm test` génère ses propres fichiers audio (ondes sinusoïdales, voix de synthèse `say` pour les paroles) : aucun693enregistrement commercial n'est dans le dépôt. Il couvre : accès anonyme refusé, rôles côté serveur, WebAuthn694(origine, RP ID, signature, vérification utilisateur, challenge rejoué ou expiré, jeton à usage unique), CSRF, import695par morceaux et reprise, doublons, fichiers piégés, archives (traversée de chemin, bombe), Range / 206 / 416 / 304,696édition, suppression auditée, redémarrage, sauvegarde → restauration.697698- L'authentificateur WebAuthn est logiciel (`tests/webauthn.ts`).699- Les tests de paroles exigent un environnement `mlx-whisper` local ; sans lui ils sont sautés et le disent.700- `SKIP_BUILD=1` réutilise `.next` ; `TEST_PORT` change le port (8691 par défaut).701702## 🚢 Déploiement et exploitation703704Détail complet : [`docs/OPERATIONS.md`](docs/OPERATIONS.md).705706| | |707|---|---|708| Site | https://music.spboucher.ai |709| App `mld` | `sp-music`, épinglée sur son nœud (`mld status`), port 8690 |710| Dépôt (source de vérité) | sur le nœud : `~/apps/sp-music` ; origin spbgit `sp-music.git` |711| Processus PM2 | `sp-music-web` (`tsx server.ts`), `sp-music-worker`, `sp-music-backup` (cron 03:45) |712| Base | PostgreSQL 17 local, base `sp_music`, rôle `spmusic_app` |713| Bibliothèque | `~/data/sp-music/library` (originaux, pochettes, rendus), mode 0700 |714| Sauvegardes | `~/backups/sp-music` |715| Secrets | `~/apps/sp-music/.env` (0600), `~/.config/sp-music/backup-passphrase` |716717**Prérequis du domaine**718719- DNS : enregistrement `A` de `music.spboucher.ai` vers la passerelle du MacLustr Tunnel.720- HTTPS : certificat obtenu et renouvelé par Caddy ; HTTP redirigé vers HTTPS. Route posée par `mld deploy`721  (`tunnel.domain`).722- Le proxy transmet les corps en flux ; un morceau d'envoi fait 8 Mo (`UPLOAD_MAX_CHUNK_MB` borne le serveur) :723  garder la limite de corps du proxy au-dessus.724- `APP_URL` doit être exactement `https://music.spboucher.ai` : c'est l'origine que WebAuthn vérifie.725726<details>727<summary><b>Première installation</b> (faite par le déploiement, pour mémoire)</summary>728729```bash730# sur le nœud731brew install ffmpeg                                   # ffmpeg + ffprobe732createuser spmusic_app --pwprompt ; createdb -O spmusic_app sp_music733psql -d sp_music -c 'CREATE EXTENSION IF NOT EXISTS citext; CREATE EXTENSION IF NOT EXISTS pg_trgm;'734mkdir -p ~/data/sp-music/library ~/backups/sp-music ~/.config/sp-music && chmod 700 ~/data/sp-music ~/backups/sp-music ~/.config/sp-music735openssl rand -base64 48 > ~/.config/sp-music/backup-passphrase && chmod 600 ~/.config/sp-music/backup-passphrase736cp .env.example .env && chmod 600 .env                # remplir APP_SECRET, DATABASE_URL, OWNER_EMAIL, chemins737# depuis le poste opérateur738mld stage <dossier> sp-music && mld deploy sp-music   # pnpm install, migrations, bootstrap, build, PM2, route HTTPS739```740741</details>742743**Créer le propriétaire et inscrire Face ID / Touch ID**7447451. Le déploiement a créé le compte propriétaire et écrit un lien à usage unique (24 h) :746   `ssh <nœud> cat ~/data/sp-music/setup-url.txt`.747   Lien expiré ? `ssh <nœud>` puis `cd ~/apps/sp-music && node_modules/.bin/tsx scripts/setup-token.ts`.7482. Ouvrir ce lien **sur l'appareil à inscrire** (iPhone, iPad ou Mac), dans Safari.7493. « Créer la clé d'accès » : iOS / macOS affiche sa propre boîte de dialogue et demande Face ID ou Touch ID. Avec le750   trousseau iCloud activé, la clé est synchronisée sur les autres appareils Apple.7514. Noter les huit codes de récupération (affichés une seule fois) hors ligne.7525. Autres appareils : `/compte` → Clés d'accès → Ajouter, depuis une session ouverte ; sur un appareil sans session,753   le navigateur propose d'utiliser un iPhone à proximité (QR code).7546. Installer en PWA : Safari → Partager → « Sur l'écran d'accueil ».755756Auditeurs : `/admin` → Comptes → Nouveau compte → transmettre le lien (72 h, usage unique).757758**Mettre à jour (sur le nœud — remote-first)**759760```bash761ssh <nœud> ; cd ~/apps/sp-music762git pull --ff-only                      # ou éditer sur place763pnpm install --frozen-lockfile764node_modules/.bin/tsx scripts/migrate.ts765node_modules/.bin/next build766pm2 restart sp-music-web sp-music-worker767git add -A && git commit -m "…" && git push origin main768```769770Les migrations sont transactionnelles et ne s'appliquent qu'une fois ; une migration appliquée puis modifiée fait771échouer le déploiement (somme de contrôle). Ne jamais `mld move sp-music` sans déplacer la base et la bibliothèque772(voir [Sauvegarde et restauration](#-sauvegarde-et-restauration)).773774Journaux : `pm2 logs sp-music-web|sp-music-worker|sp-music-backup` (aucun secret ni contenu audio n'y est écrit).775776## 💾 Sauvegarde et restauration777778`scripts/backup.sh`, chaque nuit (PM2 `sp-music-backup`) :7797801. **Base** : `pg_dump` chiffré AES-256 → `~/backups/sp-music/db/sp-music-AAAAmmjj-HHMMSS.dump.enc` (30 jours), relu781   par `pg_restore --list` à chaque exécution.7822. **Bibliothèque** : miroir `rsync` des originaux et des pochettes → `~/backups/sp-music/library/` ; ce qui783   disparaît de la bibliothèque va dans `trash/<date>/` pendant `BACKUP_TRASH_DAYS` (30). Les rendus et miniatures,784   dérivés, ne sont pas sauvegardés.7853. `last-backup.json` alimente « Dernière sauvegarde » dans `/admin` → Système.786787> **À faire par le propriétaire** : cette sauvegarde est sur le même disque que la bibliothèque. Elle protège d'une788> suppression accidentelle, pas d'une panne du disque. Copie hors nœud, depuis une autre machine :789> `rsync -a <nœud>:backups/sp-music/ /chemin/de/sauvegarde/sp-music/` (planifiable ; les processus PM2 du nœud ne790> peuvent pas joindre le réseau local). Conserver aussi `backup-passphrase` ailleurs : sans elle les dumps sont791> illisibles.792793```bash794createdb -O spmusic_app sp_music                                   # base vide795scripts/restore.sh db ~/backups/sp-music/db/<fichier>.dump.enc "$DATABASE_URL"796scripts/restore.sh library ~/backups/sp-music/library ~/data/sp-music/library797node_modules/.bin/tsx scripts/rebuild-derived.ts                   # vérifie chaque original, refait les miniatures, remet les rendus en file798pm2 restart sp-music-web sp-music-worker799```800801`rebuild-derived.ts` sort en erreur et liste tout original manquant. Les clés d'accès sont liées au domaine, pas au802nœud : elles restent valides après une restauration tant que `APP_URL` / RP ID ne changent pas. La procédure est803exécutée par `pnpm test` à chaque passage.804805## 🩺 Dépannage et pièges connus806807| Symptôme | Cause probable / remède |808|---|---|809| « Clés d'accès indisponibles ici » | page ouverte en HTTP, par IP ou sur un autre hôte → ouvrir `https://music.spboucher.ai` |810| 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 |811| 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 |812| Plus aucune clé ni code | sur le nœud : `tsx scripts/setup-token.ts --recovery` |813| Import bloqué sur « reçu » | worker arrêté : `pm2 logs sp-music-worker`, `pm2 restart sp-music-worker` ; `/admin` → Système indique « Traitement » |814| Import en erreur « type refusé » | le contenu n'est pas un format audio accepté (vérifié sur les octets, pas l'extension) |815| « Non lisible ici » sur une piste | DSD sans `TRANSCODE_DSD=true`, ou rendu AAC en préparation / en échec (`/admin` → Bibliothèque → Réanalyser) |816| 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 |817| 413 à l'envoi | fichier au-dessus de `UPLOAD_MAX_FILE_MB`, ou morceau au-dessus de la limite du proxy |818| Santé | `curl https://music.spboucher.ai/api/health` → `{ok, db, storage, worker}` |819820**Pièges visibles dans le code**821822- **Pourquoi `server.ts`** : l'audio et les pochettes sont servis par un serveur HTTP Node natif823  (`src/server/media-http.ts`) pour garder un `Content-Length` et un cadrage `Range` exacts ; `next.config.ts` fixe824  `compress: false` (la passerelle compresse le texte, l'audio doit garder ses octets intacts).825- **Session hors Next** : la recherche de session utilisée par le serveur natif est dans826  `src/lib/session-store.ts`.827- **IPv4 d'abord** : `scripts/_env.ts` force `ipv4first` (les nœuds du cluster n'ont pas de route IPv6).828- **pnpm** : `pnpm-workspace.yaml` porte à la fois `allowBuilds` (pnpm 12, nœud) et `onlyBuiltDependencies`829  (pnpm 11).830- **CSP et tests** : pas de `upgrade-insecure-requests` (casse WebKit sur `http://127.0.0.1` dans les tests).831- **Next.js 16** : lire [`AGENTS.md`](AGENTS.md) avant de modifier le code — les conventions diffèrent des versions832  antérieures.833834## ⚠️ Limites connues835836- `script-src` et `style-src` autorisent `'unsafe-inline'` (amorçage de Next.js sans nonce). Aucun contenu tiers837  n'est chargé.838- Le port 8690 du nœud est joignable depuis le réseau local sans TLS ; l'en-tête `X-Forwarded-For` y est falsifiable839  (seule la limitation de débit en dépend). L'accès prévu passe par la passerelle.840- Les originaux ne sont pas chiffrés au repos par l'application (dossier en mode 0700 sur le nœud) ; les sauvegardes841  de la base le sont.842- La sauvegarde quotidienne est sur le même disque que la bibliothèque tant qu'une copie hors nœud n'est pas mise en843  place.844- Pas de service worker : pas de lecture hors ligne sur le web (les applications natives la fournissent).845- Seul le pilote de stockage `local` existe.846847## 📚 Documentation848849- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — composants, schéma, pipeline d'import, diffusion, API, clients natifs850- [`docs/SECURITY.md`](docs/SECURITY.md) — WebAuthn, sessions, domaine, en-têtes, menaces traitées, limites connues851- [`docs/OPERATIONS.md`](docs/OPERATIONS.md) — installation, propriétaire, Face ID / Touch ID, déploiement, sauvegarde, restauration, dépannage852- [`AGENTS.md`](AGENTS.md) — règles pour les agents de code (Next.js 16)853854## 👤 Auteur855856<div align="center">857<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>858859**Simon-Pierre Boucher** — conception, développement, exploitation<br>860[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai861862</div>863864## 📄 Licence865866Le dépôt ne contient pas de fichier de licence. Tous droits réservés © 2026 Simon-Pierre Boucher.867
Files main
Menu

Theme