feat(clerk-js,shared): Backport Session Minter SDK changes to core-2

[nikosdouvlis]

Why

Session Minter (edge token minting) shipped to clerk-js on main between March and May 2026 across five small PRs. Until now, only the touch-intent change (#8135) was backported to release/core-2. The other five SDK changes have to land on core-2 too so v5 consumers can opt into edge-minted tokens once their instance flag is flipped on.

This is a behavior-preserving backport: every code path is gated behind auth_config.session_minter, which defaults to false. With the gate off, clerk-js v5 sends the same /tokens request body and runs the same retry path it does today.

What changed

Five upstream PRs ported, one per commit:

• #8107 - add optional oiat field to JwtHeader
• #8097 - monotonic cross-tab token replacement via pickFreshestJwt, so a stale edge-minted broadcast cannot clobber a fresher cached token
• #8105 - send the previous session token in the /tokens POST body when auth_config.session_minter is true
• #8108 - skip the missing_expired_token retry when Session Minter is enabled (the token is now in the body, so the retry-with-expired-token fallback is unnecessary). Legacy retry preserved when the flag is off.
• #8106 - send forceOrigin=true in the body when skipCache is true, so FAPI routes to origin instead of the Session Minter edge

A sixth commit cleans up a review-pass finding: rather than introduce a new __internal_environment getter on Clerk (which exists on main but not on core-2), the code now reads the existing __unstable__environment getter that has been on core-2 since v3. Same commit also backports the Session test coverage from #8105 and #8106 that wasn't worth porting until the env-getter question was settled.

Packages affected

• @clerk/clerk-js: AuthConfig gains a sessionMinter field, Session sends the new body fields when the flag is on, tokenCache compares broadcast tokens with pickFreshestJwt. All behavior is gated.
• @clerk/shared: AuthConfigResource.sessionMinter, AuthConfigJSON.session_minter?, JwtHeader.oiat?. All additive.

Test plan

• pnpm vitest run src/core in clerk-js: 380/380 pass
• pnpm test in shared: 641/641 pass
• New unit tests in tokenFreshness.test.ts cover the broadcast-side guard's edge cases (legacy tokens, equal oiat, tie-break)
• New Session.test.ts blocks assert the /tokens body shape for both sessionMinter: true and sessionMinter: false
• Manual: smoke test in a v5 host app against a staging instance with the flag on

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 26, 2026 2:06pm

[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: Pro

Run ID: ae76f5f0-3dce-48f5-b972-30695445e273

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch nikos/port-minter-to-core-2

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

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

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

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

@clerk/types

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

@clerk/upgrade

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

@clerk/vue

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

commit: ccff619

[nikosdouvlis]

The two failing checks (Integration Tests (machine, chrome) and Integration Tests (machine, chrome, RQ)) are pre-existing on release/core-2, not introduced by this PR.

#8633, the most recently merged PR against release/core-2 (a pure CI version-bump with no code changes), has the same two failures. The earlier PRs #8321, #8310, #8239 all had these checks passing, so the M2M test regressed somewhere between then and now.

The failure is m2m.test.ts:139 "authorizes M2M requests when sender machine has proper access to receiver machine" - it sends an M2M bearer token to a protected endpoint and expects 200, but gets 401. M2M tokens are a separate auth flow from user session tokens; nothing in this port touches the M2M code path.

Static analysis (including bundlewatch) is now green after I bumped the clerk.headless*.js limit from 67 KB to 68 KB.