Cloud Sync

Sync your hosts, keys, and settings across devices using GitHub, Google Drive, OneDrive, WebDAV, or S3-compatible storage

Netcatty supports zero-knowledge encrypted cloud sync across multiple providers. Your data is encrypted locally with your master password before being uploaded, ensuring complete privacy.

Supported Providers

• GitHub Gist - Free, version-controlled sync using GitHub’s private gists
• Google Drive - Sync to your Google Drive account
• Microsoft OneDrive - Sync to your OneDrive personal account
• WebDAV - Self-hosted or third-party WebDAV servers (Nextcloud, ownCloud, etc.)
• S3-Compatible Storage - Amazon S3, MinIO, Backblaze B2, Wasabi, and other S3-compatible services

Security Architecture

Zero-Knowledge Encryption

All sync operations use AES-256-GCM encryption with PBKDF2 key derivation:

1. Master Password - You create a master password that never leaves your device
2. Key Derivation - PBKDF2 with 600,000 iterations derives an encryption key from your password
3. Local Encryption - All data is encrypted locally before upload
4. Cloud Storage - Only encrypted ciphertext is stored in the cloud
5. Local Decryption - Data is decrypted only on your devices with your master password

What Gets Synced

The following data is included in encrypted sync:

• SSH hosts and connection details
• SSH keys and identities
• Snippets and shortcuts
• Port forwarding rules
• Known hosts
• Custom groups
• Settings (themes, fonts, keybindings)

Security States

• NO_KEY - No master key configured, sync disabled
• LOCKED - Master key exists but vault is locked
• UNLOCKED - Vault unlocked, sync operations allowed

Setup Instructions

GitHub Gist Sync

GitHub uses device flow authentication for secure, browser-based login.

1. Open Settings → Cloud Sync
2. Click Connect next to GitHub
3. Copy the device code shown
4. Click Open GitHub to visit the authorization page
5. Paste the device code and authorize Netcatty
6. Return to Netcatty - connection completes automatically

What happens:

• Netcatty creates a private gist named “Netcatty Encrypted Vault”
• Your encrypted data is stored in netcatty-vault.json
• You can view the gist (encrypted ciphertext only) at github.com/gists

Google Drive Sync

Google Drive uses OAuth 2.0 with PKCE for secure authentication.

1. Open Settings → Cloud Sync
2. Click Connect next to Google Drive
3. Sign in with your Google account in the browser window
4. Grant Netcatty permission to create files
5. Connection completes automatically

What happens:

• Netcatty creates netcatty-vault.json in your Google Drive
• Only this file is accessible to Netcatty (restricted scope)
• File updates are versioned by Google Drive

OneDrive Sync

OneDrive uses Microsoft’s OAuth 2.0 for personal accounts.

1. Open Settings → Cloud Sync
2. Click Connect next to OneDrive
3. Sign in with your Microsoft account
4. Grant Netcatty file access permission
5. Connection completes automatically

What happens:

• Netcatty creates netcatty-vault.json in OneDrive root
• Only Netcatty has access to this specific file
• OneDrive provides automatic version history

WebDAV Sync

WebDAV works with self-hosted servers like Nextcloud, ownCloud, or any WebDAV-compatible service.

Configuration Fields

interface WebDAVConfig {
  endpoint: string;        // WebDAV server URL
  authType: 'basic' | 'digest' | 'token';
  username?: string;       // For basic/digest auth
  password?: string;       // For basic/digest auth
  token?: string;          // For token auth (Bearer)
}

Setup Steps

1. Open Settings → Cloud Sync
2. Click Connect next to WebDAV
3. Enter your WebDAV server details:
   • Endpoint: https://cloud.example.com/remote.php/dav/files/username/ (Nextcloud)
   • Auth Type: Choose Basic, Digest, or Token
   • Credentials: Username/password or access token
4. Click Test Connection
5. Click Save to enable sync

Examples:

# Nextcloud
endpoint: https://cloud.example.com/remote.php/dav/files/username/
authType: basic
username: your-username
password: app-password

# ownCloud
endpoint: https://owncloud.example.com/remote.php/webdav/
authType: basic
username: your-username
password: app-password

# Generic WebDAV with token
endpoint: https://webdav.example.com/
authType: token
token: your-bearer-token

S3-Compatible Storage

Works with Amazon S3, MinIO, Backblaze B2, Wasabi, and other S3-compatible providers.

Configuration Fields

interface S3Config {
  endpoint: string;         // S3 endpoint URL
  region: string;           // AWS region (e.g., 'us-east-1')
  bucket: string;           // Bucket name
  accessKeyId: string;      // Access key ID
  secretAccessKey: string;  // Secret access key
  sessionToken?: string;    // Optional session token (STS)
  prefix?: string;          // Optional key prefix/folder
  forcePathStyle?: boolean; // Use path-style URLs (default: true)
}

Setup Steps

1. Create an S3 bucket (or equivalent) in your provider
2. Create an access key with read/write permissions for the bucket
3. Open Settings → Cloud Sync in Netcatty
4. Click Connect next to S3
5. Enter your configuration:
   • Endpoint: Provider’s S3 endpoint URL
   • Region: Bucket region
   • Bucket: Bucket name
   • Access Key ID: Your access key
   • Secret Access Key: Your secret key
   • Prefix (optional): Folder path within bucket
6. Click Test Connection
7. Click Save to enable sync

Provider Examples:

# Amazon S3
endpoint: https://s3.amazonaws.com
region: us-east-1
bucket: my-netcatty-sync
accessKeyId: AKIAIOSFODNN7EXAMPLE
secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# MinIO (self-hosted)
endpoint: https://minio.example.com
region: us-east-1
bucket: netcatty-vault
accessKeyId: minioadmin
secretAccessKey: minioadmin
forcePathStyle: true

# Backblaze B2
endpoint: https://s3.us-west-002.backblazeb2.com
region: us-west-002
bucket: my-netcatty-bucket
accessKeyId: 002abc123def456789
secretAccessKey: K002abcdefghijklmnopqrstuvwxyz123456

# Wasabi
endpoint: https://s3.wasabisys.com
region: us-east-1
bucket: netcatty-sync
accessKeyId: AKIAIOSFODNN7EXAMPLE
secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# DigitalOcean Spaces
endpoint: https://nyc3.digitaloceanspaces.com
region: nyc3
bucket: my-netcatty-space
accessKeyId: DO00EXAMPLE7ACCESSKEY
secretAccessKey: secretkey123example
forcePathStyle: false

Sync Operations

Manual Sync

1. Click the Sync button in the toolbar
2. Netcatty checks all connected providers for updates
3. If remote version is newer, you’ll be prompted to download
4. If local version is newer, changes are uploaded
5. All connected providers are updated simultaneously

Auto-Sync

Enable automatic background sync:

1. Open Settings → Cloud Sync
2. Enable Auto-sync
3. Set sync interval (1-60 minutes, default: 5 minutes)
4. Netcatty syncs automatically while unlocked

Conflict Resolution

When sync detects a conflict (both local and remote have changes):

1. Sync pauses and shows a conflict dialog
2. You can choose:
   • Use Remote - Download cloud data, overwrite local changes
   • Use Local - Upload local data, overwrite cloud changes
3. Version metadata helps you decide:
   • Device name that made the change
   • Timestamp of last update
   • Version number

Sync File Format

The encrypted vault file structure:

{
  "meta": {
    "version": 42,
    "updatedAt": 1709556234567,
    "deviceId": "uuid-of-device",
    "deviceName": "My MacBook Pro",
    "appVersion": "1.0.0",
    "iv": "base64-initialization-vector",
    "salt": "base64-kdf-salt",
    "algorithm": "AES-256-GCM",
    "kdf": "PBKDF2",
    "kdfIterations": 600000
  },
  "payload": "base64-encrypted-ciphertext"
}

• meta - Plaintext metadata for version control and sync logic
• payload - Encrypted JSON containing all your hosts, keys, and settings

Multi-Device Usage

First Device Setup

1. Set up master password
2. Connect to one or more cloud providers
3. Netcatty uploads your encrypted vault

Additional Devices

1. Install Netcatty
2. Set up the same master password
3. Connect to the same cloud provider(s)
4. Click Sync to download your vault
5. Enter your master password to decrypt

Important: All devices must use the same master password. Changing the password on one device requires re-uploading the vault with the new password.

Provider Management

Disconnect Provider

1. Open Settings → Cloud Sync
2. Click Disconnect next to the provider
3. Confirmation dialog appears
4. Provider is removed from sync rotation
5. Note: This does NOT delete your cloud data

Delete Cloud Data

GitHub Gist:

• Visit github.com/gists
• Find “Netcatty Encrypted Vault”
• Delete the gist

Google Drive / OneDrive:

• Open your cloud storage
• Find and delete netcatty-vault.json

WebDAV / S3:

• Use your provider’s interface to delete netcatty-vault.json
• Or use the Delete Cloud Data button in Netcatty settings (if available)

Troubleshooting

”Vault is locked” Error

• Unlock the vault with your master password before syncing
• Auto-sync only works when the vault is unlocked

”Provider not connected” Error

• Re-authenticate with the provider
• Check network connectivity
• Verify credentials for WebDAV/S3

Conflict on Every Sync

• Ensure all devices use the same master password
• Check system clocks are synchronized
• Try “Use Remote” once to reset, then sync normally

”Access denied” on S3/WebDAV

• Verify bucket/endpoint permissions
• Check access key has read/write access
• For S3: ensure bucket policy allows your key
• For WebDAV: verify path exists and is writable

Sync File Not Found

• Normal on first connection
• Netcatty creates the file on first upload
• For S3: ensure bucket exists
• For WebDAV: ensure base path is accessible

Best Practices

1. Use Strong Master Password - It’s the only thing protecting your data
2. Enable Multiple Providers - Redundancy in case one provider fails
3. Enable Auto-Sync - Keeps all devices up to date automatically
4. Regular Backups - Export your vault separately for disaster recovery
5. Secure Credentials - Store S3/WebDAV credentials in a password manager
6. Monitor Sync Status - Check sync history for any errors
7. Test Recovery - Verify you can restore from cloud on a fresh device

Privacy & Security

• Zero-Knowledge: Your master password never leaves your device
• End-to-End Encryption: Data is encrypted before leaving your computer
• No Backdoors: Encryption keys are derived from your password only
• Provider Agnostic: Cloud providers only see encrypted ciphertext
• Open Source: Encryption implementation is auditable

What cloud providers see:

• A JSON file named netcatty-vault.json
• Encrypted binary data (base64-encoded ciphertext)
• File size (approximate number of hosts/keys)
• Update timestamps (when you sync)

What cloud providers DO NOT see:

• Your hostnames, IP addresses, or usernames
• Your SSH keys or passwords
• Your snippets or commands
• Any settings or preferences
• Your master password

Even if a provider is compromised, your data remains secure as long as you use a strong master password.