saltcorn-samba 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.3.5] – 2026-07-05
+
+### Added
+- **Testverbindung im Konfigurations-Wizard.**
+  Auf Schritt 1 „Samba-Server“ gibt es jetzt einen Button
+  „→ Verbindung jetzt testen“. Er öffnet eine SMB-Sitzung mit den
+  aktuell im Formular stehenden Werten (ohne zu speichern), meldet den
+  Benutzer an und listet die Wurzel bzw. den Basispfad des Shares auf.
+  Bei Erfolg werden Dauer, Anzahl Einträge und die ersten 20 Namen
+  angezeigt; bei Fehlschlag der genaue SMB-Fehler plus konkreter
+  Handlungshinweis auf Deutsch (z. B. DNS, ECONNREFUSED, LOGON_FAILURE,
+  BAD_NETWORK_NAME, SMBv1).
+- **Neue Route `POST /sambatest` (nur Admin).** Nimmt die Serverdaten
+  als JSON entgegen, gibt strukturiertes Ergebnis mit `ok`, `error`,
+  `code`, `hint`, `attempted` zurück. Verändert keine Konfiguration.
+
+### Changed
+- **Alle Feld-Beschreibungen in Schritt 1 komplett neu, ausführlich
+  auf Deutsch.** Jedes Feld (Server, Freigabe, Domäne, Benutzer,
+  Passwort, Basispfad, Port) erklärt Format, Docker-Fallstricke,
+  Standardwerte und typische Fehlerquellen. Schritt 2 ebenfalls
+  vollständig lokalisiert.
+- Schritt-Namen: „Samba server“ → „Samba-Server“, „Access & permissions“
+  → „Zugriff & Berechtigungen“.
+
+## [0.3.4] – 2026-07-05
+
+### Fixed
+- **`function is not iterable` beim Installieren behoben.**
+  In v0.3.3 hatte ich überkompensiert: der Manifest-Key `dependencies`
+  wurde in eine Factory-Funktion umgewandelt — Saltcorn liest `dependencies`
+  jedoch NICHT über `withCfg`, sondern iteriert es direkt mit `for..of`
+  ([`saltcorn-data/models/plugin.ts` Zeile 638](https://github.com/saltcorn/saltcorn/blob/master/packages/saltcorn-data/models/plugin.ts)).
+  Deshalb muss `dependencies` ein statisches Array bleiben. Alle anderen
+  Keys (viewtemplates, routes, headers) werden weiterhin über `withCfg`
+  gelesen und bleiben Factory-Funktionen. Ein ausführlicher Header-Kommentar
+  über `module.exports` dokumentiert nun beide Zugriffsmuster.
+
 ## [0.3.3] – 2026-07-05
 
 ### Fixed

package/README.md

@@ -98,20 +98,22 @@ docker exec -it <saltcorn-container> \
 Nach der Installation unter *Einstellungen → Plugins → saltcorn-samba →
 Configure* ausfüllen. Die Konfiguration ist zweistufig:
 
-### Schritt 1 — *Samba server*
+### Schritt 1 — *Samba-Server*
 
 | Feld | Beispiel | Beschreibung |
 |---|---|---|
-| Server | `192.168.1.10` | Hostname oder IP des Samba-Servers |
-| Share name | `documents` | Name des Shares (ohne Slashes) |
-| Domain / Workgroup | `WORKGROUP` | optional |
-| Username | `saltcorn-user` | SMB-Benutzer |
-| Password | *(secret)* | wird im Saltcorn-Konfigstore gespeichert |
-| Base path | `projects` | *optional* — beschränkt jeden Zugriff auf dieses Unterverzeichnis |
-| Port | `445` | Standard-SMB2-Port |
-| SMB host visible to clients | `fileserver.lan` | *optional* — Host, der in `smb://`-Links auftaucht (nützlich in Docker) |
+| **Server** | `192.168.1.20`, `nas01`, `fileserver.local` | Hostname oder IP des Samba-Servers, **ohne** `smb://`-Präfix und **ohne** Backslashes. Muss aus Sicht des Saltcorn-Prozesses auflösbar sein. **In Docker:** nicht `localhost` verwenden – stattdessen LAN-IP des Hosts oder Container ins passende Netzwerk hängen. |
+| **Freigabe / Share-Name** | `daten`, `public`, `projekte` | Name der SMB-Freigabe **ohne** Slashes. Auf dem Server als `[NAME]`-Abschnitt in `smb.conf` bzw. unter Windows als Freigabename sichtbar. Nicht die Ordner-Bezeichnung. |
+| **Domäne / Arbeitsgruppe** | `WORKGROUP`, `CONTOSO` | Meist `WORKGROUP` (Standard). Für Active Directory: NetBIOS-Name der Domäne, nicht der FQDN. |
+| **Benutzername** | `saltcorn` | Samba-/AD-Benutzer, **nicht** im Format `DOMAIN\user` (Domäne gehört in das eigene Feld). Leer lassen für anonymen Zugriff (nur bei `guest ok = yes`). |
+| **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. |
 
-### Schritt 2 — *Access & permissions*
+> **Tipp:** Bevor Sie speichern, klicken Sie auf **„→ Verbindung jetzt
+> testen“** – siehe Abschnitt [Verbindung testen](#verbindung-testen).
+
+### Schritt 2 — *Zugriff & Berechtigungen*
 
 | Feld | Default | Beschreibung |
 |---|---|---|
@@ -129,7 +131,37 @@ Configure* ausfüllen. Die Konfiguration ist zweistufig:
 - Nur die Features aktivieren, die wirklich gebraucht werden.
 - Auf dem Samba-Server einen separaten Nutzer mit passenden Rechten anlegen
   (read-only wenn nur gelesen werden soll).
-- Zusätzlich mit *Base path* den Zugriff auf ein Unterverzeichnis begrenzen.
+- Zusätzlich mit *Basispfad* den Zugriff auf ein Unterverzeichnis begrenzen.
+
+### Verbindung testen
+
+Direkt im Konfigurations-Wizard (Schritt 1) gibt es den Button
+**„→ Verbindung jetzt testen“**. Er sendet die aktuell im Formular
+stehenden Werte an die interne Route `POST /sambatest` (nur für Admins),
+baut eine SMB-Verbindung auf und listet den Basispfad bzw. die
+Share-Wurzel auf. Es werden dabei **keine** Daten gespeichert oder
+geschrieben.
+
+- **Erfolg (grün):** Dauer der Verbindung, Anzahl gefundener Einträge
+  und die ersten 20 Namen (Datei/Ordner) werden angezeigt.
+- **Fehler (rot):** Der SMB-/Netzwerk-Fehler wird im Klartext gezeigt,
+  zusammen mit einem konkreten Handlungshinweis auf Deutsch, z. B.:
+  - `ECONNREFUSED` → Samba läuft nicht oder Firewall/Docker blockt 445
+  - `ETIMEDOUT` → Host nicht erreichbar (Ping/`nc -vz`)
+  - `ENOTFOUND` → DNS-Auflösung fehlgeschlagen (IP verwenden)
+  - `LOGON_FAILURE` / `ACCESS_DENIED` → Benutzer, Passwort oder Domäne falsch
+  - `BAD_NETWORK_NAME` → Share-Name existiert so nicht auf dem Server
+  - `SMB1 / protocol` → Server bietet nur SMBv1 an (nicht unterstützt)
+
+Die Route kann zusätzlich auch von Skripten aufgerufen werden:
+
+```bash
+curl -X POST -H 'Content-Type: application/json' \
+  -H "X-CSRF-Token: $CSRF" \
+  --cookie "$COOKIES" \
+  -d '{"server":"192.168.1.20","share":"daten","username":"u","password":"p"}' \
+  https://saltcorn.example.com/sambatest
+```
 
 ---
 

package/index.js

@@ -54,103 +54,262 @@ const DEFAULT_DENIED_EXT = [
 // Plugin configuration
 // ---------------------------------------------------------------------------
 
+// HTML block injected as first "field" of step 1 — Saltcorn renders fields
+// with type="String" and input_type="custom_html" as raw HTML. This gives
+// admins a Test-Verbindung button next to the form itself.
+const CONNECTION_TEST_HTML = `
+<div class="card mb-3" style="border-left:4px solid #0d6efd">
+  <div class="card-body">
+    <h5 class="card-title" style="margin-top:0">Verbindung testen</h5>
+    <p class="card-text" style="margin-bottom:.6rem">
+      Prüfen Sie die eingegebenen Zugangsdaten <b>bevor</b> Sie speichern.
+      Der Test öffnet eine SMB-Verbindung zum Server, meldet den angegebenen
+      Benutzer an und listet das Wurzel-Verzeichnis des Shares (bzw. den
+      Basispfad, falls angegeben) auf. Es werden keine Daten geschrieben.
+    </p>
+    <button type="button" class="btn btn-primary" onclick="sambaTestConn(this)">
+      → Verbindung jetzt testen
+    </button>
+    <div id="sambaTestOut" style="margin-top:.8rem"></div>
+  </div>
+</div>
+<script>
+window.sambaTestConn = async function(btn) {
+  var out = document.getElementById('sambaTestOut');
+  var form = btn.closest('form');
+  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')
+  };
+  if (!payload.server || !payload.share) {
+    out.innerHTML = '<div class="alert alert-warning">Bitte mindestens <b>Server</b> und <b>Share</b> ausfüllen.</div>';
+    return;
+  }
+  var csrf = (document.querySelector('meta[name="csrf-token"]') || {}).content || '';
+  btn.disabled = true;
+  var oldTxt = btn.textContent;
+  btn.textContent = 'Teste …';
+  out.innerHTML = '<div class="text-muted">Verbindung wird aufgebaut … (bis zu 30 s)</div>';
+  try {
+    var r = await fetch('/sambatest', {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrf, 'CSRF-Token': csrf },
+      body: JSON.stringify(payload)
+    });
+    var data = await r.json();
+    if (data && data.ok) {
+      var rows = (data.entries||[]).map(function(e){
+        return '<li>'+ (e.isDirectory?'📁 ':'📄 ') + String(e.name).replace(/[<>&]/g,'?') +'</li>';
+      }).join('');
+      out.innerHTML =
+        '<div class="alert alert-success">' +
+          '<b>✓ Verbindung erfolgreich</b> (' + data.duration_ms + ' ms)<br>' +
+          'Server: <code>' + data.server + ':' + data.port + '</code>, Share: <code>' + data.share + '</code>, ' +
+          'Basispfad: <code>' + data.base_path + '</code>, Benutzer: <code>' + data.username + '</code><br>' +
+          'Einträge gefunden: <b>' + data.entry_count + '</b>' + (data.truncated ? ' (erste 20 unten)' : '') +
+          (rows ? '<ul style="margin:.5rem 0 0 1rem">' + rows + '</ul>' : '') +
+        '</div>';
+    } else {
+      var a = data && data.attempted || {};
+      out.innerHTML =
+        '<div class="alert alert-danger">' +
+          '<b>✗ Verbindung fehlgeschlagen</b><br>' +
+          'Fehler: <code>' + String(data && data.error || 'Unbekannt').replace(/[<>&]/g,'?') + '</code>' +
+          (data && data.code ? ' <span class="text-muted">(' + data.code + ')</span>' : '') + '<br>' +
+          (data && data.hint ? '<div style="margin-top:.4rem"><b>Hinweis:</b> ' + String(data.hint).replace(/[<>&]/g,'?') + '</div>' : '') +
+          '<details style="margin-top:.4rem"><summary>Versuchte Verbindungsdaten</summary>' +
+          '<table class="table table-sm" style="margin-top:.4rem">' +
+          '<tr><td>Server</td><td><code>' + (a.server||'') + ':' + (a.port||'') + '</code></td></tr>' +
+          '<tr><td>Share</td><td><code>' + (a.share||'') + '</code></td></tr>' +
+          '<tr><td>Basispfad</td><td><code>' + (a.base_path||'') + '</code></td></tr>' +
+          '<tr><td>Domäne</td><td><code>' + (a.domain||'') + '</code></td></tr>' +
+          '<tr><td>Benutzer</td><td><code>' + (a.username||'') + '</code></td></tr>' +
+          '</table></details>' +
+        '</div>';
+    }
+  } catch (e) {
+    out.innerHTML = '<div class="alert alert-danger">Fehler beim Aufruf von /sambatest: ' +
+      String(e && e.message || e).replace(/[<>&]/g,'?') + '</div>';
+  } finally {
+    btn.disabled = false;
+    btn.textContent = oldTxt;
+  }
+};
+</script>
+`;
+
 const configuration_workflow = () =>
   new Workflow({
     steps: [
       {
-        name: "Samba server",
+        name: "Samba-Server",
         form: () =>
           new Form({
             fields: [
               new Field({
                 name: "server",
-                label: "Server",
-                sublabel: "Hostname or IP of the Samba server (no smb:// prefix)",
+                label: "Server (Hostname oder IP)",
+                sublabel:
+                  "Adresse des Samba-Servers <b>ohne</b> smb://-Präfix und ohne Backslashes. " +
+                  "Beispiele: <code>192.168.1.20</code>, <code>fileserver.local</code>, <code>nas01</code>. " +
+                  "Läuft Saltcorn in Docker, ist <code>localhost</code> → der Container selbst; nutzen Sie die LAN-IP " +
+                  "des Host-Systems (nicht 127.0.0.1) oder verbinden Sie den Container ins gleiche Bridge/Host-Netzwerk. " +
+                  "Der Hostname muss <b>aus Sicht des Saltcorn-Prozesses</b> auflösbar sein.",
                 type: "String",
                 required: true,
               }),
               new Field({
                 name: "share",
-                label: "Share name",
-                sublabel: "The share to connect to (without slashes)",
+                label: "Freigabe / Share-Name",
+                sublabel:
+                  "Name der SMB-Freigabe <b>ohne</b> Schrägstriche. Auf dem Server sichtbar als <code>[NAME]</code>-Abschnitt " +
+                  "in <code>/etc/samba/smb.conf</code> oder unter Windows als Freigabe-Name. " +
+                  "Beispiele: <code>daten</code>, <code>public</code>, <code>projekte</code>. " +
+                  "Nicht die Ordner-Bezeichnung, sondern der Freigabe-Name eingeben.",
                 type: "String",
                 required: true,
               }),
-              new Field({ name: "domain", label: "Domain / Workgroup", type: "String", default: "WORKGROUP" }),
-              new Field({ name: "username", label: "Username", type: "String" }),
-              new Field({ name: "password", label: "Password", type: "String", input_type: "password" }),
+              new Field({
+                name: "domain",
+                label: "Domäne / Arbeitsgruppe",
+                sublabel:
+                  "Windows-Domäne oder Arbeitsgruppe des Benutzers. " +
+                  "Für klassische Samba-Server im Heim-/Firmennetz meist <code>WORKGROUP</code> (Standard). " +
+                  "Für Active Directory: NetBIOS-Name der Domäne, z. B. <code>CONTOSO</code>. Nicht der FQDN.",
+                type: "String",
+                default: "WORKGROUP",
+              }),
+              new Field({
+                name: "username",
+                label: "Benutzername",
+                sublabel:
+                  "Samba-/AD-Benutzer, unter dem gelesen und (je nach Rechten) geschrieben wird. " +
+                  "<b>Nicht</b> im Format <code>DOMÄNE\\user</code> – die Domäne gehört oben ins eigene Feld. " +
+                  "Leer lassen für anonymen Zugriff (nur möglich, wenn der Share <code>guest ok = yes</code> erlaubt).",
+                type: "String",
+              }),
+              new Field({
+                name: "password",
+                label: "Passwort",
+                sublabel:
+                  "Passwort des Samba-Benutzers. Wird verschlüsselt in der Saltcorn-Datenbank abgelegt. " +
+                  "<b>Wichtig:</b> Samba nutzt ein eigenes Passwort (<code>smbpasswd</code>), nicht zwingend das Linux-Login-Passwort. " +
+                  "Moderne Samba-Server lehnen leere Passwörter ab.",
+                type: "String",
+                input_type: "password",
+              }),
               new Field({
                 name: "base_path",
-                label: "Base path",
-                sublabel: "Optional. All access is restricted to this sub-directory of the share.",
+                label: "Basispfad (optional)",
+                sublabel:
+                  "Beschränkt sämtlichen Zugriff auf ein Unterverzeichnis der Freigabe. " +
+                  "Relativ, mit Schrägstrichen, <b>ohne</b> führenden Slash. " +
+                  "Beispiel: <code>projekte/2026</code> → der File-Manager sieht nur diesen Unterordner und alles darin. " +
+                  "Leer lassen für die komplette Share-Wurzel. <code>..</code> und absolute Pfade werden abgelehnt.",
                 type: "String",
               }),
-              new Field({ name: "port", label: "Port", type: "Integer", default: 445 }),
+              new Field({
+                name: "port",
+                label: "TCP-Port",
+                sublabel:
+                  "SMB-Port des Servers. Standard: <code>445</code> (SMB2/3 über TCP). " +
+                  "Nur ändern, wenn Ihr Server bewusst auf einem anderen Port läuft. " +
+                  "<b>SMBv1 (Port 139/NetBIOS) wird nicht unterstützt</b> – aktivieren Sie SMB2+ auf dem Server " +
+                  "(<code>min protocol = SMB2</code> in smb.conf).",
+                type: "Integer",
+                default: 445,
+              }),
+              new Field({
+                name: "_test_html",
+                label: " ",
+                input_type: "custom_html",
+                attributes: { html: CONNECTION_TEST_HTML },
+              }),
             ],
           }),
       },
       {
-        name: "Access & permissions",
+        name: "Zugriff & Berechtigungen",
         form: () =>
           new Form({
             fields: [
               new Field({
                 name: "min_role_read",
-                label: "Minimum role to read files",
-                sublabel: "Saltcorn role level. 1=admin, 40=staff, 80=user, 100=public. Default: 80.",
+                label: "Mindestrolle für Lesen",
+                sublabel:
+                  "Saltcorn-Rolle, die mindestens nötig ist, um Dateien und Verzeichnisse anzusehen. " +
+                  "Werte: <code>1</code>=Admin, <code>40</code>=Staff, <code>80</code>=User, <code>100</code>=Public. " +
+                  "Kleinere Zahl = höhere Rolle. Standard: <code>80</code> (alle angemeldeten Benutzer).",
                 type: "Integer",
                 default: 80,
               }),
               new Field({
                 name: "min_role_write",
-                label: "Minimum role to upload / delete / rename",
+                label: "Mindestrolle für Upload / Löschen / Umbenennen",
                 sublabel:
-                  "Set to 100 to disable all write actions completely. Default: 40 (staff and admins).",
+                  "Setzen Sie auf <code>100</code>, um <b>alle</b> Schreibaktionen komplett zu deaktivieren – auch wenn die " +
+                  "Checkboxen unten aktiv sind. Standard: <code>40</code> (nur Staff und Admin).",
                 type: "Integer",
                 default: 40,
               }),
               new Field({
                 name: "allow_upload",
-                label: "Allow file upload",
+                label: "Datei-Upload erlauben",
+                sublabel: "Zeigt den Upload-Button und aktiviert POST /sambaupload.",
                 type: "Bool",
                 default: false,
               }),
               new Field({
                 name: "allow_delete",
-                label: "Allow delete",
+                label: "Löschen erlauben",
+                sublabel: "Erlaubt das Löschen von Dateien und leeren Verzeichnissen.",
                 type: "Bool",
                 default: false,
               }),
               new Field({
                 name: "allow_rename",
-                label: "Allow rename / move",
+                label: "Umbenennen / Verschieben erlauben",
+                sublabel: "Erlaubt Umbenennen und Verschieben innerhalb des Basispfads.",
                 type: "Bool",
                 default: false,
               }),
               new Field({
                 name: "allow_mkdir",
-                label: "Allow creating new directories",
+                label: "Neue Verzeichnisse anlegen erlauben",
+                sublabel: "Zeigt den „Neuer Ordner“-Button in der File-Manager-Ansicht.",
                 type: "Bool",
                 default: false,
               }),
               new Field({
                 name: "max_upload_mb",
-                label: "Max upload size per file (MiB)",
+                label: "Max. Upload-Größe pro Datei (MiB)",
+                sublabel: "Serverseitige Obergrenze pro Datei. Standard: 50 MiB.",
                 type: "Integer",
                 default: 50,
               }),
               new Field({
                 name: "denied_extensions",
-                label: "Blocked file extensions (comma-separated, no dots)",
+                label: "Gesperrte Datei-Endungen (komma-getrennt, ohne Punkte)",
                 sublabel:
-                  "Default: exe,bat,cmd,com,msi,scr,vbs,js,jse,wsf,wsh,ps1,ps1xml,psm1,sh,bash,zsh. Leave empty for the default set.",
+                  "Standard: <code>exe,bat,cmd,com,msi,scr,vbs,js,jse,wsf,wsh,ps1,ps1xml,psm1,sh,bash,zsh</code>. " +
+                  "Leer lassen für die Standard-Liste.",
                 type: "String",
               }),
               new Field({
                 name: "public_smb_host",
-                label: "SMB host visible to clients",
+                label: "Für Clients sichtbarer SMB-Hostname (optional)",
                 sublabel:
-                  "Optional. Host used in generated smb:// links. Defaults to the server field. Useful when Saltcorn runs in Docker but clients should see the LAN name.",
+                  "Wird in erzeugten <code>smb://</code>-Links verwendet. Standard: der Wert aus dem Feld <b>Server</b>. " +
+                  "Nützlich, wenn Saltcorn in Docker läuft (Server = interne IP), Clients aber den LAN-Namen sehen sollen " +
+                  "(z. B. <code>fileserver.local</code>).",
                 type: "String",
               }),
             ],
@@ -369,6 +528,107 @@ code{background:#f4f4f4;padding:2px 6px;border-radius:3px;word-break:break-all}<
     },
   },
 
+  // ---- Connection test (admin only) --------------------------------------
+  //
+  // POST /sambatest
+  // Body (JSON): { server, share, domain, username, password, base_path, port }
+  // Returns: { ok, server, share, base_path, entries?: [{name,isDirectory}],
+  //            error?, code?, hint? }
+  //
+  // The route accepts values straight from the config form so admins can
+  // verify the connection BEFORE saving. It never touches the persisted
+  // configuration and is restricted to role_id === 1 (admin).
+  {
+    url: "/sambatest",
+    method: "post",
+    callback: async ({ req, res }) => {
+      if (roleOf(req) !== 1) {
+        return jsonError(res, 403, "Only admins can test the connection.");
+      }
+      const body = (req.body && typeof req.body === "object") ? req.body : {};
+      const testCfg = {
+        server: String(body.server || "").trim(),
+        share: String(body.share || "").trim(),
+        domain: String(body.domain || "").trim() || "WORKGROUP",
+        username: String(body.username || "").trim(),
+        password: String(body.password || ""),
+        base_path: String(body.base_path || "").trim(),
+        port: Number(body.port) || 445,
+      };
+
+      if (!testCfg.server) return jsonError(res, 400, "Please enter a Server (hostname or IP).");
+      if (!testCfg.share) return jsonError(res, 400, "Please enter a Share name.");
+
+      const started = Date.now();
+      try {
+        const listing = await withClient(testCfg, async (client) => {
+          // If base_path is set, list it — that also verifies traversal.
+          const rel = testCfg.base_path ? sanitizeRelativePath(testCfg.base_path) : "";
+          return await client.readdir(rel);
+        });
+        const took = Date.now() - started;
+        return res.json({
+          ok: true,
+          server: testCfg.server,
+          share: testCfg.share,
+          base_path: testCfg.base_path || "(share root)",
+          port: testCfg.port,
+          domain: testCfg.domain,
+          username: testCfg.username || "(anonymous)",
+          duration_ms: took,
+          entry_count: Array.isArray(listing) ? listing.length : 0,
+          entries: (Array.isArray(listing) ? listing : []).slice(0, 20).map((e) => ({
+            name: e && (e.name || e),
+            isDirectory: !!(e && (e.isDirectory === true || (e.stats && e.stats.isDirectory && e.stats.isDirectory()))),
+          })),
+          truncated: Array.isArray(listing) && listing.length > 20,
+        });
+      } catch (err) {
+        // Turn opaque SMB / socket errors into actionable hints.
+        const msg = String((err && err.message) || err || "Unknown error");
+        const code = (err && (err.code || err.errno)) || null;
+        let hint = null;
+        const m = msg.toLowerCase();
+        if (code === "ECONNREFUSED" || m.includes("econnrefused"))
+          hint = "The server refused the connection on port " + testCfg.port +
+            ". Check that Samba is running and that a firewall (or Docker) does not block TCP/445.";
+        else if (code === "ETIMEDOUT" || m.includes("etimedout") || m.includes("timed out"))
+          hint = "Timeout — the host did not respond. Verify Server address and that it is reachable from the Saltcorn host (try: ping / nc -vz " + testCfg.server + " " + testCfg.port + ").";
+        else if (code === "ENOTFOUND" || code === "EAI_AGAIN" || m.includes("getaddrinfo"))
+          hint = "DNS lookup failed for '" + testCfg.server + "'. Use an IP address or make sure the hostname resolves from inside the Saltcorn container.";
+        else if (code === "EHOSTUNREACH" || m.includes("ehostunreach"))
+          hint = "No route to host. Check network / VPN / bridged Docker network.";
+        else if (m.includes("logon_failure") || m.includes("nt_status_logon_failure") || m.includes("access_denied") || m.includes("nt_status_access_denied"))
+          hint = "Login rejected. Check Username, Password and Domain / Workgroup. On modern Samba servers, empty passwords are usually disabled.";
+        else if (m.includes("bad_network_name") || m.includes("nt_status_bad_network_name"))
+          hint = "The share '" + testCfg.share + "' does not exist on " + testCfg.server + ". Check spelling and the [share] section in smb.conf.";
+        else if (m.includes("account_disabled") || m.includes("account_locked"))
+          hint = "The user account is disabled or locked on the Samba server.";
+        else if (m.includes("password_expired") || m.includes("password_must_change"))
+          hint = "The password must be changed before this account can be used.";
+        else if (m.includes("smb1") || m.includes("protocol"))
+          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 '..'.";
+
+        return res.status(200).json({
+          ok: false,
+          error: msg,
+          code,
+          hint,
+          attempted: {
+            server: testCfg.server,
+            share: testCfg.share,
+            port: testCfg.port,
+            domain: testCfg.domain,
+            username: testCfg.username || "(anonymous)",
+            base_path: testCfg.base_path || "(share root)",
+          },
+        });
+      }
+    },
+  },
+
   // ---- Write routes (v0.3.0) --------------------------------------------
 
   {
@@ -608,27 +868,48 @@ function wrapView(v) {
 // ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
-// IMPORTANT: how Saltcorn iterates the manifest
+// IMPORTANT: how Saltcorn reads the manifest
 // ---------------------------------------------------------------------------
-// When a plugin exports `configuration_workflow`, Saltcorn's state loader
-// treats EVERY other manifest key as a factory function and calls it with the
-// current plugin configuration — see
-// packages/saltcorn-data/db/state.ts `withCfg` (`plugin[key](cfg || {})`).
-// So each key below must be a function that returns the value, otherwise
-// Node throws `plugin[key] is not a function`. The only exceptions are the
-// bookkeeping keys `sc_plugin_api_version` and `configuration_workflow`
-// itself, which the loader accesses directly.
+// Two access patterns coexist in Saltcorn's plugin loader:
+//
+// 1. `withCfg(key)` in `saltcorn-data/db/state.ts` — when a plugin exports
+//    `configuration_workflow`, this helper calls `plugin[key](cfg)` and then
+//    iterates the return value. Any key it consults MUST therefore be a
+//    factory function that returns the real value.
+//    Keys consumed via `withCfg`: types, viewtemplates, functions,
+//    modelpatterns, fileviews, actions, eventTypes, fonts, icons,
+//    table_providers, authentication, exchange, copilot_skills,
+//    external_tables, headers, routes, capacitor_plugins.
+//
+// 2. Direct property access in `saltcorn-data/models/plugin.ts` — the
+//    loader reads a handful of keys straight off the module, WITHOUT going
+//    through `withCfg`. Those must be the raw value (not a function).
+//    Direct-access keys: dependencies (for..of loop), onLoad (called as fn),
+//    authentication (truthy check + later withCfg), user_config_form,
+//    plugin_name (string), layout / types / functions / viewtemplates
+//    (truthy checks in the plugin-store info card).
+//
+// The intersection is where confusion lives:
+// - `dependencies` is read *directly* as an iterable and MUST be an array.
+// - `viewtemplates`, `routes`, `headers` etc. are read via `withCfg` and
+//   MUST be functions when `configuration_workflow` is present.
+//
+// See:
+//   https://github.com/saltcorn/saltcorn/blob/master/packages/saltcorn-data/db/state.ts
+//   https://github.com/saltcorn/saltcorn/blob/master/packages/saltcorn-data/models/plugin.ts
 // ---------------------------------------------------------------------------
 
 module.exports = {
   sc_plugin_api_version: 1,
   configuration_workflow,
+  // The four keys below are consumed via `withCfg` → must be factory fns.
   viewtemplates: () => [wrapView(fileManagerView), wrapView(treeView)],
   routes: () => routes,
   headers: () => [
     { css: `/plugins/public/${PLUGIN_NAME}/samba.css` },
   ],
-  dependencies: () => [],
+  // `dependencies` is iterated directly (for..of) → must be a raw array.
+  dependencies: [],
 };
 
 // Note: the `samba_pdf` fieldview shipped in v0.1–0.3.1 has been removed from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saltcorn-samba",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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://).",
   "main": "index.js",
   "scripts": {