Architecture¶
flowchart TD
classDef local fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000;
classDef secure fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000;
classDef remote fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000;
classDef wasm fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000;
classDef plugin fill:#ede7f6,stroke:#4527a0,stroke-width:2px,color:#000;
subgraph Device ["Your machine — full trust"]
direction TB
Client["Desktop client\n(Tauri · Rust + React)\nVault key + decrypted secrets\nin memory"]:::secure
Vault[("Local vault file\n$APP_DATA/com.voltius.app/secrets.enc\nXChaCha20-Poly1305 ciphertext")]:::local
subgraph PluginBox ["Plugins (renderer — full app privileges)"]
Plugins["Bundled + installed ESM plugins\nRun in-process; PluginAPI is the\nsupported surface, not a sandbox"]:::plugin
end
Client <==>|"enc_key over Tauri IPC\nencrypt / decrypt"| Vault
Client -->|"PluginAPI (supported surface);\ntrust is established at install time"| Plugins
end
subgraph Cloud ["Remote services — zero knowledge"]
direction TB
Server[("Voltius server\napi.voltius.app\nauth_key hashes · wrapped keys\nEncrypted sync blobs")]:::remote
Portal["Web portal\napp.voltius.app (Next.js)\nvoltius-crypto → WASM"]:::wasm
Gist[("GitHub Gist\ngist.github.com\nEncrypted app-state blobs")]:::remote
end
subgraph Peers ["Your other devices — must prove the vault key"]
direction TB
Peer["Voltius on your laptop, desktop or phone\nSame account or paired group"]:::local
end
Tailscale["Tailscale app on this computer\n(desktop only, read-only)"]:::local
Client -->|"email + auth_key + JWT\n(never password or enc_key)"| Server
Client <==>|"ciphertext only"| Server
Client <==>|"encrypted blobs + your PAT"| Gist
Portal -.->|"same crate, same account —\nWASM, no local vault"| Server
Client <==>|"mDNS + TCP 47391, Noise channel\nvault-key proof, encrypted blobs\nfiles only if File access is on"| Peer
Client -.->|"local API: list of online peers"| Tailscale
Voltius runs as a client, a local vault file and one server, plus the optional sync layers. Your own devices also talk to each other directly over local network sync.
Components¶
| Component | Where it runs | What it holds |
|---|---|---|
| Desktop client | Your machine (Tauri / Rust + React) | Decrypted secrets and vault key in memory; master password (or random key) in the OS keychain for auto-unlock until you lock; host, snippet and folder records as plain JSON in the config directory |
| Local vault file | $APP_DATA/com.voltius.app/secrets.enc (the OS data directory) |
XChaCha20-Poly1305 ciphertext, on disk |
| Voltius server | api.voltius.app (or your self-host) |
auth_key hashes, account metadata, public keys, password-wrapped user keys, per-member wrapped team keys, encrypted per-device sync blobs and team vault ciphertext; issues JWTs |
| Web portal | app.voltius.app (Next.js) |
Same voltius-crypto crate, compiled to WASM |
| Gist host (Gist sync only) | gist.github.com (your account) |
Encrypted per-device app-state blobs |
| Local network listener | Inside the desktop or Android client, on TCP 47391 (random port if taken) on every interface | Nothing new: it serves the same encrypted sync blobs, and shared folders only when File access is on. It announces a random mDNS name that changes every 15 minutes |
| Tailscale local API (desktop only) | The Tailscale app on the same computer | Voltius reads its list of online peers to find your other devices; it changes nothing there |
| Your other devices | Your laptops, desktops and phones | Their own copy of your vault, synced directly |
Trust boundaries¶
- Inside the Tauri process — full trust, and that includes the webview: the vault key is held in the frontend's memory and passed to Rust over IPC, and decrypted secrets are returned to the frontend whenever a feature needs them (connecting, editing, sync merge). Plugins run in the same renderer, so they share that trust.
- The Voltius server — one service handles both authentication and sync. It sees
auth_key(an Argon2id derivation), email, machine fingerprints, JWTs, and your encrypted blobs. It never sees the password orenc_key, so it cannot decrypt anything it stores. - GitHub Gist — same: encrypted blobs only, plus the PAT you provided.
- Your other devices — a device on the network can reach the listener, but it gets nothing until it proves it holds your vault key (or your pairing group's secret) inside an encrypted Noise channel. A device that passes is one of yours and holds your vault, so it has the same trust as this one. Files are served only to your own account's devices, only from folders you share, and only after you turn on File access and approve the device. See Sync protocol → Local network sync.
Key separation¶
Two keys are derived from your password, and a third, independent one protects Gist sync:
| Key | Use |
|---|---|
auth_key |
Sent to the server for login. The server stores a hash of this — not the password. |
enc_key |
Local accounts: encrypts the local vault. Cloud accounts: the key-encryption key that wraps a random data key (DEK) and your X25519 private key; the DEK encrypts the vault and sync blobs, and only the wrapped copy is stored on the server. Never leaves the device. |
gist_enc_key |
Encrypts Gist-sync blobs. Derived from your Sync Passphrase (or, if you set none, your GitHub PAT) + the manifest salt; independent of your password. |
flowchart LR
classDef cleartext fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000;
classDef secure fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000;
classDef remote fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000;
classDef local fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000;
Pass["Password"]:::cleartext
KDF["Argon2id + HKDF-SHA256"]:::secure
Pass --> KDF
KDF -->|"login only"| AuthKey(("auth_key")):::secure
KDF -->|"vault only"| EncKey(("enc_key")):::secure
GistPass["Sync passphrase\n(or PAT)"]:::cleartext --> GistKDF["Argon2id + HKDF-SHA256\n+ manifest salt"]:::secure
GistKDF -->|"gist only"| GistKey(("gist_enc_key")):::secure
AuthKey -->|"hash stored"| Server[("Voltius server")]:::remote
EncKey -->|"never leaves device"| Disk[("secrets.enc")]:::local
GistKey -->|"never leaves device"| Blobs[("Gist blobs")]:::local
Compromise of one does not yield the others.
Plugins¶
Plugins run as ESM modules in the renderer process, with the app's full privileges — they are not sandboxed or isolated from the host. PluginAPI is the supported surface: stable across releases, permission-declared, and rendered consistently. It omits another plugin's vault keys and direct Tauri commands, and puts terminal I/O and port-forward tunnels behind gated permissions the user approves at install — but those limits are scope, not a security boundary. A plugin is trusted code, the same as a VS Code or Obsidian extension.
The trust boundary is therefore install time, not runtime:
- Marketplace submissions are reviewed before listing.
- Marketplace installs show the plugin's declared permissions for approval first (always for gated permissions; for the rest while the install-review toggle is on, which is the default), and the plugin is enabled once you approve.
- When a listing carries a content hash of its bundle, the install is verified against it and refused on mismatch — binding the reviewed artifact to the executed one (installs from listings without a bound hash are marked Unverified; every official marketplace listing carries one).
- Only install plugins from a source you trust.
See Plugins → Developing for what the supported surface does and doesn't cover.