Limestone encrypted vaults¶

Encryption for shared vaults (ADR-0091, key custody per ADR-0125). A local vault stays plaintext and fast; a shared vault is encrypted so access is controlled by membership of your organization, not by who a Drive folder happens to be shared with.

What Limestone can and cannot see. Your vault's files never reach us — they live in your own folder and sync through your own Drive or Dropbox. What we do hold is each shared vault's key, so that signing in is enough to open the vaults shared with you. That means Limestone can decrypt a shared vault's contents, and so could anyone who compromised or compelled us.

This is a deliberate trade, and it replaced an earlier design in which we held no keys at all. That design cost every user a second passphrase, a first-run setup step, a recovery code, and — for organizations — a shared escrow passphrase, all because we had made ourselves unable to answer "is this person allowed in?". All four are now gone.

What you keep either way:

your files are ciphertext at rest and everywhere they sync, so Dropbox and Google Drive still see nothing;
filenames stay opaque, so a folder listing reveals no titles or structure;
sharing a Drive folder still grants nobody access;
and your organization holds a key file we never see, so you can open and export your vaults even if Limestone is unreachable, or gone.

What it protects (and what it doesn't)¶

Encrypted at rest, everywhere it syncs. Note bodies, data files, notebooks, attachments, the members list, collection schema, and version history are all ciphertext on disk. Whoever the Drive/Dropbox folder is shared with — including the storage provider — sees only ciphertext.
Opaque filenames (ADR-0092). Files and folders are named by internal ids, so a folder listing reveals no titles, collection names, or structure — the readable names live only in the encrypted content. What still leaks on any synced store: the number of files/folders, their sizes and modification times, and the file-type mix (.md/.csv/…) — "metadata shape," not content or its names. The local search index (on your own machine, never synced) stays plaintext; encrypting it is a separate follow-up.
Membership is access. You can open a shared vault if you are a member of the organization that owns it. Removing someone stops us releasing the key to them straight away — but a key already on their laptop is beyond our reach, so rotating the vault's key is what actually locks them out of anything written afterward.

How the keys work¶

Each vault has one data key. There are three ways it reaches you, tried in this order, and none of them asks you to type anything:

This device. A key your machine has already been given is kept locally, so a vault you have opened here opens again with no network at all.
Your account. Limestone holds the key and releases it to members of the owning organization. This is why signing in is enough, and why a new member needs no admin to act for them. Keys are stored encrypted, so a database dump alone opens nothing — but we hold the means to decrypt them, which is the trade described above.
Your key file. Every organization gets one when it's created, downloaded once and kept by you — in a password manager or a safe. It is wrapped into every vault your organization owns, so it opens them with no Limestone server involved. This is what makes an outage an inconvenience rather than a loss, and it is why we ask you to save it before you can continue.

Limestone does not keep a copy of your key file and cannot reissue it.

Encrypting a vault¶

Open the vault, then Vault ▸ "Encrypt this vault…" (you must be signed in).
Confirm. There is nothing to choose and nothing to write down.

Existing files are re-encrypted in place and their names become opaque. The vault's key is wrapped to your organization's key file and published to your account, so every member can open it.

You cannot encrypt a vault before your organization has saved its key file. That is deliberate: a vault encrypted with no key file could not be opened if Limestone were unreachable.

Unlocking¶

Usually you don't. Opening a shared vault gets its key from this device or from your account, and the vault simply opens.

You see "This vault is encrypted" only when neither worked — you are offline on a machine that has never opened this vault, or you are not a member. Then the gate offers recovery with your key file, described below.

If you are a member and this happens on a vault encrypted before ADR-0125, an admin needs to open it once — that is what publishes its key to the organization. Try that before recovering anything.

Decrypting a local vault¶

A personal vault can be turned back into a plain, unencrypted vault — useful if you encrypted it to try the feature or no longer need it.

Open the vault (it unlocks on its own if you have opened it here before).
Settings ▸ Vault ▸ Encryption ▸ "Decrypt this vault…", then confirm.

Every file is decrypted in place and readable filenames are restored (attachments keep their internal names — the original was discarded when the vault was encrypted). The lock badge next to VAULT disappears.

Decrypting is blocked for a vault owned by an organization. Its key is held for every member, so un-encrypting it would strip protection from other people's data as well as yours. Move it out of the organization first. You can also click the lock badge left of the VAULT label at any time to jump to these controls.

If the reason you want it decrypted is that Limestone is unreachable, that is what recovery is for — see below.

Your key file, and recovery¶

Every account and organization gets one key file when it is created, and saving it is not skippable. It is the one thing that gets your data out with no Limestone server at all.

It is a fire escape, not a second way to sign in. Using it does one thing: it recovers the vault — decrypts every file in place, restores readable names, and makes the vault local. An organization's vault stops being shared.

That pairing is deliberate rather than a limitation. "Shared" means the account service releases the key to members; if that service is reachable you did not need the key file, and if it is not, no sharing can be honoured anyway. Handing back an unlocked-but-still-shared vault would be promising something nobody can keep. So recovery converts the vault into the thing it can actually be on its own: a plaintext folder you hold outright.

To recover a vault: open it, and when the gate appears choose "Recover with a key file…", read what it costs, pick your key file, and confirm. It touches no network. Afterwards the folder is ordinary files you can read, copy, or re-encrypt.

It cannot be undone from inside Limestone — if you want the vault protected and shared again, encrypt it again once you can sign in.

Keep it where you keep a password-manager export or a safe-deposit item. It will still matter in five years.
We do not have a copy and cannot reissue it. Lose it and you lose the offline path — not your data, as long as your account still works.
If it leaks, an owner generates a new one and rotates each vault's key (below). The old file then opens nothing written afterwards.

Encrypt the vault first (sharing an unencrypted vault is blocked).
Vault ▸ Share ▸ Connect this vault to your account, then invite members by handle or email.
That is the whole of it. A member opens the vault by signing in — there are no keys to hand out, nothing for them to set up first, and no admin who has to be present for it.
Share the underlying folder (Drive/Dropbox/…) with them too — that just distributes the ciphertext; membership is the real access control.

Removing a member takes effect the next time their Limestone can reach us: before opening a shared vault it asks whether the person is still entitled to the key, and on being told no it deletes the copy held on that device and shows them that their access was removed. The vault's files stay on their disk, encrypted.

Being offline delays it, but no longer indefinitely. A device that has not had your membership confirmed for 24 hours stops opening the vault from its cached key until it can ask us again. So a removal takes effect within a day whether or not the person cooperates, and no vault has to be re-encrypted for it.

Owners are exempt, deliberately. An owner holds the account key file and can already recover the data with no Limestone in existence, so expiring their cache would take away convenience without taking away any power — and it would turn an outage into apparent data loss for the one person who most needs it not to be. If we ever have to switch the servers off, owners keep working.

The remaining limit is honest and unavoidable: this is a cooperating-client control, not a cryptographic one. Someone who deliberately copied the key out of their own machine keeps whatever had already synced to them, and no message from us reaches it.

Rotating the key is the answer to that. It mints a new key, re-encrypts every file to it, and republishes — so anything written afterwards is unreadable to the old key, wherever that key ended up, and every other member's device has to come back to us for the new one. Anyone who had the vault open at the time is told it was re-keyed and reopens. It cannot un-read what someone already copied, which is unavoidable once bytes have left your machine.

Rotation is a deliberate act in Settings ▸ Vault ▸ Encryption, not something removing a member does automatically: re-encrypting an entire vault is not a thing to trigger by accident, and the check-in deadline already handles the ordinary departure.

Rotating a vault's key¶

Settings ▸ Vault ▸ Encryption ▸ "Rotate key to revoke…" (admins, on an open vault). It mints a new key, re-encrypts every file to it, wraps it to your organization's key file, and republishes it — so everyone still in the organization keeps access without doing anything.

Rotate when you remove someone who should not keep reading, or when a key file may have leaked. It protects future content only.

Where to store a shared vault¶

Because the vault is end-to-end encrypted, the ciphertext is safe to put anywhere — the storage choice is now about sync convenience, not trust:

Google Drive / Dropbox / OneDrive / iCloud Drive — a desktop-sync folder mirrored to each collaborator; point Limestone at the local mirror. Drive is fine for ~10 people editing mostly their own notes (asynchronous; it is not real-time co-editing, and concurrent edits to the same note may create merge conflicts that Limestone reconciles).
Syncthing — peer-to-peer, no third party ever holds even the ciphertext. The strongest privacy option; devices sync directly when online.
Your cloud node (ADR-0065) — your own always-on box can double as a private sync peer.

Limestone deliberately has no Google Drive API integration — it treats a shared vault as "an encrypted folder some external tool syncs," so you stay in control of where your data lives.

Gotchas¶

Losing your key file is survivable; losing your account access is what to worry about. As long as you can sign in, your vaults open. The key file is the answer to us being unreachable, not to you being locked out.
A vault nobody has opened since this changed still carries only its old keyring. An admin opening it once publishes its key; until then, new members cannot get in.
Removing a member is instant at our end and not at theirs. Rotate the key if that distinction matters for the vault in question.
A shared Drive folder being over-shared is no longer a leak — non-members just get unreadable bytes.