fix(shared): decode JWT v2 permission masks exactly by jeremy-clerk · Pull Request #9381 · clerk/javascript

jeremy-clerk · 2026-08-10T20:01:13Z

Description

JWT v2 organization permission masks were parsed through JavaScript numbers, which could lose precision above the safe integer limit and cause auth().has() to incorrectly grant or deny permissions.

Decode permission masks directly from their decimal strings with decimalToBinaryBits. This avoids relying on BigInt, which may be incompatible with ClerkJS's legacy browser bundle, while preserving the existing bit ordering for normal masks. Malformed and negative masks now fail closed.

Type of change

changeset-bot · 2026-08-10T20:01:19Z

🦋 Changeset detected

Latest commit: 9dd9f76

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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 · 2026-08-10T20:01:20Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 10, 2026 8:11pm
swingset	Ready	Preview	Aug 10, 2026 8:11pm

pkg-pr-new · 2026-08-10T20:04:28Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9381

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9381

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9381

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9381

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9381

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9381

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9381

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9381

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9381

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9381

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9381

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9381

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9381

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9381

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9381

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9381

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9381

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9381

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9381

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9381

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9381

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9381

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9381

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9381

commit: 9dd9f76

coderabbitai · 2026-08-10T20:05:12Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 9fe110e6-d198-48b6-9ca7-82430f245265

📥 Commits

Reviewing files that changed from the base of the PR and between c83fe31 and 9dd9f76.

📒 Files selected for processing (2)

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

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/cli (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)

🚧 Files skipped from review as they are similar to previous changes (2)

packages/shared/src/tests/jwtPayloadParser.spec.ts
packages/shared/src/jwtPayloadParser.ts

📝 Walkthrough

Walkthrough

The JWT payload parser now converts decimal permission masks through custom decimal division. This avoids precision loss for values beyond JavaScript’s safe integer range. Invalid masks produce empty bit arrays. Tests cover large masks, valid safe masks, out-of-range bits, malformed masks, and fail-closed authorization checks. A patch changeset was added for @clerk/shared.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the exact JWT v2 permission-mask decoding fix.
Description check	✅ Passed	The description explains the precision issue, decoding approach, compatibility consideration, and fail-closed behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/shared/src/jwtPayloadParser.ts`:
- Around line 52-54: Update buildOrgPermissions and the featurePermissionMap
handling around decimalToBinaryBits so bit indexes greater than or equal to
permissions.length are discarded before permission names are resolved. Preserve
valid permission mappings and add a regression test covering the 54-item list
with mask 18014398509481984, ensuring no org:feature:undefined permission is
produced.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 1868a535-5352-4646-8435-325176767171

📥 Commits

Reviewing files that changed from the base of the PR and between aa86d9f and c83fe31.

📒 Files selected for processing (3)

.changeset/exact-jwt-permission-masks.md
packages/shared/src/__tests__/jwtPayloadParser.spec.ts
packages/shared/src/jwtPayloadParser.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/cli (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)

github-actions · 2026-08-10T20:05:37Z

API Changes Report

Generated by Break Check on 2026-08-10T20:12:53.862Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 9dd9f76.}

fix(shared): preserve JWT permission mask precision

c83fe31

vercel Bot deployed to Preview – clerk-js-sandbox August 10, 2026 20:02 View deployment

vercel Bot deployed to Preview – swingset August 10, 2026 20:03 View deployment

coderabbitai Bot reviewed Aug 10, 2026

View reviewed changes

Comment thread packages/shared/src/jwtPayloadParser.ts

fix(shared): ignore undeclared permission bits

9dd9f76

vercel Bot deployed to Preview – clerk-js-sandbox August 10, 2026 20:09 View deployment

vercel Bot deployed to Preview – swingset August 10, 2026 20:11 View deployment

Navigation Menu

Uh oh!

fix(shared): decode JWT v2 permission masks exactly - #9381

fix(shared): decode JWT v2 permission masks exactly#9381
jeremy-clerk wants to merge 2 commits into
mainfrom
jw/fix-has-bitmask-check

jeremy-clerk commented Aug 10, 2026

Uh oh!

changeset-bot Bot commented Aug 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 10, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 10, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 10, 2026 •

edited

Loading

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Aug 10, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

jeremy-clerk commented Aug 10, 2026

Description

Type of change

Uh oh!

changeset-bot Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-bot Bot commented Aug 10, 2026 •

edited

Loading

vercel Bot commented Aug 10, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 10, 2026 •

edited

Loading

coderabbitai Bot commented Aug 10, 2026 •

edited

Loading

github-actions Bot commented Aug 10, 2026 •

edited

Loading