Google and backups¶

Google is optional. Without it, mail and CalDAV work with local settings and you can back up to a local folder.

Disconnect Google from Preferences → Accounts or Calendars. This stops Google Calendar and Drive work on this device and removes its saved Google login; cached events remain readable as offline archives. Mail accounts, local backups and existing Drive copies are retained. If the credential store is locked, use Retry Google cleanup after unlocking it. Reconnecting requires a fresh sign-in, and automatic Drive backups stay off until enabled again. This device action does not revoke Google access for other installations.

1. In Preferences → Accounts or Calendars, choose Drive backups, Calendar read/edit access, or both.
2. Choose Sign in with Google (or Reconnect Google). The displayed setup is saved before sign-in starts. Authorization opens the system browser with Shep's own Desktop OAuth client, using PKCE, exact state validation and a temporary loopback callback, following Google's desktop OAuth flow. Cancel sign-in stops the three-minute browser wait. See Google sign-in client for how builds get the client and what a build without one shows.
3. In Preferences → Backups, choose Local folder or Google Drive, set retention (1–100 copies) and interval (1–8760 hours), enter a passphrase of at least 12 characters, and make the first backup. Enable automatic backups if wanted.

Google refresh tokens and saved account passwords are kept in the OS keychain. Users never enter OAuth client details; a self-configured client from earlier versions stays in local preferences only so its existing grant keeps refreshing. Permissions for the next sign-in are selectable separately: private Drive backups and Calendar off/read-only/read-write. Fresh setup enables neither implicitly. Google may grant a subset; the active connection enables only selected, granted services. Preferences shows which permissions were granted; Calendar also supports read-only access. Drive backups require Drive permission, and missing Calendar permission leaves cached calendars readable as offline archives.

Connecting another Google account keeps the current login until the new grant is saved and validated. Calendar access and the selected credential then commit together. If validation fails, Reconnect Google retries the staged connection, including after a restart. Start a new sign-in opens Google's account chooser for a different attempt. Changed permission choices do not alter the active connection until sign-in succeeds. A staged retry must match its original requested permissions and this build's client; changing them requires a new authorization. Denied, cancelled, timed-out and expired attempts leave the active connection unchanged. Late completion cannot overwrite newer setup choices.

Google access refreshes in the background and saves any replacement refresh token. If saving fails, keep Shep open, unlock the keychain and retry Sync; the received credentials remain pending until saved. If this happens during sign-in, choose Reconnect Google after unlocking to finish the received authorization without another browser prompt. Revoked Google access requires reconnecting. A fresh sign-in must include offline access; it never reuses another account's refresh token.

Backups contain downloaded original email, account configuration, calendar-source settings and preferences. Enable Include account passwords to carry those passwords inside the encrypted snapshot. Google tokens are never included. Snapshots use compression, Argon2id and AES-256-GCM with fresh salts/nonces. The passphrase is saved in the OS keychain after a successful backup for scheduled use. Keep a separate copy of it for restore.

“Back up now” saves the displayed backup settings before starting. Make one manual copy at each destination to prepare its automatic schedule; this also works when you enable automatic backups afterward. Changing destination, Google account or OAuth application (including moving from a self-configured client to Shep's) requires a new first copy. Reconnecting the same verified Google account preserves its pending uploads and history. Existing installations need to reconnect Google once to verify the account/application binding, and make a new manual copy to establish the destination-specific keychain entry. Missing keychain access pauses automatic backups and the Backups page explains how to resume. A cleanup or keychain failure after upload reports that the copy was saved and identifies the remaining step.

Drive copies live in its private application data area, accessed only with drive.appdata; they do not appear as ordinary files in My Drive. This follows the Drive app-data model. App data belongs to the OAuth client's Google Cloud project: builds with Shep's client share it across machines, while copies made through a self-configured client are listed only by that client. Retention deletes only Shep copies after a successful new upload. Restore decrypts and validates first, then merges mail/accounts; it keeps this device's Google login and backup preferences. Calendar events sync from their calendar providers again.

Restore imports new mail and account/calendar settings in one local transaction. Existing messages, flags, folder moves, connection settings, preferences and unsent drafts are retained. Included passwords fill only missing OS-keychain entries for matching connections; restoring an older copy never replaces a current password. If the keychain is locked, the mail import is still complete: unlock it and restore the same copy again to finish the missing passwords without duplicating mail. Credentials for connections whose settings have changed are skipped. Invalid credential owners, duplicate IDs, conflicting cached identities or unreadable originals stop the import before any local changes.

Recovered emails remain cached even if the server has already deleted them. They follow server deletions again only after a complete sync confirms the same remote identity. Restore does not upload mail back to the server.

Drive reserves each file ID before transferring a copy and uploads in 1 MiB resumable chunks, following the Drive upload protocol. Shep saves the encrypted archive, reserved ID and session in backup-uploads.sqlite beside the mail cache, using a separate database connection. After interruption or an app restart, choose Back up now with the original passphrase to resume that exact copy. A missing final response is resolved by checking the reserved file's identity, size and ciphertext checksum. A confirmed copy with unfinished cleanup is retried without another upload. Healthy uploads are not stopped by an overall ten-minute deadline; individual HTTP requests and lack of progress remain bounded.