ADR 0012: npm is the unmodified release, fetched and verified on first use

  • Status: accepted (2026-10-21)
  • Context: The project runs the real, unmodified npm on the Node-compat layer. Node ships npm inside its distribution, at <prefix>/lib/node_modules/npm. ClientVM has no install step and ships no Node distribution. npm is about 2.9 MB gzipped and 12.5 MB unpacked (2,160 files). That is too large to put in the sandbox-host bundle or in every new instance’s file tree.
  • Decision:
    • npm and npx are runtimes: npmRuntime in @clientvm/node-compat. Each instance has marker files for them on PATH.
    • On first use in an instance, the runtime does the following:
      1. It downloads the pinned release npm@11.6.1 from the registry. This is the release Node 24.11 bundles.
      2. It checks the tarball’s SHA-512 integrity against the value pinned in the source.
      3. It unpacks the tarball into a staging directory. A tar reader in node-compat does this; the same reader also backs the shell’s tar command.
      4. It renames the staging directory to /usr/local/lib/node_modules/npm, so a half-written copy is never used.
      5. It then runs bin/npm-cli.js (or npx-cli.js) on the node runtime with the user’s arguments.
    • Later runs use the unpacked copy. Persisted instances keep it through OPFS, and forks keep it through CoW. The download goes through the browser’s HTTP cache, which instances of one site share.
    • CLIENTVM_NPM_TARBALL overrides the download URL, for mirrors and offline tests. The integrity check still applies to the override.
    • npm’s code is not patched. Every gap it hit was fixed in node-compat instead:
      • readline
      • http2 constants
      • v8 heap statistics
      • a main-thread worker_threads
      • path.win32
      • configurable fs.ReadStream
      • EventEmitter alias identity
      • util.debuglog
      • liveness while import() loads
  • Consequences:
    • The first npm call in an instance costs about 1 s of network plus unpacking. npm install of Express and cowsay (110 packages) takes about 11 s cold, and npm ci from the lockfile about 3 s.
    • Upgrading npm means changing two pinned constants and re-running the e2e suite.
    • Lifecycle scripts run as they would in Node: they are spawned through /bin/sh in the instance. Package code is hostile by assumption (docs/security.md); the instance boundary contains it.
    • Without network access, npm cannot run until the tarball is reachable or provided through the override.

Edit this page on GitHub ↗Markdown