fix(backend): Require configured JWT header type

[jescalan]

Summary

This changes verifyJwt / verifyToken header type validation so a missing JWT typ header is only accepted when callers have not configured headerType.

When callers explicitly pass headerType, the token must now include a typ header that matches one of the configured values. For example, headerType: 'at+jwt' now rejects a token whose JOSE header omits typ.

Root Cause

assertHeaderType returned early whenever typ was undefined, before it checked the configured allowlist. That meant an explicit headerType option could be silently skipped for typ-less tokens.

The default verifier behavior is preserved for compatibility: if headerType is omitted, a missing typ still passes.

Tests

• Added direct assertion coverage for missing typ with and without configured allowed types.
• Added verifier coverage for a token without typ when headerType: 'at+jwt' is configured.

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 13, 2026 6:51pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 85bfdad

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: 8ada79a8-6e8b-4ebd-b719-995d71c2c377

📥 Commits

Reviewing files that changed from the base of the PR and between ddc3c8d and ab16250.

📒 Files selected for processing (1)

• .changeset/tidy-chicken-bathe.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/tidy-chicken-bathe.md

---

📝 Walkthrough

Walkthrough

assertHeaderType's signature was changed to make allowedTypes optional and its early-return now occurs only when both typ and allowedTypes are undefined. When allowedTypes is provided, the function computes expectedTypes as allowedTypes ?? 'JWT', normalizes to an array, and validates typ against it, throwing TokenVerificationError for missing or unexpected typ. Tests were updated: assertions.test now checks both the no-throw case when allowedTypes is not configured and the throw case when it is; verifyJwt.test adds a case asserting verification fails with configured headerType. A changeset documents the behavior change.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: requiring a configured JWT header type when validating tokens.
Description check	✅ Passed	The description is well-related to the changeset, clearly explaining the root cause, the change behavior, tests added, and validation steps performed.
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.

_{✏️ 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.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 85bfdad