Skip to content

vaultfold threat model

This document states what vaultfold protects, against whom, and what it explicitly does not protect. It is written for someone evaluating the tool before trusting it with credentials. Decisions referenced as ADR nnnn are in docs/adr/.

The axiom

Everything in a vault directory (ciphertext, wrapped keys, public keys, policy events, file names, file sizes, file counts) and its entire history is assumed to be available to every adversary, permanently, including former members (ADR 0001). A vault may be committed to a public repository, copied into a deploy artifact, forked, or backed up. No protection below depends on any of that not happening.

Assets

  1. Secret values: passwords, API keys, tokens, private keys, notes, TOTP seeds, connection strings.
  2. Entry structure: the paths and field names of entries, which often reveal which services and environments an organisation uses.
  3. Device private keys: the keys that unwrap epoch KEKs.
  4. Epoch KEKs: group keys that decrypt every event in an epoch.
  5. Policy integrity: who is a member, which devices they have, and who may write.
  6. Availability of the current state: the ability of legitimate members to obtain the latest, complete vault.

Actors

Actor Has Wants
Outsider with ciphertext A copy of the vault directory and history Secret values, structure
Ex-member Full history plus every KEK they were ever wrapped for Current values written after revocation
Current member exceeding role A reader KEK and push access to the storage Unauthorised writes accepted by other clients
Compromised device A device private key and the local cache Everything that device could read; persistence
Compromised remote box A shell where a human forwards or pairs an agent session Values beyond what the human intended; replay
Malicious or careless AI agent session Tool access on a developer machine Secret values in its context, transcript or logs
Hostile web page Whatever a visited site can run in a page, including frames, forms and its own JavaScript A victim login, code or passkey signature, through the extension
Compromised browser extension or browser The extension's approved caller identity, or the page content the browser sees Every login, code and signature the browser session may request
Relay operator The relay's traffic and push credentials Values, entry names, or the ability to forge approvals
Storage or forge operator The bytes at rest and the ability to rewrite history Values, or to roll members back to an old state

What is protected, and how

Confidentiality of values against outsiders

Values are encrypted with XChaCha20-Poly1305 under per-event keys derived from an epoch KEK, which is wrapped only to authorised device keys with X25519 or P-256 (ADR 0002, 0003). Without a device private key, the vault is opaque. Ciphertext is padded to size buckets so value lengths are not recoverable from file sizes. The suite identifier on every wrap and event allows migration to a hybrid post-quantum recipient type without a format break, which is the mitigation for adversaries who store ciphertext today to decrypt later.

Confidentiality of structure

Entry paths, field names, entry types and metadata are inside the ciphertext. File names are content hashes. An outsider learns how many events exist and when they were written, not what they name.

Integrity and attribution of writes

Every event and policy event is signed by its author's device key. Policy records form one linear chain, each checked once against the state after the link before it (ADR 0046). Clients fold only data events whose author held the required role at the chain link the event anchors on, subject to the causal-past rule below. Unauthorised writes are excluded and reported with the author identified (ADR 0006). Values cannot be modified undetectably by anyone, including members.

Confidentiality after revocation, for future writes

Revoking a member or a compromised device creates a new epoch whose KEK is wrapped only to remaining devices (ADR 0007). Nothing written after the revocation is readable by the revoked party.

Custody of private keys

Private keys are generated on the device, in hardware where available, and never leave it (ADR 0008, 0009). Linking a new device creates a new key for that device rather than copying an existing one. Every device can be revoked individually. The agent daemon is the only long-lived process that holds unlocked key material; the CLI, TUI and GUI request narrow operations from it (ADR 0011, 0028). When no daemon can be used, the CLI unlocks an identity in-process for one command and zeroes it before exiting (ADR 0020, now only that fallback). Identities are protected by a passphrase or by the OS keychain tier: a Secure Enclave key on macOS (ADR 0031), Windows Hello or, where Hello is not set up, DPAPI on Windows (ADR 0032), and the Secret Service on Linux (ADR 0033). Unattended processes use scoped machine identities (a later change for the CLI).

Remote unlock

The daemon exposes a small, enumerated request API: principally unwrap the KEK of one collection and epoch, or resolve one reference, for a stated session; no request returns private key material. Requests carry the host, session and scope, so approval prompts are meaningful; approvals are scoped and time-limited. The relay sees only Noise-encrypted bytes between two device keys. Pairing uses a short code displayed on both ends that the human must confirm, and links carry only a request id. The daemon's remote transports (SSH forwarding as a recognised source, relay pairing) are a later change (Tailscale is after 1.0, docs/ROADMAP.md "Later"): today it listens only on the local endpoint, answers pair as unsupported, and treats a forwarded connection like any other unknown local caller.

AI agent sessions

Values are encrypted at rest, so an agent reading the vault directory obtains ciphertext. The single path to plaintext is the daemon, which denies read, get, export, totp and clipboard copy to sessions classified as agent sessions and permits only set, link, run, inject to a subprocess or file, and the metadata verbs (ADR 0012). In the daemon this is a purpose check: a request whose purpose is display is refused for an agent session unless a human allowed that one reference for at most an hour (agent-mode allow-read), and every other key or value an agent session asks for needs a scope a human approved (ADR 0029). Harness hooks that deny the read verbs in shell commands, the redact command that masks known values in tool output, and the MCP server (which has no tool that returns a value) are a later change; the daemon already serves redact, masking only values the agent's own session was served.

Availability

Every clone is a full backup of the vault and its history, and members work offline from their local cache, syncing when a backend is reachable. The threats are a force-push that rewrites or truncates history and, once a later change brings it back (docs/ROADMAP.md "Later"), compaction mistakes, which delete old event files. 1.0 has no compaction command, so no client deletes event files; a compaction would be admin-only and opt-in and would never delete policy files; the git backend never force-pushes; clients detect truncation through local-first anti-rollback and the git history check (below); and branch protection on the forge prevents a force-push from landing. Anyone who can write to the transport can delay privilege writes, and a member with write access to a shared folder can deny availability by deleting or planting files; a wrap file left by a lost or planted mint no longer blocks the next epoch of a collection (see "Ordering trust and equivocation").

Leakage into build artifacts

init writes ignore rules for common build contexts; every vault-touching command re-checks that the vault is not inside a build context without an ignore rule and that .gitattributes still marks it binary. run and inject refuse when the check fails; other commands warn.

The vault branch of an in-repo vault

An in-repo vault lives on an orphan branch (ADR 0041) that vaultfold reads and writes with git plumbing. Two properties matter here. First, repository hooks are disabled for every vault-branch git invocation (an empty hooks directory and push --no-verify), so a hook configured in the repository or by core.hooksPath neither runs on vault commits nor can refuse, rewrite or observe them. This is deliberate: the branch holds only ciphertext and signed records, and the repository's code hooks have nothing to check there. The cost is that a hook the team relies on as a control never covers vault writes. Same-branch and standalone vaults still run hooks. Second, branch-mode sync never checks a branch out, so a hostile vault branch cannot execute anything through the user's work tree, and it refuses a fetched branch whose root holds anything beyond vault.toml, the vault directory and the hygiene files.

Rules on the forge (a ruleset that restricts who may create, update or delete the branch and blocks force pushes, and the CI verify action on pushes to it) are an extra layer and never the authority. Integrity and attribution still come from the signatures and the policy chain (ADR 0006, ADR 0046), which every client replays. A forge rule keeps non-members from landing files and anyone from rewriting the branch; if it is missing or misconfigured, clients still reject unauthorised events, and rollback detection still catches a truncated or rewritten branch. A pull request requirement is not wanted: it delays writes and adds no integrity.

What is explicitly not protected

These are consequences of the design, stated so that nobody discovers them during an incident.

  1. No forward secrecy. An ex-member or a compromised device can decrypt every event of every epoch it was ever wrapped for, forever, from any copy of the history. Re-encrypting existing data does not change this. The only mitigation is rotating the underlying credentials; vaultfold tracks this with a rotation checklist but cannot perform the rotation itself.
  2. A member who has read a secret has it. The format cannot recall a value from a human's memory, clipboard or notes.
  3. Read auditing and write prevention are not available on self-hosted backends (git and filesystem; S3 and WebDAV are after 1.0). There, nothing can observe who fetched what, and write "prevention" is detection and exclusion by correct clients, plus optional CI verification with branch protection on the default branch. Both are provided by the hosted service, which verifies every event's signature against the policy chain before accepting a write and keeps a read audit log per device key (ADR 0010). No backend can prevent a member who holds a KEK from decrypting.
  4. A reader can decrypt everything in the collections they are granted. Roles govern whose writes are accepted, not who can decrypt. Read scoping exists only at collection granularity through separate KEK lineages.
  5. Plaintext exposure at the point of use. run places values in a child process's environment, which is visible to that process, its children, and on some systems to other processes of the same user via /proc or process inspection. inject to a file writes plaintext to disk if the user asks for a file. Output masking is best-effort: short values below the threshold and binary streams are not masked.
  6. Metadata leakage from the vault directory. Hidden: member display names and email addresses, device labels, collection names and entry paths, all encrypted under a collection KEK. Signer key ids are per-vault pseudonymous, so an id cannot be correlated across vaults or to a member's public SSH key. Still visible to anyone with the directory: the number of events and policy events (and so roughly how many entries exist), when changes were made (coarsened, since clients batch one user action into one commit and may jitter automatic syncs), which per-vault key id signed each event and therefore how active each device is, the number of members, devices and epochs, the device public keys, the random collection id and epoch of each event, and padded ciphertext sizes. Cover traffic and dummy events are out of scope for version 1.
  7. Availability is only as good as the backend. Nothing in the format prevents a storage operator from deleting the vault. Members' local caches and clones are the recovery path.
  8. Compromise of the device that runs the daemon yields everything that device's keys can unwrap for the session TTL, and the local encrypted cache. Hardware-resident keys (after 1.0, docs/ROADMAP.md "Later") would limit this to the session; they cannot prevent it. The daemon controls that narrow it are listed under Compromised device below.
  9. Harness classification is best-effort. An agent invoked in a way the daemon cannot recognise, on a machine where agent-mode was not enabled, is treated as the human. The MCP server path is classified correctly: the vaultfold MCP server among a process's ancestors is an explicit agent signal on its own, even when the command's environment was scrubbed (env -i). A command run through it that detaches from its ancestry before contacting the daemon (a new session plus a double fork, so it is reparented to init) escapes this; the MCP server remains the recommended integration once it ships. redact in an agent session masks only values that session was served, so it is not an oracle for others. Two agents that export no harness session id and run in the same terminal cannot be told apart: they share one agent session and its approvals. Every descendant of a harness process is that harness to the daemon: a command it runs, or anything that command starts, joins the harness's agent session and its approvals ("Borrowing a harness session id" below). Detection needs two independent signals or one explicit signal (ADR 0030); one signal alone only warns. See also "Same-user limits of the agent daemon".
  10. A weak passphrase on a stolen device. If a device is stolen and its passphrase is weak, an attacker can guess it offline; the passphrase stretching slows this down but cannot make a weak passphrase strong.

Specific attacks and mitigations

Rollback and history truncation

A storage operator or a member with force-push rights removes recent events or policy records so that other members fold an older state (for example, one in which a revoked device is still authorised, or a rotated credential still has its old value). Mitigation: every client records locally, outside the repository, the data heads it last folded and a pin of the policy chain (the last link it accepted and a hash of every link from Genesis to it). If a fetched history lacks those heads, or the pinned slot no longer holds the pinned link, the client refuses to proceed and reports a possible rollback (policy-rollback) or a fork (policy-fork), naming the slots, records and authors, keeps serving reads from its local copy, and refuses sync and every write, data or policy, until a human accepts a checked tip with vaultfold sync --accept-rollback <fingerprint> (ADR 0006, ADR 0046). A wrong fingerprint changes nothing: it is compared with the tip that would be accepted, after any fetch and before any accept, audit line, cache save or push, on every backend. This detects rollback for any member who has seen the newer state.

A git vault adds a check that does not depend on having seen anything: every fetch checks that each policy slot ever added in the branch's history still holds its first version at the fetched tip, so an ordinary commit that deletes or replaces slot files is refused by every client, a fresh clone included (see "Ordering trust and equivocation"). What neither check catches is a force-push that rewrites history for a client that never saw the old history, which is why branch protection against force-pushes is part of the setup, and why the hosted service is recommended for teams that need stronger guarantees. The CI verification action that would fail such a push at the forge is after 1.0 (docs/ROADMAP.md "Later").

Backdating by a revoked writer

Authors choose their own parents, so a revoked writer can craft an event that claims to predate their revocation.

Policy records cannot be backdated. Policy is one linear chain (ADR 0046). Every record names the current tip as its single parent and is written at the next write-once slot, and every client replays the slots in order, checking each record once against the state after the tip it names. A record that names anything but the tip is void (stale-parent), and a record written on the tip after a revocation or role removal is judged against that state and is void for authority (revoked-author, unauthorized). No slot below the first empty slot is ever empty, so a late record can only extend the chain, never land before something that already landed. A revoked device, or a demoted admin, therefore cannot grant itself or others power, add members or devices, rename others, mint epochs or revoke anyone with backdated records, and a forged revocation that is void never locks its victim out of anything. Void records are reported by vaultfold doctor (rejected-policy), naming the author when the signature verifies. Revocations, role removals and demotions are final once the command that wrote them reports success; another root admin can grant a removed role back (see "Ordering trust and equivocation").

Data events keep the causal-past rule: an event by key K is valid only if it lies in the causal past of K's revocation, that is, it is equal to or an ancestor of an event id listed in the revocation's event_heads for its collection, and an event gets authority only from grants in the chain up to the link it anchors on. Events by K concurrent with or after the revocation are rejected regardless of their claimed timestamps (ADR 0006). The cost is that a legitimate write racing a revocation is also dropped; clients list such events so an admin can review and re-apply them. The revoked writer cannot in any case produce an event readable under the new epoch.

Role reductions are integrity, not prevention. A demoted admin's KEKs for the epochs it already holds keep working for it: it cannot rewrite policy, and the data fold rejects what it writes afterwards, but it can still decrypt every epoch it was wrapped for. Only revocation with new epochs cuts off reads, so member ungrant warns when it leaves a member with no role and points at member revoke. Changing roles and renaming a member are human decisions: member grant, member ungrant and member rename are refused in an AI agent session before the vault is opened, so an agent harness cannot escalate privileges. (member add and member revoke are not covered by that refusal yet.)

Ordering trust and equivocation

Under the linear chain the storage transport (the git remote and branch, the hosted service, or the shared folder) decides one thing: which of two privilege writes made at the same moment takes a slot. Both were checked against the tip their authors saw, and nobody wins by backdating, because a record must name the tip. The loser's client pulls, re-checks and either writes again on the new tip, reports that the change is already in effect, or asks again when the outcome changed. The transport is not trusted for authenticity (every link is signed and names its parent, so it cannot forge, alter, reorder or move one) and is trusted only in part for freshness (it can withhold new links or serve an old or rewritten chain, which the pin catches for every client that saw the newer state). Privilege commands therefore need the backend: offline they exit 4 and write nothing.

What remains, and what limits it:

  • Equivocation. A malicious remote, anyone who can force-push, or a member with write access to a shared folder can show a newcomer, or a member who has not synced for a while, a chain that forks before anything that member has seen. Every member who synced past the fork refuses it and names the authors; to keep two groups apart the transport must also partition their data events, or anchors cross over and doctor reports policy-fork-evidence. Version 1 narrows the rest: member add prints the chain fingerprint of the new member's link, which the admin gives the newcomer out of band, and vault add --expect-head <fingerprint> refuses a chain that does not hold it (the join pin; it closes equivocation before the newcomer's own link, not after); key verify prints the fingerprint of this copy's tip, so two members on a call can see they agree. Transparency logs and witness co-signing are deferred.
  • Git history. On git every fetch, including vault add and a first clone, fetches full history and checks every policy slot ever added in it: a missing slot is policy-rollback, other bytes are policy-fork, naming the commit and its git author. A competing version of a slot on a merged side branch is a fork whenever it decodes as a policy record of this vault for that slot, whoever signed it; the signer is judged against the fetched tip's chain, never the local copy, and named as unverified when that chain does not register it. A history that cannot be deepened is refused as history-unchecked. So a member with push access can raise a fork alarm by merging a side branch that once held a signed competing version of a slot: the alarm names the member, is per client and recoverable, and each client clears it once with vaultfold sync --accept-rollback <fingerprint> after checking the tip with the other members (a newcomer passes --expect-head). A force-push is caught only by clients that saw the old history; branch protection blocks it.
  • Shared folders. A shared folder has no compare-and-swap across machines. Two admins can write the same slot offline; the sync tool keeps one and renames the other as a conflict copy, the losing author's client reports policy-write-lost (and offers to re-apply what can be re-applied: not a mint, and not a revocation that mints), and doctor reports the conflict copy with its author. Any member with write access to the folder is in effect a transport operator: it can delete or replace slot files and so rewrite history unseen by members who have not synced. A third party that pinned a record which then lost such a race fails closed and needs a human-checked --accept-rollback.
  • Root admins are peers. Version 1 has no quorum (Ben, 2026-10-31). Any root admin can remove another root admin's admin role or revoke its devices, directly, and another root admin can grant the role back. Two root admins in conflict can undo each other; the chain records every step with its author, and the recovery key and member revocation are the remedies. A single root admin can add a new root admin and remove every other one; last admin protection only keeps one admin in place.
  • Revoking includes the transport. Anyone who can write to the transport can delay privilege writes: each junk slot file costs a writer one slot, and a stream of them can hold a command in its retry step until its two-minute budget runs out and it exits 4 with policy-busy (only a race lost to a new link counts toward the limit of three, so junk cannot reach that limit). Junk never wedges the vault and is reported, and the hosted service refuses it at admission. In a git vault, removing a member's or device's push access at the forge is part of revoking it, and in a shared folder so is removing its write access to the folder; otherwise a revoked party keeps that delaying power.
  • The recovery key. Only the recovery key itself, reconstructed from its shares, can revoke, supersede or remove a role of the recovery key or member, or add a device to the recovery member; no admin, and no number of admins, can. So leaked shares can only be rotated by the share holders, and lost shares cannot be replaced by admins. An admin can register a recovery key in a vault that has none, which the admins then cannot remove: register one early. With a recovery key registered, only the recovery key can remove the only root admin, by any route (recovery-required). The CLI has no command yet to register or rotate a recovery key (init and doctor urge registering one early; a follow-up change adds the command).
  • Record kinds. A kind beyond format version 1 counts only once the recovery key enables it, so no admin can freeze privilege writes with a kind nobody implements. But the recovery key can enable a kind nobody implements, and then anyone able to write that kind can freeze privilege writes until the recovery key lifts the freeze (a recovery-signed link above the held record voids it). An enabled kind cannot be disabled, so once one is enabled any member able to write it can freeze privilege writes again, and each lift costs a recovery ceremony. A disable-kind record is ticketed for later (R2-D).
  • Self-only epochs. Any admin, or a rotator of a collection, can mint an epoch wrapped only for itself. That is an availability problem, not a confidentiality one: the others cannot read data written under it until another admin or the recovery key mints a new epoch for everyone.
  • Lost records in a shared folder. A record of this device that loses its slot to another admin's record is reported as policy-write-lost by the command that finds it, by sync and by doctor; so is any later record of this device that the loss voided. A lost revocation did not happen: the report says the device or member is still active and names the revocation command to run again, and a new epoch does not settle it. It is reported on every sync and doctor run until the end of the target key's supersession chain is revoked or gone (a key the revoked party rotated in the meantime is not settlement: the report names the successor key, by short id, as the device to revoke). A revocation that mints, and a lost epoch new, are never re-applied by sync (the latter is listed with vaultfold epoch new <collection>); a lost grant, role removal or revocation that mints nothing is offered for re-apply on a terminal, after a re-check against the current tip, and a lost record of another kind (a rename, for example) is listed with a note to run its command again. A folder writer can also delete or displace a record this device pinned outright (its own revocation, say), which is policy-rollback or policy-fork, never policy-write-lost: the refusal, the read-only warning and doctor name each record of this device the chain now lacks by its command and target ("device revoke" and the device), from the local cache, which keeps the command and target of every own link the pin has covered; sync --accept-rollback <fingerprint> then records each as policy-write-lost, so a revocation undone this way is reported until the device is revoked again (OpenSpec change chain-rollback-names-own-records).
  • Wrap files and lost writes in a shared folder. A member with write access to a shared folder, or push access to a git remote, is in effect a transport operator. Wrap files were once addressed by collection and epoch number only and written once, so such a member could block every later mint of a collection, and every revocation that mints (a device revoked as compromised, any member revocation), with "existing file differs" by leaving a wrap at the next epoch's path, including by the ordinary accident of losing a mint race; a lost or planted wrap for one recipient blocked a later grant or add-member giving it the epoch. Now every wrap lives under the id of the link that calls for it (epochs/<collection>/<epoch>/<link>/<keyid>.wrap, ADR 0052), which nobody can predict before that record is signed. So no wrap left by a lost write, and no wrap planted in advance, can be in the way of a privilege write: after a lost mint or a lost grant, epoch new, device revoke --grade compromised, member revoke and member grant succeed, for the losing admin and for everyone else. Lost writes cost stray files, which nothing reads as a recipient's wrap and which doctor reports as stray-wrap (a warning; it does not change the exit status). When the record that lost its slot is still present and verifies, the finding names that record and its author ("the directory is that of a lost record written by ..."). It names the author of the lost record, never the writer of the file: anyone with folder write access can put a file under that directory, and the wrapper a wrap file names is not trusted for attribution. A lost race cannot leave wraps in a git or hosted vault, since a losing record's wraps are never published there, and the hosted service stores a wrap only under the directory of the stored link that calls for it, put by that link's author. This is a claim about wrap files only. What remains:
    1. Once a link's first file reaches a shared folder, its directory name is known, and a planter can race the honest wraps for the other recipients of the same link. The sync tool keeps one file; a client uses only a wrap whose KEK matches the mint's kek_commit, trying conflict copies too, and reports the other as wrap-mismatch. On the hosted service the putter rule refuses the planter outright.
    2. Stray wraps accumulate in a shared folder: one directory per lost record that called for wraps, never deleted outside compaction, and reported at every doctor run. That costs disk, not availability of the vault. Letting sync offer to remove a client's own stray wraps once the data written under its lost mint has been re-applied is future work.
    3. Nothing here changes equivocation, forks or the detection of lost writes described above.
    4. A member with folder write access can still deny availability by other means. For example, a file that is not a directory, planted at epochs/<collection>/<next epoch>, makes every mint of that collection fail with a "not a directory" error until the file is removed. This is the same class as deleting files (see "Availability"): doctor reports the file as corrupt-file, and the hosted service refuses such names. The layout is not changed to route around it.
    5. The filesystem backend writes a mint's wraps before its record, so a record is never readable while a wrap it calls for is missing, and a wrap write that fails aborts the mint with no record published (ADR 0052 "Consequences"; OpenSpec change fsstore-wraps-before-record, ticket 01M7FYRJT2KQC73Z8Z003NB5PM). A process that ends between the two steps leaves wraps under a directory no record names, which doctor reports as orphan-wrap and then stray-wrap; they block nothing.

Display names are labels

A member's display name is sealed under the root collection key. The policy fold cannot read it, so it cannot compare names, and the hosted service cannot either. A name identifies nobody: any member, a plain reader included, can rename itself (member rename, ADR 0042), and a root admin can rename anyone except the recovery member. Uniqueness among unrevoked members and the reserved name recovery are checked by the authoring client against the names it can decrypt. They stop an honest client from creating an exact duplicate, and not:

  • a near-duplicate ("Ben" and "Ben."), or a name that is merely confusing;
  • a crafted record from a malicious client, which the fold accepts because it cannot read the name;
  • two concurrent renames or adds that merge into one name. member list marks both duplicate name, doctor reports duplicate-member-name, and member grant, member ungrant and member rename refuse the name as ambiguous until they are given a member id prefix. member revoke takes a name only and refuses a shared one, so one of the two members has to be renamed before either can be revoked by that name.

A machine identity never renames itself, even when it holds the root admin role, so a compromised CI identity cannot choose a human-looking name; a root admin of another member renames it. A reader that cannot open a member's current name shows the member id and never falls back to an earlier name.

Mitigations: member list shows the renamer and time of the current name (renamed: by "<member>" at <time>), the policy history records every rename with its author, and a root admin can rename an inappropriate name again. Fingerprint verification, key verify, is the identity check; never decide who someone is from a display name.

What a rename discloses to a party without a root KEK (the hosted service, a storage operator, a revoked device): that a member was renamed, who signed it and when, but not the name. Policy records are visible structure, as they always were. A demoted admin cannot rename another member, since a rename by it after the removal is judged at the chain tip and a backdated one is void, but it can still rename itself, which needs no admin right.

Residual risks:

  • A rename sealed under an older held root epoch. RenameMember seals under the newest root KEK the device holds. member rename is a privilege write, so it pulls first and needs the backend; the case that remains is a newer root epoch whose wrap for this device has not arrived even after the pull (for example in a shared folder whose sync tool has delivered the record but not yet the wrap). The name is then sealed under the older epoch, and a device revoked at the newer epoch can still read it. member rename warns in that case, naming vaultfold sync, and does not refuse, because a name is a label and refusing would stop the rename until the newer epoch's wrap has reached the device (ticket 01M5VZDD2N).
  • Unbounded name size. No policy record bounds enc_name today, so any member can write a valid rename of arbitrary size that every client and the hosted service keep forever. A cap is a pre-release decision (ticket 01M5VREMP4), and it has to land before the first release.
  • Records of a kind this build does not implement. RenameMember (kind 15) is a kind of format version 1, so every build that reads the linear chain understands it. A kind beyond version 1 counts only once the recovery key has enabled it (ADR 0046); a record of a kind no link enabled is void for every client. A build that meets an enabled kind it does not implement holds that record and everything above it, warns (unknown-policy-kind, an error in doctor) naming the author keyid the record claims, and refuses privilege writes (upgrade-required) until upgraded, while still serving reads and data writes. Until the user upgrades, this client may still treat a member revoked above the held record as active. The warning is a visible divergence, not a lock: refusing to open the vault would let anyone with write access to the storage deny service with one file.

Forged or replayed approvals

An attacker who knows a member's public key attempts to trigger approval prompts on their devices hoping one is accepted. Mitigation: a request is only visible on the requester's screen, whichever device claims it must show the same short code and the requesting host, session and scope, and the human confirms the code before approving. Requests carry nonces and counters, approvals are bound to the request and scoped, and pairing tokens are per session and never stored in shared locations. Claiming another person's request exposes the claimant's own access to that box, not anyone else's.

URL scheme hijacking

Any application can register the vaultfold:// scheme. Mitigation: links carry only a request id; possession of the id allows a device to look at the request, and approval still requires the human to confirm the matching code on a device that holds a valid key.

Compromised remote box

A box where a human has paired a session can request anything the human would approve, for the session's lifetime. Mitigation: approvals are scoped to a collection or path prefix and to a TTL, every request is shown to the human, and long-running or unattended workloads on such boxes use machine identities rather than a forwarded human session. This risk is inherent to remote unlock and is documented as such.

Compromised device

Malware on the machine that runs the daemon, as the same user, can ask the daemon for values. Mitigations in the daemon: caller verification identifies every local connecting process by pid, executable path and code signature or process token, checks it against a per-caller allowlist, and prompts on first contact from an unknown executable; a per-collection touch policy requires a fresh user-presence check per request (Touch ID or the login password through the macOS helper app, Windows Hello, otherwise a confirmation dialog), on by default for a collection named prod (the vault format has no per-collection flag yet); the daemon locks on screen lock, sleep, system idle (15 minutes, counted from the later of the last input event and the most recent unlock, so that an unlock over SSH is not locked at once; requests from agents do not reset it), 60 minutes without a request and an 8 hour TTL, and when a lock trigger stops working; approvals last once or for the session (8 hours); every request is written to the local audit log; and resolve, unwrap-kek and browser requests are rate-limited per session and per caller (60 a minute, burst 20). These limit the window and blast radius of a same-user compromise; the limits that remain are listed under "Same-user limits of the agent daemon" below. Root-level malware, or a keylogger with screen capture, is out of scope for any password manager, including this one.

Caller verification identity, per OS

The daemon's identity check for a locally connecting process (internal/daemon/callerid) has to resist a same-user attacker who can create, rename and delete files at will, including ones that pass their own, genuinely valid code signature. Rounds of review on the add-agent-daemon change found, and closed, three shapes of that attack; this records the rules that came out of it and where they still fall short, since a caller-identity check is exactly the kind of code where an unstated assumption becomes a real bypass.

  • darwin. Identity is the kernel's own CodeDirectory hash (cdhash) of the process that is actually running, read with csops_audittoken(CS_OPS_CDHASH) against the connection's audit token. This is never a hash of a file read back from a path: an earlier design read the executable's bytes through the connecting process's own handle, which sounds bound to the right process, but the code signature check next to it (codesign --verify, or the cgo build's own path-based fallback at the time) reopened the path independently, and a same-user attacker who keeps renaming a different, validly-signed file over that path and the original back won that race in roughly one attempt in ten across 300 tries, both with and without cgo. Reading the kernel's cached cdhash against the audit token closes this completely, because it never touches the filesystem at all: nothing a same-user attacker can do to files changes what the kernel already loaded and validated when the process exec'd. A signing identity (a "signer" key, eligible for the project's own default trust or an entry keyed by certificate rather than by hash) is granted only when the code chains to a generic Apple anchor (anchor apple generic, plus the leaf certificate's own subject OU as the team id) via the Security framework's dynamic validation against the live audit token; a self-signed or ad hoc signature never yields one, however plausible an identifier or team id it asserts about itself. This check needs cgo (the Security framework has no equivalent syscall-level interface); a CGO_ENABLED=0 darwin build never grants signer trust at all and reports every caller's identity as the cdhash alone, whether the running image is unsigned, ad hoc, still validly Apple-signed, or a file whose on-disk signature has since been broken without affecting the already-running process. A CGO_ENABLED=0 build still tells an unsigned or ad hoc image apart from a genuinely signed one, from the live process's own CS_OPS_STATUS flags (CS_VALID, CS_ADHOC, CS_LINKER_SIGNED), which are as kernel-cached and race-free as the cdhash read itself; it just never trusts a signer either way. Residual limits, accepted rather than fixed: an image with no CodeDirectory at all (unsigned Intel/amd64 builds under Rosetta commonly have none) gets TrustUnknown unconditionally, with a reason recorded, never default trust from a hash coincidence; a CGO_ENABLED=0 build cannot tell "signed and fine" apart from "signed but tampered with on disk since the process started" the way the (now-removed) path-based check once could, because CS_VALID reflects the signature validated when the process's code pages were last paged in, not the file's current bytes, and the kernel has no reason to re-fault and thus re-validate an already-resident page just because the file underneath it changed (confirmed live: corrupting a running, genuinely Apple-signed process's on-disk signature left its CS_VALID bit set); reopening the path to force that recheck is exactly what is being guarded against, so this is accepted rather than worked around; and a fully worked, live regression test for a forged self-signed certificate could not be built in this project's sandbox (macOS's ad hoc code-signing keychain search list could not be changed under it), so that specific attack is closed by the Apple-anchor rule's structure, and exercised by adjacent tests against a genuine Apple-anchored binary pinned by a non-Apple-vouched-for field, rather than reproduced end to end by an automated test.
  • windows. Identity is bound to the file the process is actually running by opening it with FILE_SHARE_READ only (so nothing else can rewrite, rename or delete it while the daemon holds it open) and then re-querying the process's image name on the same process handle, refusing the connection if it no longer matches the path just opened. This closes both the rewrite-in-place and the rename-away shapes of the same swap attack. A stronger, second binding by the open file's volume serial and file id against the process's own record of its image (ProcessImageFileMapping) was considered but not implemented, for lack of a verified struct layout to build it against; it remains an option for a future round.
  • linux. /proc/<pid>/exe always opens the running image itself, not a path that can be swapped out from under it, so no equivalent check is needed; there is no code signature to check either. Residual limit, accepted: Linux peer credentials carry no pid version, so a process that connects as one executable and then execs another keeps the connection; on darwin the audit token makes the kernel refuse that case.

Default trust goes to the project's signing identity or to the daemon's own executable; every other caller is refused until a human approves it on first contact, and approved callers are kept in an allowlist sealed under a key derived from the machine key. No project signing identity is pinned yet (it waits for the Developer ID and Authenticode certificates), so today only the daemon's own binary is trusted without that approval.

Purpose trust

A request for a key or a value names its purpose (display, metadata, inject or write), and the agent-session policy is enforced on that purpose. The daemon cannot see what the client does with what it receives, so purpose is trusted only as far as the caller is: in an agent session the daemon's own binary or the project signer receives collection keys for metadata, inject and write under an approved scope, and is trusted not to print what it decrypts; any other caller, even one a human allowlisted, receives only resolve with purpose inject and never a collection key. An attacker who can run the vaultfold binary in an agent session gains nothing from this, since the binary honours purposes; one who can replace or patch the binary is a same-user compromise of the binary itself, which caller verification detects as a changed identity.

Same-user limits of the agent daemon

These are known gaps against a process running as the same user, recorded while the daemon was built (add-agent-daemon design.md) and accepted for now. None lets a process with only ciphertext read a value; each widens what same-user malware, or a hostile agent, can do beyond what a cooperative agent would.

  • Session classification is partly self-reported. The terminal key the CLI reports (the controlling terminal's device and session leader) is the client's word: a process that calls setsid, opens a new pty or speaks the protocol directly escapes explicit agent mode (agent-mode on), which therefore guards against a cooperative agent the detector misses, not a hostile one. On Windows the terminal key is the console window handle with no session component, so a reused handle could inherit another terminal's explicit agent mode. An ancestor's argv[0] is used as an agent signal although a process controls it, because a match can only make a session more restricted; a harness that rewrites its argv[0] to something unlisted is detected by its environment marker alone, which only warns unless agent_detection = "strict". Claude Code's tool processes have no controlling terminal, so explicit agent mode cannot cover them (they are classified by CLAUDECODE plus ancestry).
  • Borrowing a harness session id. An agent session under Claude Code or Goose is keyed by the harness's session variable (CLAUDE_CODE_SESSION_ID, AGENT_SESSION_ID), so that an approval reaches the agent's retry from a new process group. The id is not a secret, so the daemon does not take it from the client: it reads the variable from the peer's environment itself and binds it to the harness process it observes among the peer's ancestors (the process named by CLAUDE_PID, else the nearest ancestor matching the harness's ancestry row), keying the session by harness, id, and that process's id and start time. A process outside that harness's process tree that copies the id, or a client reporting an id its environment does not carry, gets no harness key and a session of its own, and its audit record says harness_session_unverified without the id. What this does not stop: any descendant of the harness process is the harness, so a command the agent runs (or anything it starts) shares the agent's session and approvals, the same limit as the terminal key. On Windows, where the daemon cannot read another process's environment, the client's reported id is used, still bound to the observed harness ancestor, and any same-user process can make itself a descendant of the harness: it opens the Claude Code process with PROCESS_CREATE_PROCESS, starts vaultfold with PROC_THREAD_ATTRIBUTE_PARENT_PROCESS naming it, and reports the id it read from the audit log's actor field, which the same user can read. That open joins the harness's session and its approvals. This is the same access as injecting code into the harness, which any same-user process on Windows already has, so it is recorded here rather than closed. On Linux the start time has clock-tick resolution (10 ms), so a reused harness pid within the same tick, under a process that also carries the same id, would match.
  • Signing is scoped to the vault, not the collection. An agent session's own data event is signed whatever its collection; the collection is gated where its key is, since the event's ciphertext needs the collection key, which an agent gets only under an approved write scope, and fold rejects an event that does not decrypt. Events an agent has signed name its session id. An agent session never gets a bare hash, a policy event or a hosted service's challenge signed.
  • Approval dialogs can be driven by the same user. On Windows any process of the user can click a message box (post IDOK to it) with no permission; prefer Windows Hello for touch confirmation and, once it exists, the desktop app for approvals. On Linux under X11 any client of the display can inject input into a zenity or kdialog dialog, and the user's own ~/.config (GTK and Qt themes) can restyle it; within one line, right-to-left text can still be reordered for display (control and format characters are replaced, so a field cannot forge a line). On macOS the helper app's dialog is driven by another process only with the accessibility permission. vaultfold agent approve needs a human session whose controlling terminal the daemon observed itself.
  • OS credential stores. On Linux any same-user process that owns org.freedesktop.secrets on the session bus is the Secret Service and receives the wrapping keys stored there; the uid check before falling back to the plain algorithm is hygiene on a session bus, not a boundary. The Diffie-Hellman values of a Secret Service session live in math/big and godbus buffers that cannot be zeroed. On Windows, resetting the Windows Hello PIN deletes the Passport container and with it every Hello identity on the device, unrecoverably there: rotate first, or keep another member device. A DPAPI identity (Windows without Hello) has no user gesture at all. A Windows Hello identity's wrapping key is encrypted with RSAES-PKCS1-v1_5, the only padding the Passport provider decrypts (ADR 0032, amendment); its padding oracle is moot here, because every decryption needs its own Hello gesture on this machine and one approved gesture already decrypts the real ciphertext. Secret Service items and Windows Hello keys can be left behind, unusable, after a rotation or a failed creation (they protect nothing; a failed Hello creation that cannot delete its key names it in the error). A macOS Secure Enclave key depends on an undocumented attribute (ADR 0031) and fails closed if it changes.
  • Rate limits are shared. Agent sessions run by one binary share one caller bucket and one backoff, so one agent can hold another back.
  • A browser extension is the id the browser passes. Native messaging gives the daemon no way to tell a store build from an unpacked copy that declares the same id, so a same-user process that enables the browser's developer mode or unsigned add-ons and installs a copy with the published id is served as the published extension once the human approved that id in that browser; the typed confirmation for unpublished ids, the refusal of browsers started with developer flags (--load-extension, --disable-extensions-except) and the separate identities of the pre-release Firefox channels narrow this but do not close it (add-browser-extension design.md "Group 2 decisions" 19).
  • The Linux host rule sees the daemon's view of the image. On Linux a host passes as a vaultfold host when the running image behind /proc/<pid>/exe is a regular, non-writable file owned by the user or root in the daemon's own directory, as readlink /proc/self/fd/<n> reports it. A same-user process in its own mount namespace (unprivileged user namespaces) can bind-mount another file over that path, and readlink then reports the daemon-directory path for an image that is not the installed host; the fstat facts and the hash are the impostor's, so it is keyed by its own hash and the human is prompted as for a changed host binary ("The vaultfold host binary changed"), the prompt users also see after an upgrade. The same window exists for pid reuse between the hash and the image check. Comparing the image's device and inode with a stat of the sibling path in the daemon's namespace, or re-checking the process start time, would close both; until then this is an accepted same-user residual (add-browser-extension design.md "Group 2 decisions" 18). Browser channels are told apart by install path alone on every OS (the signature carries no channel), so a same-user process that renames a Firefox Developer Edition bundle or installs it into the release directory is served as release Firefox, which gives it nothing beyond the developer-mode residual above.
  • Locking can be late. Machines with Modern Standby send no suspend notification on Windows, so sleep there is caught by the screen lock and the clock-divergence check only. A lock trigger that stops working locks every vault once and is then unobserved.
  • The audit log is evidence, not a control. It fails open: a failed write is a warning and the request is still answered, so a same-user process that fills the disk or makes the directory unwritable silences it while secrets are served (doctor and agent status report write failures). Any client can push history out of the five rotated files with a flood of records. Records cut from the end of the newest file, and the oldest file removed with every newer one renamed a slot older, are not detected. A crash that leaves a torn last line looks like tampering to vaultfold agent log. The files are readable by the same user, so agent log shows every record even in an agent session, while the daemon's own audit-read gives an agent session only its own.
  • Memory hygiene is best effort. Key material in the daemon lives in locked, zeroed-on-release buffers, but the unlocked device key itself is on the Go heap. Some copies are not zeroed and stay in memory until garbage collection: the CLI's encoded copy of a passphrase it sends in an unlock request, the daemon decoder's copies of a decoded passphrase or redact text, and the CLI's decoded response buffers (the collection keys and values it receives; the CLI zeroes the copies it keeps). Windows has no core-dump exclusion for the daemon yet (Windows Error Reporting can dump it). A failure to lock memory is reported, not fatal.
  • Zeroing a replaced key file is best effort. key rotate overwrites the old identity file with zeros before removing it, which an SSD or a copy-on-write or journaling file system need not honour.
  • Downgrades and the machine key. The machine key moves into the OS store on first use (Secure Enclave, DPAPI or Secret Service). Running a vaultfold binary from before the daemon afterwards creates a fresh machine.key beside the sealed one, which current builds then report as a conflict until one of the two is moved aside. After an upgrade an old daemon keeps serving until vaultfold agent stop.
  • The client trusts the OS's view of the endpoint. Every daemon client (the CLI and the browser's native host) refuses an endpoint that is not the user's before sending anything (ADR 0038): on unix the socket and its directory must be the user's alone and the listening process must run as the user; on Windows the pipe must be owned by the user or by Administrators and its server process must run as the user. This defeats another local user who creates the predictable pipe name, or a socket, first. It cannot tell the real daemon from another process of the same user, which could listen on the endpoint as well as the daemon can.
  • Windows endpoint check. doctor's check of the named pipe's permissions opens the pipe as a client without SECURITY_SQOS_PRESENT, so whoever serves the pipe at that name could impersonate the user running doctor. The CLI's own connection sets it. A recorded follow-up for the first Windows run.
  • Windows paths are unverified on hardware. The Windows backends, dialogs, lock triggers, pipe checks and terminal key are cross-compiled and vetted but have not run on a Windows host.

The browser extension

The browser extension (extension/, capability browser-extension) adds a new same-user caller of the daemon and a new untrusted input: every web page the user visits. It holds no vault file, key, seed or password at rest (its storage areas hold settings, the provider table and a per-tab match cache), and everything it shows or fills comes from a daemon request over the browser's Native Messaging channel (ADR 0047, protocol in docs/protocol/browser-v1.md). No port is opened for it.

As a same-user caller

The extension is one more caller in the daemon's per-caller allowlist, and inherits the limits of "Same-user limits of the agent daemon". Its identity is the triple of host signature, browser and extension id; an unknown triple is prompted for at its first hello and can do nothing else until a human approves it (a published id with a yes, any other id by typing allow). It gets a browser session, limited to the browser verb (plus status, lock and pending), and that verb is refused to every other session kind. Agent sessions cannot drive the extension: the host refuses to connect when its parent browser was started with automation or remote debugging flags or its own environment carries an agent harness marker, the daemon repeats both checks, and the extension refuses to act in a tab whose page reports navigator.webdriver. None of that stops an agent that moves the real mouse in the human's real browser; the control for that is a collection's touch policy.

Every value that leaves the daemon for the browser (fill, copy, totp-code, passkey-get, passkey-create) is audited as a resolve with session kind browser, the browser, extension id, origin and top-level origin, never the value. Requests are rate limited at the door like any other caller (60 a minute, burst 20).

What a compromised extension or browser obtains

Treat a hostile extension build, or a browser whose extension host process is controlled by an attacker, as the extension with the user's approval already given. Through the daemon it can obtain only:

  • the metadata of logins in allowed collections (title, path, username, URLs, whether a TOTP or passkey is present), for any origin it names;
  • the password, username and TOTP code of a login entry for an origin the daemon's own match accepts, or after a confirmed flag for a cross-site frame or form. A compromised extension can send confirmed: true itself: the confirmation is a prompt in the extension's UI, and the daemon enforces that it was asked for, not that a person answered. It is a defence against a hostile page, not against a hostile extension;
  • an assertion for a passkey whose rp_id is valid for the origin it names, after any user verification the request requires, and never the private key;
  • the ability to save, update and record logins, and to lock and unlock.

It cannot obtain API keys, SSH keys, certificates, environment bundles or any entry that is not a login or a passkey: check refuses other types before any value is read. It cannot obtain a TOTP seed or a passkey private key at all (no operation returns one). It cannot obtain entries in a collection outside the daemon's [agent.browser] collections list when that is set, or in a collection with touch policy always (the prod default), which protocol version 1 does not serve to the browser. Values it does obtain are limited by the rate limit and visible in the audit log. What the host process sees is the same JSON, since it is a translator; it keeps no copy and logs no body.

A compromised browser can also read every page and every fill, which no extension design prevents.

What page-world injection exposes

Passkeys are provided by a script in the page's own JavaScript world that wraps navigator.credentials (ADR 0048). It has no extension API and holds no secret or entry data; what it exposes is the following.

  • A page can see that navigator.credentials.create and get are wrapped, and can call or replace the wrapper. That can break vaultfold passkeys on that page or fingerprint a vaultfold user. It cannot obtain a credential: the origin comes from the browser's record of the frame, not from the request, every ceremony needs a click on an extension-owned confirmation, and the key never leaves the daemon.
  • The channel between the wrapper and the extension's isolated-world bridge is a MessageChannel port handed over once per document by a synchronous event pair at document start, before any page script. A page that dispatches the hello event later gets no port, and a window.postMessage is never read as a request.
  • Requests it cannot serve fall through to the browser's own implementation, as if the extension were absent.

On-click mode registers no passkey script and no other content script until a gesture, which is the answer to the "reads every page" permission.

Phishing defences, in layers

A phishing page is a hostile web page that wants a victim's password, code or signature from the daemon, the extension or the person. The layers, outermost first, are independent: each is enough alone for the cases named, and the end-to-end phishing suite exercises them together.

  1. Origin match, in the daemon only (ADR 0049). The daemon recomputes the match on every fill, copy and totp-code from the origin the browser reported for the frame, using the public suffix list including its private section, in A-label form. Lookalikes (bank-secure.test, bank.test-login.test, evilbank.test), homographs and private-suffix neighbours (mallory.github.io for alice.github.io) do not match. A per-entry match of host, origin or never narrows it.
  2. Secure-origin rule. Nothing is offered, filled, captured, recorded or signed on an origin that is not https, except http on loopback and .localhost hosts, which are offered with a warning. file:, data:, blob:, about:, javascript: and opaque origins are refused by the daemon.
  3. Cross-site frame and form confirmation. A fill into a frame whose registrable domain differs from the top-level page's, or into a form whose action posts to another site or over a clear channel, returns confirm-required from the daemon until the request carries a confirmation; the extension shows both origins and a "Fill anyway" button, which the phishing suite never presses. A frame is also checked to hold the same document when the values arrive, else they are dropped.
  4. Fillability. Hidden, zero-size, fully transparent, off-screen, disabled and read-only fields are never filled or counted, so an invisible form beside the real one gets nothing. Auto-fill on load is off by default and, when on, applies only to a top-level https frame with exactly one match under a domain, host or origin policy and visible fields, and never submits.
  5. Menu isolation and overlay gates. The inline menu and every confirmation are an extension-origin frame in a closed shadow root: a page finds a host element and a null shadow root, and cannot read the entry list or script the buttons. On Chromium its URL is per-session (use_dynamic_url), and on Firefox the moz-extension: host is random per install. A click is ignored for 500 ms after the menu appears and while an Intersection Observer v2 check reports it obscured or not visible. Fills happen only on a gesture in that UI, the popup, the fill shortcut or a context menu item.
  6. Passkey rp id checks in three places. The isolated-world bridge, the background flow and the daemon (passkey-list, passkey-create, passkey-get) each refuse an rp id that is not the origin's host or a parent domain of it; the daemon alone also refuses a public suffix (github.io) and an IP address, and refuses a get whose rp id differs from the stored entry's. Cross-origin frames fall through to the browser.
  7. Social login prompt. The extension never reads OAuth code, state or tokens, only client_id, redirect_uri and login_hint. A flow is recorded without asking only when the user opted in and the page that started it agrees with the redirect_uri's registrable domain and is secure; a mismatch, an insecure opener, an iframe-opened popup or an unverifiable opener is shown to the person with both origins and is never recorded on its own.
  8. The test seams, and why they cannot ship. Playwright and geckodriver start browsers with the flags the automation refusal rejects, so the end-to-end suite needs three seams, each outside a release build: the daemon and the native host, built with the Go tag vaultfold_e2e, read VAULTFOLD_E2E_ALLOW_AUTOMATION=1 to skip the automation check (signer, extension id and parent browser still apply), and the daemon reads VAULTFOLD_E2E_DISABLE_ORIGIN_CHECK=1 to make every login URL match every page (the deliberately broken build make e2e-negative uses to prove the phishing suite fails without the origin check). The extension's store build ships src/lib/build/testBuild.ts, where the navigator.webdriver refusal stays on and no hook is exposed; the e2e build replaces that module with extension/e2e/override/testBuild.ts, which lives outside src/ and the addons.mozilla.org source archive. scripts/check-release-tags.sh fails a release binary built with any vaultfold_e2e tag, TestE2ESeamsOffByDefault pins a default build, the build of the e2e variants fails if the store variant carries the hooks, and test/release.test.ts fails a package that carries the e2e marker (vaultfoldTest). The environment variables are read only in files behind the tag, so no release binary reads them, and the CLI's environment tables leave them out.

The phishing suite (extension/e2e/phishing/) asserts, per case, that no input holds a victim value, no relying-party assertion for the victim verifies and the audit log has no allowed record for the victim entry. It covers lookalike, prefix and homograph domains, a private-suffix neighbour, an http downgrade, a hostile frame, three forms posting to another site, hidden, transparent, off-screen and one-pixel fields, overlay clickjacking of the menu, a page-world spoof of the passkey channel, a passkey rp id of another site and a mismatched OAuth redirect_uri, with a control case that the victim's own page fills. make e2e-negative passes only when the lookalike, homograph and private-suffix cases then fail on a leak check.

Residuals

  • The extension reads all content of every page it runs on. That is what inline menus and capture need, and the listing, first-run page and README say so. On-click mode (off by default) removes the content scripts until a gesture.
  • Developer-mode impersonation and the Linux image rule are recorded under "Same-user limits of the agent daemon" above.
  • A compromised extension can claim a confirmation. See "What a compromised extension or browser obtains".
  • Overlay checks are weaker without Intersection Observer v2. Where the browser does not implement its visibility tracking, only the 500 ms delay applies; the menu cannot be read or scripted either way.
  • The public suffix list can be stale. x.surge.sh and a.glitch.me are treated as one site by the daemon's list, so a tenant's login can match another tenant and the passkey rp id check shares the flaw (ticket 01M54MXND3).
  • Idle lock first contact gap. In a fresh profile the extension's first status comes before the human approves it, so it learns idle_lock_minutes only from a later lock or unlock; until then its idle lock does not run, and the daemon's own idle lock still does (ticket 01M5X9F0CB).
  • A redirect or navigation between opening the menu and the fill is not in the phishing suite. The daemon's origin check and the same-document check apply to it, but no end-to-end case proves it (ticket 01M5XHB8W8, which needs a spec delta first).
  • Two end-to-end cases are weaker than they should be. The overlay case can fail late rather than on the leak check, and the rp id verifier covers only the victim's rp id (test-only, ticket 01M5XMG7B0).
  • Entries in prod-style collections are not served to the browser. Protocol version 1 omits collections whose touch policy is always from matches and search and answers denied to fill and copy, because the entry's URLs cannot be matched without a touch. This is a limit on convenience, not on safety.
  • Safari and native apps have no extension path yet. They wait for the desktop app's XPC bridge and the OS credential provider integrations.
  • Sites can detect the passkey wrapper, and relying parties that demand platform attestation or an AAGUID allowlist will not work with it.

A non-member plants the vault branch or old vault files

Before the forge restricts the vault branch, anyone who can push to the repository can create it first with files of their choosing, and a migration that adopts an existing remote branch trusts the vault.json vault id alone. Planted files are inert in the fold unless they are valid, signed records. A planted wrap blocks nothing and is never read as a recipient's wrap: every wrap lives under the id of the link that calls for it, which nobody can predict before that record is signed, so a wrap planted in advance cannot be in the way of a mint, a revocation or a grant (ADR 0052; before it a wrap at the predictable next-epoch path blocked the next mint of that collection and every revocation that mints). doctor reports such a file as stray-wrap, or as orphan-wrap when its recipient does not hold the epoch. What a writer can still do with files is listed under "Wrap files and lost writes in a shared folder" in "Ordering trust and equivocation". Mitigations: vault migrate of a vault committed on the code branch anchors the local vault directory to the remote's default branch, refuses records beyond that tip that this device did not write, and copies the directory losslessly or not at all (every file at a record path must decode under its name and pass the vault check, the fold must leave no record missing a parent, key file or wrap and must know every head this machine has seen; wraps and key files no kept record needs are skipped and counted); the straggler import of files from an old vault directory imports only events and policy records a trial fold accepts, and wraps and key files an accepted policy record requires, and warns with the count it skipped; and the branch-mode root check refuses a fetched branch with unexpected root paths. None of these verifies the files of an existing remote vault branch that migrate adopts: beyond the root check and the vault id, they are taken as found. The operational control is therefore ordering: apply the forge ruleset before anyone migrates, so a non-member cannot create the branch first. Two limits once tracked as core tickets are addressed by the linear chain (ADR 0046): on an honest transport a withheld counter-revocation names a tip that is no longer the tip and is void, and a wrap written under the wrong key is never used, since a client uses only a wrap whose KEK matches the mint's kek_commit.

Malicious storage operator

Can delete or roll back (above), decides which of two concurrent privilege writes takes a slot, can withhold new policy links or show different members different chains (see "Ordering trust and equivocation"), and can observe all metadata listed in item 6. Cannot read values or structure, cannot forge events, and cannot add a device key without a signed policy event from an admin.

Hosted sync operator

The hosted sync service (add-cloud-service) is a storage operator for the namespaces it hosts, so it can see everything listed under Malicious storage operator. It stores the vault's signed metadata - the vault id, public keys, member and device ids, and event headers - inside the namespace's blobs, exactly as any git host for that vault would, and it reads the policy chain to enforce write policy. It cannot decrypt contents: values, entry paths and names, field names, and member, device and collection names stay inside ciphertext, and it never holds a KEK, DEK or private key.

The hosted namespace is a random id chosen by the client. That keeps the vault id out of object paths and keys, datastore rows, operator logs and backups (other than copies of the namespace's own blobs); the cloud spec's zero-knowledge property test pins this. It does not make the namespace unlinkable to its vault.

Residual risk: the operator, or anyone who obtains the blob store or a relay backup, can correlate a hosted namespace with the same vault seen elsewhere (a git remote, another clone, or another hosted namespace) through the vault id or any other piece of that signed metadata. That links whatever is known about the other copy to the namespace's hosted activity. A fully opaque hosted sync mode, with no server-side policy enforcement, is recorded as a future idea only (add-cloud-service design.md, Future Ideas).

Relay operator

Learns which device keys connect and when; the sizes and timing of forwarded messages; and, through push notifications, when a device was asked to approve something. Learns nothing about the vault, entries, values or scopes, which are inside the Noise channel between the two device keys. Cannot forge an approval, because approvals are signed by the approving device key and bound to the request. Can deny service. The relay protocol is open and the reference relay can be self-hosted; push delivery then requires the operator's own APNs and FCM credentials. Push registration adds a distinct, real linkage the "nothing about the vault" claim above does not cover: see "What a targeted pairing request reveals" below for exactly what a hosted operator learns by name, from the requester's device key to the recipient registration and its liveness.

Push registration (add-cloud-service task group 6) adds the following to what the operator (the relay datastore holder) can see and do:

  • What is stored. A device's registered platform push token (an APNs device token or an FCM registration token) is held in the relay datastore, keyed by the registering device's own key and the vault namespace it registered under, the namespace held in its own column (push_tokens, relaydb schema version 5; an earlier, since-corrected design packed the namespace into the device column instead of giving it one). It is never in the billing datastore, and the row holds nothing beyond the namespace, the device key, the platform and the opaque token value: no name or email. The namespace itself is a pseudonymous identifier the operator already sees for every other hosted-sync operation on that vault (cloud spec "What the service stores and sees"), not new information push registration reveals; it is still, unavoidably, a vault identifier in the operator's own datastore, so this document does not claim the row holds none. Schema version 6 (round 4) adds a second table, push_handles, mapping each opaque push handle to the one (namespace, device key) row it currently resolves to; it holds nothing beyond that mapping, so it reveals no more to the operator than push_tokens already does.
  • What a targeted pairing request reveals (relay-v1.1: orchestrator DECISION on ticket 01M3A20PVPNEGV4NE5BXRBHS4B; round 6, reviewer finding R3-B4, states this plainly rather than hedging it). A targeted-create frame itself names only an opaque push handle, never a device key or namespace: nothing on the wire, in the relay's own frames, or exposed to the requester or to any other connection ever names the recipient's device key or namespace directly, and that frame-level guarantee is real and worth stating on its own. But the hosted operator does not see only the frame: it runs both the relay process and the relaydb datastore in the same deployment (the "What is stored" point above), and since round 5 the relay process itself resolves a targeted-create's handle to the recipient's device key through an internal interface, to decide whether to skip notifying an already-connected recipient. An operator controlling both, as every hosted deployment's operator by definition does, therefore learns all of the following, not merely "a connection targeted a handle": which requester device key sent a targeted-create naming a given handle, and when; which (namespace, device key) registration that handle currently resolves to (push_handles, the "What is stored" point above); and whether that registration's device had a live connection to the relay at that moment (recipient liveness). This is strictly more than "the relay learns nothing about the vault": it is a real, named link from a requesting connection to a specific recipient registration and its online status, and this document states it as such rather than as something the operator merely "cannot derive from the frame alone". A handle is rotated (invalidated and replaced) on every re-registration or revocation, so a handle a device shared with a peer before either event stops resolving to anything afterward; the operator cannot use an old handle to link a device's registrations across a rotation, and an unknown or rotated-away handle is indistinguishable from one whose registration is currently online (both draw no push and the same created answer), which is the limit of what a requester -- as opposed to the operator -- can ever learn from sending one.
  • What APNs and FCM learn. Dispatching a notification tells Apple or Google, respectively, the device's platform token, the request id being announced, and the timing of that dispatch: enough for either platform to observe when a given device was asked to approve something, exactly as the relay operator itself can from connection timing alone. Neither platform ever receives the vault, entry, value, scope or the requesting device's identity: the push payload carries only the request id (cloud spec "Push notification relay").
  • Revocation is observable. When a namespace's policy chain revokes a device (RevokeDevice or RevokeMember), the relay datastore's row for that device's push registration under that namespace is deleted as part of processing the revocation (identities-and-devices, "Register and revoke"), and any handle that registration had minted stops resolving to anything. An operator who can watch the relay datastore over time can therefore correlate a namespace's revocation events with the disappearance of a specific device key's push registration, linking which device was removed from which namespace and when, even though the operator never learns the namespace's own meaning or the revoked member's identity beyond its device key.

Hosted service metrics and reverse proxy trust

vaultfold-cloud's /metrics endpoint (ADR 0026) reports HTTP request counts and latencies (labeled by a fixed HTTP method set and a fixed path template, never a raw request path), the number of open relay connections, and aggregate blob quota usage as unlabelled totals. It never contains a device key id, a token id, an address, a namespace or a blob path in any label or value; someone who can reach /metrics (it is routed by the same public Host() rule as every other endpoint in the Compose example, deliberately, since its content is benign) learns only aggregate traffic volume, never who did what.

The service also trusts X-Forwarded-Proto from any peer listed in VAULTFOLD_CLOUD_TRUSTED_PROXIES to decide whether a connection counts as secure. An operator who lists a peer that is not, in fact, their own TLS-terminating reverse proxy (a misconfigured CIDR that is broader than their actual proxy network, for example) lets that peer's traffic bypass the plaintext-refusal policy for machine endpoints; this is a self-hosting configuration risk, not a vulnerability in the service itself, and is why the Compose example sets the trusted-proxies list to the specific Traefik network's own subnet rather than a broad default.

Accounts and billing operator

The accounts module (add-cloud-service task group 7) is the one part of vaultfold-cloud that necessarily holds real personal and payment-adjacent data: email addresses, Polar customer and order ids, and which capability tokens a workspace issued. It is deliberately its own datastore (billing.db), opened by no code path that also opens the relay datastore (relay.db) and vice versa, so that this module's operator role is analytically separate from the relay operator role above even when the same person runs both on the same host.

  • What is stored, and what is not. billing.db holds accounts (email address, created-at), sessions and passkey credentials (hashed or public-key material, never anything that unlocks a vault), team workspaces and their members, Polar order ids and product ids, and signed license keys. It never stores a live capability token's id in the clear: each issued token's id is instead recomputed on demand from Options.TokenIDKey (configuration, never the datastore) plus the account, workspace and an issuance sequence number, so a stolen or leaked billing.db file by itself does not hand an attacker the ids needed to correlate its rows with the relay datastore's device and usage records. The one exception, revoked_tokens, holds ids in the clear by necessity: they are published in the signed revocation list to every relay and sync instance anyway, and that table names no account, workspace or order. A schema test (TestNoSharedIdentifierColumn, TestNoValueJoinsTheDatastores) enforces both the column-shape and the value-level side of this split in CI, the same way the relay/billing datastore split is checked elsewhere in this document.
  • Magic links are a bearer credential with a short window. A magic link's token is a single-use, 15-minute-default bearer value; only its hash is ever written to disk, and consuming it (or letting it expire) invalidates it permanently. Whoever can read the email it was sent to, within that window, can sign in as that account -- this is the same residual risk every "sign in via emailed link" flow carries, mitigated here only by the short default TTL, single use, and identical handling of a known versus unknown address (no enumeration: the operator's own logs and the client's own response reveal nothing about whether an address has an account). A compromised mailbox is a compromised vaultfold-cloud account for as long as an outstanding link survives; it is not a compromised vault, since a capability token only ever grants what its caveats allow against the relay and blob modules; it never carries vault key material.
  • Passkeys remove that residual risk for an account that registers one. WebAuthn credentials are origin-bound (a credential registered for this deployment's origin cannot be phished by a look-alike domain) and the private key never leaves the authenticator, so there is no shared secret in transit or at rest for an attacker to intercept the way a magic link's mail delivery can be. Registration and sign-in ceremonies use discoverable credentials with a server-side, single-use, short-lived challenge bound to the account being registered (for registration) or to nothing in particular (for sign-in, so the ceremony itself never reveals which accounts have a passkey); a challenge is consumed by its first use, successful or not, so a captured-but-unused assertion cannot be replayed after the legitimate attempt (successful or failed) that already consumed its challenge. Registration and sign-in both require user verification (WebAuthn's UV flag), not merely user presence, since a passkey is the account's only factor; the credential key's COSE algorithm is checked against the one offered (ES256) rather than merely decoded, closing an algorithm- confusion path; and a re-used or non-increasing signature counter is refused and does not overwrite the stored one, so a genuine, later assertion from the real authenticator is still judged against the last value this service actually accepted, the mitigation for a cloned authenticator's copy of the private key racing the original (round 2, review findings B3 and B4 on ticket 01M3A20PVZYCJQZZ2FPV11CGS2).
  • Unauthenticated, mail- or ceremony-triggering endpoints are rate limited per client address and, for magic links, additionally per email address (round 2, review finding B6): a request over either limit sends no mail, starts no ceremony and stores nothing, and answers identically whether or not an account exists for the address, so the limiter itself creates no new enumeration or mail-bombing surface to replace the one it closes. The client address is resolved through the operator's configured trusted proxies (VAULTFOLD_CLOUD_TRUSTED_PROXIES), the same trust model and the same code path /push's own rate limiting already uses, rather than the request's raw RemoteAddr: behind a reverse proxy, every visitor would otherwise share the proxy's own address and the limits would collapse into one global bucket for the whole deployment (round 3, review finding R1). The resolved address is never held or logged in the clear: it is hashed under a key that is itself re-derived from a random, process-lifetime secret and the current UTC day before being used as the limiter's bucket key, so a hash from one day cannot be correlated with the same address's hash on another.
  • A refund is remembered even out of order and affects only what it paid for. Polar delivers webhooks with no ordering guarantee, so a refund can arrive before, or be replayed after, the order it refunds; this module records every order id it has ever seen reported as refunded, whichever arrives first, and a refunded order is never fulfilled regardless of delivery order. Each paid order grants its own entitlement period (a subscription order's billing period, or no end for a one-time purchase), and a workspace is entitled until the latest end among its own non-refunded paid orders (round 4, review finding R4): refunding a one-time purchase, or the last non-refunded order of a subscription, revokes every capability token issued for the workspace immediately and stops further issuance; refunding one renewal while an earlier paid period is still running narrows entitlement back to that earlier period's end (or to the refund time, if that period has already ended) without touching already-issued tokens, the license, or the subscription's other periods, and a later paid renewal restores entitlement as usual. A license is added to the signed license revocation list (PathLicenseRevocations, ADR 0014's amendment; round 3, review finding R2) only when no non-refunded paid order remains for its subscription or one-time purchase, published unauthenticated and verified with the license key, never the capability token issuer key. A self-hosted deployment checking that list when online learns a license it was offline-activated with is no longer honored and the account page stops listing it; one that never reconnects keeps honoring it, the same detect-after-the-fact posture the rest of ADR 0014's license mechanism has. A partial refund changes no entitlement, token or license; it is recorded for the operator (PartialRefunds: the order id, the refunded amount and the time, no personal data, round 4, review finding R5). A subscription cancellation or revocation stops new issuance at the subscription's period end (or immediately, for a revocation) without revoking tokens already issued, which simply expire on their own; a renewal extends the same workspace and license rather than minting another pair, and an un-cancellation before the period end restores ongoing entitlement (DECISIONs on ticket 01M3A20PVZYCJQZZ2FPV11CGS2).
  • A removed, demoted or deleted admin's own pending invitations stop working immediately, as does a fully refunded workspace's (round 3, non-blocking finding N3; round 4 extends this to account deletion): an invitation is otherwise a bearer link good for up to its own TTL, so leaving it live past the access change it should have tracked would be a stale-permission window with no compensating control.
  • A rate-limited client's address is grouped by /64 when it is IPv6 (round 4, non-blocking finding), before the per-day hash above is ever computed: residential and mobile ISPs commonly hand a single customer at least a /64, so limiting by the full address would let one client cycle through addresses inside its own /64 to evade a per-client limit.
  • Workspace invitations reuse the magic-link mechanism (DECISION (g) on ticket 01M3A20PVZYCJQZZ2FPV11CGS2): an invite link is indistinguishable in shape from a plain sign-in link, usable once and only within its own, separately configurable TTL, and grants membership only on the specific workspace and role the inviting admin chose at send time, never something the recipient's own request can influence.
  • The Polar webhook secret is a credential, not a formality. Order fulfillment (workspace creation, seat grants, license issuance) is gated on a Standard Webhooks HMAC-SHA256 signature keyed by VAULTFOLD_CLOUD_BILLING_WEBHOOK_SECRET, checked with a constant-time comparison and a 5-minute timestamp tolerance against replay of an old, legitimately-signed delivery. Anyone holding that secret can fabricate a fulfilled order for any account id they can guess or enumerate (account ids are random 128-bit values, so guessing one is infeasible); it must be handled with the same care as the issuer and license signing keys, never logged, and restricted to 0600 on disk the same way (see docs/self-hosting.md). vaultfold-cloud never sees payment card data at all: Polar is the merchant of record and the only party that ever holds it, and account deletion never asks Polar to delete its own customer record, since Polar's own compliance obligations as merchant of record require it to keep one.
  • A license key is an honor-system artifact, not an enforcement mechanism (ADR 0014). It proves that this billing module signed a specific seat count for a specific workspace at a specific time; it does not, and cannot, prevent a workspace from adding more members to a self-hosted deployment than its license's seat count names. Its threat model is limited to detecting dishonesty after the fact (comparing a license's Seats against an open vault's actual member count), never preventing it.
  • Revocation from this module reaches a relay or sync instance only on its next poll, the same propagation delay every capability-token revocation already has (see VAULTFOLD_CLOUD_REVOCATION_INTERVAL in docs/self-hosting.md): removing a team member or deleting an account adds the affected token ids to the signed revocation list within the same call, but a relay or sync instance that already accepted a connection under one of those tokens keeps it until its own next revocation-list fetch and sweep, not instantly.

Residual risk and the rotation workflow

The largest residual risk is the combination of item 1 with human behaviour: a departing colleague, a lost unencrypted laptop, or a device whose lock cannot be trusted. In each case the cryptography stops future reads immediately and cheaply, and it cannot do anything about past reads. vaultfold therefore treats revocation as the start of an operational task rather than the end of a cryptographic one: on revocation it marks every entry the revoked party could read as requiring rotation, presents the list, tracks which credentials have been changed, and reminds until the list is empty. For ex-members, vaultfold audit exposure lists every entry whose current value was readable by a since-revoked member or device and has not been rotated since; this report is the operational core of the rotation workflow. Entries may also carry rotation intervals and expiry reminders independent of any incident. Teams that cannot rotate a credential should know that its confidentiality against that party is gone.

Forward secrecy

Not in version 1. The deferred design is one-time pre-keys per device: each epoch KEK is wrapped to a fresh ephemeral key, which the device deletes after caching the KEK in the OS keychain, so wraps in git history are useless to someone who later steals the long-term device key. Hardware-resident device keys (after 1.0) would cover the main case, since the key cannot be extracted. A prekey recipient type id is reserved in the suite registry.

Out of scope

Side-channel resistance of the platform's cryptographic libraries beyond using constant-time implementations; physical attacks on hardware key stores; the security of the operating system's keychain and biometric implementations; malware running as root, or a keylogger with screen capture, on the daemon's machine (same-user malware is narrowed, not prevented; see Compromised device); and the trustworthiness of the forge used to fetch a colleague's public key, which is presented as trust-on-first-use with an out-of-band verification option.