Oct 16, 2026 · Valentino Međimorec
The server is a dumb, zero-knowledge blob store behind a published OpenAPI contract (spec/openapi.yaml), so anyone can run their own and the client treats hosted and self-hosted servers identically.
Goals
- End-to-end encrypted sync of hosts, keys, identities, snippets, port-forward rules and known_hosts across devices.
- One open protocol (
vault-sync/v1): the hosted service at morphgate.com is one implementation of it, andserver/is the reference. - Offline-first: the client works fully without a server; sync is additive.
- Shared vaults for teams, in the open protocol behind the
sharingcapability (see Sharing).
Non-goals (v1)
- Server-side terminal relay or recording (session logs are recorded and sealed on the device).
- Server-side search or any feature needing plaintext.
A fully compromised server, ours or a self-hoster's, learns metadata only: account email, item count, sizes, timestamps and device list. It never sees hostnames, usernames, keys or passwords.
| Adversary | Can | Cannot |
|---|---|---|
| Malicious / breached server | Read ciphertext and metadata, drop or replay old blobs, deny service | Decrypt items, forge items (AEAD + signatures), make a client accept a vault revision below one it has seen, or a signed copy of an item older than one it has seen (item history) |
| Network attacker | Nothing beyond TLS failure | Anything: TLS required (the client refuses plain http:// except to this computer), plus E2E |
| Stolen unlocked device | Everything in that vault | Survive revocation for future changes |
| Stolen locked device | Offline brute-force of master password | Succeed quickly (Argon2id, high cost) |
| Malicious self-host operator | Same as breached server | Same as breached server |
Rollback defense. Each client remembers the highest vault revision it has seen. A server answering with a lower one is flagged as an error, not silently accepted. Items have a guard of their own: every write carries a version inside its signed envelope, deletions are signed, and a client refuses a copy of an item older than one it has seen (Item history, under Sync protocol).
KDF bounds. KDF parameters come from the server at prelogin, so the client enforces floors (≥ 64 MiB, ≥ 2 passes, ≥ 16-byte salt) and refuses to derive below them, and ceilings (≤ 1 GiB, ≤ 10 passes, ≤ 64-byte salt), so a server can't make a device allocate or compute without bound.
Metadata hygiene. Item type and size are inside the ciphertext where possible. Padding to 256-byte buckets hides exact sizes.
The master password never leaves the device. It unlocks one account keypair, which in turn unwraps a random key per vault. That extra layer is what makes password changes cheap and team sharing possible.
A master password is set (on creating a vault, changing it, or recovering) only if it has at least 10 characters and zxcvbn estimates at least 10^10 guesses for it. With Argon2id at 256 MiB per guess, that's months of a GPU rig's time for an offline attack on a stolen device or server copy. There are no character-class rules ("one digit, one symbol"): they produce predictable passwords (Summer2024!) that the estimate refuses, and passphrases of unrelated words pass (NIST SP 800-63B). Passwords set earlier keep working.
Master password ──Argon2id(salt)──▶ MK
MK ──HKDF──▶ AuthKey (sent at login; server stores a slow hash)
MK ──HKDF──▶ KEK (never stored)
KEK ─────────wraps──▶ Account keys (X25519 + Ed25519) ◀──wraps── Recovery key
Account X25519 ──sealed box──▶ Vault key (VK, one per vault)
VK ──XChaCha20-Poly1305──▶ Items
Primitives (all via audited Rust crates: argon2, chacha20poly1305, x25519-dalek, ed25519-dalek, hkdf)
| Key | Derived / generated | Used for | Stored on server as |
|---|---|---|---|
| Master password | User | Input to KDF | Never |
MK master key |
Argon2id(password, salt), m=256 MiB, t=3, p=1 | Derive KEK and AuthKey via HKDF |
Never |
AuthKey |
HKDF(MK, "auth") | Server login proof (server stores Argon2id of it) | Hash only |
KEK |
HKDF(MK, "kek") | Wraps the account private keys | Never |
| Account keys | Random X25519 (encryption) + Ed25519 (signing) | Wrap vault keys; sign items | Public: plain. Private: XChaCha20-Poly1305(KEK) |
VK vault key |
Random 256-bit per vault | Encrypt items in that vault | Sealed box to account X25519 public key |
RK recovery key |
Random 256-bit, shown once as a 56-symbol code | Alternate unwrap of account private keys | Private keys wrapped under RK too |
Item encryption. Each item is XChaCha20-Poly1305 under VK with a random 192-bit nonce. Associated data = vault_id ‖ item_id ‖ schema_version, so blobs cannot be swapped between items or vaults.
Password change. Re-derive MK, re-wrap the account private keys, upload. No item is re-encrypted.
With sync on, the server takes the new credentials first (PUT /account/keys with the current
AuthKey as proof) and the device stores them only after that, so the two never disagree. Every
other device is signed out. It keeps opening with the old password until the user signs in again
there; that sign-in downloads the new wrapping, checks it unwraps to the device's own account keys
(same public keys), and stores it, so the local vault opens with the new password from then on.
New recovery key. Same PUT /account/keys, with the unchanged password material plus
recovery. The old key stops working everywhere; nobody is signed out.
Sharing. Each member of a shared vault gets VK sealed to their X25519 key, signed by whoever sealed it. The server stores one sealed VK per member per key generation. See Sharing.
KDF parameters travel with the account (kdf: {alg, m, t, p, salt}) so they can change per account (never below the floors above).
All HKDF is HKDF-SHA256; all info strings are prefixed morphgate/v1/.
| Object | Format |
|---|---|
AuthKey |
HKDF(MK, info=auth) |
KEK |
HKDF(MK, info=kek) |
wrapped_private_keys |
nonce(24) ‖ XChaCha20-Poly1305(KEK, aad=account-keys, x25519_sk ‖ ed25519_sk) |
wrapped_private_keys_rk |
same, key = HKDF(RK, info=recovery-kek) |
recovery_proof |
HKDF(RK, info=recovery-auth) |
| Recovery code | Crockford base32 of RK ‖ SHA-256(recovery-check ‖ RK)[..3]: 56 symbols, 14 groups of 4; decoding ignores case/dashes, maps I/L→1, O→0, rejects typos via the 24-bit check |
wrapped_vault_key |
0x01 ‖ eph_pk(32) ‖ nonce(24) ‖ AEAD(k, aad=0x01‖eph_pk‖recipient_pk, key_id(16) ‖ VK(32)), k = HKDF(X25519(eph, recipient), salt=eph_pk‖recipient_pk, info=vault-key-seal); low-order points rejected |
| Envelope | 0x01 ‖ key_id(16) ‖ nonce(24) ‖ ct ‖ sig(64) |
| Blob | 0x01 ‖ key_id(16) ‖ nonce(24) ‖ XChaCha20-Poly1305(VK, aad, pad₄ₖ(plaintext)), aad = blob ‖ u16 len ‖ vault_id ‖ u16 len ‖ kind ‖ 0x01 ‖ key_id; named by lowercase hex SHA-256 of the whole blob; no signature (the signed item that refers to it holds the hash) |
| Envelope AAD | u16 len ‖ vault_id ‖ u16 len ‖ item_id ‖ u16 schema_version ‖ 0x01 ‖ key_id |
| Envelope signature | Ed25519 over envelope-sig ‖ u32 len(aad) ‖ aad ‖ version ‖ key_id ‖ nonce ‖ ct; verified before decrypting |
| Item plaintext | The item's JSON (Data model) with item_version: the time of the write in Unix milliseconds, or one more than the highest version the writer knows of the item when that is larger |
| Deletion | An envelope of the deleted item (same AAD) whose plaintext is {"type":"deleted","item_version":n} |
| Padding | ISO/IEC 7816-4 (0x80 then zeros) to a multiple of 256 bytes |
Vault meta |
An envelope with item id vault-meta (JSON {name, directory?}), under the vault key, signed by the vault's creator (created_by) |
Sharing (crates/mg-vault/src/sharing.rs). Strings are u16 len ‖ UTF-8; test vectors in the module, computed independently:
| Object | Format |
|---|---|
| Fingerprint | SHA-256(fingerprint ‖ account_id ‖ enc_pub ‖ sign_pub)[..20], as 32 Crockford base32 symbols in 8 groups of 4 |
| Member certificate | Ed25519 over member-cert ‖ org_id ‖ account_id ‖ enc_pub ‖ sign_pub |
| Admin certificate | Ed25519 over admin-cert ‖ org_id ‖ account_id ‖ sign_pub |
| Owner certificate | Ed25519 over owner-cert ‖ org_id ‖ account_id ‖ enc_pub ‖ sign_pub |
| Grant signature | Ed25519 over vault-key-grant ‖ vault_id ‖ key_id(16) ‖ recipient account_id ‖ SHA-256(wrapped_vault_key) |
| Member key signature | Ed25519 over member-key ‖ org_id ‖ account_id ‖ public key (OpenSSH type base64, no comment) |
The server knows three things: accounts, vaults and items. Items are opaque envelopes, and everything typed lives inside the ciphertext.
Server-visible item record
{
"id": "01JABC…", // ULID, client-generated
"vault_id": "01JVLT…",
"rev": 1842, // server-assigned, monotonic per vault
"base_rev": 1790, // rev the client edited from
"deleted": false, // tombstone flag
"device_id": "01JDEV…",
"author_id": "01JACC…", // sharing: who pushed this revision (set by the server)
"envelope": "base64…", // see above
"updated_at": "2026-10-16T10:00:00Z"
}Plaintext item types (client-only schema, schema_version 1)
Serialized as JSON with a type tag and the write's item_version (Item history), then sealed into an envelope.
| Type | Fields | Status |
|---|---|---|
host |
label, hostname, port, user, auth (password {password?} | key {key_ref} | agent), jump_ref? (host to tunnel through, chains allowed, no loops, ≤ 8 deep), vpn_ref? (VPN for the first hop), theme_ref? (a terminal_theme in the same vault, or builtin:<id> for one built into the app), record_sessions?, keep_session? (attach to a tmux session on the server), group_ref? (a host_group), identity_ref? (an identity, instead of user and auth; user may then be empty), tags, notes, source? (the cloud_source that keeps it: source_ref, external_id, label, gone?, state?, host_keys? (its server's keys, listed by a feed), tags? (the ones the feed gave it)) |
Implemented |
vpn |
label, vpn (wireguard {config}: wg-quick text incl. private key) |
Implemented |
ssh_key |
label, private_key (OpenSSH/PEM, as imported), passphrase?, public_key, algorithm, fingerprint | Implemented |
snippet |
name, body, tags, source? (the feed that keeps it: source_ref, external_id) | Implemented (storage only) |
identity |
label, user, auth (as a host's) — shared credentials hosts refer to | Implemented |
host_group |
name, identity_ref?, jump_ref?, vpn_ref?, theme_ref?, keep_session? — a host takes what it leaves empty from its group (credentials only when its user is empty); deleting a group makes those values the hosts' own | Implemented |
attachment |
name, host_ref?, blob, size (see Blobs) | Implemented |
session_log |
see Blobs | Implemented |
port_forward |
label, host_ref, rule (local | remote {bind_host, bind_port, target_host, target_port} | dynamic {bind_host, bind_port}) |
Implemented |
known_host |
host pattern, key type, public key | Planned (today: local known_hosts file) |
cloud_source |
label, provider, endpoint?, key_ref?, account, url?, token? — a cloud account or feed whose machines become hosts, kept in step with it (cloud sources) | Implemented |
host_ca |
label, public_key, hosts (patterns) — a CA whose signed host keys are trusted for those hosts (@cert-authority) |
Implemented |
terminal_theme |
name, background, foreground, cursor, cursor_accent, selection_background, selection_foreground?, ansi (16 colors), all #rrggbb; imported from Ghostty, Alacritty, iTerm2 or Windows Terminal theme files |
Implemented |
member_key |
account_id, public_key (OpenSSH type base64), label, sig (member key signature, hex) — only in an organization's directory vault |
Implemented |
New fields are additive; readers ignore unknown fields, so schema_version only changes for breaking changes.
References between items (*_ref) are item ids. They resolve client-side only, so the server cannot see the graph.
The client is offline-first: the vault exists on the device before any server is involved, and its rows are exactly what sync will push.
- One SQLite file in the app data dir (
vault.sqlite3, mode 0600,secure_deleteon). account: KDF params, public keys,wrapped_private_keys,wrapped_private_keys_rk(same values the server gets at register).vaults: id,key_id,wrapped_vault_key,head_rev(highest server revision seen, for the rollback guard).items: id, vault_id, envelope (NULL for tombstones, except a deletion made on this device, which keeps its signed envelope),deleted,rev(server rev the copy is based on; 0 = never synced),dirty(unpushed local change),updated_at,version(the one in the envelope) andseen_version(the one of the last copy the server confirmed).- Nothing typed is stored in plaintext: hostnames, users, passwords and keys exist only inside envelopes.
- Unlock = Argon2id + unwrap account keys + open vault key, all in memory. Lock drops every key and closes open sessions.
- Optional per device: a random device key in the OS keychain (
device_unlockholds the account keys wrapped under HKDF(device key,device-kek)). It unlocks without the master password, survives password changes and recovery, never syncs, and is tried automatically only at app launch. The device can also require Touch ID, Windows Hello or polkit (Linux) before the key is read. That is a check made by the app: it stops someone at an unlocked computer, not malware running as the user. - Every read verifies the envelope signature and its binding to
(vault_id, item_id); a tampered or swapped row fails loudly instead of being skipped. - Shared vaults: items are keyed by
(vault_id, id)and keep theirauthor_id.vault_keysholds every key generation sealed to the account,orgsthe pinned root of each organization, andpinned_keysevery account key the device verified. Items in the personal vault verify only against the account's own key, whatever author a server names. References (*_ref) must stay within one vault. A vault this account lost access to is removed from the device on the next sync. - Secrets flow one way: the UI sends passwords/keys into the Rust core, and views returned to the UI carry only
saved: true/ fingerprints.
Sync is a per-vault revision log. Pull is "give me everything after rev N". Push is a batch with optimistic concurrency per item. Conflicts resolve on the client, because only the client can read the data.
- Pull.
GET /vaults/{id}/changes?since={rev}&limit=500returns items withrev > since(tombstones included) plushead_rev. Page untilhas_more = false. - Decrypt & apply. Verify signature, decrypt, check the item's version (Item history), merge into local SQLite. Store
last_rev. - Push.
POST /vaults/{id}/changeswith a batch of{id, base_rev, deleted, envelope}.- Server accepts an item if its current rev equals
base_rev, or the item is new. - Otherwise it rejects that item with
conflictin the per-item result and returns the current server copy. - Accepted items get a new
rev. The batch is atomic per item, not per batch.
- Server accepts an item if its current rev equals
- Resolve conflicts. The server's copy wins for that item id, and the local edit that lost is kept as a new item named "(conflict)", so nothing is silently discarded. Conflict copies are ordinary items: they stay until someone deletes them.
- Realtime nudge (optional).
GET /vaults/{id}/eventsvia SSE sends only{head_rev}. Clients then pull. Self-hosters can skip this; clients fall back to polling: every 60 s while someone uses the app, every 5 minutes while nobody does (window hidden, or no input for 5 minutes), and at once on coming back. Local edits push within seconds either way. - Quiet rounds are cheap. A round lists the account's organizations (
GET /orgs) and vaults (GET /vaults). A vault whosehead_revthere equals the device'slast_revisn't pulled. An organization whoserev(optional) equals the one the device saw last isn't fetched again: its details, members, device approvals and vault members are reused, and verified again locally (the device's own pins may have changed). So a quiet round is two requests, however many organizations and vaults there are.
Tombstones. Deletes are items with deleted: true. A client with item history sends the deletion's signed envelope along (at most 1 KiB, under any key generation of the vault); a server with features.signed_tombstones keeps it for an item it has and returns it with the tombstone, and others ignore it. The server keeps tombstones for at least 90 days. A client whose last_rev is older than the oldest retained tombstone gets 410 Gone and does a full resync.
Item history. The vault's revision only says how far a device has read. Each item also has a version inside its signed envelope, so a server can't serve a device a copy of an item older than one it has seen:
- Every write carries
item_version(Wire formats): an edit, a conflict copy, a re-seal under a rotated key, a deletion. Versions grow along an item's history because a server takes a write only on the item's latest revision (base_rev); the clock keeps them growing for an item made again after its tombstone was purged. - A client remembers the version of the last copy of each item the server confirmed (pulled or pushed). A signed copy with a lower version, item or deletion, is refused: the vault's sync stops with an error, as for a vault revision below the one seen. An equal version is taken (the same write again, or an older app's re-seal of it, which keeps the plaintext).
- Apps from before item history (0.2.0) write items without
item_versionand delete without an envelope, and ignore both in what they read. A client takes such a change, and the next versioned copy starts the count again (its writer may not have seen the earlier ones). So the guard holds once every app that writes to a vault has item history. Strict item history, a client setting, refuses both kinds of change to an item that has a version; it is off while such apps may still write. - Not covered: a client without a copy of an item has nothing to compare it with (a new device,
or one starting over after
410), so a server can still serve it an old copy or leave an item out. That needs signed checkpoints of a vault's state.
Blobs and session logs. What is too big for an item goes in a blob
(/vaults/{id}/blobs/{hash}, behind features.blobs): sealed under the vault key (Wire formats),
named by the SHA-256 of its bytes, uploaded separately, and referred to by a signed item that
carries the hash. The server checks the name, the size and the owner's quota, never the content;
kind is session_log or attachment (a server may keep them apart, e.g. for retention). Clients
upload a blob before the item that names it, keep refused uploads (402, 413) for later rather
than failing the sync, delete the blobs of items they delete, and drop local copies no live item
refers to. A blob that comes back from the server is checked against its hash before it is
opened.
A session log item (type: session_log) records one terminal session of a host with
record_sessions: host_ref, title, address, started_at/ended_at (Unix ms), cols,
rows, output_bytes, the recording device, and chunks ({hash, size} in order). Each
chunk's plaintext is a raw DEFLATE (RFC 1951) stream; inflated and concatenated in order, the
chunks are an asciicast v2 file (a header line, then [time, "o", output] and
[time, "r", "COLSxROWS"] events). Recorders seal a chunk every 512 KiB of asciicast or 60 s and
update the item each time, so a crash loses little. An organization's
session_log_retention_days makes the server delete older session log blobs; a log whose
chunks are gone says so instead of playing.
An attachment item (type: attachment) keeps one file with a host: name, host_ref, blob
(the hash) and size (plaintext bytes), the file sealed whole into one attachment blob (up to
20 MiB, so it stays under servers' 25 MiB blob limit). Deleting the host deletes its attachments.
Limits. Max envelope 64 KiB, max 500 items per push. Servers advertise their own limits in capabilities.
Login proves knowledge of AuthKey and returns short-lived tokens. The client never sends the master password, and the server can't derive KEK from what it stores.
POST /auth/prelogin {email}returnskdfparams and salt. For unknown emails it returns deterministic fake params to avoid user enumeration.- The client validates the params against the floors, derives
MK, thenAuthKey. POST /auth/login {email, auth_key, device}returnsaccess_token(15 min, opaque),refresh_token(rotating, 90 days; replaying a used one revokes the device), and the wrapped account keys.- The client unwraps the private keys with
KEK. If the user opts in, a device key in the OS keychain can unlock them later (see Local vault).
Devices. Each login registers a device (name, platform, public Ed25519 key). GET /devices lists them and DELETE /devices/{id} signs one out: its tokens stop working, and its next refresh gets 401 device_revoked (servers keep answering that for the refresh token's lifetime), on which the app erases what it keeps (vaults, keys, settings, pinned host keys, its keychain entry) and returns to first run with a note saying why. Only that code erases. 401 account_deleted (the account was deleted from another device or a website) turns sync off as Disconnect → Keep a copy does: the personal vault stays, now the only copy, and team vaults go. Every other 401 (an expired session, a reused refresh token, a password changed on another device) means "sign in again", and the data stays. A device that never connects again keeps what it has, encrypted under the master password, so the UI says signing out takes effect when the device next connects. A device's own Disconnect asks whether to erase it too or keep a copy that no longer syncs.
2FA. TOTP on the account, checked at /auth/login; set up and turned off through
/account/totp…, and turned off by recovery. An organization can require it
(policies.require_totp): its vaults answer 403 totp_setup_required (with org_id) to a member
without it, and GET /vaults leaves them out, so the app checks the account when none of such an
organization's vaults is listed. WebAuthn isn't supported yet. Email-verified sign-up,
email changes and an account portal are optional features of the API spec
(spec/openapi.yaml).
Recovery. Lost password with a recovery key: POST /account/recover with recovery_proof returns wrapped_private_keys_rk and a single-use, access-only token. The client unwraps with RK (on a device that has the vault, the keys must be its own), wraps them under a new password, and sends that with the token to PUT /account/keys. Every session ends, so the device then signs in with the new password; this works on a fresh device too. Lost both: the account can be reset, but the data is unrecoverable by design, and no server operator can help: the app says so when it shows the recovery key, once, at sign-up.
Self-hosted auth. The same flow is mandatory in the spec.
Single sign-on (features.sso) is per organization and layered on top of the AuthKey
proof, never instead of it, since key unwrapping still needs the master password. An organization
with an identity provider (OIDC or SAML, set up on the server's website) and require_sso gets
403 sso_required (with org_id) on its vaults until this device has signed in there: the app
calls POST /orgs/{id}/sso/start, opens the returned URL in a browser, and retries once the user
is back. Sessions are per device and expire; a member removed from the organization, or a
provider removed, ends them. Personal vaults are never affected.
Device approval (policies.require_device_approval) adds a check after that one: a device
the organization hasn't approved gets 403 device_approval_required (with org_id, device_id
and status, pending or denied) on its vaults, so a stolen master password isn't enough on
someone else's machine. The first refusal files a request; listing vaults files it too, and
leaves those vaults out, so a new device learns it waits from its own entry in
GET /orgs/{id}/devices. Owners and admins approve or deny anyone's devices, members their own
other devices (POST /orgs/{id}/members/{account}/devices/{device}/approve or /deny), always
from a device the organization approved. Turning the policy on approves the signed-in devices of
confirmed members, confirming a member approves theirs, and signing a device out forgets its
approvals. Like single sign-on, it gates access to ciphertext only: keys never depend on it.
An organization owns shared vaults, and each member gets read, write or manage on each vault. Owners and admins open every organization vault. Personal vaults stay personal. This section is the protocol as implemented; paths and schemas are in spec/openapi.yaml (tag organizations).
What the server stores. Organizations (plaintext name, policies, the ownership chain), members (role, accepted or confirmed, certificates), invites (token hashed, single use, 7 days, bound to the address), vault grants, and a key ring per vault: one sealed key per account per generation, each with its grant signature. Items gain author_id. Vault names stay inside the encrypted meta.
Joining.
- An admin invites an address, optionally with vault grants. A server that mails invites sends the link; otherwise the admin gets the token to pass on.
- The invitee's app reads
GET /invites/{token}: the organization's name and its ownership chain. It pins the chain's first link (the creator), checks the chain to the current owner, and shows that owner's fingerprint to compare out of band. - The invitee accepts (
accepted): the server shows their keys to admins. - An admin's app compares the member's fingerprint with them out of band, signs a member certificate and seals each granted vault's keys to them, with grant signatures (
confirmed).
Whom an app trusts. Nothing the server says about keys is taken as is:
- Owners: the pinned root, then each later link of
owner_chain, verified with the previous owner's signing key (owner certificate). The creator pins themself. - Admins: an admin certificate by a verified owner.
- Members: a member certificate by a verified owner or admin (
signer_id). - Vault keys: a sealed key is used only if its grant signature verifies with a verified member's signing key. It matters because a sealed box doesn't say who sealed it, so without it a server could seal a key of its own to a member and read what they write. Grants by someone who has since left still count when this device verified them while they were a member (their pinned key), for older generations, and for the current one only while a rotation is due (so an admin can rotate). An older generation that can't be verified is left out; the current one must verify.
- Items: each envelope is verified with its author's verified signing key (
author_id); a personal vault's items with the account's own. - Pins: every verified account key is pinned. A different key for a known account is a hard error, not a prompt.
Certificates grant nothing; the server decides membership and permissions. It is trusted for that: it could keep serving a removed member, or accept pushes from a read member, but it can't read or forge items, slip in a key, or give anyone a vault key.
Key generations. Envelopes carry key_id, so a vault can have several generations. GET /vaults returns the caller's copy of each (keys), and key_id/wrapped_vault_key stay the current one for older clients. Removing anyone sets rotation_due. An app with manage then:
- Generates a new key, seals it to every account with access (owners and admins included), and switches with
POST /vaults/{id}/keys. The server requires every account (incomplete_rotation) and the current generation asprevious_key_id(409). - Re-encrypts every live item under the new key in ordinary pushes. A push under an older generation is refused per item with
stale_key; any app withwritefinishes the job.items_on_old_keyscounts what's left.
Rotation keeps a removed member from reading anything written afterwards. It doesn't un-share what they already synced: changing those secrets is the offboarding job.
Member key directory. Offboarding has to find a removed member's SSH keys on shared hosts, so members publish the public halves of the keys they use there. Each organization has a directory vault: an ordinary organization vault whose meta says directory: true, so servers need nothing new.
- Owners' and admins' apps create it when the organization has none, and keep every confirmed member at
writeon it. When two appear, apps use the one with the lowest id. - A member's app publishes
member_keyitems in it, each signed by the member over the organization, their account id and the key. - Readers accept an entry only if that signature verifies with the member's verified (or pinned) signing key. The envelope's author doesn't decide it: rotations re-encrypt every item under the rotating admin's signature, and entries must still verify after the member is gone.
- Any member with
writecan delete another member's entry, but can't forge one.
What the server enforces. Push needs write (403 not_permitted); grants and rotation need manage; confirming an admin, inviting admins, promotions and ownership transfer are the owner's. Organization vaults are created with keys for every owner and admin (incomplete_keys), and members create them only when the members_can_create_vaults policy allows. The owner can't leave or delete their account (409 sole_owner); DELETE /account (the AuthKey proves the password) removes anyone else's account, leaving its organizations, and the app then turns sync off on that device. The server keeps an audit log of what it sees (GET /orgs/{org}/events).
We publish vault-sync/v1 as an OpenAPI 3.1 document plus a conformance test suite. Any server passing the suite is a supported backend, and the client has no hosted-only code paths.
What we publish
| Artifact | License | Purpose |
|---|---|---|
spec/openapi.yaml (vault-sync/v1) |
CC0-1.0 | The contract; generate servers in any language |
tools/vault-conform (runs against a URL) |
Apache-2.0 OR MIT | Pass/fail per endpoint, with throwaway accounts: auth, devices, sync (conflicts, 410, pagination), sharing, blobs |
Reference server (server/, Rust + SQLite, single binary, Dockerfile) |
AGPL-3.0 | So self-hosting is docker run, not "implement the spec" |
Capability discovery. GET /.well-known/vault-sync, which needs no session (like the sign-up and sign-in steps), returns the spec version, limits, and optional features (Capabilities in the spec: registration_open, terms, email_verification, sse, totp, signed_tombstones, blobs, sso, sharing, billing). The client adapts its UI from that response; for example, it shows no plans when billing is absent.
Versioning. The path prefix is /v1. Additive changes are minor and must be ignored by older clients. Breaking changes go to /v2, and the client supports N and N-1.
A server may sell plans; how is outside vault-sync/v1, and self-hosted servers usually have
none. A server with plans says so in features.billing (plans_enforced), and reports each
account's and organization's Entitlement (plan, status, expires_at, grace_ends_at, …;
see the spec). Where plans are enforced:
| State | Pull | Push |
|---|---|---|
| Active or on a trial | Yes | Yes |
Ended, within its grace period (grace_ends_at) |
Yes | Yes, with a notice |
| Ended after grace | Yes (always: it's their data) | 402 payment_required, with a reason and a billing_url |
Users can always pull and export, even after a plan ends. The app shows what the server reports; it sells nothing itself.
Each component's license is in CONTRIBUTING.md: the apps and the client crates MPL-2.0, the crypto and protocol crates Apache-2.0 OR MIT, the reference server AGPL-3.0, the spec CC0. Contributions are signed off under the Developer Certificate of Origin.