E401 Unauthorized when publishing with expired limited token

Short answer

The npm CLI should not, and currently does not, locally reject a token based on expiry. Enforcement is registry-side: the CLI sends the token, the registry rejects it with E401, and the CLI surfaces that error. That said, a client-side warning is a reasonable enhancement, and it aligns with least-privilege hygiene.

Confirmed facts vs. likely explanation

Confirmed: npm access tokens can carry an expiry, and when one expires, the registry rejects it with E401 Unauthorized, which is what happens during publish. Confirmed: the CLI treats tokens as opaque bearer credentials and does not pre-validate expiry locally. Likely explanation: because tokens are opaque strings (not JWTs), the CLI cannot decode an exp claim on its own; any local check must come from registry-reported metadata, such as npm token list. Legacy tokens created before expiry support lack an expiry field, so a blanket local check cannot apply uniformly.

What to do for this case

1. Run npm token list to confirm whether the failing token is expired.
2. Revoke it with npm token revoke.
3. Create a new limited token with an expiry set, then re-authenticate and publish.
4. Verify with npm publish --loglevel verbose that the E401 came from the registry, not a local check.

Least-privilege alignment

Least-privilege guidance favors short-lived, scoped tokens plus registry-side enforcement. Automatic local invalidation is defense-in-depth but cannot replace server enforcement, since registries must reject stale tokens regardless of client behavior. The preferred mechanism is: registry as authority, CLI warns when a stored token is expired or nearing expiry, and users rotate tokens and prefer granular, expiring tokens over legacy ones.

Verification

Run npm token list with the affected profile to confirm the failing token shows an expired status. Reproduce the publish with npm publish --loglevel verbose to confirm the E401 originates from the registry response, not a local check. After minting a new expiring limited token, retry the publish to confirm the error resolves, then set a calendar reminder or CI rotation before the new expiry.

Caveats

Do not assume tokens are JWTs with a decodable exp claim; npm auth tokens are opaque, so any local expiry check depends on registry metadata, which may be unavailable offline. Legacy/forever tokens without expiry remain valid until revoked; relying on expiry alone does not cover them. Exact CLI behavior around token warnings is version-sensitive and may change across npm releases.

Conclusion

The CLI should warn when a stored token is expired or nearing expiry, but the registry should remain the authority. For the E401 case: confirm the token status, revoke it, create a new limited token with an expiry, and re-authenticate. If the token list shows the token is expired, the registry is doing its job; the CLI warning is a UX improvement, not a security boundary.