@zerodev/wallet-core 0.0.1-alpha.3

package/src/stampers/iframeStamper.ts

@@ -0,0 +1,35 @@
+import { IframeStamper as TurnkeyIframeStamper } from '@turnkey/iframe-stamper'
+import type { IframeStamper } from './types.js'
+
+export async function createIframeStamper(cfg: {
+  iframeUrl: string
+  iframeContainer: HTMLElement | null | undefined
+  iframeElementId: string
+}): Promise<IframeStamper> {
+  const inner = new TurnkeyIframeStamper({
+    iframeUrl: cfg.iframeUrl,
+    iframeContainer: cfg.iframeContainer,
+    iframeElementId: cfg.iframeElementId,
+  })
+
+  return {
+    async init() {
+      return await inner.init()
+    },
+    async injectCredentialBundle(bundle: string) {
+      return await inner.injectCredentialBundle(bundle)
+    },
+    async getPublicKey() {
+      return await inner.getEmbeddedPublicKey()
+    },
+    async stamp(payload: string) {
+      return await inner.stamp(payload)
+    },
+    async clear() {
+      await inner.clear()
+    },
+    async injectWalletExportBundle(bundle: string, organizationId: string) {
+      return await inner.injectWalletExportBundle(bundle, organizationId)
+    },
+  }
+}

package/src/stampers/index.ts

@@ -0,0 +1,8 @@
+export { createIframeStamper } from './iframeStamper.js'
+export { createIndexedDbStamper } from './indexedDbStamper.js'
+export type {
+  IframeStamper,
+  IndexedDbStamper,
+  WebauthnStamper,
+} from './types.js'
+export { createWebauthnStamper } from './webauthnStamper.js'

package/src/stampers/indexedDbStamper.ts

@@ -0,0 +1,22 @@
+import { IndexedDbStamper as TurnkeyIndexedDbStamper } from '@turnkey/indexed-db-stamper'
+import type { IndexedDbStamper } from './types.js'
+
+export async function createIndexedDbStamper(): Promise<IndexedDbStamper> {
+  const inner = new TurnkeyIndexedDbStamper()
+  await inner.init()
+
+  return {
+    async getPublicKey() {
+      return await inner.getPublicKey()
+    },
+    async stamp(payload: string) {
+      return await inner.stamp(payload)
+    },
+    async clear() {
+      await inner.clear()
+    },
+    async resetKeyPair(externalKeyPair?: CryptoKeyPair) {
+      await inner.resetKeyPair(externalKeyPair)
+    },
+  }
+}

package/src/stampers/types.ts

@@ -0,0 +1,28 @@
+/** Base stamper that transport depends on */
+export type Stamp = {
+  stampHeaderName: string
+  stampHeaderValue: string
+}
+
+export type Stamper = {
+  /** retrieve public key compressed or otherwise as per the stamper */
+  getPublicKey: () => Promise<string | null>
+  /** produce Turnkey header value for a given request body */
+  stamp: (payload: string) => Promise<Stamp>
+  /** clear local state (embedded key, IDB keypair, etc.) */
+  clear: () => Promise<void>
+}
+
+export type IframeStamper = Stamper & {
+  init(): Promise<string>
+  injectCredentialBundle(bundle: string): Promise<boolean>
+  injectWalletExportBundle(
+    bundle: string,
+    organizationId: string,
+  ): Promise<boolean>
+}
+
+export type IndexedDbStamper = Stamper & {
+  resetKeyPair: (externalKeyPair?: CryptoKeyPair) => Promise<void>
+}
+export type WebauthnStamper = Stamper

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/exportWallet.ts

@@ -0,0 +1,124 @@
+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()
+      ?.stamper.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()
+      ?.stamper.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')
+  }
+}

package/src/utils/utils.ts

@@ -0,0 +1,136 @@
+import type { PartialBy } from 'viem'
+import type { ZeroDevWalletSession } from '../types/session.js'
+
+/**
+ * Parses a session from a JWT.
+ *
+ * @param token - The JWT to parse.
+ * @returns {PartialBy<ZeroDevWalletSession, "createdAt" | "id" | "stamperType">} - The parsed session.
+ */
+export function parseSession(
+  token: string | ZeroDevWalletSession,
+): PartialBy<ZeroDevWalletSession, 'createdAt' | 'id' | 'stamperType'> {
+  if (typeof token !== 'string') {
+    return token
+  }
+  const [, payload] = token.split('.')
+  if (!payload) {
+    throw new Error('Invalid JWT: Missing payload')
+  }
+
+  const decoded = JSON.parse(Buffer.from(payload, 'base64').toString())
+  const {
+    exp,
+    public_key: publicKey,
+    session_type: sessionType,
+    user_id: userId,
+    organization_id: organizationId,
+  } = decoded
+
+  if (!exp || !publicKey || !sessionType || !userId || !organizationId) {
+    throw new Error('JWT payload missing required fields')
+  }
+
+  return {
+    sessionType,
+    userId,
+    organizationId,
+    expiry: exp,
+    token: publicKey,
+  }
+}
+
+/**
+ * Normalizes a timestamp to milliseconds.
+ *
+ * @param timestamp - The timestamp to normalize.
+ * @returns {number} - The normalized timestamp.
+ */
+export function normalizeTimestamp(timestamp: number): number {
+  return timestamp < 1e10 ? timestamp * 1_000 : timestamp
+}
+
+/**
+ * Generates a random buffer of 32 bytes.
+ *
+ * @returns {ArrayBuffer} - The random buffer.
+ */
+export const generateRandomBuffer = (): ArrayBuffer => {
+  const arr = new Uint8Array(32)
+  crypto.getRandomValues(arr)
+  return arr.buffer
+}
+
+/**
+ * Encodes a challenge in base64url format.
+ *
+ * @param challenge - The challenge to encode.
+ * @returns {string} - The encoded challenge.
+ */
+export const base64UrlEncode = (challenge: ArrayBuffer): string => {
+  return Buffer.from(challenge)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '')
+}
+
+/**
+ * Compresses an uncompressed P-256 public key into its 33-byte compressed form.
+ *
+ * @param {Uint8Array} raw - The uncompressed public key (65 bytes, starting with 0x04).
+ * @returns {Uint8Array} - The compressed public key (33 bytes, starting with 0x02 or 0x03).
+ * @throws {Error} - If the input key is not a valid uncompressed P-256 key.
+ */
+export function pointEncode(raw: Uint8Array): Uint8Array {
+  if (raw.length !== 65 || raw[0] !== 0x04) {
+    throw new Error('Invalid uncompressed P-256 key')
+  }
+
+  const x = raw.slice(1, 33)
+  const y = raw.slice(33, 65)
+
+  if (x.length !== 32 || y.length !== 32) {
+    throw new Error('Invalid x or y length')
+  }
+
+  const prefix = (y[31]! & 1) === 0 ? 0x02 : 0x03
+
+  const compressed = new Uint8Array(33)
+  compressed[0] = prefix
+  compressed.set(x, 1)
+  return compressed
+}
+
+/**
+ * Converts a Uint8Array into a lowercase hex string.
+ *
+ * @param {Uint8Array} input - The input byte array.
+ * @returns {string} - The resulting hex string.
+ */
+export function uint8ArrayToHexString(input: Uint8Array): string {
+  return input.reduce(
+    (result, x) => result + x.toString(16).padStart(2, '0'),
+    '',
+  )
+}
+
+/**
+ * Generates a compressed public key from a key pair.
+ *
+ * @returns {Promise<string>} - The compressed public key.
+ */
+export async function generateCompressedPublicKeyFromKeyPair(
+  keyPair: CryptoKeyPair,
+): Promise<string> {
+  const rawPubKey = new Uint8Array(
+    await crypto.subtle.exportKey('raw', keyPair.publicKey),
+  )
+  const compressedPubKey = pointEncode(rawPubKey)
+  const compressedHex = uint8ArrayToHexString(compressedPubKey)
+  return compressedHex
+}
+
+export const humanReadableDateTime = (): string => {
+  return new Date().toLocaleString().replaceAll('/', '-').replaceAll(':', '.')
+}