Publish-time malware scanning: how should tooling tell "pending scan" apart from "never published"?

[trivikr]

🏷️ Discussion Type

Question

Body

Publish-time malware scanning introduces a window where a version has been accepted by the registry but is not yet installable. The changelog says npm dist-tag keeps working during that window while npm deprecate and npm unpublish do not, but it doesn't describe what a read of the registry returns during it. My release automation retry depends on that read, so I'd like to understand the contract.

Why this matters

Release automation typically decides what to publish by asking the registry what already exists:

npm view <package-name> versions --json

and publishin is the version is absent from the list. There are only two states in that model: present means "skip", absent means "publish". Scanning adds a third state that both existing answers describe incorrectly.

If a pending-scan version reads as absent, then re-running a release that partially failed - the normal recovery path - will attempt to republish versions that were already accepted. We publish ~60 packages from a single monorepo release, so a partial failure part-way through the set is exactly the case we have to recover from, and it is the case most likely to land inside the scan window.

Questions

1. What does npm view <package-name> time --json return for a version that is pending scan? Today that returns created, modified, and a version → timestamp map. Does a pending version get a time entry immediately, only once it becomes available, or not at all? Relatedly: if the entry appears only on availability, does that shift the baseline for min-release-age cooldowns from publish time to availability time?

2. Does the packument's versions object include a pending version? i.e. will the probe above see it, or will it read as never published?

3. Is GET /<name>/<version> a 404 during the window? Some tooling probes the version endpoint directly rather than reading the whole packument, and the two may not agree.

4. Does re-publishing a pending version fail with E403 / EPUBLISHCONFLICT? If a conflict is guaranteed, tooling can treat that error as "already published, wait" and no new API is needed - but I'd rather rely on a stated contract than on inference from an error code that today means something else.

5. Is a first-class status signal planned, in the registry response or the CLI? Staged publishing already models a not-yet-available state and exposes it (npm stage list, npm stage view <stage-id> --json, with staged versions occupying the same version index as published ones). Something equivalent for scan-pending publishes - a field in npm view --json, or in the npm publish --json output - would let publish tooling distinguish all three states without guessing.

Happy to open an issue on npm/cli instead if that's the better venue for (5).

---

Assisted-by: claude:opus-5

[trivikr]

I reported this on changesets, as I use it for publishing packages on npm changesets/changesets#2195

[leobalter]

Thanks! We are aware this needs improvement as the one workaround today is the npm view with 404, you must have a better signal than that.