libvalence

Library for secure updates with Soatok's Valence project

Installing

Use npm to add libvalence as a dependency.

npm install --save libvalence

Usage

The public API for libvalence is called Bond. Configuration should be straightforward:

const { Bond } = require('libvalence');
 
// Initialize
let bond = Bond.fromConfig(
    'project-name-goes-here', // Name of the current project
    __dirname + "/app",       // Project directory
    [
        // Update server URLs:
        'https://update-server.example.com',
        'https://backup-server.example.com',
    ],
    [
        // Public keys:
        'public-key-of-publisher-goes-here',
        'other-public-key'
    ]
);
 
// If the user has an access token (e.g. stored in a text file), you can
// set it like so:
bond.setAccessToken('user-provided access token goes here');
 
// Add Chronicles, require 2 out of 3 to agree:
bond.addChronicle('https://chronicle.example.com', 'public key goes here')
    .addChronicle('https://chronicle2.example.com', 'public key goes here')
    .addChronicle('https://chronicle3.example.com', 'public key goes here')
    .setQuorumSamples(3)
    .setQuorumThreshold(2);

Once your Bond is setup and configured, you can use it like so to fetch updates from the server and install them:

/** @var {Bond} bond */
bond.getUpdateList('alpha').then(async (obj) => {
    try {
        let mirror = obj.mirror;
        let update = obj.updates.shift();
        let updateInfo = await fetch.fetchUpdate(update.url, mirror, bond.verifier);
        if (updateInfo.verified) {
            await bond.applier.unzipRelease(updateInfo);
        }
    } catch (e) {
        console.log(e);
    }
});

Update Policies

By default, libvalence uses a semantic versioning update policy, which will automatically apply PATCH updates but not MAJOR or MINOR version changes.

Old Version	New Version	Auto-Update?
v1.4.13	v1.4.14	YES
v1.4.13	v1.4.15	YES
v1.4.13	v1.5.0	NO
v1.4.13	v1.5.14	NO
v1.4.13	v2.0.0	NO
v1.4.13	v2.5.0	NO
v1.4.13	v2.4.14	NO

You can create your own update policy like so:

const UpdatePolicy = require('libvalence').UpdatePolicy; 
module.exports = class CustomUpdatePolicy extends UpdatePolicy {
    /**
     * @param {string} oldV 
     * @param {string} newV 
     * @returns {boolean} 
     */
    shouldUpdate(oldV, newV) {
        // Apply your logic here...
        return false;
    }
};

And then you can add it to your Bond instance like so:

const CustomUpdatePolicy = require('./CustomUpdatePolicy');
 
/** @var {Bond} bond */
bond.setUpdatePolicy(new CustomUpdatePolicy);