Lockfile-lint-api NPM

About

Lints an npm or yarn lockfile to analyze and detect issues

Install

npm install --save lockfile-lint-api

Usage

lockfile-lint-api exposes a set of validator APIs that can be used for programmatic use-cases, such as being employed by other tools and programs if needed.

Validators

The following lockfile validators are supported

Validator API	description	implemented
ValidateHttps	validates the use of HTTPS as protocol schema for all resources	✅
ValidateHost	validates a whitelist of allowed hosts to be used for resources in the lockfile	✅
ValidatePackageNames	validates that the resolved URL matches the package name	✅
ValidateScheme	validates a whitelist of allowed URI schemes to be used for hosts	✅
ValidateIntegrity	validates that the integrity hash type is sha512	✅

NOTE: package entries without a resolved field (for example, those installed from the local filesystem) will automatically pass all url-based validators.

Success and failures

When validators encounter errors they will throw an exception, and on either success or failure in validating data they will always return a descriptive object for the validation task.

Successful validation

When validation is successful the following object will be returned from the validating function:

{
  "type": "success",
  "errors": []
}

Failed validation

When validation has failed the following object will be returned from the validating function:

{
  "type": "error",
  "errors": [
    {
      "package": "@babel/cli",
      "message": "detected invalid origin for package: @babel/cli"
    }
  ]
}

Notes about the returned object:

An errors object will always return an array of errors metadata, even if there's only one error associated with the validation being performed
All errors should always have a message
The availability of the package property and other metadata depends on the specific validators being used

Example

const validator = new ValidateHost({packages: lockfile.object})
let result
try {
  result = validator.validate(['npm'])
} catch (error) {
  // something bad happened during validation and the validation
  // process couldn't take place
}

console.log(result)
/* prints
{
  "type": "error",
  "errors": [
    {
      "message": "detected invalid origin for package: meow",
      "package": "meow"
    }
  ]
}
*/

Example

const {ValidateHost, ParseLockfile} = require('lockfile-lint-api')

// path to the lockfile
const yarnLockfilePath = '/path/to/my/yarn.lock'
const options = {
  lockfilePath: yarnLockfilePath
}

// instantiate a new parser with options object
const parser = new ParseLockfile(options)

// read the file synchronously and parses it
// providing back an object that is compatible
// with the @yarn/lockfile library which has
// all the packages listed in `lockfile.object`
const lockfile = parser.parseSync()

// now instantiate a validator object with those
// list of packages
const validator = new ValidateHost({packages: lockfile.object})
let result
try {
  // validation is synchronous and is being called
  // with 'npm' as a shortcut for the npm registry
  // host to validate all lockfile resources are
  // whitelisted to the npm host
  result = validator.validate(['npm'])
} catch (error) {
  // couldn't process the validation
}

if (result.type === 'success') {
  // validation succeeded
}