Merge branch 'main' into fix-typescript-4.6.3-compilation

Author: gyaneshgouraw-okta

.github/workflows/test.yml

@@ -37,12 +37,6 @@ jobs:
         with:
           node: ${{ env.NODE_VERSION }}
 
-      - name: Save build artifacts
-        uses: actions/cache/save@v4
-        with:
-          path: .
-          key: ${{ env.CACHE_KEY }}
-
   unit:
     needs: build # Require build to complete before running tests
 
@@ -59,11 +53,8 @@ jobs:
           node-version: ${{ env.NODE_VERSION }}
           cache: npm
 
-      - name: Restore build artifacts
-        uses: actions/cache/restore@v4
-        with:
-          path: .
-          key: ${{ env.CACHE_KEY }}
+      - name: Install dependencies
+        run: npm ci --include=dev
 
       - name: Run tests
         run: npm run test

.version

@@ -1 +1 @@
-v2.3.0
+v2.5.0

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Change Log
 
+## [v2.5.0](https://github.com/auth0/auth0-react/tree/v2.5.0) (2025-09-17)
+[Full Changelog](https://github.com/auth0/auth0-react/compare/v2.4.0...v2.5.0)
+
+**Added**
+- Add support for DPoP [\#869](https://github.com/auth0/auth0-react/pull/869) ([martinml](https://github.com/martinml))
+
+## [v2.4.0](https://github.com/auth0/auth0-react/tree/v2.4.0) (2025-07-22)
+[Full Changelog](https://github.com/auth0/auth0-react/compare/v2.3.0...v2.4.0)
+
+**Added**
+- Bump @auth0/auth0-spa-js from 2.2.0 to 2.3.0 [\#858](https://github.com/auth0/auth0-react/pull/858) ([dependabot[bot]](https://github.com/apps/dependabot))
+
+**Fixed**
+- Enhance type safety in Auth0Provider and reducer by introducing generic user type [\#842](https://github.com/auth0/auth0-react/pull/842) ([gyaneshgouraw-okta](https://github.com/gyaneshgouraw-okta))
+
 ## [v2.3.0](https://github.com/auth0/auth0-react/tree/v2.3.0) (2025-01-21)
 [Full Changelog](https://github.com/auth0/auth0-react/compare/v2.2.4...v2.3.0)
 

EXAMPLES.md

@@ -8,6 +8,7 @@
 - [Protecting a route in a Next.js app (in SPA mode)](#protecting-a-route-in-a-nextjs-app-in-spa-mode)
 - [Use with Auth0 organizations](#use-with-auth0-organizations)
 - [Protecting a route with a claims check](#protecting-a-route-with-a-claims-check)
+- [Device-bound tokens with DPoP](#device-bound-tokens-with-dpop)
 
 ## Use with a Class Component
 
@@ -339,3 +340,234 @@ const Page = withAuthenticationRequired(
   withClaimCheck(Component, checkClaims, '/missing-roles' )
 );
 ```
+
+## Device-bound tokens with DPoP
+
+**Demonstrating Proof-of-Possession** —or simply **DPoP**— is a recent OAuth 2.0 extension defined in [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449).
+
+It defines a mechanism for securely binding tokens to a specific device using cryptographic signatures. Without it, **a token leak caused by XSS or other vulnerabilities could allow an attacker to impersonate the real user.**
+
+To support DPoP in `auth0-react`, some APIs available in modern browsers are required:
+
+- [Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto): allows to create and use cryptographic keys, which are used to generate the proofs (i.e. signatures) required for DPoP.
+
+- [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API): enables the use of cryptographic keys [without exposing the private material](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto#storing_keys).
+
+The following OAuth 2.0 flows are currently supported by `auth0-react`:
+
+- [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) (`authorization_code`).
+
+- [Refresh Token Flow](https://auth0.com/docs/secure/tokens/refresh-tokens) (`refresh_token`).
+
+- [Custom Token Exchange Flow](https://auth0.com/docs/authenticate/custom-token-exchange) (`urn:ietf:params:oauth:grant-type:token-exchange`).
+
+> [!IMPORTANT]
+> Currently, only the `ES256` algorithm is supported.
+
+### Enabling DPoP
+
+DPoP is disabled by default. To enable it, set the `useDpop` option to `true` when invoking the provider. For example:
+
+```jsx
+<Auth0Provider
+  domain="YOUR_AUTH0_DOMAIN"
+  clientId="YOUR_AUTH0_CLIENT_ID"
+  useDpop={true} // 👈
+  authorizationParams={{ redirect_uri: window.location.origin }}
+>
+```
+
+After enabling DPoP, **every new session using a supported OAuth 2.0 flow in Auth0 will begin transparently to use tokens that are cryptographically bound to the current browser**.
+
+> [!IMPORTANT]
+> DPoP will only be used for new user sessions created after enabling it. Any previously existing sessions will continue using non-DPoP tokens until the user logs in again.
+>
+> You decide how to handle this transition. For example, you might require users to log in again the next time they use your application.
+
+> [!NOTE]
+> Using DPoP requires storing some temporary data in the user's browser. When you log the user out with `logout()`, this data is deleted.
+
+> [!TIP]
+> If all your clients are already using DPoP, you may want to increase security by making Auth0 reject any non-DPoP interactions. See [the docs on Sender Constraining](https://auth0.com/docs/secure/sender-constraining/configure-sender-constraining) for details.
+
+### Using DPoP in your own requests
+
+You use a DPoP token the same way as a "traditional" access token, except it must be sent to the server with an `Authorization: DPoP <token>` header instead of the usual `Authorization: Bearer <token>`.
+
+To determine the type of a token, use the `detailedResponse` option in `getAccessTokenSilently()` to access the `token_type` property, which will be either `DPoP` or `Bearer`.
+
+For internal requests sent by `auth0-react` to Auth0, simply enable the `useDpop` option and **every interaction with Auth0 will be protected**.
+
+However, **to use DPoP with a custom, external API, some additional work is required**. The `useAuth()` hook provides some low-level methods to help with this:
+
+- `getDpopNonce()`
+- `setDpopNonce()`
+- `generateDpopProof()`
+
+However, due to the nature of how DPoP works, **this is not a trivial task**:
+
+- When a nonce is missing or expired, the request may need to be retried.
+- Received nonces must be stored and managed.
+- DPoP headers must be generated and included in every request, and regenerated for retries.
+
+Because of this, we recommend using the provided `fetchWithAuth()` method, which **handles all of this for you**.
+
+#### Simple usage
+
+The `fetchWithAuth()` method is a drop-in replacement for the native `fetch()` function from the Fetch API, so if you're already using it, the change will be minimal.
+
+For example, if you had this code:
+
+```js
+await fetch('https://api.example.com/foo', {
+  method: 'GET',
+  headers: { 'user-agent': 'My Client 1.0' }
+});
+
+console.log(response.status);
+console.log(response.headers);
+console.log(await response.json());
+```
+
+You would change it as follows:
+
+```js
+const { createFetcher } = useAuth0();
+
+const fetcher = createFetcher({
+  dpopNonceId: 'my_api_request'
+});
+
+await fetcher.fetchWithAuth('https://api.example.com/foo', {
+  method: 'GET',
+  headers: { 'user-agent': 'My Client 1.0' }
+});
+
+console.log(response.status);
+console.log(response.headers);
+console.log(await response.json());
+```
+
+When using `fetchWithAuth()`, the following will be handled for you automatically:
+
+- Use `getAccessTokenSilently()` to get the access token to inject in the headers.
+- Generate and inject DPoP headers when needed.
+- Store and update any DPoP nonces.
+- Handle retries caused by a rejected nonce.
+
+> [!IMPORTANT]
+> If DPoP is enabled in the provider, a `dpopNonceId` **must** be present in the `createFetcher()` parameters, since it’s used to keep track of the DPoP nonces for each request.
+
+#### Advanced usage
+
+If you need something more complex than the example above, you can provide a custom implementation in the `fetch` property.
+
+However, since `auth0-react` needs to make decisions based on HTTP responses, your implementation **must return an object with _at least_ two properties**:
+
+1. `status`: the response status code as a number.
+2. `headers`: the response headers as a plain object or as a Fetch API’s Headers-like interface.
+
+Whatever it returns, it will be passed as the output of the `fetchWithAuth()` method.
+
+Your implementation will be called with a standard, ready-to-use [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object, which will contain any headers needed for authorization and DPoP usage (if enabled). Depending on your needs, you can use this object directly or treat it as a container with everything required to make the request your own way.
+
+##### Example with `axios`
+
+```js
+const { createFetcher } = useAuth0();
+
+const fetcher = createFetcher({
+  dpopNonceId: 'my_api_request',
+  fetch: (request) =>
+    // The `Request` object has everything you need to do a request in a
+    // different library. Make sure that your output meets the requirements
+    // about the `status` and `headers` properties.
+    axios.request({
+      url: request.url,
+      method: request.method,
+      data: request.body,
+      headers: Object.fromEntries(request.headers),
+      timeout: 2000,
+      // etc.
+    }),
+  },
+});
+
+const response = await fetcher.fetchWithAuth('https://api.example.com/foo', {
+  method: 'POST',
+  body: JSON.stringify({ name: 'John Doe' }),
+  headers: { 'user-agent': 'My Client 1.0' },
+});
+
+console.log(response.status);
+console.log(response.headers);
+console.log(response.data);
+```
+
+##### Timeouts with native `fetch()`
+
+The Fetch API doesn’t support passing a timeout value directly; instead, you’re expected to use an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). For example:
+
+```js
+const { createFetcher } = useAuth0();
+
+const fetcher = createFetcher();
+
+await fetcher.fetchWithAuth('https://api.example.com/foo', {
+  signal: AbortSignal.timeout(2000)
+});
+```
+
+This works, but if you define your request parameters statically when your app starts and then call `fetchWithAuth()` after an indeterminate amount of time, you'll find that **the request will timeout immediately**. This happens because the `AbortSignal` **starts counting time as soon as it is created**.
+
+To work around this, you can pass a thin wrapper over the native `fetch()` so that a new `AbortSignal` is created each time a request is made:
+
+```js
+const { createFetcher } = useAuth0();
+
+const fetcher = createFetcher({
+  fetch: (request) => fetch(request, { signal: AbortSignal.timeout(2000) })
+});
+
+await fetcher.fetchWithAuth('https://api.example.com/foo');
+```
+
+##### Having a base URL
+
+If you need to make requests to different endpoints of the same API, passing a `baseUrl` to `createFetcher()` can be useful:
+
+```js
+const { createFetcher } = useAuth0();
+
+const fetcher = createFetcher({
+  baseUrl: 'https://api.example.com'
+});
+
+await fetcher.fetchWithAuth('/foo'); // => https://api.example.com/foo
+await fetcher.fetchWithAuth('/bar'); // => https://api.example.com/bar
+await fetcher.fetchWithAuth('/xyz'); // => https://api.example.com/xyz
+
+// If the passed URL is absolute, `baseUrl` will be ignored for convenience:
+await fetcher.fetchWithAuth('https://other-api.example.com/foo');
+```
+
+##### Passing an access token
+
+The `fetchWithAuth()` method assumes you’re using the SDK to get the access token for the request. This means that by default, it will always call `getAccessTokenSilently()` internally before making the request.
+
+However, if you already have an access token or need to pass specific parameters to `getAccessTokenSilently()`, you can override this behavior with a custom access token factory, like so:
+
+```js
+const { createFetcher, getAccessTokenSilently } = useAuth0();
+
+createFetcher({
+  getAccessToken: () =>
+    getAccessTokenSilently({
+      authorizationParams: {
+        audience: '<SOME_AUDIENCE>',
+        scope: '<SOME_SCOPE>'
+        // etc.
+      }
+    })
+});
+```

FAQ.md

@@ -4,6 +4,7 @@
 
 1. [User is not logged in after page refresh](#1-user-is-not-logged-in-after-page-refresh)
 2. [User is not logged in after successful sign in with redirect](#2-user-is-not-logged-in-after-successful-sign-in-with-redirect)
+3. [Skip the Auth0 login page](#3-skip-the-auth0-login-page)
 
 ## 1. User is not logged in after page refresh
 
@@ -20,3 +21,33 @@ In this case Silent Authentication will not work because it relies on a hidden i
 ## 2. User is not logged in after successful sign in with redirect
 
 If after successfully logging in, your user returns to your SPA and is still not authenticated, do _not_ refresh the page - go to the Network tab on Chrome and confirm that the POST to `oauth/token` resulted in an error `401 Unauthorized`. If this is the case, your tenant is most likely misconfigured. Go to your **Application Properties** in your application's settings in the [Auth0 Dashboard](https://manage.auth0.com) and make sure that `Application Type` is set to `Single Page Application` and `Token Endpoint Authentication Method` is set to `None` (**Note:** there is a known issue with the Auth0 "Default App", if you are unable to set `Token Endpoint Authentication Method` to `None`, create a new Application of type `Single Page Application` or see the advice in [issues/93](https://github.com/auth0/auth0-react/issues/93#issuecomment-673431605))
+
+## 3. Skip the Auth0 login page
+
+When integrating with third party providers such as Google or Microsoft, being redirected to Auth0 before being redirected to the corresponding provider can be sub-optimal in terms of user-experience.
+If you only have a single connection enabled, or you know up front how the user wants to authenticate, you can set the `connection` parameter when calling `loginWithRedirect()` or `loginWithPopup()`:
+
+```js
+loginWithRedirect({
+  // ...
+  authorizationParams: {
+    connection: 'connection_logical_identifier'
+  }
+})
+```
+
+Doing so for connections such as Google or Microsoft, would automatically redirect you to them instead of showing the Auth0 login page first.
+
+Additionally, if you are using `withAuthenticationRequired`, you may want it to pick up the same connection when it would redirect for login. To do so, you should provide the `connection` property when configuring `withAuthenticationRequired`:
+
+```js
+withAuthenticationRequired(Component, { 
+  loginOptions: {
+    authorizationParams: {
+      connection: 'connection_logical_identifier'
+    }
+  }
+})
+```
+
+ℹ️ You can find the connection's logical identifier as the **connection name** in the connection settings in the Auth0 dashboard for your tenant.

__mocks__/@auth0/auth0-spa-js.tsx

@@ -10,6 +10,10 @@ const isAuthenticated = jest.fn(() => false);
 const loginWithPopup = jest.fn();
 const loginWithRedirect = jest.fn();
 const logout = jest.fn();
+const getDpopNonce = jest.fn();
+const setDpopNonce = jest.fn();
+const generateDpopProof = jest.fn();
+const createFetcher = jest.fn();
 
 export const Auth0Client = jest.fn(() => {
   return {
@@ -25,5 +29,9 @@ export const Auth0Client = jest.fn(() => {
     loginWithPopup,
     loginWithRedirect,
     logout,
+    getDpopNonce,
+    setDpopNonce,
+    generateDpopProof,
+    createFetcher,
   };
 });