@exodus/stasis 1.0.0-alpha.2 → 1.0.0-beta.0

package/src/audit.js

@@ -0,0 +1,112 @@
+import { advisories } from './apis/npm/index.js'
+import semver from './apis/npm/semver.cjs'
+import { parseFile } from './parse.js'
+
+// 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/bundle-from-lockfile.js

@@ -0,0 +1,65 @@
+import { isUtf8 } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { sha512integrity } from '@exodus/stasis-core/state-util'
+import { moduleFileKey } from '@exodus/stasis-core/util'
+
+// Reconstruct an in-memory Bundle from a lockfile by reading every file it attests
+// from disk and verifying each against the lockfile's SRI digest -- the exact inverse
+// of `extract`'s lockfileFromBundle. A changed or tampered file fails closed here (the
+// digest won't match), so building from a lockfile is as trustworthy as a
+// `stasis run --lock=frozen` replay: the build only ever sees bytes the lockfile
+// vouches for. `root` is the project root the lockfile's paths are relative to.
+//
+// Directory captures (`stasis run --fs` readdir listings, format 'directory') are
+// skipped: they key a listing at a directory's own path, not a file esbuild could load.
+export function bundleFromLockfile(lockfile, { root }) {
+  if (!lockfile.imports) throw new Error('stasis: lockfile has no recorded import graph')
+  const formats = lockfile.formats ?? new Map()
+  const modules = new Map()
+  for (const [dir, { name, version, ecosystem, files }] of lockfile.modules) {
+    const out = Object.create(null)
+    for (const [rel, integrity] of Object.entries(files)) {
+      const file = moduleFileKey(dir, rel)
+      const format = formats.get(file)
+      if (format === 'directory') continue
+      const abs = resolve(root, file)
+      let bytes
+      try {
+        bytes = readFileSync(abs)
+      } catch (cause) {
+        throw new Error(`stasis: file attested by the lockfile is missing on disk: ${file}`, { cause })
+      }
+      // The lockfile digests raw on-disk bytes; verify against them before trusting
+      // the file. (Code and 'resource' files hash identically whether viewed as a
+      // string or bytes, since Node hashes a string as its UTF-8 bytes.)
+      const actual = sha512integrity(bytes)
+      if (actual !== integrity) {
+        throw new Error(`stasis: ${file} does not match the lockfile (expected ${integrity}, got ${actual})`)
+      }
+      // Store content the way a Bundle does: 'resource:base64' as base64 text,
+      // everything else (code, 'resource') as a raw UTF-8 string. A non-base64 entry is
+      // digested AND served as UTF-8 text, so a non-UTF-8 byte would transcode lossily
+      // (U+FFFD), diverging the served content from the verified bytes -- mirror the
+      // capture side's isUtf8 guard and fail closed instead.
+      if (format === 'resource:base64') {
+        out[rel] = bytes.toString('base64')
+      } else {
+        if (!isUtf8(bytes)) throw new Error(`stasis: ${file} is recorded as '${format ?? 'code'}' but is not valid UTF-8`)
+        out[rel] = bytes.toString('utf8')
+      }
+    }
+    modules.set(dir, ecosystem === undefined
+      ? { name, version, files: out }
+      : { name, version, ecosystem, files: out })
+  }
+  return new Bundle({
+    config: lockfile.config,
+    entries: lockfile.entries,
+    modules,
+    imports: lockfile.imports,
+    formats,
+  })
+}

package/src/bundle.js

@@ -1,217 +1,4 @@
-import {
-  assert,
-  fileMapToObject,
-  fileSetToObject,
-  fromEntries,
-  objectToMaps,
-  sortPaths,
-  splitNodeModulesPath,
-} from './util.js'
-
-const VERSION = 1
-const LEGACY_VERSION = 0
-
-const normalize = ({ name, version, files }) =>
-  ({ name, version, files: fromEntries(Object.entries(files)) })
-
-const inferModuleDir = (path) =>
-  splitNodeModulesPath(path) ?? { dir: '.', rel: path, name: null }
-
-// Bundle handles the JSON shape of stasis.code.br / stasis.resources.br;
-// callers (State) are responsible for the brotli wrapper around the JSON
-// text. On-disk version:
-//   v0 — legacy flat layout: top-level `sources` (or `resources`) keyed by
-//        project-relative path. No entries/modules metadata.
-//   v1 — current layout, mirrors stasis.lock.json: per-package buckets under
-//        `sources` (workspace) and `modules` (node_modules) with name+version+files,
-//        plus `entries`. File payloads carry bytes (UTF-8 source strings or base64
-//        resource blobs) instead of SRI digests.
-// We load both v0 and v1; we always serialize v1. v0 is converted on load to
-// the same in-memory shape — paths are regrouped by package dir via
-// `inferModuleDir` (best-effort, last-wins). name/version stay null since v0
-// records neither, which State uses as a marker to skip metadata cross-checks.
-export class Bundle {
-  static VERSION = VERSION
-
-  // The on-disk version this instance represents. Defaults to VERSION; parse*
-  // sets it to whatever the file declared (LEGACY_VERSION for v0 input).
-  // Serialization always writes the current VERSION regardless — loading v0 and
-  // re-saving promotes the bundle to v1.
-  version = VERSION
-  config
-  entries
-  modules
-  formats
-  imports
-
-  constructor({ config = { scope: 'full' }, entries, modules, formats, imports, version = VERSION } = {}) {
-    assert([LEGACY_VERSION, VERSION].includes(version))
-    assert(['node_modules', 'full'].includes(config.scope))
-    this.version = version
-    this.config = config
-    this.entries = entries ?? new Set()
-    this.modules = modules ?? new Map()
-    this.formats = formats ?? new Map()
-    this.imports = imports ?? new Map()
-  }
-
-  // Flat project-relative view of file contents collected from this.modules.
-  // Values are UTF-8 source strings for code bundles, base64 for resource bundles.
-  get sources() {
-    const m = new Map()
-    for (const [dir, { files }] of this.modules) {
-      for (const [rel, content] of Object.entries(files)) {
-        m.set(dir === '.' ? rel : `${dir}/${rel}`, content)
-      }
-    }
-    return m
-  }
-
-  static parseCode(text) {
-    const json = JSON.parse(text)
-    assert(json.version === VERSION || json.version === LEGACY_VERSION)
-    assert(['node_modules', 'full'].includes(json.config?.scope))
-    assert(json.formats)
-    assert(json.imports)
-
-    const modules = new Map()
-    let entries = new Set()
-
-    if (json.version === VERSION) {
-      const full = json.config.scope === 'full'
-      if (json.modules !== undefined) {
-        assert(typeof json.modules === 'object' && json.modules !== null)
-        for (const [dir, info] of Object.entries(json.modules)) {
-          assert(dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      }
-      if (full) {
-        assert(Array.isArray(json.entries))
-        // Empty entries in v1 + full would let `state.assertEntry` skip its check
-        // (it short-circuits on entries.size === 0 for v0+no-lockfile compatibility).
-        // Forbid the shape at parse time so tampered bundles can't exploit that path.
-        assert(json.entries.length > 0, 'v1 bundle with scope=full must have at least one entry')
-        assert(json.sources && typeof json.sources === 'object')
-        entries = new Set(json.entries)
-        for (const [dir, info] of Object.entries(json.sources)) {
-          assert(!dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      } else {
-        assert(json.entries === undefined)
-        assert(json.sources === undefined)
-      }
-      for (const [, { files }] of modules) {
-        for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
-      }
-    } else {
-      // v0 legacy: flat sources at top level, regrouped by inferred module dir.
-      assert(json.sources)
-      for (const [path, content] of Object.entries(json.sources)) {
-        assert(!path.startsWith('..'))
-        const { dir, rel, name } = inferModuleDir(path)
-        assert(!dir.startsWith('..') && !rel.startsWith('..'))
-        if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
-        modules.get(dir).files[rel] = content
-      }
-    }
-
-    return new Bundle({
-      version: json.version,
-      config: json.config,
-      entries,
-      modules,
-      formats: new Map(Object.entries(json.formats)),
-      imports: objectToMaps(json.imports),
-    })
-  }
-
-  static parseResources(text) {
-    const json = JSON.parse(text)
-    assert(json.version === VERSION || json.version === LEGACY_VERSION)
-
-    const modules = new Map()
-    let config = { scope: 'full' }
-
-    if (json.version === VERSION) {
-      assert(['node_modules', 'full'].includes(json.config?.scope))
-      config = json.config
-      const full = config.scope === 'full'
-      if (json.modules !== undefined) {
-        assert(typeof json.modules === 'object' && json.modules !== null)
-        for (const [dir, info] of Object.entries(json.modules)) {
-          assert(dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      }
-      if (full && json.sources !== undefined) {
-        assert(typeof json.sources === 'object' && json.sources !== null)
-        for (const [dir, info] of Object.entries(json.sources)) {
-          assert(!dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      } else if (!full) {
-        assert(json.sources === undefined)
-      }
-      for (const [, { files }] of modules) {
-        for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
-      }
-    } else {
-      // v0 legacy: flat resources at top level, regrouped by inferred module dir.
-      assert(json.resources)
-      for (const [path, content] of Object.entries(json.resources)) {
-        assert(!path.startsWith('..'))
-        const { dir, rel, name } = inferModuleDir(path)
-        assert(!dir.startsWith('..') && !rel.startsWith('..'))
-        if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
-        modules.get(dir).files[rel] = content
-      }
-    }
-
-    return new Bundle({ version: json.version, config, modules })
-  }
-
-  #groupedFromModules() {
-    const moduleEntries = []
-    const sourceEntries = []
-    for (const [dir, { name, version, files }] of this.modules) {
-      if (Object.keys(files).length === 0) continue
-      const inNodeModules = dir.includes('node_modules')
-      if (inNodeModules) assert(name && version && files)
-      const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
-      const target = inNodeModules ? moduleEntries : sourceEntries
-      target.push([dir, { name, version, files: sorted }])
-    }
-    moduleEntries.sort((a, b) => sortPaths(a[0], b[0]))
-    sourceEntries.sort((a, b) => sortPaths(a[0], b[0]))
-    return { modules: fromEntries(moduleEntries), sources: fromEntries(sourceEntries) }
-  }
-
-  serializeCode() {
-    const entries = fileSetToObject(this.entries)
-    const { modules, sources } = this.#groupedFromModules()
-    const formats = fileMapToObject(this.formats)
-    const imports = fileMapToObject(this.imports)
-    const data = { version: VERSION, config: this.config }
-    if (this.config.scope === 'full') Object.assign(data, { entries, sources })
-    Object.assign(data, { modules, formats, imports })
-    return JSON.stringify(data, undefined, 2)
-  }
-
-  serializeResources() {
-    const { modules, sources } = this.#groupedFromModules()
-    const data = { version: VERSION, config: this.config }
-    if (this.config.scope === 'full') Object.assign(data, { sources })
-    Object.assign(data, { modules })
-    return JSON.stringify(data, undefined, 2)
-  }
-}
+// Public-export adapter: backs `@exodus/stasis/bundle`. The implementation lives in
+// @exodus/stasis-core; internal tooling and tests import `@exodus/stasis-core/bundle`
+// directly, so this file exists only to back the package's `exports` map.
+export * from '@exodus/stasis-core/bundle'