dsh-plugin-inspector 0.1.0 → 0.2.1

package/lib/checks/tier-b.js

@@ -37,7 +37,7 @@ const SYSTEM_PROMPT_MEMBERS = new Set([
  * @returns the complete finding.
  */
 function tierB(finding) {
-    return { ...finding, tier: 'B', confidence: 'high' };
+    return { ...finding, tier: 'B', confidence: 'high', examples: [finding.evidence], occurrences: 1 };
 }
 /**
  * The literal text of a string argument, or `null` when it is computed.
@@ -110,7 +110,11 @@ function checkImports(file, accumulator) {
             accumulator.findings.push(tierB({
                 checkId: 'B9',
                 name: 'unmediated-process-api',
-                severity: 'critical',
+                subject: specifier,
+                // Raised to `high` by `escalateProcessImports` when this package also
+                // reads a credential or reaches the network. On its own it is a
+                // capability half the ecosystem has.
+                severity: 'medium',
                 title: `Imports \`${specifier}\`, which ${unmediated}`,
                 detail: 'A mounted bundle layer is imported into the harness process at the agent\'s uid. The harness\'s own '
                     + 'dynamic-package sandbox denies untrusted code `require` outright and redirects it to ctx services; a '
@@ -123,6 +127,7 @@ function checkImports(file, accumulator) {
             const finding = tierB({
                 checkId: 'B7',
                 name: 'network-egress',
+                subject: specifier,
                 severity: 'medium',
                 title: `Imports \`${specifier}\`, which can move bytes off the machine`,
                 detail: 'Network access is a capability, not a verdict: most plugins that reach the network do so for a '
@@ -137,6 +142,7 @@ function checkImports(file, accumulator) {
             accumulator.findings.push(tierB({
                 checkId: 'B13',
                 name: 'unmediated-filesystem',
+                subject: specifier,
                 severity: 'medium',
                 title: `Imports \`${specifier}\` rather than using the \`ctx.fs\` service`,
                 detail: 'Reads and writes through the Node filesystem API are invisible to `fs/write-intent`, '
@@ -162,6 +168,7 @@ function checkSeamReplacement(file, node, accumulator) {
     accumulator.findings.push(tierB({
         checkId: 'B1',
         name: 'seam-replacement',
+        subject: `${seam}.${method}`,
         severity: critical ? 'critical' : 'high',
         title: `Replaces the \`${seam}\` capability seam via \`.${method}()\``,
         detail: `\`${seam}\` is a catalogued core service. Providing it from a third-party layer substitutes this `
@@ -185,6 +192,7 @@ function checkSystemPrompt(file, node, accumulator) {
     accumulator.findings.push(tierB({
         checkId: 'B5',
         name: 'system-prompt-mutation',
+        subject: isAssembleListener ? 'system-prompt/assemble' : callee.name.text,
         severity: 'high',
         title: isAssembleListener
             ? 'Listens on `system-prompt/assemble`'
@@ -207,6 +215,7 @@ function checkNestedMount(file, node, accumulator) {
     accumulator.findings.push(tierB({
         checkId: 'B11',
         name: 'nested-plugin-mount',
+        subject: 'runtime-mount',
         severity: 'high',
         title: 'Mounts further plugins at runtime',
         detail: 'A layer that mounts other layers moves the analysis target: what actually runs is decided by code '
@@ -257,6 +266,7 @@ function checkDynamicCode(file, node, accumulator) {
     accumulator.findings.push(tierB({
         checkId: 'B12',
         name: 'dynamic-code-construction',
+        subject: 'runtime-code',
         severity: 'high',
         title: 'Builds and runs code at runtime',
         detail: 'Whatever this evaluates is not in the package and cannot be analysed from it. Construction alone is '
@@ -269,11 +279,14 @@ function checkDynamicCode(file, node, accumulator) {
 /** B6 — reading a credential. */
 function checkCredentialRead(file, node, accumulator) {
     let title = null;
+    let subject = '';
     if (ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
         const outer = node.expression;
         if (ts.isIdentifier(outer.expression) && outer.expression.text === 'process' && outer.name.text === 'env') {
-            if (SECRET_ENV_KEY.test(node.name.text))
+            if (SECRET_ENV_KEY.test(node.name.text)) {
                 title = `Reads the environment variable \`${node.name.text}\``;
+                subject = `env:${node.name.text}`;
+            }
         }
     }
     if (ts.isElementAccessExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
@@ -282,19 +295,23 @@ function checkCredentialRead(file, node, accumulator) {
         if (ts.isIdentifier(outer.expression) && outer.expression.text === 'process' && outer.name.text === 'env'
             && key !== null && SECRET_ENV_KEY.test(key)) {
             title = `Reads the environment variable \`${key}\``;
+            subject = `env:${key}`;
         }
     }
     if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && CREDENTIAL_PATH.test(node.text)) {
         title = `References the credential location \`${node.text}\``;
+        subject = `path:${node.text}`;
     }
     if (ts.isPropertyAccessExpression(node) && node.name.text === 'credentials' && ts.isIdentifier(node.expression)) {
         title = 'Reads the `credentials` service';
+        subject = 'service:credentials';
     }
     if (title === null)
         return;
     const finding = tierB({
         checkId: 'B6',
         name: 'credential-read',
+        subject,
         severity: 'medium',
         title,
         detail: 'Reading a credential is a capability, not a verdict — a plugin that authenticates to its own service '
@@ -318,6 +335,7 @@ function checkToolDescription(file, node, accumulator) {
         accumulator.findings.push(tierB({
             checkId: 'B10',
             name: 'model-visible-injection',
+            subject: match.ruleId,
             severity: 'high',
             title: `Tool description ${match.meaning}`,
             detail: `Heuristic \`${match.ruleId}\` matched a tool \`description\`, which is prompt text the model receives `
@@ -336,6 +354,7 @@ function checkNetworkGlobals(file, node, accumulator) {
     const finding = tierB({
         checkId: 'B7',
         name: 'network-egress',
+        subject: callee.text,
         severity: 'medium',
         title: `Calls \`${callee.text}()\``,
         detail: 'The harness\'s own dynamic-package sandbox traps `fetch` and redirects it to the `ctx.web` service, so '
@@ -381,7 +400,40 @@ export function runTierB(input) {
     const pair = pairFinding(accumulator);
     if (pair !== null)
         accumulator.findings.push(pair);
-    return accumulator.findings;
+    return escalateProcessImports(accumulator);
+}
+/**
+ * B9 — raise a process-API import from `medium` to `high` when the same package
+ * also reads a credential or reaches the network.
+ *
+ * A bare `import 'node:child_process'` was hardcoded `critical` and fired on
+ * half the published ecosystem. A severity that common is not a severity: it
+ * pushed a package disabling `fs-sandbox` down a list of a thousand identical
+ * criticals. Spawning a process is what a plugin that wraps `git`, `ffmpeg` or
+ * a language server does, and the tool cannot tell that from the other thing.
+ *
+ * The pairing is exactly the one B8 already uses — a credential read *and* a
+ * network call in the same package — and for the same reason: the combination
+ * is what changes the question from "can it run a program" to "can it run a
+ * program with something worth sending, and somewhere to send it". Either half
+ * alone is not enough, and it would not narrow anything if it were: 68 % of
+ * published plugins reach the network at all.
+ *
+ * That pairing is still a capability, not a dataflow, so it stops at `high`.
+ * @param accumulator - the accumulated Tier B state.
+ * @returns the findings, with B9 severities settled.
+ */
+function escalateProcessImports(accumulator) {
+    const paired = accumulator.credentialRead !== null && accumulator.networkCall !== null;
+    if (!paired)
+        return accumulator.findings;
+    return accumulator.findings.map(finding => finding.checkId !== 'B9' ? finding : {
+        ...finding,
+        severity: 'high',
+        detail: `${finding.detail} This package also reads a credential or reaches the network, which is why this is `
+            + 'graded above a bare process import: the two capabilities together are what an exfiltration needs. It '
+            + 'remains a capability report — nothing here shows the two are connected.',
+    });
 }
 /**
  * B8 — a credential read and a network call in the same package.
@@ -393,10 +445,15 @@ function pairFinding(accumulator) {
     const network = accumulator.networkCall;
     if (credential === null || network === null)
         return null;
-    const severity = 'critical';
+    // Not critical. This pair fires on 18 % of the published ecosystem — every
+    // telemetry client and every authenticated API client trips it — and the
+    // finding's own text says it is not a verdict. A severity that says "do not
+    // treat this as a verdict" cannot be the top one.
+    const severity = 'high';
     return tierB({
         checkId: 'B8',
         name: 'exfiltration-capability',
+        subject: 'credential-and-egress',
         severity,
         title: 'This package can read a credential and can make a network call',
         detail: 'This is a capability, not a dataflow. The tool found a credential read at '

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/files.js

@@ -23,7 +23,7 @@ export function isSourceFile(path) {
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *
- * The reach is conditional and PLAN.md §6.1 says so: a `SKILL.md` inside an npm
+ * The reach is conditional: a `SKILL.md` inside an npm
  * package is only discovered when the plugin registers it through
  * `ctx.skills`, when a patch row redirects a skill root into the package, or
  * when something copies it into the user's workspace. This predicate answers

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);
+}