community-plugins/gocryptfs/README.md

Gocryptfs

Mount, unmount, initialize, and auto-mount gocryptfs encrypted volumes from Noctalia — bar status, manager panel, and optional auto-mount after login.

Plugin

Field	Value
ID	davemhammer/gocryptfs
Entries	Bar widget: status; panel: manager; service: service

Requirements

Install these on PATH (declared in plugin.toml dependencies):

• gocryptfs — mount and gocryptfs -init
• fusermount3 or fusermount — FUSE unmount (first found wins)
• keyctl — kernel user-keyring session cache for remembered passwords (package keyutils)
• secret-tool — Freedesktop Secret Service client for reboot-persistent passwords (package libsecret / libsecret-tools)
• chmod — mode bits on short-lived temp password files
• xdg-open — open the mount point in the file manager
• cat — read /proc/mounts for mount status

Desktop keyring: persistent “Remember” needs a Secret Service backend (GNOME Keyring, KeePassXC as Secret Service, etc.) running and unlocked after login. If only keyctl is available, remember still works for the current login session.

Usage

Add the status bar widget from Settings → Bar (davemhammer/gocryptfs:status).

• Left-click — open the manager panel
• Right-click — refresh mount status

In the panel you can:

• Select a volume → Mount / Unmount / Open (file manager via xdg-open)
• Edit → Remember / Forget — store or clear the volume password (desktop keyring + session cache)
• Add an existing cipher directory, or Init a new one (gocryptfs -init)
• Mount with a remembered keyring password, an optional advanced passfile path, or a one-shot password prompt (optional “also remember”)

noctalia msg panel-toggle davemhammer/gocryptfs:manager

Auto-mount on login

Requires all of:

1. Plugin setting Auto-mount on login (default on)
2. Per-volume Auto-mount enabled
3. A remembered keyring password (Remember) or an advanced passfile path

After reboot, the desktop keyring must unlock (normal login) so secret-tool can supply the password. The kernel session key is refilled automatically on mount.

Settings

Setting	Type	Default	Description
refresh_interval	int	3	Seconds between /proc/mounts polls.
notify_on_action	bool	true	Notify after mount, unmount, init, remember, and forget.
create_mountpoint	bool	true	Create the mount directory if missing before mount.
auto_mount	bool	true	Global switch: on service start, queue volumes that have auto-mount + keyring/passfile.
show_count	bool (widget)	true	Show mounted/total on the bar.
glyph_color	select (widget)	on_surface	Lock icon color when nothing is mounted.
mounted_color	select (widget)	tertiary	Icon/dot color when at least one volume is mounted.
unmounted_color	select (widget)	on_surface_variant	Status-dot color when nothing is mounted.

IPC

noctalia msg panel-toggle davemhammer/gocryptfs:manager
noctalia msg plugin davemhammer/gocryptfs:service all refresh
noctalia msg plugin davemhammer/gocryptfs:service all reload
noctalia msg plugin davemhammer/gocryptfs:service all automount

• refresh — re-read /proc/mounts and refresh the snapshot
• reload — reload volumes.json from the plugin data dir, clear the auto-mount queue, then refresh
• automount — reset the auto-mount schedule and refresh (eligible volumes are queued again on the next status pass)

Notes

Data and filesystem

• Volume definitions live under the plugin data directory as volumes.json (not inside the cipher directory).
• With Create mount points on, the service may mkdir the configured mount path before mounting.
• Cipher, mount, and passfile paths reject empty values, NUL, and .. segments. Symlinks on those paths are followed by design (user-chosen paths).

Secrets (no long-lived plaintext under plugin data)

Remember password does not write a long-lived password file under the plugin data dir. It stores the secret in:

1. Desktop keyring via secret-tool — attributes service=noctalia-gocryptfs, volume-id=<volume-id>. Survives reboot while the login keyring is unlocked.
2. Kernel session keyring via keyctl — description noctalia-gocryptfs:<volume-id>. Fast cache for this login only; cleared on reboot/logout.

On mount / auto-mount, the service prefers the session key; if missing, it hydrates from secret-tool into keyctl, then runs gocryptfs -extpass keyctl pipe <id>. Fallback: gocryptfs -extpass secret-tool lookup ….

• One-shot typed passwords use a short-lived file under /dev/shm (tmpfs) when available, then delete it.
• Optional advanced passfile paths remain supported for users who manage their own files (plaintext by user choice; not recommended).
• Forget and volume remove clear both the desktop keyring entry and the session key.
• Passwords are not logged.

Processes and network

• Spawns: gocryptfs, fusermount3 or fusermount, keyctl, secret-tool, chmod, cat (/proc/mounts), xdg-open.
• Network: none.