npm 25 🌐 Security Best Practices & Token Management (npm audit fix, Access Tokens) - KandZ

⏱️ Estimated read: 10 min | |

Security in npm operates on two axes: the dependency tree and the credentials that authorize publishing. The dependency tree is audited with npm audit, which compares installed packages against a vulnerability database and offers automated fixes. The credentials are managed as access tokens, which have been consolidated into a single granular model as of November 2025. The two axes are independent—a project can have clean dependencies and a leaked token, or a compromised dependency and a perfectly scoped token—and the failure modes are different. The audit addresses known CVEs in third-party code; the token addresses who can publish on your behalf.

Key point: npm audit fix applies updates within the semver ranges declared in package.json. A fix that requires a major version change is not applied unless --force is passed. The granular access token model replaced legacy tokens in November 2025; legacy tokens no longer work, and the replacement is created on the website, not the CLI.

Why both axes matter

The supply chain problem. A dependency can be safe when installed and vulnerable months later when a CVE is filed against it. npm audit checks the installed tree against the advisory database and reports which packages are affected, at what severity, and what the remediation path is . Without the audit, vulnerable dependencies remain in production because no one is looking.

The credential exposure problem. An access token is a long-lived credential that grants the right to install private packages or publish new versions. A token committed to a repository, logged in a CI output, or stored in a world-readable file is a publishing credential in the hands of anyone who finds it. The granular token model exists to limit the damage: tokens can be scoped to specific packages, restricted by IP range, and set to expire .

The automation problem. CI/CD pipelines need to install private dependencies and, in deployment workflows, publish packages. The recommended approach is a read-only token for installation and a separate write token with bypass 2FA for publishing. The bypass 2FA setting is a risk decision: it allows a token to publish even when the account has 2FA enabled, which is necessary for automation but weakens the protection if the token leaks .

a. npm audit and audit fix

npm audit submits the dependency tree to the registry and receives a report of known vulnerabilities. The command exits with a non-zero code if vulnerabilities are found, which makes it suitable for CI. The --audit-level flag sets the minimum severity that triggers a failure; --omit=dev skips devDependencies .

# Report vulnerabilities
npm audit

# Fail CI on moderate or higher
npm audit --audit-level=moderate

# Skip devDependencies
npm audit --omit=dev

npm audit fix applies remediations automatically. The default behavior updates vulnerable packages to versions within the semver ranges declared in package.json. A fix that requires a major version change—outside the declared range—is not applied unless --force is passed .

# Apply safe fixes within semver ranges
npm audit fix

# Preview without changing files
npm audit fix --dry-run

# Apply major version fixes (breaking changes possible)
npm audit fix --force

The --force flag is not a convenience. It allows npm to install versions that violate the declared ranges, which means the fix may introduce breaking changes. The command should be followed by a full test run, and the package.json changes it makes should be reviewed before committing .

When a vulnerability is in a transitive dependency that the parent package has not updated, npm audit fix may not resolve it. The overrides field in package.json forces a specific version of a transitive dependency across the entire tree . This is a manual intervention, and the override should be removed once the parent package updates its dependency.

b. Access Tokens: The Granular Model

As of November 2025, only granular access tokens are supported. Legacy tokens have been removed . Granular tokens are created on the website, not the CLI; the CLI can list and revoke them, but not create them .

A granular token has several configurable properties:

Property	Purpose
Expiration	At least one day in the future; required
Packages/scopes	Up to 50 specific packages or scopes, or all
Permissions	Read-only, Read and write (publish), or stage-only
Organizations	Up to 50 organizations for settings management
IP ranges	CIDR whitelist for the token’s use
Bypass 2FA	Allow publishing without an OTP

The stage-only permission is the safest option for CI/CD publishing. The token can stage a new version for review, but it cannot publish directly. A maintainer with 2FA must promote the staged version. A leaked stage-only token cannot put a new version on the registry without that approval .

The bypass 2FA setting is unchecked by default. When checked, the token can publish even if the account has 2FA enabled. This is necessary for automated deployment but should be reserved for tokens that are only used for publishing, scoped to the specific packages they publish, and set to expire shortly after the deployment window .

c. Token Management and Revocation

The npm token list command shows the tokens associated with the account, including the token ID, the first few characters of the token, and the creation date. The full token is only shown once, at creation time .

# List tokens
npm token list

# Revoke by ID
npm token revoke <id>

The npm token revoke command accepts the full token or a truncated ID that is distinct enough to identify the token. The token is removed from the registry immediately, and it can no longer be used . The website provides the same capability through the Access Tokens page, where multiple tokens can be selected and deleted at once .

A revoked token cannot be recovered. If the token was used in a CI pipeline, the pipeline will fail on the next run until a new token is generated and stored in the secret store. The revocation is the correct response to a leaked token, and it should be followed by an audit of the actions the token performed before it was revoked.

The .npmrc file that stores the token should be gitignored. The recommended pattern is to use environment variable substitution: //registry.npmjs.org/:_authToken=${NPM_TOKEN}, with the token injected from the CI secret store . The .npmrc contains the reference, not the value.

Complete Example Session

# ============================================
# PART 1: RUN THE AUDIT
# ============================================
npm audit
# Reports vulnerabilities with severity and remediation


# ============================================
# PART 2: FAIL CI ON MODERATE+
# ============================================
npm audit --audit-level=moderate


# ============================================
# PART 3: SKIP DEV DEPENDENCIES
# ============================================
npm audit --omit=dev


# ============================================
# PART 4: APPLY SAFE FIXES
# ============================================
npm audit fix
# Updates within semver ranges only


# ============================================
# PART 5: PREVIEW FORCED FIXES
# ============================================
npm audit fix --force --dry-run
# Shows what would change without applying


# ============================================
# PART 6: APPLY FORCED FIXES
# ============================================
npm audit fix --force
# May introduce breaking changes; test afterward


# ============================================
# PART 7: OVERRIDE A TRANSITIVE DEPENDENCY
# ============================================
# Add to package.json:
# "overrides": { "semver": "^7.5.0" }
npm install
# Forces the transitive dependency to the safe version


# ============================================
# PART 8: LIST TOKENS
# ============================================
npm token list
# Shows ID, token prefix, created date


# ============================================
# PART 9: REVOKE A COMPROMISED TOKEN
# ============================================
npm token revoke <id>
# Token is immediately unusable


# ============================================
# PART 10: SECURE THE .NPMRC
# ============================================
# .npmrc
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
# .gitignore includes .npmrc
# NPM_TOKEN is set in the CI secret store

The ten parts trace the audit from report to forced fix and the token from listing to revocation. The critical distinction is between the safe fix (Part 4) and the forced fix (Part 6): the first respects the declared ranges, the second does not.

Quick Reference

npm audit Commands

Command	Effect
`npm audit`	Report vulnerabilities
`npm audit --audit-level=moderate`	Fail on moderate+
`npm audit --omit=dev`	Skip devDependencies
`npm audit fix`	Fix within semver ranges
`npm audit fix --dry-run`	Preview fixes
`npm audit fix --force`	Fix including major changes

Granular Token Properties

Property	Options
Expiration	Required, ≥1 day
Packages	Up to 50, or all
Permissions	Read-only, Read/write, Stage-only
Organizations	Up to 50
IP ranges	CIDR whitelist
Bypass 2FA	Default false

Token Commands

Command	Purpose
`npm token list`	List tokens
`npm token revoke <id>`	Revoke token

Best Practices

✅ Do This:

# Run audit in CI with a severity threshold
npm audit --audit-level=moderate                                      # ✅

# Use --dry-run before forced fixes
npm audit fix --force --dry-run                                        # ✅

# Use environment variable substitution for tokens
//registry.npmjs.org/:_authToken=${NPM_TOKEN}                           # ✅

# Use read-only tokens for CI installation
# Use stage-only or scoped write tokens for publishing                  # ✅

❌ Don’t Do This:

# Commit a token to the repository
//registry.npmjs.org/:_authToken=npm_live_xxxx                          # ❌

# Run audit fix --force without testing
npm audit fix --force  # may break the build                           # ❌

# Create a token with all packages and no expiration
# The token has no scope limit and never expires                        # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Fix requires major version	Transitive dependency pinned	Use `overrides`
Token not found after creation	Full token shown only once	Store immediately
CI publish blocked by 2FA	Token lacks bypass	Use a deployment token
Leaked token used to publish	No expiration, broad scope	Revoke, rotate, narrow scope
`.npmrc` committed	Not gitignored	Add to `.gitignore`

Visual

The Audit and Token Axes

┌──────────────────────────────────────────────────────────────┐
│  DEPENDENCY TREE              CREDENTIALS                    │
│                                                              │
│  ┌─────────────────┐          ┌─────────────────┐           │
│  │ npm audit       │          │ Access token    │           │
│  │                 │          │                 │           │
│  │ CVE check       │          │ Publish rights  │           │
│  │ Remediation     │          │ Install rights  │           │
│  └────────┬────────┘          └────────┬────────┘           │
│           │                            │                     │
│           ▼                            ▼                     │
│  ┌─────────────────┐          ┌─────────────────┐           │
│  │ audit fix       │          │ Scope, expiry   │           │
│  │ overrides       │          │ CIDR, 2FA       │           │
│  └─────────────────┘          └─────────────────┘           │
│                                                              │
│  Independent axes. Both must be managed.                     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

audit fix Decision

┌──────────────────────────────────────────────────────────────┐
│  npm audit finds vulnerability                               │
│         │                                                    │
│         ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Fix within      │────► YES: npm audit fix                │
│  │ semver ranges?  │      Safe, no breaking changes         │
│  └────────┬────────┘                                        │
│           │ NO                                               │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Requires major  │────► npm audit fix --force              │
│  │ version change? │      May break compatibility            │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Run tests       │                                        │
│  │ Review changes  │                                        │
│  └─────────────────┘                                        │
│                                                              │
│  --force is a risk decision.                                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Granular Token Model

┌──────────────────────────────────────────────────────────────┐
│  GRANULAR ACCESS TOKEN                                       │
│                                                              │
│  ┌─────────────────┐                                        │
│  │ Packages        │  Up to 50, or all                      │
│  └─────────────────┘                                        │
│  ┌─────────────────┐                                        │
│  │ Permissions     │  Read-only / Read-write / Stage-only   │
│  └─────────────────┘                                        │
│  ┌─────────────────┐                                        │
│  │ Expiration      │  Required, ≥1 day                      │
│  └─────────────────┘                                        │
│  ┌─────────────────┐                                        │
│  │ IP whitelist    │  CIDR ranges                           │
│  └─────────────────┘                                        │
│  ┌─────────────────┐                                        │
│  │ Bypass 2FA      │  Default false                         │
│  └─────────────────┘                                        │
│                                                              │
│  Created on the website, not the CLI.                        │
│  Legacy tokens removed November 2025.                        │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Token Revocation

┌──────────────────────────────────────────────────────────────┐
│  TOKEN LEAKED                                                │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────┐                                        │
│  │ npm token list  │  Find the token ID                     │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ npm token       │  Revoke immediately                    │
│  │ revoke <id>     │                                        │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Token unusable  │  Removed from registry                 │
│  └────────┬────────┘                                        │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │ Generate new    │  Narrow scope, short expiry            │
│  │ token           │  Store in secret store                 │
│  └─────────────────┘                                        │
│                                                              │
│  Revocation is immediate and irreversible.                   │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Audit command	`npm audit`
CI threshold	`--audit-level=moderate`
Safe fix	`npm audit fix` (within ranges)
Forced fix	`npm audit fix --force` (may break)
Transitive override	`overrides` in `package.json`
Token model	Granular only (since Nov 2025)
Token creation	Website only
Token listing	`npm token list`
Token revocation	`npm token revoke <id>`
CI token pattern	Read-only install; stage-only publish

Key takeaways:

npm audit fix respects the semver ranges in package.json. A fix that requires a major version change is not applied unless --force is passed. The --force flag is a risk decision that should be followed by a full test run and a review of the package.json changes .
Transitive dependencies may need overrides. When a vulnerable package is nested inside a parent that has not updated, npm audit fix may not resolve it. The overrides field forces the safe version across the entire tree. It is a manual intervention that should be removed once the parent updates .
Granular access tokens replaced legacy tokens in November 2025. The tokens are created on the website, not the CLI, and they have configurable expiration, package scope, permissions, IP ranges, and 2FA bypass. The stage-only permission is the safest option for CI/CD publishing because a leaked token cannot publish directly .
bypass 2FA is a risk decision for automation. A token with this setting can publish even when the account has 2FA enabled. It should be reserved for deployment tokens, scoped to specific packages, and set to expire shortly after the deployment window .
Revocation is immediate. npm token revoke <id> removes the token from the registry, and it can no longer be used. The full token is only shown once at creation, so a leaked token must be revoked rather than recovered .

Remember: The two security axes are independent. The audit addresses the code you depend on; the token addresses the authority to publish. A clean audit does not protect against a leaked token, and a scoped token does not protect against a vulnerable dependency. Both must be managed, and both have specific failure modes: the audit fails open when it is not run, and the token fails open when it is not scoped. The audit is a command that can be automated in CI; the token is a credential that must be created deliberately, scoped narrowly, and revoked quickly when it is no longer needed.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!