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

.changeset/session-minter-monotonic-guard.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Add monotonic token replacement based on `oiat` to prevent edge-minted tokens with stale claims from overwriting fresher DB-minted tokens in multi-tab scenarios.

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

@@ -31,6 +31,16 @@ function createJwtWithTtl(iatSeconds: number, ttlSeconds: number): string {
   return `${headerB64}.${payloadB64}.${signature}`;
 }
 
+/**
+ * Helper to create a JWT with custom iat AND oiat header for monotonic-freshness tests
+ */
+function createJwtWithOiat(iatSeconds: number, oiatSeconds: number, ttlSeconds = 60): string {
+  const header = { alg: 'HS256', typ: 'JWT', oiat: oiatSeconds };
+  const payload = { sid: 'session_123', exp: iatSeconds + ttlSeconds, iat: iatSeconds };
+  const b64 = (o: object) => btoa(JSON.stringify(o)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  return `${b64(header)}.${b64(payload)}.test-signature`;
+}
+
 describe('SessionTokenCache', () => {
   let mockBroadcastChannel: {
     addEventListener: ReturnType<typeof vi.fn>;
@@ -194,13 +204,18 @@ describe('SessionTokenCache', () => {
     });
 
     it('enforces monotonicity: does not overwrite newer token with older one', () => {
+      // Both tokens carry oiat (the production case post-rollout). Older oiat
+      // broadcast must not clobber the newer one already in cache.
+      const newerJwt = createJwtWithOiat(1666648250, 1666648250);
+      const olderJwt = createJwtWithOiat(1666648190, 1666648190);
+
       const newerEvent: MessageEvent<SessionTokenEvent> = {
         data: {
           organizationId: null,
           sessionId: 'session_123',
           template: undefined,
           tokenId: 'session_123',
-          tokenRaw: mockJwt,
+          tokenRaw: newerJwt,
           traceId: 'test_trace_7',
         },
       } as MessageEvent<SessionTokenEvent>;
@@ -210,9 +225,6 @@ describe('SessionTokenCache', () => {
       expect(resultAfterNewer).toBeDefined();
       const newerCreatedAt = resultAfterNewer?.entry.createdAt;
 
-      // mockJwt has iat: 1666648250, so create an older one with iat: 1666648190 (60 seconds earlier)
-      const olderJwt =
-        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjY2NDg4NTAsImlhdCI6MTY2NjY0ODE5MH0.Z1BC47lImYvaAtluJlY-kBo0qOoAk42Xb-gNrB2SxJg';
       const olderEvent: MessageEvent<SessionTokenEvent> = {
         data: {
           organizationId: null,

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

@@ -0,0 +1,108 @@
+import type { JWT, TokenResource } from '@clerk/shared/types';
+import { describe, expect, it } from 'vitest';
+
+import { pickFreshestJwt } from '../tokenFreshness';
+
+function makeToken(opts: { oiat?: number; iat?: number } = {}): TokenResource {
+  return {
+    jwt: {
+      header: { alg: 'RS256', kid: 'kid_1', ...(opts.oiat != null ? { oiat: opts.oiat } : {}) },
+      claims: { ...(opts.iat != null ? { iat: opts.iat } : {}) },
+    },
+    getRawString: () => 'mock-jwt',
+  } as unknown as TokenResource;
+}
+
+function makeJwt(opts: { oiat?: number; iat?: number } = {}): JWT {
+  return {
+    header: { alg: 'RS256', kid: 'kid_1', ...(opts.oiat != null ? { oiat: opts.oiat } : {}) },
+    claims: { ...(opts.iat != null ? { iat: opts.iat } : {}) },
+  } as unknown as JWT;
+}
+
+describe('pickFreshestJwt', () => {
+  describe('both have oiat (the only reachable path post-rollout)', () => {
+    it('picks existing when existing oiat > incoming oiat', () => {
+      const existing = makeToken({ oiat: 100 });
+      const incoming = makeToken({ oiat: 90 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(existing);
+    });
+
+    it('picks incoming when existing oiat < incoming oiat', () => {
+      const existing = makeToken({ oiat: 90 });
+      const incoming = makeToken({ oiat: 100 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+    });
+
+    it('picks existing when oiat equal and existing iat > incoming iat', () => {
+      const existing = makeToken({ oiat: 100, iat: 200 });
+      const incoming = makeToken({ oiat: 100, iat: 150 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(existing);
+    });
+
+    it('picks incoming when oiat equal and existing iat < incoming iat', () => {
+      const existing = makeToken({ oiat: 100, iat: 150 });
+      const incoming = makeToken({ oiat: 100, iat: 200 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+    });
+
+    it('picks existing when oiat equal and iat equal (identical, no churn)', () => {
+      const existing = makeToken({ oiat: 100, iat: 150 });
+      const incoming = makeToken({ oiat: 100, iat: 150 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(existing);
+    });
+
+    it('picks existing when oiat equal and incoming iat missing (treated as 0)', () => {
+      const existing = makeToken({ oiat: 100, iat: 150 });
+      const incoming = makeToken({ oiat: 100 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(existing);
+    });
+  });
+
+  describe('legacy (missing oiat) safety net', () => {
+    it('picks existing when incoming is legacy (no oiat) and existing has oiat', () => {
+      const existing = makeToken({ oiat: 100 });
+      const incoming = makeToken({ iat: 9999 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(existing);
+    });
+
+    it('picks incoming when existing is legacy and incoming has oiat', () => {
+      const existing = makeToken({ iat: 9999 });
+      const incoming = makeToken({ oiat: 100 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+    });
+
+    it('picks incoming when both sides are legacy (cannot rank, safe default)', () => {
+      const existing = makeToken({ iat: 200 });
+      const incoming = makeToken({ iat: 100 });
+      expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+    });
+  });
+
+  describe('same object reference', () => {
+    // When the cache hands back the same object that is already stored as
+    // lastActiveToken, callers use `pickFreshestJwt(a, b) === a` to detect
+    // "existing won, suppress redundant emit". This test documents that
+    // intentional behavior.
+    it('returns the same reference when both args are the same object', () => {
+      const token = makeToken({ oiat: 100, iat: 150 });
+      expect(pickFreshestJwt(token, token)).toBe(token);
+    });
+  });
+
+  describe('JWT input (cookie path)', () => {
+    it('accepts raw decoded JWT for both arguments', () => {
+      const a = makeJwt({ oiat: 100 });
+      const b = makeJwt({ oiat: 200 });
+      expect(pickFreshestJwt(a, b)).toBe(b);
+      expect(pickFreshestJwt(b, a)).toBe(b);
+    });
+
+    it('tie-breaks by iat on equal oiat for raw JWT inputs', () => {
+      const a = makeJwt({ oiat: 100, iat: 150 });
+      const b = makeJwt({ oiat: 100, iat: 200 });
+      expect(pickFreshestJwt(a, b)).toBe(b);
+      expect(pickFreshestJwt(b, a)).toBe(b);
+    });
+  });
+});

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

@@ -42,6 +42,7 @@ import type {
 } from '@clerk/shared/types';
 import { isWebAuthnSupported as isWebAuthnSupportedOnWindow } from '@clerk/shared/webauthn';
 
+import { pickFreshestJwt } from '@/core/tokenFreshness';
 import { unixEpochToDate } from '@/utils/date';
 import { debugLogger } from '@/utils/debug';
 import { TokenId } from '@/utils/tokenId';
@@ -458,7 +459,11 @@ export class Session extends BaseResource implements SessionResource {
       // Only emit token updates when we have an actual token — emitting with an empty
       // token causes AuthCookieService to remove the __session cookie (looks like sign-out).
       if (shouldDispatchTokenUpdate && cachedToken.getRawString()) {
-        eventBus.emit(events.TokenUpdate, { token: cachedToken });
+        const isStaler =
+          this.lastActiveToken && pickFreshestJwt(this.lastActiveToken, cachedToken) === this.lastActiveToken;
+        if (!isStaler) {
+          eventBus.emit(events.TokenUpdate, { token: cachedToken });
+        }
       }
       result = cachedToken.getRawString() || null;
     } else if (!isBrowserOnline()) {
@@ -518,6 +523,10 @@ export class Session extends BaseResource implements SessionResource {
       return;
     }
 
+    if (this.lastActiveToken && pickFreshestJwt(this.lastActiveToken, token) === this.lastActiveToken) {
+      return;
+    }
+
     eventBus.emit(events.TokenUpdate, { token });
 
     if (token.jwt) {

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

@@ -98,7 +98,9 @@ describe('Session', () => {
       expect(BaseResource.clerk.getFapiClient().request).not.toHaveBeenCalled();
 
       expect(token).toEqual(mockJwt);
-      expect(dispatchSpy).toHaveBeenCalledTimes(2);
+      // Cache hits with the same token as lastActiveToken suppress re-emission
+      // to avoid unnecessary cookie writes (monotonic freshness guard).
+      expect(dispatchSpy).toHaveBeenCalledTimes(0);
     });
 
     it('returns same token without API call when Session is reconstructed', async () => {

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 { pickFreshestJwt } 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 (pickFreshestJwt(existingToken, token) === existingToken) {
           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;
@@ -379,7 +379,9 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
     entry.tokenResolver
       .then(newToken => {
         // If this entry was overwritten by a newer set() call while our promise
-        // was pending, bail out to avoid installing orphaned timers.
+        // was pending, bail out to avoid installing orphaned timers. Monotonic
+        // replacement is enforced at the read sites (cookie + broadcast + Session)
+        // where the user-visible state lives.
         if (cache.get(key) !== value) {
           return;
         }

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

@@ -0,0 +1,48 @@
+import type { JWT, TokenResource } from '@clerk/shared/types';
+
+function asJwt(input: TokenResource | JWT): JWT | undefined {
+  return 'getRawString' in input ? input.jwt : input;
+}
+
+/**
+ * Picks the freshest of two tokens. Returns whichever argument has the more
+ * recent claim freshness; on a tie, returns `existing` (no churn).
+ *
+ * All origin-minted tokens carry the `oiat` JWT header (origin-issued-at;
+ * timestamp when claims were last assembled from the DB). A token without
+ * `oiat` is from a pre-feature codebase and is by definition staler than any
+ * token that has one.
+ *
+ * Coverage: invoked at /tokens responses, broadcast events, and cookie writes.
+ * Handshake-installed __session cookies are intentionally NOT gated:
+ * handshake is a redirect-based full auth state resync, the browser commits
+ * the Set-Cookie before any SDK code runs, and there is no in-flight race
+ * window for the gate to protect.
+ *
+ * @internal
+ */
+export function pickFreshestJwt<T extends TokenResource | JWT>(existing: T, incoming: T): T {
+  const existingOiat = asJwt(existing)?.header?.oiat;
+  const incomingOiat = asJwt(incoming)?.header?.oiat;
+
+  if (existingOiat == null && incomingOiat == null) {
+    return incoming;
+  }
+  if (incomingOiat == null) {
+    return existing;
+  }
+  if (existingOiat == null) {
+    return incoming;
+  }
+
+  if (existingOiat > incomingOiat) {
+    return existing;
+  }
+  if (existingOiat < incomingOiat) {
+    return incoming;
+  }
+
+  const existingIat = asJwt(existing)?.claims?.iat ?? 0;
+  const incomingIat = asJwt(incoming)?.claims?.iat ?? 0;
+  return existingIat >= incomingIat ? existing : incoming;
+}