MorphGate syncs through an open protocol called vault-sync/v1. morphgate.com is one implementation of it; the free reference server is another; anyone can write a third. The app has no features that only work with morphgate.com's code: it speaks the protocol, and adapts to what a server says it supports.
What is published
- The contract
spec/openapi.yaml: an OpenAPI 3.1 description of every endpoint, in the public domain (CC0). Generate a server in any language from it.- The design
docs/sync-crypto-spec.md: the threat model, the key hierarchy, the wire formats, sync, devices and sharing.- The reference server
server/: Rust and SQLite, one program, under AGPL-3.0. See Run your own sync server.- The client libraries
- The vault crypto (
crates/mg-vault) and the protocol client (crates/mg-sync), under Apache-2.0 or MIT. - The app
- Under the Mozilla Public License 2.0.
All of it is at github.com/valicm/MorphGate.
How it works, briefly
- The server knows three things: accounts, vaults and items. Items are opaque encrypted envelopes. Everything typed, such as a host's address, lives inside the ciphertext.
- Each vault is a log of revisions. A device asks for everything after the last revision it saw, and sends its changes with the revision it edited from. The server accepts a change only if nobody changed that item in between, and otherwise sends back the current copy. The device resolves the conflict, because only it can read the data.
- Signing in proves knowledge of a key derived from the master password. The password itself is never sent, and the server stores only a slow hash of that key.
- Deleted items stay as markers for at least 90 days, so devices that were away can catch up.
- Files too big for an item, such as attachments and session logs, are uploaded separately, named by the hash of their encrypted bytes, and referred to by a signed item.
- Teams are an optional part of the protocol: organizations, invites, member confirmation, per-vault access and key rotation. The server stores sealed keys and signatures for apps to check, and never holds a vault key.
Discovery
A server describes itself at /.well-known/vault-sync: the protocol version, its limits, and optional features such as two-step verification, email verification, teams, file storage, single sign-on and billing. The app reads it and shows only what the server offers. That's how the same app hides billing on your own server and shows it on morphgate.com.
Versions
Paths start with /v1. Additions keep the version, and older apps ignore what they don't know; items from newer versions of the app sync along without breaking older ones. A breaking change would get a new version.
Test a server
The reference server's tests drive the real app code: sync, conflicts, password change, recovery, signing devices out, teams and file storage. With VAULT_SYNC_URL set, they run against any server instead, which makes them a conformance suite:
VAULT_SYNC_URL=https://sync.example.com cargo test -p vault-sync-server --test protocol --test e2e --test account --test sharing --test blobs
The server under test must accept new accounts without email verification, and each run creates a number of test accounts with @example.com addresses, so use a test instance and raise its rate limits. Tests for optional features run only where the server advertises them. The repository's server/README.md has the details.