discovery-media-player 0.1.6 → 0.1.7

package/README.md

@@ -14,9 +14,10 @@ and live presentation — for teams who would rather not hand their commercial d
 to a third-party SaaS.
 
 [![CI](https://github.com/Juli1artha/discovery-media-player/actions/workflows/ci.yml/badge.svg)](https://github.com/Juli1artha/discovery-media-player/actions/workflows/ci.yml)
-[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
-[![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)
+[![npm](https://img.shields.io/npm/v/discovery-media-player?logo=npm&color=cb3837)](https://www.npmjs.com/package/discovery-media-player)
+[![Container](https://img.shields.io/badge/ghcr.io-discovery--media--player-2496ed?logo=docker&logoColor=white)](https://github.com/Juli1artha/discovery-media-player/pkgs/container/discovery-media-player)
+[![Node](https://img.shields.io/node/v/discovery-media-player?logo=node.js&color=5fa04e)](package.json)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
 <br>
 
@@ -79,6 +80,21 @@ Two populations are never merged: a prospect reading your proposal and a colleag
 it in-house produce different records. Mixing them makes "this prospect read for 12 minutes"
 a lie, which is worse than having no number at all.
 
+### What it displays
+
+| Format | Status | What that means |
+|---|:---:|---|
+| **PDF** | ✅ | The format the player is built around. Rendered by pdf.js, progressive — the first page shows before the file has finished arriving. Per-page reading time, furthest page reached, page-level presenter sync. |
+| **Images** — `.png` `.jpg` `.jpeg` `.webp` `.gif` `.avif` | ✅ | Displayed, zoomable, tracked as a single page. Total reading time is real; there is no per-page breakdown because there are no pages. |
+| **Video** | ❌ | Not displayed. A document can *carry* a presenter video during a live presentation, but a video file is not something you can open as a document. |
+| **HTML** | ❌ | Deliberately. Displaying arbitrary HTML means executing someone's script in your instance's origin, next to sessions and analytics. The same reason `.svg` is refused. |
+| **Office** (`.docx`, `.pptx`, …) | ❌ | Convert to PDF before sending. Nothing in the player renders them, and pretending otherwise would show an empty page. |
+
+An unsupported file is never a security question either. A relayed file opens on the *player's*
+origin — the domain holding sessions and analytics — so anything a browser would **render** rather
+than download (SVG, HTML, XML) is served inert: generic type, forced download, `nosniff`. It stays
+retrievable; it cannot execute.
+
 ---
 
 ## How it fits your application

package/context/storage.js

@@ -120,9 +120,20 @@ function resolveLocal(candidate, root) {
   }
 }
 
+// ⚠️ PAS DE `.svg`, ET C'EST DÉLIBÉRÉ — deux raisons qui pointent dans le même sens.
+//
+// 1. SÉCURITÉ. Un SVG est un document exécutable : servi `image/svg+xml` en ligne, il s'ouvre sur
+//    L'ORIGINE DU PLAYER et son script s'exécute avec elle. La réponse de streaming ne porte pas
+//    de CSP — c'est un fichier, pas une page. Quiconque pourrait déposer un SVG dans une source
+//    autorisée obtiendrait donc du script sur le domaine qui sert les documents.
+// 2. COHÉRENCE. `isImageDocument()` ne reconnaît pas `.svg` : la visionneuse l'envoyait à pdf.js,
+//    qui rendait un écran blanc. Le format était donc servi sans être affichable — le pire des
+//    deux mondes.
+//
+// Les formats affichables sont ceux de la matrice du README : PDF et images bitmap.
 const TYPES = {
   ".pdf": "application/pdf", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
-  ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml", ".avif": "image/avif",
+  ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif",
 };
 
 /**

package/dist/bridge.d.ts

@@ -0,0 +1,48 @@
+/** Messages émis par le player vers l'application hôte. */
+export type PlayerMessage = {
+    type: "close";
+} | {
+    type: "share";
+} | {
+    type: "embed-ready";
+} | {
+    type: "embed-denied";
+    reason: string;
+} | {
+    type: "present-left";
+} | {
+    type: "present-denied";
+} | {
+    type: "present-invite";
+    slug: string;
+} | {
+    type: "present-handover";
+    slug: string;
+} | {
+    type: "present-switch";
+    slug: string;
+};
+/** Messages émis par l'application hôte vers le player. */
+export type HostMessage = {
+    type: "handover-done";
+};
+type WireMessage = {
+    type: string;
+    slug?: string;
+    reason?: string;
+};
+/** Forme transportée sur le fil (préfixée), pour un message typé. */
+export declare function toWire(msg: PlayerMessage | HostMessage): WireMessage;
+/** Côté HÔTE : lit un message reçu du player. `null` si ce n'en est pas un. */
+export declare function parsePlayerMessage(data: unknown): PlayerMessage | null;
+/** Côté PLAYER : lit un message reçu de l'hôte. `null` si ce n'en est pas un. */
+export declare function parseHostMessage(data: unknown): HostMessage | null;
+/** Côté PLAYER : envoie un message à l'application hôte. */
+export declare function sendToHost(msg: PlayerMessage, target?: Window | null): void;
+/** Côté HÔTE : envoie un message au player. */
+export declare function sendToPlayer(frame: HTMLIFrameElement | null | undefined, msg: HostMessage): void;
+/** Côté HÔTE : écoute les messages du player. Renvoie la fonction de désabonnement. */
+export declare function onPlayerMessage(cb: (msg: PlayerMessage) => void, win?: Window): () => void;
+/** Côté PLAYER : écoute les messages de l'hôte. Renvoie la fonction de désabonnement. */
+export declare function onHostMessage(cb: (msg: HostMessage) => void, win?: Window): () => void;
+export {};

package/dist/bridge.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MIT
+//
+// ⚠️ CE FICHIER EST SOUS MIT, pas AGPL — délibérément, et c'est le seul.
+// C'est le contrat que l'application hôte doit importer pour parler au player. Le placer sous la
+// licence du cœur obligerait un hôte à ouvrir son propre code pour avoir le droit d'échanger dix
+// messages avec une iframe : la licence deviendrait un péage à l'intégration, ce qui n'est pas ce
+// qu'on protège. On protège le player, pas ceux qui s'y branchent.
+// Contrat postMessage entre le PLAYER (iframe) et l'APPLICATION HÔTE qui l'affiche.
+//
+// Le player vit dans une iframe : il possède le document, la barre d'outils et la présentation,
+// mais tout ce qui exige le jeton de session de l'hôte (inviter l'équipe, passer la main, ouvrir
+// la modale de partage) doit remonter à l'application. Ce fichier est le SEUL endroit où le
+// format de ces messages est décrit — les deux côtés l'importent.
+//
+// Il était auparavant écrit à la main des deux côtés : dix types de messages dupliqués, non
+// typés, validés par des `String(d.slug || "")` sans borne. Deux bugs en sont venus (validation
+// d'origine trop stricte qui bloquait la réception en production ; fermeture du viewer avant le
+// retrait de présence, qui laissait un participant fantôme).
+//
+// VALIDATION PAR TYPE, PAS PAR ORIGINE — délibéré. Un contrôle strict de `e.origin` bloquait la
+// réception en production (l'iframe et l'app ne partagent pas toujours la même origine perçue).
+// Les actions transportées sont inoffensives : elles ouvrent une modale ou ferment une vue, et
+// tout ce qui touche aux données est revérifié côté serveur avec le JWT. Le `slug` est en
+// revanche borné ici (charset + longueur) : c'est la seule donnée qui traverse la frontière.
+/** Préfixe historique des messages sur le fil. Neutralisable d'un seul endroit le jour de l'ouverture. */
+const WIRE_PREFIX = "3dd-doc-";
+/** Slugs de partage et de présentation : `randomBytes(9).toString("base64url")` → 12 caractères. */
+const SLUG_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const PLAYER_PLAIN = ["close", "share", "embed-ready", "present-left", "present-denied"];
+const PLAYER_WITH_REASON = ["embed-denied"];
+const PLAYER_WITH_SLUG = ["present-invite", "present-handover", "present-switch"];
+const HOST_PLAIN = ["handover-done"];
+/** Forme transportée sur le fil (préfixée), pour un message typé. */
+export function toWire(msg) {
+    const wire = { type: WIRE_PREFIX + msg.type };
+    if ("slug" in msg && msg.slug)
+        wire.slug = msg.slug;
+    if ("reason" in msg && msg.reason)
+        wire.reason = String(msg.reason).slice(0, 40);
+    return wire;
+}
+function parse(data, plain, withSlug) {
+    if (!data || typeof data !== "object")
+        return null;
+    const raw = data.type;
+    if (typeof raw !== "string" || !raw.startsWith(WIRE_PREFIX))
+        return null;
+    const type = raw.slice(WIRE_PREFIX.length);
+    if (plain.includes(type))
+        return { type };
+    if (PLAYER_WITH_REASON.includes(type)) {
+        const reason = data.reason;
+        // Motif borné et sans surprise : il traverse une frontière et finit parfois à l'écran.
+        return { type, reason: /^[a-z-]{1,40}$/.test(String(reason || "")) ? String(reason) : "unknown" };
+    }
+    if (!withSlug.includes(type))
+        return null;
+    const slug = data.slug;
+    // Un message à slug SANS slug valide est rejeté : mieux vaut ne rien ouvrir qu'ouvrir sur du vide.
+    if (typeof slug !== "string" || !SLUG_RE.test(slug))
+        return null;
+    return { type, slug };
+}
+/** Côté HÔTE : lit un message reçu du player. `null` si ce n'en est pas un. */
+export function parsePlayerMessage(data) {
+    return parse(data, PLAYER_PLAIN, PLAYER_WITH_SLUG);
+}
+/** Côté PLAYER : lit un message reçu de l'hôte. `null` si ce n'en est pas un. */
+export function parseHostMessage(data) {
+    return parse(data, HOST_PLAIN, []);
+}
+// ── Runtime ────────────────────────────────────────────────────────────────────────────────────
+// Tout est en `try` : un player qui ne parvient pas à parler à son hôte doit continuer à afficher
+// le document. Perdre le bouton « Partager » est ennuyeux, perdre le document est inacceptable.
+/** Côté PLAYER : envoie un message à l'application hôte. */
+export function sendToHost(msg, target) {
+    try {
+        const win = target || (typeof window !== "undefined" ? window.parent : null);
+        if (win)
+            win.postMessage(toWire(msg), "*");
+    }
+    catch { /* l'hôte est peut-être absent (page publique) : sans effet */ }
+}
+/** Côté HÔTE : envoie un message au player. */
+export function sendToPlayer(frame, msg) {
+    try {
+        frame?.contentWindow?.postMessage(toWire(msg), "*");
+    }
+    catch { /* iframe déjà détruite */ }
+}
+/** Côté HÔTE : écoute les messages du player. Renvoie la fonction de désabonnement. */
+export function onPlayerMessage(cb, win) {
+    const target = win || (typeof window !== "undefined" ? window : null);
+    if (!target)
+        return () => { };
+    const handler = (e) => {
+        const msg = parsePlayerMessage(e.data);
+        if (msg)
+            cb(msg);
+    };
+    target.addEventListener("message", handler);
+    return () => target.removeEventListener("message", handler);
+}
+/** Côté PLAYER : écoute les messages de l'hôte. Renvoie la fonction de désabonnement. */
+export function onHostMessage(cb, win) {
+    const target = win || (typeof window !== "undefined" ? window : null);
+    if (!target)
+        return () => { };
+    const handler = (e) => {
+        const msg = parseHostMessage(e.data);
+        if (msg)
+            cb(msg);
+    };
+    target.addEventListener("message", handler);
+    return () => target.removeEventListener("message", handler);
+}

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/docs/HOST-CONTRACT.md

@@ -0,0 +1,150 @@
+# Host contract
+
+What a host application may call, what it must implement, and what will not change without a
+version bump. If you are integrating the player, this page and [`API.md`](API.md) are the two you
+need.
+
+## Five rules
+
+1. **One source of truth.** Fix the player in the player's repository, never in a host — not even
+   in a host that once contained it. A fix written host-side is a copy, and copies drift.
+2. **Additive by default.** Adding an action, a parameter or a field breaks nobody. **Removing or
+   renaming is a break** → a new contract number, both served during the migration.
+3. **Deploy order: the player ships before its hosts.** The reverse makes a feature disappear
+   everywhere at once, with no error anywhere.
+4. **Pin the version you target, and test it.** `GET /api/doc?contract=1` answers without a
+   session, without a database and without cache — it must answer when nothing else does.
+5. **Anyone may propose, the maintainer releases.** Open an issue or a pull request here; you have
+   the context and often the fix. Releasing stays with the maintainer because publishing a version
+   decides deploy order. A local workaround is fine when you are blocked, on two conditions: report
+   it the same day, and remove it when the release lands.
+
+## Identity card
+
+```json
+{
+  "product": "discovery-media-player",
+  "contract": 1,
+  "version": "0.1.7",
+  "capabilities": ["docshare", "presentations", "embed-denied", "host-fetch", "brand-reference"],
+  "frameAncestors": ["'self'", "https://*.vercel.app", "https://app.example.com"],
+  "plugins": { "bot": false, "visitors": false, "brandIntro": false, "botBrowser": false, "providerQuotas": false }
+}
+```
+
+**Pin `contract`**, not `version`: it moves only on a break. Test `capabilities` by **presence**,
+never by order. `plugins` lets you refuse to start when you depend on an optional module this
+instance does not have.
+
+⚠️ **`frameAncestors` matters more than it looks.** A host that is not listed will never see the
+viewer: the browser blocks the iframe **before any script runs**, so no message can be emitted and
+the host sees a silence indistinguishable from an unreachable instance. Check that your domain is
+there before you open a document.
+
+## The three things a host implements
+
+Everything the player borrows arrives through one injected object. Two of its entries carry
+decisions the player deliberately refuses to make, and both can be answered over HTTP — most hosts
+therefore write **no wiring code at all**, only environment variables.
+
+### 1. Who may manage tracked links
+
+```
+POST  →  { "email": "…", "role": "…", "action": "create|list|list.all|revoke|setauth|overview|sessions|test" }
+      ←  { "allowed": true }
+```
+
+- **The player verifies the token; you decide the rights.** No answer, or a failing rule, means
+  refusal. A right that cannot be granted is not granted.
+- **`email` is the authoritative identity.** `role` is what the session token carried; a host whose
+  roles live in its own database ignores it and looks them up. That is expected.
+- **Only `allowed` is read, and it must be a boolean.** Any other shape means refused.
+- The token is already verified before the call: your route does not receive it and must not
+  re-verify it.
+
+### 2. What a client's brand is
+
+```
+POST  →  { "key": "…" }
+      ←  { "logo": "https://…", "name": "…", "dark": false }    or {} / null when unknown
+```
+
+The link carries a **reference**, never a copy of the logo: a tracked link lives for weeks in an
+inbox, and a logo frozen at send time would not follow a corrected brand. `name` is not decorative
+— it is what shows when the logo fails to load.
+
+### 3. Serving a file the player cannot reach
+
+If your documents sit behind an API key, the player must **never** hold it. Expose one route
+(`PLAYER_HOST_FETCH_BASE`), fetch the file yourself, and the player is allowed to call only that.
+Four requirements, in order of what they cost when missed:
+
+1. **Never relay the upstream `Content-Length`.** `fetch()` decompresses the body and keeps the
+   upstream headers; relaying the announced size serves a **truncated PDF**, with no error
+   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.
+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.
+4. ⚠️ **Never sign a path supplied by the client.** The first three are about transport; this one
+   is about what you transport, and it is the only one whose omission does not degrade the
+   experience but **opens your data**.
+
+   Your route serves with *your* credentials — the player has no session to present, by design.
+   An action that signs a client-supplied path becomes an oracle: a user signs a path their own
+   rights would refuse, and the player reads it back with yours. The anti-SSRF guard sees nothing:
+   the origin is legitimate, it is yours.
+
+   The shape that holds: the caller supplies a **source from a closed set and a row identifier,
+   never a path**. You re-read the path with the caller's session and your own row-level rules
+   decide. **Corollary:** when the reference itself carries a capability, signing is not enough —
+   it must be encrypted. *Signed* means nobody can forge it; it has never meant nobody can read it.
+
+## The postMessage bridge
+
+Described once in [`src/bridge.ts`](../src/bridge.ts) and published as `discovery-media-player/bridge`
+— **compiled JavaScript with type declarations, under MIT** rather than the core's AGPL, so that
+importing it is not a toll. Import it rather than copying constants: a message name retyped by hand
+is a contract in two copies, and the day it changes only one of them knows.
+
+**player → host:** `close` · `share` · `embed-ready` · `embed-denied {reason}` · `present-left` ·
+`present-denied` · `present-invite {slug}` · `present-handover {slug}` · `present-switch {slug}`
+
+**host → player:** `handover-done`
+
+### Refusals
+
+A host waiting for `embed-ready` is tempted to treat silence as a timeout and fall back to the
+browser's own viewer. **That is a security hole**: silence covers two opposite cases — the player is
+absent, or the player *refuses*. Falling back in the second case opens the document the player just
+closed.
+
+| `reason` | What happened | Host behaviour |
+|---|---|---|
+| `revoked` | unknown or revoked link | do not open |
+| `auth-required` | restricted document, visitor not signed in | do not open — the wall stays up |
+| `auth-unavailable` | restricted document, access wall missing from this instance | do not open |
+| `ended` | presentation over or unknown | do not open |
+| `url-not-allowed` | the file URL is not covered by the guard | **open**, and report the configuration |
+
+The rule underneath, safer than the list: **never fall back on a refusal of *access*; you may fall
+back on an inability to *reach*.** And "do not fall back" applies to what you **offer** — an
+"Open ↗" button left in place is falling back one second later.
+
+## Two things that will bite
+
+**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
+you expect to see.
+
+**Configured is not served.** When a diagnosis is disputed, the useful question is not who is right
+but *did you measure exactly what fails*. Two true statements about the same instance can describe
+different responses.
+
+## Versioning
+
+Semantic versioning on the package, independent of the `contract` number. Pin an **exact** version:
+the player and its hosts deploy separately, and a range brings in a version nobody decided to
+deploy, on a day someone ran `npm install` for another reason.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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",
@@ -29,13 +29,14 @@
   "files": [
     "bin",
     "context",
+    "dist",
     "server",
-    "src",
     "supabase",
     "README.md",
-    "CONTRAT.md",
     "LICENSE",
-    "LICENSE-MIT"
+    "LICENSE-MIT",
+    "docs/HOST-CONTRACT.md",
+    "!**/__tests__"
   ],
   "exports": {
     ".": "./server/handler.js",
@@ -44,12 +45,16 @@
     "./brands": "./server/brands.js",
     "./context/standalone": "./context/standalone.js",
     "./context/storage": "./context/storage.js",
-    "./bridge": "./src/bridge.ts",
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "import": "./dist/bridge.js",
+      "default": "./dist/bridge.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
     "start": "node bin/serve.js",
-    "build": "node build/bundle.mjs",
+    "build": "node build/bundle.mjs && tsc -p tsconfig.build.json && node -e \"import('./build/bundle.mjs').then(m=>m.marquerDistEsm())\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint bin context server src build",
@@ -58,7 +63,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/server/handler.js

@@ -1098,6 +1098,24 @@ function botMarkup(share, pitch) {
  * ⚠️ Et un 206 compressé est irrécupérable : les bornes portent sur les octets compressés, un
  * fragment gzip ne se décompresse pas seul. On refuse bruyamment plutôt que de servir du faux.
  */
+
+// ⚠️ CE QU'ON RELAIE S'OUVRE SUR NOTRE ORIGINE.
+//
+// Un fichier relayé sort du domaine qui sert les documents — donc avec ses cookies, son
+// `localStorage` et ses jetons de présentation. Relayer un `Content-Type` exécutable revient à
+// héberger le script de quelqu'un d'autre chez soi : un SVG déposé dans une source autorisée
+// (bucket public, route de l'hôte) s'ouvre `image/svg+xml`, et son `<script>` s'exécute avec
+// notre origine. La réponse de streaming ne porte aucune CSP — c'est un fichier, pas une page.
+//
+// Retirer `.svg` de la table des types locaux (côté `context/storage.js`) ne réglait que la
+// moitié du sujet : l'amont distant annonce le type qu'il veut, et on le recopiait.
+//
+// On ne REFUSE pas pour autant : le fichier existe, quelqu'un a le droit de le récupérer, et un
+// 502 sur une pièce jointe légitime serait une panne. On le rend simplement **inerte** — type
+// générique et téléchargement forcé. Il n'était de toute façon pas affichable (la matrice des
+// formats du README ne connaît que le PDF et les images bitmap).
+const TYPES_EXECUTABLES = /^(image\/svg|text\/html|application\/xhtml|application\/xml|text\/xml)/i;
+
 async function relayerFichier(res, r, disposition) {
   if (!r) { res.statusCode = 404; res.end("Fichier indisponible"); return; }
   if (!r.ok && r.status !== 206) { res.statusCode = 502; res.end("Fichier indisponible"); return; }
@@ -1107,7 +1125,16 @@ async function relayerFichier(res, r, disposition) {
 
   const buf = Buffer.from(await r.arrayBuffer());
   res.statusCode = r.status;
-  res.setHeader("Content-Type", r.headers.get("content-type") || "application/pdf");
+  const typeAmont = r.headers.get("content-type") || "application/pdf";
+  const executable = TYPES_EXECUTABLES.test(typeAmont);
+  res.setHeader("Content-Type", executable ? "application/octet-stream" : typeAmont);
+  // ⚠️ On ÉCRASE la disposition, on ne la complète pas : les chemins de streaming passent
+  // `inline; filename=…` pour que la visionneuse affiche le document. Sur un type exécutable,
+  // `inline` est précisément ce qu'il ne faut pas — et un `|| "attachment"` n'aurait jamais servi.
+  if (executable) disposition = "attachment";
+  // `nosniff` : sans lui, un `text/plain` contenant du HTML peut être requalifié par le
+  // navigateur — la garde ci-dessus porterait alors sur un type qui n'est pas celui qui s'ouvre.
+  res.setHeader("X-Content-Type-Options", "nosniff");
   res.setHeader("Accept-Ranges", "bytes");
   // Les bornes d'un `Content-Range` ne valent que si l'amont n'a pas compressé.
   const cr = !compresse && r.headers.get("content-range");