chore(backend,express): Introduce treatPendingAsSignedOut option to getAuth

.changeset/flat-papers-begin.md

@@ -0,0 +1,16 @@
+---
+'@clerk/backend': minor
+'@clerk/express': minor
+---
+
+Introduce `treatPendingAsSignedOut` option to `getAuth`
+
+```ts
+// `pending` sessions will be treated as signed-out by default
+const { userId } = getAuth(req)
+```
+
+```ts
+// Both `active` and `pending` sessions will be treated as authenticated when `treatPendingAsSignedOut` is false
+const { userId } = getAuth(req, { treatPendingAsSignedOut: false })
+```

packages/backend/src/tokens/authObjects.ts

@@ -5,6 +5,7 @@ import type {
   JwtPayload,
   ServerGetToken,
   ServerGetTokenOptions,
+  SessionStatusClaim,
   SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
@@ -37,7 +38,7 @@ export type SignedInAuthObject = SharedSignedInAuthObjectProperties & {
 export type SignedOutAuthObject = {
   sessionClaims: null;
   sessionId: null;
-  sessionStatus: null;
+  sessionStatus: SessionStatusClaim | null;
   actor: null;
   userId: null;
   orgId: null;
@@ -113,11 +114,14 @@ export function signedInAuthObject(
 /**
  * @internal
  */
-export function signedOutAuthObject(debugData?: AuthObjectDebugData): SignedOutAuthObject {
+export function signedOutAuthObject(
+  debugData?: AuthObjectDebugData,
+  initialSessionStatus?: SessionStatusClaim,
+): SignedOutAuthObject {
   return {
     sessionClaims: null,
     sessionId: null,
-    sessionStatus: null,
+    sessionStatus: initialSessionStatus ?? null,
     userId: null,
     actor: null,
     orgId: null,

packages/backend/src/tokens/authStatus.ts

@@ -1,4 +1,4 @@
-import type { JwtPayload } from '@clerk/types';
+import type { JwtPayload, PendingSessionOptions } from '@clerk/types';
 
 import { constants } from '../constants';
 import type { TokenVerificationErrorReason } from '../errors';
@@ -27,7 +27,7 @@ export type SignedInState = {
   afterSignInUrl: string;
   afterSignUpUrl: string;
   isSignedIn: true;
-  toAuth: () => SignedInAuthObject;
+  toAuth: (opts?: PendingSessionOptions) => SignedInAuthObject;
   headers: Headers;
   token: string;
 };
@@ -99,7 +99,14 @@ export function signedIn(
     afterSignInUrl: authenticateContext.afterSignInUrl || '',
     afterSignUpUrl: authenticateContext.afterSignUpUrl || '',
     isSignedIn: true,
-    toAuth: () => authObject,
+    // @ts-expect-error The return type is intentionally overridden here to support consumer-facing logic that treats pending sessions as signed out. This override does not affect internal session management like handshake flows.
+    toAuth: ({ treatPendingAsSignedOut = true } = {}) => {
+      if (treatPendingAsSignedOut && authObject.sessionStatus === 'pending') {
+        return signedOutAuthObject(undefined, authObject.sessionStatus);
+      }
+
+      return authObject;
+    },
     headers,
     token,
   };

packages/express/src/__tests__/helpers.ts

@@ -28,7 +28,7 @@ export function mockRequest(): ExpressRequest {
 
 export function mockRequestWithAuth(auth: Partial<AuthObject> = {}): ExpressRequestWithAuth {
   return {
-    auth: {
+    auth: () => ({
       sessionClaims: null,
       sessionId: null,
       actor: null,
@@ -41,7 +41,7 @@ export function mockRequestWithAuth(auth: Partial<AuthObject> = {}): ExpressRequ
       has: () => false,
       debug: () => ({}),
       ...auth,
-    },
+    }),
   } as unknown as ExpressRequestWithAuth;
 }
 

packages/express/src/__tests__/requireAuth.test.ts

@@ -81,7 +81,7 @@ describe('requireAuth', () => {
           return next();
         }
         const requestState = mockAuthenticateRequest({ request: req });
-        Object.assign(req, { auth: requestState.toAuth() });
+        Object.assign(req, { auth: () => requestState.toAuth() });
         next();
       };
     });

packages/express/src/authenticateRequest.ts

@@ -110,7 +110,7 @@ export const authenticateAndDecorateRequest = (options: ClerkMiddlewareOptions =
         }
       }
 
-      const auth = requestState.toAuth();
+      const auth = (opts: Parameters<typeof requestState.toAuth>[0]) => requestState.toAuth(opts);
       Object.assign(request, { auth });
 
       next();

packages/express/src/getAuth.ts

@@ -1,20 +1,24 @@
 import type { AuthObject } from '@clerk/backend';
+import type { PendingSessionOptions } from '@clerk/types';
 import type { Request as ExpressRequest } from 'express';
 
 import { middlewareRequired } from './errors';
 import { requestHasAuthObject } from './utils';
 
+type GetAuthOptions = PendingSessionOptions;
+
 /**
  * Retrieves the Clerk AuthObject using the current request object.
  *
  * @param {ExpressRequest} req - The current request object.
+ * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
  * @returns {AuthObject} Object with information about the request state and claims.
  * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
  */
-export const getAuth = (req: ExpressRequest): AuthObject => {
+export const getAuth = (req: ExpressRequest, options?: GetAuthOptions): AuthObject => {
   if (!requestHasAuthObject(req)) {
     throw new Error(middlewareRequired('getAuth'));
   }
 
-  return req.auth;
+  return req.auth(options);
 };

packages/express/src/requireAuth.ts

@@ -43,7 +43,7 @@ export const requireAuth = (options: ClerkMiddlewareOptions = {}): RequestHandle
 
       const signInUrl = options.signInUrl || process.env.CLERK_SIGN_IN_URL || '/';
 
-      if (!(request as ExpressRequestWithAuth).auth?.userId) {
+      if (!(request as ExpressRequestWithAuth).auth()?.userId) {
         return response.redirect(signInUrl);
       }
 

packages/express/src/types.ts

@@ -1,8 +1,9 @@
 import type { AuthObject, createClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
+import type { PendingSessionOptions } from '@clerk/types';
 import type { Request as ExpressRequest } from 'express';
 
-export type ExpressRequestWithAuth = ExpressRequest & { auth: AuthObject };
+export type ExpressRequestWithAuth = ExpressRequest & { auth: (options?: PendingSessionOptions) => AuthObject };
 
 export type ClerkMiddlewareOptions = AuthenticateRequestOptions & {
   debug?: boolean;