## Comment l'authentification fonctionne

MaBibli n'a **pas de connexion propre**. L'identité vient entièrement du portail YunoHost :
nginx authentifie le visiteur, puis SSOwat injecte dans la requête les en-têtes `YNH_USER`,
`YNH_USER_EMAIL` et `YNH_USER_FULLNAME`, que l'application se contente de lire.

Conséquences pratiques :

- **Qui peut voir la bibliothèque se règle dans les permissions YunoHost** (`mabibli.main`),
  pas dans l'application.
- La collection est **commune** à toutes les personnes autorisées. Chaque livre garde une trace
  de qui l'a saisi, mais personne n'est cloisonné : c'est une bibliothèque de foyer.
- Les **statuts de lecture sont personnels** (chacun sa progression), les **prêts sont communs**
  (un livre absent l'est pour tout le monde).
- Se déconnecter du portail YunoHost ne déconnecte pas nécessairement des applications :
  chacune garde sa propre session. C'est une limite connue de YunoHost, pas de MaBibli.

⚠️ **Ne pas exposer le port interne.** Le service écoute volontairement sur `127.0.0.1`
uniquement. L'application fait confiance à `YNH_USER` parce que SSOwat écrase cet en-tête à
chaque requête ; un service joignable directement permettrait à quiconque de forger
`YNH_USER` et de contourner le portail. Le port n'est pas ouvert au pare-feu, et
`ASPNETCORE_URLS` dans l'unité systemd ne doit jamais être élargi à `0.0.0.0` ou `*`.

## Domaine entier obligatoire

MaBibli s'installe **sur un domaine entier**, pas sous un sous-chemin (`/mabibli`).

Le client est une application Blazor WebAssembly : son chemin de base et les empreintes
d'intégrité de son service worker sont figés **à la compilation**. Comme le paquet installe une
archive déjà compilée — et ne compile jamais rien sur le serveur — il n'existe pas de moyen
propre de les réécrire à l'installation. YunoHost refusera donc un changement d'URL vers un
sous-chemin.

## Où vivent les données

| Quoi | Où |
|---|---|
| Binaires et client web | `/var/www/mabibli` (appartient à `root`, l'application ne peut pas s'y écrire) |
| Base SQLite | `/home/yunohost.app/mabibli/mabibli.db` |
| Journaux | `journalctl -u mabibli` |

La base est **délibérément séparée des binaires** : une mise à jour remplace intégralement
`/var/www/mabibli` sans jamais toucher aux données. Le schéma est migré automatiquement au
démarrage, il n'y a aucune commande à lancer après une mise à jour.

## Sauvegarde

La base tourne en mode **WAL**. C'est important pour qui voudrait bricoler une sauvegarde à la
main : à un instant donné, l'essentiel des données peut se trouver dans `mabibli.db-wal` et
**pas** dans `mabibli.db`. Mesuré sur une base fraîchement migrée, `mabibli.db` faisait 4 Ko —
et ne contenait **aucune table** — pendant que le fichier `-wal` en portait 205 Ko.

Le script de sauvegarde du paquet ne copie donc pas les fichiers tels quels : il demande à
SQLite un instantané cohérent (`.backup`, l'API de sauvegarde en ligne), déposé à côté de la
base sous le nom `mabibli-instantane.db`. C'est ce fichier que la restauration remet en place,
en écartant au passage les `-wal` / `-shm` de l'archive, qui décrivaient l'état d'une autre
copie de la base.

Le service **n'est pas arrêté** pendant la sauvegarde : l'API de sauvegarde en ligne garantit la
cohérence du fichier produit sans bloquer les lectures, et couper l'application à chaque
sauvegarde nocturne coûterait une indisponibilité pour rien.

Pour une sauvegarde manuelle, la bonne commande est donc :

```bash
sqlite3 /home/yunohost.app/mabibli/mabibli.db ".backup '/quelque/part/mabibli.db'"
```

et surtout pas un `cp` du seul fichier `.db`.

## Le scan du code-barres exige HTTPS

L'accès à la caméra n'est autorisé par les navigateurs que dans un contexte sécurisé. En
production, le certificat Let's Encrypt de YunoHost suffit. En revanche, joindre le serveur par
son IP locale (`http://192.168.x.x`) fera **toujours** échouer le scan : ce n'est pas un
contexte sécurisé. La saisie manuelle de l'ISBN reste disponible dans tous les cas.

## Accès sortant nécessaire

Le serveur doit pouvoir joindre `catalogue.bnf.fr` et `openlibrary.org` en HTTPS pour
pré-remplir les fiches à partir d'un ISBN. Sans accès sortant, l'application fonctionne, mais
toute saisie devient manuelle.