xSumJS

xSumJS is a Node.js package which can be used for validating file checksums and comparing them against a hash digest file. Hash digests and checksums can be generated using any of the following programs:

• xSum
• sha256sum
• DirHash
• CyberChef

---

Requirements

xsumjs is tested with Node.js 16 (LTS) and higher

---

Usage

The following is a simple example of how to use:

const xs = require('xsumjs');

try
{
    await xs( algo, digest, baseDir, files );
    console.debug( 'Good Checksum' );
}
catch ( err )
{
    console.error( 'Bad Checksum', err );
}

This is a more advanced example:

const xs            = require('xsumjs');
let fileList        = []; // populate fileList with your files to check
let xsParams        = { encoding: 'binary' }; // binary, utf8, etc.

await runValidator  ({ algo: 'sha256', fileList, fileDigest: 'SHA256SUM.txt', xsParams });

async function runValidator( args )
{
    console.log( `Validating checksums for files against ${ args.fileDigest }` );

    const digest        = path.join( '/path/to/', args.fileDigest );
    const checksum      = new xs.CSVerify( args.algo, digest, args.xsParams );

    await checksum.verify( '/path/base/folder/', args.fileList ).catch( err =>
    {
        
        if ( err instanceof xs.CSErrorMismatch )
        {
            console.error( `Checksum for ${ err.filename } did not match digest ${ args.fileDigest }` );
        }
        else if ( err instanceof xs.CSErrorParse )
        {
            console.error( `Digest ${ args.fileDigest } could not be loaded`, err );
        }
        else if ( err instanceof xs.CSErrorNoMatch )
        {
            console.error( `Checksum for ${ err.filename } not found in digest ${ args.fileDigest }` );
        }
        else
        {
            console.error( `Error finding checksums in ${ args.fileDigest }`, err );
        }

        process.exit( 1 );
    } );

    console.log( `All files successfully validated with digest ${ args.fileDigest }` );
}

---

Hash Digests

A hash digest typically contains a list of all files you wish to track in your project. The file checksum will appear to the left, followed by a space, and then the full path to the file relative to the project's root folder to the right.

d63ba16a664619c2dc4eb2aeef2a2e64cbc7931b831e0adf1c2275ee08e8fd47  example_file_1.txt
dfb8dacbd53eac730814ef2e9f74a47efabe5cb2a5e458bcad6380ae4c1f1f59  example_file_2.txt
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  sample_zip_1.zip
60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752  README.md

---

Development

Install eslint, prettier, and ensure files are properly formatted:

npm install -g prettier
npm install eslint --save-dev
npx prettier --write .

Note

Note that test checksums are compared to sha256 with 64 rounds.

To run tests:

npm run test

When running tests, a list of files are provided in the test/fixtures folder:

File	Description
tests-checksum.digest	test hash digest file. all checksums are sha256 with 64 rounds
tests-checksum.bin	test binary file
tests-checksum-bad	test file for comparing a bad checksum
tests-checksum-good	test file for comparing a good checksum
tests-checksum-good	test file for comparing an invalid checksum