[BREAKING] feat!: remove Authentication layer

[tusharpandey13]

WIP / Draft — opened for approach review before finalizing. Depends on auth-separation program decisions (deprecation window, release sequencing). Version bump and CHANGELOG will be in a separate release PR.

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.
• 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 stale @auth0/auth0-auth-js entry (also jfrog) has been removed in this PR. The remaining 3 will be cleaned up in a separate lockfile-regen PR once yarn can reach the public registry in CI.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.02985% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.40%. Comparing base (f9d6413) to head (d8fb9ad).

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1390      +/-   ##
==========================================
- Coverage   89.73%   89.40%   -0.33%     
==========================================
  Files         441      429      -12     
  Lines       20799    20383     -416     
  Branches    10146    10057      -89     
==========================================
- Hits        18663    18223     -440     
- Misses       2136     2160      +24     

Flag	Coverage Δ
alltests	89.40% <94.02%> (-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	94.59% <94.02%> (-5.41%)	⬇️

... 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.

[nandan-bhat]

We lost the mtls. endpoint alias here. The old code in src/auth/oauth.ts built the host as ${mtlsPrefix}.${options.domain} when useMTLS was set, and mtlsPrefix is gone from utils.ts now. So with useMTLS: true the token request goes to https://{domain}/oauth/token instead of https://mtls.{domain}/oauth/token.

Two ways this goes wrong:

1. The client is configured for tls_client_auth only, so the request comes back 401.
2. The client also has a secret, so the call quietly succeeds over client_secret_post and the token comes back with no cnf claim. We lose the certificate binding without any error, which is the whole point of mTLS.

For reference, auth0-auth-js handles this by sending use_mtls_endpoint_aliases: true and reading mtls_endpoint_aliases.token_endpoint from discovery.

Can we prefix the host when useMTLS is true? Also worth deciding whether the Management API baseUrl needs the alias as well once the token is certificate bound.

[nandan-bhat]

Two things here.

useMTLS?: boolean is still declared on ManagementClientOptionsWithClientAssertion, so the type advertises a combination that now always throws at construction. If we remove it from that interface, TypeScript catches the mistake at compile time instead of at runtime.

The guard is also one sided. useMTLS together with clientSecret is allowed and still puts client_secret in the body, which does not match the "mutually exclusive auth methods" reasoning in the comment above. Related to the endpoint question on line 63.

[nandan-bhat]

This check only runs on the client credentials path, since TokenProvider is only constructed from createTokenSupplier. With a static token, new ManagementClient({ domain: "tenant.auth0.com/x", token }) still builds https://tenant.auth0.com/x/api/v2 and nobody complains. An empty string also passes the regex.

Since the PR lists domain validation as a breaking change, it would be better to do this in the ManagementClient constructor (or in buildManagementBaseUrl) so it covers both auth modes, and to reject empty or whitespace only domains too.

[nandan-bhat]

We can actually resolve these. fetchToken is already async and Fern gives us core.Supplier.get (it is used in makePassthroughRequest.ts), so await core.Supplier.get(value) would work here.

As written, a dynamic header like a per request trace id shows up on Management API calls but not on the token call, which is an awkward gap to debug.

Side note on the commit message: it says this matches "the behavior fixed in v6 via PR #1392", but #1392 is still open, so this PR is currently the only place the change exists. Worth sequencing the two so they do not conflict.

[nandan-bhat]

The comment above says SDK headers always take precedence, but that only holds when the caller uses the exact same casing. headers is a plain object, so if someone passes content-type in lower case we end up with both keys and fetch joins them instead of replacing.

I reproduced it on Node 22: the request goes out with content-type: application/json, application/x-www-form-urlencoded, and the token endpoint rejects that with a 400, so the client never gets a token.

TC-2.13 only covers the exact case Content-Type, which is why it passes while the claim is not true. Suggest normalising keys to lower case before merging, or building a Headers object and using .set().

[nandan-bhat]

The table covers 9 of the roughly 19 public methods this PR removes. The ones missing that do have equivalents in auth0-auth-js:

• oauth.authorizationCodeGrantWithPKCE
• oauth.pushedAuthorization
• oauth.tokenForConnection maps to getTokenForConnection
• backchannel.authorize and backchannel.backchannelGrant map to initiateBackchannelAuthentication and backchannelAuthenticationGrant
• tokenExchange.exchangeToken maps to exchangeToken
• the four passwordless.* methods, collapsed into one row today

IDTokenValidator.validate has no public equivalent that I can find, so it is better to say that outright than to leave it out.

Also, the repo convention is a top level migration file. v5_MIGRATION_GUIDE.md exists and the Documentation list links a v6_MIGRATION_GUIDE.md, but this whole section lives only in the README and is not linked from that list.

[nandan-bhat]

Two rows here do not match the real API. In auth0-auth-js these live on a sub client: AuthClient.database is a DatabaseClient, so it should be authClient.database.signUp(...) and authClient.database.changePassword(...). authClient.signUp does not exist.

The getUserInfo row has the same problem as the section above, that method is not there at all.

Worth a footnote that getTokenByCode takes a URL and not a code, so it is not a drop in replacement for authorizationCodeGrant. The other five rows check out.

[nandan-bhat]

This section documents useMtls and customFetch on AuthClient in auth0-auth-js, but the mTLS breaking changes in this PR are on ManagementClient and the option names are different.

Nothing here tells a ManagementClient({ useMTLS: true }) user that they now have to pass a fetch option, or that useMTLS together with clientAssertionSigningKey throws at construction. Those are the customers most likely to break, and right now the thrown error message is the only clue they get.

Can we add a short "ManagementClient breaking changes" block with a working ManagementClient mTLS snippet?

[nandan-bhat]

This merged two patterns into one line. *.lcov had no trailing newline, so the edit produced *.lcov.forge/ and now neither *.lcov nor .forge/ is ignored, which means coverage output can get committed by accident.

Should be *.lcov on its own line with a newline, and .forge/ on its own line if we want it ignored. It is also unrelated to the auth separation, so it may be cleaner as a separate commit.

[nandan-bhat]

These four added entries resolve to a0us.jfrog.io, which is our internal Artifactory and returns 401 without credentials. This is a public repo.

They are also stale. @auth0/auth0-auth-js was reverted out of package.json in 53d0879, so nothing references them. Installs still work today (I checked, yarn install --frozen-lockfile passes because yarn ignores unreferenced entries), but any future jose@^6 resolution would point external contributors at a host they cannot reach. The base lockfile has zero jfrog URLs.

Can we regenerate the lockfile against the public registry and drop these?