libVES.subtle is a simple JS library for managing and sharing end-to-end encrypted items using VES public key infrastructure. The end-to-end encryption keys are safeguarded from key loss by VES redundancies and recovery options.
libVES.subtle provides a set of features sufficient for most VES integrations. For the lower level VES library, see the libVES.js docs.
<script type="text/javascript" src="https://ves.host/pub/libVES.js"></script>
/*************************************************************************** * Unlock the Vault ***************************************************************************/ // Unlock a User App Vault using an interactive browser popup // OR, unlock a User App Vault using locally stored credentials. Make sure // the credentials are stored securely // OR, unlock an Anonymous App Vault using a secret passPhrase. The Vault ID // is uniquely generated from the passphrase. // Check if the Vault is unlocked /*************************************************************************** * Get an array of all items stored in the vault * @returns Promise(Array(libVES.Item)) ***************************************************************************/ /*************************************************************************** * Create an Item instance * @returns libVES.Item ***************************************************************************/ // Create an instance of an item with a specified itemId // Create an instance of an item with an automatically assigned itemId /*************************************************************************** * Start real time event tracking. * Call vault.addEventListener() or define vault.on* event handlers prior to * the following call. The handlers are invoked with libVES.CustomEvent ***************************************************************************/ // Start tracking future events without replaying the event history // Or, start tracking and replay the past events starting with nextId. // Use nextId = 0 to replay all history from the beginning. // Or, start tracking and replay the short history that includes only // currently existing items /*************************************************************************** * Stop real time event tracking ***************************************************************************/ /*************************************************************************** * Get the special Item that stores the VESkey (passphrase) to the Vault. * The VESkey can be retrieved using item.get() is it is decryptable by the * unlocked Vault. * @returns Promise(libVES.Item) ***************************************************************************/ /*************************************************************************** * Get the list of dependent Vaults that are directly unlockable by the * current Vault. * @returns Promise(Array(libVES.Vault)) ***************************************************************************/ /*************************************************************************** * Create an instance of the specific Vault. The vaultId can be a VES URI * or a short ID. Use the owner's email address to reference a Vault within * the current VES Domain owned by the specific user. * @returns libVES.Vault ***************************************************************************/ /*************************************************************************** * Verify the status of the Vault. This call returns a Promise that resolves * to the current vault on success, or throws libVES.Error. * The call populates vault.current and vault.owned * @returns Promise(libVES.Vault) ***************************************************************************/ /*************************************************************************** * The following propertiest indicate the status of the Vault. The properies * are populated by vault.unlock(), vault.verify(), and in the Vaults * returned by item.share() ***************************************************************************/ // The Vault currently exists, and is not in a Lost status // @type boolean // The Vault/Subvault is owned by the unlocked Vault. // @type boolean // The Vault has an Admin permission on the Item. This property is populated // only in the Vaults returned by item.share() // @type boolean /*************************************************************************** * Get a VES URI that idenitfies the Vault. * @returns string ***************************************************************************/ /*************************************************************************** * Get a short identifier of the Vault. Note that the short identifier is * specific to the selected VES domain. Use vault.uri() to get a full * identifier that includes the VES domain. * @returns string ***************************************************************************/ /*************************************************************************** * Lock the Vault ***************************************************************************/ // Set the lock timeout in seconds. The Vault will be automatically locked // when the timeout expires. Register a handler for an "authexpire" event to // catch the expiration before the Vault is locked. // Any call to this function overrides the previously set timeout. // Lock the Vault immediately /*************************************************************************** * @type libVES.Item * Store a value in the item. The value is stored in the VES Repository an * e2e encrypted form. ***************************************************************************/ /*************************************************************************** * Retrieve the value stored in the item * @returns Promise(string) ***************************************************************************/ /*************************************************************************** * Manage the item sharing with other vaults in an e2e encrypted form ***************************************************************************/ // Share the item with other vaults, keep any existing sharing // Remove sharing with the specified Vaults. // Note: The current Vault can be removed if it doesn't own the Item. // Removing will make the Item unaccessible through the current Vault, // unless shared again by the Item owner. // Replace the list of vaults the Item is shared with. The current Vault is // added automatically if not included. // Get the list of vaults the Item is currently shared with // @returns Promise(Array(libVES.Vault)) // Check whether the item is shared with a specific Vault. Returns null if // not shared. // @returns Promise(libVES.Vault) /*************************************************************************** * Check if the item currently exists and was not deleted. * @returns boolean ***************************************************************************/ /*************************************************************************** * Delete the item. The item ID can be reused for another item. ***************************************************************************/ /*************************************************************************** * Start real time event tracking. * Call item.addEventListener() or define item.on* event handlers prior to * the following call. The handlers are invoked with libVES.CustomEvent ***************************************************************************/ // Start tracking future events without replaying the event history // Or, start tracking and replay the past events starting with nextId. // Use nextId = 0 to replay all history from the beginning. // Or, start tracking and replay the short history that includes only // the Vaults the Item is currently shared with /*************************************************************************** * Stop real time event tracking ***************************************************************************/ /*************************************************************************** * Get a VES URI that idenitfies the Item. * @returns string ***************************************************************************/ /*************************************************************************** * Get a short identifier of the Item. Note that the short identifier is * specific to the selected VES domain. Use item.uri() to get a full * identifier that includes the VES domain. * @returns string ***************************************************************************/ /*************************************************************************** * Check if the Item value can be retrieved and decrypted by the currently * unlocked Vault. * @returns boolean ***************************************************************************/ /*************************************************************************** * Check if the Item value can be overwritten by the currently unlocked * Vault. * @returns boolean ***************************************************************************/ /*************************************************************************** * Use the Item as a stream cipher for encrypting and decrypting arbitrary * data. If the Item is used for a cipher, the cipher key is stored in the * VES repository in an e2e encrypted form, and the Item cannot store any * other value. * @returns Promise(libVES.ItemCipher) ***************************************************************************/ /*************************************************************************** * @type libVES.ItemCipher * A stream cipher for encrypting arbitrary data. The cipher key is stored * in the VES Repository in an e2e encrypted form. The data encrypted by * the cipher can be stored at any external storage. The default cipher * algorithm is AES256GCM1K, a VES implementation based on AES-256 GCM. * The plaintext and ciphertext data can be ArrayBuffer, Uint*Array, * Int*Array, Blob or string. The type of the return value of encrypt() and * decrypt() conforms to the type of the input value. If the type is string, * the ciphertext is Base64 encoded. ***************************************************************************/ // Encrypt the data // Decrypt the data /*************************************************************************** * An arbitrary metadata object associated with the cipher. The metadata is * stored in the VES Repository in an e2e encrypted form along with the * cipher key. ***************************************************************************/ // Store metadata // Retrieve metadata /*************************************************************************** * @type libVES.CustomEvent * An event related to a Vault or an Item, current or hitorical. VES stores * a history of essential events for all objects. * * Event types: * "authexpire" : the Vault will be imminently locked unless an action * is taken. The event handler may call vault.lock(tmOut) * to extend the unlocked time by tmOut seconds. This * event is real time only, not stored in the history * "vaultcreate" : a Vault is created * "vaultadd" : the Item that stores the passphrase to a Vault is * shared with another Vault * "vaultremove" : the Item that stores the passphrase to a Vault is * unshared with another Vault * "itemcreate" : an Item is created * "itemadd" : an Item is shared with a Vault * "itemremove" : an Item is unshared with a Vault * "itemdelete" : an Item is deleted * "itemchange" : an Item has been changed. This event is delivered to * each Vault the Item is shared with that are currently * listening to real time events. The event does not * have historical value and is not guaranteed to be * permanently stored by VES. * "olditemadd" : a historical (deleted) version of the Item is shared * with a Vault. Historical versions are not guaranteed * to be permanently stored in the VES Repository. * "olditemremove" : a historical version of the Item is unshared with a * Vault * "sessioncreate" : the vault has been unlocked, a new session is created ***************************************************************************/ /*************************************************************************** * Event details dictionary ***************************************************************************/ // @type libVES.Item // The Item pertaining to the Event. Populated for "item*" and "olditem*" // event types. // @type libVES.Vault // The Vault pertaining to the event that the Item was shared or unshared // with. Populated for "*add" and "*remove" event types. // @type libVES.Vault // The Vault pertaining to the Event, the passphrase Item to which was // shared or unshared with another Vault, or an action was taken on. // Populated for "vault*" and "authexpire" event types. // @type libVES.Author // The Session that authored the changes triggering the Event // @type libVES.Author // The Session subject to the Event. Populated only for "session*" event // types. // @type int // A unique numeric ID of the Event. Not populated on provisional Events // (when replay == true). // @type Date // The timestamp of the Event. Not populated on provisional Events (when // replay == true). // @type boolean // If set to true, the Event is provisional, and does not correspond to // any Event stored in VES. Provisional events are generated by // vault.start(false) or item.start(false) to replay the short history // that leads to the current state of the Vault / Item. /*************************************************************************** * @type libVES.Author * A VES session pertaining to an authenticated App Vault or to a VES User. * The details of the session can only be retrieved by a Session with the * same owner. Historical Session details are not guaranteed to be * permanently stored in VES. ***************************************************************************/ // @type int // A unique numeric Session ID // @type libVES.Vault // The Vault that is authorized for the Session // @type string // An IPv4 or IPv6 address of the creator of the Session // @type string // A User Agent string passed to the API call that created the Session
/*************************************************************************** * ___ ___ * / \ / \ VESvault * \__ / \ __/ Encrypt Everything without fear of losing the Key * \\ // https://vesvault.com https://ves.host * \\ // * ___ \\_// * / \ / \ libVES.subtle.js * \__ / \ __/ Manage and share e2e encrypted items * \\ // Real time event tracking * \\ // VES PKI and e2e Key Exchange * \\_// VES Redundancies and Key Recovery * / \ * \___/ * * * (c) 2025 VESvault Corp * Jim Zubov <jz@vesvault.com> ***************************************************************************/ /*************************************************************************** * @type libVES.Vault * libVES.subtle Vault Factory * Use "demo" for the public shared VES demo domain * Use "x-*" to create your own experimental domain * @returns libVES.Vault ***************************************************************************/