feat(backend): add experimental OAuth token exchange for OAuth applications

.changeset/oauth-application-token-exchange.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': minor
+---
+
+Add an experimental `clerkClient.oauthApplications.__experimental_exchangeToken()` method for performing an OAuth 2.0 Token Exchange (RFC 8693) on behalf of an OAuth application. Pass your publishable key, the application's client ID and client secret, a user's OAuth access token, and the target `resource` to receive a new access token for that resource, for example to call a downstream API on a user's behalf. The request goes to your instance's token endpoint, derived from the publishable key (or from `proxyUrl` when set), so it does not require a secret key.
+
+The method checks its inputs before making any request: `resource` must be an absolute URI without a fragment that uses `https` (or `http` on `localhost`, `127.0.0.1` or `[::1]`), and each `scope` element must be a single scope token, without spaces, `"`, `\` or non-ASCII characters. Invalid input throws an `OAuthTokenExchangeError` with code `invalid_request` and no `status`. Only a `200` response with a well-formed token response counts as success; any other success status, or a response with missing or mistyped members, throws an `OAuthTokenExchangeError` with code `invalid_response`. If the token endpoint rejects the exchange, the error carries the OAuth error code in `code` (also available as `error`), `errorDescription`, and HTTP `status`. `OAuthTokenExchangeError` is exported from `@clerk/backend/errors`. Network failures from `fetch` are not wrapped.

packages/backend/src/__tests__/exports.test.ts

@@ -25,6 +25,7 @@ describe('subpath /errors exports', () => {
         "ClerkAPIResponseError",
         "MachineTokenVerificationError",
         "MachineTokenVerificationErrorCode",
+        "OAuthTokenExchangeError",
         "SignJWTError",
         "TokenVerificationError",
         "TokenVerificationErrorAction",