discovery-media-player 0.1.174 → 0.1.175

package/docs/HOST-CONTRACT.md

@@ -462,6 +462,32 @@ 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.
 
+### Reading back the reads you vouched for
+
+Every session now carries `attested_recipient_email`, read from its link — on both session readings,
+`docshare.sessions` and `docshare.sessionsByRecipient`, for members and for you alike.
+`recipient_email` stays `null` on an attested link, for the reason above. Nothing is copied into the
+sessions table: no migration beyond `0001`.
+
+You can also read those sessions yourself, server to server: `docshare.sessions` with
+`x-player-share-secret` and a `docId` answers `{ ok: true, sessions, scope: "host" }`, holding
+**only** the sessions of links that have no author **and** an attested address — the links you
+created for a visitor you vouched for. You learn how long your visitor read, never who else did:
+
+- an **anonymous** link (no attested address) is not readable with the secret;
+- a **member's** link (`created_by` set) stays behind the member's token and `list.all`;
+- a **forwarded** link born from an attested one is not readable either — its reader was chosen by
+  your visitor, and you never vouched for them;
+- every other action with the secret — `list`, `revoke`, `overview`, `setauth`,
+  `sessionsByRecipient` — is still refused with `403`.
+
+⚠️ **The sort by client is yours, and it belongs before any display.** A `docId` is shared across
+clients, so this answer covers every visitor you attested on that document. Keep only the sessions
+whose `attested_recipient_email` belongs to the client being shown, on your server, after your own
+check that the person asking may see that client. Without `0001`, the call answers `409` and names the
+file — never an empty list, which would read as *"your client read nothing"*. Rate-limited per
+calling address, separately from creation.
+
 ## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.174",
+  "version": "0.1.175",
   "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/routes-liens.js

@@ -78,17 +78,60 @@ async function traiter(req, res, body, slug) {
           // lui-même avant d'écrire.
           //
           // ⚠️ TROIS VERROUS, et chacun ferme une porte différente :
-          //   1. `create` UNIQUEMENT — révoquer, lister, lire des statistiques restent des actes
-          //      de membre. Un secret de serveur ne doit pas donner à voir qui a lu quoi.
-          //   2. AUCUN destinataire — le nominatif a un membre. L'admettre ici rouvrirait par la
-          //      bande ce que le JWT protège.
+          //   1. `create`, ET LA LECTURE DES LIENS QUE L'HÔTE A LUI-MÊME ATTESTÉS — révoquer,
+          //      lister, l'aperçu, la protection et la fiche d'une personne restent des actes de
+          //      membre. Un secret de serveur ne doit pas donner à voir qui a lu quoi. (Ce verrou
+          //      disait « `create` UNIQUEMENT » jusqu'au #574 ; ce qui a changé est dit juste
+          //      dessous, à l'endroit où la porte s'ouvre.)
+          //   2. AUCUN destinataire NOMINATIF — le nominatif a un membre. L'admettre ici rouvrirait
+          //      par la bande ce que le JWT protège. (Le destinataire ATTESTÉ n'en est pas un : il
+          //      va dans sa propre colonne, voir plus bas.)
           //   3. IDEMPOTENT par `docId` — sans ça, un redéploiement, une reprise sur erreur ou un
           //      double clic donnent trois liens pour la même plaquette, donc des statistiques
           //      fragmentées en trois, découvertes en les lisant six mois plus tard.
           if (typeof PLAYER.identity.isTrustedHostCall === "function"
               && PLAYER.identity.isTrustedHostCall(req.headers)) {
+            // ⚠️ L'HÔTE LIT LES SESSIONS DES LIENS QU'IL A CRÉÉS ET ATTESTÉS — ET AUCUNE AUTRE.
+            //
+            // Ce que le verrou 1 refusait, c'est qu'un secret de serveur donne à voir QUI a lu. Ici
+            // l'hôte ne découvre personne : chaque adresse de cette réponse, il l'a fournie lui-même
+            // à la création, depuis sa base, après vérification. Il apprend COMBIEN DE TEMPS son
+            // client a lu, pas qui. Sans cette porte, un hôte de production mesurait 108 sessions
+            // complètes, temps par page compris, et affichait « 0 de lecture » à son conseiller : le
+            // lien n'a pas d'auteur, donc aucun membre ne le voit sous « mes liens », et `list.all`
+            // le voyait sans adresse (#574).
+            //
+            // La borne est double, et chaque moitié ferme une porte :
+            //   • `created_by` NUL — les liens des membres restent derrière le JWT et `list.all` ;
+            //   • adresse attestée NON NULLE — un lien anonyme (la plaquette publique lue par un
+            //     prospect sans compte) ne se lit pas par le secret.
+            // C'est le pendant exact du « mes liens » d'un membre : l'hôte lit les liens qu'il a
+            // créés. La réponse dit `scope: "host"` pour que personne ne la confonde avec `all`.
+            //
+            // ⚠️ ON A ÉCARTÉ UNE QUESTION `list.host` POSÉE À `canManageShares`. Elle passerait par
+            // le JWT d'un membre, et le `docId` se partage entre clients : un membre verrait, dans
+            // tout écran qui lit des sessions, les clients attestés de ses collègues. Lu par le
+            // secret, le tri par client se fait sur le serveur de l'hôte, avant tout affichage.
+            if (body.action === "docshare.sessions") {
+              const docId = String(body.docId || "").trim();
+              if (!docId) return jd(400, { ok: false, error: "docId requis" });
+              // Même esprit que `hshare:` — une clé à part, parce que lire et créer n'ont pas le
+              // même rythme : la création est idempotente (une fois par document et par visiteur),
+              // la lecture revient à chaque ouverture d'un espace client. Le plafond borne un secret
+              // fuité qui balaierait des `docId`, pas l'usage d'un hôte qui affiche ses lectures.
+              const ipL = adresseAppelant(req) || "hote";
+              if (!(await PLAYER.limits.allow(`hsessions:${ipL}`, 600, 3600))) return jd(429, { ok: false, error: "rate" });
+              // ⚠️ SANS LA COLONNE, UN 409 QUI NOMME LE FICHIER — PAS UN `[]`. La sonde ne distingue
+              // pas « colonne absente » de « base injoignable », et un tableau vide se lirait
+              // « votre client n'a rien lu ». Même réponse que la création attestée, plus bas.
+              if (!(await require("./schema").attendue("destinataireAtteste"))) {
+                return jd(409, { ok: false, error: "migration", message: "Destinataire attesté indisponible : appliquez supabase/migrations/0001-destinataire-atteste.sql." });
+              }
+              const sessions = await listSessionsForDoc(docId, null, { hoteAtteste: true });
+              return jd(200, { ok: true, sessions, scope: "host" });
+            }
             if (body.action !== "docshare.create") {
-              return jd(403, { ok: false, error: "L'appel serveur à serveur ne crée que des liens sans destinataire." });
+              return jd(403, { ok: false, error: "L'appel serveur à serveur ne crée que des liens, et ne lit que les sessions des liens attestés qu'il a créés." });
             }
             // ⚠️ LE DESTINATAIRE ATTESTÉ : L'HÔTE SE PORTE GARANT, IL N'AFFIRME PAS.
             //

package/server/shares.js

@@ -672,17 +672,85 @@ function racineDuLien(slug, parParent, profondeurMax = 64) {
  *
  * `null` = toutes les sessions (le rôle qui a `list.all`), une adresse = celles dont la chaîne
  * d'origine part d'un lien que cette personne a créé.
+ *
+ * `hoteAtteste` = la portée de l'HÔTE qui lit par son secret (`scope: "host"`) : seulement les
+ * sessions des liens qu'il a créés ET attestés — voir `sessionsDesLiensAttestes`.
  */
-async function listSessionsForDoc(docId, owner = null) {
+async function listSessionsForDoc(docId, owner = null, { hoteAtteste = false } = {}) {
   const id = enc(String(docId || ""));
+  const champsLien = await champsDuLien();
+  if (hoteAtteste) return sessionsDesLiensAttestes(id, champsLien);
   const [sessions, shares] = await Promise.all([
     PLAYER.db.request(`commercial_doc_sessions?doc_id=eq.${id}&select=${SELECT_SESSION}&order=last_at.desc&limit=500`),
     // ⚠️ TOUS LES LIENS, RÉPÉTITIONS COMPRISES. La chaîne se remonte par `parent_slug` : un maillon
     // absent de cette lecture casse la remontée et fait échouer fermé une session légitime. Le
     // filtre `is_test` d'avant ne servait qu'à nommer le destinataire ; il ne peut pas servir à
     // reconstruire une filiation.
-    PLAYER.db.request(`commercial_doc_shares?doc_id=eq.${id}&select=slug,parent_slug,created_by,recipient_email,recipient_name`),
+    PLAYER.db.request(`commercial_doc_shares?doc_id=eq.${id}&select=${champsLien}`),
   ]);
+  return sessionsAvecLeurLien(sessions, shares, owner);
+}
+
+/**
+ * Les colonnes d'un LIEN qui accompagnent ses sessions — et l'adresse attestée seulement si la base
+ * la porte.
+ *
+ * ⚠️ PostgREST REJETTE UN `select=` QUI NOMME UNE COLONNE INCONNUE, et pas seulement l'écriture : un
+ * hôte qui n'a pas appliqué la 0001 verrait TOUTES ses lectures de sessions tomber en 500 le jour où
+ * il déploie ce code — pour une fonction dont il ne se sert pas. On demande donc à la sonde, comme
+ * le chemin de création le fait déjà ; un « oui » est retenu pour le processus, la question ne
+ * coûte rien après la première fois.
+ *
+ * Sans la colonne, aucun lien ne peut être attesté (la création refuse en 409 et nomme le fichier) :
+ * le `null` que portera alors chaque session est VRAI, pas une valeur par défaut.
+ */
+const CHAMPS_LIEN = "slug,parent_slug,created_by,recipient_email,recipient_name";
+async function champsDuLien(supplement = "") {
+  const atteste = await require("./schema").attendue("destinataireAtteste");
+  return CHAMPS_LIEN + supplement + (atteste ? ",attested_recipient_email" : "");
+}
+
+/**
+ * Les sessions des liens que l'HÔTE a créés et attestés : sans auteur (`created_by` nul) ET portant
+ * une adresse attestée. Rien d'autre.
+ *
+ * ⚠️ LA BORNE EST DANS LA REQUÊTE, PAS APRÈS ELLE. La lecture des membres prend les 500 sessions les
+ * plus récentes du document puis filtre par chaîne d'origine — elle ne peut pas faire autrement, la
+ * chaîne est récursive. Ici le critère est une propriété du lien lui-même, donc se pousse en base :
+ * on lit d'abord les liens attestés, puis leurs seules sessions (`slug=in.(…)`). Sans ça, une
+ * plaquette partagée — le `docId` se partage entre clients — lue par cinq cents prospects anonymes
+ * repousserait hors de la fenêtre les lectures du client attesté, et l'hôte lirait « 0 de lecture »
+ * là où il y en avait : exactement le constat du #574, reproduit par la correction.
+ *
+ * ⚠️ LA SESSION D'UN LIEN ENFANT N'EN EST PAS. Un repartage depuis un lien attesté naît avec
+ * `created_by: parent.recipient_email || parent.created_by` — nul ici — mais sans adresse attestée :
+ * son lecteur est celui que le visiteur a choisi, que l'hôte n'a jamais vérifié. Le filtre porte
+ * donc sur le lien DE LA SESSION, pas sur sa racine — l'inverse de la portée des membres, et pour
+ * la raison inverse : un membre a causé les lectures de sa descendance, l'hôte n'atteste que les
+ * adresses qu'il a fournies.
+ *
+ * ⚠️ ET SANS LA COLONNE, ON REFUSE PLUTÔT QUE DE RENDRE `[]`. La sonde ne distingue pas « colonne
+ * absente » de « base injoignable » ; un tableau vide dirait « votre client n'a rien lu » sur une
+ * base qui n'a pas répondu. La route vérifie avant d'appeler et rend le 409 de la création ; ce
+ * refus-ci ferme la porte à tout autre appelant.
+ */
+async function sessionsDesLiensAttestes(id, champsLien) {
+  if (!champsLien.includes("attested_recipient_email")) {
+    throw Object.assign(new Error("Destinataire attesté indisponible : appliquez la migration 0001-destinataire-atteste.sql."),
+      { statusCode: 409, publique: true });
+  }
+  const liens = await PLAYER.db.request(
+    `commercial_doc_shares?doc_id=eq.${id}&created_by=is.null&attested_recipient_email=not.is.null&select=${champsLien}&limit=500`);
+  const lus = Array.isArray(liens) ? liens : [];
+  if (!lus.length) return [];
+  const liste = lus.map((sh) => `"${String(sh.slug).replace(/[",()]/g, "")}"`).join(",");
+  const sessions = await PLAYER.db.request(
+    `commercial_doc_sessions?doc_id=eq.${id}&slug=in.(${enc(liste)})&select=${SELECT_SESSION}&order=last_at.desc&limit=500`);
+  return sessionsAvecLeurLien(sessions, lus, null);
+}
+
+/** Chaque session, projetée, avec ce que son lien dit d'elle — bornée à `owner` s'il est donné. */
+function sessionsAvecLeurLien(sessions, shares, owner) {
   const liste = Array.isArray(shares) ? shares : [];
   const parSlug = new Map(liste.map((sh) => [sh.slug, sh]));
   const parParent = new Map(liste.map((sh) => [sh.slug, sh.parent_slug || null]));
@@ -697,7 +765,7 @@ async function listSessionsForDoc(docId, owner = null) {
     const parent = lien && lien.parent_slug ? parSlug.get(lien.parent_slug) || null : null;
     sortie.push({
       ...sessionServie(s),
-      recipient_name: (lien && lien.recipient_name) || null,
+      ...lienServi(lien),
       // La filiation voyage avec la session : « une session, un lecteur, visible par sa chaîne
       // d'origine » ne se lit pas si la chaîne n'est pas dans la charge utile.
       parent_slug: (lien && lien.parent_slug) || null,
@@ -727,6 +795,11 @@ async function listSessionsForDoc(docId, owner = null) {
  * IP mais un `creator_ip_hash` — un HMAC salé, lié au slug pour qu'on ne puisse pas corréler une
  * adresse d'une présentation à l'autre (0.1.114). Deux décisions opposées sur la même donnée dans
  * le même produit ; celle-ci était la permissive, et personne ne les avait confrontées.
+ *
+ * ⚠️ CETTE LISTE NE PORTE QUE LES COLONNES DE LA SESSION. Ce qu'une session dit de son LIEN —
+ * `recipient_name`, la filiation, et depuis le #574 `attested_recipient_email` — est ajouté nommément
+ * par chaque lecture, depuis la ligne du lien. L'adresse attestée sort donc par décision écrite
+ * (`sessionsAvecLeurLien`), jamais parce qu'une colonne de session l'aurait emportée.
  */
 const CHAMPS_SERVIS = [
   "session_id", "slug", "doc_id", "recipient_email",
@@ -760,6 +833,31 @@ const CHAMPS_RETENUS = {
 /** La projection d'une ligne de session : ce qui sort, et rien d'autre. */
 const sessionServie = (s) => Object.fromEntries(CHAMPS_SERVIS.filter((c) => c in s).map((c) => [c, s[c]]));
 
+/**
+ * Ce qu'une session dit de son LIEN : la même liste-de-ce-qui-est-permis que `CHAMPS_SERVIS`, mais
+ * lue sur la ligne du lien. Un champ absent du lien sort `null` — jamais absent de la réponse.
+ *
+ * ⚠️ L'ADRESSE ATTESTÉE VIENT DU LIEN, ET N'ENTRE PAS DANS `CHAMPS_SERVIS`. Elle n'est pas une
+ * colonne de session et ne doit pas le devenir : la recopier dans `commercial_doc_sessions` en ferait
+ * un second exemplaire du même fait, que la révocation, la rétention et une correction d'adresse
+ * devraient chacune penser à suivre. Jusqu'au #574 elle ne sortait pas du tout : 108 sessions
+ * mesurées chez un hôte, temps par page compris, ne s'attribuaient à personne.
+ *
+ * ⚠️ ET `recipient_email` RESTE NUL pour un lien attesté — ce n'est pas un oubli de recopie. Ce champ
+ * dit aussi qui peut expédier au repartage (cf. `routes-liens.js`, « elle ne va pas dans
+ * `recipient_email` »). Servir l'adresse sous son propre nom laisse cette garde intacte.
+ *
+ * ⚠️ UNE LISTE, PAS DEUX LITTÉRAUX. Les deux lectures de sessions écrivaient chacune
+ * `recipient_name: (lien && …) || null` ; y ajouter un champ voulait dire penser aux deux, et c'est
+ * en le faisant pour l'adresse attestée que la garde `colonneMigreeConditionnelle` a tiré — elle lit
+ * toute clé `colonne:` comme une ÉCRITURE en base, or celle-ci n'en est pas une (c'est une clé de la
+ * réponse). On n'a pas desserré la garde : on a retiré le second exemplaire, et les deux lectures
+ * disent désormais la même chose d'un lien par construction. Les écritures, elles, restent sous sa
+ * surveillance entière.
+ */
+const CHAMPS_DU_LIEN_SERVIS = ["recipient_name", "attested_recipient_email"];
+const lienServi = (lien) => Object.fromEntries(CHAMPS_DU_LIEN_SERVIS.map((c) => [c, (lien && lien[c]) || null]));
+
 /** Le `select=` qui descend dans la requête — la MÊME liste, pas une seconde écriture. */
 const SELECT_SESSION = CHAMPS_SERVIS.join(",");
 
@@ -779,9 +877,12 @@ const SELECT_SESSION = CHAMPS_SERVIS.join(",");
 async function liensEtAncetres(slugs, vaguesMax = 8) {
   const parSlug = new Map();
   let aLire = [...new Set(slugs.filter(Boolean))];
+  // La même liste de colonnes que `listSessionsForDoc`, par la même fonction : les deux lectures de
+  // sessions doivent dire la même chose d'un lien, adresse attestée comprise.
+  const champsLien = await champsDuLien(",doc_id,doc_title");
   for (let vague = 0; vague < vaguesMax && aLire.length; vague += 1) {
     const liste = aLire.map((x) => `"${String(x).replace(/[",()]/g, "")}"`).join(",");
-    const lus = await PLAYER.db.request(`commercial_doc_shares?slug=in.(${enc(liste)})&select=slug,parent_slug,created_by,recipient_email,recipient_name,doc_id,doc_title`);
+    const lus = await PLAYER.db.request(`commercial_doc_shares?slug=in.(${enc(liste)})&select=${champsLien}`);
     const vus = Array.isArray(lus) ? lus : [];
     if (!vus.length) break;
     for (const sh of vus) parSlug.set(sh.slug, sh);
@@ -877,7 +978,11 @@ async function listSessionsForRecipient(email, { owner = null, depuis = null, ap
     sessions.push({
       ...sessionServie(s),
       doc_title: (lien && lien.doc_title) || null,
-      recipient_name: (lien && lien.recipient_name) || null,
+      // ⚠️ L'ADRESSE ATTESTÉE Y EST PRESQUE TOUJOURS NULLE, ET SERVIE QUAND MÊME. Cette lecture part
+      // de `recipient_email=eq.<adresse>`, que les sessions d'un lien attesté n'ont pas : elle les
+      // atteint rarement. Mais deux lectures de la même session qui ne portent pas les mêmes champs
+      // obligent l'hôte à savoir par laquelle il est passé — la même projection les en dispense.
+      ...lienServi(lien),
       parent_slug: (lien && lien.parent_slug) || null,
       parent_recipient_email: parent ? parent.recipient_email || null : null,
       parent_recipient_name: parent ? parent.recipient_name || null : null,