• X
• Mastodon
• Reddit
• LinkedIn

• Validate lockfile-provided hoisted aliases to prevent traversal and reserved-name clobbering.
• Harden pnpm patch-remove to only unlink files contained within the configured patches directory.
• Validate workspace configDependencies names and versions before building any filesystem paths.

graph TD
  W[/"pnpm-workspace.yaml"/] --> C["@pnpm/config.deps-installer"] --> V["Path validation utils"] --> S[("pnpm store")]
  L[/"pnpm-lock.yaml"/] --> H["@pnpm/headless hoisted graph"] --> V --> F["Project FS (node_modules, patches)"]
  P["pnpm patch-remove"] --> V --> F
  subgraph Legend
    direction LR
    _in[/"Input config/lockfile"/] ~~~ _mod["Module/command"] ~~~ _db[("On-disk storage")]
  end

Loading

The following are alternative approaches to this PR:

1. Lockfile-wide verifier gate for hoisted installs

• ➕ Centralizes policy enforcement and can report all violations at once
• ➕ Keeps graph-building code simpler by separating validation from execution
• ➖ v10 lacks upstream gating hooks (as noted), increasing backport complexity
• ➖ Easy to miss secondary sinks unless every consumer routes through the verifier

2. Generic path-segment sanitizer (not npm-name based)

• ➕ Can be reused for non-package-name segments beyond aliases/config deps
• ➕ Potentially fewer new dependencies (no validate-npm-package-name)
• ➖ Harder to precisely capture npm’s reserved/legacy name rules
• ➖ Risk of allowing visually safe but semantically dangerous names (e.g., reserved layout names)

3. Filesystem-only containment via realpath on all joins

• ➕ Robust against some normalization quirks and platform-specific path behavior
• ➕ Doesn’t require semantic validation of the string
• ➖ Requires filesystem access (not always available at validation time)
• ➖ Realpath can follow symlinks and needs careful handling to avoid TOCTOU issues

Recommendation: The PR’s approach (validate at the path-construction/unlink “sinks” with npm-name/semver rules plus containment checks) is the best fit for a v10 backport: it protects both lockfile-driven and config-driven flows before any filesystem effects occur, and it keeps the security boundary close to the dangerous operations. The added safeJoinModulesDir export and targeted chokepoints (normalizeConfigDeps, hoisted graph join, patch-remove batch validation) make it less likely a new caller bypasses protections.

Enhancement (2) +18 / -0

index.tsExport safeJoinModulesDir helper +1/-0

Export safeJoinModulesDir helper

• Exports 'safeJoinModulesDir' for reuse by other packages (notably headless hoisted graph building) as a common safe path sink.

fs/symlink-dependency/src/index.ts

isSubdirectory.tsAdd reusable subdirectory containment helper +17/-0

Add reusable subdirectory containment helper

• Introduces 'isSubdirectory' to robustly determine whether a resolved path is within a parent directory, including Windows escape considerations.

patching/plugin-commands-patching/src/isSubdirectory.ts

Bug fix (6) +197 / -20

assertValidConfigDepName.tsIntroduce config dependency name validator +20/-0

Introduce config dependency name validator

• Adds 'assertValidConfigDepName' to reject invalid/reserved/traversal-like names (including '__proto__') before any install-time paths are built.

config/deps-installer/src/assertValidConfigDepName.ts

assertValidConfigDepVersion.tsIntroduce config dependency version validator +15/-0

Introduce config dependency version validator

• Adds 'assertValidConfigDepVersion' to require exact semver versions so versions cannot be used as traversal-shaped store path segments.

config/deps-installer/src/assertValidConfigDepVersion.ts

normalizeConfigDeps.tsValidate configDependencies before normalization +7/-0

Validate configDependencies before normalization

• Calls the new name/version assertions during normalization so invalid inputs fail early, before registry/store paths are derived.

config/deps-installer/src/normalizeConfigDeps.ts

safeJoinModulesDir.tsReject invalid/reserved aliases before joining under node_modules +27/-9

Reject invalid/reserved aliases before joining under node_modules

• Adds npm package-name validation to 'safeJoinModulesDir' and improves error construction while retaining the existing resolved-path containment check.

fs/symlink-dependency/src/safeJoinModulesDir.ts

patchRemove.tsContain patch-remove unlinking to the patches directory +126/-10

Contain patch-remove unlinking to the patches directory

• Refactors removal into a validated batch that rejects traversal, directory entries, and nested symlink escapes, and unlinks patch files without following symlinks before updating config and re-installing.

patching/plugin-commands-patching/src/patchRemove.ts

lockfileToHoistedDepGraph.tsUse safeJoinModulesDir for hoisted alias directories +2/-1

Use safeJoinModulesDir for hoisted alias directories

• Routes the hoisted 'dep.name' directory construction through 'safeJoinModulesDir' instead of raw 'path.join' to block traversal/reserved aliases from lockfiles.

pkg-manager/headless/src/lockfileToHoistedDepGraph.ts

Tests (5) +371 / -1

installConfigDeps.tsAdd regression tests for traversal name/version and __proto__ +76/-0

Add regression tests for traversal name/version and proto

• Extends install tests to assert invalid config dependency names/versions are rejected and do not create sentinel files in the project or store directories.

config/deps-installer/test/installConfigDeps.ts

safeJoinModulesDir.test.tsTest reserved alias rejections and valid alias acceptance +24/-1

Test reserved alias rejections and valid alias acceptance

• Expands invalid alias coverage to include '.bin', '.pnpm', and 'node_modules', and adds positive cases for valid package-name aliases.

fs/symlink-dependency/test/safeJoinModulesDir.test.ts

isSubdirectory.test.tsAdd unit tests for isSubdirectory (POSIX and Windows) +19/-0

Add unit tests for isSubdirectory (POSIX and Windows)

• Covers accepted in-tree paths and rejected traversal/sibling/drive/UNC escape cases using 'path.win32' where relevant.

patching/plugin-commands-patching/test/isSubdirectory.test.ts

patchRemove.test.tsAdd patch-remove containment and symlink regression tests +166/-0

Add patch-remove containment and symlink regression tests

• Verifies patch-remove rejects unsafe targets before deletion, handles directory targets, avoids nested-symlink escapes, unlinks final symlinks without touching targets, and treats missing files as no-ops.

patching/plugin-commands-patching/test/patchRemove.test.ts

lockfileToHoistedDepGraph.test.tsAdd exploit-regression tests for hoisted alias validation +86/-0

Add exploit-regression tests for hoisted alias validation

• Adds tests ensuring crafted lockfiles with traversal/reserved aliases are rejected before any store fetch/filesystem work and do not create escaped paths.

pkg-manager/headless/test/lockfileToHoistedDepGraph.test.ts

Documentation (3) +21 / -0

config-deps-path-traversal.mdAdd changeset documenting configDependencies traversal fix +6/-0

Add changeset documenting configDependencies traversal fix

• Introduces a release note describing validation of config dependency names and versions to prevent path traversal into node_modules/store paths.

.changeset/config-deps-path-traversal.md

contain-hoisted-dependency-aliases.mdAdd changeset for hoisted alias containment hardening +9/-0

Add changeset for hoisted alias containment hardening

• Documents rejection of traversal-shaped and reserved hoisted aliases originating from lockfiles and the use of 'safeJoinModulesDir' as the enforcement point.

.changeset/contain-hoisted-dependency-aliases.md

fix-patch-remove-containment.mdAdd changeset for patch-remove containment fix +6/-0

Add changeset for patch-remove containment fix

• Adds a release note stating that 'pnpm patch-remove' is prevented from deleting files outside the configured patches directory.

.changeset/fix-patch-remove-containment.md

Other (3) +28 / -4

package.jsonAdd semver and npm-name validation dependencies +5/-1

Add semver and npm-name validation dependencies

• Adds 'semver' and 'validate-npm-package-name' plus corresponding type packages to support config dependency name/version validation.

config/deps-installer/package.json

package.jsonAdd validate-npm-package-name dependency for alias checking +4/-2

Add validate-npm-package-name dependency for alias checking

• Adds 'validate-npm-package-name' (and types) so symlink placement can enforce npm-valid aliases beyond simple containment checks.

fs/symlink-dependency/package.json

pnpm-lock.yamlLockfile updates for new validation dependencies +19/-1

Lockfile updates for new validation dependencies

• Updates the workspace lockfile to include 'semver', 'validate-npm-package-name', and related type packages used by the new validation logic.

pnpm-lock.yaml

Description

The safeJoinModulesDir() doc comment claims the joined alias path stays a “direct child” of
modulesDir, but the function intentionally accepts scoped names like "@scope/name" which create
nested directories under node_modules. This mismatch can mislead future changes/reviewers about what
the function actually guarantees (containment, not depth).

Code

fs/symlink-dependency/src/safeJoinModulesDir.ts[R5-8]

+// Joins `modulesDir` with a dependency alias and guarantees the result
+// stays a direct child of `modulesDir`. The alias becomes a directory
+// name inside `node_modules`, so it must be a valid npm package name: a
+// single `name` or `@scope/name` of URL-friendly characters with no

Evidence

The implementation comment states “direct child”, but tests explicitly treat @scope/name as a
valid alias, which produces a nested path under modulesDir (modulesDir/@scope/name) rather than
a direct child directory.

fs/symlink-dependency/src/safeJoinModulesDir.ts[5-14]
fs/symlink-dependency/test/safeJoinModulesDir.test.ts[48-58]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`safeJoinModulesDir()` documentation says the result stays a *direct child* of `modulesDir`, but the implementation allows scoped package aliases (e.g. `@scope/name`), which are necessarily nested under `node_modules/@scope/name`.

### Issue Context
This is purely a comment/documentation mismatch (runtime behavior is correct), but the function is now used as a security boundary and is exported, so accurate guarantees matter.

### Fix Focus Areas
- fs/symlink-dependency/src/safeJoinModulesDir.ts[5-13]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

assertValidConfigDepVersion() claims config dependency versions must be “an exact semver version”
but only checks semver.valid(version) != null, and normalizeConfigDeps() continues using the
original (non-canonical) version string for tarball/ID construction. This can produce inconsistent
version strings compared to other pnpm code that uses the canonicalized semver.valid() return value
when it requires exact versions.

Code

config/deps-installer/src/assertValidConfigDepVersion.ts[R7-9]

+export function assertValidConfigDepVersion (name: string, version: string): void {
+  if (semver.valid(version) == null) {
+    throw new PnpmError(

Evidence

The new validator only checks non-null return from semver.valid, while normalizeConfigDeps uses the
unmodified extracted version to build resolution/tarball fields. Elsewhere in the repo,
semver.valid’s return value is treated as the canonical version string, indicating a mismatch
between the “exact version” claim and this implementation.

config/deps-installer/src/assertValidConfigDepVersion.ts[7-14]
config/deps-installer/src/normalizeConfigDeps.ts[20-50]
config/version-policy/src/index.ts[80-89]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`assertValidConfigDepVersion()` currently validates with `semver.valid(version) != null` but does not enforce that the provided string is already in canonical/exact semver form, despite the error hint stating “must be an exact semver version”. Additionally, callers continue using the raw `version` string.
### Issue Context
Other parts of the repo treat `semver.valid()` as a canonicalizer by using its return value, which suggests the intent for “exact versions” is to work with normalized strings.
### Fix Focus Areas
- config/deps-installer/src/assertValidConfigDepVersion.ts[7-14]
- config/deps-installer/src/normalizeConfigDeps.ts[20-50]
### Suggested fix approach
- Option A (strict): change validation to require `semver.valid(version) === version` (and throw otherwise) so the error message matches behavior.
- Option B (normalize): change the validator to return the canonical version string (e.g. `const v = semver.valid(version)!`) and update `normalizeConfigDeps()` to use that returned value for `deps[pkgName].version` and for `getNpmTarballUrl()` / package IDs.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)