feat(clerk-react,backend,shared,types): Introduce has({ feature | plan })

.changeset/loud-glasses-notice.md

@@ -0,0 +1,8 @@
+---
+'@clerk/backend': minor
+'@clerk/shared': minor
+'@clerk/clerk-react': minor
+'@clerk/types': minor
+---
+
+WIP

packages/backend/src/jwt/verifyJwt.ts

@@ -76,6 +76,7 @@ export function decodeJwt(token: string): JwtReturnType<Jwt, TokenVerificationEr
   // More info at https://stackoverflow.com/questions/54062583/how-to-verify-a-signed-jwt-with-subtlecrypto-of-the-web-crypto-API
   const header = JSON.parse(decoder.decode(base64url.parse(rawHeader, { loose: true })));
   const payload = JSON.parse(decoder.decode(base64url.parse(rawPayload, { loose: true })));
+
   const signature = base64url.parse(rawSignature, { loose: true });
 
   const data = {

packages/backend/src/tokens/__tests__/authObjects.test.ts

@@ -31,4 +31,146 @@ describe('signedInAuthObject', () => {
     const token = await authObject.getToken();
     expect(token).toBe('token');
   });
+
+  describe('JWT v1', () => {
+    it('has() for orgs', () => {
+      const mockAuthenticateContext = { sessionToken: 'authContextToken' } as AuthenticateContext;
+
+      const partialJwtPayload = {
+        ___raw: 'raw',
+        act: { sub: 'actor' },
+        sid: 'sessionId',
+        org_id: 'orgId',
+        org_role: 'org:admin',
+        org_slug: 'orgSlug',
+        org_permissions: ['org:f1:read', 'org:f2:manage'],
+        sub: 'userId',
+      } as Partial<JwtPayload>;
+
+      const authObject = signedInAuthObject(mockAuthenticateContext, 'token', partialJwtPayload as JwtPayload);
+
+      expect(authObject.has({ role: 'org:admin' })).toBe(true);
+      expect(authObject.has({ permission: 'org:f1:read' })).toBe(true);
+      expect(authObject.has({ permission: 'org:f1' })).toBe(false);
+      expect(authObject.has({ permission: 'org:f2:manage' })).toBe(true);
+      expect(authObject.has({ permission: 'org:f2' })).toBe(false);
+
+      expect(authObject.has({ feature: 'org:reservations' })).toBe(false);
+      expect(authObject.has({ feature: 'org:impersonation' })).toBe(false);
+    });
+  });
+
+  describe('JWT v2', () => {
+    it('has() for orgs', () => {
+      const mockAuthenticateContext = { sessionToken: 'authContextToken' } as AuthenticateContext;
+
+      const partialJwtPayload = {
+        v: 2,
+        ___raw: 'raw',
+        act: { sub: 'actor' },
+        sid: 'sessionId',
+        fea: 'o:reservations,o:impersonation',
+        o: {
+          id: 'orgId',
+          rol: 'admin',
+          slg: 'orgSlug',
+          per: 'read,manage',
+          fpm: '3',
+        },
+
+        sub: 'userId',
+      } as Partial<JwtPayload>;
+
+      const authObject = signedInAuthObject(mockAuthenticateContext, 'token', partialJwtPayload as JwtPayload);
+
+      expect(authObject.has({ role: 'org:admin' })).toBe(true);
+      expect(authObject.has({ permission: 'org:reservations:read' })).toBe(true);
+      expect(authObject.has({ permission: 'org:reservations' })).toBe(false);
+      expect(authObject.has({ permission: 'org:reservations:manage' })).toBe(true);
+      expect(authObject.has({ permission: 'org:reservations' })).toBe(false);
+      expect(authObject.has({ permission: 'org:impersonation:read' })).toBe(false);
+      expect(authObject.has({ permission: 'org:impersonation:manage' })).toBe(false);
+
+      expect(authObject.has({ feature: 'org:reservations' })).toBe(true);
+      expect(authObject.has({ feature: 'org:impersonation' })).toBe(true);
+    });
+
+    it('has() for billing with scopes', () => {
+      const mockAuthenticateContext = { sessionToken: 'authContextToken' } as AuthenticateContext;
+
+      const partialJwtPayload = {
+        v: 2,
+        ___raw: 'raw',
+        act: { sub: 'actor' },
+        sid: 'sessionId',
+        fea: 'o:reservations,u:dashboard,uo:support-chat,o:impersonation',
+        o: {
+          id: 'orgId',
+          rol: 'member',
+          slg: 'orgSlug',
+          per: 'read,manage',
+          fpm: '2,3',
+        },
+        pla: 'u:pro,o:business',
+        sub: 'userId',
+      } as Partial<JwtPayload>;
+
+      const authObject = signedInAuthObject(mockAuthenticateContext, 'token', partialJwtPayload as JwtPayload);
+
+      expect(authObject.has({ permission: 'org:reservations:read' })).toBe(true);
+      expect(authObject.has({ permission: 'org:reservations:manage' })).toBe(false);
+
+      expect(authObject.has({ permission: 'org:support-chat:read' })).toBe(true);
+      expect(authObject.has({ permission: 'org:support-chat:manage' })).toBe(true);
+
+      expect(authObject.has({ permission: 'u:dashboard:manage' })).toBe(false);
+      expect(authObject.has({ permission: 'u:dashboard:read' })).toBe(false);
+
+      expect(authObject.has({ feature: 'org:reservations' })).toBe(true);
+      expect(authObject.has({ feature: 'user:reservations' })).toBe(false);
+      expect(authObject.has({ feature: 'org:impersonation' })).toBe(true);
+      expect(authObject.has({ feature: 'user:impersonation' })).toBe(false);
+      expect(authObject.has({ feature: 'org:dashboard' })).toBe(false);
+      expect(authObject.has({ feature: 'user:dashboard' })).toBe(true);
+      expect(authObject.has({ feature: 'org:support-chat' })).toBe(true);
+      expect(authObject.has({ feature: 'user:support-chat' })).toBe(true);
+
+      expect(authObject.has({ plan: 'org:business' })).toBe(true);
+      expect(authObject.has({ plan: 'user:business' })).toBe(false);
+
+      expect(authObject.has({ plan: 'org:pro' })).toBe(false);
+      expect(authObject.has({ plan: 'user:pro' })).toBe(true);
+    });
+
+    it('has() for billing without scopes', () => {
+      const mockAuthenticateContext = { sessionToken: 'authContextToken' } as AuthenticateContext;
+
+      const partialJwtPayload = {
+        v: 2,
+        ___raw: 'raw',
+        act: { sub: 'actor' },
+        sid: 'sessionId',
+        fea: 'o:reservations,u:dashboard,uo:support-chat,o:impersonation',
+        o: {
+          id: 'orgId',
+          rol: 'member',
+          slg: 'orgSlug',
+          per: 'read,manage',
+          fpm: '2,3',
+        },
+        pla: 'u:pro,o:business',
+        sub: 'userId',
+      } as Partial<JwtPayload>;
+
+      const authObject = signedInAuthObject(mockAuthenticateContext, 'token', partialJwtPayload as JwtPayload);
+
+      expect(authObject.has({ feature: 'reservations' })).toBe(true); // because the org has it.
+      expect(authObject.has({ feature: 'dashboard' })).toBe(true); // because the user has it.
+      expect(authObject.has({ feature: 'pro' })).toBe(false); // `pro` is a plan
+      expect(authObject.has({ feature: 'impersonation' })).toBe(true); // because the org has it.
+
+      expect(authObject.has({ plan: 'pro' })).toBe(true); // because the user has it.
+      expect(authObject.has({ plan: 'business' })).toBe(true); // because the org has it.
+    });
+  });
 });

packages/backend/src/tokens/authObjects.ts

@@ -97,7 +97,15 @@ export function signedInAuthObject(
     orgPermissions,
     factorVerificationAge,
     getToken,
-    has: createCheckAuthorization({ orgId, orgRole, orgPermissions, userId, factorVerificationAge }),
+    has: createCheckAuthorization({
+      orgId,
+      orgRole,
+      orgPermissions,
+      userId,
+      factorVerificationAge,
+      features: (sessionClaims.fea as string) || '',
+      plans: (sessionClaims.pla as string) || '',
+    }),
     debug: createDebug({ ...authenticateContext, sessionToken }),
   };
 }

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
   "files": [
     { "path": "./dist/clerk.js", "maxSize": "590kB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "73.5KB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "73.64KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "99KB" },
     { "path": "./dist/vendors*.js", "maxSize": "36KB" },

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

@@ -115,6 +115,8 @@ export class Session extends BaseResource implements SessionResource {
       orgId: activeMembership?.id,
       orgRole: activeMembership?.role,
       orgPermissions: activeMembership?.permissions,
+      features: (this.lastActiveToken?.jwt?.claims.fea as string) || '',
+      plans: (this.lastActiveToken?.jwt?.claims.pla as string) || '',
     })(params);
   };
 

packages/react/src/components/controlComponents.tsx

@@ -1,5 +1,6 @@
 import { deprecated } from '@clerk/shared/deprecated';
 import type {
+  Autocomplete,
   CheckAuthorizationWithCustomPermissions,
   HandleOAuthCallbackParams,
   OrganizationCustomPermissionKey,
@@ -61,21 +62,43 @@ export type ProtectProps = React.PropsWithChildren<
         condition?: never;
         role: OrganizationCustomRoleKey;
         permission?: never;
+        feature?: never;
+        plan?: never;
       }
     | {
         condition?: never;
         role?: never;
+        feature?: never;
+        plan?: never;
         permission: OrganizationCustomPermissionKey;
       }
     | {
         condition: (has: CheckAuthorizationWithCustomPermissions) => boolean;
         role?: never;
         permission?: never;
+        feature?: never;
+        plan?: never;
       }
     | {
         condition?: never;
         role?: never;
         permission?: never;
+        feature: Autocomplete<`user:${string}` | `org:${string}`>;
+        plan?: never;
+      }
+    | {
+        condition?: never;
+        role?: never;
+        permission?: never;
+        feature?: never;
+        plan: Autocomplete<`user:${string}` | `org:${string}`>;
+      }
+    | {
+        condition?: never;
+        role?: never;
+        permission?: never;
+        feature?: never;
+        plan?: never;
       }
   ) & {
     fallback?: React.ReactNode;
@@ -127,7 +150,12 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
     return unauthorized;
   }
 
-  if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+  if (
+    restAuthorizedParams.role ||
+    restAuthorizedParams.permission ||
+    restAuthorizedParams.feature ||
+    restAuthorizedParams.plan
+  ) {
     if (has(restAuthorizedParams)) {
       return authorized;
     }

packages/react/src/hooks/__tests__/useAuth.type.test.ts

@@ -27,10 +27,42 @@ describe('useAuth type tests', () => {
       expectTypeOf({ role: 'org:admin', permission: 'some-perm' }).not.toMatchTypeOf<ParamsOfHas>();
     });
 
+    it('has({feature}) is allowed', () => {
+      expectTypeOf({
+        feature: 'org:feature',
+      }).toMatchTypeOf<ParamsOfHas>();
+    });
+
+    it('has({plan}) is allowed', () => {
+      expectTypeOf({
+        plan: 'org:pro',
+      }).toMatchTypeOf<ParamsOfHas>();
+    });
+
+    it('has({feature: string, plan: string}) is NOT allowed', () => {
+      expectTypeOf({ plan: 'org:pro', feature: 'org:feature' }).not.toMatchTypeOf<ParamsOfHas>();
+    });
+
+    it('has({feature: string, permission: string}) is NOT allowed', () => {
+      expectTypeOf({ feature: 'org:pro', permission: 'org:feature' }).not.toMatchTypeOf<ParamsOfHas>();
+    });
+
+    it('has({plan: string, role: string}) is NOT allowed', () => {
+      expectTypeOf({ plan: 'org:pro', role: 'org:feature' }).not.toMatchTypeOf<ParamsOfHas>();
+    });
+
+    it('has({plan: string, reverification}) is allowed', () => {
+      expectTypeOf({ plan: 'org:pro', reverification: 'lax' } as const).toMatchTypeOf<ParamsOfHas>();
+    });
+
+    it('has({feature: string, reverification}) is allowed', () => {
+      expectTypeOf({ feature: 'org:feature', reverification: 'lax' } as const).toMatchTypeOf<ParamsOfHas>();
+    });
+
     it('has with role and re-verification is allowed', () => {
       expectTypeOf({
         role: 'org:admin',
-        __experimental_reverification: {
+        reverification: {
           level: 'first_factor',
           afterMinutes: 10,
         },

packages/react/src/hooks/useAuth.ts

@@ -3,6 +3,7 @@ import { eventMethodCalled } from '@clerk/shared/telemetry';
 import type {
   CheckAuthorizationWithCustomPermissions,
   GetToken,
+  JwtPayload,
   PendingSessionOptions,
   SignOut,
   UseAuthReturn,
@@ -144,7 +145,8 @@ export function useDerivedAuth(
   authObject: any,
   { treatPendingAsSignedOut = true }: PendingSessionOptions = {},
 ): UseAuthReturn {
-  const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge } = authObject ?? {};
+  const { userId, orgId, orgRole, has, signOut, getToken, orgPermissions, factorVerificationAge, sessionClaims } =
+    authObject ?? {};
 
   const derivedHas = useCallback(
     (params: Parameters<CheckAuthorizationWithCustomPermissions>[0]) => {
@@ -157,6 +159,8 @@ export function useDerivedAuth(
         orgRole,
         orgPermissions,
         factorVerificationAge,
+        features: ((sessionClaims as JwtPayload | undefined)?.fea as string) || '',
+        plans: ((sessionClaims as JwtPayload | undefined)?.pla as string) || '',
       })(params);
     },
     [has, userId, orgId, orgRole, orgPermissions, factorVerificationAge],

packages/shared/src/__tests__/jwtPayloadParser.test.ts

@@ -1,7 +1,5 @@
-import {
-  __experimental_JWTPayloadToAuthObjectProperties as JWTPayloadToAuthObjectProperties,
-  parseFeatures,
-} from '../jwtPayloadParser';
+import { splitByScope } from '../authorization';
+import { __experimental_JWTPayloadToAuthObjectProperties as JWTPayloadToAuthObjectProperties } from '../jwtPayloadParser';
 
 const baseClaims = {
   exp: 1234567890,
@@ -187,37 +185,37 @@ describe('JWTPayloadToAuthObjectProperties', () => {
   });
 });
 
-describe('parseFeatures ', () => {
+describe('splitByScope ', () => {
   test('returns empty array when no features are present', () => {
-    const { orgFeatures } = parseFeatures('');
-    expect(orgFeatures).toEqual([]);
+    const { org } = splitByScope('');
+    expect(org).toEqual([]);
   });
 
   test('only org features included', () => {
-    const { orgFeatures, userFeatures } = parseFeatures('o:impersonation,o:payments');
-    expect(orgFeatures).toEqual(['impersonation', 'payments']);
+    const { org, user } = splitByScope('o:impersonation,o:payments');
+    expect(org).toEqual(['impersonation', 'payments']);
 
-    expect(userFeatures).toEqual([]);
+    expect(user).toEqual([]);
   });
 
   test('only user features included', () => {
-    const { orgFeatures, userFeatures } = parseFeatures('u:impersonation,u:payments');
-    expect(orgFeatures).toEqual([]);
+    const { org, user } = splitByScope('u:impersonation,u:payments');
+    expect(org).toEqual([]);
 
-    expect(userFeatures).toEqual(['impersonation', 'payments']);
+    expect(user).toEqual(['impersonation', 'payments']);
   });
 
   test('both org and user features included', () => {
-    const { orgFeatures, userFeatures } = parseFeatures('o:payments,u:impersonation');
-    expect(orgFeatures).toEqual(['payments']);
+    const { org, user } = splitByScope('o:payments,u:impersonation');
+    expect(org).toEqual(['payments']);
 
-    expect(userFeatures).toEqual(['impersonation']);
+    expect(user).toEqual(['impersonation']);
   });
 
   test('features have multiple scopes', () => {
-    const { orgFeatures, userFeatures } = parseFeatures('ou:payments,u:impersonation');
-    expect(orgFeatures).toEqual(['payments']);
+    const { org, user } = splitByScope('ou:payments,u:impersonation');
+    expect(org).toEqual(['payments']);
 
-    expect(userFeatures).toEqual(['payments', 'impersonation']);
+    expect(user).toEqual(['payments', 'impersonation']);
   });
 });