fix(backend): Fix JWT array audience validation

[jescalan]

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]

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]

🦋 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]

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

export const assertAudienceClaim = (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

const shouldVerifyAudience = audienceList.length > 0 && audList.length > 0;

[pkg-pr-new]

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]

@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]

@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.