sp-browser-backend
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.
Author: Simon-Pierre Boucher
Sommaire
- Vue d'ensemble
- Fonctionnalités
- Architecture
- Pile technique
- Arborescence du dépôt
- Démarrage
- Configuration
- API
- Recherche — ce que le fournisseur permet réellement
- Identité
- Synchronisation
- Modèle de données
- Sécurité et confidentialité
- Tests
- Déploiement et exploitation
- Dépannage et reprise
- Limites connues
- Documentation
- Auteur
- Licence
🎯 Vue d'ensemble
Backend de SP Browser (macOS + iOS) : trois services dans un seul processus Node. Production : https://browser.spboucher.ai.
| Service | Rôle |
|---|---|
| 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. |
| 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. |
| SP Sync | Flux de changements chiffré de bout en bout : le serveur ne stocke que du texte chiffré. |
Node ≥ 24 (TypeScript exécuté nativement, node:sqlite), deux dépendances : fastify, @simplewebauthn/server.
Aucune étape de build.
Famille SP Browser
| Dépôt | Plateforme | Rôle |
|---|---|---|
| sp-browser-backend (ce dépôt) | API web | SP Search, SP Identity, SP Sync |
| sp-browser | macOS + iOS | Navigateur natif WebKit, client de ce backend |
Les applications n'ont jamais la clé du fournisseur de recherche : elles parlent seulement à ce backend.
✨ Fonctionnalités
| Domaine | Ce que fait le code |
|---|---|
| Recherche web | lots de 20 résultats Tavily, pages de 10, résumé facultatif étiqueté generatedBy: "tavily", extraits nettoyés du balisage Markdown |
| Recherche d'images | images des pages trouvées (attribuées à leur page) + Wikimedia Commons (dimensions, auteur, licence) ; pages de 40 |
| 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 |
| Filtres | langue, région, période (day, week, month, year), recherche sécurisée |
| 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 |
| Budget | plafond quotidien de crédits (DAILY_CREDIT_BUDGET) : au-delà, seules les réponses en cache sont servies |
| 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 |
| Identité | clés d'accès découvrables, clés supplémentaires, réauthentification avant action destructrice, récupération, sessions par appareil, invitations |
| 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 |
| Administration | /admin : santé, crédits, usage 30 jours et coût estimé, comptes, appareils, enregistrements chiffrés, erreurs, journal |
| Apple | /.well-known/apple-app-site-association (webcredentials) pour les clés d'accès des applications |
🏗 Architecture
flowchart TB
APP["SP Browser<br/>macOS · iOS"]
ADM["Administrateur<br/>/admin · jeton"]
subgraph GW["Passerelle MacLustr Tunnel"]
C["Caddy · TLS"]
end
subgraph NODE["Nœud m4mn"]
subgraph P["sp-browser-backend · node src/server.ts · port 8710"]
S["SP Search<br/>normalize → cache → budget → lots → pages"]
I["SP Identity<br/>WebAuthn · sessions · invitations"]
Y["SP Sync<br/>push · pull · clés"]
end
DB[("SQLite · WAL<br/>sp-browser.sqlite")]
BK["sp-browser-backup<br/>PM2 cron quotidien"]
end
T["Tavily"]
W["Wikimedia Commons"]
O["oEmbed · YouTube Data v3"]
APP -->|HTTPS| C
ADM -->|HTTPS| C
C -->|WireGuard| P
S --> T
S --> W
S --> O
S --> DB
I --> DB
Y --> DB
BK -->|"VACUUM INTO + gzip"| DB
Ajout d'un nouvel appareil à la synchronisation chiffrée
sequenceDiagram
autonumber
participant N as Nouvel appareil
participant S as Serveur
participant A as Appareil déjà autorisé
N->>S: connexion par clé d'accès, publie sa clé publique d'accord de clé
A->>S: GET /api/sync/keys/pending
S-->>A: appareils en attente + clé publique
A->>A: affiche un code de vérification dérivé de la clé publique
Note over N,A: l'utilisateur compare le code sur les deux appareils
A->>S: POST /api/sync/keys/approve (clé de compte scellée, HPKE)
S->>S: refuse si la clé publique a changé depuis l'affichage
N->>S: GET /api/sync/keys
S-->>N: enveloppe (illisible pour le serveur)
N->>N: ouvre l'enveloppe, obtient la clé de compte
N->>S: GET /api/sync/pull?since=0
S-->>N: enregistrements chiffrés
🧱 Pile technique
| Couche | Technologie | Version | Rôle |
|---|---|---|---|
| Runtime | Node.js | ≥ 24 (engines) |
exécute le TypeScript directement, sans build |
| HTTP | Fastify | ^5.2.0 (verrouillé 5.12.8) | serveur, trustProxy, corps limité à 1 Mo, journal des requêtes désactivé |
| WebAuthn | @simplewebauthn/server |
^13.1.1 (verrouillé 13.3.3) | clés d'accès |
| Base | node:sqlite (SQLite, WAL) |
intégré | comptes, sessions, texte chiffré, usage |
| Recherche | Tavily (POST /search, /usage) |
API externe | web, images des pages, base des vidéos |
| Images | Wikimedia Commons (API MediaWiki publique) | API externe | médias sous licence libre |
| Vidéos | oEmbed YouTube / Vimeo / Dailymotion ; YouTube Data v3 (facultatif) | API externes | confirmation des pages de lecture |
| Tests | node:test |
intégré | faux fournisseur HTTP, authentificateur WebAuthn logiciel |
| Orchestration | PM2 via mld (MacLustr) |
— | HTTPS par Caddy sur la passerelle du MacLustr Tunnel |
🗂 Arborescence du dépôt
sp-browser-backend/
├── package.json scripts start, test, test:live, invite, backup ; 2 dépendances
├── src/
│ ├── server.ts assemblage Fastify, santé, AASA, /api/search, administration, ménage horaire
│ ├── config.ts configuration par l'environnement (.env), valeurs par défaut
│ ├── db.ts SQLite (WAL), migrations en ajout seul, PRAGMA user_version
│ ├── auth.ts SP Identity : 17 routes (inscription, connexion, clés, récupération, compte, appareils)
│ ├── sync.ts SP Sync : 10 routes (clés, push, pull, effacement)
│ ├── util.ts HttpError, OpsLog, RateLimiter, fetchJSON, hachages
│ └── search/
│ ├── service.ts orchestration : validation → cache → budget quotidien → lots → pages
│ ├── normalize.ts validation de la requête, clé de cache
│ ├── tavily.ts lots web Tavily
│ ├── images.ts images des pages + Wikimedia Commons
│ ├── video.ts vidéos : restriction de domaines, confirmation oEmbed, YouTube Data v3
│ └── types.ts types de requête, de réponse et d'erreur
├── public/admin.html tableau de bord d'administration (page unique)
├── scripts/
│ ├── invite.ts invitations : create [note] · list
│ └── backup.sh copie cohérente à chaud, contrôle d'intégrité, gzip, rétention
├── test/ helpers, identity-sync, search, live
└── docs/ OPERATIONS.md · SECURITY.md · brand/🚀 Démarrage
cp .env.example .env && chmod 600 .env # renseigner TAVILY_API_KEY, SERVER_SECRET, ADMIN_TOKEN
npm install
npm test # 15 tests (faux fournisseur HTTP, authentificateur WebAuthn logiciel)
npm run test:live # essai réel Tavily + Commons + oEmbed (~4 crédits)
npm start
.env.examplen'est pas versionné dans ce dépôt (le motif.env.*de.gitignorele masque) : la liste des variables est dans Configuration et danssrc/config.ts.
Script npm |
Commande | Rôle |
|---|---|---|
start |
node src/server.ts |
serveur |
test |
node --test --test-force-exit --test-timeout=30000 --test-concurrency=1 test/*.test.ts |
suite hors ligne |
test:live |
LIVE=1 node --test --test-concurrency=1 test/live.test.ts |
essai réel contre les fournisseurs |
invite |
node scripts/invite.ts |
invitations |
backup |
bash scripts/backup.sh |
sauvegarde |
Sans SERVER_SECRET, le processus démarre quand même (tests, premier démarrage) mais les clés de limitation de
débit changent à chaque redémarrage. Sans TAVILY_API_KEY, les recherches répondent 503.
⚙️ Configuration
Lue dans l'environnement ou dans .env (jamais dans git). Noms seulement ; défauts lus dans src/config.ts.
| Variable | Rôle | Défaut |
|---|---|---|
PORT · HOST |
écoute | 8710 · 127.0.0.1 |
DATA_DIR |
dossier de la base sp-browser.sqlite (créé en mode 0700) |
./data |
PUBLIC_ORIGIN |
origine publique ; origine attendue par WebAuthn | http://localhost:8710 |
RP_ID · RP_NAME |
identifiant et nom de la partie de confiance | hôte de PUBLIC_ORIGIN · SP Browser |
APPLE_APP_IDS |
identifiants <équipe>.<bundle> servis dans le fichier d'association Apple |
vide |
TAVILY_API_KEY · TAVILY_BASE |
fournisseur de recherche | — · API Tavily |
YOUTUBE_API_KEY |
facultatif : durée et date des vidéos YouTube | vide |
OEMBED_YOUTUBE · OEMBED_VIMEO · OEMBED_DAILYMOTION |
points d'accès oEmbed (remplaçables pour les tests) | plateformes officielles |
DAILY_CREDIT_BUDGET |
plafond de crédits Tavily par jour UTC | 400 |
ANON_SEARCH |
recherche sans session | true |
ANON_SEARCH_PER_HOUR · USER_SEARCH_PER_HOUR |
limites horaires | 40 · 600 |
OPEN_REGISTRATION |
création de compte sans invitation | false |
SESSION_DAYS |
durée glissante d'une session | 60 |
AUTH_RATE_MULTIPLIER |
multiplie les limites par IP d'authentification (instances de test) | 1 |
SERVER_SECRET |
secret du serveur (HMAC des IP, etc.) | aléatoire à chaque démarrage |
ADMIN_TOKEN |
jeton du tableau de bord | vide (administration fermée) |
Points d'attention :
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.APPLE_APP_IDS: Apple met le fichier d'association en cache, jusqu'à 24 h.
🔌 API
33 routes. Toutes les réponses portent cache-control: no-store, x-content-type-options: nosniff et
referrer-policy: no-referrer. Erreurs : { "error": { "code", "message" } }.
Service et recherche (4)
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /api/health |
{ok, service, version, schema, providers} |
| GET | /.well-known/apple-app-site-association |
webcredentials pour les applications |
| POST | /api/search |
recherche web, images, vidéos |
| GET | /api/search/capabilities |
ce que la recherche sait et ne sait pas faire |
SP Identity — 17 routes
| Méthode | Chemin | Rôle |
|---|---|---|
| POST | /api/auth/register/options · /api/auth/register/verify |
création de compte (invitation, sauf OPEN_REGISTRATION=true) |
| POST | /api/auth/login/options · /api/auth/login/verify |
connexion ; clé découvrable : la clé d'accès identifie le compte |
| POST | /api/auth/reauth/options · /api/auth/reauth/verify |
confirmation avant action destructrice |
| POST | /api/auth/passkeys/options · /api/auth/passkeys/verify |
ajout d'une clé d'accès |
| DELETE | /api/auth/passkeys/:id |
retrait d'une clé d'accès |
| POST | /api/auth/recover/options · /api/auth/recover/verify |
récupération |
| GET · PATCH · DELETE | /api/account |
compte |
| DELETE | /api/devices/:id |
retrait d'un appareil |
| POST | /api/auth/logout · /api/auth/logout-all |
déconnexion, « partout » |
SP Sync — 10 routes
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /api/sync/keys |
état des clés de l'appareil |
| POST | /api/sync/keys/bootstrap |
premier appareil : mise en place |
| GET · PUT | /api/sync/keys/recovery |
blob de récupération |
| POST | /api/sync/keys/claim |
réclamation par la clé de récupération |
| GET | /api/sync/keys/pending |
appareils en attente de clé |
| POST | /api/sync/keys/approve |
approbation d'un appareil |
| POST | /api/sync/push |
envoi de changements (500 au plus par requête) |
| GET | /api/sync/pull?since= |
lecture du flux (limit de 1 à 1000, 500 par défaut) |
| DELETE | /api/sync/data |
effacement des données synchronisées |
Administration (2) — Authorization: Bearer $ADMIN_TOKEN
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /api/admin/overview |
santé, crédits, usage, identité, synchronisation, erreurs, journal |
| GET | /admin |
tableau de bord (page unique, CSP default-src 'none') |
🔎 Recherche — ce que le fournisseur permet réellement
Vérifié dans la documentation Tavily le 2026-11-18 (POST https://api.tavily.com/search, Authorization: Bearer).
| Besoin | Réalité Tavily | Ce que fait le backend |
|---|---|---|
| Recherche web | oui (max_results ≤ 20) |
lots de 20, pages de 10 |
| 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 ») |
| Résumé | include_answer |
renvoyé dans answer, étiqueté generatedBy: "tavily" |
| 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) |
| 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) |
| Suggestions, recherches associées, correction orthographique | inexistants | non fournis (GET /api/search/capabilities le dit) ; l'app suggère depuis l'historique local |
Durée et date d'une vidéo YouTube ne sont disponibles qu'avec YOUTUBE_API_KEY (chemin testé contre un faux serveur,
jamais contre l'API réelle : aucune clé fournie). Vimeo les donne par oEmbed.
POST /api/search
{ "query": "Apple Silicon AI benchmarks", "type": "web", "language": "en", "region": "ca", "page": 1,
"timeRange": "month", "safeSearch": true, "summary": true }Réponse : { query, type, page, pageSize, hasMore, provider, cached, tookMs, answer, results[], notices[] }.
Erreurs : rate_limited (429), budget_exhausted (503), provider_* (429/502/503/504). Le texte d'erreur du
fournisseur et la clé ne sortent jamais.
Protection : session facultative (ANON_SEARCH), limite par heure (par compte, ou par IP hachée pour les anonymes),
plafond quotidien de crédits (DAILY_CREDIT_BUDGET) : au-delà, seules les réponses en cache sont servies.
Détails lus dans le code : une confirmation oEmbed restée sans réponse est retentée une fois et un lot incomplet n'est jamais mis en cache ; les vignettes YouTube sont en 16:9 ; une panne de Commons ne fait jamais échouer la recherche, une panne de Tavily oui ; rien n'est extrait d'un autre moteur de recherche.
🪪 Identité
/api/auth/register/{options,verify} · /api/auth/login/{options,verify} (clé découvrable : la clé d'accès
identifie le compte) · /api/auth/passkeys/{options,verify}, DELETE /api/auth/passkeys/:id ·
/api/auth/reauth/{options,verify} (confirmation avant action destructrice) · /api/auth/recover/{options,verify} ·
GET/PATCH/DELETE /api/account · DELETE /api/devices/:id · /api/auth/logout, /api/auth/logout-all.
Création de compte sur invitation, sauf OPEN_REGISTRATION=true :
node scripts/invite.ts create "note" # affiche un code à usage unique (seul son hachage est stocké)
node scripts/invite.ts listLimites par IP (multipliées par AUTH_RATE_MULTIPLIER) : création de compte 10 par heure, connexion 30 par
10 minutes, récupération 5 par heure.
🔄 Synchronisation
/api/sync/keys (+ bootstrap, pending, approve, claim, recovery) · POST /api/sync/push ·
GET /api/sync/pull?since= · DELETE /api/sync/data. Modèle et limites : docs/SECURITY.md.
| Élément | Valeur (lue dans src/sync.ts) |
|---|---|
| Collections | history, bookmarks, favorites, tabs, closed, reading, searches, prefs |
| Changements par envoi | 500 au plus |
| Taille d'un enregistrement chiffré | 350 000 caractères au plus |
| Enregistrements par compte | 250 000 au plus (quota_exceeded, 413) |
| Conflit | l'envoi renvoie l'enregistrement courant du serveur dans conflicts |
| Pierres tombales | purgées après un an |
🗃 Modèle de données
SQLite (sp-browser.sqlite, WAL, clés étrangères actives). 9 tables, 3 migrations dans src/db.ts : liste
MIGRATIONS, ajout en fin de liste uniquement ; version suivie par PRAGMA user_version, chaque migration dans une
transaction, appliquée au démarrage. GET /api/health renvoie schema.
| Table | Contenu |
|---|---|
users |
comptes |
credentials |
clés d'accès (clé publique, compteur) |
devices |
appareils, clé publique d'accord de clé, enveloppe de la clé de compte |
sessions |
hachage du jeton, appareil, expiration |
challenges |
défis WebAuthn à usage unique |
invites |
hachage du code, note, usage |
sync_records |
texte chiffré par (compte, collection, identifiant), numéro de séquence, pierre tombale |
account_keys |
matériel de clé du compte (blob de récupération, hachages, key_version) |
usage_daily |
compteurs par jour, fournisseur et type : requêtes, crédits, succès de cache, erreurs, latence |
erDiagram
users ||--o{ credentials : possede
users ||--o{ devices : enregistre
users ||--o{ sessions : ouvre
devices ||--o{ sessions : porte
users ||--o{ sync_records : synchronise
users ||--o| account_keys : detient
🔐 Sécurité et confidentialité
Détail : docs/SECURITY.md.
Secrets. TAVILY_API_KEY, YOUTUBE_API_KEY, SERVER_SECRET, ADMIN_TOKEN : uniquement dans .env (600) sur
le nœud. Jamais dans git, dans les apps, dans les réponses ni dans les journaux. Les erreurs du fournisseur sont
converties en codes stables ; un test vérifie que ni la clé ni le texte amont ne sortent. Jetons de session :
32 octets aléatoires, seul leur SHA-256 est stocké. Un jeton par appareil ; expiration glissante (SESSION_DAYS),
révocation immédiate (déconnexion, retrait d'appareil, « partout »).
Journaux. La journalisation des requêtes HTTP est désactivée. Le journal opérationnel (en mémoire,
400 entrées) ne contient que des messages écrits par le code : jamais de requête de recherche, d'URL ni de jeton. Le
cache de recherche vit en mémoire, indexé par un hachage ; usage_daily ne compte que des nombres par jour. Les IP ne
servent qu'à limiter le débit, sous forme de HMAC.
Clés d'accès. WebAuthn avec vérification de l'utilisateur obligatoire, clés découvrables, attestation none. Le
serveur vérifie défi (usage unique, 5 min), origine, identifiant de RP, signature et compteur. La biométrie reste dans
l'authentificateur du système : le serveur ne voit qu'une signature. Toutes les clés d'accès ne se synchronisent pas
entre appareils (dépend du trousseau / gestionnaire) : d'où l'ajout de clés supplémentaires et la clé de récupération.
Chiffrement de bout en bout de la synchronisation
- Clé de compte (256 bits) créée sur le premier appareil, conservée dans son trousseau. Le serveur ne la reçoit jamais.
- Enregistrements : AEAD (ChaCha20-Poly1305) avec une clé par collection dérivée par HKDF ; données associées = collection, identifiant, version de clé. Les identifiants des enregistrements dérivés d'une URL ou d'une requête sont des HMAC sous une clé dérivée : le serveur ne peut pas les inverser.
- Nouvel appareil : il publie une clé publique d'accord de clé ; un appareil déjà autorisé affiche un code de vérification dérivé de cette clé publique, l'utilisateur le compare, puis l'appareil scelle la clé de compte pour cette clé publique (HPKE). Le serveur transporte l'enveloppe sans pouvoir l'ouvrir. Le serveur refuse l'approbation si la clé publique a changé entre l'affichage et l'envoi ; le code de vérification protège contre un serveur qui substituerait la clé.
- Récupération : la clé de compte est aussi scellée sous la clé de récupération de l'utilisateur (affichée une fois, à conserver hors ligne). Le serveur garde ce blob et un hachage scrypt d'un authentifiant dérivé de la clé de récupération — pas la clé.
- Preuve de détention : approuver un appareil, changer la clé de récupération ou effacer les données exige une valeur dérivée de la clé de compte ; le serveur n'en garde que le hachage.
Ce que le serveur voit quand même. Le nom de la collection (history, bookmarks, tabs…), des identifiants
opaques, la taille des enregistrements, les dates d'écriture, l'appareil qui a écrit, le nom et le modèle des
appareils. Il peut donc compter les pages visitées, pas les lire.
✅ Tests
npm test # 15 tests hors ligne
npm run test:live # 1 essai réel (~4 crédits Tavily), ignoré sans LIVE=1| Fichier | Tests | Portée |
|---|---|---|
test/search.test.ts |
9 | recherche web / images / vidéos contre un faux fournisseur HTTP, cache, budget, erreurs |
test/identity-sync.test.ts |
6 | comptes, clés d'accès (authentificateur WebAuthn logiciel), sessions, synchronisation |
test/live.test.ts |
1 | Tavily + Wikimedia Commons + oEmbed réels ; jamais simulé, ignoré sinon |
Les tests forcent la sortie du processus (--test-force-exit) et s'exécutent sans concurrence.
🚢 Déploiement et exploitation
Détail : docs/OPERATIONS.md.
| Site | https://browser.spboucher.ai |
App mld |
sp-browser-backend (manifeste sur la passerelle du cluster) |
| Processus PM2 | sp-browser-backend (node src/server.ts, port 8710), sp-browser-backup (cron quotidien) |
| Exposition | route Caddy posée par mld deploy sur la passerelle du MacLustr Tunnel |
| Secrets | ~/apps/sp-browser-backend/.env (600), exclu de git et du rsync |
| Données | ~/apps-data/sp-browser-backend/sp-browser.sqlite (+ -wal, -shm) |
| Sauvegardes | ~/backups/sp-browser-backend/ |
Le dossier déployé est le dépôt (origin = spbgit sp-browser-backend.git) : modifier sur le nœud,
pm2 restart sp-browser-backend, puis git commit && git push sur le nœud.
Sauvegarde. scripts/backup.sh : copie cohérente à chaud (VACUUM INTO), contrôle d'intégrité, gzip, rétention
30 jours dans ~/backups/sp-browser-backend/. La base contient des clés publiques, des hachages de jetons et du texte
chiffré de bout en bout : une sauvegarde seule ne révèle pas la navigation.
Restauration.
pm2 stop sp-browser-backend
cd ~/apps-data/sp-browser-backend && mv sp-browser.sqlite sp-browser.sqlite.bad; rm -f sp-browser.sqlite-wal sp-browser.sqlite-shm
gunzip -c ~/backups/sp-browser-backend/sp-browser-<date>.sqlite.gz > sp-browser.sqlite && chmod 600 sp-browser.sqlite
sqlite3 sp-browser.sqlite 'PRAGMA integrity_check'
pm2 start sp-browser-backend && curl -s localhost:8710/api/healthAprès restauration, les appareils dont le numéro de séquence dépasse celui de la sauvegarde renvoient leurs changements manquants au prochain cycle (l'app repousse tout enregistrement local que le serveur ne connaît plus).
Surveillance. /admin (ou GET /api/admin/overview, Authorization: Bearer $ADMIN_TOKEN) : santé, crédits du
jour / plafond, usage 30 jours et coût estimé (0,008 $ US par crédit, tarif à l'usage), compte Tavily (/usage,
rafraîchi au plus toutes les 15 minutes), comptes / appareils / sessions, enregistrements chiffrés par collection,
appareils en attente de clé, erreurs 24 h, journal opérationnel.
🩺 Dépannage et reprise
| Situation | Remède |
|---|---|
| Nœud perdu | mld deploy sp-browser-backend --node X, recopier .env et la dernière sauvegarde |
| Clé Tavily compromise | la régénérer chez Tavily, remplacer TAVILY_API_KEY, pm2 restart. Les apps n'ont jamais la clé |
| 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 |
| Nouvelle invitation | node scripts/invite.ts create "pour qui" |
Recherches en 503 budget_exhausted |
plafond DAILY_CREDIT_BUDGET atteint pour le jour UTC : seules les réponses en cache sont servies |
| Recherches en 503 au démarrage | TAVILY_API_KEY absente |
| 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 |
| Toutes les clés d'accès invalides | RP_ID ou PUBLIC_ORIGIN a changé |
/admin répond 401 |
ADMIN_TOKEN absent ou erroné |
⚠️ Limites connues
- Retirer un appareil coupe ses sessions et supprime son enveloppe, mais ne fait pas tourner la clé de compte : un
appareil retiré garde ce qu'il avait déjà déchiffré. La rotation (
key_version) est prévue par le schéma, pas implémentée. - Perdre à la fois tous les appareils et la clé de récupération rend les données synchronisées irrécupérables — c'est la propriété recherchée.
- La navigation privée n'atteint jamais le serveur : c'est l'app qui l'exclut (voir sp-browser).
- Pas de suggestions, de recherches associées ni de correction orthographique : le fournisseur n'en offre pas.
- Le chemin YouTube Data v3 n'a jamais été exercé contre l'API réelle.
- Le cache de recherche et le journal opérationnel sont en mémoire : ils repartent de zéro à chaque redémarrage.
📚 Documentation
- docs/OPERATIONS.md — déploiement, configuration, migrations, sauvegarde, restauration, reprise, surveillance
- docs/SECURITY.md — secrets, journaux, clés d'accès, chiffrement de bout en bout, limites
👤 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.