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

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }

.changeset/remove-expired-token-retry.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Skip `expired_token` retry flow when Session Minter is enabled. When `sessionMinter` is on, the token is sent in the POST body, so the retry-with-expired-token fallback is unnecessary. The retry flow is preserved for non-Session Minter mode.

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

.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.

.changeset/session-minter-oiat-type.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add `oiat` (original_issued_at) field to `JwtHeader` type for Session Minter monotonic token freshness checks.

.changeset/session-minter-send-token.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Send previous session token on `/tokens` requests to support Session Minter edge token minting.

packages/clerk-js/bundlewatch.config.json

@@ -3,7 +3,7 @@
  { "path": "./dist/clerk.js", "maxSize": "931KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "67KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "68KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
  { "path": "./dist/vendors*.js", "maxSize": "50KB" },

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

@@ -31,13 +31,23 @@ 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>;
  close: ReturnType<typeof vi.fn>;
  postMessage: ReturnType<typeof vi.fn>;
  };
- let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void;
+ let broadcastListener: (e: MessageEvent<SessionTokenEvent>) => void | Promise<void>;
  let originalBroadcastChannel: any;
 
  beforeEach(() => {
@@ -96,7 +106,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -113,7 +123,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -130,7 +140,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(1);
  });
@@ -148,7 +158,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
 
  expect(SessionTokenCache.size()).toBe(0);
@@ -168,7 +178,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
@@ -188,31 +198,33 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  expect(SessionTokenCache.size()).toBe(0);
  });
 
- it('enforces monotonicity: does not overwrite newer token with older one', () => {
+ it('enforces monotonicity: does not overwrite newer token with older one', async () => {
+ // 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>;
 
- broadcastListener(newerEvent);
+await broadcastListener(newerEvent);
  const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterNewer).toBeDefined();
  const newerCreatedAt = cachedEntryAfterNewer?.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,
@@ -224,13 +236,54 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(olderEvent);
+await broadcastListener(olderEvent);
 
  const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntryAfterOlder).toBeDefined();
  expect(cachedEntryAfterOlder?.createdAt).toBe(newerCreatedAt);
  });
 
+ it('enforces monotonicity: replaces older cached token when a fresher-oiat broadcast arrives', async () => {
+ // Inverse of the previous test: a fresher-oiat broadcast must overwrite
+ // an older-oiat token already in cache. Use ttl=120 so both tokens stay
+ // valid against the test clock (nowSec=1666648260) - cache.get drops
+ // entries past their expiry.
+ const olderJwt = createJwtWithOiat(1666648190, 1666648190, 120);
+ const newerJwt = createJwtWithOiat(1666648250, 1666648250, 120);
+
+ const olderEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: olderJwt,
+ traceId: 'test_trace_older_first',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(olderEvent);
+ const cachedEntryAfterOlder = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterOlder).toBeDefined();
+ const olderCreatedAt = cachedEntryAfterOlder?.createdAt;
+
+ const newerEvent: MessageEvent<SessionTokenEvent> = {
+ data: {
+ organizationId: null,
+ sessionId: 'session_123',
+ template: undefined,
+ tokenId: 'session_123',
+ tokenRaw: newerJwt,
+ traceId: 'test_trace_newer_second',
+ },
+ } as MessageEvent<SessionTokenEvent>;
+
+ await broadcastListener(newerEvent);
+ const cachedEntryAfterNewer = SessionTokenCache.get({ tokenId: 'session_123' });
+ expect(cachedEntryAfterNewer).toBeDefined();
+ expect(cachedEntryAfterNewer?.createdAt).not.toBe(olderCreatedAt);
+ });
+
  it('successfully updates cache with valid token', () => {
  const event: MessageEvent<SessionTokenEvent> = {
  data: {
@@ -243,7 +296,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  const cachedEntry = SessionTokenCache.get({ tokenId: 'session_123' });
  expect(cachedEntry).toBeDefined();
@@ -265,7 +318,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(event);
+void broadcastListener(event);
 
  // Flush microtasks to let the tokenResolver promise settle without advancing timers
  await Promise.resolve();
@@ -757,7 +810,7 @@ describe('SessionTokenCache', () => {
  } as MessageEvent<SessionTokenEvent>;
 
  expect(() => {
- broadcastListener(event);
+void broadcastListener(event);
  }).not.toThrow();
  });
  });
@@ -801,7 +854,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(() => {
  expect(SessionTokenCache.get({ tokenId: session2Id })).toBeDefined();
@@ -862,7 +915,7 @@ describe('SessionTokenCache', () => {
  },
  } as MessageEvent<SessionTokenEvent>;
 
- broadcastListener(broadcastEvent);
+void broadcastListener(broadcastEvent);
 
  await vi.waitFor(async () => {
  const updatedCached = SessionTokenCache.get({ tokenId: sessionId });

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

@@ -0,0 +1,111 @@
+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 incoming when oiat equal and iat equal (other claims may differ)', () => {
+ // Two tokens with identical oiat+iat may still differ in other claims
+ // (azp, org_id, etc.) during a token-format rollout. Only suppress when
+ // existing is strictly fresher; on full ties, let incoming through.
+ const existing = makeToken({ oiat: 100, iat: 150 });
+ const incoming = makeToken({ oiat: 100, iat: 150 });
+ expect(pickFreshestJwt(existing, incoming)).toBe(incoming);
+ });
+
+ 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/AuthConfig.ts

@@ -8,6 +8,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  reverification: boolean = false;
  singleSessionMode: boolean = false;
  preferredChannels: Record<string, PhoneCodeChannel> | null = null;
+ sessionMinter: boolean = false;
 
  public constructor(data: Partial<AuthConfigJSON> | null = null) {
  super();
@@ -23,6 +24,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  this.reverification = this.withDefault(data.reverification, this.reverification);
  this.singleSessionMode = this.withDefault(data.single_session_mode, this.singleSessionMode);
  this.preferredChannels = this.withDefault(data.preferred_channels, this.preferredChannels);
+ this.sessionMinter = this.withDefault(data.session_minter, this.sessionMinter);
  return this;
  }
 
@@ -33,6 +35,7 @@ export class AuthConfig extends BaseResource implements AuthConfigResource {
  object: 'auth_config',
  reverification: this.reverification,
  single_session_mode: this.singleSessionMode,
+ session_minter: this.sessionMinter,
  };
  }
 }