Passphrase & key management

It is worth getting this distinction straight, because the two secrets do very different jobs and are handled very differently.

Your vault passphrase is the root of all encryption in zcrypt. It is fed through PBKDF2-HMAC-SHA256 at 600,000 iterations with a per-file salt to derive the Key Encryption Key that wraps each file's content key. The full mechanics are in the encryption model.

• •It is never transmitted to the server and never stored, not even hashed.
• •It lives only in your device's memory while the vault is unlocked, and is discarded when the session ends or the vault locks.
• •Because the server holds nothing derived from it, a strong passphrase is the single most important thing you control. New vaults require at least 10 characters; choose a long, unique one and keep it in a password manager.

Newer clients can also wrap your file keys under one random account master key, itself wrapped under your passphrase-derived key, so a device derives one key per unlock instead of one per file. Writing files this way is off by default and only the instance operator can turn it on; files stay readable either way. Losing the passphrase makes the master key unrecoverable too.

To share with another zcrypt user without ever handing a usable key to the server, every account is bootstrapped with its own X25519 keypair. It is not a third secret for you to remember: it rides on your passphrase, the same way your file keys do. The keypair is generated on your device the first time an unlocked session needs it.

• •The public key is published to a small registry the server keeps in the clear, alongside a short fingerprint, so other members can wrap a shared key to you. It reveals nothing sensitive. That is what public keys are for.
• •The private key never leaves your device in the clear. It is wrapped under your passphrase-derived key using the same PBKDF2 → AES-256-GCM envelope as your file keys, and only that ciphertext is stored. The server cannot unwrap it.
• •Unlocking rehydrates it locally. When you unlock, the client fetches your wrapped private key and opens it with your passphrase in memory; if you have never published one, it generates and publishes a keypair on the spot.

Because your private key is decrypted into the browser while you are unlocked, a cross-site-scripting bug becomes the threat that matters most. As defense-in-depth against it, the web app serves a strict Content-Security-Policy in production. It is enforced: the browser blocks anything the policy does not allow. (A self-hoster can downgrade it to report-only with CSP_REPORT_ONLY=1.) It is a second line of defense, not a guarantee: the web app still runs the JavaScript the site serves you, so the desktop app is the stronger option if that trust matters.

Sessions use signed JSON Web Tokens, with several deliberate hardening choices around them.

• •HS256 with an explicit algorithm check. The verifier requires the header algorithm to be exactly HS256 and rejects anything else, closing the classic algorithm-confusion (e.g. alg: none) attack.
• •Typed tokens. The short-lived token issued mid-login for the 2FA step is a distinct type and is refused at authenticated endpoints, so it can never be replayed past the second factor.
• •Short-lived access tokens. Access tokens expire quickly and are refreshed via a longer-lived refresh token.
• •Refresh tokens are stored hashed. Only a SHA-256 hash of each refresh token is kept, and the issuing IP address (coarsened to its /24 for IPv4 or /48 for IPv6) and user-agent are recorded, and a change of network is flagged in the logs.

Every account carries a token version embedded in its access tokens. Bumping that version instantly invalidates every outstanding token for the account, a single switch to sign out all sessions everywhere, used on password change and on demand.

• •Account recovery (forgotten password) goes through an emailed, single-use reset token: the hash of which is what we store, never the token itself.
• •Vault recovery (forgotten passphrase) does not exist by design; see above. Account access and data access are separate problems.
• •Refresh tokens can be revoked individually or wiped for an entire account, and all of them expire on a fixed schedule regardless.

• •Per-folder encryption. Add a second password to a sensitive folder
• •Shared vaults: how your keypair seals a space key to collaborators
• •Threat model: where a weak passphrase or compromised device leaves you
• •Zero-knowledge architecture: what the server stores about your account