chore(backend,react,vue,shared,types): Derive session status from server-side state (#5447)

Author: LauraBeatris

.changeset/twelve-bees-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/vue': patch
+'@clerk/types': patch
+---
+
+Derive session status from server-side state

packages/backend/src/tokens/authObjects.ts

@@ -7,6 +7,7 @@ import type {
   OrganizationCustomRoleKey,
   ServerGetToken,
   ServerGetTokenOptions,
+  SessionStatusClaim,
 } from '@clerk/types';
 
 import type { CreateBackendApiOptions } from '../api';
@@ -29,6 +30,7 @@ export type SignedInAuthObjectOptions = CreateBackendApiOptions & {
 export type SignedInAuthObject = {
   sessionClaims: JwtPayload;
   sessionId: string;
+  sessionStatus: SessionStatusClaim | null;
   actor: ActClaim | undefined;
   userId: string;
   orgId: string | undefined;
@@ -52,6 +54,7 @@ export type SignedInAuthObject = {
 export type SignedOutAuthObject = {
   sessionClaims: null;
   sessionId: null;
+  sessionStatus: null;
   actor: null;
   userId: null;
   orgId: null;
@@ -100,6 +103,7 @@ export function signedInAuthObject(
     org_permissions: orgPermissions,
     sub: userId,
     fva,
+    sts,
   } = sessionClaims;
   const apiClient = createBackendApiClient(authenticateContext);
   const getToken = createGetToken({
@@ -111,10 +115,14 @@ export function signedInAuthObject(
   // fva can be undefined for instances that have not opt-in
   const factorVerificationAge = fva ?? null;
 
+  // sts can be undefined for instances that have not opt-in
+  const sessionStatus = sts ?? null;
+
   return {
     actor,
     sessionClaims,
     sessionId,
+    sessionStatus,
     userId,
     orgId,
     orgRole,
@@ -134,6 +142,7 @@ export function signedOutAuthObject(debugData?: AuthObjectDebugData): SignedOutA
   return {
     sessionClaims: null,
     sessionId: null,
+    sessionStatus: null,
     userId: null,
     actor: null,
     orgId: null,

packages/react/src/contexts/AuthContext.ts

@@ -1,9 +1,15 @@
 import { createContextAndHook } from '@clerk/shared/react';
-import type { ActClaim, OrganizationCustomPermissionKey, OrganizationCustomRoleKey } from '@clerk/types';
+import type {
+  ActClaim,
+  OrganizationCustomPermissionKey,
+  OrganizationCustomRoleKey,
+  SessionStatusClaim,
+} from '@clerk/types';
 
 export type AuthContextValue = {
   userId: string | null | undefined;
   sessionId: string | null | undefined;
+  sessionStatus: SessionStatusClaim | null | undefined;
   actor: ActClaim | null | undefined;
   orgId: string | null | undefined;
   orgRole: OrganizationCustomRoleKey | null | undefined;

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -37,6 +37,7 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
 
   const {
     sessionId,
+    sessionStatus,
     session,
     userId,
     user,
@@ -52,6 +53,7 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
   const authCtx = React.useMemo(() => {
     const value = {
       sessionId,
+      sessionStatus,
       userId,
       actor,
       orgId,
@@ -61,7 +63,7 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
       factorVerificationAge,
     };
     return { value };
-  }, [sessionId, userId, actor, orgId, orgRole, orgSlug, factorVerificationAge]);
+  }, [sessionId, sessionStatus, userId, actor, orgId, orgRole, orgSlug, factorVerificationAge]);
   const sessionCtx = React.useMemo(() => ({ value: session }), [sessionId, session]);
   const userCtx = React.useMemo(() => ({ value: user }), [userId, user]);
   const organizationCtx = React.useMemo(() => {

packages/shared/src/deriveState.ts

@@ -22,6 +22,7 @@ const deriveFromSsrInitialState = (initialState: InitialState) => {
   const userId = initialState.userId;
   const user = initialState.user as UserResource;
   const sessionId = initialState.sessionId;
+  const sessionStatus = initialState.sessionStatus;
   const session = initialState.session as SignedInSessionResource;
   const organization = initialState.organization as OrganizationResource;
   const orgId = initialState.orgId;
@@ -36,6 +37,7 @@ const deriveFromSsrInitialState = (initialState: InitialState) => {
     user,
     sessionId,
     session,
+    sessionStatus,
     organization,
     orgId,
     orgRole,
@@ -51,6 +53,7 @@ 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 sessionStatus = state.session?.status;
   const factorVerificationAge: [number, number] | null = state.session ? state.session.factorVerificationAge : null;
   const actor = session?.actor;
   const organization = state.organization;
@@ -67,6 +70,7 @@ const deriveFromClientSideState = (state: Resources) => {
     user,
     sessionId,
     session,
+    sessionStatus,
     organization,
     orgId,
     orgRole,

packages/types/src/jwtv2.ts

@@ -1,4 +1,5 @@
 import type { OrganizationCustomPermissionKey, OrganizationCustomRoleKey } from './organizationMembership';
+import type { SessionStatus } from './session';
 
 export interface Jwt {
   header: JwtHeader;
@@ -108,6 +109,11 @@ export interface JwtPayload extends CustomJwtSessionClaims {
    */
   fva?: [fistFactorAge: number, secondFactorAge: number];
 
+  /**
+   * Session status
+   */
+  sts?: SessionStatusClaim;
+
   /**
    * Any other JWT Claim Set member.
    */
@@ -122,3 +128,8 @@ export interface ActClaim {
   sub: string;
   [x: string]: unknown;
 }
+
+/**
+ * Session status
+ */
+export type SessionStatusClaim = Extract<SessionStatus, 'active' | 'pending'>;

packages/types/src/ssr.ts

@@ -1,4 +1,4 @@
-import type { ActClaim, JwtPayload } from './jwtv2';
+import type { ActClaim, JwtPayload, SessionStatusClaim } from './jwtv2';
 import type { OrganizationResource } from './organization';
 import type { OrganizationCustomPermissionKey, OrganizationCustomRoleKey } from './organizationMembership';
 import type { SessionResource } from './session';
@@ -11,6 +11,7 @@ export type ServerGetToken = (options?: ServerGetTokenOptions) => Promise<string
 export type InitialState = Serializable<{
   sessionClaims: JwtPayload;
   sessionId: string | undefined;
+  sessionStatus: SessionStatusClaim;
   session: SessionResource | undefined;
   actor: ActClaim | undefined;
   userId: string | undefined;

packages/vue/src/plugin.ts

@@ -68,8 +68,8 @@ export const clerkPlugin: Plugin = {
     const derivedState = computed(() => deriveState(loaded.value, resources.value, initialState));
 
     const authCtx = computed(() => {
-      const { sessionId, userId, orgId, actor, orgRole, orgSlug, orgPermissions } = derivedState.value;
-      return { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions };
+      const { sessionId, userId, orgId, actor, orgRole, orgSlug, orgPermissions, sessionStatus } = derivedState.value;
+      return { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions, sessionStatus };
     });
     const clientCtx = computed(() => resources.value.client);
     const userCtx = computed(() => derivedState.value.user);

packages/vue/src/types.ts

@@ -8,6 +8,7 @@ import type {
   OrganizationCustomPermissionKey,
   OrganizationCustomRoleKey,
   OrganizationResource,
+  SessionStatusClaim,
   SignedInSessionResource,
   UserResource,
   Without,
@@ -20,6 +21,7 @@ export interface VueClerkInjectionKeyType {
     userId: string | null | undefined;
     sessionId: string | null | undefined;
     actor: ActClaim | null | undefined;
+    sessionStatus: SessionStatusClaim | null | undefined;
     orgId: string | null | undefined;
     orgRole: OrganizationCustomRoleKey | null | undefined;
     orgSlug: string | null | undefined;