lockfile-lint-api

Programmatic API library for linting npm and yarn lockfiles to analyze and detect security issues. Provides parser and validator classes to enforce security policies and prevent malicious package injection attacks.

Quick Start

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

// Parse and validate
const parser = new ParseLockfile({ lockfilePath: './package-lock.json' });
const lockfile = parser.parseSync();
const validator = new ValidateHost({ packages: lockfile.object });
const result = validator.validate(['npm']);

if (result.type === 'success') {
  console.log('All packages are from allowed hosts');
} else {
  console.error('Validation failed:', result.errors);
}

Package Information

• Package: lockfile-lint-api
• Installation: npm install lockfile-lint-api
• Node.js: >= 16.0.0

Core Components

Parser

• ParseLockfile - Parses npm and yarn lockfiles into unified format

Validators

• ValidateHost - Validates package sources come from whitelisted hosts
• ValidateHttps - Ensures all packages use HTTPS protocol
• ValidatePackageNames - Detects name confusion attacks
• ValidateScheme - Validates URI schemes (protocols)
• ValidateUrl - Validates exact URL whitelisting
• ValidateIntegrity - Validates SHA-512 integrity hashes

Core Imports

const {
  ParseLockfile,
  ValidateHost,
  ValidateHttps,
  ValidatePackageNames,
  ValidateScheme,
  ValidateUrl,
  ValidateIntegrity
} = require('lockfile-lint-api');

Architecture

The library has two main functional areas:

1. Parsing: ParseLockfile reads and parses lockfiles (npm v1/v2/v3, yarn classic, Yarn Berry) into a unified format
2. Validation: Six validator classes that check different security aspects of lockfile contents

All validators follow a consistent pattern: accept a packages object in constructor, expose a validate() method returning a result object.

Quick Reference

Validation Result Structure

interface ValidationResult {
  type: 'success' | 'error';
  errors: ValidationError[];
}

interface ValidationError {
  message: string;
  package: string;
}

Parse Result Structure

interface ParseResult {
  type: 'success';
  object: {
    [packageKey: string]: PackageMetadata;
  };
}

interface PackageMetadata {
  version: string;
  resolved?: string;
  integrity?: string;
  requires?: Object;
}

Error Handling

• Critical Errors: Throw ParsingError exceptions for invalid arguments or parsing failures
• Validation Failures: Return error result objects with detailed information
• Auto-skip: Packages without resolved field are automatically skipped by URL-based validators

Registry Shortcuts

ValidateHost supports shortcuts:

• 'npm' → 'registry.npmjs.org'
• 'yarn' → 'registry.yarnpkg.com'
• 'verdaccio' → 'registry.verdaccio.org'

API Quick Reference

Documentation

Guides

• Quick Start Guide - Step-by-step getting started

Examples

• Real-World Scenarios - Comprehensive usage examples
• Edge Cases - Advanced scenarios and special cases

Reference

• ParseLockfile API - Complete parsing API documentation
• ValidateHost API - Host validation reference
• ValidateHttps API - HTTPS validation reference
• ValidatePackageNames API - Package name validation reference
• ValidateScheme API - URI scheme validation reference
• ValidateUrl API - URL whitelisting reference
• ValidateIntegrity API - Integrity hash validation reference

Common Patterns

Basic Validation Flow

1. Parse lockfile: new ParseLockfile({ lockfilePath }) → parseSync()
2. Create validator: new ValidateXxx({ packages: lockfile.object })
3. Validate: validator.validate(...args)
4. Check result: result.type === 'success' or handle result.errors

Comprehensive Validation

See Real-World Scenarios for complete examples including:

• CI/CD integration
• Pre-commit hooks
• Multi-validator workflows
• Error aggregation

Error Types

ParsingError types:

• NO_OPTIONS - Missing options object
• NO_LOCKFILE - Missing lockfile path or text
• NO_PARSER_FOR_TYPE - Unsupported lockfile type
• NO_PARSER_FOR_PATH - Cannot determine lockfile type
• READ_FAILED - File read failure
• PARSE_NPMLOCKFILE_FAILED - npm parsing failure
• PARSE_YARNLOCKFILE_FAILED - yarn parsing failure

Next Steps

• New to the library? Start with the Quick Start Guide
• Need examples? Check Real-World Scenarios
• Looking for API details? Browse the Reference Documentation
• Handling edge cases? See Edge Cases