@mostajs/pdf-sign 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog — @mostajs/pdf-sign
 
+## 0.4.1 — 29/09/2026
+
+**pyhanko 0.37 taisait le diagnostic « identifiants refusés » — et rien ne fixait les versions.**
+
+### Corrigé
+
+pyhanko 0.37 a remplacé son client HTTP (`requests` → `aiohttp`). Son API n'a pas changé, mais le
+code d'erreur HTTP a changé de place : il est porté par l'exception (`.status`) et non plus par la
+réponse passée en argument (`.status_code`). Sous 0.37, la 0.4.0 présentait donc un 401 comme
+« Error while contacting timestamp service » — ce qui envoie chercher un problème réseau. Les deux
+emplacements sont désormais lus. La suite complète passe sous pyhanko **0.35.1 et 0.37.0**.
+
+### Corrigé — la VÉRIFICATION, qu'aucun essai ne gardait
+
+Relevé en vérifiant que l'adaptation à 0.37 n'avait rien cassé d'autre : `verifyPdf` n'était
+essayé qu'avec le moteur Node. Le chemin pyhanko cachait deux défauts, **identiques sous 0.35 et
+0.37** — donc antérieurs à la montée de version :
+
+1. **Repli silencieux.** Tout échec de pyhanko (document verrouillé, plantage, API changée)
+   retombait sur la détection Node, qui rend `intact` et `valid` **indéfinis** — et un affichage
+   qui lit « pas false » y voit « valide ». Désormais : si pyhanko est présent, son échec est une
+   **erreur** qui nomme la cause ; `engine:"pyhanko"` sans pyhanko est une erreur. Le repli Node ne
+   vaut plus que si pyhanko **manque**.
+2. **Mauvais mot de passe pris pour le bon.** `decrypt()` ne lève pas : il rend un statut `FAILED`.
+   La boucle attendait une exception, et tenait le document pour ouvert au premier essai. Le
+   statut est désormais lu ; un document verrouillé vérifié sans son mot de passe donne
+   « document verrouillé : son mot de passe d'ouverture est requis ».
+
+`test-scripts/test-verification-pyhanko.ts` — 7 essais (T-VER-1 à 7) : intact / altéré /
+horodaté / verrouillé sans et avec mot de passe / fichier illisible / cachet avec image. Suite
+complète : **30 essais, 0 sauté, sous pyhanko 0.35.1 ET 0.37.0**.
+
+⚠️ `valid` seul ne suffit pas : sur un document altéré, pyhanko rend `valid: true` (la signature
+est mathématiquement bonne) et `intact: false` (elle ne couvre plus ce document). Lire les deux.
+
+### Relecture de l'adaptation 0.37
+
+La lecture de `.status` est restreinte aux exceptions d'`aiohttp` : ailleurs, un attribut du même
+nom pourrait ne pas être un code HTTP. Le diagnostic ne peut, par construction, que **changer le
+message** d'un échec — jamais transformer un échec en succès. Contre-épreuve : sans cette lecture,
+T-TSA-4 et T-TSA-8 échouent sous 0.37.
+
+### Ajouté — les versions Python sont FIXÉES
+
+- `python/requirements.lock.txt` : l'ensemble exact vérifié (24 paquets). **Installé par défaut**.
+- `python/requirements.txt` devient une **plage bornée** : `pyhanko>=0.35.1,<0.38`,
+  `pikepdf>=10.9,<11` (auparavant `>=0.25` / `>=8`, sans borne haute : deux installations à un
+  mois d'écart n'avaient pas les mêmes versions — c'est ainsi que 0.37 est passé inaperçu).
+- `setup-venv.sh` : accepte un répertoire (pour poser le venv **hors de node_modules/**), vérifie
+  Python ≥ 3.10 et `python3-venv` **avant** d'installer, `--plage` pour une montée de version.
+- `docs/INSTALLATION-ET-EXPLOITATION.md` (livré dans le paquet) : exigences, rôle de chaque
+  bibliothèque, installation en production, vérification, montée de version, sens de chaque
+  message d'erreur, secrets.
+
 ## 0.4.0 — 28/09/2026
 
 **Joindre un horodateur qui authentifie — c'est-à-dire un horodateur QUALIFIÉ.**

package/README.md

@@ -24,6 +24,10 @@ Le module reste **générique** : il ne connaît aucun métier. La sémantique (
 
 ## Installation
 
+> **Exploitation et maintenance** — exigences (Python ≥ 3.10), rôle de chaque bibliothèque Python,
+> installation en production **hors de `node_modules/`**, sens de chaque message d'erreur, montée
+> de version : **[docs/INSTALLATION-ET-EXPLOITATION.md](docs/INSTALLATION-ET-EXPLOITATION.md)**.
+
 ```bash
 pnpm add @mostajs/pdf-sign
 # Moteur pyhanko (optionnel : PAdES + permissions) :

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAuB3D"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAkC3D"}

package/dist/verify.js

@@ -16,19 +16,30 @@ export function verifyPdf(opts) {
     const avail = detectEngines(cfg.python);
     const trust = opts.trustPem ?? cfg.trustPem;
     const want = opts.engine ?? cfg.engine;
+    // ⚠️ AUCUN REPLI quand pyhanko EST là. Jusqu'en 0.4.0, un échec de pyhanko — document verrouillé
+    // sans son mot de passe, plantage, version de pyhanko qui change son API — retombait EN SILENCE
+    // sur la détection Node, qui ne sait dire que « une signature est présente » (intact et valid
+    // indéfinis). Un affichage qui lisait « pas false » y voyait « valide ». Une vérification qui
+    // n'a pas eu lieu doit se DIRE, pas se déguiser. Le repli Node ne vaut que si pyhanko MANQUE.
+    if (want === "pyhanko" && !avail.pyhanko) {
+        throw new Error("Vérification complète demandée, mais le moteur pyhanko est indisponible — lancer python/setup-venv.sh (ou PDF_SIGN_PYTHON).");
+    }
     if (avail.pyhanko && want !== "node") {
+        const args = [SIGN_PY, "verify", opts.input, trust ?? ""];
+        if (opts.openPassword)
+            args.push(opts.openPassword);
+        let out;
         try {
-            const args = [SIGN_PY, "verify", opts.input, trust ?? ""];
-            if (opts.openPassword)
-                args.push(opts.openPassword);
-            const out = execFileSync(avail.python, args, { encoding: "utf-8" });
-            const line = out.trim().split("\n").pop() ?? "{}";
-            const parsed = JSON.parse(line);
-            return { signed: !!parsed.signed, signatures: parsed.signatures ?? [], engine: "pyhanko" };
+            out = execFileSync(avail.python, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
         }
-        catch {
-            /* repli sur la détection Node */
+        catch (e) {
+            const trace = String(e?.stderr ?? "");
+            const net = trace.match(/ERREUR -- ([^\n]*)/);
+            throw new Error(net ? net[1] : `Vérification impossible (pyhanko) : ${trace.trim().split("\n").pop() || String(e?.message ?? e)}`);
         }
+        const line = out.trim().split("\n").pop() ?? "{}";
+        const parsed = JSON.parse(line);
+        return { signed: !!parsed.signed, signatures: parsed.signatures ?? [], engine: "pyhanko" };
     }
     // Détection Node basique : présence d'un /ByteRange + dictionnaire de signature.
     const s = readFileSync(opts.input).toString("latin1");

package/dist/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC;IAEvC,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1D,IAAI,IAAI,CAAC,YAAY;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACpD,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,MAAgB,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9E,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC;YAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC7F,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,wCAAwC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5F,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACzG,CAAC"}
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/docs/INSTALLATION-ET-EXPLOITATION.md

@@ -0,0 +1,271 @@
+# @mostajs/pdf-sign — installation, exploitation, maintenance
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**Version du module** : 0.4.1 · **Rédigé le** : 2026-09-28
+**Pour qui** : la personne qui reprend ce module — ou un produit qui l'emploie (mdseal, qatrax) —
+sans avoir assisté à sa construction. Rien ici ne suppose de savoir ce qui s'est dit avant.
+
+> **Si vous n'avez que deux minutes** : ce module signe des PDF. La signature simple se fait en
+> Node ; **tout le reste** — protection, mot de passe, horodatage, vérification complète — passe
+> par un programme **Python** (pyhanko), installé dans un environnement isolé (*venv*). Neuf
+> pannes sur dix viennent de ce venv : absent, effacé, ou d'une version non essayée. Le §6 dit
+> comment le vérifier en une commande, le §8 ce que veut dire chaque message d'erreur.
+
+---
+
+## 1. Comment le module fonctionne
+
+```
+  application (mdseal, qatrax…)
+        │  signPdf({ … })
+        ▼
+  @mostajs/pdf-sign  (Node, TypeScript)
+        │
+        ├── moteur NODE ─── @signpdf ─────────► signature PKCS#7 simple, invisible
+        │                                        (rien d'autre : ni protection, ni date)
+        │
+        └── moteur PYHANKO
+              │ 1. écrit config.json dans un dossier temporaire (droits 0700)
+              │ 2. lance : <python du venv> python/sign_with_perms.py sign … config.json
+              ▼
+            pikepdf  ── chiffrement AES-256, permissions (ni impression, ni copie)
+            pyhanko  ── signature PAdES visible
+                     └─ horodatage RFC 3161 ──► HTTPS ──► horodateur (DigiCert, Evidency…)
+```
+
+**Ce qui exige le moteur pyhanko** — sans lui, ces demandes sont **refusées**, jamais ignorées :
+
+| demande | option | pourquoi Node ne suffit pas |
+|---|---|---|
+| permissions (ni impression, ni copie) | `permissions` | chiffrement du PDF : pikepdf |
+| mot de passe à l'ouverture | `openPassword` | idem |
+| horodatage (date attestée par un tiers) | `timestampUrl` | client RFC 3161 : pyhanko |
+| cachet visible avec image | `field.stampImage` | apparence PAdES : pyhanko |
+| vérification complète (chaîne, intégrité) | `verifyPdf` | Node ne sait que détecter une signature |
+
+`engine: "auto"` (défaut) prend pyhanko s'il est disponible, Node sinon. **C'est la raison pour
+laquelle un venv absent ne se voit pas toujours** : une signature simple continue de marcher.
+
+## 2. Exigences techniques
+
+| élément | exigé | essayé | à savoir |
+|---|---|---|---|
+| système | Linux x86_64 ou aarch64 | Ubuntu 23.10 | pikepdf est livré compilé (*wheel*) pour ces deux architectures ; ailleurs, il faut compiler qpdf |
+| **Node.js** | ≥ 18 | 20 et plus | `fetch` et `AbortSignal.timeout` sont employés par les essais |
+| **Python** | **≥ 3.10** | 3.11.6 | exigé par pyhanko **et** pikepdf. Plus ancien : échec au milieu de `pip install`, sans nommer la cause (le script d'installation le vérifie avant) |
+| `python3-venv` | oui (Debian/Ubuntu) | 3.11.4 | livré à part sur Debian/Ubuntu. Absent : `python3 -m venv` échoue sur « ensurepip » → `sudo apt install python3-venv` |
+| `pip` | fourni par le venv | — | mis à jour par le script |
+| accès réseau sortant | HTTPS 443 vers l'horodateur | — | **seulement** si l'horodatage est employé. DigiCert écoute en HTTP 80 |
+| `openssl` | non (essais seulement) | 3.0.10 | sert aux essais à fabriquer un certificat jetable |
+| `qpdf` | **non** | — | embarqué dans pikepdf |
+| certificat de signature | fichier PKCS#12 (`.p12`) + sa phrase secrète | — | voir §9 |
+
+## 3. Les bibliothèques Python, une par une
+
+Versions : celles du **verrou** `python/requirements.lock.txt`, vérifiées par la suite d'essais.
+
+| bibliothèque | version | licence | rôle ici | si elle manque ou change |
+|---|---|---|---|---|
+| **pyHanko** | 0.37.0 | MIT | signature PAdES, horodatage RFC 3161, vérification | le moteur pyhanko est déclaré indisponible |
+| pyhanko-certvalidator | 0.32.1 | MIT | valide la chaîne de certificats (vérification) | tiré par pyHanko |
+| **pikepdf** | 10.15.0 | MPL-2.0 | chiffre le PDF, pose les permissions ; contient qpdf | idem |
+| cryptography | 50.0.1 | Apache-2.0 / BSD | ouvre le `.p12`, calcule la signature | « Phrase secrète invalide » si la phrase est fausse |
+| asn1crypto | 1.5.1 | MIT | structures CMS et TSP (le jeton d'horodatage) | tiré par pyHanko |
+| **aiohttp** | 3.14.3 | Apache-2.0 | **client HTTP de l'horodatage** depuis pyHanko 0.37 | voir le piège du §8, « pyhanko 0.37 » |
+| certifi | 2026.7.22 | MPL-2.0 | autorités racines pour joindre un horodateur **en HTTPS** | un HTTPS vers l'horodateur échoue en « Error while contacting » |
+| Pillow | 12.3.0 | MIT-CMU | image de fond du cachet visible | tiré par pikepdf |
+| lxml | 6.1.3 | BSD | lecture XML (structures PDF annexes) | tiré par pyHanko |
+| tzlocal | 5.4.4 | MIT | fuseau local de l'heure affichée dans le cachet | produit l'avertissement bénin « /etc/timezone is deprecated » |
+| oscrypto, uritools, yarl, multidict, frozenlist, attrs, … | cf. verrou | MIT / Apache | dépendances de second rang | ne s'installent jamais seules |
+
+**Côté Node**, pour mémoire : `@signpdf/*` (moteur Node), `pdf-lib`, `@mostajs/config` (lecture du
+`.env`).
+
+### Pourquoi deux fichiers de dépendances
+
+| fichier | contenu | qui l'emploie |
+|---|---|---|
+| `python/requirements.lock.txt` | **l'ensemble exact** essayé (24 paquets, `==`) | `setup-venv.sh`, **par défaut** — donc la production |
+| `python/requirements.txt` | la **plage admise** : `pyhanko>=0.35.1,<0.38`, `pikepdf>=10.9,<11` | `setup-venv.sh --plage`, pour une montée de version (§7) |
+
+Sans verrou, deux installations à un mois d'écart n'ont pas les mêmes versions. **C'est arrivé** :
+le poste de développement portait pyhanko 0.35.1 quand la dernière version publiée était 0.37.0,
+qui avait changé de client HTTP (§8).
+
+## 4. Installer
+
+### 4.1 Poste de développement
+
+```bash
+cd mosta-pdf-sign
+npm install
+bash python/setup-venv.sh              # crée python/.venv depuis le VERROU
+npx mosta-pdf-sign engines             # doit afficher "pyhanko": true
+```
+
+Le module trouve seul `python/.venv` : aucune variable à poser.
+
+### 4.2 Production — ⚠️ le venv HORS de `node_modules/`
+
+Dans une application, le module vit sous `node_modules/@mostajs/pdf-sign/`. **Un venv créé là est
+effacé par le `npm install` du déploiement suivant** — et rien ne le signale : les signatures
+simples continuent, seules les demandes de protection ou d'horodatage se mettent à échouer, à la
+première demande d'un client.
+
+```bash
+# depuis l'application, après npm install :
+bash node_modules/@mostajs/pdf-sign/python/setup-venv.sh /home/hmd/prod/.venv-pdfsign
+# puis, dans le .env de l'application :
+PDF_SIGN_PYTHON=/home/hmd/prod/.venv-pdfsign/bin/python
+# et redémarrer en relisant l'environnement :
+pm2 restart <application> --update-env
+```
+
+**mdseal** a son propre script, `scripts/setup-pyhanko.sh`, qui fait la même chose et pose le venv
+dans `/home/hmd/prod/.venv-pdfsign` (voir le README de mdseal). Un seul venv peut servir plusieurs
+applications du même serveur : elles emploient la même version du module.
+
+## 5. Configurer
+
+Tout se règle par le `.env` (lu par `@mostajs/config`, cascade `MOSTA_ENV`). Rien en dur.
+
+| clé | rôle | défaut |
+|---|---|---|
+| `PDF_SIGN_PYTHON` | chemin **absolu** du python du venv | voir ci-dessous |
+| `PDF_SIGN_ENGINE` | `auto` · `node` · `pyhanko` | `auto` |
+| `PDF_SIGN_P12` | certificat de signature | — (obligatoire) |
+| `PDF_SIGN_PASSPHRASE_FILE` | fichier de la phrase secrète — **préférer à** `PDF_SIGN_PASSPHRASE` | — |
+| `PDF_SIGN_REASON` / `_LOCATION` / `_NAME` / `_CONTACT` | métadonnées du cachet | — |
+| `PDF_SIGN_FIELD_PAGE` / `_FIELD_BOX` / `_STAMP_IMAGE` | position et image du cachet | page 0, bas-droite |
+| `PDF_SIGN_RESTRICT` | `true` → permissions restrictives | `false` |
+| `PDF_SIGN_TRUST_PEM` | certificat de confiance pour la vérification | — |
+| `PDF_SIGN_TSA` | adresse de l'horodateur — **apparie** les identifiants suivants | — |
+| `PDF_SIGN_TSA_API_KEY` / `_API_KEY_HEADER` | clé d'API de l'horodateur, nom de l'en-tête | — / `X-API-KEY` |
+| `PDF_SIGN_TSA_USER` / `_PASSWORD` | HTTP Basic auprès de l'horodateur | — |
+| `PDF_SIGN_TSA_TIMEOUT` | délai d'attente, secondes | 10 |
+
+⚠️ **Le choix du python, et son piège.** L'ordre est : `PDF_SIGN_PYTHON` **s'il existe** → sinon
+`python/.venv` du module → sinon `python3` du système. Un `PDF_SIGN_PYTHON` **mal orthographié**
+ne provoque donc **aucune erreur** : le module retombe sur le suivant. C'est pourquoi le §6
+demande de lire le champ `python` de `engines`, pas seulement `pyhanko: true`.
+
+⚠️ **Les identifiants de l'horodateur ne partent que vers `PDF_SIGN_TSA`.** Si l'application
+passe une autre adresse, la clé du `.env` n'est pas jointe — c'est voulu (la joindre, ce serait
+la donner à un tiers). Symptôme : « identifiants refusés (HTTP 401) » alors que la clé est bonne.
+
+## 6. Vérifier que tout marche
+
+```bash
+# 1. le moteur, et SURTOUT le chemin du python réellement employé
+PDF_SIGN_PYTHON=/home/hmd/prod/.venv-pdfsign/bin/python npx mosta-pdf-sign engines
+#    → { "node": true, "pyhanko": true, "python": "/home/hmd/prod/.venv-pdfsign/bin/python" }
+
+# 2. les versions installées
+/home/hmd/prod/.venv-pdfsign/bin/pip freeze | grep -iE 'pyhanko|pikepdf|aiohttp'
+
+# 3. la suite d'essais complète CONTRE CE venv (depuis le dépôt du module)
+PDF_SIGN_PYTHON=/home/hmd/prod/.venv-pdfsign/bin/python bash test-scripts/run-tests.sh
+#    → ✓ ALL TEST SUITES PASSED, et AUCUNE ligne « ⊘ SAUTÉ »
+```
+
+Une ligne `⊘ SAUTÉ` n'est **pas** un succès : elle dit qu'un essai n'a pas pu s'exécuter (pyhanko,
+openssl ou réseau absent) et en donne la raison. Les essais d'horodatage joignent DigiCert : sans
+réseau, trois d'entre eux sautent.
+
+## 7. Monter de version (pyhanko, pikepdf)
+
+**Jamais directement en production.** Une version non essayée n'y entre pas.
+
+```bash
+S=$(mktemp -d)
+bash python/setup-venv.sh "$S/venv" --plage          # dernières versions DANS la plage
+PDF_SIGN_PYTHON="$S/venv/bin/python" bash test-scripts/run-tests.sh
+```
+
+- Tout passe, aucun saut → régénérer le verrou (`"$S/venv/bin/pip" freeze`, en gardant l'en-tête
+  de `requirements.lock.txt`), noter la date et les versions dans l'en-tête et le CHANGELOG,
+  publier une version du module, puis réinstaller le venv de production depuis le verrou.
+- Une version **hors** de la plage (pyhanko 0.38…) → élargir la borne dans `requirements.txt`
+  **seulement après** que la suite passe dessus, et relire son journal des changements : 0.37 a
+  changé de client HTTP sans le dire dans son API.
+
+## 8. Pannes connues — ce que veut dire chaque message
+
+| message | cause | que faire |
+|---|---|---|
+| `Moteur pyhanko indisponible — lancer python/setup-venv.sh` | `engine:"pyhanko"` demandé, venv absent ou cassé | §6 étape 1 ; réinstaller (§4) |
+| `Horodatage demandé, mais le moteur retenu (node) ne sait pas horodater` | pas de pyhanko, et un `timestampUrl` | installer le venv. (Avant 0.4.0, le document sortait **sans date, sans erreur**.) |
+| `Le cœur Node ne gère pas les permissions/PAdES` | protection demandée sans pyhanko | idem |
+| protections refusées **juste après un déploiement** | venv créé dans `node_modules/`, effacé par `npm install` | §4.2 : venv hors du dépôt |
+| `Phrase secrète invalide pour ce certificat PKCS#12` | mauvaise phrase, ou phrase d'un autre certificat | vérifier le couple `PDF_SIGN_P12` / `PDF_SIGN_PASSPHRASE_FILE` |
+| `Certificat PKCS#12 illisible` | le fichier n'est pas un `.p12` | le régénérer ou le recopier en binaire |
+| `Horodatage impossible (…) : identifiants refusés par l'horodateur (HTTP 401)` | clé absente, fausse, expirée — **ou** adresse différente de `PDF_SIGN_TSA` (§5) | vérifier la clé et l'égalité exacte des adresses |
+| `… débit de l'horodateur dépassé (HTTP 429)` | trop d'appels par seconde (Evidency : 5/s) | réessayer ; étaler les signatures |
+| `… Error while contacting timestamp service` | réseau, DNS, pare-feu, délai dépassé | `curl -I <adresse>` depuis le serveur ; `PDF_SIGN_TSA_TIMEOUT` |
+| `Horodatage refusé : des identifiants ne partent pas en clair` | adresse `http://` avec une clé | passer l'adresse en `https://` |
+| `document verrouillé : son mot de passe d'ouverture est requis pour vérifier` | `verifyPdf` sur un document à mot de passe, sans `openPassword` (ou avec un faux) | fournir le mot de passe d'ouverture |
+| `Vérification impossible (pyhanko) : …` | pyhanko n'a pas pu lire le document | le fichier n'est pas un PDF signé lisible ; **avant 0.4.1, ce cas répondait « signé » par la détection Node** |
+| `modify_form ne peut pas etre refuse` | `permissions.modifyForm:false` | impossible en PDF signé : retirer l'option |
+| `/etc/timezone is deprecated …` | avertissement de tzlocal | **bénin**, aucune action |
+| `AttributeError: … __version__` | un script lit `pyhanko.__version__`, qui n'existe pas | lire `importlib.metadata.version("pyhanko")` |
+| `✗ Python >= 3.10 requis` / `ensurepip` | Python trop ancien / `python3-venv` absent | installer Python ≥ 3.10 / `sudo apt install python3-venv` |
+
+### Le piège « pyhanko 0.37 », en détail
+
+pyhanko 0.37 a remplacé son client HTTP (`requests` → `aiohttp`). Son API n'a pas changé — les
+signatures et l'horodatage marchent — mais **le code d'erreur HTTP a changé de place** dans
+l'exception. Le module 0.4.0 lisait l'ancien emplacement : sous 0.37, un refus de clé redevenait
+« Error while contacting timestamp service », qui envoie chercher un problème réseau. Corrigé en
+0.4.1 (les deux emplacements sont lus) et gardé par l'essai T-TSA-4, qui passe sous 0.35.1 **et**
+0.37.0. C'est l'exemple même de ce que le §7 prévient.
+
+### Lire un résultat de vérification
+
+| champ | sens | à retenir |
+|---|---|---|
+| `intact` | le document n'a pas changé depuis la signature | **false = document altéré** |
+| `valid` | la signature est mathématiquement correcte | reste **true** sur un document altéré : ne jamais le lire seul |
+| `trusted` | le certificat est reconnu (via `trustPem`) | false pour un certificat auto-signé non fourni |
+| `engine` | `pyhanko` = vérifié ; `node` = **seulement détecté**, rien n'a été validé | un résultat `node` ne dit jamais « valide » |
+
+## 9. Secrets
+
+| secret | où | comment il circule |
+|---|---|---|
+| certificat `.p12` | hors dépôt (`/home/hmd/prod/secrets/`, `Entreprise/.secrets/`), droits 600 | chemin dans `PDF_SIGN_P12` |
+| sa phrase secrète | fichier à part, droits 600 | `PDF_SIGN_PASSPHRASE_FILE` → lue par Python depuis le fichier |
+| clé d'API / mot de passe de l'horodateur | `.env` de l'application, jamais commité | Node → `config.json` temporaire (dossier 0700, effacé après usage) → Python |
+
+**Aucun secret ne passe par la ligne de commande** : elle se lit par n'importe quel utilisateur
+de la machine (`ps aux`). Le CLI `mosta-pdf-sign` n'accepte d'ailleurs les identifiants de
+l'horodateur que par le `.env`. Python n'imprime jamais ni la clé ni les en-têtes — seulement
+« (authentifie) ».
+
+## 10. État de la production — À COMPLÉTER
+
+La lecture du serveur n'a pas pu être faite en rédigeant ce document. À lancer sur `amia`, et à
+reporter ici :
+
+```bash
+ssh amia '/home/hmd/prod/.venv-pdfsign/bin/python --version;
+          /home/hmd/prod/.venv-pdfsign/bin/pip freeze | grep -iE "pyhanko|pikepdf|aiohttp|requests";
+          python3 --version; grep -E "^(PRETTY_NAME)" /etc/os-release'
+```
+
+| élément | valeur en production | relevé le |
+|---|---|---|
+| Python du venv | *à relever* | |
+| pyhanko / pikepdf | *à relever* | |
+| système | *à relever* | |
+
+Si les versions diffèrent du verrou : réinstaller depuis le verrou (§4.2), puis §6.
+
+## 11. Chronologie des leçons
+
+| date | ce qui s'est passé | ce qui a changé |
+|---|---|---|
+| avant 0.4 | risque identifié dans mdseal : un venv sous `node_modules/` serait effacé par le déploiement | venv hors du dépôt, §4.2 (`mdseal/scripts/setup-pyhanko.sh`) |
+| 26/09/2026 | des essais affichaient `✓` sans rien exécuter | `saute()` : un saut se voit |
+| 28/09/2026 | Node signait sans date quand on lui demandait une date | refus explicite (0.4.0) |
+| 28/09/2026 | pyhanko 0.37 : un 401 redevenait une « erreur de contact » | double lecture du code (0.4.1), verrou des versions |
+| 29/09/2026 | la vérification pyhanko n'était gardée par aucun essai ; son échec retombait sur « signé » | erreur explicite, 7 essais T-VER (0.4.1) |

package/llms.txt

@@ -1,7 +1,7 @@
 # @mostajs/pdf-sign — fiche LLM
 > Signature numérique de PDF, moteur HYBRIDE : cœur Node (PKCS#7 détaché via @signpdf, zéro Python) + bascule pyhanko (PAdES visible + permissions AES-256 + MOT DE PASSE d'ouverture) quand un venv est disponible. Config 100 % `.env`, CLI + API. Portage générique du pipeline pyhanko+pikepdf éprouvé. IMPLÉMENTÉ 0.1.0.
 
-- Version: 0.4.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Version: 0.4.1 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
 - Chemin: mostajs/mosta-pdf-sign-stack/mosta-pdf-sign · UI: ../mosta-pdf-sign-ui
 
 ## RÔLE
@@ -55,7 +55,9 @@ mosta-pdf-sign engines
 
 ## MOTEUR pyhanko (optionnel)
 bash python/setup-venv.sh  → .venv local → exporter PDF_SIGN_PYTHON=…/.venv/bin/python
-requiert pyhanko>=0.25, pikepdf>=8.
+python/requirements.lock.txt = ensemble EXACT essayé (installé par défaut) ; requirements.txt = plage
+admise (pyhanko>=0.35.1,<0.38 ; pikepdf>=10.9,<11). Python >= 3.10. En PRODUCTION : venv HORS de
+node_modules/ (setup-venv.sh <répertoire>). Doc : docs/INSTALLATION-ET-EXPLOITATION.md.
 
 ## PIÈGES
 - Le cœur Node lève si `permissions` OU `openPassword` est demandé : le chiffrement EXIGE pyhanko.
@@ -73,3 +75,6 @@ requiert pyhanko>=0.25, pikepdf>=8.
 - Les identifiants du .env ne partent QUE si timestampUrl === PDF_SIGN_TSA. Autre adresse ⇒ aucun
   identifiant du .env n'est joint (l'appelant fournit les siens).
 - HTTP 401/403 de l'horodateur ⇒ « identifiants refusés (HTTP 401) », 429 ⇒ « débit dépassé ».
+- verifyPdf (0.4.1) : pyhanko présent ⇒ son échec est une ERREUR (plus de repli Node muet) ;
+  engine:'pyhanko' sans pyhanko ⇒ ERREUR. engine 'node' dans le résultat = DÉTECTÉ, pas validé.
+- intact=false ⇒ document altéré ; valid reste true dans ce cas : lire intact ET valid.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/pdf-sign",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Signature numérique de PDF pour @mostajs — moteur HYBRIDE : cœur Node (PKCS#7 via @signpdf) + bascule pyhanko (PAdES + permissions AES-256) si disponible. Config .env, CLI, API. Réutilise le pipeline éprouvé pyhanko+pikepdf.",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -24,6 +24,7 @@
     "python/*.sh",
     "examples/*.mjs",
     "README.md",
+    "docs/INSTALLATION-ET-EXPLOITATION.md",
     "llms.txt",
     "CHANGELOG.md"
   ],

package/python/requirements.lock.txt

@@ -0,0 +1,32 @@
+# @mostajs/pdf-sign — VERROU : l'ensemble EXACT des paquets Python vérifié par la suite d'essais.
+# Auteur : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+#
+# Vérifié le 2026-09-28 : suite complète (23 essais, 0 sauté) sous Python 3.11.6, Ubuntu 23.10.
+# C'est CE fichier que `setup-venv.sh` installe par défaut. `requirements.txt` ne donne que la
+# plage admise ; ce fichier dit ce qui a été ESSAYÉ.
+#
+# Le régénérer = une montée de version : voir docs/INSTALLATION-ET-EXPLOITATION.md §7.
+aiohappyeyeballs==2.7.1
+aiohttp==3.14.3
+aiosignal==1.4.0
+asn1crypto==1.5.1
+attrs==26.1.0
+certifi==2026.7.22
+cffi==2.1.1
+cryptography==50.0.1
+frozenlist==1.8.0
+idna==3.20
+lxml==6.1.3
+multidict==6.9.1
+oscrypto==1.3.0
+packaging==26.3
+pikepdf==10.15.0
+pillow==12.3.0
+propcache==0.5.4
+pycparser==3.0
+pyHanko==0.37.0
+pyhanko-certvalidator==0.32.1
+typing_extensions==4.16.0
+tzlocal==5.4.4
+uritools==6.1.3
+yarl==1.25.1

package/python/requirements.txt

@@ -1,3 +1,14 @@
-# @mostajs/pdf-sign — dépendances du moteur pyhanko (PAdES + permissions).
-pyhanko>=0.25
-pikepdf>=8
+# @mostajs/pdf-sign — dépendances du moteur pyhanko (PAdES + permissions + horodatage).
+# Auteur : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+#
+# PLAGE ADMISE, pas versions exactes — l'ensemble exact vérifié est dans requirements.lock.txt,
+# et c'est lui que setup-venv.sh installe.
+#
+# Pourquoi des bornes HAUTES : pyhanko 0.37 a changé de client HTTP (requests → aiohttp) sans
+# changer son API publique ; seul l'endroit où se lit le code d'erreur HTTP a bougé, et le
+# diagnostic « identifiants refusés » s'est tu. Une version non essayée n'entre pas en production.
+# Élargir une borne = passer la suite d'essais sur la nouvelle version (docs/…EXPLOITATION.md §7).
+#
+# Pourquoi 0.35 au minimum : versions essayées 0.35.1 et 0.37.0. Python >= 3.10 exigé par les deux.
+pyhanko>=0.35.1,<0.38
+pikepdf>=10.9,<11

package/python/setup-venv.sh

@@ -1,9 +1,40 @@
 #!/usr/bin/env bash
-# @mostajs/pdf-sign — crée le venv Python du moteur pyhanko (optionnel : PAdES + permissions).
+# @mostajs/pdf-sign — crée le venv Python du moteur pyhanko (PAdES + permissions + horodatage).
 # @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+#
+# Usage : bash python/setup-venv.sh [répertoire-du-venv] [--plage]
+#   répertoire   défaut : python/.venv à côté de ce script
+#                ⚠️ EN PRODUCTION, PASSEZ UN RÉPERTOIRE HORS DE node_modules/ : un `npm install`
+#                efface node_modules/, donc le venv, sans qu'aucune erreur ne le signale.
+#   --plage      installe requirements.txt (dernières versions de la plage admise) au lieu du
+#                verrou requirements.lock.txt. Réservé à une MONTÉE DE VERSION, suivie des essais.
+#
+# Documentation complète : docs/INSTALLATION-ET-EXPLOITATION.md
 set -euo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-python3 -m venv "$HERE/.venv"
-"$HERE/.venv/bin/pip" install --upgrade pip >/dev/null
-"$HERE/.venv/bin/pip" install -r "$HERE/requirements.txt"
-echo "OK — venv pyhanko prêt : $HERE/.venv (exporter PDF_SIGN_PYTHON=$HERE/.venv/bin/python)"
+VENV="$HERE/.venv"
+FICHIER="$HERE/requirements.lock.txt"
+for a in "$@"; do
+  case "$a" in
+    --plage) FICHIER="$HERE/requirements.txt" ;;
+    *) VENV="$a" ;;
+  esac
+done
+
+# Python >= 3.10 : exigé par pyhanko ET pikepdf. Un Python plus ancien échouerait au milieu de
+# `pip install` avec un message qui ne nomme pas la cause.
+python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)' || {
+  echo "✗ Python >= 3.10 requis — trouvé : $(python3 --version 2>&1)" >&2; exit 1; }
+# Debian/Ubuntu livrent `venv` à part : sans lui, `python3 -m venv` échoue sur « ensurepip ».
+python3 -c 'import ensurepip' 2>/dev/null || {
+  echo "✗ module venv/ensurepip absent — sudo apt install python3-venv" >&2; exit 1; }
+
+echo "· venv    : $VENV"
+echo "· paquets : $(basename "$FICHIER")"
+python3 -m venv "$VENV"
+"$VENV/bin/pip" install --upgrade pip >/dev/null
+"$VENV/bin/pip" install -r "$FICHIER"
+# Versions lues par les MÉTADONNÉES : pyhanko n'expose pas `__version__` (AttributeError).
+"$VENV/bin/python" -c 'import importlib.metadata as m, pyhanko, pikepdf
+print("· pyhanko", m.version("pyhanko"), "· pikepdf", m.version("pikepdf"), "— import OK")'
+echo "✓ venv prêt. Déclarer : PDF_SIGN_PYTHON=$(cd "$VENV" && pwd)/bin/python"

package/python/sign_with_perms.py

@@ -164,13 +164,24 @@ def _cause_horodatage(e):
     vus, x = set(), e
     while x is not None and id(x) not in vus:
         vus.add(id(x))
-        for a in getattr(x, "args", ()):
-            code = getattr(a, "status_code", None)
+        # Deux clients HTTP selon la version de pyhanko -- et le code n'est pas au meme endroit :
+        #   <= 0.36 : `requests`, la reponse est passee en argument   -> args[i].status_code
+        #   >= 0.37 : `aiohttp`, l'exception porte le code elle-meme -> ClientResponseError.status
+        # Constate le 28/09/2026 : sous 0.37, un 401 redevenait « Error while contacting
+        # timestamp service », sans que rien d'autre ne change.
+        codes = [getattr(a, "status_code", None) for a in getattr(x, "args", ())]
+        # `.status` n'est lu que sur une exception d'aiohttp : ailleurs, un attribut du meme nom
+        # pourrait ne pas etre un code HTTP, et le message accuserait l'horodateur a tort.
+        if type(x).__module__.split(".")[0] == "aiohttp":
+            codes.append(getattr(x, "status", None))
+        for code in codes:
+            if not isinstance(code, int):
+                continue
             if code in (401, 403):
                 return f"identifiants refusés par l'horodateur (HTTP {code}) -- clé d'API ou mot de passe absent ou invalide"
             if code == 429:
                 return "débit de l'horodateur dépassé (HTTP 429) -- réessayer plus tard"
-            if code is not None and code != 200:
+            if code != 200:
                 return f"l'horodateur a répondu HTTP {code}"
         x = x.__cause__ or x.__context__
     return str(e)
@@ -226,12 +237,26 @@ def do_verify(pdf_path, cert_pem, open_password=None):
         if getattr(r, "encrypted", False):
             # Le mot de passe d'ouverture d'abord s'il est donne, la chaine vide ensuite : un
             # document non verrouille s'authentifie avec elle, un document verrouille l'exige.
+            # ⚠️ `decrypt` ne LÈVE PAS sur un mauvais mot de passe : il rend un AuthResult au statut
+            # FAILED. Jusqu'en 0.4.0, la boucle attendait une exception et tenait donc le document
+            # pour ouvert des le premier essai, quel qu'il soit — l'echec surgissait plus loin, sans
+            # nom. On lit le STATUT. (Constate le 29/09/2026 par T-VER-4, sous pyhanko 0.35 et 0.37.)
+            from pyhanko.pdf_utils.crypt import AuthStatus
+            ouvert = False
             for essai in ([open_password] if open_password else []) + [""]:
                 try:
-                    r.decrypt(essai)
-                    break
+                    ouvert = r.decrypt(essai).status != AuthStatus.FAILED
                 except Exception:
-                    continue
+                    ouvert = False
+                if ouvert:
+                    break
+            # Verrouille et aucun mot de passe ne l'ouvre : on le DIT. Continuer faisait planter
+            # l'enumeration plus bas, et l'appelant retombait (<= 0.4.0) sur une detection muette.
+            if not ouvert:
+                raise SystemExit(
+                    "ERREUR -- document verrouillé : son mot de passe d'ouverture est requis pour "
+                    "vérifier ses signatures%s." % (" (celui fourni ne l'ouvre pas)" if open_password else "")
+                )
         sigs = r.embedded_signatures
         if not sigs:
             print(json.dumps({"signed": False, "signatures": []}))