Skip to content

Declare hosted pnpm pins as named registries instead of trusting the lock - #2167

Draft
Mikola Lysenko (mikolalysenko) wants to merge 2 commits into
mainfrom
mik/pnpm-named-registry
Draft

Mikola Lysenko (mikolalysenko) wants to merge 2 commits into
mainfrom
mik/pnpm-named-registry

Conversation

@mikolalysenko

@mikolalysenko Mikola Lysenko (mikolalysenko) commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

LLM Description written by Claude Code:claude-fable-5-2

Summary

Hosted mode repoints pnpm-lock.yaml entries at the patch server. pnpm 11.10 and later check every lock entry that records a tarball URL against a registry and refuse the lock when the registry does not list that URL, so the scan has been writing trustLockfile: true to pnpm-workspace.yaml. That turns the check off for every entry in the lock, not only the patched ones.

The patch service can now serve each npm patch under its own one-package registry. The package reference result carries its address in a new optional field, npmRegistryUrl (the directory of the tarball URL), and GET <address><name> answers a version document that lists the tarball. pnpm verifies a lock entry against the named registry whose address its tarball URL starts with, so the scan now declares one per hosted pin instead of trusting the whole lock:

namedRegistries:
  socket-patch-<patch uuid>: <address>

No trustLockfile is written, and pnpm's verification stays on for every entry.

When the scan takes this path

All of these must hold. Otherwise the run is exactly what it was before (a half-covered lock would fail to install):

  • A governing 9.0 lock, not Rush, not legacy, and not a workspace member whose settings live in an ancestor file.
  • Every hosted tarball in the governing locks has a registry. Either a grant of this run that carries a usable address (http(s), ends in /, a prefix of the artifact URL), or a socket-patch-<uuid> entry already in the file from an earlier run.
  • The project's pnpm pins prove pnpm 12 or newer. At least one pin among packageManager, devEngines.packageManager, engines.pnpm and the installed node_modules/.modules.yaml, and every pin present admits nothing below 12 (12.4.2, ^12, >=12.4, 12 || 13). A range that reaches below 12, an unparseable pin or pins that disagree stay on trustLockfile.

A project with no pin at all also stays on trustLockfile, and its warning gains one sentence saying that pinning pnpm 12 or later and re-running the scan switches it to per-package registry verification.

Why pnpm 12 only

Frozen installs pass with namedRegistries on every release tried from 11.10.0 through 12.22.0. The gate is about pnpm add. Measured on a lock with three hosted entries, then pnpm add is-odd@3.0.1:

pnpm trustLockfile: true namedRegistries
11.10.0, 11.20.0, 11.25.0 hosted entries dropped hosted entries dropped
11.28.13 kept dropped
12.0.0, 12.4.2, 12.10.0, 12.22.0 kept kept

So a named registry costs nothing only from pnpm 12 on.

The workspace edit

A line splice in a new module, formats::pnpm::named_registries, never a YAML round trip:

  • No file: created with the root-only packages scaffold. A keyless file gets the scaffold with the map.
  • Otherwise the map, or its missing entries, are spliced in at the map's own indent and in the file's line ending. The user's own registries stay byte for byte.
  • An alias of ours at another address is repointed. One whose patch no governing lock names any more is removed.
  • A shape a splice would corrupt (a flow-style map, several documents) is refused, and the warning prints the lines to add with the grant token redacted.
  • --no-trust-lockfile-config, dry runs, Rush, legacy locks, a keyless file with workspace members, and an unreadable or symlinked file are respected the way the trust write respects them.
  • A pnpm_config_trust_lockfile variable or a trustLockfile: false blocks nothing here, since the declarations do not need trust.

An existing trustLockfile: true

  • Removed in the same run only when the file's bytes prove an earlier run wrote it: the file is exactly what the trust auto-config creates, or a keyless file plus the lines it splices. These are the proofs the upstream restore already uses.
  • Left alone in any other file, since nothing proves who wrote it. The warning says the hosted patches no longer need it.

Rollback

rollback, remove and a hosted to vendored takeover take each alias back out once no governed lock names its patch. A file left exactly as the run created it is deleted, and a user's file gets its bytes back. The edits are recorded under redirect_pnpm_workspace_named_registry; the warning keeps the code redirect_pnpm_trust_lockfile.

Backend dependency

Needs the matching change in Socket's backend (the npmRegistryUrl field and the version document). Against a patch service without it the field is absent and nothing changes: verified against such a service, the scan wrote trustLockfile: true as before.

Testing

TEST_RESULTS_PLACEHOLDER

End-to-end run against a patch service that serves the registry

Run with a build of this branch and real pnpm 12.22.0, on a project pinned to pnpm 12 with one unscoped and one scoped patched package:

  • The scan wrote two namedRegistries entries and no trustLockfile.
  • Each registry's version document lists exactly the tarball URL and integrity the lock pins (the scoped one requested as @scope%2Fname), and answers 404 for any other package name.
  • pnpm install --frozen-lockfile with a fresh store passed pnpm's lockfile verification and installed the patched files.
  • The same lock without the workspace file failed with ERR_PNPM_TARBALL_URL_MISMATCH.

Known limitation found in that run: pnpm add and peer dependencies

This contradicts the table above for one class of package, and the docs and a code comment in this PR still state the older claim. On pnpm 12.19.0 and later, with named registries and no trustLockfile, pnpm add re-resolves a hosted entry to the upstream tarball when the patched package has peer dependencies in its subtree (its own peerDependencies, or a dependency that has them). trustLockfile: true keeps the entry.

Measured with pnpm add after a frozen install, hosted package with a peer-dependent child:

pnpm trustLockfile: true namedRegistries
12.0.0, 12.4.2, 12.10.0, 12.16.0 kept kept
12.19.0, 12.21.0, 12.22.0 kept (12.22.0) dropped

On 12.22.0 a package with no peer dependencies in its subtree is kept under both, with or without ordinary dependencies, scoped or not; so is a package that only provides a peer.

So the pnpm 12 gate alone is not enough. Until that is resolved this stays a draft. The options are to also require that no hosted pin has peer dependencies in its subtree, or to route resolution itself through the registry with overrides, which needs the version document to carry the package's real dependency fields.

Not verified

  • Scoped and peer-dependent packages through the in-repo real-pnpm test. The cases above were run by hand.
  • Windows and Linux. The real-pnpm leg ran on macOS only; CI runs it on all three.
  • /code-review high has not been run yet.

Generated by Claude Code

…lock

pnpm >= 11 checks every lock entry that records a tarball URL against a
registry, so hosted mode has been writing `trustLockfile: true` to
pnpm-workspace.yaml, which switches that check off for the whole lock.

The patch service can now serve each npm patch under its own one-package
registry: the reference result carries its address in `npmRegistryUrl`
(the tarball URL's directory), and `GET <address><name>` answers a
version document that names the tarball. pnpm verifies a lock entry
against the named registry whose address its tarball URL starts with, so
the scan now declares one per hosted pin of the governing 9.0 locks,

    namedRegistries:
      socket-patch-<patch uuid>: <address>

and writes no `trustLockfile`: verification stays on for every entry.

The run takes this path only when both hold, and is otherwise exactly
what it was (a lock half covered would fail to install):

- every Socket-hosted tarball the governing locks record has a registry:
  a grant of this run that carries a usable address (http(s), ending in
  `/`, a prefix of the artifact URL; anything else reads as not served),
  or a `socket-patch-<uuid>` entry already in the file (a pin an earlier
  run left);
- every pnpm pin of the project (package.json `packageManager`,
  `devEngines.packageManager`, `engines.pnpm`, the installed
  node_modules/.modules.yaml; at least one present) names pnpm 12 or
  newer. pnpm 11 re-resolves a registry-verified entry on `pnpm add`,
  which drops the patch, where 11.28 keeps one under `trustLockfile`.

The workspace edit is a line splice (formats::pnpm::named_registries):
the file is created with the root-only `packages` scaffold, a keyless
file gets the scaffold with the map, and otherwise the map or its
missing entries are spliced in at the map's own indent, in the file's
line ending. The user's own registries stay byte for byte, an alias of
ours at another address is repointed, one whose patch no governing lock
names is removed, and a shape a splice would corrupt is refused with the
lines to add (grant token redacted, as everywhere else in the output).
`--no-trust-lockfile-config`, dry runs, Rush, legacy locks, a keyless
file with workspace members, an unreadable or symlinked file are
respected as the trust write respects them. A `pnpm_config_trust_lockfile`
variable or a `trustLockfile: false` blocks nothing here.

A `trustLockfile: true` an earlier run wrote is removed in the same run
when the file's bytes prove that run wrote it (the file it creates, or a
keyless file plus the lines it splices: the proofs the upstream restore
already uses, since v5 keeps no ledger). Any other one is left, and the
warning says the hosted patches no longer need it.

`rollback`, `remove` and a hosted -> vendored takeover take each alias
back out once no governed lock names its patch, one patch at a time; a
file left as the run created it is deleted, and a user's file gets its
bytes back.

The edits are recorded under `redirect_pnpm_workspace_named_registry`.
The warning keeps the code `redirect_pnpm_trust_lockfile`.

Tests: the workspace planner and its unwind (CRLF, comments, a user's
map, refusals, idempotence, stale aliases), the engine's choice between
the two settings, in-process scans and rollbacks, and a real pnpm 12 leg
that installs from a clean checkout with the default registry
unreachable, runs `pnpm add`, and fails without the declaration.

Needs a matching change in Socket's backend (the `npmRegistryUrl` field
and the version document); against a patch service without it nothing
changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Named registries are declared only on proof of pnpm 12 or newer. A
range pin now proves it when the lowest version it admits is 12.0 or
higher (`>=12`, `>=12.4 <14`, `12 || 13`, `12.0.0 - 13.0.0`), not only
an exact, caret, tilde or wildcard pin. `>=11`, a range the reader
cannot follow and pins that disagree still prove nothing.

A project with no pnpm pin at all stays on `trustLockfile` as before.
When every hosted pin has a registry, so the missing pin is the only
thing keeping it there, the warning adds one sentence: pinning pnpm 12
or later and re-running the scan switches the project to per-package
registry verification. A run against a patch service that serves no
registry is unchanged, byte for byte, and reads no lock for the
question.

docs/testing/pnpm-compatibility.md records the `pnpm add` measurement
behind the gate (pnpm 11.10 to 12.22 under both settings), and that the
registry's version document is dated by the upstream release, so pnpm's
default `minimumReleaseAge` does not hold back a new patch.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants