Remove `auth0-legacy` dependency to reduce bloat and security risks

[lukaselmer]

Checklist

• I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Describe the problem you'd like to have solved

Human issue description

The auth0-legacy feature is a cool hack for projects which need to transition gradually to v6, and don't want to import the legacy package themselves. It may have even served well for certain people and organizations for the transition period from 4 to 5.

However, the issue is that this results in additional bloat when installing this package. It installs this package with all it's dependencies (today: version 6), but also all dependencies for version 4. This doubles the attack surface regarding supply chain attacks, bloats the download size, increases the BOM, makes software clearing more difficult and expensive, and sometimes it even leads to actual vulnerabilities (e.g. #1335). And when people work with AI, the AI sometimes uses the legacy functionality, because the code is already there, instead of using the new APIs. Also, I would argue that most npm packages don't work this way. If all packages would work this way, it would be even more of a nightmare. All of this (and I think there are more arguments) is very unfortunate.

Furthermore, if users want to use both packages, they can do that using the same mechanism as you are demonstrating already. I would even argue that adding this mechanism ("auth0-legacy": "npm:auth0@^4.37.1" in package.npm) in the docs/readme may be a good idea. But since I expect most users will upgrade everything at once, I think it's better to be secure and slim by default.

PS: Examples and FAQ links are broken. I've looked into the readme. I have looked into the [Readme](https://github.com/auth0/node-auth0#readme), [Examples](https://github.com/auth0/node-auth0/blob/master/EXAMPLES.md), and [FAQ](https://github.com/auth0/node-auth0/blob/master/FAQ.md) and have not found a suitable solution or answer. Fixed in #1388

---

AI issue description / summary / restructured

While the inclusion of auth0-legacy has served as a helpful transition mechanism for projects migrating from v4 to v5 and v6, bundling a previous major version by default introduces significant downsides for the majority of modern users.

Currently, installing node-auth0 pulls in all dependencies for version 6 alongside all dependencies for version 4. I would like to propose removing auth0-legacy from the default dependencies to make the package secure and slim by default.

The Problem

Bundling an entirely separate major version of the SDK creates several cascading issues:

• Increased Attack Surface: It effectively doubles the supply chain attack surface.
• Active Vulnerabilities: Relying on older, unmaintained dependency trees can lead to actual vulnerabilities being flagged in security audits (as seen in [#1335](security audit for uuid in auth0-legacy #1335)).
• Unnecessary Bloat: It significantly inflates the download size and disk footprint.
• Compliance Overhead: It increases the Bill of Materials (BOM), making software clearing and dependency auditing more difficult and expensive for organizations.
• Poor DX with AI Assistants: Because the legacy code and types are present in the project, AI coding assistants often hallucinate or suggest using deprecated legacy functionality instead of the new v6 APIs.
• Anti-pattern: Shipping two major versions of a library in a single package deviates from standard npm ecosystem practices. If this pattern were adopted widely across the ecosystem, dependency trees would become unmanageable.

Proposed Solution

1. **Remove auth0-legacy** from the dependencies array in this package.
2. Opt-in by Default: Assume most users want the latest, slimmest, and most secure version of the package.

Migration Path / Workaround

For the subset of users who still require a gradual transition, they can achieve the exact same dual-version setup using npm's native aliasing feature.

I suggest adding a small section to the README or migration docs demonstrating how to manually include the legacy version in their own package.json:

{
  "dependencies": {
    "auth0": "^6.0.0",
    "auth0-legacy": "npm:auth0@^4.37.1"
  }
}

This approach shifts the burden of maintaining legacy dependencies to the specific projects that still need them, while providing a clean, modern default for everyone else.

Describe the ideal solution

• Drop auth0-legacy
• Optional, but useful: adopt readme to help users install both the legacy and the current version (for "power users" who want a slow transition)

Alternatives and current workarounds

• publish a "pure" package without the legacy dependency, and publish a "with-legacy-support" meta package, which includes the legacy dependency and legacy import paths
  • this might be a good solution to help
• describe "hacks" so users don't install the legacy package if they don't need it (this sounds like a lot of work 👎 )
  • needs (probably different) hacks for every widely used package manager, like npm, yarn, pnpm, bun, ...?
  • needs hacks for different bundlers, like vite, webpack, ...?

Additional context

• https://github.com/auth0/node-auth0/issues?q=auth0-legacy