chore(fastify): Use runtime keys for auth client and explicit opt-out handshake option by jescalan · Pull Request #8560 · clerk/javascript

jescalan · 2026-05-15T15:38:18Z

Summary

create server-side auth clients from resolved runtime middleware options before calling authenticateRequest
cover Fastify, Express, Astro, Nuxt, React Router, and TanStack Start so nonce handshake payload exchange can use keys passed directly to framework middleware
add focused regression coverage for runtime key propagation into client construction

Context

Forced handshake nonce transport stores a short __clerk_handshake_nonce instead of the large __clerk_handshake payload. Server SDKs then need to exchange that nonce through the Backend API client attached to authenticateRequest.

Several framework wrappers passed runtime secretKey/publishableKey into authenticateRequest, but constructed the request client from environment defaults or earlier unresolved options. That means apps loading keys asynchronously and passing them into middleware could authenticate some paths with the runtime key while nonce payload exchange still used a client created without that key.

Hono and Next.js already build the client from runtime options, so no patch was needed there.

Performance

This patch avoids adding a new per-request client construction path in the common static-key cases:

Fastify creates the Clerk client once when clerkPlugin() registers middleware.
Express creates the default client once when clerkMiddleware() is created for static options. The callback form can still create a middleware/client per request, but that was already how callback options worked.
Astro, Nuxt, React Router, and TanStack Start already created the server Clerk client inside the request path before this PR. This patch passes the resolved options into that existing construction instead of introducing another client creation.
createClerkClient() itself does not perform network I/O; it builds the Backend API resource client, authenticateRequest closure, and telemetry collector. The nonce exchange network call only happens when authenticateRequest reaches forced handshake nonce handling.

Testing

pnpm -C packages/fastify exec vitest run src/__tests__/withClerkMiddleware.test.ts
pnpm -C packages/express exec vitest run src/__tests__/clerkMiddleware.test.ts -t "builds a per-middleware ClerkClient with runtime keys"
pnpm -C packages/react-router exec vitest run src/server/__tests__/clerkMiddleware.test.ts
pnpm -C packages/nuxt exec vitest run src/runtime/server/__tests__/clerkClient.test.ts
pnpm -C packages/astro exec vitest run src/server/__tests__/clerk-client.test.ts
pnpm -C packages/tanstack-react-start exec vitest run src/server/__tests__/clerkClient.test.ts
pnpm -C packages/fastify build
pnpm -C packages/express build
pnpm -C packages/fastify lint (passes with existing no-misused-promises warnings)
pnpm -C packages/express lint (passes with existing no-misused-promises warnings)
pnpm -C packages/astro lint (passes with existing warnings)
git diff --check

Notes

Full Express middleware tests currently hit the local backend/shared export mismatch: getAutoProxyUrlFromEnvironment is not a function.
React Router, Nuxt, Astro, and TanStack builds/lints still hit existing local package-linkage/DTS issues unrelated to this patch (missing local @clerk/react/@clerk/vue exports or declarations). Their JS builds reached the compile stage before those existing declaration/linkage failures.

vercel · 2026-05-15T15:38:24Z

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		May 22, 2026 5:50pm

changeset-bot · 2026-05-15T15:38:24Z

🦋 Changeset detected

Latest commit: 8f24d90

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

This PR includes changesets to release 1 package

Name	Type
@clerk/fastify	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

jescalan · 2026-05-15T15:44:25Z

!snapshot

jeremy-clerk

LGTM

coderabbitai · 2026-05-15T15:47:00Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

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: 31c8429d-b4ad-41f2-96a2-b258683f9b11

📥 Commits

Reviewing files that changed from the base of the PR and between fda2de6 and 8f24d90.

📒 Files selected for processing (2)

packages/fastify/src/__tests__/withClerkMiddleware.test.ts
packages/fastify/src/withClerkMiddleware.ts

📝 Walkthrough

Walkthrough

This PR initializes a single Clerk client at middleware setup using resolved runtime keys, adds an optional enableHandshake flag to control handshake/redirect handling, strips handshake cookies/query params when disabled, and attaches the Clerk client to requests as request.clerk. Type declarations and the plugin decoration are updated accordingly, and tests were added to verify runtime key usage, enableHandshake behavior, handshake cookie stripping, and request.clerk exposure.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 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 accurately describes the main changes: implementing runtime key usage for auth client initialization and adding an explicit handshake opt-out option to Fastify.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the problem context, solution, performance implications, testing, and notes about related packages.
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.}

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

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

pkg-pr-new · 2026-05-15T15:48:58Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 8f24d90

wobsoriano · 2026-05-15T21:17:00Z

@copilot can you add changes from #8563 to this PR?

…quest options Agent-Logs-Url: https://github.com/clerk/javascript/sessions/facfca5a-129e-4332-97a6-caa1efbb40cd

Copilot · 2026-05-15T21:23:28Z

@copilot can you add changes from #8563 to this PR?

Done — I pulled in the changes from #8563 in commits 19f3473, 0cc1e3c, and 60312d1, and added a follow-up fix for the React Router CI type error in 9243a0a.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

download.cypress.io
- Triggering command: /usr/local/bin/node node index.js --exec install (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

jorgevrgs · 2026-05-16T12:40:28Z

It looks like enableHandshake: false doesn't prevent the API to request GET /v1/client/handshake always if the cookies __clerk_handshake and/or __clerk_handshake_nonce exist. That causes a noisy log:

ERROR Clerk: HandshakeService: error getting handshake payload: ClerkAPIResponseError: Not Found
  at ClientAPI.request (.../@clerk/backend/src/api/request.ts:278:21)
  at async HandshakeService.getCookiesFromHandshake (.../@clerk/backend/src/tokens/handshake.ts:187:34)
  at async HandshakeService.resolveHandshake (.../@clerk/backend/src/tokens/handshake.ts:220:26)
  at async authenticateRequestWithTokenInCookie (.../@clerk/backend/src/tokens/request.ts:457:16)
  at async Object.<anonymous> (.../@clerk/fastify/src/withClerkMiddleware.ts:88:26)

Quick solution: strip/ignore cookies/queries when the config is enableHandshake: false.

wobsoriano · 2026-05-16T13:47:25Z

!snapshot

wobsoriano · 2026-05-16T13:55:03Z

@jorgevrgs thanks, generated another snapshot for you

npm i @clerk/fastify@3.1.28-snapshot.v20260516134813 --save-exact

wobsoriano · 2026-05-22T17:55:05Z

!snapshot

github-actions · 2026-05-22T17:57:59Z

Hey @wobsoriano - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	3.2.5-snapshot.v20260522175603
@clerk/backend	3.4.10-snapshot.v20260522175603
@clerk/chrome-extension	3.1.27-snapshot.v20260522175603
@clerk/clerk-js	6.11.2-snapshot.v20260522175603
@clerk/dev-cli	0.1.1-snapshot.v20260522175603
@clerk/expo	3.2.13-snapshot.v20260522175603
@clerk/expo-passkeys	1.0.26-snapshot.v20260522175603
@clerk/express	2.1.18-snapshot.v20260522175603
@clerk/fastify	3.1.28-snapshot.v20260522175603
@clerk/hono	0.1.28-snapshot.v20260522175603
@clerk/localizations	4.6.5-snapshot.v20260522175603
@clerk/msw	0.0.26-snapshot.v20260522175603
@clerk/nextjs	7.3.6-snapshot.v20260522175603
@clerk/nuxt	2.4.5-snapshot.v20260522175603
@clerk/react	6.6.5-snapshot.v20260522175603
@clerk/react-router	3.2.6-snapshot.v20260522175603
@clerk/shared	4.12.1-snapshot.v20260522175603
@clerk/tanstack-react-start	1.2.6-snapshot.v20260522175603
@clerk/testing	2.0.30-snapshot.v20260522175603
@clerk/ui	1.11.1-snapshot.v20260522175603
@clerk/upgrade	2.0.3-snapshot.v20260522175603
@clerk/vue	2.2.5-snapshot.v20260522175603

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@3.2.5-snapshot.v20260522175603 --save-exact

@clerk/backend

npm i @clerk/backend@3.4.10-snapshot.v20260522175603 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.27-snapshot.v20260522175603 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.11.2-snapshot.v20260522175603 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@0.1.1-snapshot.v20260522175603 --save-exact

@clerk/expo

npm i @clerk/expo@3.2.13-snapshot.v20260522175603 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.26-snapshot.v20260522175603 --save-exact

@clerk/express

npm i @clerk/express@2.1.18-snapshot.v20260522175603 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.28-snapshot.v20260522175603 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.28-snapshot.v20260522175603 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.6.5-snapshot.v20260522175603 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.26-snapshot.v20260522175603 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.3.6-snapshot.v20260522175603 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.4.5-snapshot.v20260522175603 --save-exact

@clerk/react

npm i @clerk/react@6.6.5-snapshot.v20260522175603 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.2.6-snapshot.v20260522175603 --save-exact

@clerk/shared

npm i @clerk/shared@4.12.1-snapshot.v20260522175603 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.2.6-snapshot.v20260522175603 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.30-snapshot.v20260522175603 --save-exact

@clerk/ui

npm i @clerk/ui@1.11.1-snapshot.v20260522175603 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.3-snapshot.v20260522175603 --save-exact

@clerk/vue

npm i @clerk/vue@2.2.5-snapshot.v20260522175603 --save-exact

vercel Bot deployed to Preview May 15, 2026 15:38 View deployment

github-actions Bot added the fastify label May 15, 2026

jescalan changed the title ~~[codex] fix(fastify): use runtime keys for auth client~~ fix(fastify): use runtime keys for auth client May 15, 2026

jescalan marked this pull request as ready for review May 15, 2026 15:44

jescalan requested a review from jeremy-clerk May 15, 2026 15:44

jeremy-clerk approved these changes May 15, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

fix(fastify): use runtime keys for auth client

25efe99

jescalan force-pushed the fix/fastify-runtime-secret-handshake branch from 71d3ff7 to 25efe99 Compare May 15, 2026 15:58

github-actions Bot added express tanstack astro react-router nuxt labels May 15, 2026

jescalan changed the title ~~fix(fastify): use runtime keys for auth client~~ [codex] fix framework runtime keys for nonce handshakes May 15, 2026

jescalan marked this pull request as draft May 15, 2026 15:59

vercel Bot deployed to Preview May 15, 2026 15:59 View deployment

Copilot started work on behalf of wobsoriano May 15, 2026 21:17 View session

wobsoriano and others added 4 commits May 15, 2026 21:20

feat(fastify): Add enableHandshake option to plugin

19f3473

add test

0cc1e3c

add changeset

60312d1

fix(react-router): avoid proxy/domain type conflict in authenticateRe…

9243a0a

…quest options Agent-Logs-Url: https://github.com/clerk/javascript/sessions/facfca5a-129e-4332-97a6-caa1efbb40cd

vercel Bot deployed to Preview May 15, 2026 21:23 View deployment

Delete .changeset/sixty-lobsters-jump.md

189a897

vercel Bot deployed to Preview May 16, 2026 00:00 View deployment

chore: update changeset

99b1219

vercel Bot deployed to Preview May 16, 2026 00:02 View deployment

chore: remove as any

e5f9ebc

vercel Bot temporarily deployed to Preview May 16, 2026 00:02 Inactive

Merge branch 'main' into fix/fastify-runtime-secret-handshake

6fa13fb

vercel Bot deployed to Preview May 16, 2026 00:03 View deployment

chore: revert

a4ef868

vercel Bot temporarily deployed to Preview May 16, 2026 00:07 Inactive

wobsoriano marked this pull request as ready for review May 16, 2026 00:14

chore: stripe cookies when enableHandshake is false

54ed74d

vercel Bot temporarily deployed to Preview May 16, 2026 13:42 Inactive

Merge branch 'main' into fix/fastify-runtime-secret-handshake

fda2de6

vercel Bot deployed to Preview May 16, 2026 13:43 View deployment

wobsoriano removed express tanstack astro react-router nuxt labels May 16, 2026

This comment has been minimized.

Sign in to view

wobsoriano changed the title ~~chore(fastify): Use runtime keys for auth client and add enableHandshake option~~ chore(fastify): Use runtime keys for auth client and explicit opt-out handshake option May 16, 2026

wobsoriano added the do not merge label May 20, 2026

smarter enableHandshake

8f24d90

vercel Bot temporarily deployed to Preview May 22, 2026 17:50 Inactive

Conversation

jescalan commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Context

Performance

Testing

Notes

Uh oh!

vercel Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

jescalan commented May 15, 2026

Uh oh!

jeremy-clerk left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Review ran into problems

Uh oh!

This comment has been minimized.

pkg-pr-new Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wobsoriano commented May 15, 2026

Uh oh!

Copilot AI commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

jorgevrgs commented May 16, 2026

Uh oh!

wobsoriano commented May 16, 2026

Uh oh!

This comment has been minimized.

wobsoriano commented May 16, 2026

Uh oh!

wobsoriano commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jescalan commented May 15, 2026 •

edited

Loading

vercel Bot commented May 15, 2026 •

edited

Loading

changeset-bot Bot commented May 15, 2026 •

edited

Loading

coderabbitai Bot commented May 15, 2026 •

edited

Loading

pkg-pr-new Bot commented May 15, 2026 •

edited

Loading

Copilot AI commented May 15, 2026 •

edited

Loading