chore(fastify): Use runtime keys for auth client and add enableHandshake 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 16, 2026 0:07am

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

🦋 Changeset detected

Latest commit: a4ef868

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

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: ea53f82d-b1d1-48a3-8579-1dc3710f1000

📥 Commits

Reviewing files that changed from the base of the PR and between 25efe99 and a4ef868.

📒 Files selected for processing (5)

.changeset/silent-fastify-handshakes.md
packages/fastify/src/__tests__/withClerkMiddleware.test.ts
packages/fastify/src/clerkPlugin.ts
packages/fastify/src/types.ts
packages/fastify/src/withClerkMiddleware.ts

📝 Walkthrough

Walkthrough

This PR refactors @clerk/fastify to move Clerk client initialization from per-request to middleware setup time, enabling runtime-provided secrets to be properly threaded through session verification. The middleware now accepts an optional enableHandshake flag to control redirect behavior, and exposes the client instance on request.clerk. Type definitions are updated to reflect the new enableHandshake option and clerk property, plugin decoration wires up the property, and tests verify runtime key forwarding and the new conditional behaviors.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 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 reflects the main changes: moving to runtime keys for the auth client and adding the enableHandshake option to Fastify.
Description check	✅ Passed	The description is directly related to the changeset, explaining the fix for runtime key propagation into client construction across multiple framework 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.}

_{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: a4ef868

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)

wobsoriano · 2026-05-15T22:21:51Z

!snapshot

wobsoriano · 2026-05-15T23:21:08Z

!snapshot

…st.clerk

wobsoriano · 2026-05-15T23:38:03Z

!snapshot

github-actions · 2026-05-15T23:40:43Z

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

Package	Version
@clerk/astro	3.2.4-snapshot.v20260515233846
@clerk/backend	3.4.9-snapshot.v20260515233846
@clerk/chrome-extension	3.1.26-snapshot.v20260515233846
@clerk/clerk-js	6.11.1-snapshot.v20260515233846
@clerk/dev-cli	0.1.1-snapshot.v20260515233846
@clerk/expo	3.2.12-snapshot.v20260515233846
@clerk/expo-passkeys	1.0.25-snapshot.v20260515233846
@clerk/express	2.1.17-snapshot.v20260515233846
@clerk/fastify	3.1.27-snapshot.v20260515233846
@clerk/hono	0.1.27-snapshot.v20260515233846
@clerk/localizations	4.6.4-snapshot.v20260515233846
@clerk/msw	0.0.25-snapshot.v20260515233846
@clerk/nextjs	7.3.5-snapshot.v20260515233846
@clerk/nuxt	2.4.4-snapshot.v20260515233846
@clerk/react	6.6.4-snapshot.v20260515233846
@clerk/react-router	3.2.5-snapshot.v20260515233846
@clerk/shared	4.12.0-snapshot.v20260515233846
@clerk/tanstack-react-start	1.2.5-snapshot.v20260515233846
@clerk/testing	2.0.29-snapshot.v20260515233846
@clerk/ui	1.11.0-snapshot.v20260515233846
@clerk/upgrade	2.0.3-snapshot.v20260515233846
@clerk/vue	2.2.4-snapshot.v20260515233846

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

npm i @clerk/astro@3.2.4-snapshot.v20260515233846 --save-exact

@clerk/backend

npm i @clerk/backend@3.4.9-snapshot.v20260515233846 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.26-snapshot.v20260515233846 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.11.1-snapshot.v20260515233846 --save-exact

@clerk/dev-cli

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

@clerk/expo

npm i @clerk/expo@3.2.12-snapshot.v20260515233846 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.25-snapshot.v20260515233846 --save-exact

@clerk/express

npm i @clerk/express@2.1.17-snapshot.v20260515233846 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.27-snapshot.v20260515233846 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.27-snapshot.v20260515233846 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.6.4-snapshot.v20260515233846 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.25-snapshot.v20260515233846 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.3.5-snapshot.v20260515233846 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.4.4-snapshot.v20260515233846 --save-exact

@clerk/react

npm i @clerk/react@6.6.4-snapshot.v20260515233846 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.2.5-snapshot.v20260515233846 --save-exact

@clerk/shared

npm i @clerk/shared@4.12.0-snapshot.v20260515233846 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.2.5-snapshot.v20260515233846 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.29-snapshot.v20260515233846 --save-exact

@clerk/ui

npm i @clerk/ui@1.11.0-snapshot.v20260515233846 --save-exact

@clerk/upgrade

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

@clerk/vue

npm i @clerk/vue@2.2.4-snapshot.v20260515233846 --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

Copilot finished work on behalf of wobsoriano May 15, 2026 21:24

Copilot AI requested a review from wobsoriano May 15, 2026 21:24

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

73e523b

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

chore: remove react-router changes

a79f786

vercel Bot temporarily deployed to Preview May 15, 2026 23:12 Inactive

chore(fastify): clean up branch to fastify-only changes, expose reque…

c6ba26e

…st.clerk

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

wobsoriano changed the title ~~[codex] fix framework runtime keys for nonce handshakes~~ chore(fastify): Use runtime keys for auth client and add enableHandshake option May 15, 2026

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

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!

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

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!

wobsoriano commented May 15, 2026

Uh oh!

wobsoriano commented May 15, 2026

Uh oh!

wobsoriano commented May 15, 2026

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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