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;
  }
 

.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;
  }
 

.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;
  }
 

.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;
  }
 

.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;
  }
 

.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;
  }
 

.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;
  }
 

.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;
  }