Introduce internal Gate component (#1834)

* feat(clerk-js,types): Introduce Session.isAuthorized

* feat(clerk-js): Introduce internal Gate component

.changeset/loud-foxes-love.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Introduces a new `isAuthorized()` method in the `Session` class. Returns a promise and checks whether the active user is allowed to perform an action based on the passed (required) permission and the ones attached to the membership.

.changeset/proud-dolls-yawn.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Introduces an internal `<Gate/>` component (supporting hook and HOC) which enables us to conditionally render parts of our components based on a users permissions.

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

@@ -6,6 +6,7 @@ import type {
   MembershipRole,
   OrganizationMembershipJSON,
   OrganizationMembershipResource,
+  OrganizationPermission,
 } from '@clerk/types';
 
 import { unixEpochToDate } from '../../utils/date';
@@ -17,6 +18,12 @@ export class OrganizationMembership extends BaseResource implements Organization
   publicMetadata: OrganizationMembershipPublicMetadata = {};
   publicUserData!: PublicUserData;
   organization!: Organization;
+  /**
+   * @experimental The property is experimental and subject to change in future releases.
+   */
+  // Adding (string & {}) allows for getting eslint autocomplete but also accepts any string
+  // eslint-disable-next-line
+  permissions: (OrganizationPermission | (string & {}))[] = [];
   role!: MembershipRole;
   createdAt!: Date;
   updatedAt!: Date;
@@ -106,6 +113,7 @@ export class OrganizationMembership extends BaseResource implements Organization
     if (data.public_user_data) {
       this.publicUserData = new PublicUserData(data.public_user_data);
     }
+    this.permissions = Array.isArray(data.permissions) ? [...data.permissions] : [];
     this.role = data.role;
     this.createdAt = unixEpochToDate(data.created_at);
     this.updatedAt = unixEpochToDate(data.updated_at);

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

@@ -56,4 +56,46 @@ describe('Session', () => {
       expect(dispatchSpy.mock.calls[0]).toMatchSnapshot();
     });
   });
+
+  describe('isAuthorized()', () => {
+    it('user with permission to delete the organization should be able to delete the  organization', async () => {
+      const session = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({
+          organization_memberships: [{ name: 'Org1', id: 'org1' }],
+        }),
+        last_active_organization_id: 'org1',
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      const isAuthorized = await session.isAuthorized({ permission: 'org:profile:delete' });
+
+      expect(isAuthorized).toBe(true);
+    });
+
+    it('user with permission to read memberships should not be deleting the organization', async () => {
+      const session = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({
+          organization_memberships: [{ name: 'Org1', id: 'org1', permissions: ['org:memberships:read'] }],
+        }),
+        last_active_organization_id: 'org1',
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      const isAuthorized = await session.isAuthorized({ permission: 'org:profile:delete' });
+
+      expect(isAuthorized).toBe(false);
+    });
+  });
 });

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

@@ -4,6 +4,7 @@ import type {
   ActJWTClaim,
   GetToken,
   GetTokenOptions,
+  IsAuthorized,
   SessionJSON,
   SessionResource,
   SessionStatus,
@@ -75,6 +76,38 @@ 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 => {
+      // if there is no active organization user can not be authorized
+      if (!this.lastActiveOrganizationId || !this.user) {
+        return resolve(false);
+      }
+
+      // 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);
+      }
+
+      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);
+      }
+      return resolve(false);
+    });
+  };
+
   #hydrateCache = (token: TokenResource | null) => {
     if (token) {
       SessionTokenCache.set({

packages/clerk-js/src/core/resources/__snapshots__/OrganizationMembership.test.ts.snap

@@ -38,6 +38,7 @@ OrganizationMembership {
     "updatedAt": 1970-01-01T00:01:07.890Z,
   },
   "pathRoot": "",
+  "permissions": [],
   "publicMetadata": {
     "foo": "bar",
   },

packages/clerk-js/src/core/test/fixtures.ts

@@ -5,14 +5,15 @@ import type {
   OAuthProvider,
   OrganizationJSON,
   OrganizationMembershipJSON,
+  OrganizationPermission,
   PhoneNumberJSON,
   UserJSON,
 } from '@clerk/types';
 
 export const mockJwt =
   'eyJhbGciOiJSUzI1NiIsImtpZCI6Imluc18yR0lvUWhiVXB5MGhYN0IyY1ZrdVRNaW5Yb0QiLCJ0eXAiOiJKV1QifQ.eyJhenAiOiJodHRwczovL2FjY291bnRzLmluc3BpcmVkLnB1bWEtNzQubGNsLmRldiIsImV4cCI6MTY2NjY0ODMxMCwiaWF0IjoxNjY2NjQ4MjUwLCJpc3MiOiJodHRwczovL2NsZXJrLmluc3BpcmVkLnB1bWEtNzQubGNsLmRldiIsIm5iZiI6MTY2NjY0ODI0MCwic2lkIjoic2Vzc18yR2JEQjRlbk5kQ2E1dlMxenBDM1h6Zzl0SzkiLCJzdWIiOiJ1c2VyXzJHSXBYT0VwVnlKdzUxcmtabjlLbW5jNlN4ciJ9.n1Usc-DLDftqA0Xb-_2w8IGs4yjCmwc5RngwbSRvwevuZOIuRoeHmE2sgCdEvjfJEa7ewL6EVGVcM557TWPW--g_J1XQPwBy8tXfz7-S73CEuyRFiR97L2AHRdvRtvGtwR-o6l8aHaFxtlmfWbQXfg4kFJz2UGe9afmh3U9-f_4JOZ5fa3mI98UMy1-bo20vjXeWQ9aGrqaxHQxjnzzC-1Kpi5LdPvhQ16H0dPB8MHRTSM5TAuLKTpPV7wqixmbtcc2-0k6b9FKYZNqRVTaIyV-lifZloBvdzlfOF8nW1VVH_fx-iW5Q3hovHFcJIULHEC1kcAYTubbxzpgeVQepGg';
 
-type OrgParams = Partial<OrganizationJSON> & { role?: MembershipRole };
+type OrgParams = Partial<OrganizationJSON> & { role?: MembershipRole; permissions?: OrganizationPermission[] };
 
 type WithUserParams = Omit<
   Partial<UserJSON>,
@@ -26,8 +27,8 @@ type WithUserParams = Omit<
 
 export const getOrganizationId = (orgParams: OrgParams) => orgParams?.id || orgParams?.name || 'test_id';
 
-export const createOrganization = (params: OrgParams): OrganizationMembershipJSON => {
-  const { role, ...orgParams } = params;
+export const createOrganizationMembership = (params: OrgParams): OrganizationMembershipJSON => {
+  const { role, permissions, ...orgParams } = params;
   return {
     created_at: new Date().getTime(),
     id: getOrganizationId(orgParams),
@@ -49,6 +50,16 @@ export const createOrganization = (params: OrgParams): OrganizationMembershipJSO
     } as OrganizationJSON,
     public_metadata: {},
     role: role || 'admin',
+    permissions: permissions || [
+      'org:domains:delete',
+      'org:domains:manage',
+      'org:domains:read',
+      'org:memberships:delete',
+      'org:memberships:manage',
+      'org:memberships:read',
+      'org:profile:delete',
+      'org:profile:manage',
+    ],
     updated_at: new Date().getTime(),
   } as OrganizationMembershipJSON;
 };
@@ -145,7 +156,7 @@ export const createUser = (params: WithUserParams): UserJSON => {
       typeof p === 'string' ? createExternalAccount({ provider: p }) : createExternalAccount(p),
     ),
     organization_memberships: (params.organization_memberships || []).map(o =>
-      typeof o === 'string' ? createOrganization({ name: o }) : createOrganization(o),
+      typeof o === 'string' ? createOrganizationMembership({ name: o }) : createOrganizationMembership(o),
     ),
   } as any as UserJSON;
   res.primary_email_address_id = res.email_addresses[0]?.id;

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

@@ -0,0 +1,65 @@
+import type { IsAuthorized } 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 GateProps = PropsWithChildren<
+  GateParams & {
+    fallback?: ReactNode;
+    redirectTo?: string;
+  }
+>;
+
+export const useGate = (params: GateParams) => {
+  const { isAuthorized } = useCoreSession();
+  const { data: isAuthorizedUser } = useFetch(isAuthorized, params);
+
+  return {
+    isAuthorizedUser,
+  };
+};
+
+export const Gate = (gateProps: GateProps) => {
+  const { children, fallback, redirectTo, ...restAuthorizedParams } = gateProps;
+
+  const { isAuthorizedUser } = useGate(restAuthorizedParams);
+
+  const { navigate } = useRouter();
+
+  useEffect(() => {
+    // wait for promise to resolve
+    if (typeof isAuthorizedUser === 'boolean' && !isAuthorizedUser && redirectTo) {
+      void navigate(redirectTo);
+    }
+  }, [isAuthorizedUser, redirectTo]);
+
+  // wait for promise to resolve
+  if (typeof isAuthorizedUser === 'boolean' && !isAuthorizedUser && fallback) {
+    return <>{fallback}</>;
+  }
+
+  if (isAuthorizedUser) {
+    return <>{children}</>;
+  }
+
+  return null;
+};
+
+export function withGate<P>(Component: ComponentType<P>, gateProps: GateProps): React.ComponentType<P> {
+  const displayName = Component.displayName || Component.name || 'Component';
+  const HOC = (props: P) => {
+    return (
+      <Gate {...gateProps}>
+        <Component {...(props as any)} />
+      </Gate>
+    );
+  };
+
+  HOC.displayName = `withGate(${displayName})`;
+
+  return HOC;
+}

packages/clerk-js/src/ui/common/index.ts

@@ -2,6 +2,7 @@ export * from './BlockButtons';
 export * from './constants';
 export * from './CalloutWithAction';
 export * from './forms';
+export * from './Gate';
 export * from './InfiniteListSpinner';
 export * from './redirects';
 export * from './verification';

packages/clerk-js/src/ui/hooks/useFetch.ts

@@ -24,11 +24,11 @@ export const useFetch = <T>(
     requestStatus.setLoading();
     fetcherRef
       .current(params)
-      .then(domain => {
+      .then(result => {
         requestStatus.setIdle();
-        if (domain) {
-          setData({ ...domain });
-          callbacks?.onSuccess?.({ ...domain });
+        if (typeof result !== 'undefined') {
+          setData(typeof result === 'object' ? { ...result } : result);
+          callbacks?.onSuccess?.(typeof result === 'object' ? { ...result } : result);
         }
       })
       .catch(() => {

packages/types/src/json.ts

@@ -8,7 +8,7 @@ import type { ActJWTClaim } from './jwt';
 import type { OAuthProvider } from './oauth';
 import type { OrganizationDomainVerificationStatus, OrganizationEnrollmentMode } from './organizationDomain';
 import type { OrganizationInvitationStatus } from './organizationInvitation';
-import type { MembershipRole } from './organizationMembership';
+import type { MembershipRole, OrganizationPermission } from './organizationMembership';
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { SamlIdpSlug } from './saml';
@@ -322,6 +322,12 @@ export interface OrganizationMembershipJSON extends ClerkResourceJSON {
   object: 'organization_membership';
   id: string;
   organization: OrganizationJSON;
+  /**
+   * @experimental The property is experimental and subject to change in future releases.
+   */
+  // Adding (string & {}) allows for getting eslint autocomplete but also accepts any string
+  // eslint-disable-next-line
+  permissions: (OrganizationPermission | (string & {}))[];
   public_metadata: OrganizationMembershipPublicMetadata;
   public_user_data: PublicUserDataJSON;
   role: MembershipRole;

packages/types/src/organizationMembership.ts

@@ -25,6 +25,12 @@ declare global {
 export interface OrganizationMembershipResource extends ClerkResource {
   id: string;
   organization: OrganizationResource;
+  /**
+   * @experimental The property is experimental and subject to change in future releases.
+   */
+  // Adding (string & {}) allows for getting eslint autocomplete but also accepts any string
+  // eslint-disable-next-line
+  permissions: (OrganizationPermission | (string & {}))[];
   publicMetadata: OrganizationMembershipPublicMetadata;
   publicUserData: PublicUserData;
   role: MembershipRole;
@@ -36,6 +42,16 @@ export interface OrganizationMembershipResource extends ClerkResource {
 
 export type MembershipRole = 'admin' | 'basic_member' | 'guest_member';
 
+export type OrganizationPermission =
+  | 'org:domains:manage'
+  | 'org:domains:delete'
+  | 'org:profile:manage'
+  | 'org:profile:delete'
+  | 'org:memberships:read'
+  | 'org:memberships:manage'
+  | 'org:memberships:delete'
+  | 'org:domains:read';
+
 export type UpdateOrganizationMembershipParams = {
   role: MembershipRole;
 };

packages/types/src/session.ts

@@ -1,8 +1,20 @@
 import type { ActJWTClaim } from './jwt';
+import type { OrganizationPermission } from './organizationMembership';
 import type { ClerkResource } from './resource';
 import type { TokenResource } from './token';
 import type { UserResource } from './user';
 
+export type IsAuthorized = (isAuthorizedParams: IsAuthorizedParams) => Promise<IsAuthorizedReturnValues>;
+
+interface IsAuthorizedParams {
+  // Adding (string & {}) allows for getting eslint autocomplete but also accepts any string
+  // eslint-disable-next-line
+  permission?: OrganizationPermission | (string & {});
+  role?: string;
+}
+
+type IsAuthorizedReturnValues = boolean;
+
 export interface SessionResource extends ClerkResource {
   id: string;
   status: SessionStatus;
@@ -18,6 +30,10 @@ export interface SessionResource extends ClerkResource {
   remove: () => Promise<SessionResource>;
   touch: () => Promise<SessionResource>;
   getToken: GetToken;
+  /**
+   * @experimental The method is experimental and subject to change in future releases.
+   */
+  isAuthorized: IsAuthorized;
   clearCache: () => void;
   createdAt: Date;
   updatedAt: Date;