Oxide Cloud Sync

Encrypted self-hosted sync plugin for OxideTerm.

This plugin syncs OxideTerm data to a remote backend using a structured remote format. Saved connections and saved forwards are uploaded as structured JSON snapshots, while app settings and plugin preference settings are stored as encrypted per-section .oxide fragments. The UI is exposed as an OxideTerm plugin tab, with a status bar entry and command palette commands for quick access.

Features

• sync over WebDAV, HTTP JSON, Dropbox, Git repository contents API, or S3-compatible object storage
• structured remote sync across connections, forwards, app settings sections, and plugin settings
• encrypted .oxide import/export is still used for settings fragments and rollback backups
• per-section revision tracking to reduce unnecessary uploads and narrow conflict scope
• remote metadata check before upload
• pull-and-preview before import with a structured preview panel
• record-level import preview with rename / skip / replace / merge reasons
• section-aware restore/import controls for connections, saved forwards, app settings, and plugin settings
• conflict recovery actions for re-check, pull-first, or force upload
• persistent sync history in the plugin panel
• multiple rollback backups with metadata summaries and selective restore
• conservative conflict handling with ETag-aware upload failure reporting
• plugin-scoped secure storage for sync secrets

What It Syncs

• saved SSH connections
• owner-bound saved forwards
• global OxideTerm settings
• plugin preference settings declared through plugin settings

What It Does Not Sync

• runtime sessions
• terminal scrollback or buffers
• server-readable secrets
• automatic pull/import
• arbitrary plugin local storage data outside declared plugin settings

Requirements

• OxideTerm v1.1.19 or later (uses the host HTTP proxy plus record-level import preview metadata introduced by that version line)

Installation

Manual installation is the intended flow right now.

1. Open OxideTerm Plugin Manager and use Open Directory.
2. Copy this folder into the OxideTerm plugin directory as com.oxideterm.cloud-sync.
3. The final path should look like ~/.oxideterm/plugins/com.oxideterm.cloud-sync/ on the default macOS/Linux data directory.
4. Restart OxideTerm or refresh plugins from Plugin Manager.
5. Open the Cloud Sync tab from the status bar item or the Open Cloud Sync plugin command.

Usage

1. Choose WebDAV, HTTP JSON, Dropbox, Git, or S3 Compatible.
2. Fill in the backend-specific connection fields.
3. Set authentication mode if your backend requires it.
4. Enter the sync password used to encrypt exported .oxide snapshots.
5. Save settings.
6. Use Check Remote, Upload Now, or Pull and Preview.

During Pull and Preview, the plugin now keeps the snapshot in a structured preview card instead of immediately importing it. You can choose whether to import:

• saved connections
• saved forwards
• app settings sections
• plugin settings grouped by plugin ID

If auto upload is blocked by a remote conflict, the panel exposes dedicated recovery actions to re-check the remote, pull first, or force an overwrite.

Backend notes:

• WebDAV: use Endpoint as the remote collection base, and Namespace as the folder path under it.
• HTTP JSON: use Endpoint as the service root exposing the plugin JSON/blob API. Phase 6 structured sync additionally requires PUT /metadata and GET/PUT /objects/<path> endpoints.
• Dropbox: Namespace is treated as the folder path. Endpoint is not required. Configure an access token in the secret field.
• Git: uses a GitHub Contents API compatible endpoint. Set Endpoint to the API root, Repository to owner/repo, Branch to the target branch, Namespace to an optional folder path inside the repository, and configure a token with repository contents write permission.
• S3 Compatible: use Endpoint as the service root, Bucket as the container, Region for SigV4 signing, and Namespace as an optional object prefix.

Secret fields intentionally stay blank when the tab opens.

• Leaving a secret field blank keeps the stored value unchanged.
• Entering a new value replaces the stored secret.
• Clear Stored removes the saved secret immediately after confirmation.

Quick Start: Jianguoyun / WebDAV

If you are using Jianguoyun, use the following configuration in the plugin tab:

• Backend Type: WebDAV
• Authentication: Basic
• Endpoint: https://dav.jianguoyun.com/dav/
• Namespace: oxideterm-sync
• Basic Username: your Jianguoyun account email
• Basic Password: Jianguoyun third-party app password
• Sync Password: your local encryption password for exported .oxide snapshots

Recommended first-run flow:

1. Click Save Settings.
2. Click Check Remote.
3. If the plugin says no remote snapshot exists yet, that is expected on first use.
4. Click Upload Now to create the first encrypted snapshot.
5. On another device, use the same backend config and the same sync password, then click Pull and Preview.

Do not put the same folder path in both Endpoint and Namespace. If your Endpoint already ends with a sync folder, keep Namespace unique instead of duplicating the same path.

Official Self-Hosted Server

For the HTTP JSON backend, an official dedicated sync server is available:

OxideTerm Cloud Sync Server — Rust single-binary server with optional ChaCha20-Poly1305 encryption at rest, ETag-based concurrency control, scoped API tokens, and a built-in admin panel. Zero external dependencies, Docker-ready.

Security Notes

• Secrets are stored in plugin-scoped secure storage, not in normal plugin settings.
• Remote storage is treated as untrusted. The server only receives encrypted .oxide payloads.
• Auto upload never auto-pulls remote changes.
• Background auto upload will not trigger system keychain prompts by itself. If secrets must be unlocked, perform one manual sync action first.
• The Git backend does not speak the native Git protocol. It targets GitHub Contents API compatible servers, such as GitHub or GitHub Enterprise style endpoints.

Rollback and History

• Every import preview can create a rollback backup before applying remote data if local unsynced changes are still present.
• The plugin keeps up to 5 rollback backups with content summaries.
• The panel also keeps a sync history log so you can inspect recent upload, pull, and restore operations.

Remote Format

• Phase 6 uploads use a structured manifest (latest.json) instead of a single all-in-one .oxide blob.
• Saved connections and saved forwards are stored as structured JSON snapshots.
• App settings and plugin settings are stored as encrypted .oxide fragments per section or per plugin.
• Older remote namespaces that still contain the legacy single-blob format remain readable; the next successful upload migrates them to the structured format.

Development

• Thin entry: src/main.js
• Controller: src/controller.js
• Panel UI: src/panel.js
• Structured sync protocol: src/structuredSync.js
• Backend adapters: src/backend.js
• Local plugin state: src/store.js
• Styles: styles/main.css
• Locales: locales/
• Local E2E harness: ../../scripts/cloud-sync-plugin-e2e.mjs

License

This plugin is licensed under AGPL-3.0-only. See LICENSE.