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
}

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

lockfile-lint-api © Liran Tal, Released under the Apache-2.0 License.