common: runbook partage Pingvin fichiers > 50 Mo (cookie auth, chunks 30 Mo)

common/partage-pingvin-gros-fichiers.md

@@ -0,0 +1,43 @@
+# Partage de gros fichiers (> 50 Mo) via Pingvin Share — pv.bolbol.tn
+
+**Date** : 2026-07-04 · **Statut** : validé de bout en bout (upload 60 Mo depuis hermes-agent-nyora et 55 Mo depuis hermes-agent-tt, checksum vérifié après téléchargement public).
+
+## Problème
+
+L'API Bot Telegram refuse les fichiers > 50 Mo (`sendDocument`). L'alternative Pingvin échouait depuis des mois : tous les essais API finissaient en 403/404/413 (cf. anciennes notes `pingvin-api-issues-2026.md`, archivées).
+
+## Les 3 causes racines (ce qui NE marche PAS)
+
+1. **`Authorization: Bearer <token>` → 403 systématique.** Pingvin lit le JWT dans le **cookie** : `-H "Cookie: access_token=$TOKEN"`. C'était la cause des « Forbidden resource » historiques.
+2. **Upload en un seul POST → 413** au-delà de la limite body (= `share.chunkSize` serveur, 30 000 000 octets). Il faut chunker à **exactement 30 000 000 octets** par chunk (sauf le dernier) : toute autre taille casse le contrôle `expectedChunkIndex = ceil(tailleDisque/chunkSize)` côté serveur → erreur `unexpected_chunk_index`.
+3. **Endpoints inexistants** : `/api/v1/*`, `/api/upload`, `/api/files`, multipart `file=@` sur `/api/shares`. Le corps du chunk est du **binaire brut** (`--data-binary`, `Content-Type: application/octet-stream`) — pas de base64, pas de multipart.
+
+Autres pièges :
+- **Usernames Pingvin sensibles à la casse** : la variable d'env de tt disait `hermes_TT`, le compte est `hermes_tt` → toujours passer le username en minuscules. (Le mot de passe du compte `hermes_tt` a été réaligné le 2026-07-04 sur la valeur de `PINGVIN_PASS_TT` via le compte admin.)
+- Le `id` de fichier renvoyé par le 1er chunk doit être repassé en query param `id=` sur les chunks suivants.
+
+## Flux API validé
+
+```
+1. POST /api/auth/signIn                      {"username","password"}      → accessToken
+2. POST /api/shares                            (Cookie access_token)       → crée le share {"id","expiration":"never","security":{},"recipients":[]}
+3. POST /api/shares/<share>/files?name=<n>&chunkIndex=<i>&totalChunks=<t>[&id=<fid>]
+        body = chunk binaire brut de 30 000 000 octets (dernier = reste), Content-Type: application/octet-stream
+4. POST /api/shares/<share>/complete           (Cookie access_token)
+5. Lien public : https://pv.bolbol.tn/share/<share>   (téléchargement direct : /api/shares/<share>/files/<fid>)
+```
+
+Limite par share : 4 Go (`share.maxSize`). Suppression : `DELETE /api/shares/<share>`.
+
+## Script prêt à l'emploi
+
+Le script shell complet (copier-coller) est dans le skill **`partage-pingvin.md`** déployé à la racine `data/skills/` des 3 instances Hermes (tt, nyora, perso). Chaque conteneur agent a déjà `PINGVIN_URL=http://Pingvin-Share:3000` + `PINGVIN_USER_<INSTANCE>` / `PINGVIN_PASS_<INSTANCE>`.
+
+Le skill `envoyer-fichier-telegram.md` renvoie vers `partage-pingvin` pour les fichiers > 50 Mo ; le lien pv.bolbol.tn est ensuite envoyé par `sendMessage` Telegram.
+
+## Vérification rapide
+
+```sh
+# depuis un conteneur agent
+curl -s -o /dev/null -w "%{http_code}" https://pv.bolbol.tn/share/<SHARE_ID>   # attendu : 200
+```