saltcorn-samba 0.3.10 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,158 @@ All notable changes to `saltcorn-samba` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] – 2026-07-05
+
+### ⚠️ BREAKING CHANGES
+
+- **Node.js ≥ 20 wird jetzt zwingend benötigt** (vorher war 16 möglich).
+  Grund: die neue Dependency `smb3-client` ist ein Pure-ESM-Paket und wird
+  im Plugin über dynamic `import()` aus CommonJS geladen — das ist ab
+  Node 20 stabil.
+- **Dependency-Wechsel:** `@marsaud/smb2` wurde vollständig entfernt und
+  durch [`smb3-client`](https://www.npmjs.com/package/smb3-client) `^0.2.0`
+  ersetzt.
+- **Zwei neue Config-Felder** in Schritt 1 des Konfigurations-Wizards:
+  - `SMB-Signing` (Werte: `if-offered` / `required` / `disabled`, Default `if-offered`)
+  - `SMB-Verschlüsselung` (Werte: `if-offered` / `required` / `disabled`, Default `if-offered`)
+
+  Es ist **kein manueller Config-Umbau nötig** — die Defaults sind für
+  fast alle Setups sinnvoll. Wer aus Sicherheitsgründen Signing oder
+  Encryption erzwingen will, kann jetzt `required` wählen.
+
+### Fixed – **Moderne Samba-Server (`sign_algo_id=0` / AES-CMAC-Pflicht)**
+
+Symptom nach dem 0.3.11-Update: nach dem Setzen von
+`NODE_OPTIONS=--openssl-legacy-provider` startete Saltcorn wieder, aber im
+Samba-Log erschien beim ersten Zugriff:
+
+```
+smbd: sign_algo_id=0 in negotiate response, expected AES-CMAC (2) or higher
+```
+
+gefolgt von `STATUS_INVALID_PARAMETER` und einem 401-Fehler im Plugin.
+
+**Ursache:** Aktuelle Samba-Versionen (Ubuntu 22.04+ / Debian 12+ /
+RHEL 9+) verlangen im SMB-3.1.1-Handshake das moderne Signing-Verfahren
+**AES-128-CMAC** (`SigningAlgorithmId 2`). `@marsaud/smb2` (letztes
+Release 2020, unmaintained) implementiert diese Cipher-Suite nicht — es
+kann nur die alten HMAC-SHA256- bzw. HMAC-MD5-Signaturen und meldet
+sich mit `sign_algo_id=0`, was ein moderner Samba als Protokoll-Fehler
+verwirft.
+
+**Lösung — kompletter Wechsel der SMB-Client-Library:**
+
+| Aspekt | Vorher (`@marsaud/smb2`) | Nachher (`smb3-client` 0.2.0) |
+|---|---|---|
+| Protokoll | SMB 2.0 / 2.1 | SMB 2.1 / 3.0 / 3.0.2 / **3.1.1** |
+| Signing | HMAC-SHA256 (nur) | HMAC-SHA256 **+ AES-128-CMAC** |
+| Encryption | – | AES-128-CCM / AES-128-GCM (optional) |
+| Pre-Auth | – | SHA-512 Pre-Auth-Integrity |
+| Auth | NTLM (via `ntlm`, DES-ECB) | **NTLMv2 / SPNEGO** (ohne DES-ECB) |
+| Wartung | Letztes Release Q4 2020 | Aktiv (Mai 2026) |
+| Runtime-Deps | `ntlm`, `iconv-lite` | **keine** |
+| API | Callback | **Promise / async** |
+| Modul-System | CommonJS | Pure ESM (via dynamic import geladen) |
+
+### Removed
+
+- Legacy-Crypto-Check-Utility (`checkLegacyCryptoAvailable`,
+  `legacyCryptoErrorMessage`) sowie zugehöriger Handshake-Block in der
+  `/sambatest`-Route und im Test-Panel — nicht mehr nötig, weil
+  `smb3-client` keine Legacy-Cipher (DES-ECB) verwendet.
+- Troubleshooting-Abschnitt zum `--openssl-legacy-provider`-Flag im README
+  (durch neuen 0.4.0-Kompatibilitätsabschnitt ersetzt).
+
+### Changed
+
+- `smb-client.js` komplett neu geschrieben als dünner Wrapper um
+  `smb3-client`. Interne API (`buildClient`, `withClient`, `readdir`,
+  `readFile`, `writeFile`, `rename`, `unlink`, `mkdir`, `rmdir`) bleibt
+  identisch — kein Anpassungsbedarf in den View- oder Route-Handlern.
+- Pfad-Konvention intern umgestellt: `smb3-client` erwartet den Share als
+  erstes Segment jedes Pfads (`share/subdir/datei.pdf`) statt separat im
+  Constructor. Der Wrapper prependet den Share-Namen transparent, sodass
+  Aufrufer weiterhin nur relative Pfade (`subdir/datei.pdf`) übergeben.
+- Readdir-Ergebnisse werden pro Eintrag mit einem parallelen `stat()`-
+  Aufruf (Batch-Größe 16) angereichert, weil `smb3-client`-Dirents nur
+  `name` + `isFile()` + `isDirectory()` liefern — der Plugin-Filemanager
+  braucht aber weiterhin Größe und mtime.
+- Fehler-Mapping in `/sambatest` erweitert um typische Signing-/
+  Encryption-/Pre-Auth-Fehlermeldungen aus `smb3-client` (`bad signature`,
+  `preauth integrity`, `encryption`).
+
+### Migration
+
+1. Saltcorn stoppen.
+2. Plugin auf 0.4.0 aktualisieren (npm bzw. neues ZIP entpacken).
+3. Falls gesetzt: `NODE_OPTIONS=--openssl-legacy-provider` **entfernen**
+   (nicht mehr nötig; siehe README-Abschnitt „Troubleshooting →
+   ERR_OSSL_EVP_UNSUPPORTED").
+4. Sicherstellen, dass **Node.js ≥ 20** installiert ist (`node -v`).
+5. Saltcorn wieder starten. Die Plugin-Config bleibt gültig — die neuen
+   Felder `SMB-Signing` und `SMB-Verschlüsselung` erhalten automatisch
+   den Default `if-offered`. Wer maximale Sicherheit möchte, setzt beide
+   auf `required` (Voraussetzung: der Samba-Server unterstützt es).
+6. Im Config-Wizard einmal „→ Verbindung jetzt testen" klicken.
+
+## [0.3.11] – 2026-07-05
+
+### Fixed – **Worker-Crash / 502 durch DES-ECB auf Node 17+ / OpenSSL 3**
+
+Symptom nach dem 0.3.10-Update:
+
+```
+node:internal/crypto/cipher:117
+Error: error:0308010C:digital envelope routines::unsupported
+    at Cipheriv.createCipherBase ...
+    at .../@marsaud/smb2/node_modules/ntlm/lib/smbhash.js:46
+code: 'ERR_OSSL_EVP_UNSUPPORTED'
+worker died
+```
+
+Auf der Config-Seite dann: **„Antwort war kein JSON (HTTP 502)“**.
+
+**Ursache:** `@marsaud/smb2` benutzt über das transitive Paket `ntlm` den
+Cipher **DES-ECB** zur Berechnung der LM/NTLM-Hashes. Node.js ab Version 17
+ist gegen OpenSSL 3 gebaut, das DES-ECB standardmäßig blockiert. Der
+`createCipheriv("des-ecb", ...)`-Aufruf wirft dann synchron
+`ERR_OSSL_EVP_UNSUPPORTED`. Weil der Fehler synchron aus tiefen Callback-
+Aufrufen kommt, tötet er den Saltcorn-Worker-Prozess → der Reverse-Proxy
+liefert 502 → die Route liefert kein JSON.
+
+**Fixes in diesem Release:**
+
+1. **Präventiver Check in `smb-client.js`:** Beim ersten Aufbau eines
+   SMB-Clients wird geprüft, ob `crypto.createCipheriv("des-ecb", ...)`
+   funktioniert. Wenn nicht, wird eine saubere, ausführliche deutsche
+   Fehlermeldung mit Lieferanleitung geworfen (`E_LEGACY_CRYPTO`) — der
+   fehlerhafte NTLM-Code wird gar nicht erst betreten, der Worker überlebt.
+2. **`/sambatest`-Route:** Der Check läuft zusätzlich explizit **vor**
+   dem `withClient`-Aufruf und liefert JSON mit `code: "E_LEGACY_CRYPTO"`,
+   `error`, `hint`, `node_version` und `openssl_version` — damit steht der
+   Diagnose-Grund direkt in der UI, nicht im Server-Log.
+3. **Fehler-Mapping erweitert:** Falls der Crash doch mal aus einem
+   anderen Pfad kommt (z. B. spätere Reconnect-Versuche), erkennt die
+   Catch-Logik jetzt auch `ERR_OSSL_EVP_UNSUPPORTED`,
+   `digital envelope routines` und `unsupported` und liefert einen
+   verständlichen Hinweis.
+4. **README:** Neuer Abschnitt „Troubleshooting“ mit Setup-Rezepten für
+   `NODE_OPTIONS=--openssl-legacy-provider` (Umgebungsvariable, systemd,
+   Docker/Compose, PM2, direkter Aufruf) plus Tabelle mit den häufigsten
+   Verbindungsfehlern und Diagnose-Kommandos.
+
+### Notes
+- Das Plugin ändert keinen Node-Startparameter selbst — das können wir aus
+  Sicherheits- und Prozessgründen nicht (Node-Flags müssen beim Prozess-
+  Start gesetzt werden). Der Fix ist eine saubere Fehlererkennung mit
+  Lösungsanleitung.
+- Sobald Saltcorn mit `NODE_OPTIONS=--openssl-legacy-provider` läuft,
+  funktionieren Verbindungstest und alle SMB-Operationen ohne weitere
+  Anpassung.
+- **Roadmap:** Migration weg von `@marsaud/smb2` (letzter Release 2020) hin
+  zu einer aktiv gepflegten SMB-Client-Bibliothek, damit das
+  Legacy-Provider-Flag nicht mehr nötig ist.
+
 ## [0.3.10] – 2026-07-05
 
 ### Fixed – **DNS-Fehler: `getaddrinfo ENOTFOUND "host:445"`**

package/README.md

@@ -12,7 +12,24 @@ Features:
 - 📄 **Inline-PDF-/Bild-Anzeige** direkt im `SambaFileManager` (Klick auf eine Datei), plus Download- und externe-App-Buttons.
 - 🚀 **`smb://`-Links** — Öffnet Dateien und Ordner direkt in Nemo, Nautilus, Dolphin (Linux) oder Explorer (Windows).
 - 🔒 **Sicherheit** — Base-Path als „Chroot", strenge Path-Traversal-Prüfung (`..`, absolute Pfade, UNC, Drive-Letters, NUL-Bytes), CSRF-Schutz auf Schreib-Routen, Filename-Sanitizer, Extension-Blocklist, rollenbasierter Zugriff (getrennte Lese-/Schreib-Rollen).
-- 🐳 **Docker-freundlich** — direkt per SMB2-Protokoll, keine System-Binaries nötig.
+- 🔐 **Moderne SMB-Kryptografie** — SMB 3.1.1 mit **AES-128-CMAC-Signing** (Pflicht auf aktuellen Samba-Servern) und optionaler **AES-CCM/GCM-Verschlüsselung**. Signing- und Encryption-Modus per Config-Dropdown wählbar (`if-offered` / `required` / `disabled`). **Keine Legacy-Cipher** (DES-ECB) mehr nötig — läuft ohne `--openssl-legacy-provider` unter Node 20+.
+- 🐳 **Docker-freundlich** — direkt per SMB2/3-Protokoll, keine System-Binaries nötig.
+
+> **Voraussetzungen:** **Node.js ≥ 20** (wegen der ESM-basierten [`smb3-client`](https://www.npmjs.com/package/smb3-client) Library, die intern per dynamic `import()` geladen wird). Saltcorn 0.9+ wird unterstützt.
+
+---
+
+## Was ist neu in 0.4.0 (Migration von 0.3.x)
+
+Das Plugin wurde intern von der unmaintained `@marsaud/smb2` auf die moderne
+`smb3-client` umgestellt. **Kein Config-Umbau nötig** — die neuen Felder
+`SMB-Signing` und `SMB-Verschlüsselung` haben sinnvolle Defaults (`if-offered`).
+Dadurch:
+
+- ✅ funktioniert wieder gegen moderne Samba-Server, die `sign_algo_id != 0`
+  (AES-CMAC) verlangen,
+- ✅ **kein** `--openssl-legacy-provider`-Flag mehr nötig,
+- ⚠️ **Breaking:** Node.js ≥ 20 zwingend erforderlich (vorher 16 möglich).
 
 ---
 
@@ -109,6 +126,8 @@ Configure* ausfüllen. Die Konfiguration ist zweistufig:
 | **Passwort** | *(secret)* | Samba nutzt ein eigenes Passwort (`smbpasswd`), nicht zwingend das Linux-Login. Moderne Server lehnen leere Passwörter ab. |
 | **Basispfad** | `projekte/2026` | Optional. Relativ, mit Slashes, **ohne** führenden `/`. Beschränkt jeden Zugriff auf dieses Unterverzeichnis der Freigabe. `..` und absolute Pfade werden abgelehnt. |
 | **TCP-Port** | `445` | Standard SMB2/3 über TCP. **SMBv1 (139) wird nicht unterstützt** – auf dem Server `min protocol = SMB2` setzen. |
+| **SMB-Signing** | `if-offered` | `if-offered` (Standard), `required` oder `disabled`. Nutzt HMAC-SHA256 (SMB 2.x) bzw. AES-128-CMAC (SMB 3.x). Moderne Samba-Server verlangen häufig Signing → `required` oder `if-offered`. |
+| **SMB-Verschlüsselung** | `if-offered` | `if-offered` (Standard), `required` oder `disabled`. Nutzt AES-128/256-CCM/GCM. Shares mit serverseitigem `SMB2_SHAREFLAG_ENCRYPT_DATA` erzwingen Verschlüsselung ohnehin. |
 
 > **Tipp:** Bevor Sie speichern, klicken Sie auf **„→ Verbindung jetzt
 > testen“** – siehe Abschnitt [Verbindung testen](#verbindung-testen).
@@ -331,6 +350,73 @@ Ab dann taucht das Plugin im Plugins-Store jeder Saltcorn-Instanz auf.
 
 ---
 
+## Troubleshooting
+
+### `ERR_MODULE_NOT_FOUND` / „Cannot find package 'smb3-client'" / Worker startet nicht
+
+Das Plugin lädt `smb3-client` (ESM) via dynamic `import()` — das npm-Paket
+muss also im Plugin-Ordner installiert sein.
+
+```bash
+cd /pfad/zu/saltcorn-samba
+npm install
+saltcorn restart   # oder systemd/docker-Neustart
+```
+
+Bei Installation über die Saltcorn-Plugin-UI (Source `npm` oder `github`)
+führt Saltcorn `npm install` automatisch aus.
+
+### `STATUS_INVALID_PARAMETER` / „sign_algo_id=0" im Samba-Log
+
+Das war der Fehler in **0.3.x mit `@marsaud/smb2`**: moderne Samba-Server
+(Ubuntu 22.04+ / Debian 12+ / RHEL 9+) verlangen **AES-CMAC-Signing**, das
+die alte Library nicht konnte. **In 0.4.0 gelöst** — die neue `smb3-client`-
+Library implementiert AES-CMAC. Falls die Meldung dennoch auftaucht:
+
+- In der Plugin-Config **SMB-Signing = `required`** setzen (erzwingt
+  AES-CMAC schon beim Handshake).
+- Auf dem Server sicherstellen, dass `server signing = mandatory` gesetzt
+  ist, dann in der Client-Config ebenfalls `required` wählen.
+
+### `ERR_OSSL_EVP_UNSUPPORTED` / `--openssl-legacy-provider`
+
+**Betrifft 0.4.0 nicht mehr.** Die alte Abhängigkeit `@marsaud/smb2` nutzte
+intern DES-ECB (aus dem transitiven `ntlm`-Paket), das ab OpenSSL 3
+deaktiviert ist. `smb3-client` verwendet ausschließlich moderne Cipher
+(HMAC-SHA256, AES-128-CMAC, AES-CCM/GCM, SHA-512-PreAuth-Integrity).
+**Das `NODE_OPTIONS=--openssl-legacy-provider`-Flag darf und sollte in
+0.4.0 wieder entfernt werden.**
+
+### Signing- und Verschlüsselungs-Modi
+
+Beide Modi haben denselben Wertebereich:
+
+| Wert | Verhalten |
+|---|---|
+| `if-offered` **(Standard)** | Wird genutzt, wenn der Server es anbietet. Kompatibel mit alten und neuen Servern. |
+| `required` | Wird zwingend verlangt. Verbindung schlägt fehl, wenn der Server nicht mitmacht. Empfohlen für Produktionsumgebungen. |
+| `disabled` | Wird nicht angefordert. Nur für Legacy-Server oder isolierte LAN-Setups. Nicht mit Servern kombinieren, die Signing/Encryption erzwingen. |
+
+Typische Fehlermeldungen und was zu tun ist:
+
+| Symptom | Wahrscheinliche Ursache | Lösung |
+|---|---|---|
+| `bad signature` / `SIGNATURE_MISMATCH` | Uhrzeit-Drift zwischen Client und Server, oder falsche Credentials | Zeit synchronisieren (NTP), Passwort prüfen |
+| `preauth integrity` | Man-in-the-Middle oder Netzwerkproblem | Netzwerkpfad prüfen (VPN, Proxy) |
+| Verbindung schlägt bei `required` fehl | Server bietet Modus nicht an | Server konfigurieren oder Modus auf `if-offered` senken |
+
+### Weitere häufige Fehler
+
+| Symptom | Ursache | Lösung |
+|---|---|---|
+| `ECONNREFUSED :445` | SMB-Dienst läuft nicht oder Firewall blockt Port 445 | `nc -vz <server> 445` vom Saltcorn-Host testen |
+| `ETIMEDOUT` | Kein Netzwerkpfad (VLAN/Docker-Bridge/VPN) | Vom Saltcorn-Container aus `ping` + `nc -vz` prüfen |
+| `LOGON_FAILURE` / `STATUS_LOGON_FAILURE` | User/Passwort/Domain falsch | Zugangsdaten prüfen. Moderne Samba-Server erlauben keine leeren Passwörter |
+| `BAD_NETWORK_NAME` / `STATUS_BAD_NETWORK_NAME` | Share existiert nicht oder Schreibweise falsch | `smbclient -L //server -U user` zur Kontrolle |
+| Nur SMBv1 verfügbar | Server bietet SMB2/3 nicht an | In `smb.conf`: `min protocol = SMB2` |
+
+---
+
 ## Bekannte Grenzen
 
 - Dateien werden komplett gepuffert (`readFile` / `writeFile`). Für

package/index.js

@@ -92,13 +92,15 @@ window.sambaTestConn = async function(btn) {
   if (!form) { out.innerHTML = '<div class="alert alert-danger">Formular nicht gefunden.</div>'; return; }
   function v(n){ var el = form.querySelector('[name="'+n+'"]'); return el ? el.value : ''; }
   var payload = {
-    server:    v('server'),
-    share:     v('share'),
-    domain:    v('domain'),
-    username:  v('username'),
-    password:  v('password'),
-    base_path: v('base_path'),
-    port:      v('port')
+    server:          v('server'),
+    share:           v('share'),
+    domain:          v('domain'),
+    username:        v('username'),
+    password:        v('password'),
+    base_path:       v('base_path'),
+    port:            v('port'),
+    signing_mode:    v('signing_mode'),
+    encryption_mode: v('encryption_mode')
   };
   if (!payload.server || !payload.share) {
     out.innerHTML = '<div class="alert alert-warning">Bitte mindestens <b>Server</b> und <b>Share</b> ausfüllen.</div>';
@@ -287,6 +289,46 @@ const configuration_workflow = () =>
                 type: "Integer",
                 default: 445,
               }),
+              new Field({
+                name: "signing_mode",
+                label: "SMB-Signing",
+                sublabel:
+                  "Wie streng jede Nachricht kryptografisch signiert wird (HMAC-SHA256 für SMB 2.x, AES-128-CMAC für SMB 3.x). " +
+                  "<b>required</b>: Signing wird zwingend verlangt; Verbindung schlägt fehl, wenn der Server nicht signiert. " +
+                  "<b>if-offered</b> (Standard): Signing wird genutzt, wenn der Server es anbietet, sonst weiter ohne. " +
+                  "<b>disabled</b>: kein Signing (nur auswählen, wenn der Server Signing verweigert). " +
+                  "Moderne Samba-Server verlangen häufig Signing → „required“ oder „if-offered“ setzen.",
+                type: "String",
+                required: true,
+                attributes: {
+                  options: [
+                    { value: "if-offered", label: "if-offered (Standard)" },
+                    { value: "required",   label: "required (strikt)" },
+                    { value: "disabled",   label: "disabled (aus)" },
+                  ],
+                },
+                default: "if-offered",
+              }),
+              new Field({
+                name: "encryption_mode",
+                label: "SMB-Verschlüsselung",
+                sublabel:
+                  "Verschlüsselung der Nutzdaten auf dem Draht (AES-128/256-CCM/GCM). " +
+                  "<b>required</b>: Verbindung nur mit Verschlüsselung; scheitert, wenn der Server keine anbietet. " +
+                  "<b>if-offered</b> (Standard): Verschlüsselung wird genutzt, wenn der Server sie anbietet. " +
+                  "<b>disabled</b>: keine Verschlüsselung anfordern (nur für Legacy-Server oder LAN-Only-Setups). " +
+                  "Shares, die serverseitig <code>SMB2_SHAREFLAG_ENCRYPT_DATA</code> tragen, erzwingen Verschlüsselung ohnehin.",
+                type: "String",
+                required: true,
+                attributes: {
+                  options: [
+                    { value: "if-offered", label: "if-offered (Standard)" },
+                    { value: "required",   label: "required (strikt)" },
+                    { value: "disabled",   label: "disabled (aus)" },
+                  ],
+                },
+                default: "if-offered",
+              }),
               new Field({
                 name: "_test_html",
                 label: " ",
@@ -742,6 +784,8 @@ code{background:#f4f4f4;padding:2px 6px;border-radius:3px;word-break:break-all}<
         password: String(body.password || ""),
         base_path: String(body.base_path || "").trim(),
         port: Number(body.port) || 445,
+        signing_mode: String(body.signing_mode || "").trim() || undefined,
+        encryption_mode: String(body.encryption_mode || "").trim() || undefined,
       };
 
       if (!testCfg.server) return jsonError(res, 400, "Please enter a Server (hostname or IP).");
@@ -798,6 +842,14 @@ code{background:#f4f4f4;padding:2px 6px;border-radius:3px;word-break:break-all}<
           hint = "The server may be offering only SMBv1 which this plugin does not support. Enable SMB2 / SMB3 on the Samba server (min protocol = SMB2 in smb.conf).";
         else if (m.includes("traversal") || m.includes("path"))
           hint = "The Base path could not be validated. It must be a relative sub-directory (e.g. 'projects/2026'), never start with / or \\, and must not contain '..'.";
+        else if (m.includes("bad signature") || m.includes("sign_algo") || m.includes("signing"))
+          hint = "Signaturprüfung fehlgeschlagen. Setze in der Plugin-Config unter „SMB-Signing“ auf „if-offered“ oder prüfe auf dem Server, ob AES-CMAC unterstützt wird.";
+        else if (m.includes("pre-auth") || m.includes("preauth"))
+          hint = "Pre-Auth-Integrity fehlgeschlagen. Server und Client müssen SMB 3.1.1 sprechen. Auf Samba: 'server min protocol = SMB3_11' prüfen.";
+        else if (m.includes("encryption") || m.includes("encrypted"))
+          hint = "Verschlüsselungs-Verhandlung fehlgeschlagen. In der Plugin-Config „SMB-Verschlüsselung“ auf „if-offered“ setzen oder den Server so konfigurieren, dass er AES-GCM/CCM anbietet.";
+        else if (code === "ERR_OSSL_EVP_UNSUPPORTED" || m.includes("digital envelope routines"))
+          hint = "Node blockiert Legacy-Cipher. Ab v0.4.0 nutzt das Plugin smb3-client statt @marsaud/smb2 — diese Meldung sollte eigentlich nicht mehr auftreten. Bitte README-Abschnitt zu SMB3-Verbindung prüfen.";
 
         return res.status(200).json({
           ok: false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "saltcorn-samba",
-  "version": "0.3.10",
-  "description": "Saltcorn plugin: browse, upload, rename and delete files on a Samba/CIFS share. File-manager view, directory tree, inline PDF viewer, external-app open (smb://).",
+  "version": "0.4.0",
+  "description": "Saltcorn plugin: browse, upload, rename and delete files on a Samba/CIFS share via SMB 3.1.1 (AES-CMAC signing, optional encryption). File-manager view, directory tree, inline PDF viewer, external-app open (smb://).",
   "main": "index.js",
   "scripts": {
     "test": "node test/sanitize.test.js",
@@ -31,10 +31,10 @@
     "url": "https://github.com/pv-host/saltcorn-samba/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
-    "@marsaud/smb2": "^0.18.0"
+    "smb3-client": "^0.2.0"
   },
   "files": [
     "index.js",

package/smb-client.js

@@ -1,25 +1,53 @@
 /**
- * SMB client wrapper – provides a small, connection-pooled interface
- * around @marsaud/smb2 with security-conscious path handling.
+ * SMB client wrapper — provides a connection-scoped, `fs`-like interface
+ * around the `smb3-client` npm package (SMB 3.1.1 with AES-CMAC signing
+ * and optional AES-GCM encryption).
  *
- * All paths that come from the browser MUST be validated with
- * `sanitizeRelativePath` before being combined with the base_path.
+ * Design notes for v0.4.0:
+ *
+ * 1. Prior versions used `@marsaud/smb2` (SMB 2.0.2 / 2.1 only, tied to the
+ *    unmaintained `ntlm` package that requires DES-ECB and dies on Node 17+
+ *    with OpenSSL 3, and unable to satisfy `server signing = mandatory` on
+ *    modern Samba servers because it lacks AES-CMAC signing).
+ *
+ *    `smb3-client` speaks SMB 2.1 / 3.0 / 3.0.2 / 3.1.1, signs with either
+ *    HMAC-SHA256 or AES-128-CMAC, does SHA-512 pre-auth integrity, has zero
+ *    runtime dependencies, and no DES anywhere.
+ *
+ * 2. `smb3-client` is pure ESM. This plugin is CommonJS. We therefore load
+ *    the module via a cached dynamic `import()` inside an async helper.
+ *
+ * 3. `smb3-client`'s path convention is "<share>/<sub>/<file>" — the share
+ *    name is the FIRST segment of every path passed to `readFile`/`stat`/…
+ *    We keep the plugin's external contract (callers still pass paths that
+ *    are relative to the share root, e.g. "reports/2026/q1.xlsx"), and the
+ *    wrapper prepends the share name and optional base_path.
+ *
+ * 4. All user-supplied path components MUST go through `sanitizeRelativePath`
+ *    and `sanitizeFilename` before being handed to this wrapper. Those
+ *    sanitizers are unchanged from previous versions (tests still cover them).
  */
 
 const path = require("path");
 
-// @marsaud/smb2 is loaded lazily so the pure sanitizer helpers exported by
-// this module can be required (e.g. from unit tests) without needing the
-// native SMB dependency installed.
-let _SMB2 = null;
-function getSMB2() {
-  if (_SMB2) return _SMB2;
-  _SMB2 = require("@marsaud/smb2");
-  return _SMB2;
+// ---------------------------------------------------------------------------
+// Dynamic ESM import cache for smb3-client
+// ---------------------------------------------------------------------------
+//
+// The `smb3-client` package is pure ESM (`"type": "module"`), so we cannot
+// use CommonJS `require()`. Node supports `import()` in CommonJS as a dynamic
+// expression, which returns a Promise. We cache the resolved module.
+let _smb3Module = null;
+async function getSmb3Client() {
+  if (_smb3Module) return _smb3Module;
+  // Use string concatenation so bundlers do not try to statically resolve
+  // this at build time.
+  _smb3Module = await import("smb3-client");
+  return _smb3Module;
 }
 
 // ---------------------------------------------------------------------------
-// Path helpers
+// Path helpers (unchanged from previous versions — covered by unit tests)
 // ---------------------------------------------------------------------------
 
 /**
@@ -33,7 +61,6 @@ function sanitizeFilename(name) {
   if (typeof name !== "string") throw new Error("Filename must be a string");
   const trimmed = name.trim();
   if (!trimmed) throw new Error("Filename must not be empty");
-  // reject leading/trailing whitespace on non-empty names (Windows problem)
   if (name !== trimmed)
     throw new Error("Filename must not start or end with whitespace");
   if (trimmed.length > 255) throw new Error("Filename too long");
@@ -41,12 +68,10 @@ function sanitizeFilename(name) {
     throw new Error("Filename must not be '.' or '..'");
   if (/[\\/]/.test(trimmed)) throw new Error("Filename must not contain slashes");
   if (/[\x00-\x1f]/.test(trimmed)) throw new Error("Filename must not contain control characters");
-  // Reject characters SMB / Windows disallow in filenames
   if (/[<>:"|?*]/.test(trimmed))
     throw new Error('Filename must not contain any of: < > : " | ? *');
   if (trimmed.endsWith(".") || trimmed.endsWith(" "))
     throw new Error("Filename must not end with a dot or space");
-  // Windows reserved device names (case-insensitive, with or without extension)
   const base = trimmed.split(".")[0].toUpperCase();
   const RESERVED = new Set([
     "CON", "PRN", "AUX", "NUL",
@@ -67,15 +92,11 @@ function sanitizeRelativePath(rel) {
   if (typeof rel !== "string") throw new Error("Path must be a string");
   if (rel.length > 4096) throw new Error("Path too long");
   if (rel.includes("\0")) throw new Error("Illegal NUL byte in path");
-  // Convert backslashes to forward slashes first (do NOT collapse yet)
   let p = rel.replace(/\\/g, "/");
-  // Reject Windows drive letters and UNC paths BEFORE collapsing slashes
   if (/^[a-zA-Z]:/.test(p)) throw new Error("Drive letters not allowed");
   if (p.startsWith("//")) throw new Error("UNC paths not allowed");
-  // Now collapse multiple slashes and strip leading slash
   p = p.replace(/\/+/g, "/");
   if (p.startsWith("/")) p = p.slice(1);
-  // Reject explicit traversal segments
   const parts = p.split("/").filter((s) => s !== "" && s !== ".");
   for (const seg of parts) {
     if (seg === "..") throw new Error("Path traversal not allowed");
@@ -83,167 +104,264 @@ function sanitizeRelativePath(rel) {
   return parts.join("/");
 }
 
-/** Convert a POSIX-style relative path into the SMB backslash form. */
+/**
+ * Convert a POSIX-style relative path into the SMB backslash form.
+ * Kept for backwards compatibility — smb3-client itself uses forward
+ * slashes, but external callers (URL builders, logging) may still use
+ * this helper.
+ */
 function toSmbPath(rel) {
   return rel.replace(/\//g, "\\");
 }
 
+// ---------------------------------------------------------------------------
+// Host / port helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a possibly-composite server field into { host, port }.
+ * Tolerant to `host:445` typed into the server field, `[::1]:445` IPv6, and
+ * plain hostnames or bare IPs. Never returns a host string that contains a
+ * colon-port suffix (that would break DNS lookup).
+ */
+function parseHostPort(server, explicitPort) {
+  let host = String(server || "").trim();
+  let port;
+
+  const v6 = host.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (v6) {
+    host = v6[1];
+    if (v6[2]) port = Number(v6[2]);
+  } else {
+    const colonCount = (host.match(/:/g) || []).length;
+    if (colonCount === 1) {
+      const [h, p] = host.split(":");
+      if (h && /^\d+$/.test(p)) {
+        host = h;
+        port = Number(p);
+      }
+    }
+  }
+
+  return {
+    host,
+    port: Number(explicitPort) || port || 445,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Config validation
+// ---------------------------------------------------------------------------
+
+/** Normalise the security-mode fields to smb3-client's vocabulary. */
+function normSecurityMode(v, fallback) {
+  const s = String(v || "").toLowerCase().trim();
+  if (s === "disabled" || s === "if-offered" || s === "required") return s;
+  return fallback;
+}
+
 // ---------------------------------------------------------------------------
 // SMB client factory
 // ---------------------------------------------------------------------------
 
 /**
- * Build a fresh SMB2 client from the plugin configuration.
+ * Build and connect a fresh smb3-client `Client` from the plugin
+ * configuration. Returns a small wrapper object with `fs`-like methods that
+ * accept paths RELATIVE TO THE SHARE ROOT (with `base_path` automatically
+ * prepended). Always call `disconnect()` when done — or use `withClient()`.
  *
  *   config = {
- *     server:   "192.168.1.10",     // host or IP of the samba server
- *     share:    "documents",        // share name (no slashes)
- *     domain:   "WORKGROUP",        // optional
+ *     server:   "192.168.1.10",        // host or IP
+ *     share:    "documents",           // share name (no slashes)
+ *     domain:   "WORKGROUP",           // optional
  *     username: "reader",
  *     password: "secret",
- *     base_path:"",                 // optional subdirectory to lock into
- *     port:     445,                // optional
+ *     base_path:"",                    // optional subdirectory lock
+ *     port:     445,                   // optional
+ *     signing_mode:    "required",     // "disabled" | "if-offered" | "required"
+ *     encryption_mode: "if-offered",   // ditto
  *   }
- *
- * The returned object exposes: readdir(rel), stat(rel), readFile(rel),
- * createReadStream(rel), disconnect(), plus helpers `resolve(rel)` and
- * `basePath`.
  */
-function buildClient(config) {
+async function buildClient(config) {
   if (!config) throw new Error("Samba plugin is not configured");
-  const { server, share, domain, username, password, port } = config;
+  const { server, share, domain, username, password } = config;
   if (!server) throw new Error("Samba: server missing");
   if (!share) throw new Error("Samba: share missing");
-  if (/[\\/]/.test(share)) throw new Error("Samba: share must not contain slashes");
-
-  // Host und Port sauber trennen. Der Server-String darf NICHT im share-UNC-
-  // Pfad landen, sonst versucht Node's DNS "host:port" als Hostnamen aufzulösen
-  // (getaddrinfo ENOTFOUND "1.2.3.4:445"). @marsaud/smb2 nimmt den Port über
-  // die separate `port`-Option entgegen; der share-String enthält nur den Host.
-  //
-  // Zusätzlich tolerant sein, falls jemand versehentlich "host:445" ins
-  // Server-Feld getippt hat — dann Port dort rausziehen.
-  let hostOnly = String(server).trim();
-  let portFromServer;
-  // IPv6-Adressen in eckigen Klammern zulassen: [::1]:445
-  const v6 = hostOnly.match(/^\[([^\]]+)\](?::(\d+))?$/);
-  if (v6) {
-    hostOnly = v6[1];
-    if (v6[2]) portFromServer = Number(v6[2]);
-  } else {
-    // Nur splitten, wenn genau EIN Doppelpunkt — sonst IPv6 ohne Klammern
-    const colonCount = (hostOnly.match(/:/g) || []).length;
-    if (colonCount === 1) {
-      const [h, p] = hostOnly.split(":");
-      if (h && /^\d+$/.test(p)) {
-        hostOnly = h;
-        portFromServer = Number(p);
-      }
-    }
-  }
+  if (/[\\/]/.test(share))
+    throw new Error("Samba: share must not contain slashes");
+
+  const { host, port } = parseHostPort(server, config.port);
+  const signing = normSecurityMode(config.signing_mode, "if-offered");
+  const encryption = normSecurityMode(config.encryption_mode, "if-offered");
+
+  const basePath = sanitizeRelativePath(config.base_path || "");
+  const shareName = String(share).trim();
 
-  const effectivePort = Number(port) || portFromServer || 445;
-  const shareStr = `\\\\${hostOnly}\\${share}`;
-  const SMB2 = getSMB2();
-  const smb = new SMB2({
-    share: shareStr,
-    domain: domain || "WORKGROUP",
-    username: username || "guest",
+  const { Client } = await getSmb3Client();
+  const client = new Client({
+    host,
+    port,
+    domain: domain || "",
+    username: username || "",
     password: password || "",
-    port: effectivePort,
-    autoCloseTimeout: 10000,
+    connectTimeout: 10000,
+    requestTimeout: 30000,
+    signing,
+    encryption,
   });
 
-  const basePath = sanitizeRelativePath(config.base_path || "");
+  await client.connect();
 
-  /** Combine base + user-supplied relative into a validated SMB path. */
-  function resolve(rel) {
+  /**
+   * Combine share + basePath + user-supplied relative into the full
+   * smb3-client-style path ("share/sub/dir/file.ext"), always sanitising
+   * the user input first.
+   */
+  function resolvePath(rel) {
     const safe = sanitizeRelativePath(rel);
-    const combined = [basePath, safe].filter(Boolean).join("/");
-    return toSmbPath(combined);
+    return [shareName, basePath, safe].filter(Boolean).join("/");
+  }
+
+  /**
+   * Convert a smb3-client Dirent + best-effort stat into the shape the
+   * rest of the plugin expects (`name`, `isDirectory` as function OR
+   * boolean, `size`, `mtime`, `birthtime`).
+   *
+   * We fetch stat data in parallel because smb3-client's readdir Dirent
+   * only carries name/isFile/isDirectory. For very large directories this
+   * would fan out into many stat calls — that's an acceptable trade-off
+   * for now; a future release can optimise by using SMB2_QUERY_DIRECTORY's
+   * FileBothDirectoryInformation output directly.
+   */
+  async function enrichEntry(dirent, parentFullPath) {
+    const isDir = !!dirent.isDirectory();
+    const fullPath = parentFullPath
+      ? parentFullPath + "/" + dirent.name
+      : dirent.name;
+    let size = 0;
+    let mtime;
+    let birthtime;
+    try {
+      const st = await client.stat(fullPath);
+      size = Number(st.size || 0);
+      mtime = st.mtime;
+      birthtime = st.ctime;
+    } catch (_) {
+      // Non-fatal; return whatever we already have.
+    }
+    return {
+      name: dirent.name,
+      isDirectory: isDir,
+      size,
+      mtime,
+      birthtime,
+    };
   }
 
   return {
+    /** Share name, exposed for URL building / logging. */
+    shareName,
+    /** Sanitised base path (may be ""). */
     basePath,
-    resolve,
-    readdir(rel) {
-      return new Promise((res, rej) => {
-        smb.readdir(resolve(rel), { stats: true }, (err, files) =>
-          err ? rej(err) : res(files)
+    /** Underlying smb3-client Client — do not use unless you know why. */
+    _raw: client,
+
+    /**
+     * List a directory (share root by default). Returns an array of objects
+     * shaped like the legacy `@marsaud/smb2` output so index.js does not need
+     * to change: `{ name, isDirectory, size, mtime, birthtime }`.
+     */
+    async readdir(rel) {
+      const full = resolvePath(rel);
+      const dirents = await client.readdir(full, { withFileTypes: true });
+      // Parallel enrichment. Bounded to a reasonable concurrency to avoid
+      // saturating the SMB session on huge directories.
+      const CHUNK = 16;
+      const result = [];
+      for (let i = 0; i < dirents.length; i += CHUNK) {
+        const slice = dirents.slice(i, i + CHUNK);
+        const enriched = await Promise.all(
+          slice.map((d) => enrichEntry(d, full))
         );
-      });
+        result.push(...enriched);
+      }
+      return result;
     },
-    stat(rel) {
-      return new Promise((res, rej) => {
-        // marsaud-smb2 does not export a proper stat; emulate via readdir of parent
-        const target = resolve(rel);
-        const parent = target.includes("\\")
-          ? target.slice(0, target.lastIndexOf("\\"))
-          : "";
-        const name = target.includes("\\")
-          ? target.slice(target.lastIndexOf("\\") + 1)
-          : target;
-        smb.readdir(parent, { stats: true }, (err, files) => {
-          if (err) return rej(err);
-          const match = files.find((f) => f.name === name);
-          if (!match) return rej(new Error("Not found"));
-          res(match);
-        });
-      });
+
+    /** Stat a single file/directory (name-relative-to-share/basePath). */
+    async stat(rel) {
+      const full = resolvePath(rel);
+      const st = await client.stat(full);
+      // Return a shape compatible with the old readdir-emulated stat.
+      return {
+        name: full.split("/").pop(),
+        size: Number(st.size || 0),
+        mtime: st.mtime,
+        birthtime: st.ctime,
+        isDirectory: !!st.isDirectory,
+        isFile: !!st.isFile,
+      };
     },
-    readFile(rel) {
-      return new Promise((res, rej) => {
-        smb.readFile(resolve(rel), (err, data) =>
-          err ? rej(err) : res(data)
-        );
-      });
+
+    /** Read the full content of a file into a Buffer. */
+    async readFile(rel) {
+      return await client.readFile(resolvePath(rel));
     },
-    writeFile(rel, data) {
-      return new Promise((res, rej) => {
-        smb.writeFile(resolve(rel), data, (err) =>
-          err ? rej(err) : res()
-        );
-      });
+
+    /** Create or overwrite a file with the given Buffer / string. */
+    async writeFile(rel, data) {
+      return await client.writeFile(resolvePath(rel), data);
     },
-    exists(rel) {
-      return new Promise((res) => {
-        smb.exists(resolve(rel), (err, ok) => res(err ? false : !!ok));
-      });
+
+    /** Check whether a path exists (never throws). */
+    async exists(rel) {
+      try {
+        await client.stat(resolvePath(rel));
+        return true;
+      } catch (_) {
+        return false;
+      }
     },
-    unlink(rel) {
-      return new Promise((res, rej) => {
-        smb.unlink(resolve(rel), (err) => (err ? rej(err) : res()));
-      });
+
+    /** Delete a single file. */
+    async unlink(rel) {
+      return await client.rm(resolvePath(rel));
     },
-    rmdir(rel) {
-      return new Promise((res, rej) => {
-        smb.rmdir(resolve(rel), (err) => (err ? rej(err) : res()));
-      });
+
+    /** Remove an empty directory. */
+    async rmdir(rel) {
+      return await client.rmdir(resolvePath(rel));
     },
-    mkdir(rel) {
-      return new Promise((res, rej) => {
-        smb.mkdir(resolve(rel), (err) => (err ? rej(err) : res()));
-      });
+
+    /** Create a directory (non-recursive). */
+    async mkdir(rel) {
+      return await client.mkdir(resolvePath(rel));
     },
-    rename(oldRel, newRel) {
-      return new Promise((res, rej) => {
-        smb.rename(resolve(oldRel), resolve(newRel), (err) =>
-          err ? rej(err) : res()
-        );
-      });
+
+    /** Rename (or move within the same share). */
+    async rename(oldRel, newRel) {
+      return await client.rename(resolvePath(oldRel), resolvePath(newRel));
     },
+
+    /**
+     * Streaming read — returns a Node Readable. Note: unlike the callback-
+     * based old API this is synchronous (smb3-client's own signature).
+     */
     createReadStream(rel) {
-      return new Promise((res, rej) => {
-        smb.createReadStream(resolve(rel), (err, stream) =>
-          err ? rej(err) : res(stream)
-        );
-      });
+      return client.createReadStream(resolvePath(rel));
+    },
+
+    /** Streaming write. */
+    createWriteStream(rel) {
+      return client.createWriteStream(resolvePath(rel));
     },
-    disconnect() {
+
+    /** Tear down the SMB session and TCP socket. Always await this. */
+    async disconnect() {
       try {
-        smb.disconnect();
+        await client.close();
       } catch (_) {
-        // ignore
+        // ignore — best-effort teardown
       }
     },
   };
@@ -252,14 +370,15 @@ function buildClient(config) {
 /**
  * Execute a callback with a fresh SMB client and always disconnect afterwards.
  * Prefer this helper over building a long-lived client because SMB sessions
- * can time out and marsaud-smb2 does not handle reconnects well.
+ * time out on idle and smb3-client does not currently expose a reconnect
+ * primitive.
  */
 async function withClient(config, fn) {
-  const client = buildClient(config);
+  const client = await buildClient(config);
   try {
     return await fn(client);
   } finally {
-    client.disconnect();
+    await client.disconnect();
   }
 }