feat(clerk-js): Monotonic token replacement based on oiat

[nikosdouvlis]

Why

With Session Minter, edge-minted tokens can have fresh iat (just minted) but stale claims (copied from an old parent). In multi-tab scenarios, a background tab's stale edge token can overwrite a fresher DB-minted token in the __session cookie, causing claim regression.

The old broadcast guard compared iat, which doesn't reflect claim freshness for edge tokens.

What

Introduces oiat ?? iat as the unified claim freshness metric:

• Token with oiat (header): oiat = when claims were last read from DB
• Token without oiat: origin-minted (coupled FF), so iat = when claims were last read from DB

New shared comparator (tokenFreshness.ts) used across 4 guard points:

1. tokenCache.ts handleBroadcastMessage - replaces the old iat comparison
2. tokenCache.ts setInternal - async compare-and-swap at resolve time
3. Session.ts #dispatchTokenEvents - before token:update emit
4. AuthCookieService.ts updateSessionCookie - cookie chokepoint with session scoping

Guard 4 is the most important. It compares against the actual __session cookie value (shared state), not in-memory state. This catches the sleeping tab edge case where a tab wakes up with a stale baseline, fetches an edge token, and tries to overwrite a fresher cookie that another tab maintained.

The cookie guard scopes by sid so session switches (different oiat timelines) always pass through.

Full decision table and edge case analysis in docs/plans/session-minter-sdk-changes.md.

Stacks on #8096.

Test plan

• Broadcast: edge token with fresh iat but stale oiat is rejected
• Broadcast: tokens without oiat fall back to iat comparison
• Cache setInternal: async race, fresher resolve wins
• Session dispatch: stale token doesn't overwrite lastActiveToken
• Cookie guard: stale oiat blocked within same session
• Cookie guard: different session always allowed (session switch)
• Cookie guard: sleeping tab scenario (in-memory stale, cookie fresh)
• Cookie guard: iat fallback when oiat missing
• First mint with no existing token passes unconditionally
• Comparator: all 15 decision table rows

[changeset-bot]

🦋 Changeset detected

Latest commit: 91b664b

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

This PR includes changesets to release 21 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/shared	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	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 (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 18, 2026 1:59pm