Di-kairos/vaultwatch

📦 Moved: development continues in the paranoid-tools monorepo (vaultwatch/ directory, full history preserved). This repository is archived: its published releases stay downloadable and the installers keep working, but new issues, PRs and releases happen in the monorepo.

English · Русский

vaultwatch

An honest watchdog for an open vault — part of the Paranoid Tools ecosystem.

vaultwatch is active only while a vault is mounted. It narrows the channels through which open plaintext can leak (Spotlight, Time Machine) and restores everything on close. It runs automatically from the securetrash vault open/close hooks.

Status: early (v0.1.14, work in progress). Done: integration (hooks + vendoring), the watchdog core start/stop (Spotlight off, Time Machine exclude, cloud-detect, session report), and auto-exit --ttl via a launchd LaunchAgent (a managed timer, visible in launchctl list, cleanly removed via bootout).

Install

Checksum-verified install from the release tag (same approach as securetrash). Prefer verify-then-run — download, check the checksum, read it, then run:

curl -fsSLO https://github.com/Di-kairos/vaultwatch/releases/latest/download/install.sh
curl -fsSLO https://github.com/Di-kairos/vaultwatch/releases/latest/download/SHA256SUMS
curl -fsSLO https://github.com/Di-kairos/vaultwatch/releases/latest/download/SHA256SUMS.sig
printf '%s\n' 'releases@paranoid-tools namespaces="file" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICb2nz4EliRJIU0ExeF41klE/zlyo7XFY119mfzscn2U' > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I releases@paranoid-tools -n file -s SHA256SUMS.sig < SHA256SUMS &&   # authenticity: Ed25519, pinned key
shasum -a 256 -c SHA256SUMS --ignore-missing &&   # integrity: verifies install.sh
less install.sh &&                               # read it — then run:
bash install.sh                                  # pulls vaultwatch + checksum, verifies, installs
vaultwatch install-hooks                         # wire into securetrash

Quick form (this runs code you haven't read — choose deliberately):

curl -fsSL https://github.com/Di-kairos/vaultwatch/releases/latest/download/install.sh | bash

install.sh pulls the binary and SHA256SUMS from the immutable release tag and verifies the hash before installing. Environment variables: VWVERSION (pin a specific tag), VWDEST (install path), VWBASEURL (override the source for forks/tests).

Integrity vs authenticity (honest scope). The checksum proves the binary matches the SHA256SUMS published in the same release — it catches corruption and partial/cached tampering. Authenticity comes from the Ed25519 signature over SHA256SUMS: the snippet above and install.sh both verify it against a key pinned in this repo, and the installer fails closed when it can't (see SECURITY.md). Residual risk: one project key signs all five tools — see the ecosystem threat model. Pin a version with VWVERSION=0.1.14 instead of latest for reproducibility.

The current public release is v0.1.14 (signed, with install.sh + SHA256SUMS). Pin it for reproducibility with VWVERSION=0.1.14 instead of latest.

Usage

vaultwatch start [--ttl D] [--force] <mount>   # guard a vault (normally from the post-open hook)
vaultwatch stop  <mount>                        # restore everything + session report (post-close)
vaultwatch status                               # show active sessions (read-only)
vaultwatch install-hooks                        # wire into securetrash vault open/close
vaultwatch uninstall-hooks                      # remove (only the hooks it manages)
vaultwatch version                              # show the version

--ttl D auto-detaches the volume after D (30m, 2h, 45s, 1d, or bare seconds). The timer is installed as a launchd LaunchAgent (~/Library/LaunchAgents/com.vaultwatch.ttl..plist, RunAtLoad → sleeps D → fires vaultwatch ttlfire <mount). When it fires, vaultwatch checks for open files (lsof) and, if there are none, unmounts the volume (hdiutil detach) and restores state. If files are open it honestly leaves the volume alone and warns; --force forces hdiutil detach -force (with confirmation, risk of data loss). stop (a manual close before the TTL) tears the LaunchAgent down (bootout + plist removal).

start records the prior state and narrows leak channels; stop restores exactly what start changed (if Spotlight was already off, or the vault was already excluded from Time Machine before the session, stop leaves that as-is) and prints a session report.