1---
2name: pnpm-supply-chain-security
3description: Build-script approval (allowBuilds), minimum release age, trust policy, and exotic-subdep blocking for safer installs
4---
5 
6# pnpm Supply-Chain Security
7 
8pnpm blocks several attack vectors by default. Agents installing dependencies must understand these, since installs can fail or prompt on them.
9 
10## Build-script approval (allowBuilds)
11 
12By default pnpm does **not** run dependency lifecycle scripts (`preinstall`/`install`/`postinstall`). Packages must be explicitly approved. Approval lives in one `allowBuilds` map in `pnpm-workspace.yaml`.
13 
14```yaml title="pnpm-workspace.yaml"
15allowBuilds:
16  esbuild: true
17  core-js: false
18  # version selectors are supported
19  [email protected] || 21.6.5: true
20```
21 
22- Packages **not listed** are unreviewed and blocked by default.
23- `strictDepBuilds: true` (default) ⇒ unreviewed builds make install exit non-zero (`ERR_PNPM_IGNORED_BUILDS`). Set `false` to warn instead.
24- During install, unreviewed packages with build scripts are auto-added to `pnpm-workspace.yaml` with a placeholder so you can set `true`/`false`.
25 
26> `allowBuilds` replaces the removed `onlyBuiltDependencies`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, `onlyBuiltDependenciesFile`, and `ignoreDepScripts`.
27 
28### Approving builds
29 
30```bash
31pnpm approve-builds            # interactive prompt
32pnpm approve-builds --all      # approve all pending
33pnpm approve-builds esbuild fsevents !core-js   # ! = deny
34pnpm add --allow-build=esbuild my-bundler       # approve while adding
35pnpm add -g --allow-build=esbuild esbuild       # global (replaces approve-builds -g)
36```
37 
38### Escape hatch (dangerous)
39 
40```yaml title="pnpm-workspace.yaml"
41dangerouslyAllowAllBuilds: true   # runs ALL build scripts now and in the future — avoid
42```
43 
44## Minimum release age
45 
46Delay installing freshly published versions so malicious releases (usually pulled within an hour) are avoided. Applies to **all** deps, including transitive.
47 
48```yaml title="pnpm-workspace.yaml"
49minimumReleaseAge: 1440          # minutes; default 1440 (1 day) since v11
50minimumReleaseAgeExclude:        # always install newest of these immediately
51  - webpack
52  - '@myorg/*'
53  - [email protected]                    # exempt a specific version
54```
55 
56- `minimumReleaseAgeStrict` — when no in-range version satisfies the age, fail (default when you set `minimumReleaseAge` yourself) vs. fall back.
57- `minimumReleaseAgeIgnoreMissingTime` — skip the check for registries that omit the `time` field (default `true`).
58 
59## Trust policy
60 
61Fail if a package's trust level **decreased** vs earlier releases (e.g. was published by a trusted publisher, now only has provenance or nothing).
62 
63```yaml title="pnpm-workspace.yaml"
64trustPolicy: no-downgrade        # off (default) | no-downgrade
65trustPolicyExclude:
66  - '[email protected]'
67trustPolicyIgnoreAfter: 525600   # ignore the check for pkgs published > N minutes ago
68```
69 
70## Block exotic transitive sources
71 
72```yaml title="pnpm-workspace.yaml"
73blockExoticSubdeps: true   # default
74```
75 
76When `true`, only **direct** dependencies may use exotic sources (git repos, direct tarball URLs); all transitive deps must come from a trusted source (registry, local path, workspace link, or trusted GitHub repos).
77 
78## Lockfile integrity
79 
80Since v11, a downloaded tarball whose hash doesn't match `pnpm-lock.yaml` is a hard error (`ERR_PNPM_TARBALL_INTEGRITY`) — protecting committed lockfiles from a compromised registry/proxy. `--force` and `pnpm update` do **not** bypass it.
81 
82```bash
83pnpm install --update-checksums   # narrow opt-in after verifying the new bytes
84```
85 
86## Trusted store/cache
87 
88The content-addressable store, global virtual store, and metadata cache are part of pnpm's trust domain. Share them only between mutually trusting users/jobs and protect with filesystem permissions. `verifyStoreIntegrity` (default `true`) detects accidental corruption but does not make a writable-by-untrusted store safe.
89 
90## Key Points
91 
92- Dependency build scripts are blocked until approved via `allowBuilds` / `pnpm approve-builds`; unreviewed builds fail by default (`strictDepBuilds`).
93- `minimumReleaseAge` (default 1 day in v11) delays new releases; `trustPolicy: no-downgrade` blocks trust regressions; `blockExoticSubdeps` limits transitive git/tarball sources.
94- Tarball integrity mismatches are fatal; use `--update-checksums` only after verification.
95- Treat the store/cache as trusted shared state.
96 
97<!--
98Source references:
99- https://pnpm.io/settings#allowbuilds
100- https://pnpm.io/cli/approve-builds
101- https://pnpm.io/settings#minimumreleaseage
102- https://pnpm.io/settings#trustpolicy
103- https://pnpm.io/settings#blockexoticsubdeps
104- https://pnpm.io/supply-chain-security
105-->
106