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

Prevent multi-tab race conditions where an edge-minted token with
stale claims overwrites a fresher DB-minted token.

Uses `oiat ?? iat` as the claim freshness metric. A token with oiat
(JWT header) uses oiat as its claim freshness. A token without oiat
is origin-minted (coupled FF), so iat represents claim freshness.

Four guard points:
1. tokenCache handleBroadcastMessage - replaces old iat comparison
2. tokenCache setInternal - async compare-and-swap at resolve time
3. Session #dispatchTokenEvents - before token:update emit
4. AuthCookieService updateSessionCookie - cookie chokepoint with
   session scoping (different sessions always allowed through)

Guard 4 catches the sleeping tab edge case where in-memory guards
pass (stale baseline) but the cookie has a fresher value from
another tab.

Author: nikosdouvlis

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -13,7 +13,9 @@ import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
 import { debugLogger } from '@/utils/debug';
+import { decode } from '@/utils/jwt';
 
+import { claimFreshness } from '../tokenFreshness';
 import { clerkMissingDevBrowser } from '../errors';
 import { eventBus, events } from '../events';
 import type { FapiClient } from '../fapiClient';
@@ -194,6 +196,29 @@ export class AuthCookieService {
       return;
     }
 
+    // Monotonic freshness guard: don't regress the cookie within the same session
+    if (token) {
+      const currentRaw = this.sessionCookie.get();
+      if (currentRaw) {
+        try {
+          const current = decode(currentRaw);
+          const incoming = decode(token);
+          const currentSid = current.claims.sid;
+          const incomingSid = incoming.claims.sid;
+          // Only apply within the same session. Different sessions always allowed.
+          if (currentSid && incomingSid && currentSid === incomingSid) {
+            const currentFresh = claimFreshness(current);
+            const incomingFresh = claimFreshness(incoming);
+            if (currentFresh != null && incomingFresh != null && currentFresh > incomingFresh) {
+              return;
+            }
+          }
+        } catch {
+          // If decode fails, allow the write (don't block on malformed tokens)
+        }
+      }
+    }
+
     if (!token && !isValidBrowserOnline()) {
       debugLogger.warn('Removing session cookie (offline)', { sessionId: this.clerk.session?.id }, 'authCookieService');
     }

packages/clerk-js/src/core/resources/Session.ts

@@ -41,6 +41,7 @@ import type {
 } from '@clerk/shared/types';
 import { isWebAuthnSupported as isWebAuthnSupportedOnWindow } from '@clerk/shared/webauthn';
 
+import { shouldRejectToken } from '@/core/tokenFreshness';
 import { unixEpochToDate } from '@/utils/date';
 import { debugLogger } from '@/utils/debug';
 import { TokenId } from '@/utils/tokenId';
@@ -513,6 +514,12 @@ export class Session extends BaseResource implements SessionResource {
       return;
     }
 
+    if (this.lastActiveToken) {
+      if (shouldRejectToken(this.lastActiveToken, token)) {
+        return;
+      }
+    }
+
     eventBus.emit(events.TokenUpdate, { token });
 
     if (token.jwt) {

packages/clerk-js/src/core/tokenCache.ts

@@ -5,6 +5,7 @@ import { TokenId } from '@/utils/tokenId';
 
 import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
 import { Token } from './resources/internal';
+import { shouldRejectToken } from './tokenFreshness';
 
 /**
  * Identifies a cached token entry by tokenId and optional audience.
@@ -288,11 +289,10 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
       const result = get({ tokenId: data.tokenId });
       if (result) {
         const existingToken = await result.entry.tokenResolver;
-        const existingIat = existingToken.jwt?.claims?.iat;
-        if (existingIat && existingIat >= iat) {
+        if (shouldRejectToken(existingToken, token)) {
           debugLogger.debug(
-            'Ignoring older token broadcast',
-            { existingIat, incomingIat: iat, tabId, tokenId: data.tokenId, traceId: data.traceId },
+            'Ignoring staler token broadcast',
+            { tokenId: data.tokenId, traceId: data.traceId },
             'tokenCache',
           );
           return;
@@ -369,6 +369,15 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 
     entry.tokenResolver
       .then(newToken => {
+        // Compare-and-swap: if another concurrent resolve already committed
+        // a fresher token for this key, don't overwrite it.
+        const currentValue = cache.get(key);
+        if (currentValue?.entry?.resolvedToken && newToken) {
+          if (shouldRejectToken(currentValue.entry.resolvedToken, newToken)) {
+            return;
+          }
+        }
+
         // Store resolved token for synchronous reads
         entry.resolvedToken = newToken;
 

packages/clerk-js/src/core/tokenFreshness.ts

@@ -0,0 +1,61 @@
+import type { JWT, TokenResource } from '@clerk/shared/types';
+
+/**
+ * Returns the claim freshness of a token or raw JWT.
+ *
+ * - If the token has `oiat` (JWT header): that's when claims were last assembled from the DB.
+ *   Edge re-mints copy this value forward, so iat can be recent while oiat is old.
+ * - If the token has no `oiat`: it's origin-minted (coupled FF means no Session Minter),
+ *   so iat IS when claims were last read from the DB.
+ *
+ * @internal
+ */
+export function claimFreshness(input: TokenResource | JWT | undefined | null): number | undefined {
+  if (!input) {
+    return undefined;
+  }
+  // TokenResource has .jwt wrapping the JWT; raw JWT has .header directly
+  const jwt = 'getRawString' in input ? input.jwt : input;
+  return jwt?.header?.oiat ?? jwt?.claims?.iat;
+}
+
+/**
+ * Determines whether an incoming token should be rejected in favor of the existing one.
+ * Returns true if the incoming token is staler than the existing one.
+ *
+ * @internal
+ */
+export function shouldRejectToken(existing: TokenResource, incoming: TokenResource): boolean {
+  const existingFreshness = claimFreshness(existing);
+  const incomingFreshness = claimFreshness(incoming);
+
+  // Can't determine freshness: accept incoming as safe default
+  if (existingFreshness == null || incomingFreshness == null) {
+    return false;
+  }
+
+  // Different freshness: the fresher token wins
+  if (existingFreshness > incomingFreshness) {
+    return true;
+  }
+  if (existingFreshness < incomingFreshness) {
+    return false;
+  }
+
+  // Equal freshness: tie-break depends on regime
+  const existingHasOiat = existing.jwt?.header?.oiat != null;
+  const incomingHasOiat = incoming.jwt?.header?.oiat != null;
+  const sameRegime = existingHasOiat === incomingHasOiat;
+
+  if (sameRegime) {
+    // Same regime, equal freshness.
+    // Both have oiat: tie-break by iat (more recent mint wins). Equal iat: keep existing.
+    // Neither has oiat: both origin, same DB snapshot. Keep existing (avoid churn).
+    const existingIat = existing.jwt?.claims?.iat ?? 0;
+    const incomingIat = incoming.jwt?.claims?.iat ?? 0;
+    return existingIat >= incomingIat;
+  }
+
+  // Different regimes, equal freshness. Transition is happening. Favor incoming.
+  return false;
+}