Environment & Profile Synchronization

sshs3 provides synchronization tools designed to keep your terminal shell settings and connection profiles synchronized across multiple workstations without compromising privacy or relying on third-party cloud accounts.

1. Dotfiles Pool Sync (Opt-In)

Reconfiguring .bashrc, custom aliases, .vimrc, or .tmux.conf on hundreds of remote servers is tedious. sshs3 offers an opt-in Dotfiles Pool Sync:

1. Open Settings → Files & Storage, tick Enable dotfiles pool sync, and click Manage Dotfile Pools.
2. Click Add Files... or drag files in (e.g. ~/.bash_aliases, ~/.config/nvim/init.vim).
3. You can also right-click any file in the dual-pane file manager and choose Add to Dotfiles Pool....
4. Each pooled file shows a status indicator for whether the local source file changed on disk since it was pooled; click Refresh to re-read changed source files.
5. In any SSH profile under Environment, select the Dotfiles Pool to attach and choose a synchronization policy (e.g. silent sync upon login or interactive prompt).

Technical Architecture: Staged Session Environments

DotfilePoolStore (src/main/dotfiles/DotfilePoolStore.ts) manages pool definitions. Upon establishing an SSH connection, a fast SFTP check compares file modification timestamps. Staged files are placed into an isolated temporary session directory on the remote server and sourced automatically without modifying permanent system configurations.

2. Remote Profile Synchronization ("Own Your Data")

For operators working across multiple workstations, sshs3 provides end-to-end encrypted profile synchronization with zero proprietary cloud infrastructure. You own and control your storage backend:

• A private Amazon S3 bucket (or MinIO, Cloudflare R2, Ceph).
• A private remote SFTP server.

sequenceDiagram
    participant App as sshs3 Desktop Client
    participant Keyring as OS Keyring / Smartcard
    participant Remote as Private S3 / SFTP

    Note over App: Profile Modified Locally
    App->>Keyring: Derive AES-256-GCM Key (scrypt / PKCS#11 Challenge)
    App->>App: Encrypt Data in Memory (Zero-Knowledge)
    App->>Remote: Upload Encrypted Files (topology.enc, credentials.enc, ...)
    Note over Remote: Remote storage provider sees only random ciphertext

Zero-Knowledge Cryptographic Model

After a wrong master password the keys are not kept in memory; unlock again with the right password before pushing.

Deleting Your Sync Data

In the Synchronization panel, the Danger zone has a Delete sync data... button. After an itemized confirmation it:

• permanently deletes the encrypted sync files (topology, credentials, dotfile pools, settings, saved directory-sync and Kubernetes profiles, SSH config/known_hosts data) from the remote target;
• removes the sync target, the master-password salts and any linked smartcard from this device, and locks sync here.

It never touches your local SSH/S3 profiles, dotfile pools or settings, and other machines that are already synced are unaffected until they next push or pull.

3. Managed Block in ~/.ssh/config

sshs3 ensures all saved SSH profiles are immediately accessible when running standard ssh <host> commands in external terminal emulators, VS Code, or automation scripts.

Under Settings → Terminal, ensure Keep ~/.ssh/config in sync with saved SSH profiles is checked. Whenever a profile is created or updated, sshs3 updates a marked block in ~/.ssh/config:

# BEGIN sshs3-managed (do not edit by hand -- managed by sshs3 Remote Profile Sync)
Host prod-db
  HostName 10.0.4.12
  User dbadmin
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  ProxyJump bastion.example.com
# END sshs3-managed

Security Architecture: Strict Directive Filtering & Race-Free Serialization

• Allowlist Filtering: To prevent malicious configuration injection from shared profiles, only safe directives are written: Host, HostName, Port, User, IdentityFile, PKCS11Provider, ProxyJump, ForwardAgent, and safe network options (ServerAliveInterval, Compression, Ciphers). Executable options (ProxyCommand, LocalCommand, Match, Include) are strictly filtered out.
• Received blocks are filtered too: a managed block arriving from another machine passes the same allowlist before it is written, and configuration outside the managed block is never touched.
• Free-form extra options: a profile's extra SSH options follow the same allowlist, both in this block and on the ssh command line sshs3 starts; other options are ignored. Use the profile's own fields for identity files, jump hosts, agent forwarding and X11.
• Queue-Safe Writes: SshNativeFileMerger serializes all file mutations through queueMutation, ensuring concurrent saves and background syncs never corrupt ~/.ssh/config.

4. Troubleshooting & Diagnostics