Documentation
Network lock and recovery
The network lock protects a VIGIL-MESH network against sensitive changes decided alone or by mistake: it requires a k-of-n quorum before a critical change takes effect. And because a lock is only worth having if it can be reopened, the recovery kit is generated entirely in the browser: the server never sees a single byte of the backup keys.
The k-of-n lock
The network lock places a network's sensitive changes under quorum: a critical change only applies once k approvals out of n key holders are gathered. No single person can, on their own, modify what puts the network at risk — a quorum's agreement is required.
The benefit is twofold. First against error: an administrator's unfortunate gesture has no effect until the quorum has confirmed. Then against the compromise of a single account: taking control of one administrator is not enough to get past the lock, since k-1 independent approvals are still missing. Trust is thus distributed instead of being concentrated on a single holder.
The recovery kit
A lock only makes sense if you keep the means to reopen it after losing access. That is the role of the recovery kit. The essential point: this kit is generated entirely in the browser, via the WebCrypto API. The backup keys are born, live and stay client-side — the server never sees a single byte of these keys.
- 1Local generationThe browser produces the backup keys via WebCrypto. Nothing secret travels to the server during this step.
- 2Handover to the userThe kit is presented for you to save yourself. This is the only moment you hold the backup keys in the clear.
- 3Offline safekeepingYou store the kit offline, out of harm's way. The server, for its part, only keeps what is necessary to verify a recovery, never the backup keys themselves.
The consequence of this model is direct: a server compromise does not yield the backup keys, since it has never seen them. In return, responsibility for the kit falls to you: losing the kit with no other recovery path can mean permanently losing the ability to reopen the lock. That is not a flaw, it is the price of a server that stays blind.
Best practices
- Keep the recovery kit offline, on a medium that is not exposed to the network.
- Keep at least one backup copy in a physically separate location, to survive the loss of one medium.
- Never paste the kit's contents into an online service, a ticketing system or a messaging app: that would hand over to the network exactly what the browser kept out of its reach.
- Distribute the lock's key-holder roles among distinct people, so that the k-of-n quorum has real meaning.
- Periodically review the list of holders (departures, role changes) so that a quorum remains reachable without being overly concentrated.