@preventive/triage 1.0.0-alpha.37 → 1.0.0-alpha.38

package/risk/npm/compare.js

@@ -0,0 +1,222 @@
+// What calls for a look at a package version against the one before it, as
+// findings: `{ id, severity, ... }` each (stamps.js SEVERITIES), what it found
+// beside. Each version as risk holds one (`{ kind: 'sourcemap', npm, json,
+// fileSizes? }`: npm's facts, `npm.manifest` as manifest.js reads a version's
+// document, its files as a source map lists them, `json.sources` and
+// `json.sourcesContent`, a text or null each, and their sizes by path where
+// known), and `files` how they differ (diff.js npmFilesDiff): `onlyOther`, the
+// files the open version adds, and `changed`, those it changes, each `{ path,
+// renamedFrom?, modified? }`, by its path in the open version.
+import { bundleFileSizes, bundleFilesAsMap } from '../../common/bundle-sources.js'
+import { npmVersionFileRisk, npmVersionHosts } from './files.js'
+import { npmHostFinding } from './held.js'
+import { HOST_TAGS, npmHostSeverity, npmHostsTagged } from '../files/hosts.js'
+import { npmBecameUnreadable, npmLargeCode, npmUnreadable } from '../files/readability.js'
+import { SEVERITIES } from '../files/stamps.js'
+import { npmFoundAdded, npmRunsCodeFlags, npmRunsCodeWithout } from '../files/runs-code.js'
+import { npmDependencySpecs } from './dependencies.js'
+import { npmFilesDiff } from './diff.js'
+import { npmInstallScripts } from './install-scripts.js'
+import { npmInstallScriptsChange, npmProvenanceLost, npmPublisherChange } from './release.js'
+
+// What the open version does to its files that calls for a look, as red
+// findings: code that runs beyond itself (runs-code.js), new to a file it
+// adds or changes, the kinds with their lines (`runs-code`); a service under
+// one of the hosts' tags new to a file it adds or changes (hosts.js
+// npmExfiltration), a finding a tag a level higher than its own
+// (npmHostSeverity: `exfiltration` and `remote` red, `ip-lookup` orange); a
+// code file of 256 KiB or more it adds (npmLargeCode, `large-code`); a file
+// it changes that had no line over 200 characters and now has one over 2,000
+// (npmBecameUnreadable, `now-unreadable`); and a file it adds or changes with
+// an obfuscator's fingerprint where the one compared with had none
+// (`obfuscated`). Then in orange what any of its files runs beyond itself that
+// `runs-code` doesn't name, kept from the version compared with
+// (`kept-runs-code`). A renamed file by its old path; one renamed alone,
+// unchanged, holds what it held. A file become unreadable calls for less
+// where its source map was rebuilt with it (`rebuilt`, rebuiltWithMap), as a
+// build minifies a file and writes its map together, and in a `major`
+// release (npmMajorRelease): `now-unreadable` orange where every such file is
+// either, else red.
+function npmFileFindings(base, other, files, major) {
+  const added = new Set(files.onlyOther)
+  const after = row => npmVersionFileRisk(other, row.path)
+  const before = row => added.has(row) ? null : npmVersionFileRisk(base, row.renamedFrom ?? row.path)
+  const changed = files.changed.filter(row => row.renamedFrom == null || row.modified)
+  const touched = [...files.onlyOther, ...changed]
+  const sizes = bundleFileSizes(other)
+  // The files that hold what they didn't before, each with that.
+  const gained = key => touched.map(row => ({ path: row.path, added: npmFoundAdded(after(row)[key], before(row)?.[key] ?? null) })).filter(row => row.added)
+  const exfiltration = gained('exfiltration'), runsCode = gained('runsCode')
+  const flagged = new Set(runsCode.flatMap(row => npmRunsCodeFlags(row.added).map(({ name }) => name)))
+  const kept = [...bundleFilesAsMap(other).keys()].map(path => ({ path, found: npmRunsCodeWithout(npmVersionFileRisk(other, path).runsCode, flagged) })).filter(row => row.found)
+  return [
+    { id: 'runs-code', severity: 'critical', files: runsCode },
+    ...[...HOST_TAGS.keys()].map(tag => {
+      const rows = exfiltration.map(row => ({ path: row.path, added: npmHostsTagged(row.added, tag) })).filter(row => row.added)
+      return { id: npmHostFinding(tag), severity: rows.length > 0 ? npmHostSeverity(tag, rows[0].added, null) : HOST_TAGS.get(tag), files: rows }
+    }),
+    { id: 'large-code', severity: 'critical', files: files.onlyOther.filter(row => npmLargeCode(row.path, sizes.get(row.path))).map(row => ({ path: row.path, bytes: sizes.get(row.path) })) },
+    { id: 'now-unreadable', ...unreadableFinding(major, changed.filter(row => npmBecameUnreadable(row.path, before(row)?.readability, after(row).readability))
+      .map(row => ({ path: row.path, was: before(row).readability.longest, now: after(row).readability.longest,
+        ...rebuiltWithMap(base, other, row.path, row.renamedFrom ?? row.path) ? { rebuilt: true } : {} }))) },
+    { id: 'obfuscated', severity: 'critical', files: touched.filter(row => after(row).readability.obfuscation && !before(row)?.readability.obfuscation)
+      .map(row => ({ path: row.path, obfuscation: after(row).readability.obfuscation })) },
+    { id: 'kept-runs-code', severity: 'high', files: kept },
+  ].filter(finding => finding.files.length > 0)
+}
+
+// Hosts whose naming anew calls for no look: where packages keep their code
+// and docs, as their links and error messages name them, the most a version
+// names anew of popular packages a year apart (lit.dev, Lit's), and none
+// whose content anyone may publish (a wiki's raw pages) but github.com's
+// pages, as hosts.js githubNamed names them: a repository's own URL, its
+// files and releases are named by it. Each as it is written, not a host
+// under it, so one an attack sends to or fetches from there
+// (`api.github.com`, `raw.githubusercontent.com`) is still named; and no link
+// shortener (`git.io`, `git.new`), which can lead anywhere.
+const ALLOWED_HOSTS = new Set(['github.com', 'lit.dev', 'developer.mozilla.org', 'json-schema.org', 'nodejs.org', 'babeljs.io', 'tseslint.com',
+  'devblogs.microsoft.com', 'semver.org'])
+
+// A severity one level lower (stamps.js SEVERITIES).
+const lower = severity => SEVERITIES[Math.min(SEVERITIES.indexOf(severity) + 1, SEVERITIES.length - 1)]
+
+// Whether the open version (`now`) is a major release past the one compared
+// with (`was`): its major number higher, or its minor for 0.x. A rewrite
+// changes how a package's files read and who publishes it, and npm's `^`
+// ranges don't take a major release by themselves, as a hijacked release
+// wants them to.
+function npmMajorRelease(was, now) {
+  const [a, b] = [was, now].map(version => /^v?(\d+)\.(\d+)\./u.exec(version ?? '')?.slice(1).map(Number))
+  return Boolean(a && b) && (b[0] > a[0] || (a[0] === 0 && b[0] === 0 && b[1] > a[1]))
+}
+
+// Whether the open version's file at `path` (`basePath` in the one compared
+// with) had its source map rebuilt with it: its last line, a
+// `sourceMappingURL` comment and no more, names a map file of the package by
+// a plain path from the file's own (MAP_NAME), a source map
+// (its `mappings`, or each of an indexed map's `sections`, told), new or
+// changed from the one at its path, or beside the file's own before it was
+// renamed, as a build writes them together. An attack editing a built file
+// leaves its map as it was.
+const SOURCE_MAP_FILE = /^\s*(?:\/\/[#@] sourceMappingURL=(\S+)|\/\*[#@] sourceMappingURL=(\S+?)\s*\*\/)\s*$/u
+// A map name a build writes (`a.js.map`, `../maps/a.map`): segments of
+// letters, digits and `._~@+-`, as a browser reads them alike. One at a URL,
+// from a site's root, or with an escape or a backslash names none.
+const MAP_NAME = /^(?:[\w.~@+-]+\/)*[\w.~@+-]+\.map$/u
+function besideFile(file, name) {
+  const parts = file.split('/').slice(0, -1)
+  for (const part of name.split('/')) {
+    if (part === '..' && parts.length === 0) return null
+    if (part === '..') parts.pop()
+    else if (part !== '.') parts.push(part)
+  }
+  return parts.join('/')
+}
+function rebuiltWithMap(base, other, path, basePath) {
+  const text = bundleFilesAsMap(other).get(path)
+  const directive = typeof text === 'string' ? SOURCE_MAP_FILE.exec(text.trimEnd().split('\n').at(-1)) : null
+  const name = directive?.[1] ?? directive?.[2]
+  if (!name || !MAP_NAME.test(name)) return false
+  const [map, was] = [bundleFilesAsMap(other).get(besideFile(path, name)), bundleFilesAsMap(base)]
+  return isSourceMap(map) && map !== was.get(besideFile(path, name)) && map !== was.get(besideFile(basePath, name))
+}
+const isSourceMap = text => {
+  try {
+    const json = JSON.parse(text)
+    return typeof json?.mappings === 'string'
+      || (Array.isArray(json?.sections) && json.sections.length > 0 && json.sections.every(section => typeof section?.map?.mappings === 'string'))
+  } catch { return false }
+}
+
+// The files become unreadable as a finding says them: red, but orange in a
+// major release, or where each had its source map rebuilt with it.
+const unreadableFinding = (major, files) => ({ severity: major || files.every(row => row.rebuilt) ? 'high' : 'critical', ...major ? { major } : {}, files })
+
+// The hosts the open version's code names in its URLs that the one compared
+// with's named in none of its, ALLOWED_HOSTS aside, each `{ host, path, line,
+// places }`: the file it is first named in and its line, and `places` every
+// file that names it, `{ path, line }` each, the line it is first named on
+// there. A file unchanged names what it named, so the files the open version
+// adds or changes hold all it names anew.
+function npmNewHosts(base, other, files) {
+  const found = new Map(), known = npmVersionHosts(base)
+  for (const { path } of [...files.onlyOther, ...files.changed]) {
+    for (const [host, line] of npmVersionFileRisk(other, path).hosts ?? []) {
+      if (known.has(host) || ALLOWED_HOSTS.has(host)) continue
+      const place = { path, line }
+      if (found.has(host)) found.get(host).places.push(place)
+      else found.set(host, { host, ...place, places: [place] })
+    }
+  }
+  return [...found.values()]
+}
+
+// Whether the files of the version compared with could change what
+// npmCompareFindings finds of the open version (`other`), told before they
+// are read, by the open version's files and the manifest npm's document of
+// the one compared with gives (`manifest`): what its files call for
+// (npmFileFindings, npmNewHosts) is only ever what the open version's own
+// files hold that the one compared with's didn't, so where none of them runs
+// code beyond itself, names a service under one of the hosts' tags or a host
+// past ALLOWED_HOSTS, bears an obfuscator's fingerprint, has a line no one
+// writes (npmUnreadable) or is large code, nothing is found of them whatever
+// the one compared with holds. Nor do the one compared with's install scripts
+// differ by a binding.gyp among its files, but where its manifest names
+// neither `preinstall` nor `install`, and the open version has some.
+export function npmBaseFilesTell(other, manifest) {
+  if (npmInstallScripts(other.npm.manifest, other.json.sources).length > 0
+    && npmInstallScripts(manifest).length !== npmInstallScripts(manifest, ['binding.gyp']).length) return true
+  const sizes = bundleFileSizes(other)
+  return [...bundleFilesAsMap(other).keys()].some(path => {
+    const { runsCode, exfiltration, readability, hosts } = npmVersionFileRisk(other, path)
+    return Boolean(runsCode || exfiltration || readability.obfuscation) || npmUnreadable(path, readability) || npmLargeCode(path, sizes.get(path))
+      || [...hosts?.keys() ?? []].some(host => !ALLOWED_HOSTS.has(host))
+  })
+}
+
+// Of the dependencies the open version adds and changes against `base`, or
+// alone, none given, each with its flags (dependencies.js
+// npmFlagDependencyChanges): those it takes from elsewhere than npm's
+// registry, where the one compared with didn't, or by another spec
+// (`non-registry-deps`, each `{ name, was, now }`, its specs); and those it
+// adds that nothing of it imports, which npm installs all the same, its
+// install scripts and all, as a dependency added to run them would be
+// (`unused-deps`, each `{ name, kind, range }`).
+export function npmDependencyFindings({ added, changed }, base) {
+  const flagged = check => [...added, ...changed].filter(row => row.flags.some(flag => flag.check === check))
+  const was = base ? npmDependencySpecs(base.npm.manifest) : null
+  const fetched = flagged('source').map(row => ({ name: row.name, was: was?.get(row.name) ?? null, now: row.to ?? row.range }))
+  const unimported = flagged('unimported').map(({ name, kind, range }) => ({ name, kind, range }))
+  return [
+    ...fetched.length > 0 ? [{ id: 'non-registry-deps', severity: 'high', dependencies: fetched }] : [],
+    ...unimported.length > 0 ? [{ id: 'unused-deps', severity: 'high', dependencies: unimported }] : [],
+  ]
+}
+
+// Everything that calls for a look at the open version (`other`) against the
+// one compared with (`base`), whatever the time, in the order a reviewer reads
+// them: a publisher that changed (release.js npmPublisherChange,
+// `publisher`, each account's standing on the package told where `standing`
+// is given), a level lower in a major release (npmMajorRelease, `major`),
+// as a package changing hands with a rewrite does; provenance lost (`provenance-lost`); install scripts added or
+// changed (`install-scripts`); its `dependencies` added and changed, as
+// flagged (npmDependencyFindings); its files, by how they differ (diff.js
+// npmFilesDiff, npmFileFindings); and the hosts its code names anew
+// (npmNewHosts, `new-hosts`). A `base` without its files (`json` null),
+// where npmBaseFilesTell says they would change nothing, is found nothing of
+// by them.
+export function npmCompareFindings(base, other, dependencies, standing = null) {
+  const major = npmMajorRelease(base.npm.version, other.npm.version)
+  const publisher = npmPublisherChange(base.npm.manifest, other.npm.manifest, standing)
+  const scripts = npmInstallScriptsChange(...[base, other].map(version => ({ manifest: version.npm.manifest, paths: version.json?.sources })))
+  const files = base.json ? npmFilesDiff(base, other) : null
+  const hosts = files ? npmNewHosts(base, other, files) : []
+  return [
+    ...publisher ? [{ id: 'publisher', ...publisher, ...major ? { severity: lower(publisher.severity), major } : {} }] : [],
+    ...npmProvenanceLost(base.npm.manifest, other.npm.manifest) ? [{ id: 'provenance-lost', severity: 'critical' }] : [],
+    ...scripts ? [{ id: 'install-scripts', severity: 'high', ...scripts }] : [],
+    ...npmDependencyFindings(dependencies, base),
+    ...files ? npmFileFindings(base, other, files, major) : [],
+    ...hosts.length > 0 ? [{ id: 'new-hosts', severity: 'high', hosts }] : [],
+  ]
+}

package/risk/npm/dependencies.js

@@ -0,0 +1,153 @@
+// What calls for a look among the dependencies a package version names: one
+// npm fetches from elsewhere than its registry, and one nothing of the
+// version imports, which npm installs all the same, running its install
+// scripts, as a dependency added to run them alone would be.
+import { isNpmPackageName } from '../../common/managed/npm-packages.js'
+import { NPM_PROSE } from '../files/readability.js'
+import { npmAlias, npmDependencySource, npmRegistrySpec } from './specs.js'
+import { npmInstallScripts } from './install-scripts.js'
+
+// The kinds of dependency a manifest names, by its field (npmDependencies).
+const NPM_DEPENDENCY_KINDS = [['dependencies', null], ['peerDependencies', 'peer'], ['optionalDependencies', 'optional']]
+
+// A version's dependencies, each `{ name, range, kind, opens }`, in name
+// order: `kind` null for a plain dependency, else 'peer' or 'optional';
+// `opens` the package the viewer opens for it, the one an `npm:` alias
+// names, or null when it names none, or where npm doesn't install it from
+// its registry (specs.js npmRegistrySpec: a path, a repository, a URL),
+// whose package of that name isn't what it installs.
+export function npmDependencies(manifest) {
+  const rows = []
+  for (const [field, kind] of NPM_DEPENDENCY_KINDS) {
+    for (const [name, range] of Object.entries(manifest?.[field] ?? {})) {
+      const opens = npmAlias(range)?.name ?? name
+      rows.push({ name, range, kind, opens: isNpmPackageName(opens) && npmRegistrySpec(range) ? opens : null })
+    }
+  }
+  return rows.toSorted((a, b) => a.name.localeCompare(b.name) || (a.kind ?? '').localeCompare(b.kind ?? ''))
+}
+
+// What two versions' dependencies differ in, by name and kind: those only
+// `base` has, those only `other` has, and those whose range changed.
+export function npmDependencyChanges(base, other) {
+  const index = manifest => new Map(npmDependencies(manifest).map(row => [`${row.kind ?? ''}\0${row.name}`, row]))
+  const after = index(other), before = index(base)
+  const added = [], changed = [], removed = []
+  for (const [key, { name, kind, range, opens }] of before) {
+    const next = after.get(key)
+    if (!next) removed.push({ key, name, kind, range, opens })
+    else if (next.range !== range) changed.push({ key, name, kind, from: range, to: next.range, opens: next.opens })
+  }
+  for (const [key, { name, kind, range, opens }] of after) if (!before.has(key)) added.push({ key, name, kind, range, opens })
+  return { removed, added, changed }
+}
+
+// Files no import is read from: prose, as the Overview tells it
+// (readability.js NPM_PROSE; not code named alike, as
+// `lib/history.js`), but MDX, which imports what it renders; source maps,
+// which quote whatever their sources import, and lockfiles, which name every
+// package installed; nor the package's own package.json, which names them all.
+const MDX = /\.mdx$/iu
+const NO_IMPORTS = /(?:\.map|(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml))$/iu
+// A quote, then a run of the characters names and paths are made of (after
+// webpack's `~` too), and what ends it: a quote, escaped too, as a quote in
+// a quoted command is in binding.gyp (`require(\'nan\')`), or a template's `${`.
+const QUOTED = /["'`]~?([\w@./-]+)(\\?["'`]|\$\{)?/gu
+
+// What of a version names a package as an import would, once a version, in
+// one pass over its code files however many names are asked about: `whole`,
+// each name quoted alone or before a path in it (`'name'`, `"name/sub"`);
+// `parts`, each part of a name up to a `-` or `/` that a quote or a
+// template's `${` ends, as a package builds a name from one to pick the
+// build for the platform it runs on (`` `@rollup/rollup-${platform}` ``,
+// `"@typescript/" + name`); and `commands`, the install scripts npm runs.
+const importsByVersion = new WeakMap()
+function importsOf({ json, npm }) {
+  let found = importsByVersion.get(json)
+  if (found) return found
+  const sources = json.sources ?? [], texts = json.sourcesContent ?? []
+  found = { whole: new Set(), parts: new Set(), commands: npmInstallScripts(npm?.manifest, sources).map(([, command]) => command) }
+  for (const [i, path] of sources.entries()) {
+    if (typeof texts[i] !== 'string' || path === 'package.json' || (NPM_PROSE.test(path) && !MDX.test(path)) || NO_IMPORTS.test(path)) continue
+    for (const [, run, end] of texts[i].matchAll(QUOTED)) {
+      if (end && '-/'.includes(run.at(-1))) found.parts.add(run)
+      if (end && end !== '${') found.whole.add(run)
+      for (let at = run.indexOf('/'); at !== -1; at = run.indexOf('/', at + 1)) found.whole.add(run.slice(0, at))
+    }
+  }
+  importsByVersion.set(json, found)
+  return found
+}
+
+// Whether a command names `name`: as a word (`prebuild-install || node-gyp
+// rebuild`), or as the package installed in `node_modules` that a path
+// leads into (`node node_modules/name/setup.js`); not as part of another
+// path (`node scripts/name.js`, `node_modules/@scope/name`).
+function commandNames(command, name) {
+  for (let at = command.indexOf(name); at !== -1; at = command.indexOf(name, at + 1)) {
+    const before = command.slice(0, at)
+    if ((!/[\w@./-]$/u.test(before) || /node_modules\/(?:\.bin\/)?$/u.test(before)) && !/^[\w.-]/u.test(command.slice(at + name.length))) return true
+  }
+  return false
+}
+
+// DefinitelyTyped's stub of a package's types, once the package has types
+// of its own (`@types/mkdirp` 2.0.0), depending on that package, the
+// registry's by its name (`spec`, no `npm:` alias of another, no repository,
+// URL or path): named as DefinitelyTyped publishes the package's types
+// (`@types/name`, a scoped one's `@types/scope__name`), with nothing but
+// prose beside its package.json, no declarations of its own.
+const typesOf = name => `@types/${name.startsWith('@') ? name.slice(1).replace('/', '__') : name}`
+const typesStubOf = ({ json, npm }, name, spec) => npm?.name === typesOf(name) && npmRegistrySpec(spec) && (npmAlias(spec)?.name ?? name) === name
+  && (json.sources ?? []).every(path => path === 'package.json' || (NPM_PROSE.test(path) && !MDX.test(path)))
+
+// Whether nothing of a version (`details`, its files and manifest) imports
+// a dependency it names (`{ name, kind, range }`, or a changed one's `to`,
+// npm-package.js npmDependencies): no code file names it as an import
+// would, whole or by a part of it, nor does an install script npm runs
+// (importsOf); never where its files aren't read. Not a peer dependency,
+// which the package expects whoever installs it to provide, nor types from
+// DefinitelyTyped (`@types/`), imported by another name, where no one else
+// publishes; nor the package a stub of DefinitelyTyped's types of it
+// depends on (typesStubOf), with no code to import it.
+export function npmDependencyUnimported(details, { name, kind, range, to }) {
+  if (!details?.json || kind === 'peer' || name.startsWith('@types/') || typesStubOf(details, name, to ?? range)) return false
+  const { whole, parts, commands } = importsOf(details)
+  return !whole.has(name) && ![...name.slice(1).matchAll(/[-/]/gu)].some(({ index }) => parts.has(name.slice(0, index + 2)))
+    && !commands.some(command => commandNames(command, name))
+}
+
+// Where a source takes a dependency from, in a sentence.
+const SOURCE_NAMES = new Map([['URL', 'a URL'], ['git', 'a git repository']])
+
+// What calls for a look at a dependency a version (`details`) names
+// (`{ name, kind, range }`, or a changed one's `to`), as tags
+// (`{ check, label, tooltip }`): `source` where npm fetches it from
+// elsewhere than its registry (npmDependencySource), its spec in the
+// tooltip, and `unimported` where nothing of the version imports it
+// (npmDependencyUnimported). Against the specs another version named its
+// dependencies by (`was`, npmDependencySpecs), only where it named this one
+// by another spec, or, imported by nothing, not at all.
+export function npmDependencyFlags(details, row, was = null) {
+  const spec = row.to ?? row.range
+  const source = npmDependencySource(spec)
+  return [
+    ...source && was?.get(row.name) !== spec ? [{ check: 'source', label: 'non-registry', tooltip: `From ${SOURCE_NAMES.get(source) ?? source}, not npm's registry: ${spec}` }] : [],
+    ...!was?.has(row.name) && npmDependencyUnimported(details, row) ? [{ check: 'unimported', label: 'unimported',
+      tooltip: `${was ? `New in ${details.npm?.version}, and nothing of it` : `Nothing of ${details.npm?.version}`} imports it: no code file names it as an import would, nor does an install script` }] : [],
+  ]
+}
+
+// The specs a manifest names its dependencies by, by name, whatever their
+// kind.
+export const npmDependencySpecs = manifest => new Map(NPM_DEPENDENCY_KINDS.flatMap(([field]) => Object.entries(manifest?.[field] ?? {})))
+
+// Two versions' dependency changes (npm-package.js npmDependencyChanges),
+// each the open version (`other`) adds or changes with its `flags`
+// (npmDependencyFlags) against the one compared with (`base`), or alone,
+// none given.
+export function npmFlagDependencyChanges({ removed, added, changed }, base, other) {
+  const was = base ? npmDependencySpecs(base.npm?.manifest) : null
+  const flag = row => ({ ...row, flags: npmDependencyFlags(other, row, was) })
+  return { removed, added: added.map(flag), changed: changed.map(flag) }
+}

package/risk/npm/diff.js

@@ -0,0 +1,43 @@
+// How two versions' files differ, as Compare's diff has them
+// (ui/view/bundle-compare-diff.js computeBundleDiff), for risk's findings
+// (compare.js): the files the open version adds, and those it changes, a file
+// moved to another path paired with its old one by content, as git diff -M
+// pairs them (@preventive/compare compareTrees).
+import { compareTrees } from '@preventive/compare'
+import { bundleFilesAsMap } from '../../common/bundle-sources.js'
+
+// git's diff.renameLimit for a package's renames: past this many removed files
+// by added ones, squared, no pair is scored, and only identical content pairs
+// them.
+const RENAME_LIMIT = 250
+
+// Whether two sides hold the same file: text as text, one that isn't by its
+// digest (bundle-compare-diff.js sameContent).
+const same = (a, b) => a === b || (a?.format === 'digest' && b?.format === 'digest' && a.digest === b.digest)
+
+// A file's content as compareTrees reads it to find renames: its text, its
+// digest for one that isn't, or else its place in its list, so that only its
+// path pairs it (bundle-compare-diff.js treeData).
+const treeData = (content, at) => typeof content === 'string' ? `\0text\0${content.toWellFormed()}`
+  : content?.format === 'digest' ? `\0digest\0${content.digest}` : `\0none\0${at}`
+
+// `onlyOther`, the files the open version (`other`) adds, `{ path }` each, and
+// `changed`, those it changes, `{ path, modified }`, or moves, `{ path,
+// renamedFrom, modified }`, `modified` whether its content changed too; each
+// version as compare.js takes one. A file that isn't text is
+// told by its digest (npmBinaries), as the viewer's Compare tells it.
+export function npmFilesDiff(base, other) {
+  const after = bundleFilesAsMap(other), before = bundleFilesAsMap(base)
+  const changed = [], onlyBase = [], onlyOther = []
+  for (const [path, text] of after) {
+    if (!before.has(path)) onlyOther.push(path)
+    else if (!same(before.get(path), text)) changed.push({ path, modified: true })
+  }
+  for (const path of before.keys()) if (!after.has(path)) onlyBase.push(path)
+  const entries = (paths, files, side) => paths.filter(path => path.isWellFormed()).map((path, at) => ({ name: path, data: treeData(files.get(path), `${side}${at}`) }))
+  const renames = compareTrees(entries(onlyBase, before, 'a'), entries(onlyOther, after, 'b'), { paths: 'keys', renameLimit: RENAME_LIMIT, lines: false })
+    .filter(change => change.status === 'renamed')
+  const moved = new Set(renames.map(change => change.new.path))
+  for (const change of renames) changed.push({ path: change.new.path, renamedFrom: change.old.path, modified: change.similarity !== 100 })
+  return { onlyOther: onlyOther.filter(path => !moved.has(path)).map(path => ({ path })), changed }
+}

package/risk/npm/downloads.js

@@ -0,0 +1,84 @@
+// A package's downloads, as npm's downloads API counts them a day
+// (`{ start, end, days }`, the first day's date and a count a day from it):
+// in weeks and months, the tier among npm's packages they put it in, and a
+// dependency's to the day before its latest two weeks.
+
+export const DAY_MS = 24 * 60 * 60_000
+// The date `offset` days past a count's first day (`start`).
+export const dayOf = (start, offset) => new Date(Date.parse(start) + offset * DAY_MS)
+
+// The downloads in 7-day weeks ending on the last day, oldest first, a
+// partial oldest week left out: `{ from, to, total }`, dates as `Date`s.
+export function npmDownloadWeeks(downloads) {
+  const weeks = []
+  if (!downloads?.days) return weeks
+  for (let end = downloads.days.length - 1; end >= 6; end -= 7) {
+    let total = 0
+    for (let day = end - 6; day <= end; day++) total += downloads.days[day]
+    weeks.push({ from: dayOf(downloads.start, end - 6), to: dayOf(downloads.start, end), total })
+  }
+  return weeks.toReversed()
+}
+
+// The downloads in calendar months (UTC), oldest first, the partial months
+// at either end left out: `{ from, to, total }`, as npmDownloadWeeks has them.
+export function npmDownloadMonths(downloads) {
+  const months = []
+  if (!downloads?.days) return months
+  const start = Date.parse(downloads.start)
+  let month = null
+  downloads.days.forEach((count, i) => {
+    const day = new Date(start + i * DAY_MS)
+    if (day.getUTCDate() === 1) {
+      month = { from: day, to: day, total: 0 }
+      months.push(month)
+    }
+    if (month) { month.total += count; month.to = day }
+  })
+  const last = months.at(-1)
+  if (last && new Date(last.to.getTime() + DAY_MS).getUTCDate() !== 1) months.pop()
+  return months
+}
+
+// The weekly downloads from which a package is among npm's top 10, 20, 50,
+// 100, …, 100,000 packages, rounded: download-counts' snapshot of a month's
+// downloads (Jan 30 – Feb 28, 2026), each rank's count grown by the median
+// growth of the packages ranked around it to the 30 days Sep 9 – Oct 8,
+// 2026, as npm counts them, days it failed to count among them, then made a
+// week. An estimate, to be revisited. Below the last, a package is
+// unpopular (Infinity).
+const TIERS = [
+  [10, 550e6], [20, 405e6], [50, 285e6], [100, 225e6], [200, 165e6], [500, 95e6], [1000, 50e6], [2000, 20e6], [5000, 4e6],
+  [10_000, 850e3], [20_000, 155e3], [50_000, 18e3], [100_000, 2e3], [Infinity, 0],
+]
+
+// The tier a package's downloads put it in (TIERS), by the most it had in any
+// of its latest six 7-day weeks (npmDownloadWeeks): a week lower for a day
+// npm failed to count, as it now and then does, or for a holiday, is passed
+// over. Infinity for an unpopular one; null without a week.
+export function npmDownloadTier(downloads) {
+  const latest = npmDownloadWeeks(downloads).slice(-6)
+  if (latest.length === 0) return null
+  const most = Math.max(...latest.map(week => week.total))
+  return TIERS.find(([, from]) => most >= from)[0]
+}
+
+// A tier's name, and its tint: solid green to the top 200, green to the top
+// 5,000, yellow to the top 20,000, orange to the top 100,000, and red for
+// the unpopular, a package few would notice changing.
+export const npmTierLevel = tier => tier <= 200 ? 'is-solid' : tier <= 5000 ? 'is-top' : tier <= 20_000 ? 'is-mid' : tier <= 100_000 ? 'is-low' : 'is-unpopular'
+// A dependency's downloads to the day before its latest two weeks: a
+// package a release just pulled in, as a compromised one depending on it
+// would, could owe those to that release alone. Its own package's tier goes
+// by all of them, its Overview charting them.
+const DEPENDENCY_DAYS_LEFT_OUT = 14
+export function npmSettledDownloads(downloads, now = Date.now()) {
+  if (!downloads) return null
+  const first = Math.floor(Date.parse(downloads.start) / DAY_MS), last = Math.floor(now / DAY_MS) - 1 - DEPENDENCY_DAYS_LEFT_OUT
+  const days = downloads.days.slice(0, Math.max(0, last - first + 1))
+  return { start: downloads.start, end: new Date((first + days.length - 1) * DAY_MS).toISOString().slice(0, 10), days }
+}
+
+// A tier orange or red, past the top 20,000: one few would notice changing,
+// as a release past the top 20,000 is flagged (compare.js).
+export const npmTierLow = tier => tier > 20_000

package/risk/npm/files.js

@@ -0,0 +1,34 @@
+// What risk reads of each file of a version, once a version (stamps.js
+// npmFileRisk), and every host its scripts name: for compare.js's findings
+// and held.js's, and for the viewer, which reads its files' tags from it.
+import { bundleFileSizes, bundleFilesAsMap } from '../../common/bundle-sources.js'
+import { npmFileRisk } from '../files/stamps.js'
+
+// What a version's files are kept by: its bundle where it is one, else its
+// files' list, else itself.
+const keyOf = version => version.bundle ?? version.json ?? version
+
+// What risk reads of each file of a version (stamps.js npmFileRisk), once a
+// version and path.
+const reads = new WeakMap()
+export function npmVersionFileRisk(version, path) {
+  let files = reads.get(keyOf(version))
+  if (!files) reads.set(keyOf(version), files = new Map())
+  if (!files.has(path)) {
+    const text = bundleFilesAsMap(version).get(path)
+    files.set(path, npmFileRisk(path, typeof text === 'string' ? text : null, bundleFileSizes(version).get(path)))
+  }
+  return files.get(path)
+}
+
+// Every host a version's scripts name (hosts.js npmHosts), once a version.
+const versionHosts = new WeakMap()
+export function npmVersionHosts(version) {
+  let hosts = versionHosts.get(keyOf(version))
+  if (!hosts) {
+    hosts = new Set()
+    for (const path of bundleFilesAsMap(version).keys()) for (const host of npmVersionFileRisk(version, path).hosts?.keys() ?? []) hosts.add(host)
+    versionHosts.set(keyOf(version), hosts)
+  }
+  return hosts
+}

package/risk/npm/held.js

@@ -0,0 +1,60 @@
+// What calls for a look at a version on its own, as the npm Overview shows
+// it: what npm says of it and when it was published (npmVersionFindings),
+// and what it holds that calls for a look whatever came before it
+// (npmHeldFindings), as Compare's findings (compare.js) say what changed.
+import { bundleFilesAsMap } from '../../common/bundle-sources.js'
+import { npmDownloadTier, npmTierLevel, npmTierLow } from './downloads.js'
+import { npmInstallScripts } from './install-scripts.js'
+import { npmTooNew } from './release.js'
+import { HOST_TAGS, npmHostsTagged } from '../files/hosts.js'
+import { npmVersionFileRisk } from './files.js'
+
+// What npm says of a version and of its package, told fresh as it changes in
+// time: deprecated, `deprecated` its message (`deprecated`, red); younger
+// than `minimumReleaseAge` at `now`, published at `published` (release.js
+// npmTooNew, `too-new`, orange); and its package past the top 20,000 by
+// `downloads` (downloads.js, `popularity`, red where unpopular, else orange),
+// `tier` its rank (Infinity past the last); yellow at most, whatever its
+// tier, where an account known to publish one of npm's most downloaded
+// packages published the version (`known`, manifest.js `knownAccounts`), as
+// few download a new package such an account starts; or else, as many are
+// published by a CI that names no account, where the version was published
+// with provenance (`provenance`, manifest.js), built where it says, as a
+// token alone, stolen, publishes none, and the package is in a known scope
+// (`scope`, manifest.js npmKnownScope: one of those packages', or one of
+// those accounts' own, its `account` named), whose owner alone publishes in
+// it.
+export function npmVersionFindings({ deprecated, published, minimumReleaseAge, now, downloads, known = false, scope = null, provenance = false }) {
+  const tier = downloads ? npmDownloadTier(downloads) : null
+  const scoped = provenance ? scope : null
+  const severity = known || scoped ? 'moderate' : npmTierLevel(tier) === 'is-unpopular' ? 'critical' : 'high'
+  return [
+    ...deprecated ? [{ id: 'deprecated', severity: 'critical', message: deprecated }] : [],
+    ...published && npmTooNew(published, { minimumReleaseAge, now }) ? [{ id: 'too-new', severity: 'high', published }] : [],
+    ...tier !== null && npmTierLow(tier) ? [{ id: 'popularity', severity, tier, ...known ? { known } : scoped ? { known: true, ...scoped } : {} }] : [],
+  ]
+}
+
+// What a version holds that calls for a look, whatever came before it, in
+// orange, as its files' tags are: the scripts npm runs installing it
+// (install-scripts.js, `held-install-scripts`, `[script, command]` each); and
+// its files, each with what it holds, that run code beyond themselves
+// (`held-runs-code`), name a service under one of the hosts' tags, at the
+// tag's severity (hosts.js HOST_TAGS: `held-exfiltration` red, `held-remote`
+// orange, `held-ip-lookup` yellow), or bear an obfuscator's fingerprint
+// (`held-obfuscated`).
+export function npmHeldFindings(version) {
+  const scripts = npmInstallScripts(version.npm.manifest, version.json?.sources)
+  const reads = [...bundleFilesAsMap(version).keys()].map(path => ({ path, read: npmVersionFileRisk(version, path) }))
+  const holding = of => reads.map(({ path, read }) => ({ path, found: of(read) })).filter(row => row.found)
+  return [
+    ...scripts.length > 0 ? [{ id: 'held-install-scripts', severity: 'high', scripts }] : [],
+    { id: 'held-runs-code', severity: 'high', files: holding(read => read.runsCode) },
+    ...[...HOST_TAGS].map(([tag, severity]) => ({ id: `held-${npmHostFinding(tag)}`, severity, files: holding(read => npmHostsTagged(read.exfiltration, tag)) })),
+    { id: 'held-obfuscated', severity: 'high', files: holding(read => read.readability.obfuscation) },
+  ].filter(finding => !finding.files || finding.files.length > 0)
+}
+
+// A hosts' tag's finding, as its id names it: `exfiltration`, `remote`,
+// `ip-lookup`.
+export const npmHostFinding = tag => tag.toLowerCase().replaceAll(' ', '-')

package/risk/npm/install-scripts.js

@@ -0,0 +1,33 @@
+// The scripts npm runs as it installs a package: what release.js flags added
+// or changed, and the npm viewer lists (its Overview, and Compare's tags on a
+// package.json).
+
+// The scripts npm runs installing a package from the registry, in the order
+// it runs them; not `prepare`, which runs only for a local or git install.
+export const INSTALL_SCRIPTS = ['preinstall', 'install', 'postinstall']
+
+// A package's install scripts, `[script, command]`, in the order npm runs
+// them: those `scripts` names, and `node-gyp rebuild` where the package has
+// a `binding.gyp` at its root (`bindingGyp`) and neither install script of
+// its own, as npm runs then.
+export function installScripts(scripts, bindingGyp = false) {
+  const named = { ...scripts }
+  if (!named.preinstall && !named.install && bindingGyp) named.install = 'node-gyp rebuild'
+  return INSTALL_SCRIPTS.filter(script => typeof named[script] === 'string').map(script => [script, named[script]])
+}
+
+// An npm version's install scripts: those its manifest's `installScripts`
+// names, and node-gyp's where `paths`, its files' (a list or a set), have a
+// binding.gyp at its root.
+export function npmInstallScripts(manifest, paths = []) {
+  return installScripts(manifest?.installScripts, Boolean(paths && (paths instanceof Set ? paths.has('binding.gyp') : paths.includes('binding.gyp'))))
+}
+
+// A package.json's install scripts, from its text; none where it isn't one,
+// or names none.
+export function packageJsonInstallScripts(text, bindingGyp = false) {
+  let json = null
+  try { json = typeof text === 'string' ? JSON.parse(text) : null } catch {}
+  const scripts = json && typeof json === 'object' && json.scripts && typeof json.scripts === 'object' ? json.scripts : {}
+  return installScripts(scripts, bindingGyp)
+}