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

octoper · 2025-04-07T10:56:19Z

Description

This PR adds support for the new JWT v2 schema and also renames ver claim to v.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2025-04-07T10:56:22Z

🦋 Changeset detected

Latest commit: c1cb785

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 22 packages

Name	Type
@clerk/shared	Minor
@clerk/types	Minor
@clerk/clerk-js	Patch
@clerk/backend	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/chrome-extension	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch
@clerk/localizations	Patch
@clerk/themes	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-04-07T10:56:23Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 9, 2025 11:19am

packages/shared/src/authorization.ts

panteliselef · 2025-04-07T11:01:23Z

packages/shared/src/authorization.ts

+  createCheckAuthorization,
+  validateReverificationConfig,
+  resolveAuthState,
+  resolveSignedInAuthStateFromJWTClaims,


🙃 maybe use a new module

Not sure if there is a better module to put this, as much of this is tied and the new changes that will be added as part of JWT v2 schema are in a way tied to authorization 🤔

Maybe we could move it to a new module with JWT related things? Although the claims are authorization related, the logic here is not doing any authorization, just mapping the JWT payload to a new format. 🤔

I was also wondering if we shouldn't name this mapping here from claims -> signed in properties to payload -> claims, so claims would always have the same format regardless of the JWTPayload version, and then auth objects or JWT clients can use the claims to build their properties:

const __experimental_resolveClaimsFromJWTPayload = (payload: JwtPayload): JwtClaims

What do you think?

Maybe we could move it to a new module with JWT related things? Although the claims are authorization related, the logic here is not doing any authorization, just mapping the JWT payload to a new format.

Hmm yeah that's fair 👍

I was also wondering if we shouldn't name this mapping here from claims -> signed in properties to payload -> claims, so claims would always have the same format regardless of the JWTPayload version

The thing here is that the JWT claims will not be in the same format and it will be different depending on version also, it's also gonna be kinda of confusing when __experimental_resolveClaimsFromJWTPayload returns something different than the actual claims found on the token, that's why I've gone with claims -> signed in properties.

…sions on authObject backwards compatible

…k/types

octoper · 2025-04-09T09:19:55Z

!snapshot

clerk-cookie · 2025-04-09T09:22:05Z

Hey @octoper - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.0.20-snapshot.v20250409092045
@clerk/astro	2.6.2-snapshot.v20250409092045
@clerk/backend	1.27.2-snapshot.v20250409092045
@clerk/chrome-extension	2.2.27-snapshot.v20250409092045
@clerk/clerk-js	5.59.3-snapshot.v20250409092045
@clerk/elements	0.23.12-snapshot.v20250409092045
@clerk/clerk-expo	2.9.10-snapshot.v20250409092045
@clerk/expo-passkeys	0.2.4-snapshot.v20250409092045
@clerk/express	1.4.3-snapshot.v20250409092045
@clerk/fastify	2.2.3-snapshot.v20250409092045
@clerk/localizations	3.13.8-snapshot.v20250409092045
@clerk/nextjs	6.14.2-snapshot.v20250409092045
@clerk/nuxt	1.5.3-snapshot.v20250409092045
@clerk/clerk-react	5.26.2-snapshot.v20250409092045
@clerk/react-router	1.2.3-snapshot.v20250409092045
@clerk/remix	4.5.15-snapshot.v20250409092045
@clerk/shared	3.5.0-snapshot.v20250409092045
@clerk/tanstack-react-start	0.13.3-snapshot.v20250409092045
@clerk/testing	1.4.37-snapshot.v20250409092045
@clerk/themes	2.2.30-snapshot.v20250409092045
@clerk/types	4.52.0-snapshot.v20250409092045
@clerk/vue	1.5.2-snapshot.v20250409092045

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

octoper · 2025-04-09T09:43:55Z

!snapshot

clerk-cookie · 2025-04-09T09:45:58Z

Hey @octoper - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.0.20-snapshot.v20250409094437
@clerk/astro	2.6.2-snapshot.v20250409094437
@clerk/backend	1.27.2-snapshot.v20250409094437
@clerk/chrome-extension	2.2.27-snapshot.v20250409094437
@clerk/clerk-js	5.59.3-snapshot.v20250409094437
@clerk/elements	0.23.12-snapshot.v20250409094437
@clerk/clerk-expo	2.9.10-snapshot.v20250409094437
@clerk/expo-passkeys	0.2.4-snapshot.v20250409094437
@clerk/express	1.4.3-snapshot.v20250409094437
@clerk/fastify	2.2.3-snapshot.v20250409094437
@clerk/localizations	3.13.8-snapshot.v20250409094437
@clerk/nextjs	6.14.2-snapshot.v20250409094437
@clerk/nuxt	1.5.3-snapshot.v20250409094437
@clerk/clerk-react	5.26.2-snapshot.v20250409094437
@clerk/react-router	1.2.3-snapshot.v20250409094437
@clerk/remix	4.5.15-snapshot.v20250409094437
@clerk/shared	3.5.0-snapshot.v20250409094437
@clerk/tanstack-react-start	0.13.3-snapshot.v20250409094437
@clerk/testing	1.4.37-snapshot.v20250409094437
@clerk/themes	2.2.30-snapshot.v20250409094437
@clerk/types	4.52.0-snapshot.v20250409094437
@clerk/vue	1.5.2-snapshot.v20250409094437

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

…thObject

packages/types/src/jwtv2.ts

packages/shared/src/authorization.ts

packages/clerk-js/bundlewatch.config.json

octoper force-pushed the vaggelis/migrate-to-new-org-claims branch from f78f4c5 to 3908d07 Compare April 7, 2025 10:56

clerk-cookie added types clerk-js backend labels Apr 7, 2025

vercel bot deployed to Preview April 7, 2025 10:57 View deployment

panteliselef reviewed Apr 7, 2025

View reviewed changes

octoper self-assigned this Apr 7, 2025

octoper force-pushed the vaggelis/migrate-to-new-org-claims branch from 3908d07 to f6d4166 Compare April 7, 2025 11:06

vercel bot deployed to Preview April 7, 2025 11:07 View deployment

vercel bot deployed to Preview April 7, 2025 11:29 View deployment

vercel bot deployed to Preview April 7, 2025 12:48 View deployment

vercel bot deployed to Preview April 7, 2025 12:52 View deployment

vercel bot deployed to Preview April 7, 2025 13:01 View deployment

octoper marked this pull request as ready for review April 7, 2025 13:01

octoper requested review from iagodahlem, panteliselef, brkalow and anagstef April 7, 2025 13:03

octoper marked this pull request as draft April 7, 2025 14:09

vercel bot deployed to Preview April 7, 2025 14:52 View deployment

octoper marked this pull request as ready for review April 7, 2025 15:31

octoper force-pushed the vaggelis/migrate-to-new-org-claims branch from 0402c79 to 7fd491f Compare April 8, 2025 06:51

vercel bot deployed to Preview April 8, 2025 06:51 View deployment

vercel bot deployed to Preview April 8, 2025 12:15 View deployment

vercel bot deployed to Preview April 8, 2025 13:40 View deployment

octoper force-pushed the vaggelis/migrate-to-new-org-claims branch from ad5308b to 9b0506b Compare April 8, 2025 13:52

vercel bot deployed to Preview April 8, 2025 13:53 View deployment

octoper force-pushed the vaggelis/migrate-to-new-org-claims branch from 9b0506b to 07dcd05 Compare April 8, 2025 14:56

octoper added 2 commits April 9, 2025 12:11

refactor(clerk-js,shared,type): Support new claims and keep orgPermis…

00935b4

…sions on authObject backwards compatible

chore(shared,types): Move SharedSignedInAuthObjectProperties to @cler…

79c00e1

…k/types

clerk-cookie added the actions label Apr 9, 2025

octoper added 3 commits April 9, 2025 12:11

fix(shared): Add org: prefix to org role

7cc576a

fix(shared): Add org: prefix to org roles to match previous behavior

ceab9e7

chore(clerk-js): Change bundlewatch limit

9e968f8

vercel bot deployed to Preview April 9, 2025 09:12 View deployment

octoper force-pushed the vaggelis/migrate-to-new-org-claims branch from 5e9abef to 9e968f8 Compare April 9, 2025 09:12

clerk-cookie removed the actions label Apr 9, 2025

vercel bot deployed to Preview April 9, 2025 09:13 View deployment

fix(shared): Only parse permissions if o.per and o.fpm are not undefined

1b59290

vercel bot deployed to Preview April 9, 2025 09:20 View deployment

fix(shared): Only handle org claims if o is present

1937de1

vercel bot deployed to Preview April 9, 2025 09:42 View deployment

chore(backend): Use SharedSignedInAuthObjectProperties for SignedInAu…

cd352aa

…thObject

vercel bot deployed to Preview April 9, 2025 10:37 View deployment

chore(repo): Update changeset

f982c48

vercel bot deployed to Preview April 9, 2025 11:03 View deployment

panteliselef approved these changes Apr 9, 2025

View reviewed changes

packages/types/src/jwtv2.ts Outdated Show resolved Hide resolved

packages/shared/src/authorization.ts Outdated Show resolved Hide resolved

packages/clerk-js/bundlewatch.config.json Outdated Show resolved Hide resolved

chore(shared,types): Remove v from JWTPayloadBase as is not needed

5f27918

vercel bot deployed to Preview April 9, 2025 11:16 View deployment

chore(clerk-js): Change bundlewatch limit

c1cb785

vercel bot deployed to Preview April 9, 2025 11:19 View deployment

octoper merged commit 3ad3bc8 into main Apr 9, 2025
30 checks passed

octoper deleted the vaggelis/migrate-to-new-org-claims branch April 9, 2025 12:15

clerk-cookie mentioned this pull request Apr 9, 2025

ci(repo): Version packages #5563

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

octoper commented Apr 7, 2025 •

edited

Loading

changeset-bot bot commented Apr 7, 2025 •

edited

Loading

vercel bot commented Apr 7, 2025 •

edited

Loading

panteliselef Apr 7, 2025

octoper Apr 7, 2025

iagodahlem Apr 7, 2025 •

edited

Loading

octoper Apr 7, 2025 •

edited

Loading

octoper commented Apr 9, 2025

clerk-cookie commented Apr 9, 2025

octoper commented Apr 9, 2025

clerk-cookie commented Apr 9, 2025

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

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

Conversation

octoper commented Apr 7, 2025 • edited Loading

Description

Checklist

Type of change

changeset-bot bot commented Apr 7, 2025 • edited Loading

🦋 Changeset detected

vercel bot commented Apr 7, 2025 • edited Loading

panteliselef Apr 7, 2025

Choose a reason for hiding this comment

octoper Apr 7, 2025

Choose a reason for hiding this comment

iagodahlem Apr 7, 2025 • edited Loading

Choose a reason for hiding this comment

octoper Apr 7, 2025 • edited Loading

Choose a reason for hiding this comment

octoper commented Apr 9, 2025

clerk-cookie commented Apr 9, 2025

octoper commented Apr 9, 2025

clerk-cookie commented Apr 9, 2025

octoper commented Apr 7, 2025 •

edited

Loading

changeset-bot bot commented Apr 7, 2025 •

edited

Loading

vercel bot commented Apr 7, 2025 •

edited

Loading

iagodahlem Apr 7, 2025 •

edited

Loading

octoper Apr 7, 2025 •

edited

Loading