# Synology NAS — KDE Plasma 6 widget

A system-tray widget for **KDE Plasma 6** that lets you browse and mount your
**Synology** (or any **SMB/CIFS**) network shares the same way Plasma Vaults
handles encrypted vaults: click the tray icon, and a popup lists each configured
host with its shares — mount or unmount any of them with one click.

- Add **multiple** NAS / SMB hosts.
- Auto-discovers each host's shared folders with `smbclient`.
- Mounts real **kernel CIFS** mounts (visible to every app, not just Dolphin).
- Passwords are kept in **KWallet**, never in plain config.
- Privileged mounting is done through a tiny **polkit**-authorized helper — no
  passwordless-sudo hacks, no editing `/etc/fstab`.

> Works with any SMB server. "Synology" is just the friendly name — point it at
> a Synology DSM, a Samba box, a Windows share, a TrueNAS, whatever speaks SMB.

## Requirements

Install these with your distribution's package manager:

| Tool             | Provided by (Arch)     | Purpose                          |
|------------------|------------------------|----------------------------------|
| `kpackagetool6`  | `plasma-workspace`     | install the widget               |
| `mount.cifs`     | `cifs-utils`           | mount CIFS shares                |
| `smbclient`      | `smbclient`            | list shares on a host            |
| `pkexec`         | `polkit`               | authorize the mount helper       |
| `kwallet-query`  | `kwallet` (KF6)        | read passwords from KWallet      |
| `qdbus6`         | `qt6-tools`            | write passwords to KWallet (D-Bus) |
| `findmnt`        | `util-linux`           | detect mounted shares            |

On Debian/Ubuntu the equivalents are `plasma-workspace`, `cifs-utils`,
`smbclient`, `policykit-1`, `kwallet-bin`/`kf6-kwallet`, `util-linux`.

## Install

```sh
git clone https://git.houmeres.sk/Houmeres/Plasma-Addon-Synology-NAS.git
cd Plasma-Addon-Synology-NAS
./install.sh
```

`install.sh` copies the helper to `/usr/lib/synology-nas/helper` and the polkit
policy to `/usr/share/polkit-1/actions/` (via `sudo`), then installs the widget
for your user with `kpackagetool6`. Re-run it any time to upgrade.

Then add **Synology NAS** to your panel or system tray (right-click →
*Add Widgets…*), or try it standalone:

```sh
plasmawindowed sk.houmeres.synologynas
```

## Usage

1. Open the widget's settings (right-click → *Configure…*).
2. Under **NAS Hosts**, add a host: display name, host/IP, username, password
   (saved to KWallet), and optionally a domain, a mount-folder override, or an
   SMB-version override.
3. Under **General**, optionally set the default mount folder (defaults to
   `~/NAS`), SMB version, extra mount options and permission modes.
4. Click the tray icon → **Refresh**. Each host's shares appear; click a share
   to **Mount** it (you'll get a polkit prompt) or **Unmount** it. Use the row's
   menu to open a mounted share in your file manager.

Shares mount under `<mount folder>/<host>/<share>` (e.g.
`~/NAS/HomeNAS/photos`).

## How it works

```
 Plasmoid (QML)                      Privileged helper (root, via pkexec)
 ─────────────                       ────────────────────────────────────
 smbclient -L   ── list shares       mount.cifs //host/share  <mountpoint>
 kwallet-query  ── read password           -o credentials=…,uid=…,forceuid,…
        │                            umount <mountpoint>
        ▼
 write 0600 cred file in            polkit action:
 $XDG_RUNTIME_DIR ───────────►      sk.houmeres.synologynas.manage
        │                            (auth_admin_keep)
        └── pkexec helper mount …
```

The QML never runs privileged operations directly. It builds a `0600`
credentials file in your `$XDG_RUNTIME_DIR` (reading the password straight from
KWallet, so it never lands in QML, argv or `ps`) and calls the helper through
`pkexec`. The helper treats every argument as hostile: the mount point must
resolve inside your `$HOME` or `/run/media/<you>`, the source must be
`//host/share`, and the credentials file must be your own `0600` file under your
runtime dir.

## Security notes

- **Passwords** live in KWallet (folder *Synology NAS*). They are copied into a
  transient `0600` credentials file only for the moment of mounting, then
  removed.
- The **one** place a password briefly touches process arguments is when you
  first *save* it in the config page (`kwallet-query -w`), because the CLI has no
  other input channel here. The window is milliseconds and visible only to your
  own user (and root). Everything afterward reads from KWallet.
- The privileged helper is intentionally tiny and does **no** recursive
  deletion — on unmount it only `rmdir`s the now-empty mount/host directories.

## Uninstall

```sh
./uninstall.sh
```

Mounted shares stay mounted (unmount them first) and KWallet passwords remain —
remove them with `kwalletmanager` if desired.

## Limitations / roadmap

- No mount-at-login persistence yet (planned; the config schema already leaves
  room for it).
- Share discovery is via `smbclient -L` only (no Synology DSM API).

## License

MIT — see [LICENSE](LICENSE).