Publish-time scanning + dual-use disclosure — feedback welcome

[leobalter]

Hi all 👋

We recently rolled out two supply-chain security changes on npm, and we'd like your feedback on how they're working in practice. This thread is for discussion — questions, friction, edge cases, and suggestions are all welcome.

Full details are in the changelog: https://gh.io/npm-publish-time-scanning

What changed, in short

1. Packages are scanned at publish time

Newly published packages are now scanned before they become available to install. Most publishes see a short delay (typically a few minutes) between publishing and availability. npm dist-tag keeps working during this window; commands that depend on the published version (like npm deprecate and npm unpublish) wait until the package is available.

If your automation assumes a package is installable the instant it's published, it may need to poll/retry for availability rather than assume a fixed delay.

2. Disclosure for dual-use content

Some legitimate packages (security research tools, pen-testing utilities, obfuscation tools, etc.) have capabilities that can look like malware to automated scanning. Maintainers of these packages can now declare them with a contentPolicy field in package.json and a DISCLOSURE file describing the intended use. This helps us distinguish legitimate security tooling from malicious packages without manually reviewing every publish.

We'd love your input

We're reading this thread and will use it to improve the rollout. Thanks for helping us make the ecosystem safer 🙏

[donecarlo]

Couple of questions about the topic:

• Does scanning only involve the source code, or does it also scan the package's dependencies for possible vulnerable versions?
• Is the scanning also applicable when publishing towards a private registry?

[leobalter]

All packages are subject to scanning (private or public), and we can can scale the scanning perform it extensively on case by case basis.

[davidwarner234]

Publish-time scanning is a good step toward making npm safer. The main concern will be how automation handles the delay, so clear status signals and reliable retry guidance would help. The disclosure process for legitimate security tools also sounds like a practical approach.

[trivikr]

Feedback on how should tooling tell "pending scan" apart from "never published"

This was posted before the link was shared in the blog post https://github.com/orgs/community/discussions/203395

[trivikr]

From discussions on OpenJS slack from @leobalter

npm view is the current workaround, we are working to create a specific way to poll scanning status.

Existing publish scripts might attempt npm publish if npm view returns 404.
There should a clarification what npm publish for specific version will respond, if the package is still being scanned.

[leobalter]

we are prioritizing work to display the appropriate scanning status.

[trivikr]

Thank you, @leobalter, for the response.
Is there an issue/discussion that we can follow which shows how scanning status can be checked programatically?

[siddsriv]

Curious about the mechanics: 1. Will I be notified (and how?) if the scanning results in my package(s) not being published? 2. In case there are false positives and my package is not published owing to a potential security reason, is there an appeal process?

[leobalter]

We have notifications in place on long delays for the scanning. There is also an appeal system where a maintainer receives a direct support link if they believe a false positive occurs.

[kuhe]

If I publish [A] and [B depends-on A], (actually hundreds of these packages) in what normally was the correct dependency order, will they be held, scanned, & released in the right order?

[brainsiq]

It's perhaps still early days to make an assessment but could today's new Shai-Hulud style attack have been detected by such checks - publish actions seem to have had malware bundled in the package?

https://www.aikido.dev/blog/keyv-and-friends-compromised-in-npm-supply-chain-attack

[klassiker]

I've pasted the data for keyv@5.6.0 and keyv@6.0.0 fetched from https://registry.npmjs.org/keyv/<version> into ChatGPT:

Security improvements

• npm Trusted Publisher
• SLSA provenance attestations
• GitHub Actions publishing

These improve package provenance and supply-chain security.

Other notable changes

• Package switched to native ESM (index.mjs).
• Declaration files are now .d.mts.
• New preinstall script (setup.mjs) runs during installation.
• Internal implementation appears to have been significantly reorganized (unpacked size increased from ~117 KB to ~1.1 MB).

If you're evaluating this as an upgrade

1. Whether your Node version is 22.19+.
2. Whether any APIs changed between v5 and v6 (this requires reviewing the release notes or changelog).
3. Whether the new preinstall script is acceptable in your environment.
4. Whether your TypeScript/ESM setup is compatible with the new module layout.

"evaluate as malware"

From a malware/supply-chain risk perspective, I'd rate this package transition as Low–Medium Risk. There are a few changes worth investigating, but nothing in the metadata alone strongly indicates malicious behavior.

[jay1466]

Thanks for the transparency and for actively involving the community in this rollout! 🚀

Overall, I think these are positive changes for the npm ecosystem. Publish-time scanning is a worthwhile trade-off if it helps prevent malicious packages from reaching users. The contentPolicy and DISCLOSURE mechanism also seems like a practical way to distinguish legitimate security tools from malicious packages.

A couple of suggestions that could further improve the experience:

• 🔍 Publish Status: It would be great if maintainers could see the scan status after publishing (e.g., Queued → Scanning → Available).
• 📖 CI/CD Guidance: Since many release pipelines expect packages to be available immediately, an official guide with recommended retry/polling strategies would be very helpful.
• ⚠️ False Positives: If a package is delayed or flagged, providing maintainers with a brief explanation or reason would make troubleshooting much easier.

Really appreciate the focus on improving supply-chain security while keeping maintainers in the loop. Looking forward to seeing how this evolves! 👏

[petebacondarwin]

This scanning appears to have created a couple of incidents for us at Cloudflare where the wrangler package is released and marked as latest while the miniflare packages (one of wrangler's depedencies) is still being scanned and not available.

During this period, anyone running npx wrangler@latest ... will result in a failure because the new version of the miniflare package is not accessible.

For this two be a viable tool, there needs to be support for monorepos that release numerous tightly coupled packages in one go to be safely published.

Workarounds we considered:

• publish with non-latest dist-tag and then retag once all packages are accessible - not viable because npm dist-tag is not allowed to use OIDC
• publish staging versions and then promote to production once all packages are accessible - not viable because npm stage approve is not allowed to use OIDC
• stagger our package publication by dependency tree, waiting on each tier to be accessble before moving on - awkward but viable with extra scripting

Ideally this should be baked into the platform so that packages are scanned and released to public only when all their dependencies have been released.

[AUG235772]

npm Publish-Time Scanning & Dual-Use Disclosure Analysis

This repository serves as a technical breakdown and strategic log regarding the new supply-chain security changes introduced to the npm registry. It outlines the architectural impact on CI/CD pipelines, documents the monorepo dependency race condition, and provides actionable workarounds and community feedback templates.

---

Architectural Overview & Status Log

The transition to asymmetric, asynchronous publish-time scanning changes a fundamental invariant of the npm ecosystem:

Publish completion (npm publish exit code 0) no longer equals immediate availability.

While this structural layer is an excellent step forward for overall supply-chain security, the current implementation introduces an operational race condition for tightly coupled multi-package systems, monorepos, and downstream CI/CD delivery pipelines.

---

Critical Vulnerability: The Monorepo Dependency Race

The issue highlighted by major upstream maintainers (such as the Cloudflare wrangler and miniflare incident) exposes a critical structural edge case in asynchronous scanning queues:

[CI Pipeline Run] ──> npm publish (All workspace packages simultaneously)
  ├── package-A (Core Tool)       ──> Fast Scan Queue ──> Available! (dist-tag: latest)
  └── package-B (A's Dependency)  ──> Slow Scan Queue ──> ⏳ PENDING SCAN (404)
                                                               │
[User Execution] ──> npx package-A ────────────────────────────┘
  └── Result:  CRASH (Cannot resolve dependency "package-B@latest")

Why This Happens

The automated scanning engine evaluates package payloads independently based on binary size, file counts, heuristics, and script signatures (such as the presence of preinstall routines).

If a downstream dependency (package-B) takes longer to pass heuristics than the primary orchestration tool (package-A), the registry updates the visible latest dist-tag pointer for package-A before its critical execution tree is fully resolved on the public registry.

---

Remediation & Tooling Workarounds

Until platform-native transaction batching or synchronous blocking mechanisms are officially integrated into the npm registry, maintainers must implement defensive scripting inside their deployment pipelines.

1. The npm view Programmatic Polling Wrapper

Relying on a fixed delay (e.g., sleep 60) is unreliable due to variable queue lengths. Instead, implement a recursive polling wrapper in your CI/CD bash scripts right after publishing a package tier to verify availability before moving to the next dependent task:

#!/usr/bin/env bash

PACKAGE_NAME="your-package-name"
PACKAGE_VERSION="1.0.0"

echo "Checking registry availability for \({PACKAGE_NAME}@\){PACKAGE_VERSION}..."

until npm view "\({PACKAGE_NAME}@\){PACKAGE_VERSION}" version &>/dev/null; do
  echo "⏳ Package is still undergoing verification scanning. Retrying in 15 seconds..."
  sleep 15
done

echo " Package cleared scanning and is now public! Proceeding with pipeline..."

2. Implement a Dependency-Tree Stagger

Modify your monorepo release orchestration (using tools like Lerna, Nx, or custom workspace scripts) to sequentially publish starting strictly from the lowest leaf node up to the top-level package, executing the polling loop above between each tier.

---

Strategic Solutions Required from npm

To balance ecosystem safety with reliable CI/CD orchestration, three critical platform upgrades are required:

1. Atomic Monorepo & Multi-Package Manifest Batches: The registry needs native support for atomic or transactional publications. If multiple packages are submitted concurrently within the same authorization window, their global state promotion (the routing of the latest dist-tag) should be deferred until all dependent packages within that specific manifest boundary have successfully cleared the scanning queue.
2. Native Scan Status API Endpoint & CLI Flags: Relying on npm view to surface a 404 error is problematic because it creates an ambiguous signal between a package that is actively scanning versus one that simply doesn't exist. This breaks automated tooling that uses a 404 to safeguard against version overwrites. The registry should introduce an explicit "status": "scanning" payload or an npm publish --wait flag.
3. OIDC Support for Lifecycle Modifications: If the platform forces maintainers to use staging tags to manage release timing manually, the registry must extend OpenID Connect (OIDC) trusted publisher token policies to validate npm dist-tag and npm deprecate commands. Currently, restricting OIDC tokens exclusively to the initial publish boundary breaks secure, automated production promotions from GitHub Actions.

---

Official Feedback Discussion Template

Below is the consolidated, high-utility markdown summary designed to be posted directly back into the GitHub Community Feedback Thread #203413 to catch the attention of the product management team:

The current asynchronous queuing mechanism introduces a critical race condition for monorepos and coupled dependency trees. When a primary package clears scanning faster than its internal dependencies, the registry updates the 'latest' pointer, immediately breaking downstream installations (e.g., `npx` loops) for active users during that temporary scanning window.

To make publish-time scanning viable for complex open-source infrastructure, we need the platform to address three core architectural updates:
1. **Transactional/Atomic Releases**: Block the global public promotion of a package tree until all its companion workspace packages have cleared their respective scan queues.
2. **Unambiguous Tooling Signals**: Programmatic polling via `npm view` currently relies on an unreliable 404 state. We need a clear, explicit "pending scan" metadata status payload to prevent automated publish scripts from misinterpreting the delay.
3. **OIDC Scope Expansion**: If manual staging-to-production promotion via tags is recommended as a workaround, OIDC trust execution must be expanded to support `dist-tag` and lifecycle modifications.