feat: Add parseIdToken utility to public API (#1537)

Author: opfeffer

EXAMPLES.md

@@ -137,6 +137,21 @@ auth0.auth
 
 This endpoint requires an access token that was granted the `/userinfo` audience. Check that the authentication request that returned the access token included an audience value of `https://{YOUR_AUTH0_DOMAIN}.auth0.com/userinfo`.
 
+### Parse user profile from an ID token locally
+
+If you already have credentials (e.g. from `webAuth.authorize()` or `credentialsManager.getCredentials()`), you can extract the user profile from the ID token without a network request:
+
+```js
+import Auth0, { parseIdToken } from 'react-native-auth0';
+
+const auth0 = new Auth0({ domain, clientId });
+const credentials = await auth0.webAuth.authorize({ scope: 'openid profile email' });
+const user = parseIdToken(credentials.idToken);
+// user.sub, user.name, user.email, etc.
+```
+
+This is the same parsing that `Auth0Provider` performs internally. It's useful when you manage auth state yourself via the `Auth0` class and want to avoid the network round-trip of `auth.userInfo()`.
+
 ### Getting new access token with refresh token
 
 ```js

src/core/utils/__tests__/parseIdToken.spec.ts

@@ -0,0 +1,61 @@
+import { parseIdToken } from '../parseIdToken';
+import { jwtDecode } from 'jwt-decode';
+
+jest.mock('jwt-decode');
+
+describe('parseIdToken', () => {
+  const mockJwtDecode = jwtDecode as jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should return a User with decoded profile claims', () => {
+    mockJwtDecode.mockReturnValue({
+      sub: 'auth0|123',
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+      email_verified: true,
+      given_name: 'Jane',
+      family_name: 'Doe',
+    });
+
+    const user = parseIdToken('mock-id-token');
+
+    expect(user.sub).toBe('auth0|123');
+    expect(user.name).toBe('Jane Doe');
+    expect(user.email).toBe('jane@example.com');
+    expect(user.emailVerified).toBe(true);
+    expect(user.givenName).toBe('Jane');
+    expect(user.familyName).toBe('Doe');
+  });
+
+  it('should exclude protocol claims', () => {
+    mockJwtDecode.mockReturnValue({
+      sub: 'auth0|123',
+      iss: 'https://tenant.auth0.com/',
+      aud: 'client-id',
+      exp: 9999999999,
+      iat: 1000000000,
+    });
+
+    const user = parseIdToken('mock-id-token');
+
+    expect(user.sub).toBe('auth0|123');
+    expect((user as any).iss).toBeUndefined();
+    expect((user as any).aud).toBeUndefined();
+    expect((user as any).exp).toBeUndefined();
+    expect((user as any).iat).toBeUndefined();
+  });
+
+  it('should throw if the token is missing the sub claim', () => {
+    mockJwtDecode.mockReturnValue({
+      name: 'No Sub',
+      email: 'nosub@example.com',
+    });
+
+    expect(() => parseIdToken('bad-token')).toThrow(
+      'ID token is missing the required "sub" claim.'
+    );
+  });
+});

src/core/utils/index.ts

@@ -1,4 +1,5 @@
 export * from './validation';
 export * from './conversion';
 export * from './fetchWithTimeout';
+export * from './parseIdToken';
 export * from './scope';

src/core/utils/parseIdToken.ts

@@ -0,0 +1,27 @@
+import type { User } from '../../types';
+import { Auth0User } from '../models';
+
+/**
+ * Decodes a JWT ID token and returns a {@link User} object with standard OIDC
+ * profile claims (camelCased) and any custom claims present in the token.
+ *
+ * This provides the same user-parsing behavior that {@link Auth0Provider} uses
+ * internally, for consumers managing auth state directly via the {@link Auth0} class.
+ *
+ * @param idToken - A JWT ID token string (e.g. from `credentials.idToken`).
+ * @returns A parsed {@link User} containing profile and custom claims.
+ * @throws If the token is missing the required `sub` claim.
+ *
+ * @example
+ * ```typescript
+ * import Auth0, { parseIdToken } from 'react-native-auth0';
+ *
+ * const auth0 = new Auth0({ domain, clientId });
+ * const credentials = await auth0.webAuth.authorize({ scope: 'openid profile email' });
+ * const user = parseIdToken(credentials.idToken);
+ * // user.sub, user.name, user.email, etc.
+ * ```
+ */
+export function parseIdToken(idToken: string): User {
+  return Auth0User.fromIdToken(idToken);
+}

src/index.ts

@@ -11,6 +11,7 @@ export {
   MyAccountError,
 } from './core/models';
 export { TimeoutError } from './core/utils/fetchWithTimeout';
+export { parseIdToken } from './core/utils';
 export { TokenType } from './types/common';
 export { Auth0Provider } from './hooks/Auth0Provider';
 export { useAuth0 } from './hooks/useAuth0';