S3 Sync & Backup

Obsidian S3 Sync & Backup

Vault synchronization and scheduled backups across devices using S3-compatible storage (AWS S3, Cloudflare R2, RustFS, etc.) with optional end-to-end encryption.

Features

• Bi-directional Sync — Three-way reconciliation keeps your vault synchronized across devices via S3. Per-file SHA-256 baselines stored locally in IndexedDB detect changes accurately — no cloud manifest required.
• S3-Compatible Storage — Works with AWS S3, Cloudflare R2, RustFS, and any other S3-compatible endpoint.
• End-to-End Encryption — Optional XSalsa20-Poly1305 encryption with Argon2id key derivation. Encrypts both synced files and backup snapshots. Passphrase can be remembered for auto-unlock on startup.
• Scheduled Backups — Full vault snapshot backups with configurable intervals (hourly to weekly). Download any backup as a ZIP from settings.
• Smart Conflict Resolution — When the same file changes on two devices while offline, the plugin creates LOCAL_ and REMOTE_ copies so you never lose data.
• Status Bar Integration — Real-time sync and backup status at a glance, with clickable actions.
• Flexible Retention — Automatically clean up old backups by age (days) or number of copies.
• Plugin Settings Protection — The plugin's own settings directory is hardcoded-excluded from sync to prevent credential or passphrase leakage.
• Mobile Support — Works on iOS and Android. No desktop-only APIs used.
• Command Palette — Sync now, Backup now, Pause/Resume sync, and more — all available from the command palette with customizable hotkeys.

---

Installation

From Community Plugins

1. Open Settings → Community plugins
2. Search for "S3 Sync & Backup"
3. Click Install then Enable

---

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create the folder: <VaultPath>/.obsidian/plugins/simple-storage-sync-and-backup/
3. Copy the downloaded files into this folder.
4. Reload Obsidian and enable the plugin in Settings → Community plugins.

---

Quick Start

1. Configure S3 Connection

1. Open Settings → S3 Sync & Backup.
2. Select your provider (AWS S3, Cloudflare R2, RustFS, or Other S3-compatible).
3. Enter your credentials:
   • Endpoint URL: Required for non-AWS providers.
   • Region: Use auto for Cloudflare R2.
   • Bucket name: Your S3 bucket.
   • Access Key ID & Secret Access Key.
   • Force Path Style: Only shown for the Other S3-compatible provider — AWS S3, Cloudflare R2, and RustFS each use a fixed addressing mode (path-style for R2/RustFS, virtual-hosted for AWS).
4. Click Test Connection to verify credentials and bucket access.

2. Enable Sync

1. In the Sync section, toggle Enable sync (on by default).
2. Set the Sync prefix (default: vault) — this is the S3 folder where your files live.
3. Toggle Auto-sync and choose a Sync interval (1 min to 30 min, default: 5 min).
4. Enable Sync on startup to sync immediately when Obsidian opens.

3. Enable Backups (Optional but Recommended)

1. In the Backup section, toggle Enable backups (on by default).
2. Set the Backup prefix (default: backups).
3. Choose a Backup interval (every hour, 6 hours, 12 hours, daily, every 3 days, or weekly).
4. Enable Retention and configure a policy to auto-delete old backups.
5. Use Backup now for an immediate snapshot at any time.

4. Enable Encryption (Optional)

⚠️ Important: If you enable encryption, you MUST remember your passphrase. There is no recovery if it is lost.

1. Toggle Enable end-to-end encryption.
2. Enter a strong passphrase (minimum 8 characters — a strength indicator guides you).
3. Optionally enable Remember passphrase to auto-unlock the vault on startup.
4. Use the same passphrase on all devices syncing this vault.

When encryption is enabled:

• All synced files are encrypted before upload to S3.
• All backup snapshots are encrypted (the backup manifest remains plain JSON for metadata).
• Other devices detect the encryption state automatically and prompt for the passphrase.
• Disabling encryption re-uploads all files as plaintext (with a confirmation dialog).

---

Settings Reference

Connection

Encryption

Sync

Backup

Advanced

---

Command Palette

All commands are available via the Obsidian command palette (Ctrl/Cmd + P) and can be bound to custom hotkeys.

---

Multi-Device Sync

This plugin is designed for multi-device use. Each device gets a unique ID on first run, and all S3 uploads are tagged with the writing device's ID.

How it works:

• Each device maintains its own local sync journal (IndexedDB) with per-file baselines.
• On sync, the engine compares local state, remote state (S3), and the last-known baseline to determine what changed and where.
• If the same file changed on two devices while both were offline, a conflict is created with LOCAL_ and REMOTE_ copies of the file.

Encryption across devices:

• When encryption is enabled on one device, other devices detect the encrypted state on next sync and prompt for the passphrase.
• Use the same passphrase on all devices. If the wrong passphrase is entered, the plugin notifies you and clears any saved passphrase.
• Encryption enable/disable operations use an advisory lock to prevent two devices from migrating simultaneously.

---

S3 Bucket Structure

your-bucket/
├── vault/                              # LIVE DATA (synced)
│   ├── .obsidian-s3-sync/
│   │   └── .vault.enc                  # Encryption marker (if enabled)
│   ├── Notes/
│   │   └── my-note.md
│   └── Attachments/
│       └── image.png
│
└── backups/                            # SNAPSHOTS (read-only)
    ├── backup-2024-12-25T14-30-00/
    │   ├── .backup-manifest.json       # Plain JSON: file count, checksums, encrypted flag
    │   └── ... (full vault copy)
    └── backup-2024-12-24T14-30-00/

Note: The plugin's own settings directory (.obsidian/plugins/simple-storage-sync-and-backup/) is never uploaded to S3, regardless of exclude pattern configuration.

---

Security

• Encryption algorithm: XSalsa20-Poly1305 (via tweetnacl) with Argon2id key derivation (via hash-wasm).
• Content identity: SHA-256 fingerprints of plaintext content, stored in S3 custom metadata.
• Network use: Outbound network requests go only to the S3-compatible endpoint you configure (AWS S3, Cloudflare R2, or RustFS) over HTTPS. No third-party services, telemetry endpoints, analytics, or update servers are contacted. The plugin performs the following kinds of network activity, all under your control:
  • Periodic sync polls your bucket on a user-configurable interval (default 5 minutes, range 1–30 minutes). Controlled by the Enable sync and Auto-sync toggles plus the Sync interval dropdown in Settings — turning either toggle off stops all scheduled sync traffic.
  • Periodic backups snapshot your vault on a user-configurable schedule (default daily, options from hourly to weekly). Controlled by the Enable backups toggle and the Backup interval dropdown.
  • Manual operations (sync now, backup now, test connection, download backup) only run when you invoke them from the command palette, status bar, or settings.
• No telemetry: The plugin sends no usage data, error reports, or identifiers anywhere. Disabling sync and backups stops all network activity completely.
• No remote code execution: All encryption and hashing runs locally in the browser. The plugin never fetches or evaluates code from the network.
• Credential protection: S3 credentials and saved passphrases are stored in Obsidian's data.json, which is hardcoded-excluded from sync to prevent leakage.

---

Testing

The plugin includes 565+ automated tests: unit tests covering sync, encryption, backup, and utility modules, pipeline end-to-end tests, and integration tests against live S3 endpoints. CI runs linting, type-checking, and the full test suite on every pull request.

---

FAQ

---

Support & Contributing

• Issues: Report bugs or request features
• Contributing: See CONTRIBUTING.md for development setup and guidelines.

License

MIT © Ceilão Labs

Made with love for the Obsidian community