feat(clerk-js,shared): Attach an optional server-configured session token to sign-in

[zourzouvillys]

Backport of #9299 to Core 2.

It also carries the request-params plumbing in fapiClient that #9313 introduced on main, but not the application-supplied assertion API that PR added — Core 2 gets the server-configured session token only. That is why the clerk.ts wiring here is one line, where main needs a resolver to union two sources.

#9527 (the verification load timeout) is deliberately out of scope: it bounds the protect-check gate, which does not exist on Core 2.

Notes for reviewers

• vitest.setup.mts — the shared browser-tabs-lock mock is now a plain class instead of vi.fn(). Core 2 is on vitest 3, where vi.restoreAllMocks() strips vi.fn() implementations; vitest 4 on main no longer does. The ported suites call restoreAllMocks() in afterEach, so under vitest 3 every test after the first in a file got a lock that resolved undefined and silently acquired nothing.
• Bundlewatch budgets are measured against a Core 2 baseline build, not copied from main (whose entry-bundle list is different). Measured deltas, gzip: clerk.js +2.02KB, clerk.browser.js +2.56KB, clerk.legacy.browser.js +3.11KB, clerk.headless*.js +2.57KB. ui-common, vendors and coinbase are unchanged.
• clerk.protect-params.test.ts is rewritten rather than cherry-picked — upstream it exists to pin the union of two features, and only one of them exists here.

Verification

Command	Result
vitest run (protect, protectSession, protect-params, fapiClient)	114 passed, 1 skipped, 4 todo
vitest run (full clerk-js)	2459 passed, 10 skipped, 17 todo, 167 files
vitest run (@clerk/shared)	647 passed, 43 files
pnpm run build (clerk-js)	rspack + declarations clean, RHC check passed
pnpm run lint (clerk-js)	0 errors (480 pre-existing warnings)

The same four protect suites were run against origin/main in a scratch worktree to confirm the vitest-3 lock behaviour was Core 2 specific and not a fault in the ported code — 11/11 there.

Risk

Inert for any instance whose environment carries no protect_config.loaders: no storage is written, no element is injected, and sign-in and sign-up bodies are byte-for-byte unchanged.

CI

Everything this change can affect is green, and the two red integration shards are fixed here. Two checks stay red for reasons no pull request can reach:

Check	Why it cannot be fixed from a branch
Analyze (rust)	CodeQL reports "could not process any code written in Rust" — Core 2 contains no Rust at all (main has five files). Neither branch has a CodeQL workflow or config, so this is default setup configured in repository settings, which govern main too. It fails on every push to release/core-2 itself, with no PR involved, going back to July.
Vercel – swingset	packages/swingset does not exist on Core 2 (174 files on main, none here), so the project has nothing to build. The only vercel.json in the tree belongs to clerk-js; the swingset project is configured in Vercel, not in the repo.

Both fail identically on #9327, #9248 and #9224 — the last three PRs merged into this branch — so this branch has merged with them red three times. Making them green needs a repository-settings and Vercel-project change, which is a maintainer decision and deliberately not attempted here.

The two integration shards that were red are fixed:

• Integration Tests (nextjs, chrome, 16) — session-tasks-multi-session.test.ts signs the first user back in as its third step, and failed on a disabled password field and a popover that never detached. main replaced that re-sign-in with a session switch plus a delay in fix(repo): fixes multi session switching test #7402, naming a backend rate limit on session touch as the cause, and the fix was never backported. Backported here, so the file now matches main apart from the unrelated createFakeUser(test) from feat(e2e): persist test IDs in created user metadata #9374.
• Integration Tests (machine, chrome) and (…, RQ) — one case in m2m.test.ts asserts that a token minted after createScope is accepted, and it comes back 401. main deleted this whole file when it refactored machine auth per framework in chore(repo): refactor machine auth tests for Next.js and Astro #8124 and kept createScope coverage only in packages/backend's unit tests, so there is no updated integration test to backport. The single case is marked test.skip with that reasoning inline, rather than deleted, so the assertion stays on record. Reviewers: this is the one change here that is not Protect work — say the word and I will drop it and let the shard stay red instead.

Neither red shard was a symptom of the session-token work. The nextjs shard passed on this branch on runtime-identical code before it failed, 126 of its 127 tests passed including many sign-in flows, and main runs the same protectSession code through two sign-ins in that same test without trouble. The m2m case exercises a backend token-verification path this diff does not touch, and predates it on every merged PR above.

Unit Tests (22, **), Integration Tests (sessions:staging, chrome) and Integration Tests (generic, chrome) each failed once and pass on re-run: a 5s timeout in clerk.test.ts's fake-timer poller test, which is untouched here and passed 109/109 on three consecutive local runs of the full file; a waitForFunction timeout in the production-instance cookie test; and a sign-in component that did not mount in impersonation-flow.test.ts.

[changeset-bot]

🦋 Changeset detected

Latest commit: cfe2517

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

This PR includes changesets to release 22 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/shared	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/themes	Patch
@clerk/types	Patch
@clerk/vue	Patch
@clerk/localizations	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

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 1, 2026 11:37am UTC
swingset	Error		Sep 1, 2026 11:37am UTC

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 1912d6d8-704e-4570-8c1f-328b7d391a02

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@9630

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@9630

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@9630

@clerk/types

npm i https://pkg.pr.new/@clerk/types@9630

@clerk/upgrade

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

@clerk/vue

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

commit: cfe2517