chore(backend,nextjs): Introduce treatPendingAsSignedOut option to server-side utilities and control components

.changeset/tender-brooms-look.md

@@ -0,0 +1,21 @@
+---
+'@clerk/nextjs': minor
+---
+
+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 })
+```
+
+```ts
+const { userId } = getAuth(req, { treatPendingAsSignedOut: false })
+```
+
+```tsx
+<SignedIn treatPendingAsSignedOut={false}>
+  User has a session that is either pending (requires tasks resolution) or active
+</SignedIn>
+```

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/nextjs/src/app-router/server/auth.ts

@@ -1,5 +1,6 @@
 import type { AuthObject } from '@clerk/backend';
 import { constants, createClerkRequest, createRedirect, type RedirectFun } from '@clerk/backend/internal';
+import type { PendingSessionOptions } from '@clerk/types';
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
@@ -38,7 +39,7 @@ type Auth = AuthObject & {
 };
 
 export interface AuthFn {
-  (): Promise<Auth>;
+  (options?: PendingSessionOptions): Promise<Auth>;
 
   /**
    * `auth` includes a single property, the `protect()` method, which you can use in two ways:
@@ -68,7 +69,7 @@ export interface AuthFn {
  * - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions.
  * - Requires [`clerkMiddleware()`](https://clerk.com/docs/references/nextjs/clerk-middleware) to be configured.
  */
-export const auth: AuthFn = async () => {
+export const auth: AuthFn = async ({ treatPendingAsSignedOut } = {}) => {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   require('server-only');
 
@@ -89,7 +90,7 @@ export const auth: AuthFn = async () => {
   const authObject = await createAsyncGetAuth({
     debugLoggerName: 'auth()',
     noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
-  })(request);
+  })(request, { treatPendingAsSignedOut });
 
   const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');
 

packages/nextjs/src/app-router/server/controlComponents.tsx

@@ -1,17 +1,22 @@
 import type { ProtectProps } from '@clerk/clerk-react';
+import type { PendingSessionOptions } from '@clerk/types';
 import React from 'react';
 
 import { auth } from './auth';
 
-export async function SignedIn(props: React.PropsWithChildren): Promise<React.JSX.Element | null> {
+export async function SignedIn(
+  props: React.PropsWithChildren<PendingSessionOptions>,
+): Promise<React.JSX.Element | null> {
   const { children } = props;
-  const { userId } = await auth();
+  const { userId } = await auth({ treatPendingAsSignedOut: props.treatPendingAsSignedOut });
   return userId ? <>{children}</> : null;
 }
 
-export async function SignedOut(props: React.PropsWithChildren): Promise<React.JSX.Element | null> {
+export async function SignedOut(
+  props: React.PropsWithChildren<PendingSessionOptions>,
+): Promise<React.JSX.Element | null> {
   const { children } = props;
-  const { userId } = await auth();
+  const { userId } = await auth({ treatPendingAsSignedOut: props.treatPendingAsSignedOut });
   return userId ? null : <>{children}</>;
 }
 
@@ -29,7 +34,7 @@ export async function SignedOut(props: React.PropsWithChildren): Promise<React.J
  */
 export async function Protect(props: ProtectProps): Promise<React.JSX.Element | null> {
   const { children, fallback, ...restAuthorizedParams } = props;
-  const { has, userId } = await auth();
+  const { has, userId } = await auth({ treatPendingAsSignedOut: props.treatPendingAsSignedOut });
 
   /**
    * Fallback to UI provided by user or `null` if authorization checks failed

packages/nextjs/src/server/clerkMiddleware.ts

@@ -2,6 +2,7 @@ import type { AuthObject, ClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, ClerkRequest, RedirectFun, RequestState } from '@clerk/backend/internal';
 import { AuthStatus, constants, createClerkRequest, createRedirect } from '@clerk/backend/internal';
 import { parsePublishableKey } from '@clerk/shared/keys';
+import type { PendingSessionOptions } from '@clerk/types';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -41,7 +42,7 @@ export type ClerkMiddlewareAuthObject = AuthObject & {
 };
 
 export interface ClerkMiddlewareAuth {
-  (): Promise<ClerkMiddlewareAuthObject>;
+  (opts?: PendingSessionOptions): Promise<ClerkMiddlewareAuthObject>;
 
   protect: AuthProtect;
 }
@@ -182,11 +183,14 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
       const redirectToSignUp = createMiddlewareRedirectToSignUp(clerkRequest);
       const protect = await createMiddlewareProtect(clerkRequest, authObject, redirectToSignIn);
 
-      const authObjWithMethods: ClerkMiddlewareAuthObject = Object.assign(authObject, {
-        redirectToSignIn,
-        redirectToSignUp,
-      });
-      const authHandler = () => Promise.resolve(authObjWithMethods);
+      const authHandler = (opts?: PendingSessionOptions) => {
+        const authObjWithMethods: ClerkMiddlewareAuthObject = Object.assign(requestState.toAuth(opts), {
+          redirectToSignIn,
+          redirectToSignUp,
+        });
+
+        return Promise.resolve(authObjWithMethods);
+      };
       authHandler.protect = protect;
 
       let handlerResult: Response = NextResponse.next();

packages/nextjs/src/server/createGetAuth.ts

@@ -1,6 +1,7 @@
 import type { AuthObject } from '@clerk/backend';
 import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
+import type { PendingSessionOptions } from '@clerk/types';
 
 import { withLogger } from '../utils/debugLogger';
 import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
@@ -22,7 +23,7 @@ export const createAsyncGetAuth = ({
   noAuthStatusMessage: string;
 }) =>
   withLogger(debugLoggerName, logger => {
-    return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+    return async (req: RequestLike, opts?: { secretKey?: string } & PendingSessionOptions): Promise<AuthObject> => {
       if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
         logger.enable();
       }
@@ -52,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,
@@ -62,7 +63,7 @@ export const createSyncGetAuth = ({
   noAuthStatusMessage: string;
 }) =>
   withLogger(debugLoggerName, logger => {
-    return (req: RequestLike, opts?: { secretKey?: string }): AuthObject => {
+    return (req: RequestLike, opts?: { secretKey?: string } & PendingSessionOptions): AuthObject => {
       if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
         logger.enable();
       }

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

@@ -1,6 +1,7 @@
 import type { AuthObject } from '@clerk/backend';
 import { AuthStatus, constants, signedInAuthObject, signedOutAuthObject } from '@clerk/backend/internal';
 import { decodeJwt } from '@clerk/backend/jwt';
+import type { PendingSessionOptions } from '@clerk/types';
 
 import type { LoggerNoCommit } from '../../utils/debugLogger';
 import { API_URL, API_VERSION, PUBLISHABLE_KEY, SECRET_KEY } from '../constants';
@@ -14,7 +15,10 @@ import { assertTokenSignature, decryptClerkRequestData } from '../utils';
  */
 export function getAuthDataFromRequest(
   req: RequestLike,
-  opts: { secretKey?: string; logger?: LoggerNoCommit } = {},
+  {
+    treatPendingAsSignedOut = true,
+    ...opts
+  }: { secretKey?: string; logger?: LoggerNoCommit } & PendingSessionOptions = {},
 ): AuthObject {
   const authStatus = getAuthKeyFromRequest(req, 'AuthStatus');
   const authToken = getAuthKeyFromRequest(req, 'AuthToken');
@@ -35,6 +39,7 @@ export function getAuthDataFromRequest(
     authStatus,
     authMessage,
     authReason,
+    treatPendingAsSignedOut,
   };
 
   opts.logger?.debug('auth options', options);
@@ -53,5 +58,9 @@ export function getAuthDataFromRequest(
     authObject = signedInAuthObject(options, jwt.raw.text, jwt.payload);
   }
 
+  if (treatPendingAsSignedOut && authObject.sessionStatus === 'pending') {
+    authObject = signedOutAuthObject(options, authObject.sessionStatus);
+  }
+
   return authObject;
 }