[BREAKING] feat!: remove Authentication layer

[tusharpandey13]

What this does

Removes the Authentication layer from node-auth0, making it a Management-API-only SDK. ManagementClient continues to work — internal token acquisition is handled directly via the client credentials grant.

Changes

Area	Change
Removed	src/auth/ (9 files), src/userinfo/ — AuthenticationClient + UserInfoClient gone from main entrypoint
TokenProvider	Inlined client credentials grant (raw fetch + jose). Preserves 10s leeway refresh, in-flight de-dup, client-secret + client-assertion modes. mTLS token endpoint uses mtls.{domain} automatically. Timeout (10s) throws ManagementError(408). Non-2xx throws ManagementError with parsed OAuth error body.
Dead code	Removed src/lib/runtime.ts, auth-only src/utils.ts helpers (mtlsPrefix, resolveValueToPromise). Kept generateClientInfo for telemetry
Dependencies	Removed uuid
Docs	README updated; migration guide rebuilt with corrected v6→v7 method-mapping table, error handling section, mTLS breaking changes

Breaking changes

• AuthenticationClient and UserInfoClient removed from auth0 main entrypoint. The auth0/legacy entrypoint (auth0-legacy v4) still ships them.
• getUserInfo: UserInfoClient is removed. Use authClient.getUserInfo({ accessToken }) from @auth0/auth0-auth-js (shipped in #228). For ID token claims, use TokenResponse.claims directly.
• mTLS: Management clients with useMTLS: true must supply an explicit fetch option. Throws at construction if absent — prevents silent 401s at request time. Token endpoint uses mtls.{domain} automatically.
• mTLS + client-assertion: mutually exclusive — throws at construction if both are provided (incompatible token endpoint auth methods). useMTLS removed from ManagementClientOptionsWithClientAssertion type.
• Domain validation: domain must be a bare hostname. Slashes or query strings throw at construction.
• Error type: token acquisition failures throw ManagementError (not Error). Carries statusCode and parsed body.

Implementation notes

• TokenProvider POSTs to https://{domain}/oauth/token (or https://mtls.{domain}/oauth/token when useMTLS) with application/x-www-form-urlencoded. expires_in (seconds) → Date.now() + expires_in * 1000 for cache expiry.
• Client-assertion path uses jose (importPKCS8 + SignJWT), already a project dependency.
• User-supplied header keys normalized to lowercase before SDK headers override — prevents duplicate Content-Type/content-type causing 400s.
• Internal token request advertises node-auth0 identity in the Auth0-Client header.
• Telemetry env field (runtime fingerprint) intentionally absent — documented in code.

Tests

• token-provider.test.ts: TC-2.1–2.16. Covers credential modes, cache hit, leeway refresh, in-flight de-dup, error propagation, error-not-cached retry, expiry, mTLS customFetch forwarding, mTLS throw-on-no-fetch, domain validation, mTLS+assertion guard, header normalization, typed error body, timeout error.
• export-surface.test.ts: asserts AuthenticationClient/UserInfoClient absent from main entrypoint.
• Deleted tests/auth/**, tests/userinfo/**, tests/lib/runtime.test.ts.

Validation

• Build (CJS + ESM)
• Lint
• Unit tests — 555/555

Known issues

yarn.lock contains 3 entries (jose, oauth4webapi, openid-client) that resolve to the internal Artifactory registry (a0us.jfrog.io). These predate this PR and will cause 401s for external contributors running yarn install. The 3 will be cleaned up in a separate lockfile-regen PR.

🤖 Generated with Claude Code

Related PRs

• Migration guide (docs): docs: add Authentication API migration guide (auth0-auth-js / auth0-server-js) #1395
• Migration skill: feat(auth0): node-auth0 → auth0-auth-js/server-js migration skill agent-skills#176

[codecov]

Codecov Report

❌ Patch coverage is 95.31250% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.40%. Comparing base (f9d6413) to head (8ddcee5).

Files with missing lines	Patch %	Lines
src/management/wrapper/token-provider.ts	95.31%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1390      +/-   ##
==========================================
- Coverage   89.73%   89.40%   -0.33%     
==========================================
  Files         441      429      -12     
  Lines       20799    20380     -419     
  Branches    10146     9723     -423     
==========================================
- Hits        18663    18221     -442     
- Misses       2136     2159      +23     

Flag	Coverage Δ
alltests	89.40% <95.31%> (-0.33%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/index.ts	100.00% <ø> (ø)
src/lib/middleware/auth0-client-telemetry.ts	57.14% <ø> (-35.72%)	⬇️
src/management/wrapper/ManagementClient.ts	100.00% <ø> (ø)
src/utils.ts	100.00% <ø> (ø)
src/management/wrapper/token-provider.ts	95.77% <95.31%> (-4.23%)	⬇️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tusharpandey13]

Related PRs:

• Migration guide (docs): docs: add Authentication API migration guide (auth0-auth-js / auth0-server-js) #1395
• Migration skill: feat(auth0): node-auth0 → auth0-auth-js/server-js migration skill agent-skills#176

[tusharpandey13]

Deferred items and follow-up plan

Consolidating the remaining review threads here so there is a single place to track them, and resolving those threads against this list.

Most of these are fallout from the auth-separation work itself: it orphaned some now-dead code and exposed the fetch option. Grouping the code cleanup into one follow-up PR that lands before the v7 GA cut.

Follow-up cleanup PR (pre-v7-GA):

• Remove dead exports (src/lib/errors.ts, src/lib/models.ts): ResponseError, FetchError, and JSONApiResponse are exported from the entrypoint but back code paths the auth-separation removed. Deleting public exports is breaking, so it has to land within v7. (TimeoutError stays; it is still used internally by the retry path, so at most it comes off the public export.)
• fetch option test + docs (ManagementClient.ts): fetch is already a typed public option; this is a test asserting Management requests route through a supplied fetch, plus a README entry. No code/contract change.
• Remove dead pre() (auth0-client-telemetry.ts): the middleware pre() hook is unreachable after the pipeline was dropped. It is internal-only (never re-exported) and the file is .fernignored, so a hand edit is safe. No contract change.

Separate PR (not auth-separation cleanup):

• Domain validation coverage (token-provider.ts): the domain guard only runs on the client-credentials path; the static-token constructor skips it. This is a pre-existing gap, and closing it adds a new throw, so it belongs in its own change rather than bundled with cleanup.

Still owed in this PR (not deferred): expanding the migration section with the full list of removed public exports (IdTokenValidateOptions, TokenSet, SUBJECT_TOKEN_TYPES, the token-for-connection constants, AuthenticationClientOptions, and the removed error/response types).