refactor(js): extract key derivation into a KeyResolver

[jacekradko]

Step 3 of the TokenCache decouple (SDK-117 landed steps 1-2). This lifts the prefix::tokenId::audience key construction out of tokenCache.ts into a small createKeyResolver module, so the cache and store layers only pass opaque string keys around. The serialization moves verbatim, so there's no behavior change; the existing audience/coalescing tests in tokenCache.test.ts and the Session consumer suite are the regression bar and stay green.

One judgment call worth a look: I dropped TokenCacheKey.fromKey (the string-to-object parser) instead of porting it into the new module. It had zero callers repo-wide, so this removes dead code rather than relocating it. Trivial to add back if SDK-141's cross-tab coordinator ends up needing to parse a stored key.

audience stays a key dimension (nothing in production sets it today) with the empty-string/undefined coalescing preserved. Shipped as a clerk-js patch so the refactor shows up in the changelog, though it is internal-only with no observable change.

Closes SDK-139.

Summary by CodeRabbit

• New Features

  • Token cache key generation is now audience-aware and centralized, reducing collisions across token contexts.
  • Cache key prefixes can be customized for more predictable keying.

• Bug Fixes

  • Empty and undefined audience values now produce the same derived cache key.
  • Cache expiration now reliably removes entries using the exact stored key.

• Tests

  • Added coverage for key formatting, audience handling (including normalization), and configurable prefix behavior.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 29, 2026 7:22pm
swingset	Ready	Preview, Comment	Jun 29, 2026 7:22pm

[changeset-bot]

🦋 Changeset detected

Latest commit: fd6e335

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

This PR includes changesets to release 4 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/electron	Patch
@clerk/expo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

Extracts token cache key construction into keyResolver.ts and updates MemoryTokenCache to use the new resolver for cache key generation and cleanup. The PR also adds tests for key formatting and normalization, plus a changeset entry.

Changes

Key Resolver Extraction

Layer / File(s)	Summary
keyResolver module: types, interface, factory packages/clerk-js/src/core/keyResolver.ts, packages/clerk-js/src/core/__tests__/keyResolver.test.ts	Defines TokenCacheKeyJSON, KeyResolver, and createKeyResolver(prefix?) for prefix::tokenId::audience serialization with empty/undefined audience normalization. Tests cover formatting, default prefix, audience normalization, isolation, and custom prefixes.
tokenCache refactored to use keyResolver packages/clerk-js/src/core/tokenCache.ts, .changeset/sdk-139-extract-key-resolver.md	Removes the in-file TokenCacheKey class and local key constants. MemoryTokenCache now creates a resolver, uses toKey() for reads/writes/deletes, and the changeset records the internal refactor as a patch release.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• clerk/javascript#8860: Refactors packages/clerk-js/src/core/tokenCache.ts internals around MemoryTokenCache, like this PR’s key-resolution extraction.

Suggested reviewers

• wobsoriano

Poem

🐇 A key was tucked inside a shell,
Now split apart and named quite well.
prefix::tokenId::audience hops free,
With tests to guard its symmetry.
The cache goes thunk, the resolver sings—
A tidy hop for little things.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: extracting token-cache key derivation into a KeyResolver.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9032

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9032

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9032

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9032

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9032

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9032

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9032

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9032

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9032

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9032

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9032

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9032

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9032

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9032

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9032

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9032

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9032

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9032

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9032

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9032

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9032

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9032

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9032

commit: fd6e335

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-30T00:51:43.157Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on fd6e335.}