discovery-media-player 0.1.4 → 0.1.5

package/CONTRAT.md

@@ -14,10 +14,11 @@
 
 ## Les cinq règles
 
-1. **Un seul dépôt de vérité.** Le player se corrige dans le studio (`player/`, `api/doc.js`,
-   `api/_player-context.js`). **Jamais dans un hôte.** Un correctif écrit côté hôte est une copie
-   qui divergera — le précédent est documenté : un runtime copié dans 4 dépôts, 3 sur 4 servaient
-   une version périmée sans que personne ne le voie.
+1. **Un seul dépôt de vérité.** Le player se corrige **dans le dépôt du player**, jamais dans un
+   hôte — pas même dans celui qui l'a écrit à l'origine, qui l'installe aujourd'hui depuis npm
+   comme tous les autres. Un correctif écrit côté hôte est une copie qui divergera : le précédent
+   est documenté — un runtime copié dans 4 dépôts, 3 sur 4 servaient une version périmée sans que
+   personne ne le voie.
 2. **Additif par défaut.** Ajouter une action, un paramètre ou un champ ne casse aucun hôte : c'est
    libre, ça se note au journal. **Retirer ou renommer est une rupture** → nouvelle version, les
    deux servies pendant la migration.
@@ -43,7 +44,33 @@
    **Qui prévient qui.** Une PR d'hôte qui exige une version plus récente l'écrit **dans son titre**
    (« requiert player ≥ v2 »). Elle ne peut pas être mergée avant que l'instance correspondante soit
    déployée. C'est la seule règle nécessaire : il n'y a qu'une personne qui déploie les deux.
-5. **Un besoin d'hôte se demande, il ne se code pas sur place.** Section « Demandes » en bas.
+5. **Qui corrige le module générique.** Cette règle disait « un besoin d'hôte se demande, il ne
+   se code pas sur place ». Elle datait d'avant la publication, quand le player vivait dans un
+   hôte et qu'aucun autre ne pouvait y toucher. Maintenant qu'il a son dépôt, elle est trop
+   étroite : un hôte **peut** coder — dans le bon dépôt.
+
+   **N'importe quel hôte propose. Le mainteneur arbitre et publie.**
+
+   | | |
+   |---|---|
+   | Un hôte trouve un défaut du player | il ouvre une **issue ou une PR sur le dépôt du player** — il a le contexte, souvent déjà le code |
+   | Le mainteneur | tranche, fusionne, **publie la version** |
+   | Les hôtes | épinglent la nouvelle version quand ils décident de la prendre |
+
+   ⚠️ **La publication reste au mainteneur, et ce n'est pas une question de hiérarchie.** Publier
+   une version décide de l'ordre de déploiement (règle 3). Si chacun publie, plus personne ne sait
+   quelle instance tourne sur quoi.
+
+   ⚠️ **Et l'arbitrage n'est pas une formalité : un hôte optimise pour son cas, c'est normal.**
+   Exemple vécu — un hôte a corrigé chez lui, en trois lignes, le fait que le gestionnaire lise
+   `req.query` sur une plateforme qui ne le remplit pas. Son correctif était juste. Le bon
+   correctif était **dans le cœur**, parce que le défaut touchait tous les hôtes, présents et à
+   venir. Seul quelqu'un qui tient les contraintes des deux côtés voit ça.
+
+   **Le contournement local est autorisé quand il débloque**, à deux conditions : le signalement
+   est ouvert **le jour même**, et le contournement est **retiré quand la version arrive**. Sinon
+   il devient permanent, et on a deux implémentations qui divergent — c'est-à-dire le problème que
+   ce contrat existe pour empêcher.
 
 ---
 
@@ -181,6 +208,47 @@ lire n'importe quoi, avec des identifiants : c'est précisément ce que la garde
    *(Le player applique lui-même cette règle depuis le 13/08 — `relayerFichier()`, un seul chemin
    pour ses trois routes de streaming. Le piège nous concernait aussi.)*
 
+⚠️ **ET UNE QUATRIÈME, D'UNE AUTRE NATURE — celle-ci n'abîme pas l'expérience, elle ouvre les
+données.**
+
+Les trois précédentes portent sur le TRANSPORT. Celle-ci porte sur ce qu'on transporte :
+
+> **Ce que votre route accepte de signer est ce que n'importe quel appelant peut lire.
+> Ne signez jamais un chemin fourni par le client.**
+
+Le raisonnement tient en trois phrases. Le player va chercher le fichier **serveur à serveur** —
+il n'a, par construction, aucune session à faire valoir : c'est tout l'objet du secret partagé.
+Votre route le sert donc avec **ses propres droits**, souvent une clé de service qui contourne
+vos politiques de ligne. Une action qui signe un chemin reçu du navigateur devient alors un
+oracle : un utilisateur fait signer un chemin que ses droits lui refusent, ouvre l'aperçu, et le
+player le lui lit avec les vôtres.
+
+**La garde anti-SSRF ne voit rien** — l'origine est parfaitement légitime, c'est la vôtre.
+
+La forme qui tient : **l'appelant fournit une SOURCE d'un ensemble fermé et un IDENTIFIANT de
+ligne, jamais un chemin.** Le chemin est relu en base avec la session de l'appelant, et vos
+politiques tranchent comme partout ailleurs. C'est la même règle que `brandKey` (une référence,
+pas une copie) et que `PLAYER_HOST_FETCH_BASE` (un préfixe, pas une origine) : **on transmet de
+quoi retrouver, jamais de quoi désigner.**
+
+⚠️ **Le piège est qu'elle est souvent théorique le jour où on l'écrit.** Si vos politiques
+laissent aujourd'hui tout membre connecté lire, l'élévation n'existe pas encore — elle apparaîtra
+au premier resserrement, des mois plus tard, et personne ne fera le lien entre « on a restreint un
+accès » et « une route signe encore n'importe quoi ».
+
+**Corollaire, rencontré par le même hôte une semaine plus tard : quand ce que la référence
+TRANSPORTE est elle-même une capacité, signer ne suffit pas — il faut chiffrer.** Une référence
+signée reste lisible : le base64 se décode. *Signé* veut dire « personne ne peut le forger » ; ça
+n'a jamais voulu dire « personne ne peut le lire ». Si votre référence contient une URL qui sert le
+fichier sans authentification et que rien n'expire, la publier en clair revient à publier le
+fichier.
+
+*(Signalée par le second hôte après l'avoir rencontrée en basculant ses premières surfaces.
+Vérifiée chez l'hôte historique le jour même : une route y signait un chemin reçu du client,
+derrière une liste NOIRE de rôles — un compte d'espace client passait, et tout rôle créé plus tard
+serait passé aussi.)*
+
+
 ### Un refus se dit — `embed-denied`
 
 Un hôte qui intègre la visionneuse (`?embed=1`) attend `embed-ready`. Il est tentant d'en faire un
@@ -340,7 +408,13 @@ documents **sans passer par le player**, donc sans être comptée. Ce n'est pas
 c'est la pente naturelle d'un produit vivant — un `<iframe src="....pdf">` s'écrit en dix secondes.
 
 **Chaque hôte doit tenir la liste de ses portes et la rechasser périodiquement.** Une recherche
-suffit : `.pdf`, `window.open`, `<embed`, `<iframe` sur un fichier, `application/pdf`. Le tableau
+suffit : `.pdf`, `window.open`, `<embed`, `<iframe` sur un fichier, `application/pdf`.
+
+⚠️ **Et le critère de recherche décide de ce qu'on trouve.** Un hôte a inventorié ses portes en
+cherchant les appels de son moteur de stockage — et a manqué son plus gros gisement de documents,
+parce que ces fichiers-là ne sont pas dans son stockage. Aucune recherche de cette forme ne pouvait
+les voir. Cherchez par ce que l'utilisateur OBTIENT (un document qui s'ouvre), pas par la
+technique que vous vous attendez à trouver. Le tableau
 des portes recensées vit chez chaque hôte, pas ici. La règle, elle, est commune : **une porte non
 recensée est une lecture non comptée**, et l'écart ne se voit dans aucune statistique — il se voit
 seulement quand quelqu'un le cherche.
@@ -522,6 +596,8 @@ Toute évolution de la frontière se note ici, datée, avec sa nature.
 | 2026-08-13 | précision | **Le câblage d'une instance appartient à l'HÔTE** (4 fichiers, un seul à écrire) : il ne contient que des décisions de l'hôte. `forKey` d'une instance séparée **appelle une route de l'hôte** plutôt que de recopier la correspondance clé → logo. |
 | 2026-08-13 | additif | **`GET /api/doc?contract=1`** existe enfin : la règle 4 reposait sur un point qui n'avait jamais été écrit. Carte d'identité sans session, sans base, sans cache, sans URL ni secret. |
 | 2026-08-13 | additif | **Le schéma part avec le player** (`player/supabase/init.sql`) : un fichier rejouable qui amène une base vierge à l'état attendu, **déjà durci** — une instance neuve ne connaît jamais l'état « lecture anonyme ouverte ». |
+| 2026-08-13 | précision | **Règle 5 réécrite : qui corrige le module générique.** Elle interdisait à un hôte de coder — c'était vrai quand le player vivait dans un hôte. N'importe quel hôte **propose** désormais (issue ou PR sur le dépôt du player) ; **le mainteneur arbitre et publie**, parce que publier décide de l'ordre de déploiement. Contournement local autorisé s'il débloque, à condition d'ouvrir le signalement le jour même et de le retirer à l'arrivée de la version. |
+| 2026-08-13 | précision | **Règle 1 recadrée** : « le player se corrige dans le studio » devient « dans le dépôt du player » — l'hôte historique l'installe depuis npm comme les autres. |
 | 2026-08-13 | décision | **Dépôt public dès la création, AGPL-3.0** : `PLAYER_SOURCE_URL` pointe dessus, aucun jeton ni clé de déploiement chez les hôtes. Le câblage d'un hôte est considéré couvert — il ne doit donc contenir aucun secret en clair, ce qui est de toute façon la bonne façon de l'écrire. |
 | 2026-08-13 | décision | **Aucun nom de tiers dans le dépôt publié** : les hôtes sont désignés par leur RÔLE (« l'hôte historique », « le second hôte »), jamais par leur raison sociale, et les exemples d'URL sont fictifs. Le rôle porte toute l'information technique ; le nom ne dit qu'une chose — quelles entreprises travaillent ensemble et où leurs documents vivent. |
 

package/README.md

@@ -1,6 +1,11 @@
 <div align="center">
 
-# Discovery Media Player
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Juli1artha/discovery-media-player/main/assets/logo-dark.svg">
+  <img alt="Discovery Media Player" src="https://raw.githubusercontent.com/Juli1artha/discovery-media-player/main/assets/logo.svg" width="520">
+</picture>
+
+<br><br>
 
 **Send a document. Know if it was read.**
 
@@ -13,19 +18,32 @@ to a third-party SaaS.
 [![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](package.json)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-informational.svg)](#docker)
 
+<br>
+
+<img src="https://raw.githubusercontent.com/Juli1artha/discovery-media-player/main/assets/captures/viewer.png" alt="The viewer: a document, a toolbar, and the tracked-reading timer running" width="900">
+
+<br>
+
 </div>
 
 ---
 
 ## Try it in two minutes
 
+**[▶ Open the live demo](https://discovery-media-player-demo.vercel.app)** — a document, in the
+real viewer, nothing to install.
+
+Or on your own machine, over your own files:
+
 ```bash
 docker run --rm -p 3000:3000 -v "$PWD/documents:/data" ghcr.io/juli1artha/discovery-media-player
 ```
 
-Drop a PDF in `./documents`, open `http://localhost:3000/preview/your-file.pdf`. No database,
-no account, no configuration — the viewer, progressive page loading, and the reading timer all
-work from a folder on disk.
+Drop a PDF in `./documents` and open `http://localhost:3000`. No database, no account, no
+configuration — the viewer, progressive page loading and the reading timer all work from a folder
+on disk.
+
+<img src="https://raw.githubusercontent.com/Juli1artha/discovery-media-player/main/assets/captures/folder.png" alt="Folder mode: the server lists what it can display" width="760">
 
 From source, the same thing:
 
@@ -138,6 +156,11 @@ if you run a modified version and people read documents through it over a networ
 able to obtain your source. Set `PLAYER_SOURCE_URL` to where yours lives — the pages served
 link to it.
 
+**The name and the logo are not covered by it.** `assets/` and the words *Discovery Media
+Player* are trademarks of 3D Discovery: fork the code freely, but call your fork something else.
+This is the usual arrangement in open source, and it protects you as much as us — nobody should
+be able to publish something under this name that we did not write.
+
 One exception, on purpose: **[`src/bridge.ts`](src/bridge.ts) is MIT**
 ([`LICENSE-MIT`](LICENSE-MIT)). It is the message contract a host application imports to talk to
 the player. Putting it under the core licence would make integration itself a toll. We protect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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/handler.js

@@ -2714,10 +2714,22 @@ async function handler(req, res) {
     // (+ extras via DOC_FRAME_ANCESTORS, séparés par des espaces — futurs domaines
     // custom d'XP). La CSP frame-ancestors PRIME sur le X-Frame-Options SAMEORIGIN
     // global du vercel.json (spec : XFO ignoré quand frame-ancestors est présent).
+    // ⚠️ EMBARQUEMENT DEMANDÉ SANS HÔTE AUTORISÉ : le seul cas où le player ne peut pas se
+    // défendre lui-même. C'est le NAVIGATEUR qui bloque, avant que la page ne soit chargée —
+    // donc aucun `embed-denied` ne peut partir, et l'hôte voit un silence indiscernable d'une
+    // instance injoignable. Le signaler ici est la seule occasion : c'est le moment exact où l'on
+    // sait qu'on est destiné à être encadré. Sans DOC_FRAME_ANCESTORS, personne ne peut AFFICHER,
+    // exactement comme sans PLAYER_HOST_AUTHZ_URL personne ne peut DIFFUSER.
+    if (share.embed && !(PLAYER.config.extraFrameAncestors || []).length) {
+      try {
+        PLAYER.errors.capture(
+          new Error("?embed=1 demandé mais DOC_FRAME_ANCESTORS est vide : seuls une page de même origine et *.vercel.app peuvent encadrer cette instance"),
+          { route: "doc", indice: "le navigateur bloquera l'iframe avant le chargement — aucun embed-denied ne partira" },
+        );
+      } catch { /* jamais bloquant */ }
+    }
     const frameAncestors = share.embed
-      ? ["'self'", "https://*.vercel.app"]
-          .concat(String(process.env.DOC_FRAME_ANCESTORS || "").split(/\s+/).filter(Boolean))
-          .join(" ")
+      ? embedFrameAncestors()
       : "'self'";
     return sendHtml(res, 200, viewerHtml(share, nonce, logoUrl, pitch), `'nonce-${nonce}'`, [originOf(logoUrl), originOf(share.bot_avatar), originOf(share.brand_logo)].filter(Boolean).join(" "), frameAncestors);
   } catch (error) {