Skip to content

refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jacekradko merged 4 commits into from
Jun 30, 2026
Merged

refactor(js): extract key derivation into a KeyResolver #9032

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ad15730
refactor(js): extract key derivation into a KeyResolver
jacekradko Jun 29, 2026
8482004
Merge branch 'main' into jacek/sdk-139-extract-key-resolver
wobsoriano Jun 29, 2026
f0c3a43
Merge branch 'main' into jacek/sdk-139-extract-key-resolver
jacekradko Jun 29, 2026
fd6e335
chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…
jacekradko Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/sdk-139-extract-key-resolver.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.
37 changes: 37 additions & 0 deletions packages/clerk-js/src/core/__tests__/keyResolver.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
it('serializes a key as prefix::tokenId::audience', () => {
const resolver = createKeyResolver();
expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
});

it('defaults to the clerk prefix and an empty audience segment', () => {
const resolver = createKeyResolver();
expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
});

it('coalesces empty-string and undefined audience to the same key', () => {
const resolver = createKeyResolver();
expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
});

it('produces distinct keys for different audiences of the same tokenId', () => {
const resolver = createKeyResolver();
expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
resolver.toKey({ tokenId: 'same', audience: 'b' }),
);
});

it('isolates an audience-scoped key from the no-audience key of the same id', () => {
const resolver = createKeyResolver();
expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
});

it('respects a custom prefix', () => {
const resolver = createKeyResolver('custom');
expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
});
});
35 changes: 35 additions & 0 deletions packages/clerk-js/src/core/keyResolver.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
* Derives the opaque string keys used to address entries in the token store,
* keeping key construction out of the storage layer.
*/

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
* Identifies a cached token entry by tokenId and optional audience.
*/
export interface TokenCacheKeyJSON {
audience?: string;
tokenId: string;
}

export interface KeyResolver {
/**
* Serializes a key to its string form `prefix::tokenId::audience`.
* Empty-string and undefined audience collapse to the same key.
*/
toKey(key: TokenCacheKeyJSON): string;
}

/**
* Creates a {@link KeyResolver} bound to a key prefix.
*
* `audience` is currently unused by production (no caller sets it) but kept as a
* key dimension so an audience-scoped token can coexist with the session token
* of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
* name must derive from the same key so all three agree.
*/
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});
55 changes: 7 additions & 48 deletions packages/clerk-js/src/core/tokenCache.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
* Identifies a cached token entry by tokenId and optional audience.
*/
interface TokenCacheKeyJSON {
audience?: string;
tokenId: string;
}

/**
* Cache entry containing token metadata and resolver.
* Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
* Default seconds before token expiration to trigger background refresh.
* This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
* Converts between cache key objects and string representations.
* Format: `prefix::tokenId::audience`
*/
export class TokenCacheKey {
/**
* Parses a cache key string into a TokenCacheKey instance.
*/
static fromKey(key: string): TokenCacheKey {
const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
return new TokenCacheKey(prefix, { audience, tokenId });
}

constructor(
public prefix: string,
public data: TokenCacheKeyJSON,
) {
this.prefix = prefix;
this.data = data;
}

/**
* Converts the key to its string representation for Map storage.
*/
toKey(): string {
const { tokenId, audience } = this.data;
return [this.prefix, tokenId, audience || ''].join(DELIMITER);
}
}

/**
* Message format for BroadcastChannel token synchronization between tabs.
*/
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
* Automatically manages token expiration and cleanup via scheduled timeouts.
* BroadcastChannel support is enabled whenever the environment provides it.
*/
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
const store = createTokenStore<TokenCacheValue>();
const keyResolver = createKeyResolver(prefix);
const tabId = generateTabId();

let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
ensureBroadcastChannel();

const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
const value = store.get(cacheKey.toKey());
const key = keyResolver.toKey(cacheKeyJSON);
const value = store.get(key);

if (!value) {
return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
if (value.refreshTimeoutId !== undefined) {
clearTimeout(value.refreshTimeoutId);
}
store.delete(cacheKey.toKey());
store.delete(key);
return;
}

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
* @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
*/
const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
const cacheKey = new TokenCacheKey(prefix, {
const key = keyResolver.toKey({
audience: entry.audience,
tokenId: entry.tokenId,
});

const key = cacheKey.toKey();

// Clear timers from any existing entry for this key to prevent orphaned
// refresh timers from accumulating across set() calls (e.g., from
// #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
refactor(js): extract key derivation into a KeyResolver by jacekradko · Pull Request #9032 · clerk/javascript · GitHub
Skip to content
refactor(js): extract key derivation into a KeyResolver#9032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

jacekradko
merged 4 commits into

from

Jun 30, 2026
 Merged


refactor(js): extract key derivation into a KeyResolver
#9032
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
ad15730

refactor(js): extract key derivation into a KeyResolver


jacekradko Jun 29, 2026
8482004

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


wobsoriano Jun 29, 2026
f0c3a43

Merge branch 'main' into jacek/sdk-139-extract-key-resolver


jacekradko Jun 29, 2026
fd6e335

chore(js): bump clerk-js patch for KeyResolver refactor changelog vis…


jacekradko Jun 30, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/sdk-139-extract-key-resolver.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': patch
---

Refactor the internal token cache so entry keys are derived through a dedicated `KeyResolver` module. This is an internal change with no effect on caching behavior or the public API.

37 changes: 37 additions & 0 deletions
packages/clerk-js/src/core/__tests__/keyResolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
import { describe, expect, it } from 'vitest';

import { createKeyResolver } from '../keyResolver';

describe('createKeyResolver', () => {
 it('serializes a key as prefix::tokenId::audience', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: 'aud' })).toBe('clerk::session_123::aud');
 });

 it('defaults to the clerk prefix and an empty audience segment', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('clerk::session_123::');
 });

 it('coalesces empty-string and undefined audience to the same key', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'session_123', audience: '' })).toBe(resolver.toKey({ tokenId: 'session_123' }));
 });

 it('produces distinct keys for different audiences of the same tokenId', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(
 resolver.toKey({ tokenId: 'same', audience: 'b' }),
 );
 });

 it('isolates an audience-scoped key from the no-audience key of the same id', () => {
 const resolver = createKeyResolver();
 expect(resolver.toKey({ tokenId: 'same', audience: 'a' })).not.toBe(resolver.toKey({ tokenId: 'same' }));
 });

 it('respects a custom prefix', () => {
 const resolver = createKeyResolver('custom');
 expect(resolver.toKey({ tokenId: 'session_123' })).toBe('custom::session_123::');
 });
});

35 changes: 35 additions & 0 deletions
packages/clerk-js/src/core/keyResolver.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
/**
 * Derives the opaque string keys used to address entries in the token store,
 * keeping key construction out of the storage layer.
 */

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
export interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

export interface KeyResolver {
 /**
 * Serializes a key to its string form `prefix::tokenId::audience`.
 * Empty-string and undefined audience collapse to the same key.
 */
 toKey(key: TokenCacheKeyJSON): string;
}

/**
 * Creates a {@link KeyResolver} bound to a key prefix.
 *
 * `audience` is currently unused by production (no caller sets it) but kept as a
 * key dimension so an audience-scoped token can coexist with the session token
 * of the same id. If it is revived, the cross-tab broadcast and Web Locks lock
 * name must derive from the same key so all three agree.
 */
export const createKeyResolver = (prefix: string = KEY_PREFIX): KeyResolver => ({
 toKey: ({ tokenId, audience }) => [prefix, tokenId, audience || ''].join(DELIMITER),
});

55 changes: 7 additions & 48 deletions
packages/clerk-js/src/core/tokenCache.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,18 +4,11 @@ import { debugLogger } from '@/utils/debug';
import { TokenId } from '@/utils/tokenId';

import { POLLER_INTERVAL_IN_MS } from './auth/SessionCookiePoller';
import { createKeyResolver, type TokenCacheKeyJSON } from './keyResolver';
import { Token } from './resources/internal';
import { pickFreshestJwt } from './tokenFreshness';
import { createTokenStore } from './tokenStore';

/**
 * Identifies a cached token entry by tokenId and optional audience.
 */
interface TokenCacheKeyJSON {
 audience?: string;
 tokenId: string;
}

/**
 * Cache entry containing token metadata and resolver.
 * Extends TokenCacheKeyJSON with additional properties for expiration tracking and token retrieval.
Expand DownExpand Up@@ -105,9 +98,6 @@ export interface TokenCache {
 size(): number;
}

const KEY_PREFIX = 'clerk';
const DELIMITER = '::';

/**
 * Default seconds before token expiration to trigger background refresh.
 * This threshold accounts for timer jitter, SafeLock contention (~5s), network latency,
Expand All@@ -122,36 +112,6 @@ const BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS = 15;
const BROADCAST = { broadcast: true };
const NO_BROADCAST = { broadcast: false };

/**
 * Converts between cache key objects and string representations.
 * Format: `prefix::tokenId::audience`
 */
export class TokenCacheKey {
 /**
 * Parses a cache key string into a TokenCacheKey instance.
 */
 static fromKey(key: string): TokenCacheKey {
 const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
 return new TokenCacheKey(prefix, { audience, tokenId });
 }

 constructor(
 public prefix: string,
 public data: TokenCacheKeyJSON,
 ) {
 this.prefix = prefix;
 this.data = data;
 }

 /**
 * Converts the key to its string representation for Map storage.
 */
 toKey(): string {
 const { tokenId, audience } = this.data;
 return [this.prefix, tokenId, audience || ''].join(DELIMITER);
 }
}

/**
 * Message format for BroadcastChannel token synchronization between tabs.
 */
Expand All@@ -173,8 +133,9 @@ const generateTabId = (): string => {
 * Automatically manages token expiration and cleanup via scheduled timeouts.
 * BroadcastChannel support is enabled whenever the environment provides it.
 */
const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
const MemoryTokenCache = (prefix?: string): TokenCache => {
 const store = createTokenStore<TokenCacheValue>();
 const keyResolver = createKeyResolver(prefix);
 const tabId = generateTabId();

 let broadcastChannel: BroadcastChannel | null = null;
Expand DownExpand Up@@ -213,8 +174,8 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 const get = (cacheKeyJSON: TokenCacheKeyJSON): TokenCacheGetResult | undefined => {
 ensureBroadcastChannel();

 const cacheKey = new TokenCacheKey(prefix, cacheKeyJSON);
 const value = store.get(cacheKey.toKey());
 const key = keyResolver.toKey(cacheKeyJSON);
 const value = store.get(key);

 if (!value) {
 return;
Expand All@@ -233,7 +194,7 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 if (value.refreshTimeoutId !== undefined) {
 clearTimeout(value.refreshTimeoutId);
 }
 store.delete(cacheKey.toKey());
 store.delete(key);
 return;
 }

Expand DownExpand Up@@ -344,13 +305,11 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
 * @param options - Configuration for cache behavior; broadcast controls whether to notify other tabs
 */
 const setInternal = (entry: TokenCacheEntry, options: { broadcast: boolean } = BROADCAST) => {
 const cacheKey = new TokenCacheKey(prefix, {
 const key = keyResolver.toKey({
 audience: entry.audience,
 tokenId: entry.tokenId,
 });

 const key = cacheKey.toKey();

 // Clear timers from any existing entry for this key to prevent orphaned
 // refresh timers from accumulating across set() calls (e.g., from
 // #hydrateCache during _updateClient AND #refreshTokenInBackground).
Expand Down
Loading