feat(backend): Error if azp is missing on a cookie-based token

[jescalan]

Description

If a session token is sent via cookie, this usually means it's being sent through the browser. When an app is browser-based, it's expected that requests are sent with an Origin header and session JWTs are built with an azp claim. For native apps, this isn't the case, as they don't have urls or enforce an origin header. Because of this, we don't enforce azp claims on session tokens.

This PR makes a small change, such that if session tokens are sent via cookie and are missing an azp claim, which generally is suspicious, as there's no natural scenario where this would make a lot of sense, we error instead of accepting it.

Checklist

• [ ] pnpm test runs as expected.
• [ ] pnpm build runs as expected.
• [ ] (If applicable) JSDoc comments have been added or updated for any package exports
• [ ] (If applicable) Documentation has been updated

Type of change

• [ ] 🐛 Bug fix
• [ ] 🌟 New feature
• [ ] 🔨 Breaking change
• [ ] 📖 Refactoring / dependency upgrade / documentation
• [ ] other:

Summary by CodeRabbit

• Bug Fixes
  • Strengthened token validation by enforcing required security claim verification. Session tokens missing critical claims are now properly rejected, improving authentication security and reliability.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 808c933cf13b5191a2d1d927446c3e54700ee4d2

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

[vercel[bot]]

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Dec 19, 2025 1:54pm

[coderabbitai[bot]]

Walkthrough

The changes add validation for the azp (authorized party) claim in JWT tokens. A new error reason TokenMissingAzp is introduced in the errors module, along with corresponding tests for cookie-based authentication flows. Production code now enforces the presence of azp in session tokens received via cookies.

Changes

Cohort / File(s)	Summary
Error Definition packages/backend/src/errors.ts	Added new token verification error reason TokenMissingAzp with value 'token-missing-azp' to expand the set of defined verification failure reasons.
Token Validation packages/backend/src/tokens/request.ts	Introduced enforcement check for azp claim presence in session tokens from cookies; throws TokenVerificationError with TokenMissingAzp reason if the claim is missing.
Tests packages/backend/src/tokens/__tests__/request_azp.test.ts	Added new test suite for authenticateRequest covering cookie-based token flows with azp present and absent, and header-based authentication with missing azp.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Error constant addition is straightforward and follows existing patterns
• Test file introduces multiple test cases but follows conventional mocking patterns already established in the codebase
• Production logic change is a single validation check integrated into existing error handling flow

Poem

🐰 The azp must present be, In tokens flowing wild and free, A guardian check, so swift and keen, Now validates what's never seen! No missing party shall slip through, Our JWT vault is safe and true! 🔐

Pre-merge checks and finishing touches

❌ 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%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Error if azp is missing on a cookie-based token' directly and clearly describes the main change: enforcing azp claim presence for cookie-based tokens and throwing an error when it's absent.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch je.error-on-missing-azp-in-cookie

---

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

[pkg-pr-new[bot]]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7332

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 808c933

[brkalow]

This would be a breaking change