feat: Add refresh token grant support (MRRT)

[tanya732]

Summary

Adds support for Auth0 refresh-token grants, including Multi-Resource Refresh Token (MRRT) flows. The SDK performs token exchanges and returns results, while applications are responsible for refresh-token storage, access-token caching, and refresh-token rotation handling.

Changes

• Added AuthenticationController.renewAuth(...) with overloads for:

  • renewAuth(refreshToken, domain) (recommended)
  • renewAuth(refreshToken)
  • renewAuth(refreshToken, request)

• Added RenewAuthRequest with withAudience(...), withScope(...), and execute() methods.

• Added scope support to Tokens via getScope() while preserving backward compatibility.

• Updated RequestProcessor to support refresh-token grants and propagate granted scope information into Tokens.

Notes

• Auth0 MRRT requests may fall back to the default audience if the requested audience is not allowed. Applications should validate the returned access token audience.
• When refresh-token rotation is enabled, applications must persist the new refresh token returned by execute().
• Refresh-token grants typically do not return an ID token.
• For Multiple Custom Domains (MCD), applications should persist and reuse the original domain via renewAuth(refreshToken, domain).

[tanya732]

@copilot Please review

[Copilot]

@copilot Please review

Here is the review of the MRRT implementation (all tests pass ✅):

Overall: The implementation is well-structured and correct. The builder-style RenewAuthRequest, the three renewAuth overloads, and the scope propagation through the normal login flow all look good.

---

Observations / items addressed:

1. Javadoc gap in RenewAuthRequest (fixed – 4e39c0d): The class-level doc referenced only renewAuth(String, String) and renewAuth(String), missing renewAuth(String, HttpServletRequest). Added the missing @link.

2. Tokens.serialVersionUID not bumped: Adding scope to a Serializable class without changing the UID is backward-compatible (old serialized instances deserialize with scope = null), so this is fine as-is. Worth noting that it's intentional.

3. buildRenewAuthRequest(refreshToken) uses instanceof for the static-domain check: This is safe given StaticDomainProvider and ResolverDomainProvider are the only two internal implementations of DomainProvider. No action needed, just something to be aware of if new providers are added later.

4. execute() is callable multiple times: Unlike AuthorizeUrl.build(), there is no guard against repeated calls. Each invocation will fire a new token request. This is actually fine for retries, and the Javadoc warns about rotation, so no change needed.

5. No explicit scope assertion in RequestProcessorTest for the handle() code-exchange flow: The scope field is set in mergeTokens() / exchangeCodeForTokens(), but the test coverage for that path relies on mock responses that don't set scope. Consider adding a test that verifies scope is correctly plumbed through from TokenHolder.getScope() when handle() is called.