discovery-media-player 0.1.124 → 0.1.125

package/context/standalone.js

@@ -633,7 +633,15 @@ function createStandaloneContext(env = process.env) {
        *
        * ⚠️ Sert à fabriquer les liens qui partent par email. L'en-tête `Host` ne convient pas :
        * il est choisi par le client, donc un lecteur pouvait faire envoyer un message signé de
-       * l'hôte dont le bouton pointe ailleurs. Vide ⇒ repli sur `Host`, mais signalé.
+       * l'hôte dont le bouton pointe ailleurs.
+       *
+       * ⚠️ VIDE ⇒ RIEN NE PART. Ce commentaire a annoncé « repli sur `Host`, mais signalé »
+       * pendant tout le temps où le code refusait déjà l'envoi (`public-url-unconfigured`,
+       * routes-liens.js) — la 0.1.21 posait ce repli, la seconde passe d'audit l'a fermé, et
+       * trois textes sur quatre ont continué à le promettre (troisième audit externe, 21/08).
+       * Ce getter rend "" ; son unique consommateur retient le courrier, journalise le motif,
+       * et crée quand même le lien. Un commentaire qui décrit un comportement retiré est pire
+       * qu'une absence de commentaire : il fait renoncer à vérifier.
        */
       get publicUrl() {
         const v = sansBarreFinale(env.PLAYER_PUBLIC_URL).trim();

package/context/storage.js

@@ -191,6 +191,20 @@ async function lireDepuis(fh, stat, cible, range) {
     return reponse(413, {}, Buffer.alloc(0));
   }
 
+  // ⚠️ UN FICHIER VIDE N'A PAS DE PLAGE À DIFFUSER — et c'est une régression que le passage au flux
+  // a introduite. Avec `total === 0`, la borne haute vaut `total - 1`, soit -1 : `createReadStream`
+  // reçoit alors `{ start: 0, end: -1 }` et meurt en `TypeError` à la fermeture du descripteur.
+  // Le tampon d'avant tolérait `Buffer.alloc(0)` sans rien dire ; le flux, non.
+  //
+  // Un PDF de zéro octet est évidemment invalide — mais il doit produire une RÉPONSE, pas une
+  // exception serveur : c'est le lecteur qui décidera qu'il n'y a rien à afficher, et un 500 lui
+  // dirait « notre faute » au lieu de « ce fichier est vide ». Le cas AVEC `Range` est déjà traité
+  // plus haut : `debut < total` est faux, donc 416. (Relevé par un audit externe.)
+  if (total === 0) {
+    await fh.close().catch(() => {});
+    return reponse(200, { "content-type": type, "content-length": "0" }, Buffer.alloc(0));
+  }
+
   // ⚠️ ON DIFFUSE, ON N'ALLOUE PLUS — et le plafond ne suffisait pas à rendre l'allocation sûre.
   //
   // `Buffer.alloc(fin - debut + 1)` réservait la plage DEMANDÉE en une fois : jusqu'à 60 Mio par

package/docs/README.md

@@ -19,6 +19,14 @@ no document assumes you have read the others.
 | [`MIGRATIONS.md`](MIGRATIONS.md) | What happens to a database **already in service** when the player expects a newer schema. (French.) |
 | [`RETENTION.md`](RETENTION.md) | The declared perimeter of data retention: every personal-data column has a written policy, and CI enforces that the list is complete. Also an export of the package: `require.resolve("discovery-media-player/retention")`. (French.) |
 
+## You are contributing, or publishing a version
+
+| Document | What it gives you |
+|---|---|
+| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | how to run the benches, what review looks for, and the one rule: a behaviour worth keeping is worth a test that fails without it. |
+| [`../AGENTS.md`](../AGENTS.md) | the conventions that are not obvious from the file tree — which ones a guard enforces, and which ones only review does. |
+| [`RELEASING.md`](RELEASING.md) | the release train, freezing the candidate SHA, the read-only preflight to run **before** the tag, and what to do when a tag lands on the wrong commit. |
+
 ## You are evaluating the project
 
 The external audit trail is public, unedited, and kept in the state it was received —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.124",
+  "version": "0.1.125",
   "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",
@@ -32,6 +32,7 @@
     "dist",
     "server",
     "supabase",
+    "types",
     "README.md",
     "LICENSE",
     "LICENSE-MIT",
@@ -40,13 +41,19 @@
     "!**/__tests__"
   ],
   "exports": {
-    ".": "./server/handler.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./server/handler.js"
+    },
     "./shares": "./server/shares.js",
     "./presentations": "./server/presentations.js",
     "./brands": "./server/brands.js",
     "./contrat": "./docs/HOST-CONTRACT.md",
     "./retention": "./docs/RETENTION.md",
-    "./context/standalone": "./context/standalone.js",
+    "./context/standalone": {
+      "types": "./types/standalone.d.ts",
+      "default": "./context/standalone.js"
+    },
     "./context/storage": "./context/storage.js",
     "./bridge": {
       "types": "./dist/bridge.d.ts",
@@ -67,7 +74,8 @@
     "prepublishOnly": "npm run build && npm test",
     "test:e2e": "node -e \"require('fs').existsSync('vitest.e2e.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.e2e.config.mjs",
     "test:base": "node -e \"require('fs').existsSync('vitest.base.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.base.config.mjs",
-    "test:charge": "node -e \"require('fs').existsSync('vitest.charge.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.charge.config.mjs"
+    "test:charge": "node -e \"require('fs').existsSync('vitest.charge.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.charge.config.mjs",
+    "test:campagne": "node -e \"require('fs').existsSync('vitest.campagne.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.campagne.config.mjs"
   },
   "engines": {
     "node": ">=22"

package/types/context.d.ts

@@ -0,0 +1,154 @@
+/**
+ * CE QU'UNE APPLICATION HÔTE FOURNIT AU PLAYER.
+ *
+ * ⚠️ Le cœur ne sait rien de l'application qui l'héberge : tout ce qu'il emprunte — stockage,
+ * base, identité, limites, marque, journalisation — arrive par cet objet, injecté une fois via
+ * `init(context)`. C'est la seule frontière, et ces types la DÉCRIVENT ; ils ne la déplacent pas.
+ *
+ * ⚠️ LA RÉFÉRENCE RESTE `docs/HOST-CONTRACT.md`. Ce fichier est une aide de frappe, pas le
+ * contrat : quand les deux divergent, le contrat gagne — et c'est ce fichier qu'il faut corriger.
+ * Les champs marqués optionnels le sont RÉELLEMENT : leur absence ferme une fonction en le
+ * disant, elle ne casse pas l'instance.
+ */
+
+/** Une requête HTTP entrante, telle que le player en a besoin. Volontairement minimale :
+ *  le player lit `req.query` quand la plateforme le fournit, et retombe sur `req.url` sinon —
+ *  un `http.createServer` nu marche donc sans adaptateur. */
+export interface RequeteEntrante {
+  url?: string;
+  method?: string;
+  headers: Record<string, string | string[] | undefined>;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  socket?: { remoteAddress?: string };
+  on?(evenement: string, ecouteur: (...args: never[]) => void): unknown;
+}
+
+/** La réponse, côté Node. Le player écrit le statut, les en-têtes, puis le corps. */
+export interface ReponseSortante {
+  statusCode: number;
+  setHeader(nom: string, valeur: string | number | readonly string[]): unknown;
+  end(corps?: unknown): unknown;
+  write?(morceau: unknown): unknown;
+  writableEnded?: boolean;
+}
+
+export interface Plage { start: number; end?: number }
+
+/** Un flux lisible, décrit STRUCTURELLEMENT : ce paquet ne dépend pas de `@types/node`, et
+ *  exiger cette dépendance d'un consommateur pour lire un type serait une taxe déguisée. */
+export interface FluxLisible {
+  pipe?(destination: unknown): unknown;
+  on?(evenement: string, ecouteur: (...args: never[]) => void): unknown;
+  [Symbol.asyncIterator]?(): AsyncIterator<unknown>;
+}
+
+export interface FichierRelaye {
+  body: FluxLisible | Uint8Array | null;
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+export interface Stockage {
+  /** Refus par défaut : ce qui n'est pas explicitement permis ne se relaie pas. */
+  isAllowedUrl(url: string): boolean;
+  fetchFile(url: string, options?: { range?: Plage }): Promise<FichierRelaye | null>;
+  put(seau: string, chemin: string, contenu: Uint8Array, type: string): Promise<boolean>;
+  /** Optionnel : sans lui, les pièces jointes du chat sont refusées — et le player le dit.
+   *  Le cœur ne doit jamais détenir la clé qui signe. */
+  signUpload?(seau: string, chemin: string): Promise<{ token: string; publicUrl: string } | null>;
+}
+
+export interface BaseDeDonnees {
+  /** Forme PostgREST : `table?colonne=eq.valeur`. Volontairement sans jointure imbriquée ni
+   *  arbre booléen — c'est ce qui garde un portage à la traduction plutôt qu'à la réécriture. */
+  request(chemin: string, options?: { method?: string; body?: unknown; headers?: Record<string, string> }): Promise<unknown>;
+  selectAll(chemin: string): Promise<unknown[]>;
+}
+
+export interface Identite {
+  verifyToken(entete: string | undefined): Promise<unknown | null>;
+  roleOf(utilisateur: unknown): Promise<string | null> | string | null;
+  isAdmin(utilisateur: unknown): Promise<boolean> | boolean;
+  /**
+   * Le player vérifie le jeton ; VOUS décidez des droits. Pas de réponse, ou une règle qui
+   * échoue, valent refus. L'action est passée parce que les hôtes séparent l'envoi ordinaire
+   * de l'administration.
+   */
+  canManageShares(utilisateur: unknown, action: string): Promise<boolean> | boolean;
+  /** Optionnel : autorise VOTRE serveur à créer un lien en son nom propre. Absent ⇒ ce chemin
+   *  n'existe pas. Le cœur ne voit jamais le secret : il demande, vous répondez. */
+  isTrustedHostCall?(entetes: Record<string, string | string[] | undefined>): Promise<boolean> | boolean;
+}
+
+export interface MarqueResolue { logo: string; name: string; dark?: boolean }
+
+export interface Marque {
+  name: string;
+  poweredBy: string;
+  loaderName: string;
+  logo(): Promise<string> | string;
+  /** `name` est le repli quand le logo ne charge pas — le champ le plus oublié, et le seul
+   *  qui aide quand tout le reste échoue. */
+  forKey(cle: string): Promise<MarqueResolue | null>;
+  title(base: string, qualificatif?: string): string;
+}
+
+export interface Limites {
+  /** ⚠️ Fail-open : un limiteur en panne ne doit pas tuer un lecteur. */
+  allow(cle: string, max: number, fenetreSecondes: number): Promise<boolean>;
+}
+
+export interface Courriel {
+  to: string;
+  subject: string;
+  html?: string;
+  text?: string;
+  [autre: string]: unknown;
+}
+
+export interface Mentions {
+  sourceUrl: string;
+  legalUrl: string;
+  privacyUrl: string;
+  trackingNotice: string;
+  /** Optionnel : la mention d'un lien que PERSONNE n'a envoyé. Absente ⇒ repli sur la première,
+   *  plutôt que de n'en afficher aucune. */
+  trackingNoticeAnonymous?: string;
+  /** ⚠️ Vide ⇒ AUCUN courriel ne part : la route répond `sendRefused: "public-url-unconfigured"`
+   *  et journalise. L'en-tête `Host` ne convient pas — le client le choisit. */
+  publicUrl?: string;
+}
+
+export interface Reglages {
+  /** Consommé tel quel, SANS barre finale : le cœur ne renormalise plus. */
+  supabaseUrl: string;
+  supabasePublishableKey: string;
+  mapsKey: string;
+  extraFrameAncestors: string[];
+  /** Ce qui est POSÉ, à côté de ce que le code SAIT faire : la carte d'identité publie les deux,
+   *  parce qu'une capacité disponible mais non configurée se comporte comme une absence. */
+  separateIssuer?: boolean;
+  hostShare?: boolean;
+  hostMail?: boolean;
+  retentionSweep?: boolean;
+  hostAuthStorageKey?: string;
+  [autre: string]: unknown;
+}
+
+export interface ContextePlayer {
+  storage: Stockage;
+  db: BaseDeDonnees;
+  identity: Identite;
+  branding: Marque;
+  limits: Limites;
+  legal: Mentions;
+  config: Reglages;
+  errors: { capture(erreur: unknown, meta?: Record<string, unknown>): unknown };
+  mail: { send(message: Courriel): Promise<{ sent: true } | null> };
+  /** Greffons appartenant à l'hôte. Le cœur affiche, trace et présente sans aucun — c'est testé. */
+  plugins: Record<string, unknown>;
+  /** Dit si un greffon est présent, sans le charger. */
+  has(nom: string): boolean;
+  schema?: unknown;
+}

package/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `discovery-media-player` — le point d'entrée.
+ *
+ * Le player est un GESTIONNAIRE DE REQUÊTES, pas un cadriciel : vous le montez où vous voulez,
+ * les chemins sont les vôtres. Tout ce qu'il emprunte arrive par `init(context)`.
+ *
+ *     const player = require("discovery-media-player");
+ *     const { createStandaloneContext } = require("discovery-media-player/context/standalone");
+ *     player.init(createStandaloneContext(process.env));
+ *     app.use("/api/doc", (req, res) => player.handler(req, res));
+ */
+
+import type { ContextePlayer, RequeteEntrante, ReponseSortante } from "./context.js";
+
+export type { ContextePlayer, RequeteEntrante, ReponseSortante };
+export * from "./context.js";
+
+/**
+ * Injecte le contexte. À appeler UNE FOIS, avant la première requête.
+ *
+ * ⚠️ Le cœur garde ce contexte dans un état de module : deux instances chargées dans le même
+ * processus partagent donc ce qu'on leur injecte. Une fabrique multi-instances est un chantier
+ * ouvert ; jusque-là, une instance par processus.
+ */
+export function init(contexte: ContextePlayer): void;
+
+/**
+ * Sert une requête. Lit `req.query` quand la plateforme le fournit (serverless, Express) et
+ * retombe sur `req.url` sinon — un `http.createServer` nu marche sans adaptateur.
+ */
+export function handler(requete: RequeteEntrante, reponse: ReponseSortante): Promise<void>;
+
+/** Un script tiers épinglé : version exacte dans l'URL, empreinte SRI à côté. */
+export interface Tiers { url: string; sri: string }
+
+/**
+ * ⚠️ EXPORTÉ POUR ÊTRE CONFRONTÉ, PAS POUR ÊTRE UTILISÉ. Le banc navigateur et la garde de forge
+ * partent de cet inventaire pour vérifier qu'aucune URL de script du gabarit ne lui échappe.
+ * Un hôte n'a rien à en faire — s'il en dépend, c'est le signe d'un manque ailleurs.
+ */
+export const TIERS: Record<string, Tiers>;

package/types/standalone.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `discovery-media-player/context/standalone` — un contexte complet, construit depuis
+ * l'environnement.
+ *
+ * C'est le chemin le plus court vers une instance qui marche : un dossier de documents, et rien
+ * d'autre. Chaque réglage est une variable d'environnement, décrite dans `docs/CONFIGURATION.md`
+ * — il n'y a pas de fichier de configuration, exprès : une instance est décrite entièrement par
+ * son environnement.
+ */
+
+import type { ContextePlayer, BaseDeDonnees, Limites } from "./context.js";
+
+/**
+ * Construit le contexte. `env` vaut `process.env` par défaut ; le passer explicitement permet
+ * de servir deux marques depuis un même processus, ou d'éprouver une configuration sans la poser.
+ *
+ * ⚠️ Ce qui n'est pas configuré est FERMÉ, pas deviné : sans base, les liens tracés n'existent
+ * pas ; sans `PLAYER_PUBLIC_URL`, aucun courriel ne part. Un refus nommé vaut mieux qu'un repli
+ * silencieux.
+ */
+export function createStandaloneContext(env?: Record<string, string | undefined>): ContextePlayer;
+
+/**
+ * Le limiteur de débit du contexte autonome, exposé pour qui compose son propre contexte.
+ *
+ * ⚠️ Fail-open, délibérément : un limiteur en panne ne doit pas empêcher un lecteur d'ouvrir son
+ * document. Il protège d'un abus, il ne garde pas une porte.
+ */
+export function creerLimites(db: BaseDeDonnees, journal: { capture(erreur: unknown, meta?: Record<string, unknown>): unknown }): Limites;