Key security features
- Agents never hold your secrets. A broker on your computer makes calls for them. The broker
- We can't read your vault. It is encrypted on your device, with keys we never receive. Your vault
- Two keys open your vault: your passphrase and an Account Key that never leaves your device. Two keys
- Nothing we store helps anyone guess your passphrase. Two keys
- Only your paired broker can ask for a brokered secret. Every request it makes is signed. Signatures
- Secrets that matter wait for you. You approve each new destination. Ask me first
- Where your secrets went is recorded on your computer, not ours. What we know
- Every use is in a tamper-evident log. Logs
- Repairing an agent replaces its vault key, not just its password. Repair
- The connection to us already uses post-quantum key exchange. The connection
Principles
01
We protect your secrets by not knowing them.
It is impossible to lose or misuse what you don't have. So we store your vault but can't open it. Before an account locks, we see destinations submitted for approval. After locking, the details of every approval request are hidden from us too: web destinations and reasons, and the payee and amount, what is to be signed, or the recipe.
02
Agents get results, not secrets.
An agent that holds a secret can be tricked into sending it somewhere. So agents never get one. They ask a broker to act, and the broker keeps the secret.
03
Encryption first, then your computer's own walls.
Wherever we can, a secret is protected by encryption rather than by a rule. Where encryption can't help, because the broker has to use the secret, we rely on the separate accounts your operating system already enforces.
04
Write down what we don't protect.
This paper and our limitations page say where the protections stop. If a claim here turns out to be wrong, we correct it in the changelog, dated.
Who's who
- You, the owner
- You create the vault, decide which agent gets which secret, and approve the ones that matter.
- Your browser
- It does all the encryption for your vault. Your passphrase never leaves it.
- Our server
- It stores your encrypted vault, checks requests and sends approval emails. It can't read your secrets.
- The broker
- The helper app: a small program on your computer, running under its own account. It holds your agents' secrets and makes calls with them. The rest of the vault and site call it the helper app; this paper uses its technical name.
- Your agents
- Claude, Codex or any MCP client. They talk to the broker and never receive a secret.
Your vault
Your vault is locked on your device, with a key made from two things: your passphrase, and an Account Key your browser creates and keeps. We receive only the locked result.
Two keys, not one
If someone broke into our servers, they would find locked data and nothing that helps them guess your passphrase. Even if they guessed it, they would still need your Account Key, which has never been anywhere but your device.
For the technically curious: how the keys are made
- The browser generates a 16-byte Account Key and keeps it locally. It is never sent to us.
- Your passphrase is stretched (below), then combined with the Account Key through HKDF-SHA256 into two separate keys: one that proves to us you know the passphrase, and one that encrypts your vault.
- We store only a hash of the proof key. It can't be turned back into the key, and because the Account Key is mixed in, it can't be used to test passphrase guesses either.
- Vault contents are encrypted with AES-256-GCM, with a fresh 12-byte nonce for every write. Once every computer on an account runs the new version and no secret is still set up the version-1 way, the owner's next unlock also seals names, tags, shapes, services, part names and usage setups with keys derived from the vault key. This includes headers, templates, basic-auth usernames, SSH hosts, private addresses and signed operations. Our server erases its plaintext copies in one transaction. Until that account locks, those metadata remain readable by our server.
- The vault's own key is random. It is stored wrapped: once under your key, and once for each agent. Revoking an agent discards its wrapping.
Slow to guess, on purpose
Before your passphrase is used, it is run through Argon2id, which deliberately takes memory and time. That is unnoticeable when you unlock once, and very expensive for someone trying billions of guesses.
For the technically curious: the settings, and moving older vaults
- Argon2id with t=1, m=46 MiB (47,104 KiB), p=1: OWASP's first-choice setting. Memory is what password-cracking hardware can't cheaply add.
- Existing vaults move from PBKDF2-SHA256 (600,000 rounds) to Argon2id the next time their owner unlocks, because that is the only moment the passphrase is present. The account records which method was used, so an upgrade can never lock you out.
- A browser that can't run Argon2id (WebAssembly turned off, as in iPhone Lockdown Mode) creates new vaults with PBKDF2 instead, and reports it. A vault already on Argon2id can't be opened in such a browser; the page says why instead of reporting a wrong passphrase.
The broker
The broker is a small program that runs on your computer under its own account, separate from yours. Your agents run as you, so they can't open the broker's files or look into its memory. It is the same separation that stops one person on a shared computer reading another's documents. Its code and bundled Node live in a root-owned install folder, separate from broker data: /opt/wundervault on Linux and macOS, or %ProgramFiles%\Wundervault on Windows. A privileged root updater installs updates. After one final manual update, use Vault → Computers → "Update now" with one passkey check. Your browser seals the order to that computer's broker; our server relays it but cannot read or forge it. The updater downloads the release, verifies a release record signed with the owner's release key, and checks every file hash. It installs beside the old version, switches, restarts and checks health. If the new version is unhealthy, it rolls back automatically. New updates are forward-only; rollback is recovery from a failed update, not permission to install an older release. Agent apps pick up updates when reopened, and the vault flags older app copies.
For the technically curious: each operating system
- Linux. A
wundervaultsystem account; its store in/var/lib/wundervault, readable only by that account. The systemd service drops every special privilege and sees the rest of the system read-only. The store's own key is sealed withsystemd-creds, to the TPM where the machine has one. - Windows. A dedicated account runs the broker as a scheduled task. Agents reach it over a local-only connection, and it proves it owns that connection by signing a challenge. Tested on Windows 10: an ordinary account and an unelevated administrator are both refused its files.
- macOS. A LaunchDaemon runs the broker as its own
_wundervaultaccount, with a store only that account can read: the same separate-account design as Linux. macOS has no equivalent of the Linux service lockdown, so here the separate account is most of the protection, and FileVault is what protects the store's key on a stolen disk. - Agents talk to the broker over a local socket and prove which agent they are with a per-agent token.
- The broker never runs a command on your computer for an agent. It makes web requests and signatures (SSH logins, wallet payments within your rules, data you approve), nothing else. For SSH, your agent's own
sshclient runs the remote command; the broker only signs the login.
Pairing and signatures
You pair your computer's broker with your account once. After that, our server only hands a brokered secret to a request your broker signed. Someone who copies an agent's password from somewhere still can't use it to get your secrets.
For the technically curious: the pairing and the signature
- During installation the broker creates a P-256 key pair. The private half stays in the broker's store.
- The pairing command,
sudo /opt/wundervault/current/node /opt/wundervault/current/app/bin/wundervault-agent --pairon Linux and macOS (bundled Node and the broker by full path in the root-owned install folder, as the installer prints it: with sudo, a bare name could resolve to a program in a folder the user's agents can write), sends the public half and shows a fingerprint. You confirm the same fingerprint in your dashboard. - When you set up or repair an agent, its credential is sealed to that broker's key (ephemeral ECDH, HKDF-SHA256, AES-256-GCM). You carry a claim code to the computer; it names the sealed package and opens nothing.
- Every request from a paired broker carries an ECDSA signature over the method, the exact path, a hash of the body, a timestamp and a one-time nonce. We refuse a missing, stale (over 120 seconds), replayed or wrong signature.
Brokered calls
Your agent can use a secret in four ways, and none hands it over. For a web service, the broker sends the request with your secret attached, or signed with it, and returns the answer. For SSH, the broker signs the login while your agent runs the connection. A wallet pays inside your rules. A signing key signs what you approve.
Web services
- The agent names the destination, method, path, headers and body. When adding a key, you can search for a service and paste its named parts into boxes labelled the service's way. The catalogue sets delivery, service addresses and approval. Any other service is added by name and set up by hand, and an optional one-time tidy-up card helps file existing keys better. The broker places each named part separately: as a bearer token (
Authorization: Bearer …), in a header you name or a query parameter, as a username and password, or as part of the web address. This supports two-header credentials, key-plus-email credentials and basic-auth pairs. The agent cannot override credential-bearing fields. - Or the secret never travels: each request carries a code made from it (an HMAC, AWS Signature Version 4, or OAuth 1.0a for X and services like it, where the broker keeps all four values and signs each request itself). Your agent describes how the service wants it; you approve each new way once per address. The secret is only ever the signing key, never part of what is sent.
- Not yet: a token exchange (OAuth), a client certificate, or requests signed with a key pair.
- HTTPS only, with real certificate checks. Redirects are not followed with your secret attached.
- Private network addresses are refused unless you have allowed a specific one for that secret.
- Every named part, including IDs and usernames, is scrubbed from replies before the agent receives them. Answers have size and time limits.
Wallets and signing keys
- A wallet pays x402 requests in USDC on Base and Solana. The broker builds and signs the payment itself; the token's contract and signing details come from the broker, never from the merchant.
- You set a daily limit and the payees you trust. Inside those, the broker signs at once. Anything else waits for you. A new wallet's limit is $0.
- Your rules are encrypted in your browser with the agent's key. Our server stores them and can't read or change them, and the broker refuses rules older than ones it has seen.
- When you approve, your browser seals the approval to exactly what you were shown. The broker opens the seal and refuses if the payment, the bytes or the recipe differ. Our server can delay an approval; it can't make one.
- A signing key signs only what you approve, one signature at a time. SSH keys and wallet keys are refused as signing keys.
- Our server learns that a payment or signature happened. The payee, amount and data reach it only while you are being asked, and are erased when you decide.
Run without asking, or ask me first
- Run without asking
- The call goes ahead. It is logged on your computer, and the first time that secret goes somewhere new, we can email you.
- Ask me first
- The first call to a new destination waits. You see where it is going, with which method and path, and approve it once or for a time window. Approval needs a passkey check from the last hour. After the account locks, the broker seals the web request's key name, destination and reason. Our server matches approvals using an HMAC it cannot reverse; your browser opens and checks the details. Within a window, calls to the same destination, method and path go ahead whatever they contain; anything different asks again.
SSH
- The broker serves the SSH signing protocol on a temporary socket for one connection. Your agent's
sshuses it; the key never leaves the broker. - Each SSH key lists the hosts it may be used with. A key with no hosts listed can't be used at all.
Approvals and alerts
When a secret needs you, it waits under Approvals in your vault. If you turn on approval emails in Settings (they are off by default), we email you a doorbell, not a letter: which agent, but no key name unless you enable "Name my keys in emails". Destinations and reasons stay out of emails. You see the details after signing in. If nobody answers before the agent gives up, we send one reminder.
For the technically curious: what an email can contain
- Approval emails carry the agent's name. Key names are omitted by default and included only if you enable "Name my keys in emails". Destinations and the agent's stated reason are never put in an email.
- For a "run without asking" secret, the broker tells our server only that a call went somewhere new, never where. We email you about it only if you turned alerts on for that secret; they are off by default.
What we know, and what we don't
We designed Wundervault so that the record of where your secrets go stays with you.
- We can't see
- Your secret values, your passphrase, your Account Key, or where a "run without asking" secret was sent. After your account locks, names, tags, shapes, services, part names and usage setups are sealed too. We no longer know which services you use. Web approval names, destinations and reasons are also hidden from us.
- We can see
- Your account information, including your email address and agent names. Before locking, we can also read key names and usage setups, including how credentials are attached, and destinations and reasons submitted for approval. Locking happens only after every computer on the account updates and no secret is still set up the version-1 way, on your next unlock. After locking, the server retains ids, which agent has which key, tier, a one-bit wallet-or-signer note, padded counts and sizes, timing, and broker and agent versions. Before locking, pending wallet payment, signature and recipe approval details, including payee, amount and what is signed or its digest, are readable by our server until you decide; after locking they arrive sealed by your broker and only your browser opens them. If you enable "Name my keys in emails", we also retain the key names you choose to put in emails.
- On your computer
- The broker keeps a full log of every use: where each secret went, why, and what happened. Read it with
sudo /opt/wundervault/current/node /opt/wundervault/current/app/bin/wundervault-agent --destinations(by full path, as the installer prints it, for the same reason), which opens a self-contained page and then deletes it.
Logs
Every use of a secret is written to your activity log. Each entry is linked to the one before it, so removing or editing one breaks the chain and shows up when you check.
For the technically curious: how the chain works
- Each entry carries an HMAC over its contents and the previous entry's code, keyed by a server-side audit key. Each account has its own chains, and a signed record of where each chain starts and ends.
- From 1.0 an entry also records the secret's name at the time, inside the signature, so the log can still name a secret you later deleted or renamed. At account locking, activity labels are sealed. The server verifies the existing chain, adds a checkpoint row marking the transition, and re-signs the earlier rows with HMACs covering sealed labels instead of plaintext names. Later rows use that format too.
- Agent-written text in the log is capped at 500 characters, stripped of control characters, and labelled as the agent's own words.
The log on your computer
The broker also writes a full log on your computer: one line for every use of a secret, with where it went, the reason your agent gave, and what happened. Each line is signed by the broker and linked to the one before. We keep a fingerprint of each line, which reveals nothing about it, so if the log on your computer is ever changed, even by someone with administrator rights, it stops matching our copy and we email you. It is kept for a year.
For the technically curious: how the two copies are checked
- Each line holds its content, a random 16-byte salt, the previous line's hash, its own hash, and an ECDSA P-256 signature by the broker's key over
"wv-activity-log-v1\n" + hash. The hash is SHA-256 over"wv-activity-chain-v1\n" + previous hash + "\n" + digest, where the digest is SHA-256 of the line's canonical JSON. - The broker sends us each line's digest, never the line. Because of the salt, a digest can't be confirmed by guessing what a line said. Our server computes the chain itself and accepts only digests that continue from where its copy ends; the starting point is set once and the broker can never move it.
- The broker compares its log with our copy within a minute of starting and daily. A rewritten line changes every hash after it, so it can't match our copy, even when re-signed with the broker's own key; lines cut off the end leave the log shorter than our copy. So is a line changed or removed inside the log, which the broker's own check finds. Each is reported as a security event and emailed, at most once a day for each computer.
- Only you can start a new record for a computer, from the vault page with your passkey, for example after restoring it from a backup.
Repair and recovery
If an agent may have been exposed, repairing it gives it a brand-new vault key and re-encrypts everything it holds. Then we show you which secrets it had already used, because those need replacing at the service that issued them. Re-encryption can't call back a secret that was already read.
For the technically curious: all or nothing
- A repair generates the new key in your browser and re-encrypts every entry in one all-or-nothing request, guarded so nothing prepared under the old key can land afterwards.
- A recovery code, created with your vault, restores access on a new device. If you lose access to the vault without a way to recover it, you lose names and setups as well as secret values. Our server cannot recover sealed metadata.
The connection
The connection between you and us uses TLS with a hybrid of classic and post-quantum key exchange (X25519MLKEM768). Your vault is also encrypted before it is sent, so even a recorded connection holds nothing readable.
Design choices, and why
- A broker on your computer
- Your secrets never sit on our server in usable form, and agents never hold them. Not chosen: A hosted proxy: we would see every destination and hold usable secrets.
- A separate operating-system account
- A boundary the operating system already enforces. Not chosen: File permissions on your own account: an agent running as you can read anything you can.
- Argon2id at 46 MiB, one pass
- Memory is what cracking hardware can't cheaply add, and it stays quick on phones. Not chosen: More passes with less memory: cheap for attackers, slow for phones.
- Two-part key derivation
- A server breach plus a guessed passphrase still opens nothing. Not chosen: A passphrase alone.
- AES-256-GCM
- Authenticated, standard, and fast in every browser. Not chosen: Modes that don't detect tampering.
- P-256 signatures from the broker
- Available everywhere the broker runs, including the browser. Not chosen: A secret shared with our server, which could then sign too.
- The agent names the destination
- The agent knows where it's going; you approve where it matters. Catalogue presets simplify known services; any other service is added by name and set up by hand. Not chosen: Requiring a pre-written integration for every service, which would limit coverage.
- Destinations kept on your computer
- Where your secrets go is your business. Not chosen: A hosted record of your network.
- A local-only connection on Windows
- Windows can't apply access rules to Node's named pipes; we tested it. Not chosen: Named pipes, which worked for administrators only.
What we don't protect against
The full list is on our limitations page. The most important ones:
- A "run without asking" secret goes where your agent asks. Use "ask me first" for secrets that matter.
- Your agents share your account on your computer, so they can use each other's broker access.
- Someone with administrator rights on your computer is inside the wall. Separately, the broker protects setup integrity against server downgrades: after opening a sealed setup on an account, it refuses plaintext setups, older setup revisions and setups inconsistent with the value. These checks do not protect against an administrator who controls the broker itself.
- Your browser runs the code we serve. A compromised server could serve bad code; the browser encryption is open source, so you can check what is sent.
- We have not had a third-party security audit.
Appendix: parameters
- Passphrase stretching
- Argon2id t=1, m=47,104 KiB, p=1 (PBKDF2-SHA256, 600,000 rounds, for older vaults until their next unlock)
- Key separation
- HKDF-SHA256 with a 16-byte Account Key
- Encryption
- AES-256-GCM, 12-byte random nonce
- Setup links
- PBKDF2-SHA256, 600,000 rounds; single use; 15 minutes
- Broker identity
- ECDSA P-256; requests valid for 120 seconds; one-time nonces
- Credential sealing
- Ephemeral ECDH P-256 → HKDF-SHA256 → AES-256-GCM
- Installer signature
- Ed25519
- Connection
- TLS 1.3, X25519MLKEM768
- Activity kept
- 30 days by default (60, 90 or 365 selectable); approvals, revocations and refusals 365 days