The two-gate model
PulsVault separates proving who you are (the authentication gate) from proving you can decrypt your vault (the vault-session gate). Learn how unlock, lock, and session timeouts work.
Signing in and being able to read your secrets are two separate things in PulsVault. This is the two-gate model, and it's why you sometimes have to "unlock" even though you're already signed in.
The two gates#
| Gate | Proves | Backed by | Typical lifetime |
|---|---|---|---|
| 1 — Authentication | Who you are | Email + password + 2FA → JWT | ~1 hour (web), longer on mobile |
| 2 — Vault session | You can decrypt your vault | Possession of your unlocked keys → X-Vault-Session |
You choose: 5 min – 24 h, or never |
Gate 1 gets you into the app. Gate 2 gets your keys into memory so items can be decrypted.
Unlocking (opening gate 2)#
There are two ways to unlock:
- Access Key — the standard path. Your KEK is derived from your password and Access Key and your UMK is unwrapped. Right after sign-in the app remembers what it derived from your password for five minutes, in memory only; after that it asks for your password together with the Access Key.
- Trusted device — a previously trusted device relays the unlock so you don't re-enter the key.
A lost Access Key is recovered with your Recovery Key; the Recovery Key does not unlock the vault by itself.
When you unlock, the server issues a short-lived vault-session token. The app attaches it to vault, item, and folder requests as proof you're entitled to the encrypted material.
Locking (closing gate 2)#
Your vault locks — keys are wiped from memory — when:
- The vault-session timeout you chose expires
- You lock manually (in any open tab), sign out, close the app, or reload the page
- A vault-session error is detected (the app re-prompts to unlock)
You stay signed in (gate 1) but must unlock again to read secrets.
On a shared or public computer, pick a short vault-session (5–15 minutes). On your own trusted device, a longer session means fewer prompts. Change it in vault settings.
Why split them?#
- Smaller exposure window. Even with a valid login, secrets stay encrypted until you unlock — and re-lock automatically.
- Defense in depth. Stealing a session token isn't enough to read vaults without the keys, which never leave your device.
- Flexibility. Long-lived logins for convenience; short-lived vault sessions for safety.