solidity loader: resolve @-scoped imports via Node-style walk-up

The hardcoded `node_modules/<spec>` fallback couldn't see monorepos,
didn't verify the package existed, and accepted `..` segments verbatim
(letting a malicious solidity source read sibling files).

Replace it with `resolveNodeModulesSpec(baseDir, specifier)`:
- splits `@scope/pkg/sub/path` correctly
- walks up from baseDir looking for `<dir>/node_modules/<pkg>/package.json`
- rejects `..` in the subpath
- rejects resolutions outside baseDir (the Bundle layer can't store them)

`resolveSolImport` is pure again. The Node fallback is applied at both
call sites (`collectSolidityFilesFromDisk` already has baseDir;
`buildSolidityTree` now accepts it as an option, threaded through from
`buildSolidityBundle`).

Author: claude

src/cmd/bundle.js

@@ -92,7 +92,7 @@ export async function buildSolidityBundle({ cwd = process.cwd(), entries, mappin
   const normalized = normalizeEntries(entries, cwd)
 
   const sources = await collectSolidityFilesFromDisk(baseDir, normalized, remappings)
-  const { resolutions, missing } = buildSolidityTree(sources, { remappings })
+  const { resolutions, missing } = buildSolidityTree(sources, { remappings, baseDir })
 
   // Bundles must be self-contained. Refuse to write one when an entry
   // can't be loaded from disk, or when any in-bundle file has an import

src/loaders/solidity.js

@@ -5,6 +5,7 @@
 // file (foundry.toml or remappings.txt) is read to extract `remappings`,
 // but is itself not included in `sources`.
 
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 
@@ -73,6 +74,41 @@ export function resolveSolImport(specifier, fromFile, remappings) {
   return null
 }
 
+// Node-style resolution for a bare `@scope/pkg/sub/path.sol` specifier:
+// walk up from `baseDir` looking for `<dir>/node_modules/<pkg>/package.json`
+// (matching Node's CJS resolution algorithm). Returns the file path
+// relative to `baseDir` (POSIX-style), or null when no such package is
+// found, when the subpath contains `..`, or when the package was found
+// outside `baseDir` (a parent monorepo's node_modules) and bundling it
+// would require an out-of-tree path the Bundle layer would reject.
+export function resolveNodeModulesSpec(baseDir, specifier) {
+  if (!specifier.startsWith('@')) return null
+  const parts = specifier.split('/')
+  if (parts.length < 3) return null // `@scope/pkg` alone has no file to load
+  const pkgName = parts.slice(0, 2).join('/')
+  const subParts = parts.slice(2)
+  // Path-traversal guard: a `..` in the subpath could escape the package
+  // directory (or even baseDir) once we hand the joined path to readFile.
+  if (subParts.includes('..')) return null
+  const subPath = subParts.join('/')
+  let dir = resolve(baseDir)
+  while (true) {
+    const pkgDir = join(dir, 'node_modules', pkgName)
+    if (existsSync(join(pkgDir, 'package.json'))) {
+      const abs = join(pkgDir, subPath)
+      const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
+      // The Bundle workspace bucket rejects file paths that start with
+      // `..`, so a package resolved at a parent's node_modules can't
+      // round-trip through the bundle even though Node could load it.
+      if (rel.startsWith('..') || isAbsolute(rel)) return null
+      return rel
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
 // Build the { sources, resolutions, missing } triple from a Map of
 // already-loaded Solidity sources (any key format — relative paths for
 // disk-loaded projects, `${address}/${cname}` for etherscan, etc.) plus
@@ -82,13 +118,17 @@ export function resolveSolImport(specifier, fromFile, remappings) {
 // `@openzeppelin/contracts/.../IERC20.sol` which is itself a stored
 // cname). `missing` lists every (spec, from) pair that could not be
 // resolved or that resolved to a file that wasn't loaded into `sources`.
-export function buildSolidityTree(sources, { remappings = [] } = {}) {
+export function buildSolidityTree(sources, { remappings = [], baseDir } = {}) {
   const resolutions = new Map()
   const missing = []
   for (const [path, content] of sources) {
     const specMap = new Map()
     for (const spec of extractSolImports(content)) {
       let resolved = resolveSolImport(spec, path, remappings)
+      // Node-style node_modules fallback for `@scope/pkg/...` specifiers
+      // when remappings/relative resolution didn't hit. Requires baseDir
+      // since we have to walk disk to find the package.
+      if (!resolved && baseDir) resolved = resolveNodeModulesSpec(baseDir, spec)
       if (resolved && !sources.has(resolved)) resolved = null
       // Verbatim fallback: many Solidity ecosystems (etherscan bundles,
       // hardhat flat layouts) ship `@openzeppelin/...` imports as literal
@@ -152,6 +192,7 @@ export async function collectSolidityFilesFromDisk(baseDir, entries, remappings)
       sources.set(relPath, content)
       for (const spec of extractSolImports(content)) {
         let resolved = resolveSolImport(spec, relPath, remappings)
+        if (!resolved) resolved = resolveNodeModulesSpec(baseDir, spec)
         if (!resolved && knownEntries.has(spec)) resolved = spec
         if (resolved) {
           if (!sources.has(resolved)) next.push(resolved)

tests/bundle-cmd.test.js

@@ -130,6 +130,23 @@ test('buildSolidityBundle places node_modules files in per-package modules bucke
   )
 })
 
+test('buildSolidityBundle resolves @-scoped imports via node_modules with no mapping file', async (t) => {
+  // No --mapping passed: @oz/contracts/utils/Math.sol must fall back to
+  // node_modules/@oz/contracts/utils/Math.sol on disk.
+  const cwd = join(fixtures, 'nm-fallback')
+  const bundle = await buildSolidityBundle({ cwd, entries: ['src/A.sol'] })
+  t.assert.deepEqual(
+    [...bundle.modules.keys()].toSorted(),
+    ['.', 'node_modules/@oz/contracts'],
+  )
+  t.assert.equal(bundle.modules.get('node_modules/@oz/contracts').name, '@oz/contracts')
+  t.assert.equal(bundle.modules.get('node_modules/@oz/contracts').version, '5.0.0')
+  t.assert.equal(
+    bundle.imports.get('solidity').get('src/A.sol').get('@oz/contracts/utils/Math.sol'),
+    'node_modules/@oz/contracts/utils/Math.sol',
+  )
+})
+
 test('buildSolidityBundle throws when a node_modules file has no resolvable package.json', async (t) => {
   await t.assert.rejects(
     () => buildSolidityBundle({

tests/fixtures/solidity-bundle/nm-fallback/node_modules/@oz/contracts/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "my-app",
+  "version": "0.1.0"
+}

tests/fixtures/solidity-bundle/nm-fallback/node_modules/@oz/contracts/utils/Math.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "@oz/contracts/utils/Math.sol";
+
+contract A {
+    function foo() public pure returns (uint256) {
+        return Math.max(1, 2);
+    }
+}

tests/fixtures/solidity-bundle/nm-fallback/package.json

@@ -11,6 +11,7 @@ import {
   parseRemappings,
   parseRemappingsFromToml,
   readRemappingsFile,
+  resolveNodeModulesSpec,
   resolveSolImport,
 } from '../src/loaders/solidity.js'
 
@@ -86,8 +87,41 @@ test('resolveSolImport picks the longest remapping prefix', (t) => {
   t.assert.equal(resolveSolImport('@oz/other.sol', 'src/A.sol', remappings), 'lib/oz/other.sol')
 })
 
-test('resolveSolImport returns null for non-relative, non-remapped imports', (t) => {
+test('resolveSolImport returns null for non-relative, non-remapped imports (no disk lookup)', (t) => {
+  // The pure resolver doesn't know about disk; the caller layers a
+  // resolveNodeModulesSpec fallback on top when baseDir is available.
   t.assert.equal(resolveSolImport('@unknown/Foo.sol', 'src/A.sol', []), null)
+  t.assert.equal(resolveSolImport('foo/X.sol', 'src/A.sol', []), null)
+})
+
+test('resolveNodeModulesSpec finds a scoped package at baseDir/node_modules and returns the subpath', (t) => {
+  const baseDir = join(fixtures, 'nm-fallback')
+  t.assert.equal(
+    resolveNodeModulesSpec(baseDir, '@oz/contracts/utils/Math.sol'),
+    'node_modules/@oz/contracts/utils/Math.sol',
+  )
+})
+
+test('resolveNodeModulesSpec returns null for unscoped specifiers (only `@scope/pkg/...` is supported)', (t) => {
+  t.assert.equal(resolveNodeModulesSpec(join(fixtures, 'nm-fallback'), 'foo/X.sol'), null)
+  t.assert.equal(resolveNodeModulesSpec(join(fixtures, 'nm-fallback'), 'X.sol'), null)
+})
+
+test('resolveNodeModulesSpec returns null for `@scope/pkg` with no file subpath', (t) => {
+  t.assert.equal(resolveNodeModulesSpec(join(fixtures, 'nm-fallback'), '@oz/contracts'), null)
+})
+
+test('resolveNodeModulesSpec rejects `..` in the subpath (path-traversal guard)', (t) => {
+  const baseDir = join(fixtures, 'nm-fallback')
+  t.assert.equal(resolveNodeModulesSpec(baseDir, '@oz/contracts/../../etc/passwd'), null)
+  t.assert.equal(resolveNodeModulesSpec(baseDir, '@oz/contracts/utils/../Math.sol'), null)
+})
+
+test('resolveNodeModulesSpec returns null when the package is not installed under baseDir', (t) => {
+  t.assert.equal(
+    resolveNodeModulesSpec(join(fixtures, 'nm-fallback'), '@absent/nope/X.sol'),
+    null,
+  )
 })
 
 test('resolveSolImport returns null when relative traversal escapes the root', (t) => {