guth-sync 0.1.0

Private-by-default rsync plugin for Guth and guth-cli.
Documentation

Guth Sync

Guth Sync is the rsync command plugin for Guth and guth-cli. It keeps the transport simple: OpenSSH encrypts and authenticates the connection, while rsync performs bounded one-way transfers between matching UUIDv7 profiles.

Guth Sync currently supports Unix systems with OpenSSH and rsync 3.2.5 or newer.

Install

Both machines need OpenSSH, rsync 3.2.5 or newer, guth-cli, and guth-sync:

cargo install guth-cli
cargo install guth-sync
guth-sync install-plugin

Create a dedicated SSH key for Guth Sync and restrict it on the receiving machine instead of granting it a shell:

ssh-keygen -t ed25519 -f ~/.ssh/guth-sync
guth-sync authorized-key ~/.ssh/guth-sync.pub >> ~/.ssh/authorized_keys

Use --identity ~/.ssh/guth-sync when transferring. The generated entry uses OpenSSH's restrict option and a forced Guth Sync command. An unrestricted SSH account remains fully trusted and can bypass application-level folder boundaries, so a shared profile key is not protection from a user who already has shell access to that account.

Pair Two Folders

Create a profile on the first machine:

guth-sync init ~/Sync
guth-sync pairing-code <profile-uuid>

Display and transfer the reusable pairing credential through a trusted channel. On the other machine:

guth-sync join ~/Sync

Paste the pairing code at the hidden prompt. The UUID and 256-bit key must match on both machines. For headless provisioning, guth-sync join ~/Sync --code-stdin reads the code from a bounded standard-input pipe instead of process arguments.

Transfer

Push or pull the whole profile:

guth-sync push <profile-uuid> user@machine --all
guth-sync pull <profile-uuid> user@machine --all

Transfer selected relative paths:

guth-sync push <profile-uuid> user@machine Documents notes.txt
guth-sync pull <profile-uuid> user@machine Pictures/report.png

Use --port N for an SSH service that does not listen on port 22. --identity, --known-hosts, and --remote-program accept safe absolute paths for restricted or nonstandard SSH installations. SSH host-key checking is strict; establish the host's key through a trusted channel before transferring.

The remote SSH account must have guth-sync in its command path. Guth Sync invokes a short-lived rsync server through SSH; it does not open a separate listening port. Transfers preserve destination-only files because destructive rsync deletion options are not exposed.

Privacy Model

  • Profiles are stored below $XDG_CONFIG_HOME/guth-sync/profiles, or ~/.config/guth-sync/profiles, in user-only directories and files.
  • Guth Sync stores only the profile UUID, root path, and matching transfer key. It does not store endpoints, hostnames, IP addresses, session identifiers, transfer history, filenames, or logs.
  • Plugin manifests contain only the public UUIDv7 plugin identity and executable metadata.
  • Local commands are spawned directly without sh -c; remote command components are strictly validated. Secrets are not placed in process arguments.
  • Temporary rsync configuration and password files are mode 0600 and removed after normal completion. Abrupt process or machine termination can leave a private temporary file for manual cleanup.

A direct SSH transfer cannot hide network metadata. Each peer, network infrastructure, and the remote SSH service can observe connection addresses, timing, and traffic volume; sshd may keep system logs. Use a trusted VPN, jump host, or anonymity network when endpoint privacy is required. Guth Sync makes no claim that direct transfers conceal IP addresses.

Endpoints are not written to Guth Sync files, but an endpoint supplied on the command line can appear in shell history and the local process table while rsync is running. This is unavoidable for the direct SSH connection model.

Safety

Guth Sync rejects absolute and parent-traversing transfer paths, profile roots containing control characters, unsafe profile permissions, symlinked profile files, malformed endpoints, mismatched profile keys, and non-SSH host activation. Pull is not integrated with Guth's undo stack, so dry-run and backups remain appropriate for important data.

Profile trees must not be concurrently rewritten by untrusted local processes during a transfer. Guth Sync rejects stable source-path symlink traversal, but rsync operates on a live filesystem rather than a transactional snapshot.