Repository Public
1<div align="center">23<img src="docs/brand/logo.svg" alt="SP Browser Backend logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="SP Browser icon" width="112" height="112">89# sp-browser-backend1011**Backend de SP Browser (macOS + iOS) : recherche orchestrée (SP Search), comptes à clés d'accès (SP Identity) et synchronisation chiffrée de bout en bout (SP Sync) — trois services dans un seul processus Node, sans étape de build.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1415[](https://browser.spboucher.ai/api/health)161718192021222324252627282930313233[](https://git.spboucher.ai/sp-browser-backend/commits)34[](https://git.spboucher.ai/sp-browser-backend/commits)35[](https://git.spboucher.ai/sp-browser-backend/insights)36[](https://git.spboucher.ai/sp-browser-backend)37[](https://git.spboucher.ai/sp-browser-backend/insights)38[](https://git.spboucher.ai/sp-browser-backend)39[](https://git.spboucher.ai/sp-browser-backend/branches)40[](https://git.spboucher.ai/sp-browser-backend/tags)41[](https://git.spboucher.ai/sp-browser-backend)42434445464748495051525354555657</div>5859---6061## Sommaire6263- [Vue d'ensemble](#-vue-densemble)64- [Fonctionnalités](#-fonctionnalités)65- [Architecture](#-architecture)66- [Pile technique](#-pile-technique)67- [Arborescence du dépôt](#-arborescence-du-dépôt)68- [Démarrage](#-démarrage)69- [Configuration](#-configuration)70- [API](#-api)71- [Recherche — ce que le fournisseur permet réellement](#-recherche--ce-que-le-fournisseur-permet-réellement)72- [Identité](#-identité)73- [Synchronisation](#-synchronisation)74- [Modèle de données](#-modèle-de-données)75- [Sécurité et confidentialité](#-sécurité-et-confidentialité)76- [Tests](#-tests)77- [Déploiement et exploitation](#-déploiement-et-exploitation)78- [Dépannage et reprise](#-dépannage-et-reprise)79- [Limites connues](#-limites-connues)80- [Documentation](#-documentation)81- [Auteur](#-auteur)82- [Licence](#-licence)8384---8586## 🎯 Vue d'ensemble8788Backend de **SP Browser** (macOS + iOS) : trois services dans un seul processus Node. Production :89**https://browser.spboucher.ai**.9091| Service | Rôle |92|---|---|93| **SP Search** | `POST /api/search` — orchestration de recherche (web, images, vidéos) au-dessus de Tavily, avec normalisation, déduplication, cache, plafond de dépense et comptage d'usage. |94| **SP Identity** | Comptes à **clés d'accès** (WebAuthn/FIDO2), sessions liées à un appareil, récupération par clé de récupération. Aucun mot de passe. |95| **SP Sync** | Flux de changements **chiffré de bout en bout** : le serveur ne stocke que du texte chiffré. |9697Node ≥ 24 (TypeScript exécuté nativement, `node:sqlite`), deux dépendances : `fastify`, `@simplewebauthn/server`.98Aucune étape de build.99100### Famille SP Browser101102| Dépôt | Plateforme | Rôle |103|---|---|---|104| **[sp-browser-backend](https://git.spboucher.ai/sp-browser-backend)** (ce dépôt) | API web | SP Search, SP Identity, SP Sync |105| [sp-browser](https://git.spboucher.ai/sp-browser) | macOS + iOS | Navigateur natif WebKit, client de ce backend |106107Les applications n'ont jamais la clé du fournisseur de recherche : elles parlent seulement à ce backend.108109## ✨ Fonctionnalités110111| Domaine | Ce que fait le code |112|---|---|113| Recherche web | lots de 20 résultats Tavily, pages de 10, résumé facultatif étiqueté `generatedBy: "tavily"`, extraits nettoyés du balisage Markdown |114| Recherche d'images | images des pages trouvées (attribuées à leur page) + Wikimedia Commons (dimensions, auteur, licence) ; pages de 40 |115| Recherche de vidéos | Tavily restreint à YouTube / Vimeo / Dailymotion, chaque URL confirmée par l'oEmbed de la plateforme ; API YouTube Data v3 si `YOUTUBE_API_KEY` ; pages de 20 |116| Filtres | langue, région, période (`day`, `week`, `month`, `year`), recherche sécurisée |117| Cache | en mémoire, indexé par un hachage ; durée 20 min (web), 6 h (images), 3 h (vidéos) ; 600 entrées au plus ; requêtes identiques simultanées regroupées |118| Budget | plafond quotidien de crédits (`DAILY_CREDIT_BUDGET`) : au-delà, seules les réponses en cache sont servies |119| Limitation | par heure, par compte ou par IP hachée pour les anonymes ; limites par IP sur la création de compte, la connexion et la récupération |120| Identité | clés d'accès découvrables, clés supplémentaires, réauthentification avant action destructrice, récupération, sessions par appareil, invitations |121| Synchronisation | 10 collections chiffrées (dont `canvas` et `handoff`, ajoutées pour SP Browser 3.0), numéro de séquence par compte, détection de conflits, pierres tombales purgées après un an |122| Administration | `/admin` : santé, crédits, usage 30 jours et coût estimé, comptes, appareils, enregistrements chiffrés, erreurs, journal |123| Apple | `/.well-known/apple-app-site-association` (`webcredentials`) pour les clés d'accès des applications |124125## 🏗 Architecture126127```mermaid128flowchart TB129 APP["SP Browser<br/>macOS · iOS"]130 ADM["Administrateur<br/>/admin · jeton"]131 subgraph GW["Passerelle MacLustr Tunnel"]132 C["Caddy · TLS"]133 end134 subgraph NODE["Nœud m4mn"]135 subgraph P["sp-browser-backend · node src/server.ts · port 8710"]136 S["SP Search<br/>normalize → cache → budget → lots → pages"]137 I["SP Identity<br/>WebAuthn · sessions · invitations"]138 Y["SP Sync<br/>push · pull · clés"]139 end140 DB[("SQLite · WAL<br/>sp-browser.sqlite")]141 BK["sp-browser-backup<br/>PM2 cron quotidien"]142 end143 T["Tavily"]144 W["Wikimedia Commons"]145 O["oEmbed · YouTube Data v3"]146 APP -->|HTTPS| C147 ADM -->|HTTPS| C148 C -->|WireGuard| P149 S --> T150 S --> W151 S --> O152 S --> DB153 I --> DB154 Y --> DB155 BK -->|"VACUUM INTO + gzip"| DB156```157158### Ajout d'un nouvel appareil à la synchronisation chiffrée159160```mermaid161sequenceDiagram162 autonumber163 participant N as Nouvel appareil164 participant S as Serveur165 participant A as Appareil déjà autorisé166 N->>S: connexion par clé d'accès, publie sa clé publique d'accord de clé167 A->>S: GET /api/sync/keys/pending168 S-->>A: appareils en attente + clé publique169 A->>A: affiche un code de vérification dérivé de la clé publique170 Note over N,A: l'utilisateur compare le code sur les deux appareils171 A->>S: POST /api/sync/keys/approve (clé de compte scellée, HPKE)172 S->>S: refuse si la clé publique a changé depuis l'affichage173 N->>S: GET /api/sync/keys174 S-->>N: enveloppe (illisible pour le serveur)175 N->>N: ouvre l'enveloppe, obtient la clé de compte176 N->>S: GET /api/sync/pull?since=0177 S-->>N: enregistrements chiffrés178```179180## 🧱 Pile technique181182| Couche | Technologie | Version | Rôle |183|---|---|---|---|184| Runtime | Node.js | ≥ 24 (`engines`) | exécute le TypeScript directement, sans build |185| HTTP | Fastify | ^5.2.0 (verrouillé 5.12.8) | serveur, `trustProxy`, corps limité à 1 Mo, journal des requêtes désactivé |186| WebAuthn | `@simplewebauthn/server` | ^13.1.1 (verrouillé 13.3.3) | clés d'accès |187| Base | `node:sqlite` (SQLite, WAL) | intégré | comptes, sessions, texte chiffré, usage |188| Recherche | Tavily (`POST /search`, `/usage`) | API externe | web, images des pages, base des vidéos |189| Images | Wikimedia Commons (API MediaWiki publique) | API externe | médias sous licence libre |190| Vidéos | oEmbed YouTube / Vimeo / Dailymotion ; YouTube Data v3 (facultatif) | API externes | confirmation des pages de lecture |191| Tests | `node:test` | intégré | faux fournisseur HTTP, authentificateur WebAuthn logiciel |192| Orchestration | PM2 via `mld` (MacLustr) | — | HTTPS par Caddy sur la passerelle du MacLustr Tunnel |193194## 🗂 Arborescence du dépôt195196```197sp-browser-backend/198├── package.json scripts start, test, test:live, invite, backup ; 2 dépendances199├── src/200│ ├── server.ts assemblage Fastify, santé, AASA, /api/search, administration, ménage horaire201│ ├── config.ts configuration par l'environnement (.env), valeurs par défaut202│ ├── db.ts SQLite (WAL), migrations en ajout seul, PRAGMA user_version203│ ├── auth.ts SP Identity : 17 routes (inscription, connexion, clés, récupération, compte, appareils)204│ ├── sync.ts SP Sync : 10 routes (clés, push, pull, effacement)205│ ├── util.ts HttpError, OpsLog, RateLimiter, fetchJSON, hachages206│ └── search/207│ ├── service.ts orchestration : validation → cache → budget quotidien → lots → pages208│ ├── normalize.ts validation de la requête, clé de cache209│ ├── tavily.ts lots web Tavily210│ ├── images.ts images des pages + Wikimedia Commons211│ ├── video.ts vidéos : restriction de domaines, confirmation oEmbed, YouTube Data v3212│ └── types.ts types de requête, de réponse et d'erreur213├── public/admin.html tableau de bord d'administration (page unique)214├── scripts/215│ ├── invite.ts invitations : create [note] · list216│ └── backup.sh copie cohérente à chaud, contrôle d'intégrité, gzip, rétention217├── test/ helpers, identity-sync, search, live218└── docs/ OPERATIONS.md · SECURITY.md · brand/219```220221## 🚀 Démarrage222223```bash224cp .env.example .env && chmod 600 .env # renseigner TAVILY_API_KEY, SERVER_SECRET, ADMIN_TOKEN225npm install226npm test # 15 tests (faux fournisseur HTTP, authentificateur WebAuthn logiciel)227npm run test:live # essai réel Tavily + Commons + oEmbed (~4 crédits)228npm start229```230231> `.env.example` n'est pas versionné dans ce dépôt (le motif `.env.*` de `.gitignore` le masque) : la liste des232> variables est dans [Configuration](#-configuration) et dans `src/config.ts`.233234| Script `npm` | Commande | Rôle |235|---|---|---|236| `start` | `node src/server.ts` | serveur |237| `test` | `node --test --test-force-exit --test-timeout=30000 --test-concurrency=1 test/*.test.ts` | suite hors ligne |238| `test:live` | `LIVE=1 node --test --test-concurrency=1 test/live.test.ts` | essai réel contre les fournisseurs |239| `invite` | `node scripts/invite.ts` | invitations |240| `backup` | `bash scripts/backup.sh` | sauvegarde |241242Sans `SERVER_SECRET`, le processus démarre quand même (tests, premier démarrage) mais les clés de limitation de243débit changent à chaque redémarrage. Sans `TAVILY_API_KEY`, les recherches répondent 503.244245## ⚙️ Configuration246247Lue dans l'environnement ou dans `.env` (jamais dans git). Noms seulement ; défauts lus dans `src/config.ts`.248249| Variable | Rôle | Défaut |250|---|---|---|251| `PORT` · `HOST` | écoute | `8710` · `127.0.0.1` |252| `DATA_DIR` | dossier de la base `sp-browser.sqlite` (créé en mode 0700) | `./data` |253| `PUBLIC_ORIGIN` | origine publique ; origine attendue par WebAuthn | `http://localhost:8710` |254| `RP_ID` · `RP_NAME` | identifiant et nom de la partie de confiance | hôte de `PUBLIC_ORIGIN` · `SP Browser` |255| `APPLE_APP_IDS` | identifiants `<équipe>.<bundle>` servis dans le fichier d'association Apple | vide |256| `TAVILY_API_KEY` · `TAVILY_BASE` | fournisseur de recherche | — · API Tavily |257| `YOUTUBE_API_KEY` | facultatif : durée et date des vidéos YouTube | vide |258| `OEMBED_YOUTUBE` · `OEMBED_VIMEO` · `OEMBED_DAILYMOTION` | points d'accès oEmbed (remplaçables pour les tests) | plateformes officielles |259| `DAILY_CREDIT_BUDGET` | plafond de crédits Tavily par jour UTC | `400` |260| `ANON_SEARCH` | recherche sans session | `true` |261| `ANON_SEARCH_PER_HOUR` · `USER_SEARCH_PER_HOUR` | limites horaires | `40` · `600` |262| `OPEN_REGISTRATION` | création de compte sans invitation | `false` |263| `SESSION_DAYS` | durée glissante d'une session | `60` |264| `AUTH_RATE_MULTIPLIER` | multiplie les limites par IP d'authentification (instances de test) | `1` |265| `SERVER_SECRET` | secret du serveur (HMAC des IP, etc.) | aléatoire à chaque démarrage |266| `ADMIN_TOKEN` | jeton du tableau de bord | vide (administration fermée) |267268Points d'attention :269270- `RP_ID` / `PUBLIC_ORIGIN` : les clés d'accès sont liées à ce domaine — le changer invalide toutes les clés d'accès.271- `APPLE_APP_IDS` : Apple met le fichier d'association en cache, jusqu'à 24 h.272273## 🔌 API27427533 routes. Toutes les réponses portent `cache-control: no-store`, `x-content-type-options: nosniff` et276`referrer-policy: no-referrer`. Erreurs : `{ "error": { "code", "message" } }`.277278**Service et recherche (4)**279280| Méthode | Chemin | Rôle |281|---|---|---|282| GET | `/api/health` | `{ok, service, version, schema, providers}` |283| GET | `/.well-known/apple-app-site-association` | `webcredentials` pour les applications |284| POST | `/api/search` | recherche web, images, vidéos |285| GET | `/api/search/capabilities` | ce que la recherche sait et ne sait pas faire |286287<details>288<summary><b>SP Identity — 17 routes</b></summary>289290| Méthode | Chemin | Rôle |291|---|---|---|292| POST | `/api/auth/register/options` · `/api/auth/register/verify` | création de compte (invitation, sauf `OPEN_REGISTRATION=true`) |293| POST | `/api/auth/login/options` · `/api/auth/login/verify` | connexion ; clé découvrable : la clé d'accès identifie le compte |294| POST | `/api/auth/reauth/options` · `/api/auth/reauth/verify` | confirmation avant action destructrice |295| POST | `/api/auth/passkeys/options` · `/api/auth/passkeys/verify` | ajout d'une clé d'accès |296| DELETE | `/api/auth/passkeys/:id` | retrait d'une clé d'accès |297| POST | `/api/auth/recover/options` · `/api/auth/recover/verify` | récupération |298| GET · PATCH · DELETE | `/api/account` | compte |299| DELETE | `/api/devices/:id` | retrait d'un appareil |300| POST | `/api/auth/logout` · `/api/auth/logout-all` | déconnexion, « partout » |301302</details>303304<details>305<summary><b>SP Sync — 10 routes</b></summary>306307| Méthode | Chemin | Rôle |308|---|---|---|309| GET | `/api/sync/keys` | état des clés de l'appareil |310| POST | `/api/sync/keys/bootstrap` | premier appareil : mise en place |311| GET · PUT | `/api/sync/keys/recovery` | blob de récupération |312| POST | `/api/sync/keys/claim` | réclamation par la clé de récupération |313| GET | `/api/sync/keys/pending` | appareils en attente de clé |314| POST | `/api/sync/keys/approve` | approbation d'un appareil |315| POST | `/api/sync/push` | envoi de changements (500 au plus par requête) |316| GET | `/api/sync/pull?since=` | lecture du flux (`limit` de 1 à 1000, 500 par défaut) |317| DELETE | `/api/sync/data` | effacement des données synchronisées |318319</details>320321**Administration (2)** — `Authorization: Bearer $ADMIN_TOKEN`322323| Méthode | Chemin | Rôle |324|---|---|---|325| GET | `/api/admin/overview` | santé, crédits, usage, identité, synchronisation, erreurs, journal |326| GET | `/admin` | tableau de bord (page unique, CSP `default-src 'none'`) |327328## 🔎 Recherche — ce que le fournisseur permet réellement329330Vérifié dans la documentation Tavily le 2026-11-18 (`POST https://api.tavily.com/search`, `Authorization: Bearer`).331332| Besoin | Réalité Tavily | Ce que fait le backend |333|---|---|---|334| Recherche web | oui (`max_results` ≤ 20) | lots de 20, pages de 10 |335| Pagination | **aucun paramètre d'offset** | pages 1–2 dans le premier lot ; au-delà, nouveau lot avec `exclude_domains` = domaines déjà montrés (« autres sites ») |336| Résumé | `include_answer` | renvoyé dans `answer`, étiqueté `generatedBy: "tavily"` |337| Images | pas de point d'accès dédié ; `include_images` | images des pages trouvées (attribuées à leur page) + **Wikimedia Commons** (API publique, dimensions, auteur, licence) |338| Vidéos | **aucune recherche vidéo** | Tavily restreint à YouTube/Vimeo/Dailymotion, puis chaque URL doit être une page de lecture **confirmée par l'oEmbed de la plateforme** ; sinon elle est écartée. Avec `YOUTUBE_API_KEY` : API YouTube Data v3 (durée, date) |339| Suggestions, recherches associées, correction orthographique | **inexistants** | non fournis (`GET /api/search/capabilities` le dit) ; l'app suggère depuis l'historique local |340341Durée et date d'une vidéo YouTube ne sont disponibles qu'avec `YOUTUBE_API_KEY` (chemin testé contre un faux serveur,342**jamais contre l'API réelle** : aucune clé fournie). Vimeo les donne par oEmbed.343344`POST /api/search`345346```json347{ "query": "Apple Silicon AI benchmarks", "type": "web", "language": "en", "region": "ca", "page": 1,348 "timeRange": "month", "safeSearch": true, "summary": true }349```350351Réponse : `{ query, type, page, pageSize, hasMore, provider, cached, tookMs, answer, results[], notices[] }`.352353Erreurs : `rate_limited` (429), `budget_exhausted` (503), `provider_*` (429/502/503/504). Le texte d'erreur du354fournisseur et la clé ne sortent jamais.355356Protection : session facultative (`ANON_SEARCH`), limite par heure (par compte, ou par IP hachée pour les anonymes),357**plafond quotidien de crédits** (`DAILY_CREDIT_BUDGET`) : au-delà, seules les réponses en cache sont servies.358359Détails lus dans le code : une confirmation oEmbed restée sans réponse est retentée une fois et un lot incomplet360n'est jamais mis en cache ; les vignettes YouTube sont en 16:9 ; une panne de Commons ne fait jamais échouer la361recherche, une panne de Tavily oui ; rien n'est extrait d'un autre moteur de recherche.362363## 🪪 Identité364365`/api/auth/register/{options,verify}` · `/api/auth/login/{options,verify}` (clé découvrable : la clé d'accès366identifie le compte) · `/api/auth/passkeys/{options,verify}`, `DELETE /api/auth/passkeys/:id` ·367`/api/auth/reauth/{options,verify}` (confirmation avant action destructrice) · `/api/auth/recover/{options,verify}` ·368`GET/PATCH/DELETE /api/account` · `DELETE /api/devices/:id` · `/api/auth/logout`, `/api/auth/logout-all`.369370Création de compte sur invitation, sauf `OPEN_REGISTRATION=true` :371372```bash373node scripts/invite.ts create "note" # affiche un code à usage unique (seul son hachage est stocké)374node scripts/invite.ts list375```376377Limites par IP (multipliées par `AUTH_RATE_MULTIPLIER`) : création de compte 10 par heure, connexion 30 par37810 minutes, récupération 5 par heure.379380## 🔄 Synchronisation381382`/api/sync/keys` (+ `bootstrap`, `pending`, `approve`, `claim`, `recovery`) · `POST /api/sync/push` ·383`GET /api/sync/pull?since=` · `DELETE /api/sync/data`. Modèle et limites : [docs/SECURITY.md](docs/SECURITY.md).384385| Élément | Valeur (lue dans `src/sync.ts`) |386|---|---|387| Collections | `history`, `bookmarks`, `favorites`, `tabs`, `closed`, `reading`, `searches`, `prefs` |388| Changements par envoi | 500 au plus |389| Taille d'un enregistrement chiffré | 350 000 caractères au plus |390| Enregistrements par compte | 250 000 au plus (`quota_exceeded`, 413) |391| Conflit | l'envoi renvoie l'enregistrement courant du serveur dans `conflicts` |392| Pierres tombales | purgées après un an |393394## 🗃 Modèle de données395396SQLite (`sp-browser.sqlite`, WAL, clés étrangères actives). 9 tables, 3 migrations dans `src/db.ts` : liste397`MIGRATIONS`, ajout en fin de liste uniquement ; version suivie par `PRAGMA user_version`, chaque migration dans une398transaction, appliquée au démarrage. `GET /api/health` renvoie `schema`.399400| Table | Contenu |401|---|---|402| `users` | comptes |403| `credentials` | clés d'accès (clé publique, compteur) |404| `devices` | appareils, clé publique d'accord de clé, enveloppe de la clé de compte |405| `sessions` | hachage du jeton, appareil, expiration |406| `challenges` | défis WebAuthn à usage unique |407| `invites` | hachage du code, note, usage |408| `sync_records` | texte chiffré par (compte, collection, identifiant), numéro de séquence, pierre tombale |409| `account_keys` | matériel de clé du compte (blob de récupération, hachages, `key_version`) |410| `usage_daily` | compteurs par jour, fournisseur et type : requêtes, crédits, succès de cache, erreurs, latence |411412```mermaid413erDiagram414 users ||--o{ credentials : possede415 users ||--o{ devices : enregistre416 users ||--o{ sessions : ouvre417 devices ||--o{ sessions : porte418 users ||--o{ sync_records : synchronise419 users ||--o| account_keys : detient420```421422## 🔐 Sécurité et confidentialité423424Détail : [docs/SECURITY.md](docs/SECURITY.md).425426**Secrets.** `TAVILY_API_KEY`, `YOUTUBE_API_KEY`, `SERVER_SECRET`, `ADMIN_TOKEN` : uniquement dans `.env` (600) sur427le nœud. Jamais dans git, dans les apps, dans les réponses ni dans les journaux. Les erreurs du fournisseur sont428converties en codes stables ; un test vérifie que ni la clé ni le texte amont ne sortent. Jetons de session :42932 octets aléatoires, seul leur SHA-256 est stocké. Un jeton par appareil ; expiration glissante (`SESSION_DAYS`),430révocation immédiate (déconnexion, retrait d'appareil, « partout »).431432**Journaux.** La journalisation des requêtes HTTP est **désactivée**. Le journal opérationnel (en mémoire,433400 entrées) ne contient que des messages écrits par le code : jamais de requête de recherche, d'URL ni de jeton. Le434cache de recherche vit en mémoire, indexé par un hachage ; `usage_daily` ne compte que des nombres par jour. Les IP ne435servent qu'à limiter le débit, sous forme de HMAC.436437**Clés d'accès.** WebAuthn avec vérification de l'utilisateur obligatoire, clés découvrables, attestation `none`. Le438serveur vérifie défi (usage unique, 5 min), origine, identifiant de RP, signature et compteur. La biométrie reste dans439l'authentificateur du système : le serveur ne voit qu'une signature. Toutes les clés d'accès ne se synchronisent pas440entre appareils (dépend du trousseau / gestionnaire) : d'où l'ajout de clés supplémentaires et la clé de récupération.441442**Chiffrement de bout en bout de la synchronisation**443444- **Clé de compte** (256 bits) créée sur le premier appareil, conservée dans son trousseau. Le serveur ne la reçoit445 jamais.446- **Enregistrements** : AEAD (ChaCha20-Poly1305) avec une clé par collection dérivée par HKDF ; données associées =447 collection, identifiant, version de clé. Les identifiants des enregistrements dérivés d'une URL ou d'une requête448 sont des HMAC sous une clé dérivée : le serveur ne peut pas les inverser.449- **Nouvel appareil** : il publie une clé publique d'accord de clé ; un appareil déjà autorisé affiche un code de450 vérification dérivé de cette clé publique, l'utilisateur le compare, puis l'appareil scelle la clé de compte pour451 cette clé publique (HPKE). Le serveur transporte l'enveloppe sans pouvoir l'ouvrir. Le serveur refuse l'approbation452 si la clé publique a changé entre l'affichage et l'envoi ; le code de vérification protège contre un serveur qui453 substituerait la clé.454- **Récupération** : la clé de compte est aussi scellée sous la **clé de récupération** de l'utilisateur (affichée une455 fois, à conserver hors ligne). Le serveur garde ce blob et un hachage scrypt d'un authentifiant dérivé de la clé de456 récupération — pas la clé.457- **Preuve de détention** : approuver un appareil, changer la clé de récupération ou effacer les données exige une458 valeur dérivée de la clé de compte ; le serveur n'en garde que le hachage.459460**Ce que le serveur voit quand même.** Le nom de la collection (`history`, `bookmarks`, `tabs`…), des identifiants461opaques, la taille des enregistrements, les dates d'écriture, l'appareil qui a écrit, le nom et le modèle des462appareils. Il peut donc compter les pages visitées, pas les lire.463464## ✅ Tests465466```bash467npm test # 15 tests hors ligne468npm run test:live # 1 essai réel (~4 crédits Tavily), ignoré sans LIVE=1469```470471| Fichier | Tests | Portée |472|---|---|---|473| `test/search.test.ts` | 9 | recherche web / images / vidéos contre un faux fournisseur HTTP, cache, budget, erreurs |474| `test/identity-sync.test.ts` | 6 | comptes, clés d'accès (authentificateur WebAuthn logiciel), sessions, synchronisation |475| `test/live.test.ts` | 1 | Tavily + Wikimedia Commons + oEmbed réels ; jamais simulé, ignoré sinon |476477Les tests forcent la sortie du processus (`--test-force-exit`) et s'exécutent sans concurrence.478479## 🚢 Déploiement et exploitation480481Détail : [docs/OPERATIONS.md](docs/OPERATIONS.md).482483| | |484|---|---|485| Site | https://browser.spboucher.ai |486| App `mld` | `sp-browser-backend` (manifeste sur la passerelle du cluster) |487| Processus PM2 | `sp-browser-backend` (`node src/server.ts`, port 8710), `sp-browser-backup` (cron quotidien) |488| Exposition | route Caddy posée par `mld deploy` sur la passerelle du MacLustr Tunnel |489| Secrets | `~/apps/sp-browser-backend/.env` (600), exclu de git et du rsync |490| Données | `~/apps-data/sp-browser-backend/sp-browser.sqlite` (+ `-wal`, `-shm`) |491| Sauvegardes | `~/backups/sp-browser-backend/` |492493Le dossier déployé est le dépôt (`origin` = spbgit `sp-browser-backend.git`) : modifier **sur le nœud**,494`pm2 restart sp-browser-backend`, puis `git commit && git push` sur le nœud.495496**Sauvegarde.** `scripts/backup.sh` : copie cohérente à chaud (`VACUUM INTO`), contrôle d'intégrité, gzip, rétention49730 jours dans `~/backups/sp-browser-backend/`. La base contient des clés publiques, des hachages de jetons et du texte498chiffré de bout en bout : une sauvegarde seule ne révèle pas la navigation.499500**Restauration.**501502```bash503pm2 stop sp-browser-backend504cd ~/apps-data/sp-browser-backend && mv sp-browser.sqlite sp-browser.sqlite.bad; rm -f sp-browser.sqlite-wal sp-browser.sqlite-shm505gunzip -c ~/backups/sp-browser-backend/sp-browser-<date>.sqlite.gz > sp-browser.sqlite && chmod 600 sp-browser.sqlite506sqlite3 sp-browser.sqlite 'PRAGMA integrity_check'507pm2 start sp-browser-backend && curl -s localhost:8710/api/health508```509510Après restauration, les appareils dont le numéro de séquence dépasse celui de la sauvegarde renvoient leurs511changements manquants au prochain cycle (l'app repousse tout enregistrement local que le serveur ne connaît plus).512513**Surveillance.** `/admin` (ou `GET /api/admin/overview`, `Authorization: Bearer $ADMIN_TOKEN`) : santé, crédits du514jour / plafond, usage 30 jours et coût estimé (0,008 $ US par crédit, tarif à l'usage), compte Tavily (`/usage`,515rafraîchi au plus toutes les 15 minutes), comptes / appareils / sessions, enregistrements chiffrés par collection,516appareils en attente de clé, erreurs 24 h, journal opérationnel.517518## 🩺 Dépannage et reprise519520| Situation | Remède |521|---|---|522| Nœud perdu | `mld deploy sp-browser-backend --node X`, recopier `.env` et la dernière sauvegarde |523| Clé Tavily compromise | la régénérer chez Tavily, remplacer `TAVILY_API_KEY`, `pm2 restart`. Les apps n'ont jamais la clé |524| Utilisateur sans clé d'accès | il utilise sa clé de récupération dans l'app. Sans elle, personne (pas même l'administrateur) ne peut rouvrir ses données ; on peut seulement supprimer le compte |525| Nouvelle invitation | `node scripts/invite.ts create "pour qui"` |526| Recherches en 503 `budget_exhausted` | plafond `DAILY_CREDIT_BUDGET` atteint pour le jour UTC : seules les réponses en cache sont servies |527| Recherches en 503 au démarrage | `TAVILY_API_KEY` absente |528| Clé d'accès refusée dans l'app après déploiement | Apple met `apple-app-site-association` en cache jusqu'à 24 h ; vérifier `APPLE_APP_IDS` |529| Toutes les clés d'accès invalides | `RP_ID` ou `PUBLIC_ORIGIN` a changé |530| `/admin` répond 401 | `ADMIN_TOKEN` absent ou erroné |531532## ⚠️ Limites connues533534- Retirer un appareil coupe ses sessions et supprime son enveloppe, mais **ne fait pas tourner la clé de compte** : un535 appareil retiré garde ce qu'il avait déjà déchiffré. La rotation (`key_version`) est prévue par le schéma, pas536 implémentée.537- Perdre à la fois tous les appareils et la clé de récupération rend les données synchronisées irrécupérables — c'est538 la propriété recherchée.539- La navigation privée n'atteint jamais le serveur : c'est l'app qui l'exclut (voir540 [sp-browser](https://git.spboucher.ai/sp-browser)).541- Pas de suggestions, de recherches associées ni de correction orthographique : le fournisseur n'en offre pas.542- Le chemin YouTube Data v3 n'a jamais été exercé contre l'API réelle.543- Le cache de recherche et le journal opérationnel sont en mémoire : ils repartent de zéro à chaque redémarrage.544545## 📚 Documentation546547- [docs/OPERATIONS.md](docs/OPERATIONS.md) — déploiement, configuration, migrations, sauvegarde, restauration, reprise, surveillance548- [docs/SECURITY.md](docs/SECURITY.md) — secrets, journaux, clés d'accès, chiffrement de bout en bout, limites549550## 👤 Auteur551552<div align="center">553<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>554555**Simon-Pierre Boucher** — conception, développement, exploitation<br>556[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai557558</div>559560## 📄 Licence561562Le dépôt ne contient pas de fichier de licence. Tous droits réservés © 2026 Simon-Pierre Boucher.563