# ftpLab — client FTP / FTPS pour BERKIOS

Source : https://docs.berkios.online/modules/ftplab/ · Section : Modules · Documentation officielle BERKIOS (https://docs.berkios.online)


ftpLab est une bibliothèque **native** du Bridge (comme KConnect ou Berkrypt) : un client FTP ouvre des sockets TCP, ce que
les bibliothèques `.bkl` (simples macros) ne peuvent pas faire. Elle est écrite en Node pur, **sans dépendance**.

19 commandes `ftp-*` (voir `COMMANDES.md`) : sessions (`ftp-connecter`, `ftp-deconnecter`, `ftp-sessions`, `ftp-etat`, `ftp-ping`),
navigation (`ftp-repertoire`, `ftp-aller-a`, `ftp-lister`, `ftp-taille`, `ftp-modifie-le`), transferts (`ftp-telecharger`,
`ftp-televerser`, `ftp-lire-texte`, `ftp-ecrire-texte`) et gestion (`ftp-creer-dossier`, `ftp-supprimer`,
`ftp-supprimer-dossier`, `ftp-renommer`). Permissions : `ftp.connect`, `ftp.read`, `ftp.write`.

## Ce qui est pris en charge
- FTP et **FTPS** : TLS explicite (`AUTH TLS`, défaut) ou implicite (port 990). Données chiffrées (`PROT P`) avec reprise de session TLS.
- Mode **passif** (EPSV, puis PASV). Listing par `MLSD` quand le serveur l'annonce, sinon `LIST` (formats Unix et DOS/Windows).
- Noms de fichiers UTF-8, transferts binaires, connexion anonyme.

## Sécurité
- **Chiffré par défaut** : sans option, `ftp-connecter` exige TLS et **ne se replie jamais en clair**. Si le serveur ne propose pas FTPS, l'erreur `tls_refuse` survient *avant* l'envoi de l'utilisateur et du mot de passe. Le FTP en clair doit être demandé explicitement (`securite: "aucune"`) : mot de passe et fichiers circulent alors lisibles par tout le réseau.
- **Certificat vérifié** par défaut. `verifierCertificat: false` accepte un certificat auto-signé ou expiré : la connexion reste chiffrée mais le serveur n'est plus authentifié (attaque de l'homme du milieu possible).
- **Réseau privé refusé** (localhost, 10/8, 172.16/12, 192.168/16, lien local…) tant que le Bridge n'est pas lancé avec `BERKIOS_SYSTEM_ALLOW_PRIVATE_NETWORK=1`. Contrôle fait à la résolution DNS (pas de contournement par « DNS rebinding »).
- **Pas de « FTP bounce »** : l'adresse annoncée par PASV est ignorée, le canal de données rejoint toujours l'adresse du canal de contrôle.
- **Pas d'injection de commande** : tout argument contenant un retour à la ligne ou un caractère nul est refusé avant envoi.
- **Fichiers locaux confinés** au dossier de travail du Bridge (`..` et liens symboliques refusés). Un téléchargement n'écrase jamais un fichier existant sans `ecraser: true` et passe par un fichier temporaire (aucun fichier partiel laissé).
- **Mot de passe** jamais renvoyé, jamais repris dans une erreur, non enregistré. Il est présent en mémoire du Bridge pendant la session uniquement.
- Limites : 8 sessions, 100 Mio par transfert, 1 Mio pour `ftp-lire-texte` / `ftp-ecrire-texte`, listing de 8 Mio, délai 15 s (réglable), session fermée après 10 min d'inactivité. Un transfert interrompu ferme la session.

## Limites connues
- Pas de mode actif, ni SFTP (SSH) : SFTP est un autre protocole.
- Pas de reprise de transfert, pas de suppression ni de téléchargement récursif de dossiers (à écrire explicitement, dossier par dossier).
- Les serveurs FTPS exigeant une reprise de session TLS stricte sur le canal de données sont pris en charge via `getSession()` ; non testé contre des serveurs réels (tests faits sur un serveur FTP/FTPS simulé en mémoire : `test/helpers/mock-ftp-server.mjs`).
- Une session est liée au dossier de travail qui l'a ouverte ; elle est perdue au redémarrage du Bridge.

## Développement
```text
node --test "test/*.test.mjs"      # 14 tests (les 2 tests FTPS nécessitent openssl)
node scripts/generate-manifest.mjs # ftplab.manifest.json
node scripts/generate-docs.mjs     # COMMANDES.md
```
Branchement au Bridge : `bridge/ftplab-commands.mjs` (tests : `bridge/tests/ftplab-commands.test.mjs`).