LavaMoat Preinstall Always Fail

LavaMoat Preinstall Always Fail is a security utility npm package that prevents accidental execution of npm lifecycle scripts by failing during the preinstall phase. It forces developers to be explicit about script execution by requiring the --ignore-scripts flag, promoting safer package management practices.

Package Information

• Package Name: @lavamoat/preinstall-always-fail
• Package Type: npm
• Language: JavaScript (npm lifecycle scripts)
• Installation: npm install @lavamoat/preinstall-always-fail

Core Installation

Add to your project's dependencies:

{
  "dependencies": {
    "@lavamoat/preinstall-always-fail": "^2.1.1"
  }
}

Basic Usage

This package has no programmatic API. It works automatically through npm's package lifecycle system:

# This will fail with an error message
npm install

# This will succeed - scripts are ignored 
npm install --ignore-scripts

# This will also succeed
yarn install --ignore-scripts

When installation is attempted without --ignore-scripts, the package fails with this message:

Don't run npm lifecycle scripts by default! Create a .yarnrc or .npmrc and set enableScripts: false. Then, whitelist them with @lavamoat/allow-scripts

Architecture

This package implements security through npm lifecycle hooks rather than exportable code:

• Preinstall Script: Automatically triggered during package installation
• Failure Mechanism: Always exits with code 1 unless scripts are disabled
• Security Model: Forces explicit opt-in to script execution
• Integration Pattern: Works with @lavamoat/allow-scripts for selective script whitelisting

Capabilities

Preinstall Security Gate

Prevents accidental execution of npm lifecycle scripts by failing during package installation.

{
  "scripts": {
    "preinstall": "echo \"Don't run npm lifecycle scripts by default! Create a .yarnrc or .npmrc and set enableScripts: false. Then, whitelist them with @lavamoat/allow-scripts\" && exit 1"
  }
}

Behavior:

• Executes automatically during npm install or yarn install
• Always exits with code 1 (failure) when scripts are enabled
• Displays security warning message
• Installation proceeds only when --ignore-scripts flag is used

Test Script Placeholder

Provides a minimal test script that always passes for package validation.

{
  "scripts": {
    "test": "exit 0"
  }
}

Behavior:

• Always exits with code 0 (success)
• Satisfies npm package requirements for test scripts
• No actual testing functionality

Security Model

Protection Mechanism

The package implements a fail-safe security model:

1. Default Denial: All npm script execution is blocked by default
2. Explicit Override: Developers must use --ignore-scripts to proceed
3. Conscious Choice: Forces awareness of script execution risks
4. Integration Ready: Works with selective script whitelisting tools

Installation Workflow

# Step 1: Attempt normal installation (fails)
npm install
# Output: Error message and exit code 1

# Step 2: Install with scripts disabled (succeeds)  
npm install --ignore-scripts

# Step 3: Use selective script execution (recommended)
npx @lavamoat/allow-scripts setup

Configuration Integration

Recommended .npmrc configuration:

enable-scripts=false

Recommended .yarnrc.yml configuration:

enableScripts: false

Environment Requirements

• Node.js: ^16.20.0 || ^18.0.0 || ^20.0.0 || ^22.0.0 || ^24.0.0
• Package Managers: npm, yarn, pnpm (any version)
• Dependencies: None (self-contained)

Integration Patterns

Project Security Setup

{
  "dependencies": {
    "@lavamoat/preinstall-always-fail": "^2.1.1",
    "@lavamoat/allow-scripts": "^3.0.0"
  }
}

CI/CD Integration

# GitHub Actions example
- name: Install dependencies safely
  run: npm install --ignore-scripts

- name: Setup allowed scripts
  run: npx @lavamoat/allow-scripts setup

Error Handling

Installation Failure

When scripts are enabled, installation fails with:

• Exit Code: 1
• Error Message: "Don't run npm lifecycle scripts by default! Create a .yarnrc or .npmrc and set enableScripts: false. Then, whitelist them with @lavamoat/allow-scripts"
• Resolution: Add --ignore-scripts flag or configure package manager to disable scripts by default

No Programmatic Errors

This package throws no runtime errors as it provides no programmatic API. All errors occur during package installation phase only.