discovery-media-player 0.1.3 → 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:
 
@@ -87,6 +105,9 @@ forking it. A fix lands once and reaches every instance on its next deploy.
 - **Node / Express / Next.js** — same handler, mounted on a route
 - **Standalone** — `npm start`, or the Docker image
 
+It reads `req.query` when the platform provides it (serverless, Express) and falls back to parsing
+`req.url` when it does not — so a bare `http.createServer` works too, without a shim.
+
 See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the boundary, and
 [`docs/API.md`](docs/API.md) for the surface an integrator implements.
 
@@ -135,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.3",
+  "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/__tests__/plateforme.test.js

@@ -0,0 +1,82 @@
+// LE GESTIONNAIRE NE DOIT DÉPENDRE D'AUCUNE PLATEFORME.
+//
+// Le README promet « Vercel, Next.js, Express, ou le serveur HTTP de Node — le même gestionnaire ».
+// C'était vrai à une convention près, jamais écrite : il lisait `req.query`, que les plateformes
+// serverless et Express remplissent, mais qu'un serveur HTTP nu laisse indéfini.
+//
+// ⚠️ ET LE SYMPTÔME ÉTAIT LE PIRE POSSIBLE. Sans paramètres, la requête cherchait un partage nommé
+// « rien » et rendait « Ce lien n'est plus valide ou a été révoqué ». Un intégrateur voyait un
+// REFUS là où il lui manquait un branchement — l'inversion exacte qu'on passe notre temps à
+// corriger. Signalé par un hôte qui montait le player sur http.createServer : chez lui, ça aurait
+// marché en production par chance, pas par construction.
+
+const player = require("../handler.js");
+
+function contexteMinimal() {
+  return {
+    plugins: {}, has: () => false,
+    storage: { isAllowedUrl: () => false, async fetchFile() { return null; }, async put() {} },
+    db: { async request() { return []; }, async selectAll() { return []; } },
+    mail: { async send() {} },
+    identity: { async verifyToken() { return null; }, roleOf: () => "", isAdmin: () => false, async canManageShares() { return false; } },
+    limits: { async allow() { return true; } },
+    branding: { async logo() { return ""; }, name: "", poweredBy: "", loaderName: "", async forKey() { return null; }, title: (b) => b },
+    errors: { async capture() {} },
+    legal: { sourceUrl: "", legalUrl: "", privacyUrl: "", trackingNotice: "" },
+    config: { supabaseUrl: "", supabasePublishableKey: "", mapsKey: "", extraFrameAncestors: [] },
+  };
+}
+
+async function appel(req) {
+  player.init(contexteMinimal());
+  const res = {
+    statusCode: 0, headers: {}, body: "",
+    setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
+    end(b) { this.body = String(b == null ? "" : b); },
+  };
+  await player.handler({ method: "GET", headers: {}, socket: {}, ...req }, res);
+  return res;
+}
+
+describe("d'où viennent les paramètres", () => {
+  // La convention serverless : la plateforme a déjà analysé l'URL.
+  it("utilise req.query quand la plateforme le fournit", async () => {
+    const res = await appel({ query: { contract: "1" } });
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).contract).toBe(1);
+  });
+
+  // ⚠️ Le cas qui produisait « lien révoqué ». Un serveur HTTP nu ne remplit pas req.query.
+  it("les retrouve dans req.url quand elle ne le fournit pas", async () => {
+    const res = await appel({ url: "/api/doc?contract=1" });
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).contract).toBe(1);
+  });
+
+  it("ne se laisse pas troubler par une URL absurde", async () => {
+    const res = await appel({ url: "pas une url du tout" });
+    expect(res.statusCode).toBe(400);
+  });
+});
+
+describe("quand rien n'est demandé", () => {
+  // ⚠️ LE POINT. Ni slug, ni présentation, ni aperçu : il n'y a rien à afficher, et ce n'est PAS
+  // un refus. Rendre la page de révocation envoyait l'intégrateur chercher un lien mort.
+  it("le dit, au lieu d'afficher « lien révoqué »", async () => {
+    const res = await appel({ query: {} });
+    expect(res.statusCode).toBe(400);
+    expect(res.body).toContain("Aucun document demandé");
+    expect(res.body).not.toContain("révoqué");
+  });
+
+  it("oriente vers la cause réelle : les paramètres de requête", async () => {
+    expect((await appel({ query: {} })).body).toMatch(/paramètres de requête/);
+  });
+
+  // Un slug inconnu, LUI, est bien un refus : la distinction doit rester nette dans les deux sens.
+  it("un slug inconnu reste un refus, pas une erreur de branchement", async () => {
+    const res = await appel({ query: { slug: "Inconnu-1234" } });
+    expect(res.statusCode).toBe(404);
+    expect(res.body).toContain("révoqué");
+  });
+});

package/server/handler.js

@@ -2113,9 +2113,34 @@ async function readJsonBody(req) {
   });
 }
 
+/**
+ * Paramètres de la requête, quelle que soit la plateforme.
+ *
+ * Le gestionnaire lit `req.query` — la convention des plateformes serverless (Vercel, Next.js) et
+ * d'Express. Un serveur HTTP nu ne la remplit pas : `req.query` est alors `undefined`, et TOUT
+ * paramètre disparaît.
+ *
+ * ⚠️ CE QUE ÇA DONNAIT, ET POURQUOI C'ÉTAIT LE PIRE DES SYMPTÔMES. Sans paramètres, la requête
+ * partait chercher un partage nommé « rien », n'en trouvait pas, et affichait « Ce lien n'est plus
+ * valide ou a été révoqué ». Un intégrateur voyait donc un REFUS là où il n'avait simplement pas
+ * branché la plateforme. C'est exactement l'inversion qu'on passe notre temps à corriger : une
+ * erreur de câblage ne doit jamais ressembler à une décision.
+ *
+ * Signalé par un hôte qui montait le player sur `http.createServer` : chez lui ça aurait marché en
+ * production (Vercel remplit `req.query`) — par chance, pas par construction.
+ */
+function parametres(req) {
+  if (req.query && typeof req.query === "object") return req.query;
+  try {
+    return Object.fromEntries(new URL(req.url || "/", "http://interne").searchParams);
+  } catch {
+    return {};
+  }
+}
+
 async function handler(req, res) {
   try {
-    const q = req.query || {};
+    const q = parametres(req);
     const slug = String(q.slug || "").trim();
 
     if (req.method === "POST") {
@@ -2496,6 +2521,17 @@ async function handler(req, res) {
       return;
     }
 
+    // AUCUN DOCUMENT DEMANDÉ. Ni slug, ni présentation, ni aperçu, ni carte d'identité — il n'y a
+    // rien à afficher, et ce n'est pas un refus. Le dire franchement évite qu'un intégrateur
+    // cherche un lien révoqué là où il lui manque un paramètre.
+    if (req.method === "GET" && !slug && !q.present && !q.preview && !q.contract) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Aucun document demandé. Attendu : ?slug=… , ?present=… , ?preview=1 ou ?contract=1.\n" +
+              "Si vous intégrez le player, vérifiez que la plateforme fournit les paramètres de requête.");
+      return;
+    }
+
     // ── CARTE D'IDENTITÉ (`?contract=1`) ─────────────────────────────────────────────────────
     // La règle 4 du contrat demande à l'hôte d'épingler la version qu'il vise et de le VÉRIFIER.
     // Sans point d'interrogation, cette règle était une intention : un hôte ne pouvait pas écrire
@@ -2678,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) {