feat(types,shared): JWT v2 - Support new organization claims structure

.changeset/cool-socks-invite.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Adding the new `o` claim that contains all organization related info for JWT v2 schema

.changeset/cyan-hairs-share.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/backend': patch
+---
+
+Uses the helper function `__experimental_JWTPayloadToAuthObjectProperties` from `@clerk/shared` to handle the new JWT v2 schema.

packages/backend/src/tokens/authObjects.ts

@@ -1,13 +1,11 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
+import { __experimental_JWTPayloadToAuthObjectProperties } from '@clerk/shared/jwtPayloadParser';
 import type {
-  ActClaim,
   CheckAuthorizationFromSessionClaims,
   JwtPayload,
-  OrganizationCustomPermissionKey,
-  OrganizationCustomRoleKey,
   ServerGetToken,
   ServerGetTokenOptions,
-  SessionStatusClaim,
+  SharedSignedInAuthObjectProperties,
 } from '@clerk/types';
 
 import type { CreateBackendApiOptions } from '../api';
@@ -27,28 +25,7 @@ export type SignedInAuthObjectOptions = CreateBackendApiOptions & {
 /**
  * @internal
  */
-type SignedInAuthObjectProperties = {
-  sessionClaims: JwtPayload;
-  sessionId: string;
-  sessionStatus: SessionStatusClaim | null;
-  actor: ActClaim | undefined;
-  userId: string;
-  orgId: string | undefined;
-  orgRole: OrganizationCustomRoleKey | undefined;
-  orgSlug: string | undefined;
-  orgPermissions: OrganizationCustomPermissionKey[] | undefined;
-  /**
-   * Factor Verification Age
-   * Each item represents the minutes that have passed since the last time a first or second factor were verified.
-   * [fistFactorAge, secondFactorAge]
-   */
-  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
-};
-
-/**
- * @internal
- */
-export type SignedInAuthObject = SignedInAuthObjectProperties & {
+export type SignedInAuthObject = SharedSignedInAuthObjectProperties & {
   getToken: ServerGetToken;
   has: CheckAuthorizationFromSessionClaims;
   debug: AuthObjectDebug;
@@ -92,31 +69,6 @@ const createDebug = (data: AuthObjectDebugData | undefined) => {
   };
 };
 
-const generateSignedInAuthObjectProperties = (claims: JwtPayload): SignedInAuthObjectProperties => {
-  // fva can be undefined for instances that have not opt-in
-  const factorVerificationAge = claims.fva ?? null;
-
-  // sts can be undefined for instances that have not opt-in
-  const sessionStatus = claims.sts ?? null;
-
-  // TODO(jwt-v2): replace this when the new claim for org permissions is added, this will not break
-  // anything since the JWT v2 is not yet available
-  const orgPermissions = claims.org_permissions;
-
-  return {
-    sessionClaims: claims,
-    sessionId: claims.sid,
-    sessionStatus,
-    actor: claims.act,
-    userId: claims.sub,
-    orgId: claims.org_id,
-    orgRole: claims.org_role,
-    orgSlug: claims.org_slug,
-    orgPermissions,
-    factorVerificationAge,
-  };
-};
-
 /**
  * @internal
  */
@@ -126,14 +78,13 @@ export function signedInAuthObject(
   sessionClaims: JwtPayload,
 ): SignedInAuthObject {
   const { actor, sessionId, sessionStatus, userId, orgId, orgRole, orgSlug, orgPermissions, factorVerificationAge } =
-    generateSignedInAuthObjectProperties(sessionClaims);
+    __experimental_JWTPayloadToAuthObjectProperties(sessionClaims);
   const apiClient = createBackendApiClient(authenticateContext);
   const getToken = createGetToken({
     sessionId,
     sessionToken,
     fetcher: async (...args) => (await apiClient.sessions.getToken(...args)).jwt,
   });
-
   return {
     actor,
     sessionClaims,

packages/clerk-js/bundlewatch.config.json

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

packages/clerk-js/src/core/jwt-client.ts

@@ -1,3 +1,4 @@
+import { __experimental_JWTPayloadToAuthObjectProperties } from '@clerk/shared/jwtPayloadParser';
 import type {
   ClientJSON,
   OrganizationMembershipJSON,
@@ -43,47 +44,47 @@ export function createClientFromJwt(jwt: string | undefined | null): Client {
     } as unknown as ClientJSON);
   }
 
-  const { sid, sub, org_id, org_role, org_permissions, org_slug, fva } = token.jwt.claims;
-
-  // TODO(jwt-v2): when JWT version 2 is available, we should use the new claims instead of the old ones
+  const { sessionId, userId, orgId, orgRole, orgPermissions, orgSlug, factorVerificationAge } =
+    __experimental_JWTPayloadToAuthObjectProperties(token.jwt.claims);
 
+  // TODO(jwt-v2): when JWT version 2 is available, we should revise org permissions
   const defaultClient = {
     object: 'client',
-    last_active_session_id: sid,
+    last_active_session_id: sessionId,
     id: 'client_init',
     sessions: [
       {
         object: 'session',
-        id: sid,
+        id: sessionId,
         status: 'active',
-        last_active_organization_id: org_id || null,
+        last_active_organization_id: orgId || null,
         // @ts-expect-error - ts is not happy about `id:undefined`, but this is allowed and expected
         last_active_token: {
           id: undefined,
           object: 'token',
           jwt,
         } as TokenJSON,
-        factor_verification_age: fva || null,
+        factor_verification_age: factorVerificationAge || null,
         public_user_data: {
-          user_id: sub,
+          user_id: userId,
         } as PublicUserDataJSON,
         user: {
           object: 'user',
-          id: sub,
+          id: userId,
           organization_memberships:
-            org_id && org_slug && org_role
+            orgId && orgSlug && orgRole
               ? [
                   {
                     object: 'organization_membership',
-                    id: org_id,
-                    role: org_role,
-                    permissions: org_permissions || [],
+                    id: orgId,
+                    role: orgRole,
+                    permissions: orgPermissions || [],
                     organization: {
                       object: 'organization',
-                      id: org_id,
+                      id: orgId,
                       // Use slug as name for the organization, since name is not available in the token.
-                      name: org_slug,
-                      slug: org_slug,
+                      name: orgSlug,
+                      slug: orgSlug,
                       members_count: 1,
                       max_allowed_memberships: 1,
                     },

packages/shared/package.json

@@ -117,7 +117,8 @@
     "web3",
     "getEnvVariable",
     "pathMatcher",
-    "organization"
+    "organization",
+    "jwtPayloadParser"
   ],
   "scripts": {
     "build": "tsup",

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

@@ -0,0 +1,166 @@
+import { __experimental_JWTPayloadToAuthObjectProperties as JWTPayloadToAuthObjectProperties } from '../jwtPayloadParser';
+
+const baseClaims = {
+  exp: 1234567890,
+  iat: 1234567890,
+  iss: 'https://api.clerk.com',
+  sub: 'sub',
+  sid: 'sid',
+  azp: 'azp',
+  nbf: 1234567890,
+  __raw: '',
+};
+
+describe('JWTPayloadToAuthObjectProperties', () => {
+  test('auth object with JWT v2 does not produces anything org related if there is no org active', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObjectV2 } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'u:impersonation,u:memberships',
+    });
+
+    const { sessionClaims: v1Claims, ...signedInAuthObjectV1 } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+    });
+    expect(signedInAuthObjectV1).toEqual(signedInAuthObjectV2);
+    expect(signedInAuthObjectV1.orgId).toBeUndefined();
+    expect(signedInAuthObjectV1.orgPermissions).toBeUndefined();
+    expect(signedInAuthObjectV1.orgRole).toBeUndefined();
+    expect(signedInAuthObjectV1.orgSlug).toBeUndefined();
+  });
+
+  test('produced auth object is the same for v1 and v2', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObjectV2 } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'o:impersonation',
+      o: {
+        id: 'org_xxxxxxx',
+        rol: 'admin',
+        slg: '/test',
+        per: 'read,manage',
+        fpm: '3',
+      },
+    });
+
+    const { sessionClaims: v1Claims, ...signedInAuthObjectV1 } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      org_id: 'org_xxxxxxx',
+      org_role: 'org:admin',
+      org_slug: '/test',
+      org_permissions: ['org:impersonation:read', 'org:impersonation:manage'],
+    });
+    expect(signedInAuthObjectV1).toEqual(signedInAuthObjectV2);
+  });
+
+  test('produced auth object is the same for v1 and v2', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObjectV2 } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'o:impersonation',
+      o: {
+        id: 'org_xxxxxxx',
+        rol: 'admin',
+        slg: '/test',
+        per: 'read,manage',
+        fpm: '3',
+      },
+    });
+
+    const { sessionClaims: v1Claims, ...signedInAuthObjectV1 } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      org_id: 'org_xxxxxxx',
+      org_role: 'org:admin',
+      org_slug: '/test',
+      org_permissions: ['org:impersonation:read', 'org:impersonation:manage'],
+    });
+    expect(signedInAuthObjectV1).toEqual(signedInAuthObjectV2);
+  });
+
+  test('org permissions are generated correctly when fea, per, and fpm are present', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObject } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'o:impersonation,o:memberships',
+      o: {
+        id: 'org_xxxxxxx',
+        rol: 'admin',
+        slg: '/test',
+        per: 'read,manage',
+        fpm: '2,3',
+      },
+    });
+
+    expect(signedInAuthObject.orgPermissions?.sort()).toEqual(
+      ['org:impersonation:read', 'org:memberships:read', 'org:memberships:manage'].sort(),
+    );
+  });
+
+  test('if a feature is not mapped to any permissions it is added as is to the orgPermissions array', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObject } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'o:impersonation,o:memberships,o:feature3',
+      o: {
+        id: 'org_id',
+        rol: 'admin',
+        slg: 'org_slug',
+        per: 'read,manage',
+        fpm: '2,3',
+      },
+    });
+
+    expect(signedInAuthObject.orgPermissions?.sort()).toEqual(
+      ['org:impersonation:read', 'org:memberships:read', 'org:memberships:manage'].sort(),
+    );
+  });
+
+  test('includes both org and user scoped features', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObject } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'uo:impersonation,o:memberships,uo:feature3',
+      o: {
+        id: 'org_id',
+        rol: 'admin',
+        slg: 'org_slug',
+        per: 'read,manage',
+        fpm: '2,3,2',
+      },
+    });
+
+    expect(signedInAuthObject.orgPermissions?.sort()).toEqual(
+      ['org:impersonation:read', 'org:memberships:read', 'org:memberships:manage', 'org:feature3:read'].sort(),
+    );
+  });
+
+  test('if there is no o.fpm and o.per org permissions should be empty arrat', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObject } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'u:impersonation,u:memberships,u:feature3',
+      o: {
+        id: 'org_id',
+        rol: 'admin',
+        slg: 'org_slug',
+      },
+    });
+
+    expect(signedInAuthObject.orgPermissions).toEqual([]);
+  });
+
+  test('org role is prefixed with org:', () => {
+    const { sessionClaims: v2Claims, ...signedInAuthObject } = JWTPayloadToAuthObjectProperties({
+      ...baseClaims,
+      v: 2,
+      fea: 'u:impersonation,u:memberships,u:feature3',
+      o: {
+        id: 'org_id',
+        rol: 'admin',
+        slg: 'org_slug',
+      },
+    });
+
+    expect(signedInAuthObject.orgRole).toBe('org:admin');
+  });
+});

packages/shared/src/authorization.ts

@@ -12,6 +12,7 @@ import type {
   SignOut,
   UseAuthReturn,
 } from '@clerk/types';
+import { permission } from 'process';
 
 type TypesToConfig = Record<SessionVerificationTypes, Exclude<ReverificationConfig, SessionVerificationTypes>>;
 type AuthorizationOptions = {