feat(backend): signal support for handshake nonce

[jacekradko]

Description

Send query string param to signal support for handshake nonce flow from current version of @clerk/backend

Related: SDKI-979

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:

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 13, 2025 6:00pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 4c521d9

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

This PR includes changesets to release 11 packages

Name	Type
@clerk/backend	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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

[Copilot]

Pull Request Overview

This PR adds support for signaling the handshake nonce flow by including a query parameter.

• In handshake.ts, the query parameter SupportsHandshakeNonce is appended to the URL.
• In handshake.test.ts, corresponding tests ensure the parameter is correctly set in both regular and development modes.
• In constants.ts, a new constant for SupportsHandshakeNonce is added to support the new query parameter.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
packages/backend/src/tokens/handshake.ts	Appends a new query parameter for handshake nonce support.
packages/backend/src/tokens/tests/handshake.test.ts	Adds tests to validate the presence of the new query parameter.
packages/backend/src/constants.ts	Introduces the SupportsHandshakeNonce constant to hold the parameter key.

[jfoshee]

LGTM. So to be doubly clear: this indicates "nonce support", but FAPI still has the option to return 'optimized' payload in initial response, right?
I'll work on API definition update and FAPI implementation.

[jacekradko]

@jfoshee Yeah, this is just to signal to the API that it COULD send a handshake nonce