dsh-plugin-inspector 0.6.0 → 0.7.0

package/lib/checks/tier-c.js

@@ -7,9 +7,11 @@
  * user is entitled to see it.
  *
  * A Tier C hit also has a mechanical consequence. Tier B recognises a whitelist
- * of syntactic shapes, so when code is minified, when identifiers are computed,
- * or when the shipped artifact has no readable source, a Tier B *positive* is
- * still true but a Tier B *negative* means nothing. `inspect.ts` reads the
+ * of syntactic shapes — a member, on a receiver, taking a name it can resolve —
+ * so when code is minified, when a name is assembled out of something this tool
+ * cannot fold, when a member is detached from the receiver the checks match it
+ * on, or when the shipped artifact has no readable source, a Tier B *positive*
+ * is still true but a Tier B *negative* means nothing. `inspect.ts` reads the
  * output of this module to lower Tier B confidence and to forbid the report
  * from claiming nothing was found.
  * @module dsh-plugin-inspector/checks/tier-c
@@ -17,6 +19,7 @@
 import ts from 'typescript';
 import { lineColumn, snippet } from "../files.js";
 import { MAX_EXAMPLES } from "../model.js";
+import { BUILTIN_MODULE_GETTER, foldConstantString, isBuiltinModuleGetter } from "../syntax.js";
 /** A line longer than this is not written by hand. */
 const MINIFIED_LINE_LENGTH = 500;
 /** Below this many bytes, a low line count says nothing. */
@@ -27,6 +30,42 @@ const DISPATCH_RECEIVERS = new Set(['ctx', 'context', 'globalThis', 'global']);
 const NAMED_TARGET_CALLEES = new Set([
     'on', 'once', 'provide', 'set', 'get', 'emit', 'waterfall', 'bail', 'parallel', 'serial',
 ]);
+/**
+ * Members every Tier B check can only match *through* their receiver.
+ *
+ * B1 reads `<receiver>.provide` / `.set` / `.mixin`, B5 reads
+ * `<receiver>.on`, B11 reads `.plugin`, B10 reads `tools.register`, and B7,
+ * B9 and B13 read `process.getBuiltinModule`. Every one of them is a property
+ * access on a named receiver, so pulling the member off the receiver and
+ * binding it to a bare name removes the only thing those checks match on —
+ * while the call still does exactly what it did.
+ *
+ * This is not the assembled-name case. The name is right there in plain text;
+ * what is gone is the receiver, and following it to the call site is value
+ * tracking this tool does not do.
+ */
+const RECEIVER_ANCHORED_MEMBERS = new Set([
+    'provide', 'set', 'mixin', 'on', 'plugin', 'register', BUILTIN_MODULE_GETTER,
+]);
+/**
+ * Receivers whose members {@link RECEIVER_ANCHORED_MEMBERS} names.
+ *
+ * The plugin context, plus `process` — the receiver of `getBuiltinModule`. The
+ * guard is what keeps `const { set } = options` out of the check.
+ */
+const ANCHORED_RECEIVERS = new Set([...DISPATCH_RECEIVERS, 'process']);
+/** The harness's plugin entry point, whose first parameter is the context. */
+const PLUGIN_ENTRY = 'apply';
+/** Why an unresolvable name makes every Tier B negative meaningless. */
+const ASSEMBLED_NAME_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.';
+/** Why a detached member makes every Tier B negative meaningless. */
+const DETACHED_MEMBER_DETAIL = 'Every Tier B check that matches this member matches it on its receiver: B1 reads '
+    + '`ctx.provide`, B5 reads `ctx.on`, B10 reads `tools.register`, B13 reads `process.getBuiltinModule`. Bound to a '
+    + 'bare name the member still does all of that, and the call site no longer says on what. Following the binding is '
+    + 'value tracking this tool does not do, so no Tier B negative for this package carries any information. A Tier B '
+    + 'positive still does — the tool saw what it saw.';
 /**
  * Build one Tier C finding. Confidence is `moderate`: these are heuristics
  * about form, and a hand-written file can legitimately have one long line.
@@ -85,20 +124,18 @@ function checkMinification(files) {
     }
     return findings;
 }
-/** C2 — names the analyzer cannot resolve without running the code. */
+/** C2 — names and receivers the analyzer cannot resolve without running the code. */
 function checkDynamicDispatch(files) {
     const findings = [];
     for (const { path, text, node: source } of files) {
-        const report = (node, what) => {
+        const report = (node, what, why) => {
             findings.push(tierC({
                 checkId: 'C2',
                 name: 'dynamic-dispatch',
                 subject: what,
                 severity: 'high',
                 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.',
+                detail: why,
                 evidence: {
                     file: path,
                     path: lineColumn(text, node.getStart(source)),
@@ -108,29 +145,36 @@ function checkDynamicDispatch(files) {
             }));
         };
         const isComputed = (node) => node !== undefined && !ts.isStringLiteral(node) && !ts.isNoSubstitutionTemplateLiteral(node);
+        // A specifier Tier B folded to a constant is one Tier B matched, so it is
+        // not a gap. Only what the folder gives up on degrades the report.
+        const isUnresolvedSpecifier = (node) => isComputed(node) && foldConstantString(node) === null;
         const visit = (node) => {
             if (ts.isElementAccessExpression(node) && ts.isIdentifier(node.expression)
                 && DISPATCH_RECEIVERS.has(node.expression.text) && isComputed(node.argumentExpression)) {
-                report(node, `resolves a member of \`${node.expression.text}\` from a computed name`);
+                report(node, `resolves a member of \`${node.expression.text}\` from a computed name`, ASSEMBLED_NAME_DETAIL);
             }
+            if (ts.isVariableDeclaration(node))
+                reportDetachedBindings(node, report);
+            if (ts.isFunctionLike(node))
+                reportDetachedContextParameter(node, report);
             if (ts.isCallExpression(node)) {
                 const callee = node.expression;
                 const isRequire = ts.isIdentifier(callee) && callee.text === 'require';
                 const isImport = callee.kind === ts.SyntaxKind.ImportKeyword;
-                if ((isRequire || isImport) && isComputed(node.arguments[0])) {
-                    report(node, 'loads a module from a computed specifier');
+                if ((isRequire || isImport || isBuiltinModuleGetter(node)) && isUnresolvedSpecifier(node.arguments[0])) {
+                    report(node, 'loads a module from a computed specifier', ASSEMBLED_NAME_DETAIL);
                 }
                 if (ts.isIdentifier(callee) && callee.text === 'atob') {
-                    report(node, 'decodes a base64 string at runtime');
+                    report(node, 'decodes a base64 string at runtime', ASSEMBLED_NAME_DETAIL);
                 }
                 if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'from'
                     && ts.isIdentifier(callee.expression) && callee.expression.text === 'Buffer'
                     && (literalOf(node.arguments[1]) === 'base64' || literalOf(node.arguments[1]) === 'base64url')) {
-                    report(node, 'decodes a base64 string at runtime');
+                    report(node, 'decodes a base64 string at runtime', ASSEMBLED_NAME_DETAIL);
                 }
                 if (ts.isPropertyAccessExpression(callee) && NAMED_TARGET_CALLEES.has(callee.name.text)
                     && isDispatchReceiver(callee.expression) && isAssembledName(node.arguments[0])) {
-                    report(node, `passes an assembled name to \`${receiverName(callee.expression)}.${callee.name.text}()\``);
+                    report(node, `passes an assembled name to \`${receiverName(callee.expression)}.${callee.name.text}()\``, ASSEMBLED_NAME_DETAIL);
                 }
             }
             ts.forEachChild(node, visit);
@@ -139,6 +183,84 @@ function checkDynamicDispatch(files) {
     }
     return findings;
 }
+/**
+ * Report every {@link RECEIVER_ANCHORED_MEMBERS} member a binding pattern pulls
+ * out of a known receiver.
+ *
+ * A computed property in the pattern — `const { [name]: fn } = ctx` — is
+ * `ctx[name]` written as a destructuring, and is recorded as that same finding
+ * so the two spellings aggregate together.
+ * @param pattern - the binding pattern.
+ * @param receiver - how the finding names the object being destructured.
+ * @param report - the reporter.
+ */
+function reportPatternMembers(pattern, receiver, report) {
+    for (const element of pattern.elements) {
+        const property = element.propertyName ?? element.name;
+        if (ts.isComputedPropertyName(property)) {
+            report(element, `resolves a member of ${receiver} from a computed name`, ASSEMBLED_NAME_DETAIL);
+            continue;
+        }
+        if (!ts.isIdentifier(property) || !RECEIVER_ANCHORED_MEMBERS.has(property.text))
+            continue;
+        report(element, `binds \`${property.text}\` off ${receiver} to a bare name`, DETACHED_MEMBER_DETAIL);
+    }
+}
+/**
+ * Whether an expression names a receiver whose members Tier B matches by name.
+ * @param node - the expression.
+ * @returns the receiver's own name, or `null`.
+ */
+function anchoredReceiver(node) {
+    if (node === undefined)
+        return null;
+    if (ts.isIdentifier(node) && ANCHORED_RECEIVERS.has(node.text))
+        return node.text;
+    // `this.ctx` and `self.ctx` are the same receiver held on a field.
+    if (ts.isPropertyAccessExpression(node) && DISPATCH_RECEIVERS.has(node.name.text))
+        return node.name.text;
+    return null;
+}
+/**
+ * C2 — a variable declaration that detaches an anchored member from its
+ * receiver, in either spelling: `const { provide } = ctx`, or
+ * `const provide = ctx.provide`.
+ * @param node - the variable declaration.
+ * @param report - the reporter.
+ */
+function reportDetachedBindings(node, report) {
+    const source = anchoredReceiver(node.initializer);
+    if (source !== null && ts.isObjectBindingPattern(node.name)) {
+        reportPatternMembers(node.name, `\`${source}\``, report);
+        return;
+    }
+    const initializer = node.initializer;
+    if (initializer === undefined || !ts.isPropertyAccessExpression(initializer))
+        return;
+    const receiver = anchoredReceiver(initializer.expression);
+    if (receiver === null || !RECEIVER_ANCHORED_MEMBERS.has(initializer.name.text))
+        return;
+    report(node, `binds \`${initializer.name.text}\` off \`${receiver}\` to a bare name`, DETACHED_MEMBER_DETAIL);
+}
+/**
+ * C2 — a plugin entry point that destructures its context parameter:
+ * `export function apply({ provide }) { … }`.
+ *
+ * The receiver is known here without any binding to follow: `apply`'s first
+ * parameter is the plugin context by the harness's own mount contract, which is
+ * what keeps this off every other function that destructures an options object.
+ * @param node - the function-like declaration.
+ * @param report - the reporter.
+ */
+function reportDetachedContextParameter(node, report) {
+    const name = node.name;
+    if (name === undefined || !ts.isIdentifier(name) || name.text !== PLUGIN_ENTRY)
+        return;
+    const first = node.parameters[0];
+    if (first === undefined || !ts.isObjectBindingPattern(first.name))
+        return;
+    reportPatternMembers(first.name, 'the plugin context', report);
+}
 /**
  * Whether an expression names the plugin context.
  *
@@ -174,16 +296,22 @@ function receiverName(node) {
     /* v8 ignore stop */
 }
 /**
- * Whether a node builds a string at runtime rather than naming one. A plain
- * identifier is deliberately excluded: `ctx.on(EVENT_NAME, …)` against a module
- * constant is ordinary code, and treating it as evasion would degrade the
+ * Whether a node builds a string at runtime rather than naming one, and does it
+ * in a way the constant folder could not follow.
+ *
+ * A plain identifier is deliberately excluded: `ctx.on(EVENT_NAME, …)` against a
+ * module constant is ordinary code, and treating it as evasion would degrade the
  * analysis of nearly every well-written plugin.
  * @param node - the argument node.
- * @returns true for concatenation, an interpolated template, or a call.
+ * @returns true for an unfoldable concatenation, template, or call.
  */
 function isAssembledName(node) {
     if (node === undefined)
         return false;
+    // A name Tier B folded to a constant is a name Tier B matched. Reporting it
+    // here as well would degrade the whole report over a site that was read.
+    if (foldConstantString(node) !== null)
+        return false;
     if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken)
         return true;
     if (ts.isTemplateExpression(node))

package/lib/index.js

@@ -12,8 +12,9 @@
  * @module dsh-plugin-inspector
  */
 export { analyze, exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from "./inspect.js";
+export { MAX_ATTESTATION_BYTES, packageUrl, PROVENANCE_PREDICATE_TYPE, provenanceAbsent, provenanceUnavailable, provenanceUnreadable, readProvenance, } from "./attestation.js";
 export { inspectFromNpm, precheck } from "./npm.js";
-export { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, verifyIntegrity, } from "./registry.js";
+export { attestationUrl, DEFAULT_REGISTRY, fetchAttestation, 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";

package/lib/inspect.js

@@ -10,6 +10,7 @@
  * @module dsh-plugin-inspector/inspect
  */
 import { readFileSync } from 'node:fs';
+import { provenanceUnavailable } from "./attestation.js";
 import { EXPRESSION_CLASSES, PatchParseError, parsePatchDocument, } from "./cordis-yaml.js";
 import { isCordisConfigFile, isModelVisibleText, isSourceFile, normalizePackagePath } from "./files.js";
 import { HARNESS_REFERENCE } from "./knowledge.js";
@@ -95,11 +96,13 @@ export async function inspect(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.
+ * @param registry - where the bytes came from, when they were fetched from a registry.
+ * @param provenance - what the registry's attestation said and what was checked
+ * of it; defaults to the `unavailable` fact the two local modes carry.
  * @returns the complete report.
  * @throws ManifestError when the manifest cannot be read.
  */
-export function analyze(source, registry) {
+export function analyze(source, registry, provenance = provenanceUnavailable()) {
     const manifest = parseManifest(source.files.get('package.json') ?? '');
     const declared = manifest.dsh.bundle?.patch;
     const mountsAsBundle = declared !== undefined;
@@ -131,6 +134,7 @@ export function analyze(source, registry) {
         unmountedPatchFiles: others,
         sourceFiles,
         modelVisibleFiles,
+        provenance,
     };
     const tierC = runTierC(input);
     const unreadable = tierC.filter(finding => !NON_DEGRADING_CHECKS.has(finding.checkId));
@@ -148,6 +152,7 @@ export function analyze(source, registry) {
         packageName: manifest.name,
         packageVersion: manifest.version,
         license: manifest.license,
+        provenance,
         mountsAsBundle,
         bundlePatchPath: declared ?? null,
         shipsClientBundle: manifest.dsh.client !== undefined && manifest.exportPaths.includes('./client'),

package/lib/knowledge.js

@@ -11,9 +11,15 @@
  */
 /**
  * Harness version these tables were transcribed from — the version string in
- * the checkout's own `packages/bundle/*/package.json`.
+ * the shipped bundles' own `package.json`, which is `dsh`'s own version.
+ *
+ * Re-verified against `0.1.1-rc.2`, the release npm tags `latest`, by
+ * extracting each table from the published packages and diffing it against the
+ * one here. What moved: six rows inserted by the web bundle, three seam keys,
+ * and two sandbox traps this table had never carried. What did not: every row
+ * name, every row's bundle membership, and the waterfall event set.
  */
-export const HARNESS_REFERENCE = '0.1.0-rc.5';
+export const HARNESS_REFERENCE = '0.1.1-rc.2';
 /**
  * The three profile bundles the harness ships, mapped to what each one is.
  * A package that *is* one of these composes the core rows rather than modifying
@@ -63,6 +69,7 @@ export const CORE_ROWS = new Map([
     ['cordis-host-runner', { module: '@deepseek-ai/dsh-cordis-host-runner', bundles: ['web-app'] }],
     ['credentials', { module: '@deepseek-ai/dsh-credentials-local', bundles: ['base'] }],
     ['directory-picker', { module: '@deepseek-ai/dsh-host-directory-picker-auto', bundles: ['web-app'] }],
+    ['file-reference-local', { module: '@deepseek-ai/dsh-file-reference-local', bundles: ['web-app'] }],
     ['fs-observation-policy', { module: '@deepseek-ai/dsh-fs-observation-policy', bundles: ['base'] }],
     ['fs-sandbox', { module: '@deepseek-ai/dsh-fs-sandbox', bundles: ['base'] }],
     ['goal', { module: '@deepseek-ai/dsh-goal', bundles: ['base'] }],
@@ -92,6 +99,7 @@ export const CORE_ROWS = new Map([
     ['session-projection', { module: '@deepseek-ai/dsh-session-projection', bundles: ['base'] }],
     ['session-projection-cache', { module: '@deepseek-ai/dsh-session-projection-cache', bundles: ['web-app'] }],
     ['session-query-sqlite', { module: '@deepseek-ai/dsh-session-query-sqlite', bundles: ['base'] }],
+    ['session-reference', { module: '@deepseek-ai/dsh-session-reference', bundles: ['web-app'] }],
     ['session-stats', { module: '@deepseek-ai/dsh-session-stats', bundles: ['web-app'] }],
     ['session-telemetry-otel', { module: '@deepseek-ai/dsh-session-telemetry-otel', bundles: ['base'] }],
     ['session-title', { module: '@deepseek-ai/dsh-session-title', bundles: ['base'] }],
@@ -137,6 +145,8 @@ export const CORE_ROWS = new Map([
     ['typert-gateway', { module: '@deepseek-ai/dsh-api-gateway', bundles: ['base'] }],
     ['typert-loader', { module: '@deepseek-ai/dsh-typert-loader', bundles: ['base'] }],
     ['ui-agent-preset', { module: '@deepseek-ai/dsh-client-ui-agent-preset', bundles: ['web-app'] }],
+    ['ui-attachment', { module: '@deepseek-ai/dsh-client-ui-attachment', bundles: ['web-app'] }],
+    ['ui-brand-official', { module: '@deepseek-ai/dsh-client-ui-brand-official', bundles: ['web-app'] }],
     ['ui-commands', { module: '@deepseek-ai/dsh-client-ui-commands', bundles: ['web-app'] }],
     ['ui-conversation', { module: '@deepseek-ai/dsh-client-ui-conversation', bundles: ['web-app'] }],
     ['ui-cordis', { module: '@deepseek-ai/dsh-client-ui-cordis', bundles: ['web-app'] }],
@@ -149,6 +159,8 @@ export const CORE_ROWS = new Map([
     ['ui-model-selection', { module: '@deepseek-ai/dsh-client-ui-model-selection', bundles: ['web-app'] }],
     ['ui-permission', { module: '@deepseek-ai/dsh-client-ui-permission-presets', bundles: ['web-app'] }],
     ['ui-plan', { module: '@deepseek-ai/dsh-client-ui-plan', bundles: ['web-app'] }],
+    ['ui-reference', { module: '@deepseek-ai/dsh-client-ui-reference', bundles: ['web-app'] }],
+    ['ui-renderer', { module: '@deepseek-ai/dsh-client-ui-renderer', bundles: ['web-app'] }],
     ['ui-settings', { module: '@deepseek-ai/dsh-client-ui-settings', bundles: ['web-app'] }],
     ['ui-settings-general', { module: '@deepseek-ai/dsh-client-ui-settings-general', bundles: ['web-app'] }],
     ['ui-settings-models', { module: '@deepseek-ai/dsh-client-ui-settings-models', bundles: ['web-app'] }],
@@ -207,10 +219,10 @@ export const SECURITY_ROW_IDS = new Map([
  * replaces a core service for every consumer in its scope.
  */
 export const SEAM_KEYS = new Set([
-    'agentDefaultModel', 'agentLoop', 'agentPresets', 'agents', 'apiProxy', 'approval',
-    'attachments', 'clientModules', 'codeRuntime', 'commands', 'compaction', 'credentials',
-    'directoryPicker', 'e2b', 'fs', 'goals', 'invariants', 'jobs', 'llm', 'lsp',
-    'messageFeedback', 'permissionPresets', 'planMode', 'sandbox', 'sandboxPolicy',
+    'agentDefaultModel', 'agentLoop', 'agentPresets', 'agents', 'agentTeams', 'apiProxy', 'approval',
+    'attachments', 'authorization', 'clientModules', 'codeRuntime', 'commands', 'compaction',
+    'credentials', 'directoryPicker', 'e2b', 'fileReferences', 'fs', 'goals', 'invariants', 'jobs',
+    'llm', 'lsp', 'messageFeedback', 'permissionPresets', 'planMode', 'sandbox', 'sandboxPolicy',
     'sessionPersistence', 'sessionProjectionCache', 'sessionProjections', 'sessionQuery',
     'sessionReferenceResolver', 'sessions', 'sessionTelemetry', 'sessionTitle', 'settings',
     'shell', 'shellEnv', 'skills', 'spillStore', 'storage', 'storageDomain', 'subagents',
@@ -218,10 +230,21 @@ export const SEAM_KEYS = new Set([
     'tools', 'typert', 'typertGateway', 'userQuestions', 'web', 'webServer', 'workflowEngine',
     'workspaceRegistry',
 ]);
-/** The subset of {@link SEAM_KEYS} whose replacement removes a constraint. */
+/**
+ * The subset of {@link SEAM_KEYS} whose replacement removes a constraint.
+ *
+ * `authorization` joined the catalogue in `0.1.1-rc.2`: it is the registry of
+ * flows that obtain a credential through a conversation with the user, so
+ * providing it means owning that conversation. That is the same class of
+ * substitution as `credentials`, which this set already holds. The other two
+ * keys the release added are not: `fileReferences` decides which paths are
+ * offered for completion and `agentTeams` is the team form of `subagents`,
+ * which is deliberately not here either.
+ */
 export const SECURITY_SEAM_KEYS = new Set([
-    'approval', 'sandbox', 'sandboxPolicy', 'permissionPresets', 'credentials', 'subprocess',
-    'shell', 'fs', 'tools', 'agentLoop', 'sessionPersistence', 'sessionTelemetry', 'invariants',
+    'approval', 'authorization', 'sandbox', 'sandboxPolicy', 'permissionPresets', 'credentials',
+    'subprocess', 'shell', 'fs', 'tools', 'agentLoop', 'sessionPersistence', 'sessionTelemetry',
+    'invariants',
 ]);
 /**
  * Waterfall events, from `EVENT_API` in the api-catalog. A listener on one of
@@ -229,6 +252,10 @@ export const SECURITY_SEAM_KEYS = new Set([
  * without calling it short-circuits the chain including the built-in behavior.
  *
  * Note there is no `fs/read-intent` — the intent family is write and edit only.
+ *
+ * Unchanged in `0.1.1-rc.2`. The catalogue's event set grew by four and lost
+ * one, but every addition carries `mode: 'emit'`, and only `mode: 'waterfall'`
+ * hands a listener the trailing `next` this set is about.
  */
 export const WATERFALL_EVENTS = new Set([
     'agent/pre-step', 'agent/request', 'agent/request-error', 'approval/request',
@@ -252,6 +279,8 @@ export const SANDBOX_DENIED_GLOBALS = new Map([
     ['setTimeout', "redirected to the cordis timer service (inject: ['timer'])"],
     ['setInterval', "redirected to the cordis timer service (inject: ['timer'])"],
     ['setImmediate', "redirected to the cordis timer service (inject: ['timer'])"],
+    ['clearTimeout', "redirected to the cordis timer service (inject: ['timer'])"],
+    ['clearInterval', "redirected to the cordis timer service (inject: ['timer'])"],
 ]);
 /**
  * Node builtins that start or evaluate code off the mediated path. A mounted

package/lib/npm.js

@@ -7,16 +7,27 @@
  * 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`;
+ *    `hasInstallScript`, the install lifecycle scripts, `dsh.bundle`, and
+ *    whether the registry holds a provenance attestation at all;
  * 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.
+ * 4. read the provenance attestation, when step 1 said there is one, and check
+ *    it against the bytes step 3 vouched for;
+ * 5. decode in memory and analyse, exactly as the tarball path does.
+ *
+ * Step 4 is the only request this module makes that is not unconditional, and
+ * it is skipped for every package the version document says has no attestation
+ * — which on the measured corpus is 28 packages in 40. It never fails an
+ * analysis: an endpoint that is down or a bundle that does not decode leaves
+ * the provenance fact in state `unreadable`, which is a different answer from
+ * `absent` and is printed as one.
  *
  * No subprocess, no disk write, no lifecycle script, and no `npm pack`.
  * @module dsh-plugin-inspector/npm
  */
+import { provenanceAbsent, provenanceUnreadable, readProvenance, } from "./attestation.js";
 import { analyze } from "./inspect.js";
-import { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, resolvePackage, } from "./registry.js";
+import { attestationUrl, DEFAULT_REGISTRY, fetchAttestation, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, } from "./registry.js";
 import { loadTarballBuffer } from "./source.js";
 /**
  * The metadata pre-check, which needs no tarball.
@@ -31,6 +42,46 @@ import { loadTarballBuffer } from "./source.js";
 export async function precheck(spec, options = {}) {
     return resolvePackage(parseSpec(spec), options);
 }
+/**
+ * Read the registry's provenance attestation for a resolved package, when it
+ * has one, and check it against the bytes that were downloaded.
+ *
+ * Every failure on this path becomes a fact rather than a refusal. The tarball
+ * has already been checked against `dist.integrity`, so the analysis is sound
+ * whatever the attestation endpoint does, and turning a registry outage into
+ * exit code 2 would make provenance a precondition for reading a package
+ * instead of something reported about it.
+ * @param resolved - the packument reading for the version.
+ * @param registry - the registry base URL, without a trailing slash.
+ * @param tarball - the verified tarball bytes.
+ * @param options - where to fetch from.
+ * @returns what the registry says about the build origin, and what was checked.
+ */
+async function readRegistryProvenance(resolved, registry, tarball, options) {
+    if (resolved.provenancePredicateType === null)
+        return provenanceAbsent();
+    let url;
+    try {
+        url = attestationUrl(registry, resolved.name, resolved.version);
+    }
+    catch (error) {
+        /* v8 ignore next -- `attestationUrl` refuses a name or version only with a RegistryError. */
+        if (!(error instanceof RegistryError))
+            throw error;
+        return provenanceUnreadable(null, error.message);
+    }
+    let body;
+    try {
+        body = await fetchAttestation(url, options);
+    }
+    catch (error) {
+        /* v8 ignore next -- `fetchAttestation` reports every refusal as a RegistryError. */
+        if (!(error instanceof RegistryError))
+            throw error;
+        return provenanceUnreadable(url, error.message);
+    }
+    return readProvenance(body, { name: resolved.name, version: resolved.version, tarball, url });
+}
 /**
  * Fetch a published package and inspect it in memory.
  * @param spec - `<name>` or `<name>@<version>`; no version means the `latest` tag.
@@ -42,9 +93,11 @@ export async function precheck(spec, options = {}) {
 export async function inspectFromNpm(spec, options = {}) {
     const resolved = await precheck(spec, options);
     const verified = await fetchVerifiedTarball(resolved, options);
+    const registry = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
+    const attestation = await readRegistryProvenance(resolved, registry, verified.bytes, options);
     const provenance = {
         spec,
-        registry: (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, ''),
+        registry,
         resolvedVersion: resolved.version,
         tarball: resolved.tarball,
         digest: verified.digest,
@@ -54,5 +107,5 @@ export async function inspectFromNpm(spec, options = {}) {
         tarballBytes: verified.bytes.byteLength,
     };
     const source = await loadTarballBuffer(verified.bytes, `npm:${resolved.name}@${resolved.version}`);
-    return analyze(source, provenance);
+    return analyze(source, provenance, attestation);
 }

package/lib/registry.js

@@ -19,6 +19,7 @@
  * @module dsh-plugin-inspector/registry
  */
 import { createHash } from 'node:crypto';
+import { MAX_ATTESTATION_BYTES } from "./attestation.js";
 import { INSTALL_LIFECYCLE_SCRIPTS } from "./knowledge.js";
 import { MAX_TOTAL_BYTES } from "./source.js";
 /** The public npm registry, used when no other is named. */
@@ -146,6 +147,7 @@ export async function resolvePackage(spec, options = {}) {
         integrity: typeof dist.integrity === 'string' ? dist.integrity : null,
         shasum: typeof dist.shasum === 'string' ? dist.shasum : null,
         hasInstallScript: record.hasInstallScript === true,
+        provenancePredicateType: asString(asRecord(asRecord(dist.attestations).provenance), 'predicateType'),
         lifecycleScripts: INSTALL_LIFECYCLE_SCRIPTS.filter(name => typeof scripts[name] === 'string'),
         bundlePatch: typeof bundle.patch === 'string' ? bundle.patch : null,
         metadataBytes: body.byteLength,
@@ -162,6 +164,16 @@ function asRecord(value) {
         ? value
         : {};
 }
+/**
+ * Read a string field, or `null` when it is absent or of another type.
+ * @param record - the containing record.
+ * @param key - the field name.
+ * @returns the string, or `null`.
+ */
+function asString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : null;
+}
 /**
  * Refuse a tarball URL that points somewhere other than the registry that
  * described it.
@@ -260,3 +272,45 @@ export async function fetchVerifiedTarball(resolved, options = {}) {
     const bytes = await readCapped(response, MAX_TARBALL_BYTES, `tarball ${resolved.tarball}`);
     return verifyIntegrity(bytes, resolved);
 }
+/**
+ * The endpoint an npm-compatible registry serves a version's attestation
+ * bundle from.
+ *
+ * Built from the registry base URL rather than read out of
+ * `dist.attestations.url`, which is the opposite of how the tarball URL is
+ * handled and is deliberate: the tarball has to come from wherever the registry
+ * says because there is no other way to name it, so that URL is taken from the
+ * document and then refused unless it is same-origin. An attestation needs no
+ * such freedom. Constructing the path here means a doctored packument cannot
+ * redirect the request at all, not even to another path on the same host.
+ *
+ * The name and version are re-validated because both come out of the version
+ * document, which is registry-controlled: `name` is not necessarily the name
+ * that was asked for, and it is interpolated into a URL.
+ * @param registry - the registry base URL, without a trailing slash.
+ * @param name - the resolved package name.
+ * @param version - the resolved version.
+ * @returns the absolute URL.
+ * @throws RegistryError when the document's name or version would not address this endpoint.
+ */
+export function attestationUrl(registry, name, version) {
+    if (!PACKAGE_NAME.test(name))
+        throw new RegistryError(`the version document names no npm package: ${name}`);
+    if (!VERSION_OR_TAG.test(version))
+        throw new RegistryError(`the version document names no version: ${version}`);
+    return `${registry}/-/npm/v1/attestations/${name}@${version}`;
+}
+/**
+ * Download an attestation document.
+ *
+ * Only ever called when the version document said there is one, so a package
+ * without provenance costs no request at all.
+ * @param url - the endpoint, from {@link attestationUrl}.
+ * @param options - where to fetch from.
+ * @returns the document as served.
+ * @throws RegistryError on a transport failure, a non-2xx status, or an oversized body.
+ */
+export async function fetchAttestation(url, options = {}) {
+    const response = await get(url, 'application/json', options);
+    return readCapped(response, MAX_ATTESTATION_BYTES, 'attestation document');
+}