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

.changeset/angry-nights-smash.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add support for feature or plan based authorization.

.changeset/cold-bears-go.md

@@ -0,0 +1,5 @@
+---
+'@clerk/types': minor
+---
+
+Add `pla` claim to `VersionedJwtPayload`.

.changeset/every-feet-brush.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Replace `parseFeatures` with `splitByScope`.

.changeset/flat-cougars-mate.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Update `createCheckAuthorization` to support authorization based on features and plans.

.changeset/four-doors-attack.md

@@ -0,0 +1,33 @@
+---
+'@clerk/clerk-react': minor
+---
+
+Add support for feature or plan based authorization
+
+## `useAuth()`
+### Plan
+- `useAuth().has({ plan: "my-plan" })`
+
+### Feature
+- `useAuth().has({ feature: "my-feature" })`
+
+### Scoped per user or per org
+- `useAuth().has({ feature: "org:my-feature" })`
+- `useAuth().has({ feature: "user:my-feature" })`
+- `useAuth().has({ plan: "user:my-plan" })`
+- `useAuth().has({ plan: "org:my-plan" })`
+
+## `<Protect />`
+
+### Plan
+- `<Protect plan="my-plan" />`
+
+### Feature
+- `<Protect feature="my-feature" />`
+
+### Scoped per user or per org
+- `<Protect feature="org:my-feature" />`
+- `<Protect feature="user:my-feature" />`
+- `<Protect plan="org:my-plan" />`
+- `<Protect plan="user:my-plan" />`
+

.changeset/four-streets-join.md

@@ -0,0 +1,17 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Add support for feature or plan based authorization
+
+### Plan
+- `Clerk.session.checkAuthorization({ plan: "my-plan" })`
+
+### Feature
+- `Clerk.session.checkAuthorization({ feature: "my-feature" })`
+
+### Scoped per user or per org
+- `Clerk.session.checkAuthorization({ feature: "org:my-feature" })`
+- `Clerk.session.checkAuthorization({ feature: "user:my-feature" })`
+- `Clerk.session.checkAuthorization({ plan: "user:my-plan" })`
+- `Clerk.session.checkAuthorization({ plan: "org:my-plan" })`

.changeset/hip-sides-kick.md

@@ -0,0 +1,61 @@
+---
+'@clerk/nextjs': minor
+---
+
+Add support for feature or plan based authorization
+
+
+## `await auth()`
+### Plan
+- `(await auth()).has({ plan: "my-plan" })`
+
+### Feature
+- `(await auth()).has({ feature: "my-feature" })`
+
+### Scoped per user or per org
+- `(await auth()).has({ feature: "org:my-feature" })`
+- `(await auth()).has({ feature: "user:my-feature" })`
+- `(await auth()).has({ plan: "user:my-plan" })`
+- `(await auth()).has({ plan: "org:my-plan" })`
+
+## `auth.protect()`
+### Plan
+- `auth.protect({ plan: "my-plan" })`
+
+### Feature
+- `auth.protect({ feature: "my-feature" })`
+
+### Scoped per user or per org
+- `auth.protect({ feature: "org:my-feature" })`
+- `auth.protect({ feature: "user:my-feature" })`
+- `auth.protect({ plan: "user:my-plan" })`
+- `auth.protect({ plan: "org:my-plan" })`
+
+
+## `<Protect />`
+
+### Plan
+- `<Protect plan="my-plan" />`
+
+### Feature
+- `<Protect feature="my-feature" />`
+
+### Scoped per user or per org
+- `<Protect feature="org:my-feature" />`
+- `<Protect feature="user:my-feature" />`
+- `<Protect plan="org:my-plan" />`
+- `<Protect plan="user:my-plan" />`
+
+
+## `useAuth()`
+### Plan
+- `useAuth().has({ plan: "my-plan" })`
+
+### Feature
+- `useAuth().has({ feature: "my-feature" })`
+
+### Scoped per user or per org
+- `useAuth().has({ feature: "org:my-feature" })`
+- `useAuth().has({ feature: "user:my-feature" })`
+- `useAuth().has({ plan: "user:my-plan" })`
+- `useAuth().has({ plan: "org:my-plan" })`

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/nextjs/src/app-router/server/controlComponents.tsx

@@ -49,7 +49,12 @@ export async function Protect(props: ProtectProps): Promise<React.JSX.Element |
     return restAuthorizedParams.condition(has) ? authorized : unauthorized;
   }
 
-  if (restAuthorizedParams.role || restAuthorizedParams.permission) {
+  if (
+    restAuthorizedParams.role ||
+    restAuthorizedParams.permission ||
+    restAuthorizedParams.feature ||
+    restAuthorizedParams.plan
+  ) {
     return has(restAuthorizedParams) ? authorized : unauthorized;
   }