Forward initial session status to signed out object

Author: LauraBeatris

.changeset/tender-brooms-look.md

@@ -1,8 +1,10 @@
 ---
-'@clerk/nextjs': patch
+'@clerk/nextjs': minor
 ---
 
-Introduce `treatPendingAsSignedOut` to `auth`, `getAuth` and server-side control components
+Introduce `treatPendingAsSignedOut` option to `getAuth` and `auth` from `clerkMiddleware`
+
+By default, `treatPendingAsSignedOut` is set to `true`, which means pending sessions are treated as signed-out. You can set this option to `false` to treat pending sessions as authenticated.
 
 ```ts
 const { userId } = auth({ 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

@@ -27,7 +27,9 @@ export type SignedInState = {
   afterSignInUrl: string;
   afterSignUpUrl: string;
   isSignedIn: true;
-  toAuth: (opts?: PendingSessionOptions) => SignedInAuthObject;
+  toAuth: <T extends PendingSessionOptions | undefined = undefined>(
+    opts?: T,
+  ) => T extends undefined ? SignedInAuthObject : SignedInAuthObject | SignedOutAuthObject;
   headers: Headers;
   token: string;
 };
@@ -102,7 +104,7 @@ export function signedIn(
     // @ts-expect-error Dynamically return `SignedOutAuthObject` based on options
     toAuth: ({ treatPendingAsSignedOut = true } = {}) => {
       if (treatPendingAsSignedOut && authObject.sessionStatus === 'pending') {
-        return signedOutAuthObject();
+        return signedOutAuthObject(undefined, authObject.sessionStatus);
       }
 
       return authObject;

packages/nextjs/src/server/createGetAuth.ts

@@ -53,7 +53,7 @@ export const createAsyncGetAuth = ({
 /**
  * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
  * that required dynamic imports (using `require` would not work).
- * It powers the synchronous top-level api `getAuh()`.
+ * It powers the synchronous top-level api `getAuth()`.
  */
 export const createSyncGetAuth = ({
   debugLoggerName,

packages/nextjs/src/server/data/getAuthDataFromRequest.ts

@@ -59,7 +59,7 @@ export function getAuthDataFromRequest(
   }
 
   if (treatPendingAsSignedOut && authObject.sessionStatus === 'pending') {
-    authObject = signedOutAuthObject(options);
+    authObject = signedOutAuthObject(options, authObject.sessionStatus);
   }
 
   return authObject;