chore(express): Remove deprecated enableHandshake option and req.auth property access

[wobsoriano]

Description

This PR removes deprecated enabledHandshake option and direct req.auth property access.

Resolves USER-4803

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

• Breaking Changes

  • Removed the deprecated handshake option from middleware — update middleware calls accordingly.
  • Direct access to request auth as an object was removed; retrieve authentication via the getAuth-style call.

• Refactor

  • Simplified authentication flow and removed legacy handshake/compatibility pathway.

• Tests

  • Removed obsolete tests covering the deprecated auth/handshake behavior.

• Documentation

  • Updated upgrade notes documenting the removal and migration examples.

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		Feb 25, 2026 8:06pm

[changeset-bot]

🦋 Changeset detected

Latest commit: d709f7b

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

This PR includes changesets to release 1 package

Name	Type
@clerk/express	Major

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

[wobsoriano]

!allow-major

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: d709f7b

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 2e6da64 and d709f7b.

📒 Files selected for processing (1)

• packages/upgrade/src/versions/core-3/changes/express-deprecated-removed.md

---

📝 Walkthrough

Walkthrough

This PR removes the deprecated enableHandshake option from the Clerk Express middleware and deletes the legacy handshake flow. It replaces direct access to req.auth with getAuth(req), updates Express.Request.auth to a function signature, removes enableHandshake from ClerkMiddlewareOptions, and deletes tests/routes relying on the legacy API.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically describes the main changes: removal of the deprecated enableHandshake option and req.auth property access from the Express middleware, which aligns with all major file changes across the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

[jacekradko]

Let's add a change file here for this breaking change: https://github.com/clerk/javascript/tree/main/packages/upgrade/src/versions/core-3/changes

[wobsoriano]

Let's add a change file here for this breaking change: https://github.com/clerk/javascript/tree/main/packages/upgrade/src/versions/core-3/changes

updated! thanks