chore(shared,vue,nextjs,astro,clerk-react): Update useAuth to handle pending session as signed-out

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',

.changeset/common-teams-do.md

@@ -0,0 +1,5 @@
+---
+'@clerk/astro': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `clerk({ treatPendingAsSignedOut: false })`

.changeset/early-boats-help.md

@@ -0,0 +1,5 @@
+---
+'@clerk/vue': minor
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `app.use(clerkPlugin, { treatPendingAsSignedOut: false })`

.changeset/modern-paws-mate.md

@@ -0,0 +1,7 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+---
+
+Update `useAuth` to handle pending sessions as signed-out by default, with opt-out via `useAuth({ treatPendingAsSignedOut: false })` or `<ClerkProvider treatPendingAsSignedOut={false} />`

packages/astro/src/env.d.ts

@@ -18,6 +18,7 @@ interface InternalEnv {
  readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
  readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+ readonly PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT?: string;
 }
 
 interface ImportMeta {

packages/astro/src/integration/create-integration.ts

@@ -19,7 +19,15 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
  return (params?: Params): AstroIntegration => {
- const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
+ const {
+ proxyUrl,
+ isSatellite,
+ domain,
+ signInUrl,
+ signUpUrl,
+ enableEnvSchema = true,
+ treatPendingAsSignedOut,
+ } = params || {};
 
  // These are not provided when the "bundled" integration is used
  const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -57,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
  /**
  * Convert the integration params to environment variable in order for it to be readable from the server
  */
+ ...buildEnvVarFromOption(treatPendingAsSignedOut, 'PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT'),
  ...buildEnvVarFromOption(signInUrl, 'PUBLIC_CLERK_SIGN_IN_URL'),
  ...buildEnvVarFromOption(signUpUrl, 'PUBLIC_CLERK_SIGN_UP_URL'),
  ...buildEnvVarFromOption(isSatellite, 'PUBLIC_CLERK_IS_SATELLITE'),

packages/astro/src/react/hooks.ts

@@ -1,22 +1,20 @@
+import { resolveAuthState } from '@clerk/shared/authorization';
 import type {
- ActClaim,
  CheckAuthorizationWithCustomPermissions,
  Clerk,
  GetToken,
-OrganizationCustomRoleKey,
+PendingSessionOptions,
  SignOut,
+ UseAuthReturn,
 } from '@clerk/types';
 import type { Store, StoreValue } from 'nanostores';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { $authStore } from '../stores/external';
+import { $authStore, $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
 
-type CheckAuthorizationSignedOut = undefined;
-type CheckAuthorizationWithoutOrgOrUser = (params?: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => false;
-
 /**
  * @internal
  */
@@ -54,61 +52,7 @@ const createSignOut = () => {
  };
 };
 
-type UseAuthReturn =
- | {
- isLoaded: false;
- isSignedIn: undefined;
- userId: undefined;
- sessionId: undefined;
- actor: undefined;
- orgId: undefined;
- orgRole: undefined;
- orgSlug: undefined;
- has: CheckAuthorizationSignedOut;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: false;
- userId: null;
- sessionId: null;
- actor: null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: null;
- orgRole: null;
- orgSlug: null;
- has: CheckAuthorizationWithoutOrgOrUser;
- signOut: SignOut;
- getToken: GetToken;
- }
- | {
- isLoaded: true;
- isSignedIn: true;
- userId: string;
- sessionId: string;
- actor: ActClaim | null;
- orgId: string;
- orgRole: OrganizationCustomRoleKey;
- orgSlug: string | null;
- has: CheckAuthorizationWithCustomPermissions;
- signOut: SignOut;
- getToken: GetToken;
- };
-
-type UseAuth = () => UseAuthReturn;
+type UseAuth = (options?: PendingSessionOptions) => UseAuthReturn;
 
 /**
  * Returns the current auth state, the user and session ids and the `getToken`
@@ -138,12 +82,15 @@ type UseAuth = () => UseAuthReturn;
  * return <div>...</div>
  * }
  */
-export const useAuth: UseAuth = () => {
- const { sessionId, userId, actor, orgId, orgRole, orgSlug, orgPermissions } = useStore($authStore);
+export const useAuth: UseAuth = ({ treatPendingAsSignedOut } = {}) => {
+ const authContext = useStore($authStore);
+ const clerkContext = useStore($clerkStore);
 
  const getToken: GetToken = useCallback(createGetToken(), []);
  const signOut: SignOut = useCallback(createSignOut(), []);
 
+ const { userId, orgId, orgRole, orgPermissions } = authContext;
+
  const has = useCallback(
  (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
  if (!params?.permission && !params?.role) {
@@ -169,71 +116,27 @@ export const useAuth: UseAuth = () => {
  [orgId, orgRole, userId, orgPermissions],
  );
 
- if (sessionId === undefined && userId === undefined) {
- return {
- isLoaded: false,
- isSignedIn: undefined,
- sessionId,
- userId,
- actor: undefined,
- orgId: undefined,
- orgRole: undefined,
- orgSlug: undefined,
- has: undefined,
- signOut,
+ const payload = resolveAuthState({
+ authObject: {
+ ...authContext,
  getToken,
- };
- }
-
- if (sessionId === null && userId === null) {
- return {
- isLoaded: true,
- isSignedIn: false,
- sessionId,
- userId,
- actor: null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
  signOut,
- getToken,
- };
- }
-
- if (!!sessionId && !!userId && !!orgId && !!orgRole) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId,
- orgRole,
- orgSlug: orgSlug || null,
  has,
- signOut,
- getToken,
- };
- }
+ },
+ options: {
+ treatPendingAsSignedOut:
+ // Fallback from option provided via SSR / CSR contexts
+ treatPendingAsSignedOut ??
+ clerkContext?.__internal_getOption?.('treatPendingAsSignedOut') ??
+ import.meta.env.PUBLIC_CLERK_TREAT_PENDING_AS_SIGNED_OUT,
+ },
+ });
 
- if (!!sessionId && !!userId && !orgId) {
- return {
- isLoaded: true,
- isSignedIn: true,
- sessionId,
- userId,
- actor: actor || null,
- orgId: null,
- orgRole: null,
- orgSlug: null,
- has: () => false,
- signOut,
- getToken,
- };
+ if (!payload) {
+ throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
  }
 
-throw new Error('Invalid state. Feel free to submit a bug or reach out to support');
+return payload;
 };
 
 /**

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -54,7 +54,7 @@ export function PromisifiedAuthProvider({
  * }
  * ```
  */
-export function usePromisifiedAuth() {
+export function usePromisifiedAuth(options: Parameters<typeof useAuth>[0] = {}) {
  const isPagesRouter = useRouter();
  const valueFromContext = React.useContext(PromisifiedAuthContext);
 
@@ -64,16 +64,15 @@ export function usePromisifiedAuth() {
  }
 
  // At this point we should have a usable auth object
-
  if (typeof window === 'undefined') {
  // Pages router should always use useAuth as it is able to grab initial auth state from context during SSR.
  if (isPagesRouter) {
- return useAuth();
+ return useAuth(options);
  }
 
  // We don't need to deal with Clerk being loaded here
- return useDerivedAuth(resolvedData);
+ return useDerivedAuth({ ...resolvedData, ...options });
  } else {
- return useAuth(resolvedData);
+ return useAuth({ ...resolvedData, ...options });
  }
 }

packages/react/src/hooks/__tests__/useAuth.test.tsx

@@ -101,6 +101,94 @@ describe('useDerivedAuth', () => {
  expect(current.has?.({ permission: 'test' })).toBe(false);
  });
 
+ it('returns signed out state when session has pending status by default', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: true` option, returns signed out state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: true }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(false);
+ expect(current.sessionId).toBeNull();
+ expect(current.userId).toBeNull();
+ expect(current.actor).toBeNull();
+ expect(current.orgId).toBeNull();
+ expect(current.orgRole).toBeNull();
+ expect(current.orgSlug).toBeNull();
+ expect(current.has).toBeInstanceOf(Function);
+ expect(current.has?.({ permission: 'test' })).toBe(false);
+ });
+
+ it('with `treatPendingAsSignedOut: false` option, returns signed in state when session has pending status', () => {
+ const authObject = {
+ sessionId: 'session123',
+ sessionStatus: 'pending',
+ userId: 'user123',
+ actor: 'actor123',
+ orgId: 'org123',
+ orgRole: 'admin',
+ orgSlug: 'my-org',
+ signOut: vi.fn(),
+ getToken: vi.fn(),
+ };
+
+ const {
+ result: { current },
+ } = renderHook(() => useDerivedAuth(authObject, { treatPendingAsSignedOut: false }));
+
+ expect(current.isLoaded).toBe(true);
+ expect(current.isSignedIn).toBe(true);
+ expect(current.sessionId).toBe('session123');
+ expect(current.userId).toBe('user123');
+ expect(current.actor).toBe('actor123');
+ expect(current.orgId).toBe('org123');
+ expect(current.orgRole).toBe('admin');
+ expect(current.orgSlug).toBe('my-org');
+ expect(typeof current.has).toBe('function');
+ expect(current.signOut).toBe(authObject.signOut);
+ expect(current.getToken).toBe(authObject.getToken);
+ });
+
  it('returns signed in with org context when sessionId, userId, orgId, and orgRole are present', () => {
  const authObject = {
  sessionId: 'session123',