discovery-media-player 0.1.163 → 0.1.165

package/bin/serve.js

@@ -179,7 +179,21 @@ async function servir(req, res) {
   // Le player lit `req.query` (convention des plateformes serverless) et `req.body` déjà analysé.
   req.query = q;
   if (req.method === "POST") {
-    req.body = await lireCorpsJson(req);
+    // ⚠️ TROIS ISSUES DISTINCTES, TROIS RÉPONSES — un corps invalide, trop gros ou coupé rendait
+    // `{}` dans les trois cas, et le gestionnaire répondait « bad-event » à un client qui n'avait
+    // qu'envoyé un fichier trop lourd. 413 pour le dépassement (avec `Connection: close` : on ne
+    // draine pas un corps sans fin), 400 pour un JSON illisible, rien pour une connexion partie.
+    // Relevé par un audit externe le 13/09.
+    const lu = await lireCorpsJson(req);
+    if (lu.etat === "too-large") {
+      res.setHeader("Connection", "close");
+      res.once("finish", () => { try { req.destroy(); } catch { /* déjà parti */ } });
+      player.refuserEnTexte(res, 413, "Corps trop volumineux (1 Mo au plus)");
+      return;
+    }
+    if (lu.etat === "invalid-json") { player.refuserEnTexte(res, 400, "Corps JSON illisible"); return; }
+    if (lu.etat === "aborted") { try { res.end(); } catch { /* flux clos */ } return; }
+    req.body = lu.corps;
   }
 
   try {
@@ -202,22 +216,43 @@ const serveur = http.createServer((req, res) => {
     player.refuserEnTexte(res, 500, "Erreur");
   });
 });
+// ⚠️ LES DÉLAIS DE NODE (300 s par requête, 60 s pour les en-têtes) SONT CEUX D'UN SERVEUR DERRIÈRE UN
+// PROXY, PAS D'UN SERVEUR EXPOSÉ. Mesurés par un audit externe le 13/09 : `requestTimeout` 300 000,
+// `headersTimeout` 60 000. Une connexion qui envoie ses en-têtes au goutte-à-goutte tenait donc une
+// minute, un corps lent cinq — par socket. ⚠️ Ces bornes portent sur la REQUÊTE : `requestTimeout`
+// ne couvre PAS l'émission d'une réponse (cette phrase affirmait que « trente secondes couvrent un
+// relais de 60 Mo » — faux, relevé par le même audit) ; un relais lent est borné par ses propres
+// délais de progression et de budget (`relayStallMs`, `relayMaxMs` dans le gestionnaire). Les
+// en-têtes n'ont aucune raison de prendre plus de quinze secondes ; un keep-alive court rend les
+// sockets. Un proxy amont peut serrer davantage, jamais l'inverse.
+serveur.requestTimeout = 30_000;
+serveur.headersTimeout = 15_000;
+serveur.keepAliveTimeout = 5_000;
 
 /** Corps JSON, borné. Un corps sans fin est une façon peu coûteuse de faire tomber un serveur. */
+/**
+ * Rend `{ etat, corps }` : `ok` (corps = l'objet lu, `{}` pour un corps vide), `too-large` (la lecture
+ * s'arrête au premier octet au-delà de `maxOctets`, sans drainer la suite), `invalid-json`, ou
+ * `aborted` (la connexion est partie avant la fin). L'appelant choisit le code HTTP : ici, on ne sait
+ * que lire.
+ */
 function lireCorpsJson(req, maxOctets = 1_000_000) {
   return new Promise((resolve) => {
-    let taille = 0;
+    let taille = 0, regle = false;
     const morceaux = [];
+    const rendre = (v) => { if (!regle) { regle = true; resolve(v); } };
     req.on("data", (c) => {
+      if (regle) return;
       taille += c.length;
-      if (taille > maxOctets) { req.destroy(); resolve({}); return; }
+      if (taille > maxOctets) { try { req.pause(); } catch { /* déjà clos */ } rendre({ etat: "too-large", corps: null }); return; }
       morceaux.push(c);
     });
     req.on("end", () => {
-      try { resolve(JSON.parse(Buffer.concat(morceaux).toString("utf8") || "{}")); }
-      catch { resolve({}); }
+      try { rendre({ etat: "ok", corps: JSON.parse(Buffer.concat(morceaux).toString("utf8") || "{}") }); }
+      catch { rendre({ etat: "invalid-json", corps: null }); }
     });
-    req.on("error", () => resolve({}));
+    req.on("error", () => rendre({ etat: "aborted", corps: null }));
+    req.on("aborted", () => rendre({ etat: "aborted", corps: null }));
   });
 }
 
@@ -286,4 +321,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { serveur, servir, versParametres, pageAccueil, __arreterProprement: arreterProprement, DELAI_ARRET_MS };
+module.exports = { serveur, servir, versParametres, pageAccueil, lireCorpsJson, __arreterProprement: arreterProprement, DELAI_ARRET_MS };

package/context/standalone.js

@@ -56,12 +56,43 @@ function sansBarreFinale(valeur) {
  * consultations protégées.
  *
  * ⚠️ ET UNE COURSE DE PROMESSES NE SUFFIRAIT PAS : elle rendrait la main sans ANNULER le `fetch`,
- * donc sans rien libérer. C'est `AbortSignal` ou rien. Un signal fourni par l'appelant a priorité —
- * un hôte qui borne lui-même une opération longue n'est pas écrasé.
+ * donc sans rien libérer. C'est `AbortSignal` ou rien. Un signal fourni par l'appelant s'AJOUTE au
+ * plancher — voir `composerSignaux` : le premier des deux qui parle gagne.
  */
+/**
+ * ⚠️ ON COMPOSE LES SIGNAUX, ON NE LES REMPLACE PAS — ET LA PREMIÈRE ÉCRITURE LES REMPLAÇAIT.
+ *
+ * Elle disait `options.signal || AbortSignal.timeout(delai)` : un signal fourni par l'appelant
+ * SUPPRIMAIT le plancher, au lieu de s'y ajouter. Un hôte qui borne lui-même une opération longue
+ * croyait donc ajouter une garantie, et en retirait une. Mesuré : avec un signal qui n'expire jamais
+ * et `timeoutMs: 20`, la promesse est encore en attente après 150 ms.
+ *
+ * ⚠️ ET LE COMMENTAIRE BÉNISSAIT LE DÉFAUT. Il écrivait « un signal fourni par l'appelant a
+ * priorité — un hôte qui borne lui-même une opération longue n'est pas écrasé ». L'intention est
+ * juste ; « a priorité » était la mauvaise traduction. Le premier des deux qui parle gagne : c'est
+ * ce que « borner » veut dire. Rapporté par un audit externe le 12/09 comme défaut LATENT — aucun
+ * appel du produit ne transmet aujourd'hui de signal, donc personne ne l'aurait vu arriver.
+ */
+function composerSignaux(fourni, delaiMs) {
+  const horloge = (typeof AbortSignal !== "undefined" && AbortSignal.timeout)
+    ? AbortSignal.timeout(delaiMs) : undefined;
+  if (!fourni) return horloge;
+  if (!horloge) return fourni;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([fourni, horloge]);
+  // ⚠️ REPLI SANS `AbortSignal.any` : un contrôleur qui suit les deux. Le `aborted` se teste AVANT
+  // de s'abonner — un signal déjà déclenché n'émettra plus jamais son événement, et l'attendre
+  // serait une attente infinie posée par la précaution elle-même.
+  const relais = new globalThis.AbortController();
+  const abandonner = () => { try { relais.abort(); } catch { /* déjà abandonné */ } };
+  for (const s of [fourni, horloge]) {
+    if (s.aborted) { abandonner(); break; }
+    try { s.addEventListener("abort", abandonner, { once: true }); } catch { /* signal exotique */ }
+  }
+  return relais.signal;
+}
+
 function fetchBorne(cible, options = {}, delaiMs) {
-  const signal = options.signal
-    || (typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(delaiMs) : undefined);
+  const signal = composerSignaux(options.signal, delaiMs);
   return fetch(cible, { ...options, ...(signal ? { signal } : {}) });
 }
 
@@ -243,13 +274,33 @@ async function appelHote(url, secret, corps, errors) {
  * base. Y adosser un compteur partagé ferait payer à la garde le prix qu'on venait d'épargner à ce
  * qu'elle garde. Sur ce chemin, la protection réelle est le cache, pas le compteur.
  *
- * ⚠️ LE COMPTE PARTAGÉ N'EST PAS ATOMIQUE. PostgREST ne sait pas exprimer « incrémente » : c'est une
- * lecture puis une écriture. Deux instances peuvent donc lire la même valeur et n'en écrire qu'une —
- * le compteur SOUS-estime sous forte concurrence. Pour une limite de débit, sous-estimer signifie
- * laisser passer un peu plus, jamais refuser à tort. Le dire vaut mieux que laisser croire à une
- * exactitude qu'on n'a pas.
+ * ⚠️ CE PARAGRAPHE DISAIT QUE LE COMPTE PARTAGÉ N'EST PAS ATOMIQUE. C'EST FAUX DEPUIS 0004, et il
+ * a survécu à ce qu'il décrivait — écrit quand PostgREST ne savait pas exprimer « incrémente »,
+ * donc quand compter était une lecture puis une écriture. La migration `0004-limites-atomiques.sql`
+ * a remplacé les deux par UNE instruction serveur : `player_rate_limit_bump`. Corrigé plutôt que
+ * supprimé, parce qu'un hôte qui l'a lu a pu bâtir une compensation dont il n'a pas besoin.
+ *
+ * ⚠️ ET LA DÉGRADATION RÉELLE EST L'INVERSE DE CE QU'IL LAISSAIT CROIRE. Sans 0004, l'étage partagé
+ * ne compte pas moins bien : IL NE COMPTE PAS DU TOUT. Le `return true` plus bas laisse passer, et
+ * seul le compteur LOCAL, par processus, subsiste — une limite de 120/h en autorise 120 PAR
+ * EXÉCUTION. « Non atomique » nommait un mode qui n'existe pas : un comptage partagé dégradé.
+ *
+ * La matrice complète est dans `docs/HOST-CONTRACT.md` ; elle est la version qui fait foi.
+ *
+ * ⚠️ CETTE PHRASE-CI EST LE JUMEAU FRANÇAIS DE CELLE CORRIGÉE DANS LE CONTRAT LE 11/09 — À 95
+ * LIGNES DE L'AVERTISSEMENT CORRIGÉ LE MÊME JOUR, DANS CE MÊME FICHIER. Corriger un exemplaire
+ * d'une affirmation et pas l'autre est le mode de panne que ce dépôt traque partout ailleurs : deux
+ * copies d'une règle divergent, et personne ne les confronte. Cherchez le MÉCANISME que vous venez
+ * de changer, pas les mots dont vous vous souvenez.
+ */
+/**
+ * @param horloge lecture du temps, injectable. ⚠️ ELLE EXISTE POUR QU'UN BANC N'AIT PAS À REMPLACER
+ * `Date.now` GLOBALEMENT. Une simulation d'une heure d'audience doit faire avancer le temps ; le
+ * seul moyen était de rustiner un global, ce qui laisse l'instrument dépendre d'un `finally` posé au
+ * bon endroit — et la première écriture de cette simulation l'avait posé au mauvais, mesurant en
+ * partie le temps RÉEL sans le dire. Une horloge passée en argument ne peut pas fuir.
  */
-function creerLimites(db, journal) {
+function creerLimites(db, journal, horloge = () => Date.now()) {
   const seaux = new Map();
   const PREFIXES_LOCAUX = ["pread:"];
   let partageDisponible = null;   // null = pas encore demandé
@@ -263,7 +314,7 @@ function creerLimites(db, journal) {
   // anti-inondation, et c'est le compromis explicitement recommandé.
   const PLAFOND_CLES = 5000;
   function localAutorise(cle, max, fenetreSecondes) {
-    const maintenant = Date.now();
+    const maintenant = horloge();
     const fenetreMs = fenetreSecondes * 1000;
     let e = seaux.get(cle);
     if (!e || maintenant - e.debut >= fenetreMs) e = { debut: maintenant, compte: 0 };
@@ -390,7 +441,23 @@ function createStandaloneContext(env = process.env) {
         // ⚠️ DERNIÈRE BARRIÈRE avant un DELETE à la clé service_role (P1 huitième audit). Bucket en
         // liste blanche, et refus de toute traversée — chaque segment sur l'alphabet des chemins
         // signés. `fetch` normalise `..` : un chemin non validé sortirait du bucket visé.
-        if (bucket !== "present-attachments") return false;
+        //
+        // ⚠️ LA LISTE NE PORTAIT QU'UN BUCKET SUR LES DEUX, ET LA PURGE DU CACHE DE VOIX N'A DONC
+        // JAMAIS RIEN RETIRÉ. `tts-cache` était refusé ICI, avant tout appel réseau : chaque retrait
+        // rendait `false`, la trace partait quand même, et l'objet restait dans un bucket PUBLIC
+        // sans plus aucun chemin vers lui — puisque cette capacité expose `put` et `remove`, jamais
+        // `list`. C'est très exactement le mal que la migration 0021 avait été écrite pour rendre
+        // réparable, à 100 %, en silence.
+        //
+        // ⚠️ ET CE SILENCE ÉTAIT DOCUMENTÉ. Le rapport comptait ces refus dans `fichiersErreur`, que
+        // `docs/RETENTION.md` explique par un fait vrai — un tiers des empreintes n'a pas de `.json`
+        // d'alignement (552 mp3 pour 356 json, mesuré par un hôte). Une explication JUSTE rendait
+        // donc un échec TOTAL indiscernable d'un fonctionnement normal. Trouvé le 12/09 en écrivant
+        // la documentation du correctif d'un AUTRE défaut du même chemin.
+        //
+        // La liste énumère maintenant les deux buckets que la rétention doit atteindre, et rien
+        // d'autre : la barrière garde son objet, elle cesse d'interdire le travail qu'on lui demande.
+        if (bucket !== "present-attachments" && bucket !== "tts-cache") return false;
         const segs = String(chemin).split("/");
         for (const seg of segs) {
           if (seg === "" || seg === "." || seg === ".." || !/^[A-Za-z0-9._-]+$/.test(seg)) return false;
@@ -399,7 +466,23 @@ function createStandaloneContext(env = process.env) {
           const r = await fetchBorne(`${base}/storage/v1/object/${encodeURIComponent(bucket)}/${segs.map(encodeURIComponent).join("/")}`, {
             method: "DELETE", headers: { apikey: cle, Authorization: `Bearer ${cle}` },
           }, DELAI_STOCKAGE_MS);
-          return r.ok;
+          if (r.ok) return true;
+          // ⚠️ UN OBJET DÉJÀ ABSENT EST UN SUCCÈS POUR CE QU'ON DEMANDE ICI, ET CE N'EST PLUS UNE
+          // NUANCE DE COMPTAGE. La purge RETIENT désormais la ligne quand ce
+          // retrait rend `false`, parce que la ligne est le seul chemin vers l'objet (`storage`
+          // expose `put` et `remove`, jamais `list`). Rendre `false` sur un objet qui n'est plus là
+          // retiendrait donc la ligne POUR TOUJOURS, en attendant un fichier qui n'existe pas —
+          // exactement la sur-rétention que le correctif de la sous-rétention ne doit pas créer.
+          // Ce qu'on demande est « l'objet n'est plus là », et il n'y est plus.
+          //
+          // ⚠️ ON LIT LE CORPS PARCE QUE LE CODE NE SUFFIT PAS. Le Storage de Supabase répond 400
+          // sur un objet manquant, pas seulement 404 : se fier au seul statut raterait le cas le
+          // plus fréquent. NON VÉRIFIÉ CONTRE UN SUPABASE VIVANT DEPUIS CE DÉPÔT — ce qui est
+          // éprouvé ici est la CORRESPONDANCE (statut et corps vers verdict), pas la forme exacte
+          // que le fournisseur émet. Un hôte qui observerait une autre formulation doit la dire.
+          if (r.status === 404) return true;
+          const corps = await r.text().catch(() => "");
+          return /not[_ ]?found|no such key|does not exist/i.test(corps);
         } catch { return false; }
       },
 
@@ -757,6 +840,13 @@ function createStandaloneContext(env = process.env) {
       supabasePublishableKey: env.SUPABASE_PUBLISHABLE_KEY || "",
       mapsKey: env.GOOGLE_MAPS_API_KEY || "",
       extraFrameAncestors: String(env.DOC_FRAME_ANCESTORS || "").split(/\s+/).filter(Boolean),
+      // Transferts de fichiers simultanés par processus (défaut 64) : le relais refuse en 503 au-delà,
+      // avant tout appel amont. Lu ICI, pas dans le cœur — la configuration entre par le contexte.
+      maxConcurrentRelays: Number(env.PLAYER_MAX_RELAYS || 0) || 64,
+      // Un relais sans progression pendant relayStallMs, ou plus long que relayMaxMs, est abandonné
+      // (source et réponse détruites) : sans ça, un client qui cesse de lire garde sa place pour toujours.
+      relayStallMs: Number(env.PLAYER_RELAY_STALL_MS || 0) || 30_000,
+      relayMaxMs: Number(env.PLAYER_RELAY_MAX_MS || 0) || 900_000,
 
       /**
        * Clé de `localStorage` sous laquelle VOTRE application range la session de ses membres.

package/context/storage.js

@@ -327,6 +327,22 @@ function isAllowedStorageUrl(candidate, origins, hostBase, root) {
 //   3. le nombre de sauts est borné, et le protocole ne peut pas changer de nature : une
 //      redirection vers `file:` transformerait un amont distant en lecture de disque local.
 const MAX_REDIRECTIONS = 5;
+/**
+ * ⚠️ LE BUDGET EST GLOBAL À L'OPÉRATION, PAS PAR SAUT — ET IL ÉTAIT PAR SAUT.
+ *
+ * Chaque tour de boucle créait son propre `AbortSignal.timeout(60 s)`. Avec six tours (saut 0 à 5),
+ * une chaîne de redirections lente pouvait donc immobiliser la requête, sa socket et sa place
+ * d'admission pendant SIX MINUTES — alors que le commentaire juste en dessous affirmait « le délai
+ * est large mais il est borné ». Il bornait un saut ; personne ne bornait l'opération. Relevé par
+ * un audit externe le 12/09.
+ *
+ * ⚠️ CE N'EST PAS UN TROU DE SÉCURITÉ, ET LE DIRE COMPTE : chaque saut repasse la garde complète
+ * d'origine et recalcule le secret. Le risque est de DISPONIBILITÉ — c'est la même leçon que les
+ * appels non bornés du contexte autonome, au même endroit du raisonnement.
+ *
+ * Un seul signal, créé avant la boucle et partagé par tous les sauts : le total ne peut pas dépasser
+ * ce chiffre, quel que soit le nombre de redirections.
+ */
 const DELAI_MAX_MS = 60_000;
 
 async function fetchAllowedFile(url, { range } = {}, { origins, hostBase, root, secret } = {}) {
@@ -335,6 +351,10 @@ async function fetchAllowedFile(url, { range } = {}, { origins, hostBase, root,
   if (local) return readLocal(local, range);
 
   let cible = String(url);
+  // ⚠️ CRÉÉ ICI, PAS DANS LA BOUCLE : `AbortSignal.timeout` compte à partir de sa création, donc un
+  // signal fabriqué avant le premier saut EST le budget de toute l'opération.
+  const budget = (typeof AbortSignal !== "undefined" && AbortSignal.timeout)
+    ? AbortSignal.timeout(DELAI_MAX_MS) : undefined;
   for (let saut = 0; saut <= MAX_REDIRECTIONS; saut++) {
     const headers = { "accept-encoding": "identity" };
     if (range) headers.range = range;
@@ -342,8 +362,9 @@ async function fetchAllowedFile(url, { range } = {}, { origins, hostBase, root,
     if (isHostFetchUrl(cible, hostBase) && secret) headers["x-player-fetch-secret"] = secret;
 
     // Un amont qui ne répond jamais immobiliserait la requête et ses ressources indéfiniment.
-    // Le délai est large — un gros document met du temps — mais il est borné.
-    const r = await fetch(cible, { headers, redirect: "manual", signal: AbortSignal.timeout(DELAI_MAX_MS) });
+    // Le délai est large — un gros document met du temps — mais il borne l'OPÉRATION ENTIÈRE, pas
+    // chaque saut : le même signal sert à tous, donc le temps déjà consommé ne se reconstitue pas.
+    const r = await fetch(cible, { headers, redirect: "manual", ...(budget ? { signal: budget } : {}) });
     if (r.status < 300 || r.status > 399) return r;
 
     const suivante = r.headers.get("location");

package/docs/HOST-CONTRACT.md

@@ -410,6 +410,56 @@ inheritance both refuse — without either of them knowing why.
 Requires `supabase/migrations/0001-destinataire-atteste.sql`. Until it is applied the player refuses
 the attested creation and names the file; it never falls back to the other column.
 
+## The visitor wall (`plugins.visitors`): what the player counts, and what your plugin must do
+
+A host can gate documents behind a soft wall — an e-mail code, or a Google credential — by providing
+`plugins.visitors` with `requestCode(email, { title })`, `verifyCode(email, code, name)` and
+`verifyGoogle(credential)`. The player exposes them as `visitor-request`, `visitor-verify` and
+`visitor-google`.
+
+⚠️ **Until this train, only the request was rate-limited; verification called your plugin directly.**
+An external audit reproduced 1 000 code attempts and 1 000 Google verifications from one address with
+zero limiter calls (13/09). A short code with no counter in the plugin was brute-forceable, and a
+Google verification per anonymous request was a network amplifier. The player no longer assumes your
+plugin counts — the same rule as the assistant's session↔document binding: a security property must
+not depend on code the player does not contain.
+
+| action | per address | per identity (fingerprint of the normalised e-mail, never the address) |
+|---|---|---|
+| `visitor-request` | 20 / hour | 5 / hour |
+| `visitor-verify` | 100 / hour | 10 / 15 minutes |
+| `visitor-google` | 100 / hour | — |
+
+Counters are taken **at admission**: success, failure and an exception in your plugin consume them
+alike. Beyond a limit the answer is `429 { error: "rate" }` and **your plugin is not called**.
+
+⚠️ **Provide `rateLimitKey(email): Promise<string>` on the plugin — the identity key should be
+yours.** Without it the player keys the per-identity counters on a truncated SHA-256 of the
+normalised e-mail: `player_rate_limits` never carries an address in clear, but a fingerprint is a
+**pseudonym, not a secret** — anyone reading that table, a backup or an admin tool can precompute the
+fingerprints of likely addresses (an audit showed it on 13/09). Your implementation should be a
+stable, opaque HMAC with a host-side secret and **domain separation**:
+`HMAC(secret, "visitor-email\0" + emailNormalised)`. The player calls it with the e-mail already
+trimmed and lower-cased, prefixes your key with `h:` (a fallback fingerprint gets `e:`, so the two
+never collide), and truncates it to 64 characters. If the capability is absent, throws, or returns
+anything but a non-empty string, the player **falls back to the fingerprint and reports it once per
+process** through `errors.capture` (`benin: true`): refusing to limit would be worse than limiting
+under a weak pseudonym, and silence would be worse than both. (An earlier version of this paragraph
+said the player holds no server secret at all — too absolute: the standalone context already carries
+`ipHashSecret` for another purpose. The key still belongs with you, not with that secret.)
+
+⚠️ **What your plugin must still guarantee — the player cannot do it for you:**
+
+- the code is **short-lived** (minutes, not hours) and **single-use**: a code that stays valid after a
+  successful verification can be replayed from a shoulder-surfed screen;
+- the code has enough entropy for 10 attempts per quarter-hour not to be a lottery — six digits give
+  one chance in 100 000 per attempt at that pace, which is acceptable; four digits are not;
+- `verifyGoogle` validates the credential's audience and issuer server-side, and does not accept an
+  expired token.
+
+The player's counters bound the *rate*; your plugin bounds the *code*. Both are needed, and neither
+replaces the other.
+
 ## ⚠️ What `limits.allow` promises changed
 
 It used to promise *best effort, per process*. The standalone context now counts in a **shared
@@ -712,6 +762,15 @@ Four requirements, in order of what they cost when missed:
    anywhere. Announce the length of what you send, request `Accept-Encoding: identity`, and refuse
    a compressed `206` — range bounds refer to compressed bytes.
 2. **Relay `Range`** (`206` + `Accept-Ranges: bytes`). Progressive loading depends on it.
+   ⚠️ And expect the player to hold **at most `config.maxConcurrentRelays` relays open per process**
+   (default 64; `PLAYER_MAX_RELAYS` in the standalone context): above it the player answers **503
+   with `Retry-After: 2` before calling you**, with no queue. The stream bounded bytes; nothing
+   bounded how many streams were open — an audit opened 200 slow transfers and got 200 upstream
+   connections (13/09). The slot is released in a `finally`, so your errors and a client leaving
+   mid-stream give it back — and so does a relay that **stops progressing**: no chunk for
+   `config.relayStallMs` (30 s) or a total beyond `config.relayMaxMs` (15 min) aborts the pipeline,
+   destroying your response and the client's. A client that stops reading no longer keeps a slot
+   forever; a route of yours that stops sending does not either.
 3. **Accept a server-to-server call.** A tracked link is opened by someone with no session on your
    side. Authenticate the player with the shared secret in the `x-player-fetch-secret` **header** —
    header only, never a query string: logs keep URLs.
@@ -762,6 +821,15 @@ back on an inability to *reach*.** And "do not fall back" applies to what you **
 
 ## What will bite
 
+⚠️ **Every capability you provide must settle in bounded time — `db.request` first of all.** The
+player awaits your `db.request`, `storage.fetchFile`, `mail.send` and the visitor plugin; a promise
+that never settles keeps a request in flight, and the read cache admits at most 128 in-flight reads
+per process before answering **503 busy** to everyone. A database call that hangs is therefore not
+"slow", it is an availability incident for the whole instance — the exact mechanism an audit
+reproduced inside the test suite with a never-settling promise (13/09). Time out your own calls
+(the standalone context bounds its own with `AbortSignal`), and never return a promise you cannot
+guarantee will settle.
+
 **Your document-opening doors reappear.** A host has more than one place that opens a file, and new
 ones get written. Keep the list and hunt it periodically — and note that **your search criteria
 decide what you find**: search by what the user *obtains* (a document opens), not by the technique
@@ -825,6 +893,94 @@ was a correct `bot`, and the reader would have returned an empty string for ever
 set, so every request refused, on a perfectly correct integration. If your field is none of those
 three, tell us and we widen the list. The field name carries no security; the **role** filter does.
 
+⚠️ **`reshare` now answers with a three-state `delivery`, and the state you must handle is
+`"unknown"`.** The response used to carry a single `sent` boolean, which collapsed three different
+outcomes: your mail path declined, *we* declined, or **the call failed without us learning what your
+side did**. Only the third is dangerous — if your host really sent the message and then answered too
+late, a caller reading `sent: false` retries, creating a **second child link and a second email**.
+
+| `delivery` | what happened | what to do |
+|---|---|---|
+| `"sent"` | your mail path reported success | nothing |
+| `"refused"` | a decision was made — yours or ours; `sendRefused` names it, and when your mail hook answered `{ sent: false, reason }` (or `motif`) that word comes back as `hostReason`, trimmed to 80 characters | surface the reason; retrying will refuse again |
+| `"unknown"` | the call failed (timeout, network). **We do not know whether the mail went out** | surface it to a human. **Do not retry automatically** — a retry may duplicate the email |
+| `"not-requested"` | `send` was falsy | nothing |
+
+`sent` is unchanged for integrations already reading it.
+
+⚠️ **Your refusal reason was being thrown away.** One host answers every refusal with
+`{ sent: false, motif }` — eight distinct reasons — precisely so that *refused* never reads as *down*;
+the route read only `sent`. From this train on, a string `reason` or `motif` on your hook's answer travels
+back to the caller as `hostReason` (a string, at most 80 characters; an object is ignored). It is
+your word to your own caller, not a channel: keep it short and non-sensitive.
+
+⚠️ **And you can now make the retry safe: pass a `clientKey`.** Two `reshare` calls with the same
+parent, the same recipient and the same `clientKey` return the **same child link** and send **one**
+email — the second answers `delivery: "idempotent"`, which means *"this was already done"*, not
+*"this failed"*. Generate the key before the first call and reuse it on every retry.
+
+- The key you send is **fingerprinted on our side**, together with the parent and the recipient. It
+  is never stored as you wrote it, and it cannot collide with the system links the host-to-host path
+  creates.
+- ⚠️ **This rides on migration `0011`, which you may already have.** No new column was added: the
+  table has carried a unique idempotency key since then, and the reshare route had simply never been
+  offered it. If `0011` is not applied, `clientKey` is ignored and you get the old behaviour — a
+  retry creates a second link. Nothing breaks; the guarantee is what degrades, and `delivery` still
+  tells you when you are in doubt.
+- Without a `clientKey`, nothing changes: several links to the same recipient remain possible, which
+  is a legitimate thing to want.
+
+⚠️ **Avatars are only loaded from origins the page already serves content from, and everything else
+degrades to initials.** An avatar URL is an `<img>` in the browser of **every other viewer**: an
+arbitrary URL therefore sends each of them — their IP, user agent, the time, the page origin — to
+whoever wrote it. That is not an XSS (the markup is escaped); it is a privacy leak aimed at your
+audience, and an external audit reproduced it on 2026-09-12 against the real chat renderer.
+
+Three things changed, and the second one is the one you may notice:
+
+- **A participant who is not authenticated no longer supplies an avatar at all.** A proven identity
+  replaces what is asserted; an anonymous visitor proves nothing, so the field is dropped and the
+  audience sees initials.
+- **A member's avatar must come from your Supabase origin (or be a relative URL).** It arrives from
+  your identity provider's metadata, and a provider that lets a user edit that field would hand us
+  an arbitrary URL under a proven name. ⚠️ **If your members' avatars live elsewhere — Gravatar, a
+  CDN, Google — they will now render as initials.** Serve them from your own storage to get the
+  images back. The degradation is visible and reversible; the leak was neither.
+- **The renderer refuses the same URLs again**, because one path never reaches this server: a
+  participant can broadcast presence over Realtime straight to the other viewers. No server-side
+  barrier can see that, so the check also lives where every path converges — at render time.
+- ⚠️ **`data:` and `blob:` URLs are refused too, deliberately.** They reach no one, but a data URL
+  travels inside every message row and every presence broadcast, and one more "harmless" form is
+  one more form to reason about at the next audit. A host that stores avatars as data URLs — as an
+  offline fallback, say — will see initials, and nothing will say why except this line. (Asked for by
+  a host, 13/09: three of its members carry one.)
+
+⚠️ **What your `storage.remove` returns now decides whether a row survives.** It returns a boolean:
+`true` means the object is gone, `false` means it is still there. Until 0.1.163 the retention sweep
+erased the row either way — and since this capability exposes `put` and `remove` but **never
+`list`**, the row is the only path to the object: erasing it stranded the file in the bucket
+permanently. The sweep now **keeps the row** when `remove` returns `false`, and reports it as
+`retenues`. Two consequences for you:
+
+- **Do not return `false` for an object that was already absent.** An already-gone object is a
+  success for this purpose — returning `false` makes the sweep retain a row forever, waiting for a
+  file that does not exist. ⚠️ **The player's own standalone context used to have exactly this bug**,
+  found while writing this paragraph: it returned `r.ok`, and Supabase Storage answers an error for a
+  missing object, so the fix for lost files would have created permanent retention instead. It now
+  treats 404 — and a body naming "not found" — as removed, because what is being asked is *"the
+  object is no longer there"*, and it is not there. If you wrap a different provider, do the same.
+- **`retenues > 0` in a retention report means your provider refused a removal**, not that the purge
+  is broken. The next pass retries. A row that lingers is recoverable; a file whose only pointer was
+  erased is not.
+- ⚠️ **If you provide no `storage.remove` at all, file-bearing rows are retained too — and the report
+  says so.** There were three states, not two: `true`, `false`, and *not attempted*. Until 0.1.164 the
+  third one let the row go "as before" — so a host providing `put` without `remove` manufactured
+  permanently unreachable objects at every sweep, with no counter moving. A host found it by reading
+  `retention.js`, not this paragraph, which assumed you provide one. Now: the row stays, `retenues`
+  counts it, the report carries `sansRemove: true` (in `dryRun` too, so you can read it before arming
+  the sweep), and the missing capability is reported once per process through `errors.capture` with
+  `benin: true`. Provide `storage.remove` and the next pass lets them go.
+
 **If you write to the `tts-cache` bucket yourself, write the trace too.** Retention removes an object
 only when its fingerprint has a row in `doc_tts_objects`, and only the player's own route writes that
 row. Anything your code puts in that bucket is therefore invisible to the sweep — **permanently**,

package/docs/RETENTION.md

@@ -287,8 +287,54 @@ numbers, say so; do not round the sentence.
 it defers nothing. A host with no PITR and eight daily snapshots has **one** deadline, not two: the
 age of its oldest snapshot. Take the later of the deadlines that *exist*.
 
+## Cleaning up the objects the broken sweep stranded
+
+The voice-cache sweep removed nothing until it was fixed (see above), so every voice object it
+"purged" is still in the bucket with its row deleted — unreachable by the product, by construction.
+`tools/orphelins-tts.mjs` exists for exactly that backlog, and for nothing else.
+
+```
+node tools/orphelins-tts.mjs --inspecter [--age-jours=N] [--limite=N]
+node tools/orphelins-tts.mjs --inspecter --supprimer --confirme=<the count from the report>
+```
+
+It reads `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` from the environment, and it deliberately
+**steps outside the host contract**: it talks to the Storage API directly to do the one thing the
+contract does not expose — `list`. That is why it is not a guard, runs in no workflow, and contacts
+nothing at all until you pass `--inspecter`.
+
+⚠️ **It cannot tell our orphans from yours, and no measurement can.** An object with no row is one of
+three things: stranded by the broken sweep, a relic from before migration 0021, or **a file your own
+code wrote under the player's naming** — one integrating host reported 908 of those. The tool
+therefore:
+
+- **reports by default** and deletes nothing;
+- treats only objects **older than the retention window** as candidates — a recent object with no row
+  may be a synthesis whose trace write just failed, and deleting it would erase a file the product is
+  about to serve;
+- refuses to act unless you **type the candidate count back** from a report it produced on the
+  current state. If the number has changed since you looked, the bucket moved, and that is precisely
+  what the barrier is there to tell you;
+- never touches a name that is not `<fingerprint>.mp3` / `.json`, nor an object whose date it cannot
+  read — no date means *we do not know*, and we do not delete what we do not know.
+
+Read the report before passing `--supprimer`. If your own code writes to this bucket, write the trace
+too (see *Voice* in `docs/HOST-CONTRACT.md`) — that is what makes your objects distinguishable, and
+what keeps them out of this tool's candidate list.
+
 ## Limits stated rather than left unsaid
 
+- ⚠️ **Until the next release the voice-cache sweep removed nothing at all, in the reference host context,
+  and the paragraph below is what hid it.** `storage.remove` carries an allow-list — a last barrier
+  before a DELETE with the service-role key — and it named only `present-attachments`. `tts-cache`
+  was refused **before any network call**: every removal returned `false`, the trace row was erased
+  anyway, and the object stayed in a public bucket with no path left to it. That is precisely the
+  harm migration 0021 was written to make repairable, realised at 100%.
+  ⚠️ **What concealed it is a true explanation.** Those refusals were counted in `fichiersErreur`,
+  which the next bullet attributes — correctly — to alignment files that legitimately do not exist.
+  A correct account of the noise is the best place to hide a signal. Found on 2026-09-12 while
+  writing the documentation for a *different* fix on the same path; the allow-list now names both
+  buckets the sweep must reach, and nothing else.
 - ⚠️ **`fichiersErreur` can be high without any removal having failed.** Each fingerprint has two
   objects, and the alignment `.json` is not always there — the provider does not always return one.
   Measured on an integrating host's bucket on 27/08: **552 `.mp3` for 356 `.json`**, so 196 audio
@@ -312,6 +358,34 @@ age of its oldest snapshot. Take the later of the deadlines that *exist*.
 - **The dryRun report is complete for presentations**: `messagesExaminees`, `presencesExaminees`
   and `fichiersCandidats` say what the REAL purge would do — same selection walk, no-op deletion,
   `efface.* = 0`.
+- ⚠️ **A row is never erased above a file that resisted, and `retenues` counts the rows kept.**
+  Until 0.1.163 the deletion was unconditional: a failed `storage.remove` still erased the row — and
+  with it the only path to the object. The `storage` capability exposes `put` and `remove`, **never
+  `list`**, which is the very argument that justified migration 0021: with no row there is nothing
+  to walk, so the object stays in the bucket **permanently**, beyond the reach of any sweep. Found
+  by an external audit on 2026-09-12, reproduced before being fixed. A retained row is recoverable —
+  the next pass retries it; a lost file is not. Read `retenues > 0` as *"the storage provider refused
+  a removal; look at it"*, not as a purge failure.
+- ⚠️ **And "not attempted" is the third state, found by a host on 0.1.164.** A host providing `put`
+  without `remove` had no capability to refuse with: `retirerFichier` answered `null` and the row
+  went "as before" — the irreversible loss above, through the other door. Now a missing
+  `storage.remove` retains every file-bearing row, counts it in `retenues`, sets `sansRemove: true` on
+  the result (also in `dryRun`), and is reported once per process (`errors.capture`, `benin: true`).
+  A row without a file still goes.
+- ⚠️ **The alignment `.json` never retains anything — only the audio does.** A third of fingerprints
+  legitimately have no companion (see the 552/356 measurement above); gating the row on both objects
+  would hold a third of the cache forever to protect files that do not exist. So the `.mp3` alone
+  decides, and a missing `.json` is still **counted** in `fichiersErreur` rather than masked.
+- ⚠️ **A presentation is not deleted above a retained message.** The condition used to require only
+  that nothing was `tronque`; "retained" is a second way of not having gone, and without it the fix
+  above would have reopened the parent/child orphan an earlier audit had closed.
+- ⚠️ **The delete carries the purge predicate, not just the identifiers.** The sweep selects by date
+  and used to delete by identifier alone: a heartbeat landing between the two requests refreshed a
+  row that was then erased anyway, judged on a date that was no longer its own. Same audit, same
+  day, also reproduced. PostgREST applies every predicate in the URL at delete time, so replaying
+  the original filter makes the row be judged on its state **at that instant**. The race window does
+  not disappear — it stops being destructive. `select=` returns only what actually went, so the
+  counts stay honest when the database spares a row at the last moment.
 - **The purge advances in BOUNDED BATCHES** (200 rows, a ceiling of 5000 per table and 500
   presentations per run): it selects a batch of identifiers, deletes them with `id=in.(…)`, and
   starts again. The report (`r.rapport`) carries, per table: `examinees`, `supprimees`, `tronque`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.163",
+  "version": "0.1.165",
   "description": "Self-hosted document viewer: per-recipient tracked links, reading analytics, live presentation. The core knows nothing about the application hosting it — everything it borrows arrives through an injected context.",
   "keywords": [
     "pdf-viewer",