@zerodev/wallet-core 0.0.1-alpha.10

package/src/stampers/webauthnStamper.ts

@@ -0,0 +1,21 @@
+import { WebauthnStamper as TurnkeyWebauthnStamper } from '@turnkey/webauthn-stamper'
+import type { WebauthnStamper } from './types.js'
+
+export async function createWebauthnStamper({
+  rpId,
+}: {
+  rpId: string
+}): Promise<WebauthnStamper> {
+  const inner = new TurnkeyWebauthnStamper({ rpId })
+
+  return {
+    async getPublicKey() {
+      //   return await inner.();
+      return null
+    },
+    async stamp(payload: string) {
+      return await inner.stamp(payload)
+    },
+    async clear() {},
+  }
+}

package/src/storage/adapters.ts

@@ -0,0 +1,20 @@
+import WindowWrapper from '../polyfills/window.js'
+import type { StorageAdapter } from './manager.js'
+
+export function createWebStorageAdapter(
+  storage: Storage = WindowWrapper.localStorage,
+): StorageAdapter {
+  return {
+    getItem(key: string): string | null {
+      return storage.getItem(key)
+    },
+
+    setItem(key: string, value: string): void {
+      storage.setItem(key, value)
+    },
+
+    removeItem(key: string): void {
+      storage.removeItem(key)
+    },
+  }
+}

package/src/storage/manager.ts

@@ -0,0 +1,170 @@
+import type { ZeroDevWalletSession } from '../types/session.js'
+import { normalizeTimestamp } from '../utils/utils.js'
+
+export type StorageAdapter = {
+  getItem(key: string): string | null | Promise<string | null>
+  setItem(key: string, value: string): void | Promise<void>
+  removeItem(key: string): void | Promise<void>
+}
+
+export type StorageManager = {
+  storeSession(
+    sessionData: ZeroDevWalletSession,
+    sessionKey: string,
+  ): Promise<void>
+  getActiveSession(): Promise<ZeroDevWalletSession | undefined>
+  getActiveSessionKey(): Promise<string | undefined>
+  getSession(sessionKey: string): Promise<ZeroDevWalletSession | undefined>
+  listSessionKeys(): Promise<string[]>
+  listSessions(): Promise<ZeroDevWalletSession[]>
+  setActiveSession(sessionKey: string): Promise<void>
+  clearSession(sessionKey: string): Promise<void>
+  clearAllSessions(): Promise<void>
+}
+
+export function createStorageManager(adapter: StorageAdapter): StorageManager {
+  const ACTIVE_SESSION_KEY = '@zerodev/active_session'
+  const ALL_SESSIONS_KEY = '@zerodev/sessions'
+
+  const storeSession = 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)
+      await adapter.setItem(ALL_SESSIONS_KEY, JSON.stringify(sessions))
+    }
+
+    // Set as active session
+    await adapter.setItem(ACTIVE_SESSION_KEY, sessionKey)
+  }
+
+  const getActiveSession = async (): Promise<
+    ZeroDevWalletSession | undefined
+  > => {
+    const activeKey = await adapter.getItem(ACTIVE_SESSION_KEY)
+    if (!activeKey) return undefined
+
+    return getSession(activeKey)
+  }
+
+  const getActiveSessionKey = async (): Promise<string | undefined> => {
+    const key = await adapter.getItem(ACTIVE_SESSION_KEY)
+    return key || undefined
+  }
+
+  const getSession = async (
+    sessionKey: string,
+  ): Promise<ZeroDevWalletSession | undefined> => {
+    const sessionStr = await adapter.getItem(sessionKey)
+    if (!sessionStr) return undefined
+
+    try {
+      const session: ZeroDevWalletSession = JSON.parse(sessionStr)
+
+      // Check if session is expired
+      if (session.expiry && normalizeTimestamp(session.expiry) < Date.now()) {
+        await clearSession(sessionKey)
+        return undefined
+      }
+
+      return session
+    } catch (_error) {
+      // Invalid JSON, clean up
+      await clearSession(sessionKey)
+      return undefined
+    }
+  }
+
+  const listSessionKeys = async (): Promise<string[]> => {
+    const sessionsStr = await adapter.getItem(ALL_SESSIONS_KEY)
+    const sessionKeys = JSON.parse(sessionsStr || '[]')
+
+    // Clean up any keys that don't have corresponding sessions
+    const validKeys: string[] = []
+    for (const key of sessionKeys) {
+      const exists = await adapter.getItem(key)
+      if (exists) {
+        validKeys.push(key)
+      }
+    }
+
+    // Update the list if we found invalid keys
+    if (validKeys.length !== sessionKeys.length) {
+      await adapter.setItem(ALL_SESSIONS_KEY, JSON.stringify(validKeys))
+    }
+
+    return validKeys
+  }
+
+  const listSessions = async (): Promise<ZeroDevWalletSession[]> => {
+    const sessionKeys = await listSessionKeys()
+    const sessions: ZeroDevWalletSession[] = []
+
+    for (const key of sessionKeys) {
+      const session = await getSession(key)
+      if (session) {
+        sessions.push(session)
+      }
+    }
+
+    return sessions
+  }
+
+  const setActiveSession = async (sessionKey: string): Promise<void> => {
+    // Verify the session exists
+    const session = await getSession(sessionKey)
+    if (!session) {
+      throw new Error(`Session not found: ${sessionKey}`)
+    }
+
+    await adapter.setItem(ACTIVE_SESSION_KEY, sessionKey)
+  }
+
+  const clearSession = async (sessionKey: string): Promise<void> => {
+    // Remove the session data
+    await adapter.removeItem(sessionKey)
+
+    // Remove from sessions list
+    const sessions = await listSessionKeys()
+    const updated = sessions.filter((k) => k !== sessionKey)
+    await adapter.setItem(ALL_SESSIONS_KEY, JSON.stringify(updated))
+
+    // Clear active session if it was the cleared one
+    const activeKey = await adapter.getItem(ACTIVE_SESSION_KEY)
+    if (activeKey === sessionKey) {
+      await adapter.removeItem(ACTIVE_SESSION_KEY)
+    }
+  }
+
+  const clearAllSessions = async (): Promise<void> => {
+    const sessions = await listSessionKeys()
+
+    // 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)
+  }
+
+  return {
+    storeSession,
+    getActiveSession,
+    getActiveSessionKey,
+    getSession,
+    listSessionKeys,
+    listSessions,
+    setActiveSession,
+    clearSession,
+    clearAllSessions,
+  }
+}

package/src/types/session.ts

@@ -0,0 +1,18 @@
+export enum SessionType {
+  READ_ONLY = 'SESSION_TYPE_READ_ONLY',
+  READ_WRITE = 'SESSION_TYPE_READ_WRITE',
+}
+
+export type StamperType = 'iframe' | 'indexedDb' | 'passkey'
+
+export type ZeroDevWalletSession = {
+  id: string
+  userId: string
+  organizationId: string
+  stamperType: StamperType
+  sessionType?: SessionType
+  token?: string
+  publicKey?: string
+  expiry: number
+  createdAt: number
+}

package/src/utils/buildClientSignature.ts

@@ -0,0 +1,86 @@
+import type { IndexedDbStamper } from '../stampers/types.js'
+import { derToRawSignature } from './derToRawSignature.js'
+
+export type BuildClientSignatureParams = {
+  /** The verification token JWT from Auth Proxy's verifyOtp */
+  verificationToken: string
+  /** The compressed public key hex */
+  publicKey: string
+  /** The IndexedDB stamper for signing */
+  stamper: IndexedDbStamper
+}
+
+/**
+ * Builds a client signature for OTP login.
+ *
+ * Steps:
+ * 1. Decode verificationToken JWT to extract `id` field as tokenId
+ * 2. Build message: JSON.stringify({ login: { publicKey }, tokenId, type: "USAGE_TYPE_LOGIN" })
+ * 3. Sign message with stamper → get stampHeaderValue
+ * 4. Parse stampHeaderValue → extract DER signature hex
+ * 5. Convert DER to raw r||s format
+ * 6. Return raw signature hex
+ *
+ * @param params - The parameters for building the client signature
+ * @returns The raw r||s signature hex (64 bytes = 128 chars)
+ */
+export async function buildClientSignature(
+  params: BuildClientSignatureParams,
+): Promise<string> {
+  const { verificationToken, publicKey, stamper } = params
+
+  // Step 1: Extract tokenId from verification token JWT payload
+  const tokenId = extractTokenIdFromJwt(verificationToken)
+
+  // Step 2: Build the signature payload message
+  const signaturePayload = {
+    login: { publicKey },
+    tokenId,
+    type: 'USAGE_TYPE_LOGIN',
+  }
+  const message = JSON.stringify(signaturePayload)
+
+  // Step 3: Sign the message using the stamper
+  const stamp = await stamper.stamp(message)
+
+  // Step 4: Parse the stamp to extract the DER signature
+  // The stampHeaderValue is base64url encoded JSON containing the signature
+  const stampData = JSON.parse(base64UrlDecode(stamp.stampHeaderValue))
+  const derSignatureHex: string = stampData.signature
+
+  // Step 5: Convert DER signature to raw r||s format
+  const rawSignature = derToRawSignature(derSignatureHex)
+
+  // Step 6: Return raw signature hex
+  return rawSignature
+}
+
+/**
+ * Extracts the token ID (id field) from a JWT's payload
+ */
+function extractTokenIdFromJwt(jwt: string): string {
+  const parts = jwt.split('.')
+  if (parts.length !== 3) {
+    throw new Error('Invalid JWT format')
+  }
+
+  const payload = JSON.parse(base64UrlDecode(parts[1]!))
+  if (!payload.id) {
+    throw new Error('JWT payload missing id field')
+  }
+
+  return payload.id
+}
+
+/**
+ * Decodes a base64url encoded string
+ */
+function base64UrlDecode(str: string): string {
+  // Add padding if necessary
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/')
+  const padding = base64.length % 4
+  if (padding) {
+    base64 += '='.repeat(4 - padding)
+  }
+  return atob(base64)
+}

package/src/utils/derToRawSignature.ts

@@ -0,0 +1,103 @@
+/**
+ * Converts a DER-encoded ECDSA signature to raw r||s format.
+ *
+ * DER format: 0x30 [length] 0x02 [r-length] [r] 0x02 [s-length] [s]
+ * Raw format: [r (32 bytes)] [s (32 bytes)]
+ *
+ * @param derHex - The DER-encoded signature as a hex string
+ * @returns The raw signature as a hex string (r||s, 64 bytes = 128 chars)
+ */
+export function derToRawSignature(derHex: string): string {
+  const der = hexToBytes(derHex)
+
+  // Verify SEQUENCE tag (0x30)
+  if (der[0] !== 0x30) {
+    throw new Error('Invalid DER signature: expected SEQUENCE tag (0x30)')
+  }
+
+  let offset = 2 // Skip SEQUENCE tag and length
+
+  // Parse r INTEGER
+  if (der[offset] !== 0x02) {
+    throw new Error('Invalid DER signature: expected INTEGER tag (0x02) for r')
+  }
+  offset++ // Skip INTEGER tag
+
+  const rLength = der[offset]!
+  offset++ // Skip length byte
+
+  const rBytes = der.slice(offset, offset + rLength)
+  offset += rLength
+
+  // Parse s INTEGER
+  if (der[offset] !== 0x02) {
+    throw new Error('Invalid DER signature: expected INTEGER tag (0x02) for s')
+  }
+  offset++ // Skip INTEGER tag
+
+  const sLength = der[offset]!
+  offset++ // Skip length byte
+
+  const sBytes = der.slice(offset, offset + sLength)
+
+  // Remove leading zero bytes if present (DER uses signed integers)
+  // and pad to 32 bytes
+  const r = padTo32Bytes(stripLeadingZeros(rBytes))
+  const s = padTo32Bytes(stripLeadingZeros(sBytes))
+
+  // Concatenate r || s
+  const raw = new Uint8Array(64)
+  raw.set(r, 0)
+  raw.set(s, 32)
+
+  return bytesToHex(raw)
+}
+
+/**
+ * Converts a hex string to a Uint8Array
+ */
+function hexToBytes(hex: string): Uint8Array {
+  const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex
+  const bytes = new Uint8Array(cleanHex.length / 2)
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleanHex.slice(i * 2, i * 2 + 2), 16)
+  }
+  return bytes
+}
+
+/**
+ * Converts a Uint8Array to a hex string (no 0x prefix)
+ */
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/**
+ * Strips leading zero bytes from a byte array
+ * DER integers are signed, so positive numbers may have a leading 0x00
+ */
+function stripLeadingZeros(bytes: Uint8Array): Uint8Array {
+  let start = 0
+  while (start < bytes.length - 1 && bytes[start] === 0) {
+    start++
+  }
+  return bytes.slice(start)
+}
+
+/**
+ * Pads a byte array to 32 bytes (left-padded with zeros)
+ */
+function padTo32Bytes(bytes: Uint8Array): Uint8Array {
+  if (bytes.length === 32) {
+    return bytes
+  }
+  if (bytes.length > 32) {
+    // This shouldn't happen for P-256, but handle it gracefully
+    return bytes.slice(bytes.length - 32)
+  }
+  const padded = new Uint8Array(32)
+  padded.set(bytes, 32 - bytes.length)
+  return padded
+}

package/src/utils/exportPrivateKey.ts

@@ -0,0 +1,116 @@
+import type { ZeroDevWalletSDK } from '../core/createZeroDevWallet.js'
+import type { KeyFormat } from '../stampers/types.js'
+
+export type ExportPrivateKeyParameters = {
+  /** Wallet to use for the export */
+  wallet: ZeroDevWalletSDK
+  /** Target public key from export iframe for encryption */
+  targetPublicKey: string
+  /** Wallet address to export (optional, defaults to wallet's account address) */
+  address?: string
+}
+
+/**
+ * Export a wallet account's private key
+ *
+ * This calls Turnkey's export_wallet_account API to get an encrypted bundle
+ * containing the account's private key. The bundle is encrypted with the
+ * targetPublicKey (from Turnkey's export iframe).
+ *
+ * @param params - Export parameters
+ * @returns Encrypted export bundle and metadata
+ *
+ * @example
+ * ```ts
+ * // In UI: Initialize export iframe first
+ * const iframeStamper = await createIframeStamper({
+ *   iframeUrl: 'https://export.turnkey.com',
+ *   iframeContainer: document.getElementById('export-container'),
+ *   iframeElementId: 'export-iframe'
+ * });
+ * const targetPublicKey = await iframeStamper.init();
+ *
+ * // Call SDK to get encrypted bundle
+ * const { exportBundle, address, organizationId } = await exportPrivateKey({
+ *   wallet,
+ *   targetPublicKey
+ * });
+ *
+ * // Inject into iframe to display private key
+ * await iframeStamper.injectKeyExportBundle(exportBundle, organizationId, 'Hexadecimal');
+ * ```
+ */
+export async function exportPrivateKey(
+  params: ExportPrivateKeyParameters,
+): Promise<{ exportBundle: string; address: string; organizationId: string }> {
+  const { targetPublicKey, wallet, address: addressParam } = params
+
+  const session = await wallet.getSession()
+  if (!session) {
+    throw new Error('Session not found')
+  }
+  const { organizationId } = session
+
+  // If address not provided, get it from the wallet's account
+  let address = addressParam
+  if (!address) {
+    const account = await wallet.toAccount()
+    if (!account?.address) {
+      throw new Error('Could not get address from wallet account')
+    }
+    address = account.address
+  }
+
+  const exportBody = JSON.stringify({
+    type: 'ACTIVITY_TYPE_EXPORT_WALLET_ACCOUNT',
+    timestampMs: Date.now().toString(),
+    organizationId: organizationId,
+    parameters: {
+      address: address,
+      targetPublicKey,
+    },
+  })
+
+  const stamperKey =
+    session.stamperType === 'indexedDb' ? 'indexedDbStamper' : 'webauthnStamper'
+  const stamper = wallet.client[stamperKey]
+  if (!stamper) {
+    throw new Error(`Stamper '${stamperKey}' not found on wallet.client`)
+  }
+
+  const exportStamp = await stamper.stamp(exportBody)
+  if (!exportStamp) {
+    throw new Error('Failed to stamp export body')
+  }
+
+  const exportResponse = await fetch(
+    'https://api.turnkey.com/public/v1/submit/export_wallet_account',
+    {
+      method: 'POST',
+      body: exportBody,
+      headers: {
+        [exportStamp.stampHeaderName]: exportStamp.stampHeaderValue,
+      },
+    },
+  )
+  if (!exportResponse.ok) {
+    const errorText = await exportResponse.text()
+    throw new Error(
+      `Failed to export wallet account: ${exportResponse.status} ${errorText}`,
+    )
+  }
+  const exportData = await exportResponse.json()
+
+  const exportBundle =
+    exportData?.activity?.result?.exportWalletAccountResult?.exportBundle
+
+  if (!exportBundle) {
+    throw new Error(
+      `Export bundle not found in response: ${JSON.stringify(exportData)}`,
+    )
+  }
+
+  return { exportBundle, address: address!, organizationId }
+}
+
+export type { KeyFormat }

package/src/utils/exportWallet.ts

@@ -0,0 +1,130 @@
+import type { ZeroDevWalletSDK } from '../core/createZeroDevWallet.js'
+
+export type ExportWalletParameters = {
+  /** Wallet to use for the export */
+  wallet: ZeroDevWalletSDK
+  /** Target public key from export iframe for encryption */
+  targetPublicKey: string
+}
+
+/**
+ * TODO: Add it as standard action in the SDK when backend is ready
+ * Export a wallet's seed phrase
+ *
+ * This calls Turnkey's export_wallet API to get an encrypted bundle
+ * containing the wallet's mnemonic. The bundle is encrypted with the
+ * targetPublicKey (from Turnkey's export iframe).
+ *
+ * @param params - Export parameters
+ * @returns Encrypted export bundle
+ *
+ * @example
+ * ```ts
+ * // In UI: Initialize export iframe first
+ * const iframeStamper = await createIframeStamper({
+ *   iframeUrl: 'https://export.turnkey.com',
+ *   iframeContainer: document.getElementById('export-container'),
+ *   iframeElementId: 'export-iframe'
+ * });
+ * const targetPublicKey = await iframeStamper.init();
+ *
+ * // Call SDK to get encrypted bundle
+ * const exportBundle = await exportWallet({
+ *   wallet,
+ *   targetPublicKey
+ * });
+ *
+ * // Inject into iframe to display seed phrase
+ * await iframeStamper.injectWalletExportBundle(exportBundle, organizationId);
+ * ```
+ */
+export async function exportWallet(
+  params: ExportWalletParameters,
+): Promise<{ exportBundle: string; walletId: string; organizationId: string }> {
+  const { targetPublicKey, wallet } = params
+
+  try {
+    const session = await wallet.getSession()
+    if (!session) {
+      throw new Error('Session not found')
+    }
+    const { organizationId } = session
+
+    const listWalletsBody = JSON.stringify({
+      organizationId,
+    })
+
+    const listWalletsStamp =
+      await wallet.client[
+        session.stamperType === 'indexedDb'
+          ? 'indexedDbStamper'
+          : 'webauthnStamper'
+      ].stamp(listWalletsBody)
+    if (!listWalletsStamp) {
+      throw new Error('Failed to stamp list wallets body')
+    }
+
+    const listWalletsResponse = await fetch(
+      'https://api.turnkey.com/public/v1/query/list_wallets',
+      {
+        method: 'POST',
+        body: listWalletsBody,
+        headers: {
+          [listWalletsStamp.stampHeaderName]: listWalletsStamp.stampHeaderValue,
+        },
+      },
+    )
+    if (!listWalletsResponse.ok) {
+      throw new Error('Failed to list wallets')
+    }
+    const listWalletsData = await listWalletsResponse.json()
+
+    const walletId = listWalletsData.wallets[0].walletId
+
+    const exportWalletBody = JSON.stringify({
+      type: 'ACTIVITY_TYPE_EXPORT_WALLET',
+      timestampMs: Date.now().toString(),
+      organizationId: organizationId,
+      parameters: {
+        walletId: walletId,
+        targetPublicKey,
+        language: 'MNEMONIC_LANGUAGE_ENGLISH',
+      },
+    })
+    const exportWalletStamp =
+      await wallet.client[
+        session.stamperType === 'indexedDb'
+          ? 'indexedDbStamper'
+          : 'webauthnStamper'
+      ].stamp(exportWalletBody)
+    if (!exportWalletStamp) {
+      throw new Error('Failed to stamp export wallet body')
+    }
+    const exportWalletResponse = await fetch(
+      'https://api.turnkey.com/public/v1/submit/export_wallet',
+      {
+        method: 'POST',
+        body: exportWalletBody,
+        headers: {
+          [exportWalletStamp.stampHeaderName]:
+            exportWalletStamp.stampHeaderValue,
+        },
+      },
+    )
+    if (!exportWalletResponse.ok) {
+      throw new Error('Failed to export wallet')
+    }
+    const exportWalletData = await exportWalletResponse.json()
+
+    const exportBundle =
+      exportWalletData?.activity?.result?.exportWalletResult?.exportBundle
+
+    if (!exportBundle) {
+      throw new Error('Export bundle not found in response')
+    }
+
+    return { exportBundle, walletId, organizationId }
+  } catch (_) {
+    throw new Error('Error exporting wallet')
+  }
+}