discovery-media-player 0.1.140 → 0.1.142

package/docs/HOST-CONTRACT.md

@@ -54,6 +54,21 @@ need.
 never by order. `plugins` lets you refuse to start when you depend on an optional module this
 instance does not have.
 
+⚠️ **`ctx.has(name)` is that same question in code — and it is documented here because it was, until
+27/08, an accident.** The injected context carries it: `has(name)` answers whether the named plugin
+is present, the same truth the `plugins` field above reports over HTTP. Supply it as
+`has: (name) => !!plugins[name]`; the standalone context returns `false` for everything, having no
+plugins at all.
+
+**As measured on 27/08, nothing in `server/` called it** — that is a reading, not an omission of
+this paragraph, and it is why implementing it buys you nothing immediately and skipping it costs
+you nothing. It is written down for the opposite reason: on that day one host was found to
+implement it *correctly and without knowing*, because the type declared it, while the shape lived
+in 57 test fixtures and, **until this paragraph existed**, in no document at all. A seam that
+exists, works, and is written nowhere is one rename away from being deleted as dead — and it would
+not have been dead. If a future feature needs to ask *"does this host have that plugin?"*, this is
+the spelling, and there should not be a second one.
+
 ⚠️ **`runtime` is the only way to see what the player is actually running on.** `nodeRequired` is
 the floor the package declares, `node` is what the process reports — two numbers, no verdict:
 compare them with your own semver rather than trusting a field we compute for you.
@@ -217,10 +232,20 @@ it. `verdict` is then one of:
 
 | verdict | meaning |
 |---|---|
-| `non-sonde` | nothing asked yet — **not** *nothing missing* |
-| `partiel` | some expectations checked, none of them missing |
+| `non-sonde` | nothing asked yet — **not** *nothing missing*, and **process-local**: this process has looked at nothing; another instance may have looked at everything |
+| `partiel` | some checked, none of them missing — the probe is **lazy**: a column is inspected only once something touches it, so this is *how much has been exercised*, never *how much exists* |
 | `complet` | all checked, all present |
 | `incomplet` | at least one is missing — `manquant` names the file and the sleeping feature |
+| `indetermine` | the database did not answer; this measurement did not happen |
+
+⚠️ **The first two rows are one trap, and it fires on every deploy.** Because the probe is lazy and
+lives in the process, a fresh instance answers `non-sonde`, then `partiel`, then `complet` as
+traffic exercises columns — on a database that never changed. Measured at an integrating host on
+27/08, on one unchanged base: `sondees=9 complet` on the old instance, `sondees=0 non-sonde` right
+after the deploy, `sondees=1 partiel` sixty-seven minutes later. They looked three times before
+concluding, because a neighbouring field had already taught them to distrust that zero — and they
+were about to report a regression that did not exist. Read these two verdicts as *what this
+process has asked so far*, never as a statement about the schema.
 
 Each `manquant` entry has **exactly this shape** — pin your parser to it, not to what a schema
 probe "should" return:
@@ -240,7 +265,6 @@ If you consume this card, test your parser against the JSON above, not against a
 ⚠️ **A card without a `schema` field is an alert, not a success**: it signals an instance older
 than 0.1.58 — a version that cannot answer the question. (Rule contributed by the second host, for
 exactly the monitoring case where "no data" would otherwise read as "all clear".)
-| `indetermine` | the database did not answer; this measurement did not happen |
 
 ⚠️ **`incomplet` wins over `partiel`**: a missing column is a positive fact and settles the verdict
 on its own, even when the rest has not been checked.
@@ -540,13 +564,39 @@ This is not hypothetical: an integrating host reported 908 objects it had writte
 the parity was deliberate, so that one clip serves both surfaces. Nothing about the name distinguishes
 its objects from the player's; only the missing row does.
 
-So `doc_tts_objects` is a **host write point**, not an internal table. Write it with the same
-fingerprint the player computes, and nothing else:
+So `doc_tts_objects` is a **host write point**, not an internal table. What the sweep needs from
+you is **one property, and only this one**:
+
+> the `hash` you write in the row **is** the object's base name — the file is `<hash>.mp3`, its
+> alignment is `<hash>.json`, and nothing else has to be true.
+
+⚠️ **How you compute that digest is yours, and this page used to say otherwise.** It read *"write
+it with the same fingerprint the player computes, and nothing else"*, which made a perfectly safe
+host non-compliant on paper — and the obvious fix, realigning the formula, is the one thing that
+would break: the objects already in the bucket carry the **old** digest in their names, so a row
+written with a new one points at nothing, and the real name loses its only row. Reported on 27/08
+by a host whose third writer uses `preview-fr-v2` where the player uses `v2`. Their five write
+sites are correct as they stand.
+
+The sweep never recomputes anything: it reads `hash` from the row and removes `hash + ".mp3"` and
+`hash + ".json"` (`server/retention.js`). A bench holds that property rather than a comment —
+`retentionCacheDeVoix.test.js` builds its rows with `hash: "aaa"`, which is the sha256 of nothing,
+and requires `tts-cache/aaa.mp3` to be the file removed.
+
+**The player's own formula matters for one thing only, and it is not retention** — sharing. Its
+route recomputes this digest to find a clip it already paid for, so match it *if* you want one clip
+to serve both surfaces (as one host deliberately does, for 908 objects). If you don't, the player
+simply synthesises its own, and nothing else changes:
 
 ```
 hash = sha256(voiceId + "|" + modelId + "|v2|" + spokenText)   -- hex, lowercase
 ```
 
+| requirement | mandatory? | if you don't |
+|---|---|---|
+| the row's `hash` is the object's base name | **yes, always** | the object is invisible to the sweep, permanently |
+| the digest matches the player's formula | no — only to share a clip | the player synthesises its own, and pays for it |
+
 ```sql
 insert into public.doc_tts_objects (hash) values ($1)
 on conflict (hash) do nothing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.140",
+  "version": "0.1.142",
   "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",

package/server/reponses.js

@@ -81,4 +81,35 @@ function repondreJson(res, statut, valeur, entetes) {
  */
 const jsonPour = (res) => (statut, valeur, entetes) => repondreJson(res, statut, valeur, entetes);
 
-module.exports = { refuserEnTexte, repondreJson, repondreJsonTexte, jsonPour };
+/**
+ * L'ÉTIQUETTE DE ROUTE D'UNE ERREUR CAPTURÉE — bornée, parce que l'appelant la choisit.
+ *
+ * ⚠️ NEUF SITES LA POSAIENT À L'IDENTIQUE, ET AUCUN NE LA BORNAIT :
+ * `route: String(body.action || "(sans action)")`. `body.action` vient du corps de la requête, donc
+ * de n'importe qui : un mégaoctet de texte, des retours à la ligne, des guillemets, des octets de
+ * contrôle. Ça part ensuite dans le puits d'erreurs de l'HÔTE — Sentry, un journal, un fichier —
+ * c'est-à-dire dans un système qu'on ne contrôle pas et dont on ne connaît pas les échappements.
+ *
+ * ⚠️ CE QU'ON EMPÊCHE N'EST PAS « UNE GROSSE CHAÎNE », C'EST LA FORGERIE DE STRUCTURE. Un saut de
+ * ligne dans un journal ligne-par-ligne ouvre une entrée qui n'a jamais eu lieu ; un guillemet dans
+ * un puits qui concatène du JSON en ouvre un champ. On ne garde donc que les caractères dont une
+ * action est faite — lettres, chiffres, `.`, `_`, `:`, `-` — et rien d'autre ne traverse.
+ *
+ * ⚠️ ET ON DIT LA TRONCATURE PLUTÔT QUE DE LA TAIRE. Une étiquette coupée en silence se lit comme
+ * une action qui s'appelle vraiment comme ça. Le `…` final est la différence entre « voici le nom »
+ * et « voici ce qu'il en restait ».
+ *
+ * Rendre `(action illisible)` plutôt que du vide quand tout a été retiré : « aucune action » et
+ * « une action dont il ne reste rien de lisible » sont deux constats différents, et un exploitant
+ * qui voit le second sait qu'on lui a envoyé quelque chose d'anormal.
+ */
+const ETIQUETTE_MAX = 64;
+function etiquetteRoute(action) {
+  const brut = String(action == null ? "" : action).trim();
+  if (!brut) return "(sans action)";
+  const propre = brut.replace(/[^A-Za-z0-9._:-]/g, "");
+  if (!propre) return "(action illisible)";
+  return propre.length > ETIQUETTE_MAX ? propre.slice(0, ETIQUETTE_MAX) + "…" : propre;
+}
+
+module.exports = { refuserEnTexte, repondreJson, repondreJsonTexte, jsonPour, etiquetteRoute };

package/server/routes-agent.js

@@ -10,7 +10,7 @@
 // agentVoix.test.js échoue sans cette ligne.
 const crypto = require("node:crypto");
 const { adresseAppelant } = require("./appelant");
-const { jsonPour } = require("./reponses.js");
+const { jsonPour, etiquetteRoute } = require("./reponses.js");
 
 const { getShareBySlug } = require("./shares");
 const { creerCache, CODE_SATURATION } = require("./cache.js");
@@ -355,7 +355,7 @@ async function traiter(req, res, body, _slug) {
             cached: extrait.cached || undefined,
             spoken: spoken !== text ? spoken : undefined,
           });
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       if (body.action === "bot-start" || body.action === "bot-say" || body.action === "bot-history" || body.action === "bot-nudge" || body.action === "bot-book" || body.action === "bot-contact" || body.action === "bot-rate" || body.action === "bot-script") {
         const jp = jsonPour(res);
@@ -470,7 +470,7 @@ async function traiter(req, res, body, _slug) {
           const r = await docbot.botSay(String(body.sessionId || ""), share, text, pages, mobile, blang);
           if (r.error) return jp(400, { ok: false, error: r.error });
           return jp(200, { ok: true, ...r });
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       // Assistance (heartbeat) : PUBLIC (l'audience est anonyme). Journalise qui suit / combien de temps / pages vues.
       // Rate-limit généreux par IP (heartbeat ≈ 145/h/participant) : bloque le spam d'assistants factices sans

package/server/routes-direct.js

@@ -4,7 +4,7 @@
 // Reste à PLAT dans server/ (les gardes de forge ciblent server/*.js).
 
 const { adresseAppelant, lcMembre, cleAnonyme, profilDuJeton } = require("./appelant");
-const { jsonPour } = require("./reponses.js");
+const { jsonPour, etiquetteRoute } = require("./reponses.js");
 
 const { createPresentation, getPresentation, setPage, endPresentation, addMessage, toggleReaction, editMessage, deleteMessage, setChatLock, createUploadUrl, reclaimPresentation, touchPresentation, listActivePresentations, handoverPresentation, endPresentationByOwner, recordAttendance, presentationStats, listPresentationsForDoc, switchPresentationDoc, setPresentationContent } = require("./presentations");
 // Cadence de présence et cible de mutualisation par IP (P1 performance). L'intervalle DOIT
@@ -49,7 +49,7 @@ async function traiter(req, res, body, _slug) {
           // hôte, chaque « Terminer » échouait en 23502 (marqueur d'archive NOT NULL) — et ce 500
           // muet ne laissait RIEN, même pas une ligne dans le journal d'erreurs. Un journal que
           // personne ne lit vaut peu ; aucun journal ne vaut rien du tout.
-          try { PLAYER.errors.capture(erreur instanceof Error ? erreur : new Error(String(erreur)), { route: "present-" + String(body.action || "").replace(/^present-/, "") }); } catch { /* jamais bloquant */ }
+          try { PLAYER.errors.capture(erreur instanceof Error ? erreur : new Error(String(erreur)), { route: etiquetteRoute("present-" + String(body.action || "").replace(/^present-/, "")) }); } catch { /* jamais bloquant */ }
           return jp(500, { ok: false });
         }
       }
@@ -222,7 +222,7 @@ async function traiter(req, res, body, _slug) {
           // des présences) : une présentation close refuse toute écriture, jeton valide ou non.
           const pt = (r.ok && jetonCandidat) ? jetonCandidat : "";
           return jp(r.ok ? 200 : (r.status || 400), pt ? { ...r, pt } : r);
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       // Gestion des présentations (membre AUTHENTIFIÉ requis) : liste / reprise / transfert / stats / historique doc.
       if (body.action === "present-list" || body.action === "present-reclaim" || body.action === "present-handover" || body.action === "present-owner-end" || body.action === "present-stats" || body.action === "present-doc-list" || body.action === "present-switch" || body.action === "present-content") {
@@ -275,7 +275,7 @@ async function traiter(req, res, body, _slug) {
           else if (body.action === "present-content") r = await setPresentationContent(String(body.slug || ""), (u && u.email) || "", isAdmin, body.content, String(body.control || ""));
           else r = await handoverPresentation(String(body.slug || ""), u.email, body.newOwner);
           return jp(r.ok ? 200 : (r.status || 400), r);
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       // Chat de présentation (historisé) : n'importe quel participant (présentateur ou audience) poste un
       // message. Écriture via service role ; anti-spam par IP (60/h). La présentation doit exister.
@@ -301,7 +301,7 @@ async function traiter(req, res, body, _slug) {
             avatar: (profil && profil.avatar) || body.avatar,
             isPresenter: validControl, isMember: !!profil, body: body.body, replyTo: body.replyTo, replyName: body.replyName, replyText: body.replyText, authorToken: body.authorToken, attachment: body.attachment , clientKey: body.clientKey });
           return jp(r.ok ? 200 : (r.status || 400), r);
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       // Pièce jointe : URL d'upload signée (la présentation doit exister ; rate-limit).
       if (body.action === "present-upload-url") {
@@ -314,7 +314,7 @@ async function traiter(req, res, body, _slug) {
           if (!allowed) return jp(429, { ok: false, error: "rate" });
           const r = await createUploadUrl(String(body.slug || ""), body.name, body.type);
           return jp(r.ok ? 200 : (r.status || 400), r);
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       // Chat : éditer / supprimer un message, verrouiller le chat.
       if (body.action === "present-msg-edit" || body.action === "present-msg-delete" || body.action === "present-chatlock") {
@@ -325,7 +325,7 @@ async function traiter(req, res, body, _slug) {
           else if (body.action === "present-msg-delete") r = await deleteMessage(String(body.slug || ""), body.msgId, { authorToken: body.authorToken, control: body.control });
           else r = await setChatLock(String(body.slug || ""), String(body.control || ""), !!body.locked);
           return jp(r.ok ? 200 : (r.status || 400), r);
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
       // Réaction emoji (toggle) sur un message du chat de présentation.
       if (body.action === "present-react") {
@@ -345,7 +345,7 @@ async function traiter(req, res, body, _slug) {
           const reacteur = require("./presentations").reacteurDepuisJeton(body.authorToken);
           const r = await toggleReaction(String(body.slug || ""), body.msgId, body.emoji, reacteur, body.etat);
           return jp(r.ok ? 200 : (r.status || 400), r);
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jp(500, { ok: false }); }
       }
   return false;
 }

package/server/routes-liens.js

@@ -4,7 +4,7 @@
 // Reste à PLAT dans server/ (les gardes de forge ciblent server/*.js).
 
 const { adresseAppelant } = require("./appelant");
-const { jsonPour, repondreJson } = require("./reponses.js");
+const { jsonPour, repondreJson, etiquetteRoute } = require("./reponses.js");
 const { estConflit } = require("./erreurs-base.js");
 const { createShare, createReshare, sendReshareEmail, revokeShare, setShareAuth, listSharesForDoc, listSessionsForDoc, internalStatsForDoc, cleIdempotence, getShareBySlug, logView, upsertSession, upsertInternalSession, overview: docOverview } = require("./shares");
 const { SESSION_QUOTA_PER_HOUR, VIEW_QUOTA_PER_HOUR } = require("./shared.generated.js");
@@ -249,7 +249,7 @@ async function traiter(req, res, body, slug) {
         }
         const { slug } = await createShare({ brandKey: body.brandKey, docId: body.docId, docTitle: body.docTitle, fileUrl: body.fileUrl, fileName: body.fileName, recipientEmail: body.recipientEmail, recipientName: body.recipientName, createdBy: u.email, bot: body.bot, botScript: body.botScript, guided: body.guided, profileId: body.profileId, allowDownload: body.allowDownload, videoLayout: body.videoLayout, logo: body.logo, logoDark: body.logoDark });
         return jd(200, { ok: true, slug });
-        } catch (e) { try { PLAYER.errors.capture(e, { route: String(body.action || "(sans action)") }); } catch { /* jamais bloquant */ } return jd(500, { ok: false }); }
+        } catch (e) { try { PLAYER.errors.capture(e, { route: etiquetteRoute(body.action) }); } catch { /* jamais bloquant */ } return jd(500, { ok: false }); }
       }
 
       // Re-partage (forward depuis la visionneuse) : crée un lien enfant tracé, et envoie l'email via 3D