@exodus/stasis 1.0.0-alpha.2 → 1.0.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
@@ -17,6 +17,7 @@
     "logo.svg",
     "src/apis/npm/index.js",
     "src/apis/npm/semver.cjs",
+    "src/audit.js",
     "src/bundle.js",
     "src/cmd/bundle.js",
     "src/config.js",

package/src/audit.js

@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs'
+import { brotliDecompressSync } from 'node:zlib'
+
+import { advisories } from './apis/npm/index.js'
+import semver from './apis/npm/semver.cjs'
+import { Bundle } from './bundle.js'
+import { Lockfile } from './lockfile.js'
+
+function parseFile(file) {
+  let buf
+  try {
+    buf = readFileSync(file)
+  } catch (cause) {
+    if (cause.code === 'ENOENT') throw new Error(`File not found: ${file}`, { cause })
+    throw new Error(`Failed to read ${file}: ${cause.message}`, { cause })
+  }
+  // Lockfiles are JSON text starting with `{`; code/resource bundles are
+  // brotli-compressed JSON. Sniff to route to the right parser so its
+  // diagnostic surfaces on failure.
+  if (buf[0] === 0x7b /* '{' */) {
+    try {
+      return Lockfile.parse(buf.toString('utf8'))
+    } catch (cause) {
+      throw new Error(`Failed to parse stasis lockfile: ${file}`, { cause })
+    }
+  }
+  let text
+  try {
+    text = brotliDecompressSync(buf).toString('utf8')
+  } catch (cause) {
+    throw new Error(`Failed to read ${file} as a stasis bundle (not brotli)`, { cause })
+  }
+  // Code bundles carry `formats`/`imports`; resource bundles don't. Route on shape.
+  try {
+    const isCode = JSON.parse(text).formats !== undefined
+    return isCode ? Bundle.parseCode(text) : Bundle.parseResources(text)
+  } catch (cause) {
+    throw new Error(`Failed to parse stasis bundle: ${file}`, { cause })
+  }
+}
+
+// Only audit installed dependencies; workspace/first-party packages live under
+// non-`node_modules` keys in .modules (Lockfile/Bundle merge sources in) and
+// shouldn't be sent to the public registry — they leak names and produce noise.
+export function collectPackagesFromFile(file) {
+  const out = []
+  for (const [dir, { name, version }] of parseFile(file).modules) {
+    if (!dir.includes('node_modules')) continue
+    if (name && version) out.push({ name, version })
+  }
+  return out
+}
+
+export function collectPackages(files) {
+  const seen = new Set()
+  const out = []
+  for (const file of files) {
+    for (const { name, version } of collectPackagesFromFile(file)) {
+      const key = `${name}@${version}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      out.push({ name, version })
+    }
+  }
+  return out.toSorted((a, b) => a.name.localeCompare(b.name) || semver.compare(a.version, b.version))
+}
+
+const SEVERITY_ORDER = { critical: 0, high: 1, moderate: 2, low: 3, info: 4, none: 5 }
+
+export function flattenAdvisories(result, packages = []) {
+  const installed = new Map()
+  for (const { name, version } of packages) {
+    if (!installed.has(name)) installed.set(name, [])
+    installed.get(name).push(version)
+  }
+  const rows = []
+  for (const [pkg, list] of Object.entries(result)) {
+    if (!Array.isArray(list)) continue
+    const installedVersions = installed.get(pkg) ?? []
+    for (const adv of list) {
+      const range = adv.vulnerable_versions ?? ''
+      const affected = range
+        ? installedVersions.filter((v) => semver.satisfies(v, range))
+        : installedVersions
+      // npm occasionally returns advisories whose vulnerable range matches none
+      // of the versions we submitted; drop them so the table (and the CLI exit
+      // code) reflect only real hits.
+      if (installedVersions.length > 0 && affected.length === 0) continue
+      rows.push({
+        package: pkg,
+        installed: affected.join(', '),
+        vulnerable: range,
+        severity: adv.severity ?? '',
+        title: adv.title ?? '',
+        url: adv.url ?? '',
+      })
+    }
+  }
+  rows.sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity] ?? 99
+    const sb = SEVERITY_ORDER[b.severity] ?? 99
+    if (sa !== sb) return sa - sb
+    if (a.package !== b.package) return a.package < b.package ? -1 : 1
+    return a.title < b.title ? -1 : 1
+  })
+  return rows
+}
+
+// Line breaks in npm advisory titles would otherwise break the box layout.
+// Covers LF, bare CR (and CRLF), and U+2028 / U+2029 line/paragraph separators.
+const cell = (v) => String(v ?? '').replace(/[\r\n\u2028\u2029]+/gu, ' ')
+
+export function formatTable(rows, columns) {
+  if (rows.length === 0) return ''
+  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length)))
+  const pad = (s, w) => s.padEnd(w)
+  const line = (l, m, r, fill) => l + widths.map((w) => fill.repeat(w + 2)).join(m) + r
+  const row = (vals) => '│ ' + vals.map((v, i) => pad(cell(v), widths[i])).join(' │ ') + ' │'
+  return [
+    line('┌', '┬', '┐', '─'),
+    row(columns),
+    line('├', '┼', '┤', '─'),
+    ...rows.map((r) => row(columns.map((c) => r[c]))),
+    line('└', '┴', '┘', '─'),
+  ].join('\n')
+}
+
+export async function audit(files) {
+  const packages = collectPackages(files)
+  if (packages.length === 0) {
+    return { packages, advisories: {}, rows: [] }
+  }
+  const result = await advisories(packages)
+  const rows = flattenAdvisories(result, packages)
+  return { packages, advisories: result, rows }
+}
+
+export function printAuditReport({ packages, rows }, { out = process.stdout, err = process.stderr } = {}) {
+  err.write(`Scanned ${packages.length} package${packages.length === 1 ? '' : 's'}\n`)
+  if (packages.length === 0) {
+    err.write('No node_modules entries found in the input files\n')
+    return
+  }
+  if (rows.length === 0) {
+    err.write('No advisories found\n')
+    return
+  }
+  out.write(formatTable(rows, ['severity', 'package', 'installed', 'vulnerable', 'title', 'url']) + '\n')
+}

package/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

package/src/loaders/solidity.js

@@ -6,6 +6,7 @@
 // but is itself not included in `sources`.
 
 import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 
 const SOL_IMPORT_RE = /import\s[^"']*["']([^"']+)["']/gu
@@ -28,16 +29,16 @@ export function parseRemappings(content) {
   }).filter(Boolean)
 }
 
-// Returns a candidate resolved path, or null if the specifier doesn't match
-// any remapping and isn't a relative import. The caller is responsible for
-// checking whether the resolved path actually exists in `sources` (the
-// etherscan bundle's cnames are exact-match keys — `@openzeppelin/…` lives
-// alongside `contracts/Foo.sol` — so a non-relative, non-remapped specifier
-// may still be a hit when matched verbatim against the bundle). Logging
-// "Missing import" also lives at the callsite because only the callsite
-// knows whether that verbatim fallback matched.
-export function resolveSolImport(specifier, fromFile, remappings) {
-  // Try remappings (longest prefix match)
+// Resolve a Solidity import specifier to a baseDir-relative POSIX path,
+// trying three strategies in order:
+//   1. user remappings (longest prefix wins)
+//   2. relative path (`./...` or `../...`); traversal above the project
+//      root returns null instead of clamping
+//   3. Node's CJS resolver via createRequire, anchored at the importing
+//      source — only when `baseDir` is provided and the specifier looks
+//      like a scoped npm package (`@scope/pkg/sub/path`)
+// Returns null when no strategy resolves the import.
+export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir } = {}) {
   let best = null
   for (const { prefix, target } of remappings) {
     if (specifier.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) {
@@ -47,13 +48,9 @@ export function resolveSolImport(specifier, fromFile, remappings) {
   if (best) {
     const target = best.target.replace(/\/$/u, '')
     const remaining = specifier.slice(best.prefix.length).replace(/^\//u, '')
-    const result = remaining ? `${target}/${remaining}` : target
-    return result.replace(/^\.\//u, '')
+    return (remaining ? `${target}/${remaining}` : target).replace(/^\.\//u, '')
   }
 
-  // Relative import. `..` segments that would traverse above the project
-  // root return null instead of silently clamping to root — clamping would
-  // change the import target into something the source never asked for.
   if (specifier.startsWith('.')) {
     const fromDir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : ''
     const parts = [...(fromDir ? fromDir.split('/') : []), ...specifier.split('/')]
@@ -70,30 +67,41 @@ export function resolveSolImport(specifier, fromFile, remappings) {
     return resolved.join('/')
   }
 
+  // Node-style `@scope/pkg/sub/path`. createRequire is anchored at the
+  // importing source so nested node_modules resolve like Node would
+  // (a file under `node_modules/foo/` finds its deps in
+  // `foo/node_modules/` before walking up). `..` segments in the
+  // subpath are rejected so a crafted specifier can't escape the
+  // resolved package via require.resolve's own path normalization.
+  if (baseDir && specifier.startsWith('@')) {
+    const parts = specifier.split('/')
+    if (parts.length < 3) return null
+    if (parts.slice(2).includes('..')) return null
+    try {
+      const abs = createRequire(resolve(baseDir, fromFile)).resolve(specifier)
+      const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
+      if (!rel.startsWith('..') && !isAbsolute(rel)) return rel
+    } catch { /* package missing, exports map blocks the subpath, … */ }
+  }
+
   return null
 }
 
 // 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
-// optional remappings. Imports that resolve via remappings/relative paths
-// win; as a fallback we also accept an import specifier that matches a
-// stored key verbatim (etherscan bundles imports like
-// `@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 = [] } = {}) {
+// already-loaded Solidity sources plus optional remappings. Imports that
+// resolve via remappings/relative/Node win; as a final fallback an
+// import specifier that matches a stored key verbatim (etherscan
+// bundles, hardhat flat layouts) is accepted. `missing` lists every
+// (spec, from) pair that could not be resolved or that resolved to a
+// file not loaded into `sources`.
+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)
+      let resolved = resolveSolImport(spec, path, { remappings, baseDir })
       if (resolved && !sources.has(resolved)) resolved = null
-      // Verbatim fallback: many Solidity ecosystems (etherscan bundles,
-      // hardhat flat layouts) ship `@openzeppelin/...` imports as literal
-      // keys in the source map. If the remap/relative resolution didn't
-      // hit but the bundle has the specifier itself as a key, use it.
       if (!resolved && sources.has(spec)) resolved = spec
       if (resolved) {
         specMap.set(spec, resolved)
@@ -107,21 +115,12 @@ export function buildSolidityTree(sources, { remappings = [] } = {}) {
   return { sources, resolutions, missing }
 }
 
-// Walk the filesystem starting from `entries`, following relative/remapped
-// imports and reading each file exactly once. Returns a Map<relPath, content>
-// suitable for passing into buildSolidityTree. Files in the same wave are
-// read in parallel; subsequent waves depend on the imports discovered in
-// the previous one.
-//
-// Specifiers that exactly match one of the explicit entries (the file
-// list passed by the caller) are accepted as-is, even when they don't
-// match any remapping. Solidity projects routinely write
-// `import "src/A.sol"` and rely on solc's include-path / Foundry's
-// remap-from-root behavior; here we don't have a true include path,
-// but if the caller listed `src/A.sol` themselves we know the path is
-// intentional and resolves to that file. Mirrors the `sources.has(spec)`
-// fallback in `buildSolidityTree`, but applied during the walk so the
-// file actually gets loaded into `sources`.
+// Walk the filesystem starting from `entries`, following resolved
+// imports and reading each file exactly once. Files in the same wave
+// are read in parallel; the next wave depends on the imports
+// discovered in the previous one. Caller-listed entries are also
+// accepted as verbatim non-relative import targets (Foundry-style
+// `import "src/A.sol"`).
 export async function collectSolidityFilesFromDisk(baseDir, entries, remappings) {
   const sources = new Map()
   const knownEntries = new Set(entries)
@@ -129,9 +128,6 @@ export async function collectSolidityFilesFromDisk(baseDir, entries, remappings)
   const processWave = async (wave) => {
     const toLoad = [...new Set(wave)].filter((p) => !sources.has(p))
     if (toLoad.length === 0) return
-    // A resolved path that doesn't exist on disk is treated like an
-    // unresolved import: warn and skip rather than aborting the entire
-    // walk. Other read errors (EACCES, EIO, …) still propagate.
     const reads = await Promise.all(
       toLoad.map(async (relPath) => {
         try {
@@ -151,7 +147,7 @@ export async function collectSolidityFilesFromDisk(baseDir, entries, remappings)
       const [relPath, content] = entry
       sources.set(relPath, content)
       for (const spec of extractSolImports(content)) {
-        let resolved = resolveSolImport(spec, relPath, remappings)
+        let resolved = resolveSolImport(spec, relPath, { remappings, baseDir })
         if (!resolved && knownEntries.has(spec)) resolved = spec
         if (resolved) {
           if (!sources.has(resolved)) next.push(resolved)
@@ -210,5 +206,5 @@ export async function loadSolidity(solTxtFile) {
   const entries = lines.map((l) => l.replace(/^\.\//u, ''))
   for (const e of entries) assertWithinBase(baseDir, e, 'Entry path')
   const sources = await collectSolidityFilesFromDisk(baseDir, entries, remappings)
-  return buildSolidityTree(sources, { remappings })
+  return buildSolidityTree(sources, { remappings, baseDir })
 }