dsh-plugin-inspector 0.6.0 → 0.7.0

package/lib/report.js

@@ -19,6 +19,16 @@ const COLOR = {
     bold: '\u001b[1m',
     reset: '\u001b[0m',
 };
+/** Indent that lines a wrapped fact value up under the first one. */
+const CONTINUATION = `\n${' '.repeat(18)}`;
+/** What each unchecked claim means, spelled out rather than left as a key. */
+const GAP_MEANING = {
+    'certificate-chain': 'that the signing certificate is Sigstore\'s — this tool carries no trust root, so a '
+        + 'registry serving a doctored bundle passes every check above',
+    'transparency-log': 'the Rekor transparency-log inclusion proof in the bundle, which needs the same trust root',
+    'builder-identity': 'the signer identity, because the statement names no GitHub Actions workflow to compare the '
+        + 'certificate against',
+};
 /** How the human report labels each severity. */
 const LABEL = {
     critical: 'CRITICAL',
@@ -123,6 +133,46 @@ function describeFileSet(facts) {
     return `working tree narrowed to what npm would publish, by ${basis}`
         + ` (${facts.unpublishedFiles} unpublished file(s) not read)`;
 }
+/**
+ * Say what the registry attested about this tarball's build origin, and — with
+ * equal prominence — what of that was checked here and what was not.
+ *
+ * The report is not allowed to let a reader mistake one for the other. "The
+ * registry told me a claim exists" and "I checked the claim" are different
+ * statements, and the second is only partly true: the digest, the package
+ * name, the DSSE signature and the certificate's own identity are checked, and
+ * whether the certificate belongs to Sigstore is not. So the `not checked` row
+ * is printed whenever the `checked` row is, never as a footnote and never
+ * conditionally.
+ * @param provenance - the fact.
+ * @returns the rows to print.
+ */
+function renderProvenance(provenance) {
+    if (provenance.state === 'unavailable') {
+        return [['provenance', `not readable here — ${provenance.reason}`]];
+    }
+    if (provenance.state === 'absent') {
+        return [['provenance',
+                'none — the registry published no build provenance for this version, which most published packages do not']];
+    }
+    if (provenance.state === 'unreadable') {
+        return [['provenance', `the registry says this version has one and it could not be read — ${provenance.reason}`]];
+    }
+    const origin = `${provenance.sourceRepository ?? 'an unnamed repository'}`
+        + `${provenance.sourceCommit === null ? '' : ` @ ${provenance.sourceCommit}`}`
+        + `${provenance.sourceRef === null ? '' : ` (${provenance.sourceRef})`}`;
+    return [
+        ['provenance', provenance.state === 'attested'
+                ? `attested to ${origin}`
+                : `ATTESTED TO ${origin}, AND THE ATTESTATION DOES NOT CHECK OUT`],
+        ['built by', `${provenance.workflow ?? 'an unnamed workflow'}`
+                + `${provenance.builder === null ? '' : ` on ${provenance.builder}`}`],
+        ['checked', provenance.checks
+                .map(check => `${check.passed ? 'ok  ' : 'FAIL'} ${check.name} — ${check.detail}`)
+                .join(CONTINUATION)],
+        ['not checked', provenance.notChecked.map(gap => GAP_MEANING[gap]).join(CONTINUATION)],
+    ];
+}
 /**
  * Render the "what does this plugin do" section, which is printed whether or
  * not there are findings.
@@ -132,23 +182,24 @@ function describeFileSet(facts) {
  */
 function renderFacts(report, paint) {
     const { facts } = report;
-    const provenance = report.target.registry;
+    const registry = 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
+        ...registry === undefined
             ? []
             : [
-                ['fetched from', `${provenance.tarball} (${provenance.tarballBytes} bytes, never written to disk)`],
+                ['fetched from', `${registry.tarball} (${registry.tarballBytes} bytes, never written to disk)`],
                 // Which field matched is not cosmetic: `dist.shasum` is SHA-1 and is
                 // only reached on packages published before npm 5, so naming
                 // `dist.integrity` there would report a stronger check than ran.
-                ['verified', `${provenance.digest} matched `
-                        + `${provenance.algorithm === 'sha1' ? 'dist.shasum' : 'dist.integrity'} before anything parsed it`],
-                ['install script', provenance.hasInstallScript
+                ['verified', `${registry.digest} matched `
+                        + `${registry.algorithm === 'sha1' ? 'dist.shasum' : 'dist.integrity'} before anything parsed it`],
+                ['install script', registry.hasInstallScript
                         ? 'yes — the registry marks this package as running one at install time'
                         : 'no — the registry does not mark this package as running one'],
             ],
+        ...renderProvenance(facts.provenance),
         /* v8 ignore start -- `mountsAsBundle` is true exactly when the manifest declared a path. */
         ['mounted layer', facts.mountsAsBundle
                 ? `yes — dsh.bundle.patch = ${facts.bundlePatchPath ?? '?'} (imported into the harness process at the agent's uid)`
@@ -157,7 +208,7 @@ function renderFacts(report, paint) {
         ['browser bundle', facts.shipsClientBundle ? 'yes — dsh.client with an ./client export, executed in the user\'s browser' : 'no'],
         ['rows inserted', facts.insertedRows.length === 0
                 ? 'none'
-                : facts.insertedRows.map(row => `${row.id}${row.name === undefined ? '' : ` → ${row.name}`}`).join('\n                ')],
+                : facts.insertedRows.map(row => `${row.id}${row.name === undefined ? '' : ` → ${row.name}`}`).join(CONTINUATION)],
         ['rows modified', facts.targetedRows.length === 0 ? 'none' : facts.targetedRows.join(', ')],
         ['!!js in layer', describeExpressions(facts.jsExpressions)],
         ['other layers', facts.unmountedPatchFiles.length === 0

package/lib/syntax.js

@@ -0,0 +1,135 @@
+/**
+ * Readings of a syntax tree that both capability detection and readability
+ * detection need, and that must agree between them.
+ *
+ * Tier B matches a name; Tier C reports the names it could not match. If the
+ * two disagree about which expressions are constant, a package gets both a
+ * finding and a degrade for the same site, or neither. They agree because they
+ * ask the same function.
+ *
+ * Nothing here evaluates anything. {@link foldConstantString} reads literals
+ * out of an already-parsed tree and concatenates them; it never constructs a
+ * function, and it never touches an identifier's value.
+ * @module dsh-plugin-inspector/syntax
+ */
+import ts from 'typescript';
+/**
+ * How far {@link foldConstantString} descends before answering `null`.
+ *
+ * A bound rather than a promise: the folder recurses over attacker-supplied
+ * syntax, and a name worth hiding is not hidden eight levels of concatenation
+ * deep. Past the bound the answer is "this tool cannot resolve it", which
+ * degrades the report rather than dropping the site.
+ */
+const MAX_FOLD_DEPTH = 8;
+/**
+ * The separator `Array.prototype.join` uses when called with no argument.
+ */
+const DEFAULT_JOIN_SEPARATOR = ',';
+/**
+ * The `Array.prototype.join` case: `['node:child', '_process'].join('')`.
+ * @param node - the call expression.
+ * @param depth - the current recursion depth.
+ * @returns the joined text, or `null` when any part is not a constant.
+ */
+function foldJoin(node, depth) {
+    const callee = node.expression;
+    if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'join')
+        return null;
+    if (!ts.isArrayLiteralExpression(callee.expression))
+        return null;
+    const separator = node.arguments.length === 0
+        ? DEFAULT_JOIN_SEPARATOR
+        : fold(node.arguments[0], depth + 1);
+    if (separator === null)
+        return null;
+    const parts = [];
+    for (const element of callee.expression.elements) {
+        const part = fold(element, depth + 1);
+        if (part === null)
+            return null;
+        parts.push(part);
+    }
+    return parts.join(separator);
+}
+/**
+ * The template case: `` `node:${'fs'}` ``.
+ * @param node - the template expression.
+ * @param depth - the current recursion depth.
+ * @returns the assembled text, or `null` when any span is not a constant.
+ */
+function foldTemplate(node, depth) {
+    let text = node.head.text;
+    for (const span of node.templateSpans) {
+        const value = fold(span.expression, depth + 1);
+        if (value === null)
+            return null;
+        text += value + span.literal.text;
+    }
+    return text;
+}
+/**
+ * The recursive half of {@link foldConstantString}.
+ * @param node - the expression to fold.
+ * @param depth - the current recursion depth.
+ * @returns the text, or `null`.
+ */
+function fold(node, depth) {
+    if (node === undefined || depth > MAX_FOLD_DEPTH)
+        return null;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    if (ts.isParenthesizedExpression(node))
+        return fold(node.expression, depth + 1);
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const left = fold(node.left, depth + 1);
+        const right = fold(node.right, depth + 1);
+        return left === null || right === null ? null : left + right;
+    }
+    if (ts.isTemplateExpression(node))
+        return foldTemplate(node, depth);
+    if (ts.isCallExpression(node))
+        return foldJoin(node, depth);
+    return null;
+}
+/**
+ * The text a constant string expression holds, or `null` when the expression is
+ * not constant.
+ *
+ * Four forms, chosen because each one is a spelling of a name that a reader
+ * sees and a name-matching check does not: a literal, a `+` chain of them, a
+ * template whose every span is one, and `[…].join(…)` over an array of them.
+ * Anything reaching an identifier, a property, or any other call answers
+ * `null` — resolving those is value tracking, which this tool does not do and
+ * which Tier C exists to admit.
+ * @param node - the expression, or `undefined` for a missing argument.
+ * @returns the text, or `null`.
+ */
+export function foldConstantString(node) {
+    return fold(node, 0);
+}
+/**
+ * The Node API that hands back a builtin module without `require` and without
+ * an `import` declaration, added in Node 22.3.
+ *
+ * It reaches the same modules the harness sandbox's `require` trap covers,
+ * from a call that sandbox never sees: the sandbox leaves
+ * `process` `undefined`, so inside it this expression throws, and a mounted
+ * bundle layer is not inside it.
+ * @see https://nodejs.org/api/process.html#processgetbuiltinmoduleid
+ */
+export const BUILTIN_MODULE_GETTER = 'getBuiltinModule';
+/**
+ * Whether a call is `process.getBuiltinModule(…)`.
+ *
+ * The receiver is required. `getBuiltinModule` pulled off `process` and bound
+ * to a bare name is not this — it is a detached member, which Tier C reports as
+ * dispatch it cannot follow.
+ * @param node - the call expression.
+ * @returns true when the call loads a builtin through `process`.
+ */
+export function isBuiltinModuleGetter(node) {
+    const callee = node.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === BUILTIN_MODULE_GETTER
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'process';
+}

package/lib/types/attestation.d.ts

@@ -0,0 +1,173 @@
+/**
+ * npm provenance attestations: what the registry says about where a published
+ * tarball was built, and how much of that this tool can check for itself.
+ *
+ * A provenance attestation is a Sigstore bundle holding a DSSE envelope over an
+ * in-toto statement. The statement names the tarball by digest and, for a
+ * GitHub Actions build, the source repository, the commit, and the workflow
+ * file that produced it. npm publishes one when a package is released from a
+ * trusted CI environment.
+ *
+ * **This module is careful about the difference between reading a claim and
+ * checking one, because a reader who confuses them is worse off than one who
+ * has neither.** Everything it can check runs offline against bytes already in
+ * hand, and everything it cannot check is named in the same record:
+ *
+ * - `subject-digest` — the statement's subject digest is the SHA-512 of the
+ *   tarball this run analysed. This is the binding that makes the rest mean
+ *   anything: without it the attestation could be about another version.
+ * - `subject-package` — that subject is this package at this version, written
+ *   as a package URL.
+ * - `dsse-signature` — the envelope's signature verifies under the public key
+ *   of the certificate carried inside the bundle.
+ * - `certificate-identity` — the certificate's subject alternative name is the
+ *   workflow the statement claims built the package, so payload and signer
+ *   agree.
+ *
+ * What it does **not** do is establish that the certificate is Sigstore's. That
+ * needs the Fulcio root, which lives in the Sigstore trust root and not on any
+ * npm registry, and the same root is what a Rekor inclusion proof is checked
+ * against. Without it these four checks prove the bundle is internally
+ * consistent and is about these exact bytes — not that the identity in it is
+ * real. Those gaps are listed in {@link ProvenanceFact.notChecked} and printed
+ * in the report, so no reader has to infer them.
+ * @module dsh-plugin-inspector/attestation
+ */
+/** The SLSA predicate type npm publishes a build provenance statement under. */
+export declare const PROVENANCE_PREDICATE_TYPE = "https://slsa.dev/provenance/v1";
+/**
+ * Largest attestation document the tool will read. Real bundles are tens of
+ * kilobytes; the transparency-log inclusion proof is most of that.
+ */
+export declare const MAX_ATTESTATION_BYTES: number;
+/**
+ * How much provenance this report has.
+ *
+ * `absent` is the common case and is not a defect: most published packages
+ * carry no attestation. `unavailable` is the honest answer for a directory or
+ * a local tarball, neither of which has a registry statement to read.
+ */
+export type ProvenanceState = 'unavailable' | 'absent' | 'unreadable' | 'attested' | 'failed';
+/** The name of one check this tool runs against a fetched attestation. */
+export type ProvenanceCheckName = 'subject-digest' | 'subject-package' | 'dsse-signature' | 'certificate-identity';
+/**
+ * Something a full verifier would establish and this tool does not.
+ *
+ * `certificate-chain` and `transparency-log` are unconditional: both need the
+ * Sigstore trust root. `builder-identity` appears when the statement does not
+ * name a GitHub Actions workflow, which is the only build type whose signer
+ * identity this tool knows how to reconstruct from the payload.
+ */
+export type ProvenanceGap = 'certificate-chain' | 'transparency-log' | 'builder-identity';
+/** The outcome of one check, with what it compared. */
+export interface ProvenanceCheck {
+    readonly name: ProvenanceCheckName;
+    /** What was compared against what, in one line. */
+    readonly detail: string;
+    readonly passed: boolean;
+}
+/** Everything a fact says about the build, whatever state it is in. */
+interface ProvenanceClaims {
+    /** The predicate type the statement carries. */
+    readonly predicateType: string | null;
+    /** The source repository the statement names, e.g. `https://github.com/owner/repo`. */
+    readonly sourceRepository: string | null;
+    /** The commit that repository was built from. */
+    readonly sourceCommit: string | null;
+    /** The git ref the build ran on, e.g. `refs/tags/v1.2.3`. */
+    readonly sourceRef: string | null;
+    /** Repository-relative path of the workflow that built it. */
+    readonly workflow: string | null;
+    /** The builder the statement names, e.g. a GitHub-hosted runner. */
+    readonly builder: string | null;
+    /** The identity in the signing certificate's subject alternative name. */
+    readonly signerIdentity: string | null;
+    /** Every check that ran, in a fixed order. */
+    readonly checks: readonly ProvenanceCheck[];
+    /** Every claim this tool did not establish. */
+    readonly notChecked: readonly ProvenanceGap[];
+}
+/**
+ * What the registry says about this package's build origin, and what of it was
+ * checked. Emitted for every report, including the two modes that have no
+ * registry statement to read at all.
+ *
+ * The state carries the two fields whose presence depends on it, so a consumer
+ * never has to ask whether a `reason` is meaningful in the state it found: the
+ * two states that have a reason always have one, and the two that report on a
+ * real attestation always name the endpoint it came from.
+ */
+export type ProvenanceFact = (ProvenanceClaims & {
+    readonly state: 'unavailable';
+    /** Why this mode has no attestation to read. */
+    readonly reason: string;
+    readonly attestationUrl: null;
+}) | (ProvenanceClaims & {
+    readonly state: 'absent';
+    readonly reason: null;
+    readonly attestationUrl: null;
+}) | (ProvenanceClaims & {
+    readonly state: 'unreadable';
+    /** What went wrong reading the attestation the registry said it holds. */
+    readonly reason: string;
+    /** The endpoint that was asked, or `null` when none could be built. */
+    readonly attestationUrl: string | null;
+}) | (ProvenanceClaims & {
+    readonly state: 'attested' | 'failed';
+    readonly reason: null;
+    /** The registry endpoint the bundle was read from. */
+    readonly attestationUrl: string;
+});
+/** What a fetched attestation is checked against. */
+export interface ProvenanceSubject {
+    readonly name: string;
+    readonly version: string;
+    /** The tarball bytes, already checked against `dist.integrity`. */
+    readonly tarball: Buffer;
+    /** The endpoint the document came from, recorded in the fact. */
+    readonly url: string;
+}
+/**
+ * The fact for a target that has no registry statement: a directory, or a
+ * tarball on disk. Stated rather than reported as an absence, because "this
+ * package has no provenance" and "this mode cannot read provenance" are
+ * different answers and only one of them is about the package.
+ * @returns the fact.
+ */
+export declare function provenanceUnavailable(): ProvenanceFact;
+/**
+ * The fact for a published package whose version document declares no
+ * provenance attestation.
+ * @returns the fact.
+ */
+export declare function provenanceAbsent(): ProvenanceFact;
+/**
+ * The fact for an attestation the registry named but this run could not read.
+ * @param url - the endpoint that was asked, or `null` when none could be built.
+ * @param reason - what went wrong.
+ * @returns the fact.
+ */
+export declare function provenanceUnreadable(url: string | null, reason: string): ProvenanceFact;
+/**
+ * The package URL npm writes an attestation subject's name as. A scope's `@`
+ * is percent-encoded there and nowhere else in the document.
+ * @param name - the package name.
+ * @param version - the resolved version.
+ * @returns the package URL.
+ */
+export declare function packageUrl(name: string, version: string): string;
+/**
+ * Check a fetched attestation document against the tarball this run analysed.
+ *
+ * The digest comparison is the load-bearing one: it is what ties the statement
+ * to these bytes rather than to some other version of the same package. The
+ * bytes handed in are the ones `dist.integrity` already vouched for, so a pass
+ * here means one chain of digests runs from the version document through the
+ * download to the signed statement.
+ * @param body - the attestation document as served.
+ * @param subject - the package the document is supposed to be about.
+ * @returns the fact, in state `attested`, `failed`, or `unreadable`.
+ */
+export declare function readProvenance(body: Buffer, subject: ProvenanceSubject): ProvenanceFact;
+export {};
+//# sourceMappingURL=attestation.d.ts.map

package/lib/types/checks/input.d.ts

@@ -7,6 +7,7 @@
  * than something every check has to be trusted about.
  * @module dsh-plugin-inspector/checks/input
  */
+import type { ProvenanceFact } from '../attestation.ts';
 import type { PatchDocument, PatchParseError } from '../cordis-yaml.ts';
 import type { PackageManifest } from '../manifest.ts';
 import type { PluginSource } from '../source.ts';
@@ -38,5 +39,11 @@ export interface CheckInput {
     readonly sourceFiles: readonly string[];
     /** Package-relative paths of shipped skill and agent-instruction markdown. */
     readonly modelVisibleFiles: readonly string[];
+    /**
+     * What the registry published about this tarball's build origin. Carries
+     * state `unavailable` on the two modes that read local bytes, which forbids
+     * every provenance verdict — see `runTierA`.
+     */
+    readonly provenance: ProvenanceFact;
 }
 //# sourceMappingURL=input.d.ts.map

package/lib/types/checks/tier-c.d.ts

@@ -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

package/lib/types/index.d.ts

@@ -12,8 +12,9 @@
  * @module dsh-plugin-inspector
  */
 export { analyze, exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from './inspect.ts';
+export { MAX_ATTESTATION_BYTES, packageUrl, PROVENANCE_PREDICATE_TYPE, provenanceAbsent, provenanceUnavailable, provenanceUnreadable, readProvenance, type ProvenanceCheck, type ProvenanceCheckName, type ProvenanceFact, type ProvenanceGap, type ProvenanceState, type ProvenanceSubject, } from './attestation.ts';
 export { inspectFromNpm, precheck } from './npm.ts';
-export { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, verifyIntegrity, type PackageSpec, type RegistryOptions, type ResolvedPackage, type VerifiedTarball, } from './registry.ts';
+export { attestationUrl, DEFAULT_REGISTRY, fetchAttestation, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, verifyIntegrity, type PackageSpec, type RegistryOptions, type ResolvedPackage, type VerifiedTarball, } from './registry.ts';
 export { renderHuman, renderJson } from './report.ts';
 export { classifyExpression, isJsExpr, parsePatchDocument, patchSchema, PatchParseError, type ExpressionClass, type ExpressionSite, type ExpressionSlot, type InsertedRow, type JsExprNode, type OverridePatch, type PatchDocument, } from './cordis-yaml.ts';
 export { declaredPackages, ManifestError, parseManifest, type PackageManifest } from './manifest.ts';

package/lib/types/inspect.d.ts

@@ -9,6 +9,7 @@
  * `cordis-yaml.ts`, and its result is discarded without being called.
  * @module dsh-plugin-inspector/inspect
  */
+import { type ProvenanceFact } from './attestation.ts';
 import { type RegistryProvenance, type Report, type Severity } from './model.ts';
 import { type PluginSource } from './source.ts';
 /**
@@ -39,11 +40,13 @@ export declare function inspect(target: string): Promise<Report>;
 /**
  * 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 declare function analyze(source: PluginSource, registry?: RegistryProvenance): Report;
+export declare function analyze(source: PluginSource, registry?: RegistryProvenance, provenance?: ProvenanceFact): Report;
 /**
  * Whether a report should fail a CI gate.
  * @param report - the report.

package/lib/types/knowledge.d.ts

@@ -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 declare const HARNESS_REFERENCE = "0.1.0-rc.5";
+export declare const HARNESS_REFERENCE = "0.1.1-rc.2";
 /** The shipped bundles, each of which is one patch layer over the profile root. */
 export type BundleName = 'base' | 'headless' | 'web-app';
 /**
@@ -62,7 +68,17 @@ export declare const SECURITY_ROW_IDS: ReadonlyMap<string, string>;
  * replaces a core service for every consumer in its scope.
  */
 export declare const SEAM_KEYS: ReadonlySet<string>;
-/** 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 declare const SECURITY_SEAM_KEYS: ReadonlySet<string>;
 /**
  * Waterfall events, from `EVENT_API` in the api-catalog. A listener on one of
@@ -70,6 +86,10 @@ export declare const SECURITY_SEAM_KEYS: ReadonlySet<string>;
  * 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 declare const WATERFALL_EVENTS: ReadonlySet<string>;
 /** Waterfall events whose short-circuit removes a decision the user would otherwise make. */

package/lib/types/model.d.ts

@@ -9,6 +9,7 @@
  * would fire on every legitimate plugin and train users to ignore the tool.
  * @module dsh-plugin-inspector/model
  */
+import type { ProvenanceFact } from './attestation.ts';
 /** How much a finding should weigh on an install decision. */
 export type Severity = 'critical' | 'high' | 'medium' | 'low';
 /**
@@ -25,7 +26,11 @@ export declare const SEVERITY_RANK: Readonly<Record<Severity, number>>;
 export declare const SEVERITIES: readonly Severity[];
 /** Where in the analysed package a finding was observed. */
 export interface Evidence {
-    /** Package-relative path of the file the finding came from. */
+    /**
+     * Package-relative path of the file the finding came from, or the name of the
+     * registry field it came from when the finding is about what the registry
+     * published rather than about the package contents.
+     */
     readonly file: string;
     /** A locator inside that file: a YAML path, a JSON pointer, or `line:column`. */
     readonly path?: string;
@@ -93,6 +98,13 @@ export interface Facts {
     readonly packageName: string;
     readonly packageVersion: string;
     readonly license: string | null;
+    /**
+     * What the registry says about where this tarball was built, and which of
+     * those claims this run checked. Always present: the two modes that read
+     * local bytes report `unavailable`, which is a different answer from a
+     * published package that has no attestation.
+     */
+    readonly provenance: ProvenanceFact;
     /** True when `package.json` declares `dsh.bundle.patch` — a mounted patch layer. */
     readonly mountsAsBundle: boolean;
     /** The declared patch path, verbatim and unresolved, or `null`. */

package/lib/types/npm.d.ts

@@ -7,10 +7,20 @@
  * 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

package/lib/types/registry.d.ts

@@ -54,6 +54,13 @@ export interface ResolvedPackage {
     readonly lifecycleScripts: readonly string[];
     /** The `dsh.bundle.patch` value, which is what makes a package a mounted layer. */
     readonly bundlePatch: string | null;
+    /**
+     * The predicate type of the provenance attestation the registry says it
+     * holds for this version, from `dist.attestations.provenance`, or `null` when
+     * it says it holds none. Reading it here is what keeps the attestation
+     * endpoint unasked for the majority of packages that have no attestation.
+     */
+    readonly provenancePredicateType: string | null;
     /** Bytes of metadata read to learn all of the above. */
     readonly metadataBytes: number;
 }
@@ -116,4 +123,37 @@ export declare function verifyIntegrity(bytes: Buffer, resolved: ResolvedPackage
  * @throws RegistryError on a transport failure, an oversized body, or a hash mismatch.
  */
 export declare function fetchVerifiedTarball(resolved: ResolvedPackage, options?: RegistryOptions): Promise<VerifiedTarball>;
+/**
+ * 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 declare function attestationUrl(registry: string, name: string, version: string): string;
+/**
+ * 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 declare function fetchAttestation(url: string, options?: RegistryOptions): Promise<Buffer>;
 //# sourceMappingURL=registry.d.ts.map