feat(nextjs,clerk-react,types,clerk-js): Add experimental support for <Gate/>

.changeset/orange-pumpkins-poke.md

@@ -0,0 +1,10 @@
+---
+'@clerk/chrome-extension': minor
+'@clerk/clerk-js': minor
+'@clerk/backend': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+'@clerk/types': minor
+---
+
+Experimental support for `<Gate/>` with role checks.

packages/backend/src/tokens/authObjects.ts

@@ -1,5 +1,11 @@
 import { deprecated } from '@clerk/shared/deprecated';
-import type { ActClaim, JwtPayload, ServerGetToken, ServerGetTokenOptions } from '@clerk/types';
+import type {
+  ActClaim,
+  experimental__CheckAuthorizationWithoutPermission,
+  JwtPayload,
+  ServerGetToken,
+  ServerGetTokenOptions,
+} from '@clerk/types';
 
 import type { Organization, Session, User } from '../api';
 import { createBackendApiClient } from '../api';
@@ -36,6 +42,10 @@ export type SignedInAuthObject = {
   orgSlug: string | undefined;
   organization: Organization | undefined;
   getToken: ServerGetToken;
+  /**
+   * @experimental The method is experimental and subject to change in future releases.
+   */
+  experimental__has: experimental__CheckAuthorizationWithoutPermission;
   debug: AuthObjectDebug;
 };
 
@@ -51,6 +61,10 @@ export type SignedOutAuthObject = {
   orgSlug: null;
   organization: null;
   getToken: ServerGetToken;
+  /**
+   * @experimental The method is experimental and subject to change in future releases.
+   */
+  experimental__has: experimental__CheckAuthorizationWithoutPermission;
   debug: AuthObjectDebug;
 };
 
@@ -110,6 +124,7 @@ export function signedInAuthObject(
     orgSlug,
     organization,
     getToken,
+    experimental__has: createHasAuthorization({ orgId, orgRole, userId }),
     debug: createDebug({ ...options, ...debugData }),
   };
 }
@@ -131,11 +146,21 @@ export function signedOutAuthObject(debugData?: AuthObjectDebugData): SignedOutA
     orgSlug: null,
     organization: null,
     getToken: () => Promise.resolve(null),
+    experimental__has: () => false,
     debug: createDebug(debugData),
   };
 }
 
-export function prunePrivateMetadata(resource?: { private_metadata: any } | { privateMetadata: any } | null) {
+export function prunePrivateMetadata(
+  resource?:
+    | {
+        private_metadata: any;
+      }
+    | {
+        privateMetadata: any;
+      }
+    | null,
+) {
   // Delete sensitive private metadata from resource before rendering in SSR
   if (resource) {
     // @ts-ignore
@@ -166,7 +191,7 @@ export function sanitizeAuthObject<T extends Record<any, any>>(authObject: T): T
  */
 export const makeAuthObjectSerializable = <T extends Record<string, unknown>>(obj: T): T => {
   // remove any non-serializable props from the returned object
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+
   const { debug, getToken, ...rest } = obj as unknown as AuthObject;
   return rest as unknown as T;
 };
@@ -190,3 +215,34 @@ const createGetToken: CreateGetToken = params => {
     return sessionToken;
   };
 };
+
+const createHasAuthorization =
+  ({
+    orgId,
+    orgRole,
+    userId,
+  }: {
+    userId: string;
+    orgId: string | undefined;
+    orgRole: string | undefined;
+  }): experimental__CheckAuthorizationWithoutPermission =>
+  params => {
+    if (!orgId || !userId) {
+      return false;
+    }
+
+    if (params.role) {
+      return orgRole === params.role;
+    }
+
+    if (params.some) {
+      return !!params.some.find(permObj => {
+        if (permObj.role) {
+          return orgRole === permObj.role;
+        }
+        return false;
+      });
+    }
+
+    return false;
+  };

packages/chrome-extension/src/__snapshots__/exports.test.ts.snap

@@ -8,6 +8,7 @@ exports[`public exports should not include a breaking change 1`] = `
   "ClerkProvider",
   "CreateOrganization",
   "EmailLinkErrorCode",
+  "Experimental__Gate",
   "MagicLinkErrorCode",
   "MultisessionAppSupport",
   "OrganizationList",

packages/clerk-js/src/core/resources/Session.test.ts

@@ -73,7 +73,7 @@ describe('Session', () => {
         updated_at: new Date().getTime(),
       } as SessionJSON);
 
-      const isAuthorized = await session.isAuthorized({ permission: 'org:sys_profile:delete' });
+      const isAuthorized = await session.experimental__checkAuthorization({ permission: 'org:sys_profile:delete' });
 
       expect(isAuthorized).toBe(true);
     });
@@ -93,7 +93,7 @@ describe('Session', () => {
         updated_at: new Date().getTime(),
       } as SessionJSON);
 
-      const isAuthorized = await session.isAuthorized({ permission: 'org:sys_profile:delete' });
+      const isAuthorized = await session.experimental__checkAuthorization({ permission: 'org:sys_profile:delete' });
 
       expect(isAuthorized).toBe(false);
     });

packages/clerk-js/src/core/resources/Session.ts

@@ -2,9 +2,9 @@ import { runWithExponentialBackOff } from '@clerk/shared';
 import { is4xxError } from '@clerk/shared/error';
 import type {
   ActJWTClaim,
+  CheckAuthorization,
   GetToken,
   GetTokenOptions,
-  IsAuthorized,
   SessionJSON,
   SessionResource,
   SessionStatus,
@@ -69,8 +69,6 @@ export class Session extends BaseResource implements SessionResource {
     return SessionTokenCache.clear();
   };
 
-  // TODO: Fix this eslint error
-
   getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
     return runWithExponentialBackOff(() => this._getToken(options), {
       shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
@@ -80,48 +78,44 @@ export class Session extends BaseResource implements SessionResource {
   /**
    * @experimental The method is experimental and subject to change in future releases.
    */
-  isAuthorized: IsAuthorized = async params => {
-    return new Promise((resolve, reject) => {
-      // if there is no active organization user can not be authorized
-      if (!this.lastActiveOrganizationId || !this.user) {
-        return resolve(false);
-      }
+  experimental__checkAuthorization: CheckAuthorization = params => {
+    // if there is no active organization user can not be authorized
+    if (!this.lastActiveOrganizationId || !this.user) {
+      return false;
+    }
 
-      // loop through organizationMemberships from client piggybacking
-      const orgMemberships = this.user.organizationMemberships || [];
-      const activeMembership = orgMemberships.find(mem => mem.organization.id === this.lastActiveOrganizationId);
+    // loop through organizationMemberships from client piggybacking
+    const orgMemberships = this.user.organizationMemberships || [];
+    const activeMembership = orgMemberships.find(mem => mem.organization.id === this.lastActiveOrganizationId);
 
-      // Based on FAPI this should never happen, but we handle it anyway
-      if (!activeMembership) {
-        return resolve(false);
-      }
+    // Based on FAPI this should never happen, but we handle it anyway
+    if (!activeMembership) {
+      return false;
+    }
 
-      const activeOrganizationPermissions = activeMembership.permissions;
-      const activeOrganizationRole = activeMembership.role;
+    const activeOrganizationPermissions = activeMembership.permissions;
+    const activeOrganizationRole = activeMembership.role;
 
-      if (params.permission) {
-        return resolve(activeOrganizationPermissions.includes(params.permission));
-      }
-      if (params.role) {
-        return resolve(activeOrganizationRole === params.role);
-      }
+    if (params.permission) {
+      return activeOrganizationPermissions.includes(params.permission);
+    }
+    if (params.role) {
+      return activeOrganizationRole === params.role;
+    }
 
-      if (params.any) {
-        return resolve(
-          !!params.any.find(permObj => {
-            if (permObj.permission) {
-              return activeOrganizationPermissions.includes(permObj.permission);
-            }
-            if (permObj.role) {
-              return activeOrganizationRole === permObj.role;
-            }
-            return false;
-          }),
-        );
-      }
+    if (params.some) {
+      return !!params.some.find(permObj => {
+        if (permObj.permission) {
+          return activeOrganizationPermissions.includes(permObj.permission);
+        }
+        if (permObj.role) {
+          return activeOrganizationRole === permObj.role;
+        }
+        return false;
+      });
+    }
 
-      return reject();
-    });
+    return false;
   };
 
   #hydrateCache = (token: TokenResource | null) => {

packages/clerk-js/src/ui/common/Gate.tsx

@@ -1,12 +1,11 @@
-import type { IsAuthorized } from '@clerk/types';
+import type { CheckAuthorization } from '@clerk/types';
 import type { ComponentType, PropsWithChildren, ReactNode } from 'react';
 import React, { useEffect } from 'react';
 
 import { useCoreSession } from '../contexts';
-import { useFetch } from '../hooks';
 import { useRouter } from '../router';
 
-type GateParams = Parameters<IsAuthorized>[0];
+type GateParams = Parameters<CheckAuthorization>[0];
 type GateProps = PropsWithChildren<
   GateParams & {
     fallback?: ReactNode;
@@ -15,11 +14,10 @@ type GateProps = PropsWithChildren<
 >;
 
 export const useGate = (params: GateParams) => {
-  const { isAuthorized } = useCoreSession();
-  const { data: isAuthorizedUser } = useFetch(isAuthorized, params);
+  const { experimental__checkAuthorization } = useCoreSession();
 
   return {
-    isAuthorizedUser,
+    isAuthorizedUser: experimental__checkAuthorization(params),
   };
 };
 

packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationProfileRoutes.tsx

@@ -77,7 +77,7 @@ export const OrganizationProfileRoutes = (props: PropsOfComponent<typeof Profile
                   </Route>
                   <Route path=':id'>
                     <Gate
-                      any={[{ permission: 'org:sys_domains:manage' }, { permission: 'org:sys_domains:delete' }]}
+                      some={[{ permission: 'org:sys_domains:manage' }, { permission: 'org:sys_domains:delete' }]}
                       redirectTo='../../'
                     >
                       <VerifiedDomainPage />

packages/clerk-js/src/ui/utils/test/mockHelpers.ts

@@ -35,7 +35,7 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepJestMocked<LoadedClerk
   mockMethodsOf(clerk.client.signUp);
   clerk.client.sessions.forEach(session => {
     mockMethodsOf(session, {
-      exclude: ['isAuthorized'],
+      exclude: ['experimental__checkAuthorization'],
     });
     mockMethodsOf(session.user);
     session.user?.emailAddresses.forEach(m => mockMethodsOf(m));

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

@@ -1,3 +1,5 @@
+import type { experimental__CheckAuthorizationWithoutPermission } from '@clerk/types';
+import { redirect } from 'next/navigation';
 import React from 'react';
 
 import { auth } from './auth';
@@ -13,3 +15,38 @@ export function SignedOut(props: React.PropsWithChildren) {
   const { userId } = auth();
   return userId ? null : <>{children}</>;
 }
+
+type GateServerComponentProps = React.PropsWithChildren<
+  Parameters<experimental__CheckAuthorizationWithoutPermission>[0] & {
+    fallback?: React.ReactNode;
+    redirectTo?: string;
+  }
+>;
+
+/**
+ * @experimental The component is experimental and subject to change in future releases.
+ */
+export function experimental__Gate(gateProps: GateServerComponentProps) {
+  const { children, fallback, redirectTo, ...restAuthorizedParams } = gateProps;
+  const { experimental__has } = auth();
+
+  const isAuthorizedUser = experimental__has(restAuthorizedParams);
+
+  const handleFallback = () => {
+    if (!redirectTo && !fallback) {
+      throw new Error('Provide `<Gate />` with a `fallback` or `redirectTo`');
+    }
+
+    if (redirectTo) {
+      return redirect(redirectTo);
+    }
+
+    return <>{fallback}</>;
+  };
+
+  if (!isAuthorizedUser) {
+    return handleFallback();
+  }
+
+  return <>{children}</>;
+}

packages/nextjs/src/client-boundary/controlComponents.ts

@@ -5,6 +5,7 @@ export {
   ClerkLoading,
   SignedOut,
   SignedIn,
+  Experimental__Gate,
   RedirectToSignIn,
   RedirectToSignUp,
   RedirectToUserProfile,

packages/nextjs/src/components.client.ts

@@ -1,2 +1,2 @@
 export { ClerkProvider } from './client-boundary/ClerkProvider';
-export { SignedIn, SignedOut } from './client-boundary/controlComponents';
+export { SignedIn, SignedOut, Experimental__Gate } from './client-boundary/controlComponents';

packages/nextjs/src/components.server.ts

@@ -1,10 +1,11 @@
 import { ClerkProvider } from './app-router/server/ClerkProvider';
-import { SignedIn, SignedOut } from './app-router/server/controlComponents';
+import { experimental__Gate, SignedIn, SignedOut } from './app-router/server/controlComponents';
 
-export { ClerkProvider, SignedOut, SignedIn };
+export { ClerkProvider, SignedOut, SignedIn, experimental__Gate as Experimental__Gate };
 
 export type ServerComponentsServerModuleTypes = {
   ClerkProvider: typeof ClerkProvider;
   SignedIn: typeof SignedIn;
   SignedOut: typeof SignedOut;
+  Experimental__Gate: typeof experimental__Gate;
 };

packages/nextjs/src/index.ts

@@ -93,6 +93,12 @@ export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsS
 export const SignedIn = ComponentsModule.SignedIn as ServerComponentsServerModuleTypes['SignedIn'];
 export const SignedOut = ComponentsModule.SignedOut as ServerComponentsServerModuleTypes['SignedOut'];
 
+/**
+ * @experimental
+ */
+export const Experimental__Gate =
+  ComponentsModule.Experimental__Gate as ServerComponentsServerModuleTypes['Experimental__Gate'];
+
 export const auth = ServerHelperModule.auth as ServerHelpersServerModuleTypes['auth'];
 export const currentUser = ServerHelperModule.currentUser as ServerHelpersServerModuleTypes['currentUser'];
 // export const getAuth = ServerHelperModule.getAuth as ServerHelpersServerModuleTypes['getAuth'];