@zerodev/wallet-core 0.0.3 → 0.0.4

package/src/index.native.ts

@@ -27,11 +27,14 @@ export type {
   GetWhoamiReturnType,
   LoginWithOTPParameters,
   LoginWithOTPReturnType,
+  LogoutParameters,
+  LogoutReturnType,
   OAuthAuthenticator,
   OtpContact,
   PasskeyAuthenticator,
   RegisterWithOTPParameters,
   RegisterWithOTPReturnType,
+  SessionKeyAuthenticator,
   Sign7702AuthorizationParameters,
   Sign7702AuthorizationReturnType,
   SignMessageParameters,
@@ -50,6 +53,7 @@ export {
   getUserWallet,
   getWhoami,
   loginWithOTP,
+  logout,
   registerWithOTP,
   sign7702Authorization,
   signMessage,

package/src/index.ts

@@ -24,11 +24,14 @@ export type {
   GetWhoamiReturnType,
   LoginWithOTPParameters,
   LoginWithOTPReturnType,
+  LogoutParameters,
+  LogoutReturnType,
   OAuthAuthenticator,
   OtpContact,
   PasskeyAuthenticator,
   RegisterWithOTPParameters,
   RegisterWithOTPReturnType,
+  SessionKeyAuthenticator,
   Sign7702AuthorizationParameters,
   Sign7702AuthorizationReturnType,
   SignMessageParameters,
@@ -51,6 +54,7 @@ export {
   getUserWallet,
   getWhoami,
   loginWithOTP,
+  logout,
   registerWithOTP,
   sign7702Authorization,
   signMessage,

package/src/native/stampers/secureStore.ts

@@ -1,22 +1,78 @@
 import { ApiKeyStamper, SignatureFormat } from '@turnkey/api-key-stamper'
-import { generateP256KeyPair } from '@turnkey/crypto'
+import { generateP256KeyPair, verifyStampSignature } from '@turnkey/crypto'
 import * as SecureStore from 'expo-secure-store'
 import type { ApiKeyStamper as ZDApiKeyStamper } from '../../stampers/types.js'
 
-const PUBLIC_KEY = 'zerodev.publicKey'
-const PRIVATE_KEY = 'zerodev.privateKey'
+const KEY_PAIR = 'zerodev.keyPair'
+const LEGACY_PUBLIC_KEY = 'zerodev.publicKey'
+const LEGACY_PRIVATE_KEY = 'zerodev.privateKey'
+
+type StoredKeyPair = { publicKey: string; privateKey: string }
+const KEY_PAIR_CHECK = 'ZeroDev Wallet key-pair ownership check'
+
+function parseKeyPair(value: string | null): StoredKeyPair | null {
+  if (!value) return null
+  try {
+    const pair = JSON.parse(value) as Partial<StoredKeyPair>
+    if (
+      typeof pair.publicKey !== 'string' ||
+      !pair.publicKey ||
+      typeof pair.privateKey !== 'string' ||
+      !pair.privateKey
+    ) {
+      return null
+    }
+    return pair as StoredKeyPair
+  } catch {
+    return null
+  }
+}
 
 class SecureStoreStamperInner {
   private publicKeyHex: string | null = null
 
   async init(): Promise<void> {
-    const publicKey = await SecureStore.getItemAsync(PUBLIC_KEY)
-    const privateKey = await SecureStore.getItemAsync(PRIVATE_KEY)
+    const storedPair = parseKeyPair(await SecureStore.getItemAsync(KEY_PAIR))
+    if (storedPair && (await this.isUsable(storedPair))) {
+      this.publicKeyHex = storedPair.publicKey
+      return
+    }
+
+    const publicKey = await SecureStore.getItemAsync(LEGACY_PUBLIC_KEY)
+    const privateKey = await SecureStore.getItemAsync(LEGACY_PRIVATE_KEY)
+    if (
+      publicKey &&
+      privateKey &&
+      (await this.isUsable({ publicKey, privateKey }))
+    ) {
+      await this.persistKeyPair({ publicKey, privateKey })
+      await Promise.all([
+        SecureStore.deleteItemAsync(LEGACY_PUBLIC_KEY),
+        SecureStore.deleteItemAsync(LEGACY_PRIVATE_KEY),
+      ])
+      return
+    }
 
-    if (publicKey && privateKey) {
-      this.publicKeyHex = publicKey
-    } else {
-      await this.resetKeyPair()
+    // No usable stored credential — missing, corrupt, or mismatched (e.g. a
+    // broken key written before this validation existed). Mint a fresh pair
+    // rather than throwing: a key that fails the ownership check can't produce
+    // a valid stamp anyway, and a thrown init would brick the app — it could
+    // neither log out nor reset the stamper (both need a constructed SDK). The
+    // user simply re-authenticates from a clean state. Only validation failures
+    // land here; SecureStore I/O errors still propagate (we never discard a key
+    // just because a read/write transiently failed).
+    await this.resetKeyPair()
+  }
+
+  // True if the stored pair passes the ownership check. Isolates validation
+  // (pure crypto) from I/O so init() can distinguish an unusable key (reset)
+  // from a transient SecureStore failure (propagate).
+  private async isUsable(pair: StoredKeyPair): Promise<boolean> {
+    try {
+      await this.validateKeyPair(pair)
+      return true
+    } catch {
+      return false
     }
   }
 
@@ -24,20 +80,36 @@ class SecureStoreStamperInner {
     return this.publicKeyHex
   }
 
-  async resetKeyPair(externalKeyPair?: {
-    publicKey: string
-    privateKey: string
-  }): Promise<void> {
-    await this.clear()
-
+  async resetKeyPair(externalKeyPair?: StoredKeyPair): Promise<void> {
     const pair = externalKeyPair ?? generateP256KeyPair()
+    await this.persistKeyPair(pair)
+  }
 
-    await SecureStore.setItemAsync(PUBLIC_KEY, pair.publicKey)
-    await SecureStore.setItemAsync(PRIVATE_KEY, pair.privateKey)
-
+  private async persistKeyPair(pair: StoredKeyPair): Promise<void> {
+    await this.validateKeyPair(pair)
+    // SecureStore replaces one value atomically. Update memory only after the
+    // durable write succeeds, so a failed rotation preserves the live pair.
+    await SecureStore.setItemAsync(KEY_PAIR, JSON.stringify(pair))
     this.publicKeyHex = pair.publicKey
   }
 
+  private async validateKeyPair(pair: StoredKeyPair): Promise<void> {
+    try {
+      const signature = await new ApiKeyStamper({
+        apiPublicKey: pair.publicKey,
+        apiPrivateKey: pair.privateKey,
+      }).sign(KEY_PAIR_CHECK, SignatureFormat.Der)
+      if (
+        await verifyStampSignature(pair.publicKey, signature, KEY_PAIR_CHECK)
+      ) {
+        return
+      }
+    } catch {
+      // Normalize invalid encoding and mismatched-key failures below.
+    }
+    throw new Error('Stored public and private keys do not match.')
+  }
+
   private async getTurnkeyApiKeyStamper(): Promise<ApiKeyStamper> {
     if (!this.publicKeyHex) {
       throw new Error(
@@ -45,14 +117,14 @@ class SecureStoreStamperInner {
       )
     }
 
-    const privateKey = await SecureStore.getItemAsync(PRIVATE_KEY)
-    if (!privateKey) {
-      throw new Error('No private key found in secure store.')
+    const pair = parseKeyPair(await SecureStore.getItemAsync(KEY_PAIR))
+    if (!pair || pair.publicKey !== this.publicKeyHex) {
+      throw new Error('No matching key pair found in secure store.')
     }
 
     return new ApiKeyStamper({
       apiPublicKey: this.publicKeyHex,
-      apiPrivateKey: privateKey,
+      apiPrivateKey: pair.privateKey,
     })
   }
 
@@ -70,8 +142,13 @@ class SecureStoreStamperInner {
   }
 
   async clear(): Promise<void> {
-    await SecureStore.deleteItemAsync(PUBLIC_KEY)
-    await SecureStore.deleteItemAsync(PRIVATE_KEY)
+    // Remove legacy recovery sources first. If this fails, keep the atomic
+    // record authoritative so a later init cannot resurrect a revoked key.
+    await Promise.all([
+      SecureStore.deleteItemAsync(LEGACY_PUBLIC_KEY),
+      SecureStore.deleteItemAsync(LEGACY_PRIVATE_KEY),
+    ])
+    await SecureStore.deleteItemAsync(KEY_PAIR)
     this.publicKeyHex = null
   }
 }
@@ -117,6 +194,7 @@ export async function createSecureStoreStamper(): Promise<ZDApiKeyStamper> {
       return inner.sign(payload)
     },
     async clear() {
+      pendingKeyPair = null
       await inner.clear()
     },
     async resetKeyPair() {
@@ -128,6 +206,20 @@ export async function createSecureStoreStamper(): Promise<ZDApiKeyStamper> {
       pendingKeyPair = keyPair
       return keyPair.publicKey
     },
+    async stampPending(payload: string) {
+      if (!pendingKeyPair) throw new Error('No pending key rotation')
+      return new ApiKeyStamper({
+        apiPublicKey: pendingKeyPair.publicKey,
+        apiPrivateKey: pendingKeyPair.privateKey,
+      }).stamp(payload)
+    },
+    async signPending(payload: string) {
+      if (!pendingKeyPair) throw new Error('No pending key rotation')
+      return new ApiKeyStamper({
+        apiPublicKey: pendingKeyPair.publicKey,
+        apiPrivateKey: pendingKeyPair.privateKey,
+      }).sign(payload, SignatureFormat.Der)
+    },
     async commitKeyRotation() {
       if (!pendingKeyPair) {
         throw new Error('No pending key rotation to commit')
@@ -135,5 +227,8 @@ export async function createSecureStoreStamper(): Promise<ZDApiKeyStamper> {
       await inner.resetKeyPair(pendingKeyPair)
       pendingKeyPair = null
     },
+    async discardKeyRotation() {
+      pendingKeyPair = null
+    },
   }
 }

package/src/stampers/indexedDbStamper.ts

@@ -1,13 +1,44 @@
+import { p256 } from '@noble/curves/nist.js'
 import { IndexedDbStamper as TurnkeyIndexedDbStamper } from '@turnkey/indexed-db-stamper'
 import { generateCompressedPublicKeyFromKeyPair } from '../utils/utils.js'
 import type { ApiKeyStamper } from './types.js'
 
+async function signWithKeyPair(
+  keyPair: CryptoKeyPair,
+  payload: string,
+): Promise<string> {
+  const rawSignature = new Uint8Array(
+    await crypto.subtle.sign(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      keyPair.privateKey,
+      new TextEncoder().encode(payload),
+    ),
+  )
+  return p256.Signature.fromBytes(rawSignature, 'compact').toHex('der')
+}
+
+function encodeStamp(publicKey: string, signature: string): string {
+  const json = JSON.stringify({
+    publicKey,
+    scheme: 'SIGNATURE_SCHEME_TK_API_P256',
+    signature,
+  })
+  return btoa(json).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
 export async function createIndexedDbStamper(): Promise<ApiKeyStamper> {
   const inner = new TurnkeyIndexedDbStamper()
   await inner.init()
 
   let pendingKeyPair: CryptoKeyPair | null = null
 
+  // A rotation must be prepared before it can be stamped/signed with; centralize
+  // the guard so the pending-key paths don't each repeat it.
+  const requirePending = (): CryptoKeyPair => {
+    if (!pendingKeyPair) throw new Error('No pending key rotation')
+    return pendingKeyPair
+  }
+
   return {
     async getPublicKey() {
       return await inner.getPublicKey()
@@ -19,6 +50,7 @@ export async function createIndexedDbStamper(): Promise<ApiKeyStamper> {
       return await inner.sign(payload)
     },
     async clear() {
+      pendingKeyPair = null
       await inner.clear()
     },
     async resetKeyPair() {
@@ -34,6 +66,18 @@ export async function createIndexedDbStamper(): Promise<ApiKeyStamper> {
       pendingKeyPair = keyPair
       return await generateCompressedPublicKeyFromKeyPair(keyPair)
     },
+    async stampPending(payload: string) {
+      const keyPair = requirePending()
+      const publicKey = await generateCompressedPublicKeyFromKeyPair(keyPair)
+      const signature = await signWithKeyPair(keyPair, payload)
+      return {
+        stampHeaderName: 'X-Stamp',
+        stampHeaderValue: encodeStamp(publicKey, signature),
+      }
+    },
+    async signPending(payload: string) {
+      return signWithKeyPair(requirePending(), payload)
+    },
     async commitKeyRotation() {
       if (!pendingKeyPair) {
         throw new Error('No pending key rotation to commit')
@@ -41,5 +85,8 @@ export async function createIndexedDbStamper(): Promise<ApiKeyStamper> {
       await inner.resetKeyPair(pendingKeyPair)
       pendingKeyPair = null
     },
+    async discardKeyRotation() {
+      pendingKeyPair = null
+    },
   }
 }

package/src/stampers/types.ts

@@ -37,8 +37,14 @@ export type ApiKeyStamper = Stamper & {
   resetKeyPair: () => Promise<void>
   /** Generate a new key pair internally, return its compressed public key, but keep the OLD key active for stamp(). */
   prepareKeyRotation: () => Promise<string>
+  /** Stamp with the prepared key without making it active. */
+  stampPending: (payload: string) => Promise<Stamp>
+  /** Sign with the prepared key without making it active. */
+  signPending: (payload: string) => Promise<string>
   /** Promote the pending key to active. Call after the server accepts the new key. */
   commitKeyRotation: () => Promise<void>
+  /** Forget the prepared key while keeping the active key untouched. */
+  discardKeyRotation: () => 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/storage/manager.ts

@@ -20,31 +20,114 @@ export type StorageManager = {
   setActiveSession(sessionKey: string): Promise<void>
   clearSession(sessionKey: string): Promise<void>
   clearAllSessions(): Promise<void>
+  stageSessionTransition(
+    sessionData: ZeroDevWalletSession,
+    publicKey: string,
+  ): Promise<void>
+  commitSessionTransition(): Promise<ZeroDevWalletSession | undefined>
+  recoverSessionTransition(
+    activePublicKey: string | null,
+  ): Promise<ZeroDevWalletSession | undefined>
+}
+
+type SessionTransition = {
+  sessionData: ZeroDevWalletSession
+  publicKey: string
+}
+
+// Process-wide serialization queue for storage mutations. Every mutating op
+// runs through `withMutation`, which chains onto this tail so read-modify-write
+// sequences over the shared active-session pointer and session list can't
+// interleave and corrupt each other. Module-level (not per-manager) so
+// concurrent managers over the same storage still serialize; the tail swallows
+// each outcome so one failed mutation never jams the queue.
+let mutationTail = Promise.resolve()
+
+function isStoredSession(value: unknown): value is ZeroDevWalletSession {
+  if (!value || typeof value !== 'object') return false
+  const session = value as Partial<ZeroDevWalletSession>
+  return (
+    typeof session.id === 'string' &&
+    typeof session.userId === 'string' &&
+    typeof session.organizationId === 'string' &&
+    (session.stamperType === 'apiKey' || session.stamperType === 'passkey') &&
+    typeof session.token === 'string' &&
+    session.token.length > 0 &&
+    typeof session.expiry === 'number' &&
+    Number.isFinite(session.expiry) &&
+    session.expiry > 0 &&
+    typeof session.createdAt === 'number' &&
+    Number.isFinite(session.createdAt)
+  )
 }
 
 export function createStorageManager(adapter: StorageAdapter): StorageManager {
   const ACTIVE_SESSION_KEY = '@zerodev/active_session'
   const ALL_SESSIONS_KEY = '@zerodev/sessions'
+  const SESSION_TRANSITION_KEY = '@zerodev/session_transition'
 
-  const storeSession = async (
+  const withMutation = async <T>(mutation: () => Promise<T>): Promise<T> => {
+    const result = mutationTail.then(mutation)
+    mutationTail = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    return result
+  }
+
+  const parseSessionKeys = (value: string | null): string[] | undefined => {
+    if (!value) return []
+    try {
+      const parsed: unknown = JSON.parse(value)
+      if (
+        !Array.isArray(parsed) ||
+        !parsed.every((key): key is string => typeof key === 'string')
+      ) {
+        return undefined
+      }
+      return parsed
+    } catch {
+      return undefined
+    }
+  }
+
+  const restoreItem = async (key: string, value: string | null) => {
+    if (value === null) await adapter.removeItem(key)
+    else await adapter.setItem(key, value)
+  }
+
+  const storeSessionUnlocked = async (
     sessionData: ZeroDevWalletSession,
     sessionKey: string,
   ): Promise<void> => {
-    // Store the session data
-    await adapter.setItem(sessionKey, JSON.stringify(sessionData))
-
-    // Add to sessions list if not already present
-    const sessionsStr = await adapter.getItem(ALL_SESSIONS_KEY)
-    const sessions = JSON.parse(sessionsStr || '[]')
-    if (!sessions.includes(sessionKey)) {
-      sessions.push(sessionKey)
+    const recordKey = sessionKey
+    const [previousRecord, previousIndex, previousActive] = await Promise.all([
+      adapter.getItem(recordKey),
+      adapter.getItem(ALL_SESSIONS_KEY),
+      adapter.getItem(ACTIVE_SESSION_KEY),
+    ])
+    try {
+      await adapter.setItem(recordKey, JSON.stringify(sessionData))
+      const sessions = parseSessionKeys(previousIndex) ?? []
+      if (!sessions.includes(sessionKey)) sessions.push(sessionKey)
       await adapter.setItem(ALL_SESSIONS_KEY, JSON.stringify(sessions))
+      await adapter.setItem(ACTIVE_SESSION_KEY, sessionKey)
+    } catch (error) {
+      await Promise.allSettled([
+        restoreItem(recordKey, previousRecord),
+        restoreItem(ALL_SESSIONS_KEY, previousIndex),
+        restoreItem(ACTIVE_SESSION_KEY, previousActive),
+      ])
+      throw error
     }
-
-    // Set as active session
-    await adapter.setItem(ACTIVE_SESSION_KEY, sessionKey)
   }
 
+  const storeSession = async (
+    sessionData: ZeroDevWalletSession,
+    sessionKey: string,
+  ): Promise<void> =>
+    withMutation(() => storeSessionUnlocked(sessionData, sessionKey))
+
   const getActiveSession = async (): Promise<
     ZeroDevWalletSession | undefined
   > => {
@@ -66,10 +149,14 @@ export function createStorageManager(adapter: StorageAdapter): StorageManager {
     if (!sessionStr) return undefined
 
     try {
-      const session: ZeroDevWalletSession = JSON.parse(sessionStr)
+      const session: unknown = JSON.parse(sessionStr)
+      if (!isStoredSession(session)) {
+        await clearSession(sessionKey)
+        return undefined
+      }
 
       // Check if session is expired
-      if (session.expiry && normalizeTimestamp(session.expiry) < Date.now()) {
+      if (normalizeTimestamp(session.expiry) < Date.now()) {
         await clearSession(sessionKey)
         return undefined
       }
@@ -82,13 +169,17 @@ export function createStorageManager(adapter: StorageAdapter): StorageManager {
     }
   }
 
-  const listSessionKeys = async (): Promise<string[]> => {
+  const listSessionKeysUnlocked = async (): Promise<string[]> => {
     const sessionsStr = await adapter.getItem(ALL_SESSIONS_KEY)
-    const sessionKeys = JSON.parse(sessionsStr || '[]')
+    const parsedKeys = parseSessionKeys(sessionsStr)
+    if (!parsedKeys) {
+      await adapter.removeItem(ALL_SESSIONS_KEY)
+      return []
+    }
 
     // Clean up any keys that don't have corresponding sessions
     const validKeys: string[] = []
-    for (const key of sessionKeys) {
+    for (const key of parsedKeys) {
       const exists = await adapter.getItem(key)
       if (exists) {
         validKeys.push(key)
@@ -96,13 +187,16 @@ export function createStorageManager(adapter: StorageAdapter): StorageManager {
     }
 
     // Update the list if we found invalid keys
-    if (validKeys.length !== sessionKeys.length) {
+    if (validKeys.length !== parsedKeys.length) {
       await adapter.setItem(ALL_SESSIONS_KEY, JSON.stringify(validKeys))
     }
 
     return validKeys
   }
 
+  const listSessionKeys = async (): Promise<string[]> =>
+    withMutation(listSessionKeysUnlocked)
+
   const listSessions = async (): Promise<ZeroDevWalletSession[]> => {
     const sessionKeys = await listSessionKeys()
     const sessions: ZeroDevWalletSession[] = []
@@ -124,15 +218,17 @@ export function createStorageManager(adapter: StorageAdapter): StorageManager {
       throw new Error(`Session not found: ${sessionKey}`)
     }
 
-    await adapter.setItem(ACTIVE_SESSION_KEY, sessionKey)
+    await withMutation(async () => {
+      await adapter.setItem(ACTIVE_SESSION_KEY, sessionKey)
+    })
   }
 
-  const clearSession = async (sessionKey: string): Promise<void> => {
+  const clearSessionUnlocked = async (sessionKey: string): Promise<void> => {
     // Remove the session data
     await adapter.removeItem(sessionKey)
 
     // Remove from sessions list
-    const sessions = await listSessionKeys()
+    const sessions = await listSessionKeysUnlocked()
     const updated = sessions.filter((k) => k !== sessionKey)
     await adapter.setItem(ALL_SESSIONS_KEY, JSON.stringify(updated))
 
@@ -143,19 +239,100 @@ export function createStorageManager(adapter: StorageAdapter): StorageManager {
     }
   }
 
-  const clearAllSessions = async (): Promise<void> => {
-    const sessions = await listSessionKeys()
+  const clearSession = async (sessionKey: string): Promise<void> =>
+    withMutation(() => clearSessionUnlocked(sessionKey))
+
+  const clearAllSessions = async (): Promise<void> =>
+    withMutation(async () => {
+      await clearAllSessionsUnlocked()
+      await adapter.removeItem(SESSION_TRANSITION_KEY)
+    })
+
+  async function clearAllSessionsUnlocked(): Promise<void> {
+    const sessions = await listSessionKeysUnlocked()
 
-    // Remove all session data
     for (const key of sessions) {
       await adapter.removeItem(key)
     }
 
-    // Clear the metadata
     await adapter.removeItem(ALL_SESSIONS_KEY)
     await adapter.removeItem(ACTIVE_SESSION_KEY)
   }
 
+  const parseTransition = (value: string | null): SessionTransition | null => {
+    if (!value) return null
+    try {
+      const parsed = JSON.parse(value) as Partial<SessionTransition>
+      if (
+        !isStoredSession(parsed.sessionData) ||
+        typeof parsed.publicKey !== 'string' ||
+        !parsed.publicKey
+      ) {
+        return null
+      }
+      return parsed as SessionTransition
+    } catch {
+      return null
+    }
+  }
+
+  const stageSessionTransition = async (
+    sessionData: ZeroDevWalletSession,
+    publicKey: string,
+  ): Promise<void> =>
+    withMutation(async () => {
+      await adapter.setItem(
+        SESSION_TRANSITION_KEY,
+        JSON.stringify({ sessionData, publicKey }),
+      )
+    })
+
+  const commitSessionTransition = async (): Promise<
+    ZeroDevWalletSession | undefined
+  > =>
+    withMutation(async () => {
+      const transition = parseTransition(
+        await adapter.getItem(SESSION_TRANSITION_KEY),
+      )
+      if (!transition) {
+        await adapter.removeItem(SESSION_TRANSITION_KEY)
+        return undefined
+      }
+
+      await clearAllSessionsUnlocked()
+      await storeSessionUnlocked(
+        transition.sessionData,
+        transition.sessionData.id,
+      )
+      await adapter.removeItem(SESSION_TRANSITION_KEY)
+      return transition.sessionData
+    })
+
+  const normalizeKey = (key: string) => key.replace(/^0x/, '').toLowerCase()
+
+  const recoverSessionTransition = async (
+    activePublicKey: string | null,
+  ): Promise<ZeroDevWalletSession | undefined> => {
+    const transition = parseTransition(
+      await adapter.getItem(SESSION_TRANSITION_KEY),
+    )
+    if (!transition) {
+      if (await adapter.getItem(SESSION_TRANSITION_KEY)) {
+        await adapter.removeItem(SESSION_TRANSITION_KEY)
+      }
+      return undefined
+    }
+    if (!activePublicKey) {
+      await adapter.removeItem(SESSION_TRANSITION_KEY)
+      return undefined
+    }
+    if (normalizeKey(activePublicKey) !== normalizeKey(transition.publicKey)) {
+      await adapter.removeItem(SESSION_TRANSITION_KEY)
+      return undefined
+    }
+    return commitSessionTransition()
+  }
+
   return {
     storeSession,
     getActiveSession,
@@ -166,5 +343,8 @@ export function createStorageManager(adapter: StorageAdapter): StorageManager {
     setActiveSession,
     clearSession,
     clearAllSessions,
+    stageSessionTransition,
+    commitSessionTransition,
+    recoverSessionTransition,
   }
 }

package/src/types/session.ts

@@ -12,6 +12,8 @@ export type ZeroDevWalletSession = {
   stamperType: StamperType
   sessionType?: SessionType
   token: string
+  /** Public key bound into the session JWT; persisted for crash recovery. */
+  publicKey?: string
   expiry: number
   createdAt: number
 }

package/src/utils/buildClientSignature.ts

@@ -7,7 +7,7 @@ export type BuildClientSignatureParams = {
   /** The compressed public key hex */
   publicKey: string
   /** The API key stamper for signing */
-  stamper: ApiKeyStamper
+  stamper: Pick<ApiKeyStamper, 'stamp'>
 }
 
 /**
@@ -64,7 +64,9 @@ function extractTokenIdFromJwt(jwt: string): string {
     throw new Error('Invalid JWT format')
   }
 
-  const payload = JSON.parse(base64UrlDecode(parts[1]!))
+  const encodedPayload = parts[1]
+  if (!encodedPayload) throw new Error('Invalid JWT format')
+  const payload = JSON.parse(base64UrlDecode(encodedPayload))
   if (!payload.id) {
     throw new Error('JWT payload missing id field')
   }