feat(backend,types,clerk-js,clerk-react): Add the fva sessionClaim (#4061)

Co-authored-by: Haris Chaniotakis <haris@clerk.dev>

Author: panteliselef

.changeset/eleven-apricots-rest.md

@@ -0,0 +1,26 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/backend": minor
+"@clerk/clerk-react": minor
+"@clerk/types": minor
+---
+
+Experimental support: Expect a new sessionClaim called `fva` that tracks the age of verified factor groups.
+
+### Server side
+
+This can be applied to any helper that returns the auth object
+
+**Nextjs example**
+
+```ts
+auth(). __experimental_factorVerificationAge
+```
+
+### Client side
+
+**React example**
+```ts
+const { session } = useSession()
+session?. __experimental_factorVerificationAge
+```

package-lock.json

@@ -34,6 +34,13 @@ export type SignedInAuthObject = {
   orgRole: OrganizationCustomRoleKey | undefined;
   orgSlug: string | undefined;
   orgPermissions: OrganizationCustomPermissionKey[] | undefined;
+  /**
+   * Factor Verification Age
+   * Each item represents the minutes that have passed since the last time a first or second factor were verified.
+   * [fistFactorAge, secondFactorAge]
+   * @experimental This API is experimental and may change at any moment.
+   */
+  __experimental_factorVerificationAge: [number | null, number | null];
   getToken: ServerGetToken;
   has: CheckAuthorizationWithCustomPermissions;
   debug: AuthObjectDebug;
@@ -51,6 +58,13 @@ export type SignedOutAuthObject = {
   orgRole: null;
   orgSlug: null;
   orgPermissions: null;
+  /**
+   * Factor Verification Age
+   * Each item represents the minutes that have passed since the last time a first or second factor were verified.
+   * [fistFactorAge, secondFactorAge]
+   * @experimental This API is experimental and may change at any moment.
+   */
+  __experimental_factorVerificationAge: [null, null];
   getToken: ServerGetToken;
   has: CheckAuthorizationWithCustomPermissions;
   debug: AuthObjectDebug;
@@ -86,6 +100,7 @@ export function signedInAuthObject(
     org_slug: orgSlug,
     org_permissions: orgPermissions,
     sub: userId,
+    fva: __experimental_factorVerificationAge,
   } = sessionClaims;
   const apiClient = createBackendApiClient(authenticateContext);
   const getToken = createGetToken({
@@ -103,6 +118,7 @@ export function signedInAuthObject(
     orgRole,
     orgSlug,
     orgPermissions,
+    __experimental_factorVerificationAge,
     getToken,
     has: createHasAuthorization({ orgId, orgRole, orgPermissions, userId }),
     debug: createDebug({ ...authenticateContext, sessionToken }),
@@ -122,6 +138,7 @@ export function signedOutAuthObject(debugData?: AuthObjectDebugData): SignedOutA
     orgRole: null,
     orgSlug: null,
     orgPermissions: null,
+    __experimental_factorVerificationAge: [null, null],
     getToken: () => Promise.resolve(null),
     has: () => false,
     debug: createDebug(debugData),

packages/backend/src/tokens/authObjects.ts

@@ -39,6 +39,7 @@ export class Session extends BaseResource implements SessionResource {
   actor!: ActJWTClaim | null;
   user!: UserResource | null;
   publicUserData!: PublicUserData;
+  __experimental_factorVerificationAge: [number | null, number | null] = [null, null];
   expireAt!: Date;
   abandonAt!: Date;
   createdAt!: Date;
@@ -235,6 +236,7 @@ export class Session extends BaseResource implements SessionResource {
     this.status = data.status;
     this.expireAt = unixEpochToDate(data.expire_at);
     this.abandonAt = unixEpochToDate(data.abandon_at);
+    this.__experimental_factorVerificationAge = data.factor_verification_age;
     this.lastActiveAt = unixEpochToDate(data.last_active_at);
     this.lastActiveOrganizationId = data.last_active_organization_id;
     this.actor = data.actor;

packages/clerk-js/src/core/resources/Session.ts

@@ -31,7 +31,8 @@ function sessionChanged(prev: SessionResource, next: SessionResource): boolean {
   return (
     prev.id !== next.id ||
     prev.updatedAt.getTime() < next.updatedAt.getTime() ||
-    sessionUserMembershipPermissionsChanged(next, prev)
+    sessionFVAChanged(prev, next) ||
+    sessionUserMembershipPermissionsChanged(prev, next)
   );
 }
 
@@ -49,6 +50,13 @@ function userMembershipsChanged(prev: UserResource, next: UserResource): boolean
   );
 }
 
+function sessionFVAChanged(prev: SessionResource, next: SessionResource): boolean {
+  return (
+    prev.__experimental_factorVerificationAge[0] !== next.__experimental_factorVerificationAge[0] ||
+    prev.__experimental_factorVerificationAge[1] !== next.__experimental_factorVerificationAge[1]
+  );
+}
+
 function sessionUserMembershipPermissionsChanged(prev: SessionResource, next: SessionResource): boolean {
   if (prev.lastActiveOrganizationId !== next.lastActiveOrganizationId) {
     return true;

packages/clerk-js/src/utils/memoizeStateListenerCallback.ts

@@ -9,4 +9,5 @@ export const [AuthContext, useAuthContext] = createContextAndHook<{
   orgRole: OrganizationCustomRoleKey | null | undefined;
   orgSlug: string | null | undefined;
   orgPermissions: OrganizationCustomPermissionKey[] | null | undefined;
+  __experimental_factorVerificationAge: [number | null, number | null];
 }>('AuthContext');

packages/react/src/contexts/AuthContext.ts

@@ -35,15 +35,35 @@ export function ClerkContextProvider(props: ClerkContextProvider): JSX.Element |
   const clerkCtx = React.useMemo(() => ({ value: clerk }), [clerkLoaded]);
   const clientCtx = React.useMemo(() => ({ value: state.client }), [state.client]);
 
-  const { sessionId, session, userId, user, orgId, actor, organization, orgRole, orgSlug, orgPermissions } =
-    derivedState;
+  const {
+    sessionId,
+    session,
+    userId,
+    user,
+    orgId,
+    actor,
+    organization,
+    orgRole,
+    orgSlug,
+    orgPermissions,
+    __experimental_factorVerificationAge,
+  } = derivedState;
 
   const authCtx = React.useMemo(() => {
-    const value = { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions };
+    const value = {
+      sessionId,
+      userId,
+      actor,
+      orgId,
+      orgRole,
+      orgSlug,
+      orgPermissions,
+      __experimental_factorVerificationAge,
+    };
     return { value };
-  }, [sessionId, userId, actor, orgId, orgRole, orgSlug]);
-  const userCtx = React.useMemo(() => ({ value: user }), [userId, user]);
+  }, [sessionId, userId, actor, orgId, orgRole, orgSlug, __experimental_factorVerificationAge]);
   const sessionCtx = React.useMemo(() => ({ value: session }), [sessionId, session]);
+  const userCtx = React.useMemo(() => ({ value: user }), [userId, user]);
   const organizationCtx = React.useMemo(() => {
     const value = {
       organization: organization,

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -26,6 +26,7 @@ const deriveFromSsrInitialState = (initialState: InitialState) => {
   const orgPermissions = initialState.orgPermissions as OrganizationCustomPermissionKey[];
   const orgSlug = initialState.orgSlug;
   const actor = initialState.actor;
+  const __experimental_factorVerificationAge = initialState.__experimental_factorVerificationAge;
 
   return {
     userId,
@@ -38,6 +39,7 @@ const deriveFromSsrInitialState = (initialState: InitialState) => {
     orgPermissions,
     orgSlug,
     actor,
+    __experimental_factorVerificationAge,
   };
 };
 
@@ -46,6 +48,9 @@ const deriveFromClientSideState = (state: Resources) => {
   const user = state.user;
   const sessionId: string | null | undefined = state.session ? state.session.id : state.session;
   const session = state.session;
+  const __experimental_factorVerificationAge: [number | null, number | null] = state.session
+    ? state.session.__experimental_factorVerificationAge
+    : [null, null];
   const actor = session?.actor;
   const organization = state.organization;
   const orgId: string | null | undefined = state.organization ? state.organization.id : state.organization;
@@ -67,5 +72,6 @@ const deriveFromClientSideState = (state: Resources) => {
     orgSlug,
     orgPermissions,
     actor,
+    __experimental_factorVerificationAge,
   };
 };

packages/react/src/utils/deriveState.ts

@@ -104,6 +104,13 @@ export interface SessionJSON extends ClerkResourceJSON {
   object: 'session';
   id: string;
   status: SessionStatus;
+  /**
+   * Factor Verification Age
+   * Each item represents the minutes that have passed since the last time a first or second factor were verified.
+   * [fistFactorAge, secondFactorAge]
+   * @experimental This API is experimental and may change at any moment.
+   */
+  factor_verification_age: [number | null, number | null];
   expire_at: number;
   abandon_at: number;
   last_active_at: number;

packages/types/src/json.ts

@@ -101,6 +101,14 @@ export interface JwtPayload extends CustomJwtSessionClaims {
    */
   org_permissions?: OrganizationCustomPermissionKey[];
 
+  /**
+   * Factor Verification Age
+   * Each item represents the minutes that have passed since the last time a first or second factor were verified.
+   * [fistFactorAge, secondFactorAge]
+   * @experimental This API is experimental and may change at any moment.
+   */
+  fva: [number | null, number | null];
+
   /**
    * Any other JWT Claim Set member.
    */

packages/types/src/jwtv2.ts

@@ -55,6 +55,13 @@ export interface SessionResource extends ClerkResource {
   status: SessionStatus;
   expireAt: Date;
   abandonAt: Date;
+  /**
+   * Factor Verification Age
+   * Each item represents the minutes that have passed since the last time a first or second factor were verified.
+   * [fistFactorAge, secondFactorAge]
+   * @experimental This API is experimental and may change at any moment.
+   */
+  __experimental_factorVerificationAge: [number | null, number | null];
   lastActiveToken: TokenResource | null;
   lastActiveOrganizationId: string | null;
   lastActiveAt: Date;

packages/types/src/session.ts

@@ -20,4 +20,5 @@ export type InitialState = Serializable<{
   orgSlug: string | undefined;
   orgPermissions: OrganizationCustomPermissionKey[] | undefined;
   organization: OrganizationResource | undefined;
+  __experimental_factorVerificationAge: [number | null, number | null];
 }>;