libves

v3.2.0

Published

17 days ago

Recoverable end-to-end encryption for browser and Node — key management, sharing, and key recovery without exposing keys or plaintext

          ___       ___
         /   \     /   \    VESvault
         \__ /     \ __/    Encrypt Everything without fear of losing the Key
            \\     //                   https://vesvault.com  https://ves.host
             \\   //
     ___      \\_//
    /   \     /   \         libVES:                      VESvault API library
    \__ /     \ __/
       \\     //
        \\   //
         \\_//              - Key Management and Exchange
         /   \              - Item Encryption and Sharing
         \___/              - VESrecovery™

libVES.js

End-to-end encryption for the browser and Node — that you can actually recover from.

The official VESvault JavaScript library. It does client-side end-to-end encryption with three things most E2E stacks leave you to build (or skip) yourself:

End-to-end encryption at rest — data is encrypted in the browser/Node; the server only ever stores ciphertext.
Secure item sharing — share an encrypted value with another user by reference; they decrypt it with their key, no shared password.
VESrecovery™ — recover from a lost key without weakening the encryption.

Also on npm: libves.

Why VES exists

True end-to-end encryption has a brutal failure mode: lose the key and the data is gone forever. That single problem is why most products quietly fall back to server-side encryption, where the provider can read everything.

VES makes the encryption keys themselves recoverable — through other devices and people you trust — without the VESvault service ever seeing your keys or your plaintext. You get real end-to-end encryption and a way back in when a device is lost.

Is VESrecovery a backdoor? No. Recovery re-shares an encrypted key along a trust chain you define (your other devices, designated recovery contacts); the server only ever holds ciphertext it cannot decrypt. The mechanism — and its honest trade-offs — are written up in the VESrecovery design doc and at https://ves.host. We welcome scrutiny of it.

Quick start

// Open a vault in the shared `demo` domain (use your own identity in place of
// [email protected]). unlock() runs your app's auth: the VES authorization popup
// in the browser, or the local key store under Node — see the docs for options.
const vault = libVES.subtle('//demo/[email protected]');
await vault.unlock();

// Items are addressed by URI. Encrypt + store, then read it back:
await vault.item('//demo/note-1').put('hello');
console.log(await vault.item('//demo/note-1').get());   // -> "hello"

// Share with another VES user — they decrypt with their own key
// (their vault must already exist):
await vault.item('//demo/note-1').share(['//demo/[email protected]']);

put() / get() / share() handle the encryption, key exchange, and API calls for you. Full API reference: https://ves.host/docs/libVES-subtle.

Domains. A VES domain (the demo above) namespaces vaults and items. It may mirror a DNS domain, but it must be registered in VES first. Two kinds work without registration: demo — a shared sandbox, used in the examples here — and x-… — experimental domains (any name beginning with x-) that are created automatically on first use, giving you a private namespace to build against. Any other (real DNS) domain returns an error until it is registered through VES Enterprise.

Runnable end-to-end examples live in tests/ (01-item.js, 02-share.js, …) and can be run with node tests/01-item.js or opened in the browser via tests/index.html.

Install

npm install libves

Or build from source (see below) and load libVES-<version>.js with a <script> tag.

Building

node build.js — produces version-stamped libVES-<version>.js (browser) and libVES-<version>.node.js (Node) for CDN/<script> delivery, plus stable libVES.js and libVES.node.js (the npm browser / main entry points). Cross-platform; Makefile.bat and make all both call it.
node build.js --minify — also writes libVES-<version>.min.js and libVES.min.js (requires npm i -D terser).
Requires Node 18+ (uses the built-in fetch).

Wasm builds

Post-quantum (ML-KEM via liboqs) and ECDH primitives are compiled to WebAssembly. See the comments in WasmOQS/Makefile and WasmECDH/Makefile.

Post-quantum

The library supports post-quantum key exchange (ML-KEM / Kyber and other KEMs) via the libVES.Algo.OQS module and the WasmOQS build. This matters today: "harvest now, decrypt later" means data exchanged with classical-only keys can be captured now and broken once quantum hardware arrives.

Real-time events

libVES.Vault and libVES.Item are event targets: call .start() and add listeners to react to activity as it happens — an item shared with you, a key granted or revoked, a new session opened.

vault.addEventListener('itemadd', (e) => {
    console.log('shared with me:', e.detail.item.uri());
});
vault.start();          // begin watching; vault.stop() to end

Useful for live UI updates, notifications, and reacting to shares and revocations without polling your own state. (libVES.Watch is the lower-level long-poll primitive underneath.)

Pricing & terms

VES has a free tier; paid usage is priced by volume. The library is free and open source under the Apache License 2.0. See current terms and pricing at https://ves.host/terms_conditions and https://vesvault.com.

Contributing

Bug reports and small, focused fixes are welcome via issues and pull requests. Because this is security-critical software backed by a hosted service, larger changes — new cryptography, API-surface or protocol changes — should start with an issue before you write code; we can't always merge changes that affect the protocol or the service. See CONTRIBUTING.md for build, syntax-check, and test details, and our Code of Conduct.

Security issues are different: please don't open a public issue or PR — follow SECURITY.md.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme