npmreg

Documentation

Overview

Package npmreg asks the npm registry whether versions run install scripts (preinstall / install / postinstall) and whether they were published with sigstore provenance attestations. A bump that ADDS install scripts where the outgoing version ran none is how several real npm supply-chain attacks delivered their payload (Shai-Hulud's postinstall worm being the loudest); a bump that DROPS provenance where every previous version had it is what publishing with a stolen token looks like (a token thief can publish, but cannot make the project's CI attest the release). lockvet flags both transitions.

One GET per changed package fetches the abbreviated metadata document (Accept: application/vnd.npm.install-v1+json), which carries per-version hasInstallScript and dist.attestations fields. The endpoint answers with Access-Control-Allow-Origin: * and the Accept header is CORS-safelisted, so the wasm build can use it too.

Index

• Variables
• func Annotate(diffs []diffx.FileDiff) error

Variables

var RegistryURL = "https://registry.npmjs.org"

RegistryURL is a var so tests can point it at a fake server.

Functions

func Annotate

func Annotate(diffs []diffx.FileDiff) error

Annotate does two npm-registry passes over the diffs, sharing one metadata download per package:

• It sets ScriptsAdded / ScriptedVersions on bumps whose incoming version runs install scripts while no outgoing version did. Only transitions are flagged: a brand-new dependency with install scripts is ordinary (native builds), and a package that has always had them tells you nothing new.
• It sets ProvenanceDropped / UnattestedVersions on bumps whose incoming version carries no sigstore provenance attestation while EVERY known outgoing version did. Again transitions only, and the strictest one: packages that never attested, or attest only sometimes, are never flagged (the top stable versions below the incoming one must all be attested), and only releases younger than ~a month are flagged at all — this is a while-it's-happening signal, not an audit of history.
• It re-verifies Unlisted flags (set by the deps.dev layer, which can lag npm by days) against the registry itself: a version npm serves is not unlisted, no matter what deps.dev thinks. Versions the npm registry confirms missing keep the flag — that is exactly what unpublished malware looks like. Call it AFTER depsdev.Annotate.

Best-effort: network errors return an error but leave diffs usable.