fix(backend): Fix JWT array audience validation by jescalan · Pull Request #8470 · clerk/javascript

jescalan · 2026-05-04T19:11:28Z

Summary

This fixes JWT audience validation for tokens whose aud claim is an array.

verifyJwt now passes the raw aud claim and configured audience option into assertAudienceClaim. The assertion helper already normalizes string and string-array inputs, so this lets it evaluate array audiences correctly.

Scope

This does not mean default Clerk session tokens have an aud claim. They generally do not, and this PR does not change the existing behavior for tokens with no aud: if the token has no audience claim, verifyJwt still skips audience validation.

The bug only applies when both of these are true:

the caller configured audience
the token payload contains aud as a string array

That shape is valid JWT syntax and is already represented in this package's M2M token parsing fallback (aud?: string[]). Clerk-issued M2M tokens also allow custom claims, and aud is not reserved there. So the fix is scoped to correctly enforcing the existing audience option when an array aud is present, not to introducing audience binding for all Clerk tokens.

Root Cause

verifyJwt wrapped both values before calling the assertion:

assertAudienceClaim([aud],[audience]);

When the token already had aud as a string array, the assertion received a nested array. That shape skipped both validation branches: it was not a string, and it was not an array of strings. The function returned without enforcing the configured audience.

Tests

Added assertion coverage for two string arrays with no intersection.
Added verifier coverage using signed JWTs:
- accepts an array aud when it includes the configured audience
- rejects an array aud when it does not include the configured audience

Validation

NODE_OPTIONS=--no-experimental-webstorage pnpm --filter @clerk/backend build
pnpm --filter @clerk/backend build:runtime
NODE_OPTIONS=--no-experimental-webstorage pnpm exec vitest run src/jwt/__tests__/assertions.test.ts src/jwt/__tests__/verifyJwt.test.ts --environment node --typecheck.enabled=false
pnpm --filter @clerk/backend format:check
git diff --check

vercel · 2026-05-04T19:11:33Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 14, 2026 4:24pm

changeset-bot · 2026-05-04T19:11:37Z

🦋 Changeset detected

Latest commit: cc75a63

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

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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

coderabbitai · 2026-05-04T19:21:50Z

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

Run ID: fc3120d1-25d0-45c3-b736-8f1f47559a41

📥 Commits

Reviewing files that changed from the base of the PR and between 5c2ce3b and b1d1a8e.

📒 Files selected for processing (1)

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

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

packages/backend/src/jwt/tests/verifyJwt.test.ts

📝 Walkthrough

Walkthrough

verifyJwt now calls assertAudienceClaim(aud, audience) without wrapping values in arrays. Tests added: a unit test for assertAudienceClaim that expects an "Invalid JWT audience claim array" error when arrays do not intersect, and two verifyJwt tests that sign tokens with aud as an array — one verifies success when the configured audience is present, the other verifies failure when it is absent.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(backend): Fix JWT array audience validation' accurately and concisely describes the main change: fixing JWT audience validation when the aud claim is an array.
Description check	✅ Passed	The description comprehensively explains the fix, root cause, scope, tests added, and validation steps performed, all directly related to the JWT array audience validation changes.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

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

dominic-clerk

This could be for a follow-up but I think we could change the types in

javascript/packages/backend/src/jwt/assertions.ts

Line 10 in f2af9ba

exportconstassertAudienceClaim=(aud?: unknown,audience?: unknown)=>{

from unknown to string | string[]

Also I understand skipping verification if we have no expected audience, but it seems odd to skip it if we do expect something and the token doesn't provide any.

javascript/packages/backend/src/jwt/assertions.ts

Line 13 in f2af9ba

constshouldVerifyAudience=audienceList.length>0&&audList.length>0;

pkg-pr-new · 2026-05-13T18:53:37Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8470

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: cc75a63

wobsoriano

@dominic-clerk approving as this fixes array aud handling and adds targeted coverage.

The type cleanup and missing aud behavior question can be a follow-up, right?

dominic-clerk · 2026-05-14T08:08:25Z

@wobsoriano yes it can be a follow-up, what would be the best way to ensure it doesn't fall through cracks? A ticket in SDK team?

wobsoriano · 2026-05-14T14:45:59Z

@wobsoriano yes it can be a follow-up, what would be the best way to ensure it doesn't fall through cracks? A ticket in SDK team?

Yes, SDK team.

Created SDK-89.

fix(backend): verify array jwt audiences
f2af9ba

github-actionsBot added the backend label May 4, 2026

vercelBotdeployed to Preview May 4, 2026 19:11 View deployment

jescalan changed the title ~~[codex] Fix JWT array audience validation~~fix(backend): Fix JWT array audience validationMay 4, 2026

jescalan requested review from brkalow, dominic-clerk and jacekradko and removed request for brkalow May 4, 2026 19:18

jescalan marked this pull request as ready for review May 4, 2026 19:18

dominic-clerk reviewed May 5, 2026
View reviewed changes

Merge branch 'main' into codex/fix-verify-token-array-aud
c5a870f

vercelBotdeployed to Preview May 13, 2026 18:51 View deployment

Merge branch 'main' into codex/fix-verify-token-array-aud
9416b81

vercelBotdeployed to Preview May 13, 2026 19:07 View deployment

chore: add changeset
5c2ce3b

vercelBotdeployed to Preview May 13, 2026 19:54 View deployment

wobsoriano approved these changes May 13, 2026
View reviewed changes

chore: format
b1d1a8e

vercelBotdeployed to Preview May 14, 2026 16:17 View deployment

Merge branch 'main' into codex/fix-verify-token-array-aud
cc75a63

vercelBotdeployed to Preview May 14, 2026 16:24 View deployment

wobsoriano merged commit ee25cf2 into mainMay 14, 2026
43 checks passed

wobsoriano deleted the codex/fix-verify-token-array-aud branch May 14, 2026 16:34

clerk-cookie mentioned this pull request May 14, 2026
ci(repo): Version packages #8518
Merged

Navigation Menu

Uh oh!

fix(backend): Fix JWT array audience validation - #8470

fix(backend): Fix JWT array audience validation#8470
wobsoriano merged 6 commits into
mainfrom
codex/fix-verify-token-array-aud

jescalan commented May 4, 2026•
edited
Loading

Uh oh!

vercelBot commented May 4, 2026•
edited
Loading

Uh oh!

changeset-botBot commented May 4, 2026•
edited
Loading

Uh oh!

coderabbitaiBot commented May 4, 2026•
edited
Loading

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

dominic-clerk left a comment •
edited
Loading

Uh oh!

pkg-pr-newBot commented May 13, 2026•
edited
Loading

Uh oh!

wobsoriano left a comment

Uh oh!

dominic-clerk commented May 14, 2026

Uh oh!

wobsoriano commented May 14, 2026•
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jescalan commented May 4, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope

Root Cause

Tests

Validation

Uh oh!

vercelBot commented May 4, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-botBot commented May 4, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitaiBot commented May 4, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

dominic-clerk left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkg-pr-newBot commented May 13, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

dominic-clerk commented May 14, 2026

Uh oh!

wobsoriano commented May 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jescalan commented May 4, 2026•
edited
Loading

vercelBot commented May 4, 2026•
edited
Loading

changeset-botBot commented May 4, 2026•
edited
Loading

coderabbitaiBot commented May 4, 2026•
edited
Loading

dominic-clerk left a comment •
edited
Loading

pkg-pr-newBot commented May 13, 2026•
edited
Loading

wobsoriano commented May 14, 2026•
edited
Loading