dsh-plugin-inspector 0.1.0 → 0.2.0

package/lib/checks/tier-c.js

@@ -33,7 +33,7 @@ const NAMED_TARGET_CALLEES = new Set([
  * @returns the complete finding.
  */
 function tierC(finding) {
-    return { ...finding, tier: 'C', confidence: 'moderate' };
+    return { ...finding, tier: 'C', confidence: 'moderate', examples: [finding.evidence], occurrences: 1 };
 }
 /** C1 — source that is not written to be read. */
 function checkMinification(input) {
@@ -57,12 +57,13 @@ function checkMinification(input) {
         findings.push(tierC({
             checkId: 'C1',
             name: 'minified-source',
+            subject: 'minified-source',
             severity: 'medium',
-            title: `\`${path}\` is minified or generated`,
-            detail: `Longest line is ${longest} characters across ${lines.length} line(s), and lines that long are `
-                + `${Math.round(longBytes * 100 / Math.max(text.length, 1))}% of the file. Capability detection reads `
-                + 'syntax, and it reads minified syntax no better than a person does. Every Tier B negative for this '
-                + 'package is unreliable while this file is in it.',
+            title: 'Ships source that is minified or generated',
+            detail: `In \`${path}\` the longest line is ${longest} characters across ${lines.length} line(s), and lines `
+                + `that long are ${Math.round(longBytes * 100 / Math.max(text.length, 1))}% of the file. Capability `
+                + 'detection reads syntax, and it reads minified syntax no better than a person does. Every Tier B '
+                + 'negative for this package is unreliable while a file like this is in it.',
             evidence: { file: path, path: '1:1', snippet: snippet(lines[0] ?? '') },
             bypass: 'none — this finding is about the analysis, not about the plugin',
         }));
@@ -81,8 +82,9 @@ function checkDynamicDispatch(input) {
             findings.push(tierC({
                 checkId: 'C2',
                 name: 'dynamic-dispatch',
+                subject: what,
                 severity: 'high',
-                title: `\`${path}\` ${what}`,
+                title: `Shipped source ${what}`,
                 detail: 'Every Tier B check matches a literal name. A name assembled at runtime defeats all of them, so no '
                     + 'Tier B negative for this package carries any information. A Tier B positive still does — the tool saw '
                     + 'what it saw.',
@@ -209,6 +211,7 @@ function checkSourcelessBuild(input) {
         findings.push(tierC({
             checkId: 'C3',
             name: 'sourceless-build-output',
+            subject: 'no-authored-source',
             severity: 'low',
             title: `Ships ${built.length} built file(s) and no source`,
             detail: 'What runs is the built output, so that is what this tool analysed — but there is nothing in the '
@@ -222,8 +225,9 @@ function checkSourcelessBuild(input) {
         findings.push(tierC({
             checkId: 'C6',
             name: 'minified-artifact',
+            subject: 'min-js',
             severity: 'low',
-            title: `\`${path}\` is a minified artifact`,
+            title: 'Ships a minified artifact',
             detail: 'A `.min.js` file is output, not source. It was still parsed, but nothing about its readability '
                 + 'supports a confident negative.',
             evidence: { file: path },
@@ -244,6 +248,7 @@ function checkUnreadableFiles(input) {
     return [...byReason].map(([reason, paths]) => tierC({
         checkId: 'C4',
         name: 'unreadable-payload',
+        subject: reason,
         severity: reason === 'binary' ? 'medium' : 'low',
         title: `${paths.length} file(s) were not analysed (${reason})`,
         detail: reason === 'binary'
@@ -259,6 +264,7 @@ function checkPatchWalkLimit(input) {
     return input.patches.filter(patch => patch.limit !== null).map(patch => tierC({
         checkId: 'C5',
         name: 'patch-walk-truncated',
+        subject: patch.file,
         severity: 'high',
         title: `\`${patch.file}\` was only read in part (${patch.limit === 'depth' ? 'nesting' : 'node count'} ceiling)`,
         detail: patch.limit === 'depth'

package/lib/cli.js

@@ -11,6 +11,8 @@
 import process from 'node:process';
 import { exceedsThreshold, inspect, TOOL_VERSION } from "./inspect.js";
 import { SEVERITY_RANK } from "./model.js";
+import { inspectFromNpm } from "./npm.js";
+import { DEFAULT_REGISTRY } from "./registry.js";
 import { renderHuman, renderJson } from "./report.js";
 /** Exit codes this tool uses. */
 export const EXIT = {
@@ -22,11 +24,18 @@ const USAGE = `dsh-inspect — know what a DeepSeek Harness plugin does before y
 
 Usage
   dsh-inspect <target> [options]
+  dsh-inspect --from-npm <name>[@<version>] [options]
 
   <target>                A plugin directory, or an npm tarball (.tgz / .tar.gz).
                           Nothing in the target is installed, built, or executed.
 
 Options
+  --from-npm <spec>       Fetch a published package from the registry, verify its
+                          dist.integrity hash, and analyse it in memory. This is
+                          the only mode that opens a socket, and it never runs
+                          npm, writes to disk, or executes an install script.
+  --registry <url>        Registry base URL for --from-npm.
+                          (default: ${DEFAULT_REGISTRY})
   --json                  Emit the machine-readable JSON document on stdout.
   --fail-on <severity>    Exit 1 at or above this severity.
                           critical | high | medium | low | none    (default: high)
@@ -40,7 +49,7 @@ Exit codes
   2  analysis could not be performed
 
 To inspect a published package without installing it:
-  npm pack <name>@<version> --pack-destination /tmp && dsh-inspect /tmp/<name>-<version>.tgz
+  dsh-inspect --from-npm <name>@<version>
 `;
 /** Raised for a malformed command line; the message is printed and the tool exits 2. */
 export class UsageError extends Error {
@@ -53,9 +62,23 @@ export class UsageError extends Error {
  */
 export function parseArgs(argv) {
     let target = null;
+    let fromNpm = null;
+    let registry = DEFAULT_REGISTRY;
     let json = false;
     let failOn = 'high';
     let color = process.stdout.isTTY === true;
+    /**
+     * Read the value of an option that takes one.
+     * @param index - the option's own position in argv.
+     * @param option - the option name, for the error message.
+     * @returns the value.
+     */
+    const value = (index, option) => {
+        const next = argv[index + 1];
+        if (next === undefined)
+            throw new UsageError(`${option} needs a value`);
+        return next;
+    };
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index] ?? '';
         if (argument === '--help' || argument === '-h') {
@@ -78,15 +101,25 @@ export function parseArgs(argv) {
             color = true;
             continue;
         }
+        if (argument === '--from-npm') {
+            if (fromNpm !== null)
+                throw new UsageError('only one package may be fetched at a time');
+            fromNpm = value(index, '--from-npm');
+            index += 1;
+            continue;
+        }
+        if (argument === '--registry') {
+            registry = value(index, '--registry');
+            index += 1;
+            continue;
+        }
         if (argument === '--fail-on') {
-            const value = argv[index + 1];
+            const severity = value(index, '--fail-on');
             index += 1;
-            if (value === undefined)
-                throw new UsageError('--fail-on needs a severity');
-            if (value !== 'none' && !(value in SEVERITY_RANK)) {
-                throw new UsageError(`--fail-on must be one of critical, high, medium, low, none — got ${value}`);
+            if (severity !== 'none' && !(severity in SEVERITY_RANK)) {
+                throw new UsageError(`--fail-on must be one of critical, high, medium, low, none — got ${severity}`);
             }
-            failOn = value;
+            failOn = severity;
             continue;
         }
         if (argument.startsWith('-'))
@@ -95,9 +128,18 @@ export function parseArgs(argv) {
             throw new UsageError('only one target may be inspected at a time');
         target = argument;
     }
+    // Fetching is opt-in per invocation and never a fallback: a mistyped path
+    // must not become a registry lookup, and a registry spec must not silently
+    // shadow a local directory of the same name.
+    if (target !== null && fromNpm !== null) {
+        throw new UsageError('--from-npm fetches a published package; it cannot be combined with a local target');
+    }
+    const common = { registry, json, failOn, color };
+    if (fromNpm !== null)
+        return { ...common, target: null, fromNpm };
     if (target === null)
-        throw new UsageError('a target directory or tarball is required');
-    return { target, json, failOn, color };
+        throw new UsageError('a target directory or tarball is required, or --from-npm <name>');
+    return { ...common, target, fromNpm: null };
 }
 /**
  * Run one invocation.
@@ -116,7 +158,9 @@ export async function main(argv) {
     if (options === null)
         return EXIT.clean;
     try {
-        const report = await inspect(options.target);
+        const report = options.fromNpm === null
+            ? await inspect(options.target)
+            : await inspectFromNpm(options.fromNpm, { registry: options.registry });
         process.stdout.write(options.json ? renderJson(report) : renderHuman(report, options.color));
         return exceedsThreshold(report, options.failOn) ? EXIT.findings : EXIT.clean;
     }

package/lib/index.js

@@ -11,12 +11,14 @@
  * The ceiling is triage, not containment. See `README.md` §Limitations.
  * @module dsh-plugin-inspector
  */
-export { exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from "./inspect.js";
+export { analyze, exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from "./inspect.js";
+export { inspectFromNpm, precheck } from "./npm.js";
+export { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, verifyIntegrity, } from "./registry.js";
 export { renderHuman, renderJson } from "./report.js";
 export { classifyExpression, isJsExpr, parsePatchDocument, patchSchema, PatchParseError, } from "./cordis-yaml.js";
 export { declaredPackages, ManifestError, parseManifest } from "./manifest.js";
-export { DEFAULT_LIMITS, loadSource, SourceError } from "./source.js";
+export { DEFAULT_LIMITS, loadSource, loadTarballBuffer, SourceError, } from "./source.js";
 export { globMatch, publishSet } from "./publish.js";
 export { INJECTION_RULES, scanInjection } from "./injection.js";
-export { compareFindings, SEVERITIES, SEVERITY_RANK, summarize, } from "./model.js";
+export { aggregateFindings, compareFindings, MAX_EXAMPLES, SEVERITIES, SEVERITY_RANK, summarize, } from "./model.js";
 export { CORE_ROWS, CORE_ROW_IDS, HARNESS_BUNDLE_PACKAGES, HARNESS_REFERENCE, SEAM_KEYS, SECURITY_ROW_IDS, WATERFALL_EVENTS, } from "./knowledge.js";

package/lib/inspect.js

@@ -13,7 +13,7 @@ import { EXPRESSION_CLASSES, PatchParseError, parsePatchDocument, } from "./cord
 import { isCordisConfigFile, isModelVisibleText, isSourceFile, normalizePackagePath } from "./files.js";
 import { HARNESS_REFERENCE } from "./knowledge.js";
 import { parseManifest } from "./manifest.js";
-import { SEVERITY_RANK, compareFindings, summarize, } from "./model.js";
+import { SEVERITY_RANK, aggregateFindings, compareFindings, summarize, } from "./model.js";
 import { loadSource } from "./source.js";
 import { runTierA } from "./checks/tier-a.js";
 import { runTierB } from "./checks/tier-b.js";
@@ -69,13 +69,26 @@ function downgrade(confidence, degraded) {
     return 'moderate';
 }
 /**
- * Inspect a plugin package.
+ * Inspect a plugin package on disk.
+ *
+ * Nothing on this path opens a socket: neither this module nor anything it
+ * imports can reach the registry, which is what makes "a directory or tarball
+ * scan never fetches" structural rather than a promise.
  * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.
  * @returns the complete report.
  * @throws SourceError or ManifestError when the target cannot be analysed at all.
  */
 export async function inspect(target) {
-    const source = await loadSource(target);
+    return analyze(await loadSource(target));
+}
+/**
+ * Run every check over an already-decoded package.
+ * @param source - the decoded package.
+ * @param registry - provenance, when the bytes were fetched from a registry.
+ * @returns the complete report.
+ * @throws ManifestError when the manifest cannot be read.
+ */
+export function analyze(source, registry) {
     const manifest = parseManifest(source.files.get('package.json') ?? '');
     const declared = manifest.dsh.bundle?.patch;
     const mountsAsBundle = declared !== undefined;
@@ -114,7 +127,10 @@ export async function inspect(target) {
         ...runTierB(input).map(finding => ({ ...finding, confidence: downgrade(finding.confidence, degraded) })),
         ...tierC,
     ];
-    const findings = [...raw].sort(compareFindings);
+    // Aggregate before sorting: the report is a list of decisions, one per check
+    // per subject, and the count travels inside the finding. A package importing
+    // `node:fs` from eleven files states that once.
+    const findings = aggregateFindings(raw).sort(compareFindings);
     const facts = {
         packageName: manifest.name,
         packageVersion: manifest.version,
@@ -141,9 +157,9 @@ export async function inspect(target) {
         unpublishedFiles: source.unpublishedFiles,
     };
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         tool: { name: TOOL_NAME, version: TOOL_VERSION, harnessReference: HARNESS_REFERENCE },
-        target: { kind: source.kind, path: source.path },
+        target: { kind: source.kind, path: source.path, ...registry === undefined ? {} : { registry } },
         facts,
         analysis: {
             integrity: degraded ? 'degraded' : 'complete',

package/lib/npm.js

@@ -0,0 +1,58 @@
+/**
+ * `--from-npm` — inspecting a published package without installing it.
+ *
+ * This module is the only path in the tool that reaches a network, and it is
+ * separate from `inspect.ts` on purpose: a directory or tarball scan cannot
+ * arrive here, because nothing on that path imports this file. The steps are
+ * fixed and their order is the guarantee:
+ *
+ * 1. read the version document (~3 KB) — which already answers
+ *    `hasInstallScript`, the install lifecycle scripts, and `dsh.bundle`;
+ * 2. download the tarball into memory;
+ * 3. verify `dist.integrity` **before** anything parses a byte of it;
+ * 4. decode in memory and analyse, exactly as the tarball path does.
+ *
+ * No subprocess, no disk write, no lifecycle script, and no `npm pack`.
+ * @module dsh-plugin-inspector/npm
+ */
+import { analyze } from "./inspect.js";
+import { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, resolvePackage, } from "./registry.js";
+import { loadTarballBuffer } from "./source.js";
+/**
+ * The metadata pre-check, which needs no tarball.
+ *
+ * A caller sweeping many packages can read this for each of them at a few
+ * kilobytes apiece and decide which ones are worth downloading.
+ * @param spec - `<name>` or `<name>@<version>`.
+ * @param options - where to fetch from.
+ * @returns what the version document says.
+ * @throws RegistryError when the package or version does not resolve.
+ */
+export async function precheck(spec, options = {}) {
+    return resolvePackage(parseSpec(spec), options);
+}
+/**
+ * Fetch a published package and inspect it in memory.
+ * @param spec - `<name>` or `<name>@<version>`; no version means the `latest` tag.
+ * @param options - where to fetch from.
+ * @returns the complete report, carrying the registry provenance.
+ * @throws RegistryError when the package cannot be resolved, fetched, or verified.
+ * @throws SourceError or ManifestError when the fetched tarball is not a package.
+ */
+export async function inspectFromNpm(spec, options = {}) {
+    const resolved = await precheck(spec, options);
+    const verified = await fetchVerifiedTarball(resolved, options);
+    const provenance = {
+        spec,
+        registry: (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, ''),
+        resolvedVersion: resolved.version,
+        tarball: resolved.tarball,
+        digest: verified.digest,
+        algorithm: verified.algorithm,
+        hasInstallScript: resolved.hasInstallScript,
+        metadataBytes: resolved.metadataBytes,
+        tarballBytes: verified.bytes.byteLength,
+    };
+    const source = await loadTarballBuffer(verified.bytes, `npm:${resolved.name}@${resolved.version}`);
+    return analyze(source, provenance);
+}

package/lib/registry.js

@@ -0,0 +1,261 @@
+/**
+ * Fetching a published package from an npm registry, and proving the bytes are
+ * the ones the registry vouched for.
+ *
+ * This is the one module in the tool that opens a socket, and it exists behind
+ * one explicit flag. A network fetch is not execution — nothing here installs,
+ * unpacks to disk, or runs a lifecycle script — but it is a side effect the
+ * tool's other two modes do not have, so it is never reached implicitly: a
+ * directory or tarball scan cannot get here, because neither imports this
+ * module.
+ *
+ * The order of operations is the security property. The packument is read
+ * first, which is ~3 KB and already answers `hasInstallScript`, the install
+ * lifecycle scripts, and whether the package declares `dsh.bundle` — a
+ * pre-check that needs no tarball at all. Only then is the tarball fetched, and
+ * its `dist.integrity` hash is verified **before** any byte of it reaches the
+ * tar parser. A hash mismatch is a refusal, not a warning: the whole point of
+ * the mode is that the analysed bytes are the published bytes.
+ * @module dsh-plugin-inspector/registry
+ */
+import { createHash } from 'node:crypto';
+import { INSTALL_LIFECYCLE_SCRIPTS } from "./knowledge.js";
+import { MAX_TOTAL_BYTES } from "./source.js";
+/** The public npm registry, used when no other is named. */
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/** Largest packument the tool will read. A version document is a few kilobytes. */
+export const MAX_METADATA_BYTES = 4 * 1024 * 1024;
+/**
+ * Largest compressed tarball the tool will download. The decompressed stream is
+ * capped separately, and lower, by the tar reader.
+ */
+export const MAX_TARBALL_BYTES = MAX_TOTAL_BYTES;
+/** Hash algorithms accepted in a Subresource Integrity string, weakest last. */
+const SRI_ALGORITHMS = new Set(['sha512', 'sha384', 'sha256']);
+/**
+ * npm package names, as the registry accepts them. Validated because the name
+ * is interpolated into a URL: `../` in a package name is a request for a
+ * different endpoint, and a `http://…` "name" is a request to a different host.
+ */
+const PACKAGE_NAME = /^(?:@[a-z0-9~][a-z0-9-._~]*\/)?[a-z0-9~][a-z0-9-._~]*$/;
+/** Versions and dist-tags, as they may appear after the `@` in a spec. */
+const VERSION_OR_TAG = /^[A-Za-z0-9][A-Za-z0-9-._+]*$/;
+/** Thrown when a package cannot be resolved, fetched, or verified. */
+export class RegistryError extends Error {
+}
+/**
+ * Split a `<name>` or `<name>@<version>` argument.
+ *
+ * The `@` that starts a scope is not a separator, so `@scope/name` has no
+ * version and `@scope/name@1.2.3` has one.
+ * @param spec - the argument as typed.
+ * @returns the package name and the requested version, if any.
+ * @throws RegistryError when the name or version is not one the registry accepts.
+ */
+export function parseSpec(spec) {
+    const separator = spec.lastIndexOf('@');
+    const split = separator > 0;
+    const name = split ? spec.slice(0, separator) : spec;
+    const version = split ? spec.slice(separator + 1) : null;
+    if (!PACKAGE_NAME.test(name))
+        throw new RegistryError(`not an npm package name: ${spec}`);
+    if (version !== null && !VERSION_OR_TAG.test(version)) {
+        throw new RegistryError(`not a version or dist-tag: ${version}`);
+    }
+    return { name, version };
+}
+/**
+ * Read one response body under a ceiling, without materialising more than the
+ * ceiling allows. A registry that streams forever is a hang, and a hang in a
+ * gate is a denial of service.
+ * @param response - the fetch response.
+ * @param limit - the ceiling in bytes.
+ * @param what - what is being read, for the error message.
+ * @returns the body.
+ * @throws RegistryError when the body passes the ceiling.
+ */
+async function readCapped(response, limit, what) {
+    const body = response.body;
+    if (body === null)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        total += chunk.byteLength;
+        if (total > limit)
+            throw new RegistryError(`${what} is larger than ${limit} bytes`);
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * GET a URL, failing loud on anything but a 2xx.
+ * @param url - the absolute URL.
+ * @param accept - the Accept header.
+ * @param options - registry options carrying the fetch implementation.
+ * @returns the response.
+ * @throws RegistryError on a transport failure or a non-2xx status.
+ */
+async function get(url, accept, options) {
+    const call = options.fetch ?? globalThis.fetch;
+    let response;
+    try {
+        response = await call(url, { headers: { accept, 'user-agent': 'dsh-plugin-inspector' } });
+    }
+    catch (error) {
+        throw new RegistryError(`cannot reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new RegistryError(`${url} returned HTTP ${response.status}`);
+    return response;
+}
+/**
+ * Read the packument for one version, which is the pre-check.
+ * @param spec - the package name and requested version.
+ * @param options - where to fetch from.
+ * @returns everything the metadata says, including the tarball URL and its hash.
+ * @throws RegistryError when the package or version does not resolve, or when
+ * the document does not carry a tarball URL on the registry's own origin.
+ */
+export async function resolvePackage(spec, options = {}) {
+    const registry = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
+    const url = `${registry}/${spec.name}/${encodeURIComponent(spec.version ?? 'latest')}`;
+    const response = await get(url, 'application/json', options);
+    const body = await readCapped(response, MAX_METADATA_BYTES, 'package metadata');
+    let document;
+    try {
+        document = JSON.parse(body.toString('utf8'));
+    }
+    catch (error) {
+        throw new RegistryError(`${url} did not return JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const record = asRecord(document);
+    const dist = asRecord(record.dist);
+    const tarball = typeof dist.tarball === 'string' ? dist.tarball : null;
+    if (tarball === null)
+        throw new RegistryError(`${url} carries no dist.tarball`);
+    assertSameOrigin(tarball, registry);
+    const scripts = asRecord(record.scripts);
+    const dsh = asRecord(record.dsh);
+    const bundle = asRecord(dsh.bundle);
+    return {
+        name: typeof record.name === 'string' ? record.name : spec.name,
+        version: typeof record.version === 'string' ? record.version : (spec.version ?? 'latest'),
+        tarball,
+        integrity: typeof dist.integrity === 'string' ? dist.integrity : null,
+        shasum: typeof dist.shasum === 'string' ? dist.shasum : null,
+        hasInstallScript: record.hasInstallScript === true,
+        lifecycleScripts: INSTALL_LIFECYCLE_SCRIPTS.filter(name => typeof scripts[name] === 'string'),
+        bundlePatch: typeof bundle.patch === 'string' ? bundle.patch : null,
+        metadataBytes: body.byteLength,
+    };
+}
+/**
+ * Narrow an unknown JSON value to a record, so a hostile document's `dist: 7`
+ * reads as "no fields" rather than throwing somewhere further down.
+ * @param value - the parsed JSON value.
+ * @returns the value as a record, or an empty one.
+ */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Refuse a tarball URL that points somewhere other than the registry that
+ * described it.
+ *
+ * The integrity hash comes from the same document as the URL, so a hostile
+ * registry can always make the two agree — this does not defend against that.
+ * What it does refuse is a single doctored packument on an honest registry
+ * pointing the download at a host of the attacker's choosing, which would make
+ * the tool fetch an arbitrary URL on the user's behalf.
+ * @param tarball - the declared tarball URL.
+ * @param registry - the registry base URL.
+ * @throws RegistryError when the origins differ or the URL is not http(s).
+ */
+function assertSameOrigin(tarball, registry) {
+    let url;
+    let base;
+    try {
+        url = new URL(tarball);
+        base = new URL(registry);
+    }
+    catch {
+        throw new RegistryError(`dist.tarball is not a URL: ${tarball}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new RegistryError(`dist.tarball is not an http(s) URL: ${tarball}`);
+    }
+    if (url.origin !== base.origin) {
+        throw new RegistryError(`dist.tarball ${tarball} is not on the registry's origin ${base.origin}`);
+    }
+}
+/**
+ * Check downloaded bytes against what the registry published.
+ *
+ * `dist.integrity` is preferred and is a real check. `dist.shasum` is SHA-1 and
+ * is accepted only when there is no `integrity` field at all, which happens on
+ * packages published before npm 5; it is recorded in the report as the weaker
+ * check it is. No digest at all is a refusal, because "verified" would then be
+ * a claim the tool cannot make.
+ * @param bytes - the downloaded tarball.
+ * @param resolved - what the packument said about it.
+ * @returns the algorithm and digest that matched.
+ * @throws RegistryError on a mismatch, an unusable digest, or no digest at all.
+ */
+export function verifyIntegrity(bytes, resolved) {
+    if (resolved.integrity !== null) {
+        // An `integrity` field may carry several space-separated digests. One
+        // matching digest in a recognised algorithm is the check; an unrecognised
+        // algorithm is not silently ignored, it just is not a match.
+        for (const entry of resolved.integrity.trim().split(/\s+/)) {
+            const dash = entry.indexOf('-');
+            const algorithm = dash < 0 ? '' : entry.slice(0, dash);
+            if (!SRI_ALGORITHMS.has(algorithm))
+                continue;
+            const expected = entry.slice(dash + 1);
+            const actual = digest(algorithm, bytes, 'base64');
+            if (actual !== expected) {
+                throw new RegistryError(`integrity check failed for ${resolved.name}@${resolved.version}: `
+                    + `registry published ${algorithm}-${expected}, downloaded bytes are ${algorithm}-${actual}`);
+            }
+            return { bytes, algorithm, digest: entry };
+        }
+        throw new RegistryError(`no usable digest in dist.integrity for ${resolved.name}@${resolved.version}: ${resolved.integrity}`);
+    }
+    if (resolved.shasum !== null) {
+        const actual = digest('sha1', bytes, 'hex');
+        if (actual !== resolved.shasum) {
+            throw new RegistryError(`shasum check failed for ${resolved.name}@${resolved.version}: `
+                + `registry published sha1-${resolved.shasum}, downloaded bytes are sha1-${actual}`);
+        }
+        return { bytes, algorithm: 'sha1', digest: `sha1-${actual}` };
+    }
+    throw new RegistryError(`${resolved.name}@${resolved.version} carries neither dist.integrity nor dist.shasum, so the download cannot be verified`);
+}
+/**
+ * Hash a buffer.
+ * @param algorithm - the hash algorithm.
+ * @param bytes - the input.
+ * @param encoding - how to render the digest.
+ * @returns the digest.
+ */
+function digest(algorithm, bytes, encoding) {
+    return createHash(algorithm).update(bytes).digest(encoding);
+}
+/**
+ * Download a resolved package's tarball and verify it before returning it.
+ *
+ * Nothing parses the bytes on the way in — they are counted against a ceiling
+ * and hashed, and a failed hash throws before any caller can see them.
+ * @param resolved - the packument reading for the version to fetch.
+ * @param options - where to fetch from.
+ * @returns the verified tarball, in memory.
+ * @throws RegistryError on a transport failure, an oversized body, or a hash mismatch.
+ */
+export async function fetchVerifiedTarball(resolved, options = {}) {
+    const response = await get(resolved.tarball, 'application/octet-stream', options);
+    const bytes = await readCapped(response, MAX_TARBALL_BYTES, `tarball ${resolved.tarball}`);
+    return verifyIntegrity(bytes, resolved);
+}

package/lib/report.js

@@ -43,14 +43,16 @@ export function renderJson(report) {
  * @returns the rendered lines.
  */
 function renderFinding(finding, paint) {
-    const where = finding.evidence.path === undefined
-        ? finding.evidence.file
-        : `${finding.evidence.file}:${finding.evidence.path}`;
+    const count = finding.occurrences > 1 ? ` ${paint('dim', `(×${finding.occurrences})`)}` : '';
     const lines = [
-        `${paint(finding.severity, LABEL[finding.severity])}  ${paint('bold', finding.title)}`,
+        `${paint(finding.severity, LABEL[finding.severity])}  ${paint('bold', finding.title)}${count}`,
         `          ${paint('dim', `${finding.checkId} ${finding.name} · tier ${finding.tier} · confidence ${finding.confidence}`)}`,
-        `          ${paint('dim', where)}`,
     ];
+    for (const example of finding.examples)
+        lines.push(`          ${paint('dim', locate(example))}`);
+    if (finding.occurrences > finding.examples.length) {
+        lines.push(`          ${paint('dim', `… and ${finding.occurrences - finding.examples.length} more site(s)`)}`);
+    }
     if (finding.evidence.snippet !== undefined)
         lines.push(`          ${paint('dim', `> ${finding.evidence.snippet}`)}`);
     for (const line of wrap(finding.detail, 88))
@@ -60,6 +62,14 @@ function renderFinding(finding, paint) {
     lines.push('');
     return lines;
 }
+/**
+ * Render one example site as `file:locator`.
+ * @param evidence - the site.
+ * @returns the location.
+ */
+function locate(evidence) {
+    return evidence.path === undefined ? evidence.file : `${evidence.file}:${evidence.path}`;
+}
 /**
  * Wrap prose to a column without breaking words.
  * @param text - the prose.
@@ -121,9 +131,19 @@ function describeFileSet(facts) {
  */
 function renderFacts(report, paint) {
     const { facts } = report;
+    const provenance = report.target.registry;
     const rows = [
         ['package', `${facts.packageName}@${facts.packageVersion}${facts.license === null ? '' : ` (${facts.license})`}`],
         ['read from', `${report.target.kind} ${report.target.path}`],
+        ...provenance === undefined
+            ? []
+            : [
+                ['fetched from', `${provenance.tarball} (${provenance.tarballBytes} bytes, never written to disk)`],
+                ['verified', `${provenance.digest} matched dist.integrity before anything parsed it`],
+                ['install script', provenance.hasInstallScript
+                        ? 'yes — the registry marks this package as running one at install time'
+                        : 'no — the registry does not mark this package as running one'],
+            ],
         ['mounted layer', facts.mountsAsBundle
                 ? `yes — dsh.bundle.patch = ${facts.bundlePatchPath ?? '?'} (imported into the harness process at the agent's uid)`
                 : 'no — installs as a plain library, and dsh plugin add prints a warning saying so'],