fix(bundle): Solidity loader — decide file ownership by real path; invalid configs are errors

[exo-nikita]

Follow-up to #177's post-merge review, plus the reviews of this PR itself. Rebased onto main after #194 (Solidity bundles from soldeer.lock), so this PR uses @preventive/lockfile 1.0.0-alpha.4 (#193) for TOML (#183) and .gitmodules, and contains no --manifests redaction: carried files are included as written. The Solidity loader, the ownership walk included, reads the project through main's filesystem host (#189, #194), so a bundle built from a Vfs gets the same containment as one read from disk. I reproduced each finding before fixing it, and each has a regression test that fails on the base it fixes.

Ownership by real path

Whether a file belonged to a dependency used to be decided from its lexical path, with the real path checked only in some places. loaders/solidity-ownership.js now resolves each path once, one component at a time, and decides its owner from where the file really is. The same check is used by import resolution, the file walk, entries, --manifests (which files may be carried), forge's nested-config discovery, and the package.json files that decide which package a source belongs to.

• Dependencies: node_modules/<pkg> (and @scope/<pkg>), the entries of forge's libs (an absolute one by its real path), Soldeer's dependencies/, and git submodules. A symlinked lib/ entry counts as the dependency wherever it points. A file belongs to a dependency when its real path lies in one, however the path got there, so code reached through src/vendor -> ../lib/dep/src is the dependency's.

• A dependency's imports must land on its own files or another dependency's, never the project's.

• Links nobody trusted placed are never followed. This covers:

  • a symlink planted inside a dependency that leads out of it to anything but another dependency;
  • a symlink outside the project that leads back into it. Example: a dependency linked from elsewhere, lib/evil -> ../../shared/evil, that holds a link back to the project's .env.

  Following one of these is refused with the reason, whether it's reached as an import (including one routed by a dependency's remapping), an entry, a carried manifest, a package.json used to assign a package, or the dependency's own foundry.toml, extends base or remappings.txt.

• Checked against the OS: the link-by-link walk's result is compared with the host's own realpath: on disk, the OS's realpath(3), which gives the filesystem's own spelling. A path the two resolve differently is refused rather than trusted. So is one the walk can't resolve but the OS can, and one the OS can't resolve at all: a real path past PATH_MAX, or a link whose end it can't name, such as /proc/self/fd/0 or /dev/stdin on an open pipe. A path counts as missing only when nothing is there at all. A .. in a path is resolved by the OS from where the link leads, not textually. Link targets are split on the OS's separators only (on POSIX a \ is part of a name), and a target that isn't UTF-8 counts as unresolved, not missing.

• A dependency's config reaches only what the path from the root does. One found through an absolute or /proc/self/cwd lib is judged by its real path. A dependency outside the root reads nothing, and a directory a dependency's libs names must be a dependency itself (not the project's own directory passed off as one). A refused config says why, with the ownership reason.

• Case-insensitive filesystems: each path component takes the filesystem's own spelling, so LIB/evil is checked as lib/evil (tested by emulation, with a host that lowercases paths).

• .gitmodules is read once per bundle, with @preventive/lockfile's parseGitmodules, which reads it the way git's config parser does. A URL is taken as written (checkUrls: false): one relative to the superproject's remote (../x.git), a path, or none. Stasis only uses the URL to name a GitHub submodule's bucket, so such a submodule is still a dependency, just without a GitHub name.

• A .gitmodules the library refuses never fails the bundle, and never makes a submodule's directory the project's own code. It is warned about and read one submodule section at a time. This covers:

  • something git reads two ways: a key twice, or a second section;
  • something git reads but the library doesn't check: update = none, active, a [core] or [include] section, a tab in a value;
  • a [submodule.x] header, which is read the way git reads it, as [submodule "x"].

  Each submodule's first path, url and branch are kept, as git's submodule commands read them, and each is re-read by the library. A branch, then a URL, that still doesn't read is dropped with a warning. A submodule whose path doesn't read fails closed: if the path names a directory inside the repository (./deps/x, deps/x/), that directory is still a dependency, unnamed. Only a path outside the repository (../x) is skipped. So a planted link in such a directory, even outside forge's libs, stays refused.

• A .gitmodules git itself refuses is an error, as it is to git. That means any "bad config line":

  • a header such as [submodule x], [submodule.deps/x], or [submodule "x" with no ];
  • a key followed by something other than =;
  • a value with no closing quote, or an unknown escape.

  Reading past such a line could lose a submodule's section, and its directory would then count as the project's own code. The lenient read now follows git's config.c character by character and refuses exactly what git refuses. A differential fuzz against git config -f --list -z (16,000 files) matched git on every file, in both what's refused and the keys and values read.

• Links the project placed can point anywhere in the root. That covers a workspace package in node_modules, a linked lib/ entry, and a link on the path the project was opened by (a symlinked checkout).

Invalid input is an error

Each of these fails the bundle naming the file from the project root (or naming the variable), whether it's the project's, a dependency's, or read under --mapping. Nothing falls back to a default:

• TOML: a foundry.toml or extends base that isn't TOML.
• Not UTF-8: a .sol source, a .sol.txt listing, a foundry.toml, a remappings.txt, a --mapping file or a .gitmodules. They're decoded strictly with @exodus/bytes (now a direct dependency of stasis; stasis-core stays dependency-free), keeping a byte-order mark. Before, a .sol file was read with readFile(…, 'utf8'), which bundles a stray \xe9 as U+FFFD: text that isn't the file's.
• Not a regular file: config files are read only if they're regular files, and a package.json that isn't one is never read. A FIFO, a socket, a device, or a link to one (the project's own remappings.txt -> /dev/stdin) can't stall the bundle or feed it the process's input. A config path the host can't stat is read to learn why: only "nothing there" counts as no file, so a loop or an unsearchable directory is still an error.
• Wrong types: a mistyped src, test, script, libs, auto_detect_remappings or extends (for example libs = "deps").
• Remappings: a line or FOUNDRY_REMAPPINGS/DAPP_REMAPPINGS entry that isn't [context:]prefix=target, or a remappings value that isn't an array of such strings.
• package.json: one that decides a Solidity source's package but doesn't parse, isn't UTF-8, or isn't a regular file. A leading byte-order mark is skipped, as npm skips it. The error gives the file and position and never quotes the text, because the parser's own message would. Bash and Rust bundles, stasis add and JS --package-json still walk past a malformed one, as on main.

Forge refuses all of these too, except that it silently skips a dependency's foundry.toml it can't read. A dependency's config that forge rejects for its settings (a missing or nested extends, colliding keys, a link out of the dependency) is still skipped with a warning, as forge skips it. Only that class of error (ConfigRefused) is caught.

A remappings.txt line is trimmed the way forge trims it, so a byte-order mark stays part of the first remapping, as it does in forge.

--manifests

--manifests carries every config file the resolution read, whatever it's called (extends = "base.conf", --mapping=remaps). With --mapping that includes the root foundry.toml and its extends base, read for the lib dirs. It also carries the lock files and the package.json, foundry.toml and remappings.txt of each bundled package, all as written. A package.json is tagged json; every other file is a resource, including a --mapping=remaps.json. .env files and hardhat.config.* are never carried, however they're cased.

A config file is carried under its path in the project. It is carried under its real path instead when a .., or an absolute or /proc/self/cwd lib, leads somewhere else. So extends = "cfg/base.toml" with cfg -> shared is carried as cfg/base.toml, where forge will look for it after stasis extract.

A config whose real path the OS can't give (past PATH_MAX) is never given a normalized name, since that could name another file. It keeps the name it was read by, .. and all, however the root was spelled in the path (L/../base.toml, <root>/./L/../base.toml, a doubled /, the root's real path), and is refused. A path from no spelling of the root stays absolute and is refused as unresolvable.

A config the resolution read that can't be carried fails --manifests with an error naming it, because without it the bundle couldn't reproduce the resolution. That covers one outside the bundle root (extends = "../shared-base.toml"), a .env one (base.env, .env.toml, Base.ENV, .env.local), a hardhat.config.* one in any case, one the ownership rules refuse, and one that's gone. Without --manifests nothing is carried, and these bundle as forge resolves them.

Other fixes

• --mapping:
  • a root foundry.toml whose settings forge would reject (a broken extends) falls back to the default lib dirs, with a warning;
  • FOUNDRY_PROFILE is reported only when it names a profile the root foundry.toml has, and warned about otherwise.
• forge and solc fidelity:
  • an extends path is joined as forge joins it, not normalized, so a .. after a symlink leads where forge's does, in the project's config and a dependency's alike (extends = "sub/../base.toml" with sub -> real/in reads real/base.toml, not base.toml);
  • a legacy [<name>] table's extends is ignored, as forge ignores it;
  • a remappings.txt taken as written accepts an empty target (x/=), as solc does.
• Mistyped extensionless entry: reported as no such file or directory. The directory-entry rules are in directoryEntryError and isSolidityEntry, used by both the CLI and buildBundle.
• Shared helpers:
  • realpathOrNull is the one realpath helper for solidity.js, foundry.js and the ownership walk (realpath(3) on disk, the host's own otherwise);
  • readRegularFileOrNull (in stasis-core, through host) is the one reader for config files and carried manifests, and decodeUtf8 the one strict UTF-8 decoder for Solidity sources and configs;
  • a carried manifest is read by the real path the ownership check resolved, so the file carried is the one that was vouched for;
  • readPackageJson is the one package.json reader behind findPackageMetadata, and it reads through host;
  • projectRelative names the config files read, for both solidity.js and foundry.js;
  • ownership.assert is the one refuse-and-throw check, and ownership.submodules the one parsed .gitmodules;
  • packageLookup is the one per-directory package cache, shared by a JS bundle's --package-json pass and its buckets.

Checks

• Forge oracle (v1.8.3): the scenario, profile, legacy-extends and test-case suites all match, as do 5,700 fuzzed projects across the runs and the symlinked-extends cases (the project's and a dependency's). The oracle also confirms forge refuses a bad remappings.txt line, rejects libs = "deps" and keeps a leading BOM. solc-js 0.8.30 confirms the empty remapping target.
• git 2.43: the .gitmodules reader matches git config -f --list -z on 16,000 fuzzed files. The library also refuses every one of about 187,000 files git refuses, so the strict check can't be bypassed on the main path.
• node --run test (exodus-test, Node 24): 2173 pass, 0 fail, all 81 suites, main's Soldeer Vfs bundles included. node --run lint: clean.
• A Solidity bundle built through a Vfs host refuses a dependency's link to the project's .env. That test fails if the ownership walk reads the disk instead of the host.
• Two tests guard against hangs, and both hang on the previous code:
  • one runs the bundle in a child whose stdin is an open anonymous pipe;
  • another puts a FIFO at a dependency's package.json.
• Deliberately unchanged:
  • a project's own symlink (e.g. src/E.sol -> ../.env) is still trusted, because the project placed it;
  • a symlink an extends path goes through isn't carried itself (bundles don't hold symlinks), only the file read;
  • packages that pnpm doesn't hoist to the top-level node_modules still can't be found from inside another package, as on main.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C6oBS5QX4oqZcd2d3STiGA