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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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

.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
+```

packages/backend/src/tokens/authObjects.ts

@@ -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/clerk-js/src/core/resources/Session.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/utils/memoizeStateListenerCallback.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/react/src/contexts/AuthContext.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/ClerkContextProvider.tsx

@@ -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/utils/deriveState.ts

@@ -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/types/src/json.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/jwtv2.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/session.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/ssr.ts

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