guth-sync 0.1.1

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.

Read-Only Replicas

Protect one profile on the current machine, or make all local profiles read-only by default:

guth-sync read-only <profile-uuid> on
guth-sync read-only <profile-uuid> off
guth-sync read-only --all on
guth-sync read-only --all off

The policy belongs to this local Guth instance, so paired machines can choose different modes. A read-only local replica can push its data and can serve peer pulls. It rejects local pulls and peer pushes because those operations would modify the protected folder. Remote write-direction sessions are rejected even when the initiating peer requested a dry run. Policy changes apply to new transfer sessions and do not terminate a transfer already in progress.

The first policy change marks the local profile as policy-aware. Guth Sync 0.1.0 refuses that newer profile schema rather than bypassing protection after a downgrade, and Guth Sync 0.1.1 fails closed if a marked profile's policy file is missing or invalid. Keep $XDG_CONFIG_HOME/guth-sync/access-policy.json with the profile files when backing up or restoring this instance.

Guth exposes the same per-profile toggle from a matching Sync Folder's context menu and the all-profile toggle in plugin settings. A Sync Folder shortcut must exactly match a configured Guth Sync profile root before Guth offers the protection toggle.

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 the profile UUID, root path, matching transfer key, and local read-only policy. 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.