0
# LavaMoat Preinstall Always Fail
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @lavamoat/preinstall-always-fail
7
- **Package Type**: npm  
8
- **Language**: JavaScript (npm lifecycle scripts)
9
- **Installation**: `npm install @lavamoat/preinstall-always-fail`
10

11
## Core Installation
12

13
Add to your project's dependencies:
14

15
```json
16
{
17
  "dependencies": {
18
    "@lavamoat/preinstall-always-fail": "^2.1.1"
19
  }
20
}
21
```
22

23
## Basic Usage
24

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

27
```bash
28
# This will fail with an error message
29
npm install
30

31
# This will succeed - scripts are ignored 
32
npm install --ignore-scripts
33

34
# This will also succeed
35
yarn install --ignore-scripts
36
```
37

38
When installation is attempted without `--ignore-scripts`, the package fails with this message:
39
```
40
Don't run npm lifecycle scripts by default! Create a .yarnrc or .npmrc and set enableScripts: false. Then, whitelist them with @lavamoat/allow-scripts
41
```
42

43
## Architecture
44

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

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

52
## Capabilities
53

54
### Preinstall Security Gate
55

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

58
```json { .api }
59
{
60
  "scripts": {
61
    "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"
62
  }
63
}
64
```
65

66
**Behavior:**
67
- Executes automatically during `npm install` or `yarn install`
68
- Always exits with code 1 (failure) when scripts are enabled
69
- Displays security warning message
70
- Installation proceeds only when `--ignore-scripts` flag is used
71

72
### Test Script Placeholder
73

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

76
```json { .api }
77
{
78
  "scripts": {
79
    "test": "exit 0"
80
  }
81
}
82
```
83

84
**Behavior:**
85
- Always exits with code 0 (success)
86
- Satisfies npm package requirements for test scripts
87
- No actual testing functionality
88

89
## Security Model
90

91
### Protection Mechanism
92

93
The package implements a fail-safe security model:
94

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

100
### Installation Workflow
101

102
```bash
103
# Step 1: Attempt normal installation (fails)
104
npm install
105
# Output: Error message and exit code 1
106

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

110
# Step 3: Use selective script execution (recommended)
111
npx @lavamoat/allow-scripts setup
112
```
113

114
### Configuration Integration
115

116
Recommended `.npmrc` configuration:
117

118
```ini
119
enable-scripts=false
120
```
121

122
Recommended `.yarnrc.yml` configuration:
123

124
```yaml
125
enableScripts: false
126
```
127

128
## Environment Requirements
129

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

134
## Integration Patterns
135

136
### Project Security Setup
137

138
```json
139
{
140
  "dependencies": {
141
    "@lavamoat/preinstall-always-fail": "^2.1.1",
142
    "@lavamoat/allow-scripts": "^3.0.0"
143
  }
144
}
145
```
146

147
### CI/CD Integration
148

149
```yaml
150
# GitHub Actions example
151
- name: Install dependencies safely
152
  run: npm install --ignore-scripts
153

154
- name: Setup allowed scripts
155
  run: npx @lavamoat/allow-scripts setup
156
```
157

158
## Error Handling
159

160
### Installation Failure
161

162
When scripts are enabled, installation fails with:
163

164
- **Exit Code**: 1
165
- **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"
166
- **Resolution**: Add `--ignore-scripts` flag or configure package manager to disable scripts by default
167

168
### No Programmatic Errors
169

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