@zerodev/wallet-core 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerodev/wallet-core",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "ZeroDev Wallet SDK built on Turnkey",
   "repository": {
     "type": "git",

package/src/client/transports/createTransport.ts

@@ -12,6 +12,11 @@ export type CreateTransportOptions = {
   name?: string
   /** Extra options merged into every fetch() call */
   fetchOptions?: Omit<RequestInit, 'body' | 'method' | 'signal'>
+  /**
+   * @internal The package reported in the `X-SDK-Version` header. Wrapper
+   * packages set their own name and version; apps should not set it.
+   */
+  sdkVersion?: string
 }
 
 /**
@@ -37,6 +42,7 @@ export function zeroDevWalletTransport(
       apiKeyStamper,
       passkeyStamper,
       ...(options.fetchOptions && { fetchOptions: options.fetchOptions }),
+      ...(options.sdkVersion && { sdkVersion: options.sdkVersion }),
     })
 
     return {

package/src/client/transports/rest.ts

@@ -2,6 +2,7 @@ import { canonicalizeEx } from 'json-canonicalize'
 import { RestRequestError, RestTimeoutError } from '../../errors/request.js'
 import type { Stamper } from '../../stampers/types.js'
 import type { StamperType } from '../../types/session.js'
+import { version } from '../../version.js'
 
 export type RestRequestArgs = {
   path: string
@@ -42,6 +43,8 @@ export type RestTransportConfig = {
   name?: string
   apiKeyStamper: Stamper
   passkeyStamper: Stamper
+  /** `X-SDK-Version` value; defaults to this package. */
+  sdkVersion?: string
 }
 
 export function rest(url: string, cfg: RestTransportConfig): RestTransport {
@@ -60,6 +63,8 @@ export function rest(url: string, cfg: RestTransportConfig): RestTransport {
         ...((cfg.fetchOptions?.headers as Record<string, string>) ?? {}),
         ...(args.headers ?? {}),
         'content-type': 'application/json',
+        // Lets KMS report which SDK package and version each project runs.
+        'X-SDK-Version': cfg.sdkVersion ?? `@zerodev/wallet-core@${version}`,
       }
 
       // Handle stamping if requested

package/src/core/createZeroDevWalletCore.ts

@@ -17,9 +17,14 @@ import {
 } from '../storage/manager.js'
 import { SessionType, type ZeroDevWalletSession } from '../types/session.js'
 import { buildClientSignature } from '../utils/buildClientSignature.js'
+import { withCrossTabLock } from '../utils/crossTabLock.js'
 import { encryptOtpAttempt } from '../utils/encryptOtpAttempt.js'
 import { createOrganizationIdResolver } from '../utils/resolveOrganizationId.js'
-import { humanReadableDateTime, parseSession } from '../utils/utils.js'
+import {
+  humanReadableDateTime,
+  normalizeTimestamp,
+  parseSession,
+} from '../utils/utils.js'
 export interface ZeroDevWalletConfigCore {
   organizationId?: string
   proxyBaseUrl?: string
@@ -29,6 +34,11 @@ export interface ZeroDevWalletConfigCore {
   apiKeyStamper: ApiKeyStamper
   passkeyStamper?: PasskeyStamper
   fetchOptions?: CreateTransportOptions['fetchOptions']
+  /**
+   * @internal The package reported in the `X-SDK-Version` header. Wrapper
+   * packages set their own name and version; apps should not set it.
+   */
+  sdkVersion?: string
 }
 
 export type { StorageAdapter, StorageManager } from '../storage/manager.js'
@@ -128,6 +138,7 @@ export async function createZeroDevWalletCore(
     transport: zeroDevWalletTransport({
       baseUrl: config.proxyBaseUrl || `${KMS_SERVER_URL}/api/v1`,
       ...(config.fetchOptions && { fetchOptions: config.fetchOptions }),
+      ...(config.sdkVersion && { sdkVersion: config.sdkVersion }),
     }),
   })
 
@@ -193,7 +204,8 @@ export async function createZeroDevWalletCore(
     }
   }
 
-  const commitReplacementSession = async (
+  // Callers must hold the cross-tab lock; see commitReplacementSession.
+  const commitReplacementSessionLocked = async (
     session: ZeroDevWalletSession,
     targetPublicKey: string,
   ) => {
@@ -227,26 +239,41 @@ export async function createZeroDevWalletCore(
       if (!recovered) throw error
     }
   }
+  const commitReplacementSession = (
+    session: ZeroDevWalletSession,
+    targetPublicKey: string,
+  ) =>
+    withCrossTabLock(() =>
+      commitReplacementSessionLocked(session, targetPublicKey),
+    )
 
-  await withKeyTransition(async () => {
-    const activePublicKey = await client.apiKeyStamper.getPublicKey()
-    await sessionStorageManager.recoverSessionTransition(activePublicKey)
-    const restoredSession = await sessionStorageManager.getActiveSession()
-    if (restoredSession) {
-      try {
-        const restoredPublicKey = parseSession(restoredSession.token).publicKey
-        if (
-          !activePublicKey ||
-          !restoredPublicKey ||
-          normalizeKey(activePublicKey) !== normalizeKey(restoredPublicKey)
-        ) {
+  await withKeyTransition(() =>
+    withCrossTabLock(async () => {
+      // The stamper read the vault before this tab got the lock; another tab
+      // may have committed a new key since. A stale key here would look like a
+      // mismatch and clear that tab's valid session.
+      await client.apiKeyStamper.reload?.()
+      const activePublicKey = await client.apiKeyStamper.getPublicKey()
+      await sessionStorageManager.recoverSessionTransition(activePublicKey)
+      const restoredSession = await sessionStorageManager.getActiveSession()
+      if (restoredSession) {
+        try {
+          const restoredPublicKey = parseSession(
+            restoredSession.token,
+          ).publicKey
+          if (
+            !activePublicKey ||
+            !restoredPublicKey ||
+            normalizeKey(activePublicKey) !== normalizeKey(restoredPublicKey)
+          ) {
+            await sessionStorageManager.clearAllSessions()
+          }
+        } catch {
           await sessionStorageManager.clearAllSessions()
         }
-      } catch {
-        await sessionStorageManager.clearAllSessions()
       }
-    }
-  })
+    }),
+  )
 
   return {
     client,
@@ -291,56 +318,94 @@ export async function createZeroDevWalletCore(
     },
 
     async clearAllSessions() {
-      if (await sessionStorageManager.getActiveSession()) {
-        throw new Error(
-          'Refusing to clear the active session locally; use logout() to revoke its remote key first.',
-        )
-      }
-      await sessionStorageManager.clearAllSessions()
+      // Under the lock, so it cannot remove another tab's in-flight journal.
+      return withKeyTransition(() =>
+        withCrossTabLock(async () => {
+          if (await sessionStorageManager.getActiveSession()) {
+            throw new Error(
+              'Refusing to clear the active session locally; use logout() to revoke its remote key first.',
+            )
+          }
+          await sessionStorageManager.clearAllSessions()
+        }),
+      )
     },
 
     async refreshSession(sessionId?: string) {
-      return withKeyTransition(async () => {
-        const activeSessionKey =
-          await sessionStorageManager.getActiveSessionKey()
-        if (sessionId && sessionId !== activeSessionKey) {
-          throw new Error(
-            'Refreshing an inactive session is not supported with a single active key vault',
-          )
-        }
-        const activeSession = await sessionStorageManager.getActiveSession()
-        if (!activeSession) {
-          throw new Error('No active session')
-        }
-        if (activeSession.stamperType !== 'apiKey') {
-          throw new Error('Invalid session type')
-        }
+      // Without an id, refresh the session active when called, so a tab that
+      // then waits behind another tab's refresh adopts it instead of rotating
+      // again. Read now but awaited inside, so the call keeps its queue place.
+      const expected =
+        sessionId === undefined
+          ? sessionStorageManager.getActiveSessionKey()
+          : Promise.resolve(sessionId)
+      expected.catch(() => undefined)
+      return withKeyTransition(() =>
+        withCrossTabLock(async () => {
+          const expectedId = await expected
+          const activeSessionKey =
+            await sessionStorageManager.getActiveSessionKey()
+          const activeSession = await sessionStorageManager.getActiveSession()
+          if (!activeSession) {
+            throw new Error('No active session')
+          }
+          if (expectedId && expectedId !== activeSessionKey) {
+            // Another tab replaced the session while this one waited. Adopt it
+            // only when that tab also replaced the key under this one. Within
+            // one tab, a call without an id refreshes the current session and
+            // an inactive id stays an error. Callers should still compare the
+            // identity: the other tab may have signed in to a different account.
+            if (activeSession.stamperType === 'apiKey') {
+              const keyBefore = await client.apiKeyStamper.getPublicKey()
+              await client.apiKeyStamper.reload?.()
+              const activePublicKey = await client.apiKeyStamper.getPublicKey()
+              if (
+                activePublicKey &&
+                normalizeKey(activePublicKey) !==
+                  normalizeKey(keyBefore ?? '') &&
+                normalizeKey(activePublicKey) ===
+                  normalizeKey(activeSession.publicKey ?? '') &&
+                normalizeTimestamp(activeSession.expiry) > Date.now()
+              ) {
+                return activeSession
+              }
+            }
+            if (sessionId !== undefined) {
+              throw new Error(
+                'Refreshing an inactive session is not supported with a single active key vault',
+              )
+            }
+          }
+          if (activeSession.stamperType !== 'apiKey') {
+            throw new Error('Invalid session type')
+          }
 
-        const targetPublicKey = await prepareFreshKeyRotation()
-        try {
-          const data = await client.loginWithStamp({
-            targetPublicKey,
-            projectId,
-            // Stamp-login is signed against the Turnkey parent org; the backend
-            // resolves the sub-org from the stamped credential. Signing the
-            // sub-org here makes the relayed payload's org mismatch the
-            // signature → Turnkey SIGNATURE_INVALID.
-            organizationId: await resolveOrganizationId(),
-            stampWith: 'apiKey',
-          })
-          const session = createReplacementSession(
-            data.session,
-            targetPublicKey,
-            'indexedDb',
-            SessionType.READ_WRITE,
-          )
-          await commitReplacementSession(session, targetPublicKey)
-          return session
-        } catch (error) {
-          await client.apiKeyStamper.discardKeyRotation()
-          throw error
-        }
-      })
+          const targetPublicKey = await prepareFreshKeyRotation()
+          try {
+            const data = await client.loginWithStamp({
+              targetPublicKey,
+              projectId,
+              // Stamp-login is signed against the Turnkey parent org; the backend
+              // resolves the sub-org from the stamped credential. Signing the
+              // sub-org here makes the relayed payload's org mismatch the
+              // signature → Turnkey SIGNATURE_INVALID.
+              organizationId: await resolveOrganizationId(),
+              stampWith: 'apiKey',
+            })
+            const session = createReplacementSession(
+              data.session,
+              targetPublicKey,
+              'indexedDb',
+              SessionType.READ_WRITE,
+            )
+            await commitReplacementSessionLocked(session, targetPublicKey)
+            return session
+          } catch (error) {
+            await client.apiKeyStamper.discardKeyRotation()
+            throw error
+          }
+        }),
+      )
     },
 
     // [TODO] refactor to smaller utils/actions
@@ -408,24 +473,28 @@ export async function createZeroDevWalletCore(
                   encodedPublicKey: registrationPublicKey,
                 })
 
-                // Registration proves the temporary key exists remotely. Make
-                // it active so it can authorize the durable replacement key.
-                await client.apiKeyStamper.commitKeyRotation()
-                const targetPublicKey = await prepareFreshKeyRotation()
-                const loginData = await client.loginWithStamp({
-                  projectId,
-                  targetPublicKey,
-                  // Sign against the parent org (see refreshSession note) — the
-                  // backend derives the sub-org from the stamped credential.
-                  organizationId: await resolveOrganizationId(),
+                // From here the shared vault changes, so hold the cross-tab
+                // lock; the passkey prompt above stays outside it.
+                return await withCrossTabLock(async () => {
+                  // Registration proves the temporary key exists remotely. Make
+                  // it active so it can authorize the durable replacement key.
+                  await client.apiKeyStamper.commitKeyRotation()
+                  const targetPublicKey = await prepareFreshKeyRotation()
+                  const loginData = await client.loginWithStamp({
+                    projectId,
+                    targetPublicKey,
+                    // Sign against the parent org (see refreshSession note) — the
+                    // backend derives the sub-org from the stamped credential.
+                    organizationId: await resolveOrganizationId(),
+                  })
+                  const session = createReplacementSession(
+                    loginData.session,
+                    targetPublicKey,
+                    'indexedDb',
+                  )
+                  await commitReplacementSessionLocked(session, targetPublicKey)
+                  return data
                 })
-                const session = createReplacementSession(
-                  loginData.session,
-                  targetPublicKey,
-                  'indexedDb',
-                )
-                await commitReplacementSession(session, targetPublicKey)
-                return data
               } catch (error) {
                 await client.apiKeyStamper.discardKeyRotation()
                 throw error
@@ -619,19 +688,34 @@ export async function createZeroDevWalletCore(
         }
 
         preparedOAuthPublicKey = undefined
-        let cleanupError: unknown
-        try {
-          await client.apiKeyStamper.clear()
-        } catch (error) {
-          cleanupError = error
-        }
-        try {
-          await sessionStorageManager.clearAllSessions()
-        } catch (error) {
-          cleanupError ??= error
-        }
-        if (cleanupError) throw cleanupError
-        return true
+        return withCrossTabLock(async () => {
+          // Another tab may have signed in while the revoke was in flight. Keep
+          // a session for a different account, or one that appeared after a
+          // signed-out start; a same-account refresh is still ours to clear.
+          const current = await sessionStorageManager.getActiveSession()
+          if (
+            current &&
+            (!session ||
+              current.organizationId !== session.organizationId ||
+              current.userId !== session.userId)
+          ) {
+            await client.apiKeyStamper.discardKeyRotation()
+            return true
+          }
+          let cleanupError: unknown
+          try {
+            await client.apiKeyStamper.clear()
+          } catch (error) {
+            cleanupError = error
+          }
+          try {
+            await sessionStorageManager.clearAllSessions()
+          } catch (error) {
+            cleanupError ??= error
+          }
+          if (cleanupError) throw cleanupError
+          return true
+        })
       })
     },
 

package/src/stampers/indexedDbStamper.ts

@@ -1,5 +1,6 @@
 import { p256 } from '@noble/curves/nist.js'
 import { IndexedDbStamper as TurnkeyIndexedDbStamper } from '@turnkey/indexed-db-stamper'
+import { withCrossTabLock } from '../utils/crossTabLock.js'
 import { generateCompressedPublicKeyFromKeyPair } from '../utils/utils.js'
 import type { ApiKeyStamper } from './types.js'
 
@@ -28,7 +29,9 @@ function encodeStamp(publicKey: string, signature: string): string {
 
 export async function createIndexedDbStamper(): Promise<ApiKeyStamper> {
   const inner = new TurnkeyIndexedDbStamper()
-  await inner.init()
+  // On an empty vault init() generates and stores a key; under the lock it
+  // cannot overwrite a key another tab is committing.
+  await withCrossTabLock(() => inner.init())
 
   let pendingKeyPair: CryptoKeyPair | null = null
 
@@ -88,5 +91,9 @@ export async function createIndexedDbStamper(): Promise<ApiKeyStamper> {
     async discardKeyRotation() {
       pendingKeyPair = null
     },
+    // Unlocked: its callers already hold the cross-tab lock.
+    async reload() {
+      await inner.init()
+    },
   }
 }

package/src/stampers/types.ts

@@ -45,6 +45,11 @@ export type ApiKeyStamper = Stamper & {
   commitKeyRotation: () => Promise<void>
   /** Forget the prepared key while keeping the active key untouched. */
   discardKeyRotation: () => Promise<void>
+  /**
+   * Re-read the active key from the shared vault, which another tab may have
+   * rotated. Omit when each app has its own vault (React Native).
+   */
+  reload?: () => Promise<void>
   /**
    * Sign `payload` with the currently active key. Returns a hex-encoded
    * ECDSA-P256 / SHA-256 signature in ASN.1 DER form.

package/src/utils/crossTabLock.ts

@@ -0,0 +1,19 @@
+// Tabs of one origin share the key vault and session storage but not the
+// in-process key-transition queue in createZeroDevWalletCore. A Web Lock spans
+// tabs. It covers a whole refresh, so every tab's timer firing at the same
+// instant sends one stamp login (Turnkey fails concurrent ones for a sub-org,
+// DPL-798), and every write of the shared vault and session, including the
+// stamper's first key on an empty vault, so one tab cannot overwrite another's
+// key or consume its transition journal. It never spans a passkey prompt or
+// OAuth popup: an abandoned prompt would block every other tab. It is not
+// re-entrant, so code running under it must not take it again. Without Web
+// Locks (React Native, very old browsers) there is one instance per app or the
+// in-process queue is all we have.
+export const KEY_TRANSITION_LOCK = '@zerodev/key_transition'
+
+export const withCrossTabLock = async <T>(
+  task: () => Promise<T>,
+): Promise<T> => {
+  const locks = typeof navigator === 'undefined' ? undefined : navigator.locks
+  return locks ? await locks.request(KEY_TRANSITION_LOCK, task) : task()
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+// Synced from package.json by scripts/sync-version.mjs in changeset:version.
+export const version = '0.0.7'