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 4, 2026 7:11pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: ddc3c8d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a 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: cd9a46bc-d2b2-4868-a2bb-992a6b3bd9c6

📥 Commits

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

📒 Files selected for processing (3)

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

---

📝 Walkthrough

Walkthrough

The JWT header type validation logic has been modified in the assertHeaderType function and its corresponding tests. The function signature changed from defaulting allowedTypes to 'JWT' to making it optional. The validation behavior now differs: previously, when the JWT typ header was missing, no error was thrown regardless of configuration. Now, validation throws an error when typ is missing but allowedTypes is explicitly provided. The early-return condition was modified to only return without validation when both typ and allowedTypes are undefined. Test coverage was updated to verify both the new error-throwing behavior and the passing case when allowedTypes is not configured.

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 'fix(backend): Require configured JWT header type' accurately summarizes the main change—enforcing that configured JWT header types must be present in tokens.
Description check	✅ Passed	The description clearly explains the change, its root cause, affected functions, test coverage, and validation steps—all directly related to the JWT header type validation updates.
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.}

---

_{Review rate limit: 4/5 reviews remaining, refill in 12 minutes.}

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