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).

---

Permissions and data access

The plugin is a sync and backup tool, so by design it enumerates every file in your vault and then reads / uploads / downloads the files inside your configured sync and backup scope. This section spells out exactly what each piece of the plugin touches so you can make an informed decision before enabling it.

What the plugin reads

What the plugin writes

What is sent off your device

• HTTP traffic goes only to the S3 endpoint you configure (AWS S3, Cloudflare R2, RustFS, or any other S3-compatible endpoint). The transport scheme matches the endpoint you set — HTTPS for hosted providers; the plugin accepts plain HTTP if you choose it (e.g. http://localhost:9000 for a local RustFS).
• No telemetry, no analytics, no error reporting, no update polling. The Security section below covers the network-use detail.
• No remote code execution. The plugin never downloads or evaluates code from the network — all cryptography runs locally in the browser.

What is not read or written

• The plugin does not access the operating system shell, filesystem, or any APIs beyond those Obsidian exposes.
• It does not touch files outside the configured vault.
• It does not contact any host other than the S3 endpoint you configure.

Important — Obsidian config files are in scope by default. Only the plugin's own settings directory (.obsidian/plugins/simple-storage-sync-and-backup/) is hard-excluded. Other files under .obsidian/ (workspace layout, hotkeys, third-party plugin settings, etc.) are vault files from Obsidian's point of view and are enumerated and synced unless you add them to Exclude patterns in settings. If you do not want those propagated across devices, add patterns such as .obsidian/workspace*, .obsidian/hotkeys.json, .obsidian/plugins/**, etc. The defaults (**/workspace*, .trash/**) cover the workspace layout but not other config files.

---

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