Metadata-Version: 2.4
Name: kcryptfs
Version: 0.2.1
Summary: System-tray frontend for gocryptfs encrypted folders on KDE Plasma
Author-email: Michal Belica <code@beli.sk>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/beli-sk/kcryptfs
Keywords: gocryptfs,encryption,fuse,kde,plasma
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.5
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# KCryptfs

A system-tray frontend for [gocryptfs](https://github.com/rfjakob/gocryptfs)
encrypted folders on KDE Plasma (6.x). Built with Python 3 and PySide6 (Qt 6).

Project home: <https://gitlab.com/beli-sk/kcryptfs>

## Features

- **Create encrypted vaults** with the supported gocryptfs options
  (plaintextnames, longnames, deterministic names, scryptn, legacy
  AES-SIV / XChaCha modes).
- **Add existing vaults** - register a vault pair initialized elsewhere
  (e.g. with the gocryptfs CLI); the encrypted directory is checked to be
  an initialized gocryptfs vault.
- **Store vault pairs** - each vault remembers its encrypted directory, its
  mount point and its options.
- **Mount / unmount** vaults, asking for the password on every mount.
- **Mount All / Unmount All** - mount or unmount every vault included in
  these actions at once. Mount All asks for one password and reuses it for
  all vaults, asking again (for the remaining ones) when some reject it;
  each vault can be opted out of the bulk actions.
- **Open files view** - see which processes currently hold files open on the
  mounted vaults (fast in-process `/proc` scan, no external tools needed).
- **System tray icon** with a "Vaults" menu that lists every vault and lets
  you mount, unmount or open it directly from the tray; closing the window
  keeps the app running in the tray.
- **"Show when relevant" tray support** - on Plasma the tray icon is only
  shown while the window is open or a notification needs attention, and
  hides into the tray's overflow otherwise (override per-icon with Plasma's
  tray settings).
- **Global shortcuts** - the app registers itself with KDE's global
  shortcuts; assign key combinations in System Settings -> Keyboard ->
  Shortcuts -> KCryptfs to open the window, mount all vaults or unmount
  all vaults from anywhere (no defaults are preset).
- **Autostart at login** (hidden in the tray), managed through the standard
  XDG autostart mechanism with a KDE system-tray availability condition, and
  toggleable both in-app and in KDE System Settings.
- **Settings dialog** for autostart and close-to-tray behavior (toolbar or
  tray menu).

## Security notes

- Passwords are **never stored** and never passed on the command line. They
  are written to a temporary mode-0600 passfile (on tmpfs when
  `XDG_RUNTIME_DIR` is available) that is deleted as soon as gocryptfs
  returns.
- The encrypted data itself is managed entirely by gocryptfs; KCryptfs only
  stores directory pairs and option flags in `~/.config/kcryptfs/vaults.json`.
- `allow_other` requires `user_allow_other` in the host `/etc/fuse.conf`;
  gocryptfs will refuse to mount if it is missing.

## Installation

Fedora 44+:

```sh
sudo dnf install kcryptfs
```

(once the package or a Copr repository is published - see `packaging/`).

From source:

```sh
python -m venv .venv
.venv/bin/pip install .
.venv/bin/kcryptfs
```

Runtime requirements: `gocryptfs`, `fuse3`, PySide6. `lsof` is an optional
fallback for the open-files view (normally not needed). On Fedora, the
package pulls in the KDE Frameworks Python bindings
(`python3-kf6-kstatusnotifieritem`, `python3-kf6-knotifications`) for the
"Show when relevant" tray behavior and desktop notifications; without them
the app falls back to a plain always-visible tray icon.

## Usage

- **New Vault**: pick a name, an encrypted directory (where ciphertext is
  stored) and a mount point (where decrypted files appear), set a password
  and choose the encryption options.
- **Add Existing Vault**: register an already-initialized vault by picking
  its encrypted directory (must contain `gocryptfs.conf`) and mount point;
  the password is still asked on every mount.
- **Mount**: select a vault and enter its password; optional per-vault mount
  options (read-only, reverse, auto-unmount idle timeout, allow_other,
  mount over non-empty directory) can be adjusted in the same dialog.
- **Mount All / Unmount All**: bulk actions for all vaults included in them
  (included by default, toggleable per vault in the create/edit dialog).
  Mount All reuses one password for every vault and re-asks only for the
  vaults that rejected it, until everything is mounted or you cancel.
- **Open Mount Point**: opens the mounted vault in Dolphin.
- **Open Files**: lists every process currently holding a file open on the
  mounted vaults, refreshing automatically.
- **Settings**: toggle "start at login" and close-to-tray behavior; the app
  then comes up hidden in the tray.

Command line: `kcryptfs [--hidden] [--version]`. `--hidden` starts the app
in the tray only (used by the autostart entry).

## Development

```sh
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

Headless GUI smoke test:

```sh
QT_QPA_PLATFORM=offscreen .venv/bin/kcryptfs
```

## Packaging

- `packaging/kcryptfs.spec` - Fedora RPM spec (uses `%pyproject` macros,
  validates desktop/metainfo files, runs the test suite in `%check`).
- `data/sk.coders.kcryptfs.metainfo.xml` - AppStream metadata for software
  centers.
- `data/autostart/sk.coders.kcryptfs.desktop` - installed to
  `/etc/xdg/autostart`, opt-in by default.

## License

MIT - see `LICENSE`.
