sga-patch v0.0.6
sga-patch
Software Update Patch Generation Utility for NodeJs and NWJS Applications
This tool allows user to generate an installation patch that allows for remote upgrading of NodeJs and NWJS applications.
To generate a patch archive, user must supply two folders - A: Existing folder deployed on user systems (previous software version deployment); B - folder that is meant to be deployed (new software version deployment); Patch Generator will compare both folders, identify differences, compress them using ZIP/DEFLATE compression and package them into a proprietary patch file.
Features:
- Proprietary file format
- File header validation (won't accept garbage or corrupt downloads)
- SHA256 content signature validation
- Content signing with private RSA key
- Optional validation with public RSA key
- Optional comparison of
name
field in package.json (to ensure that patch is not being applied to a different project) - All data is compressed
Public RSA key is meant to be installed on client systems. RSA signature validation prevents hostile actors from publishing updates even if they are able to gain access to the server infrastructure.
Install via NPM:
npm install -g sga-patch
Generate RSA keypair:
sga-patch generate-keys
Create patch archive:
sga-patch package <source folder> <dest folder> <archive filename>
NOTE: You must use quotes if folders contain spaces.
To execute update process:
- Download patch file
- Make sure you have a local copy of
.sga-rsa-pub
file - Read
.sga-rsa-pub
file - Run the following code:
var Patch = require('sga-patch');
var pgen = new Patch(/*{ trace : true }*/);
pgen.applyPatch('patch-filename.sga-patch', 'destination/folder/', /* Options: */ { pkcs1 : /* .sga-rsa-pub contents */, testPackageName : true }, callback);
Options:
- pkcs1 - if defined, should contain RSA pub key. Patch deployment will fail if key signature does not match.
- testPackageName - if
true
target folder will be tested for packagename
inpackage.json
and patch deployment will fail if it does not match the name of the package from which patch has been generated.
Full example:
var fs = require('fs');
var Patch = require('sga-patch');
var pgen = new Patch(options);
var pkcs1 = fs.readFileSync('.sga-rsa-pub','utf8');
pgen.applyPatch('test-archive.sga-patch','c:/dev/project/test-output/', { pkcs1, testPackageName : true }, function(err) {
if(err) {
console.log("Error:",err.toString());
err && err.stack && console.log(err);
}
else {
console.log('Patch applied!');
}
})
NOTE: If you are testing patch deployment against the target folder, you may get console warnings in case patch is unable to delete folders or files that should exist in the target destination.