@zerodev/wallet-core 0.0.1-alpha.3

package/src/client/types.ts

@@ -0,0 +1,66 @@
+import type { Stamper } from '../stampers/types.js'
+import type { RestRequestFn } from './transports/rest.js'
+
+export type TransportConfig = {
+  /** The name of the transport. */
+  name: string
+  /** The key of the transport. */
+  key: string
+  /** Base URL for the API */
+  url: string
+  /** Proxy base URL for auth requests */
+  proxyBaseUrl?: string
+  /** Request timeout in milliseconds */
+  timeoutMs: number
+  /** The type of the transport. */
+  type: string
+}
+
+export type Transport = (options: { stamper: Stamper }) => {
+  config: TransportConfig
+  request: RestRequestFn
+  value?: Record<string, unknown>
+}
+
+export type ClientConfig<TStamper extends Stamper = Stamper> = {
+  /** Transport for the client */
+  transport: Transport
+  /** Stamper for authenticated requests */
+  stamper: TStamper
+  /** Organization ID */
+  organizationId?: string
+  /** A key for the client. */
+  key?: string
+  /** A name for the client. */
+  name?: string
+}
+
+export type Client<
+  extended extends Extended | undefined = undefined,
+  TStamper extends Stamper = Stamper,
+> = {
+  /** Transport configuration */
+  transport: TransportConfig & Record<string, unknown>
+  /** Request function from transport */
+  request: RestRequestFn
+  /** Stamper for authenticated requests */
+  stamper: TStamper
+  /** Organization ID */
+  organizationId?: string
+  /** A key for the client */
+  key: string
+  /** A name for the client */
+  name: string
+  /** The type of client */
+  type: string
+  /** A unique ID for the client */
+  uid: string
+  /** Extend the client with additional functionality */
+  extend: <const client extends Extended>(
+    fn: (client: Client<extended>) => client,
+  ) => Client<client & (extended extends Extended ? extended : unknown)>
+} & (extended extends Extended ? extended : unknown)
+
+type Extended = {
+  [key: string]: unknown
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const DEFAULT_SESSION_EXPIRATION_IN_SECONDS = '900' // default to 15 minutes
+export const DEFAULT_IFRAME_CONTAINER_ID = 'turnkey-auth-iframe-container-id'
+export const DEFAULT_IFRAME_ELEMENT_ID = 'turnkey-default-iframe-element-id'
+export const DEFAULT_ORGANIZATION_ID = '6254bb1d-0d0d-4f7e-96b8-77c94fe0b0c1'
+export const KMS_SERVER_URL = 'https://kms.dev.zerodev.app'

package/src/core/createZeroDevWallet.ts

@@ -0,0 +1,477 @@
+import { getWebAuthnAttestation } from '@turnkey/http'
+import type { LocalAccount } from 'viem/accounts'
+import type { EmailCustomization } from '../actions/auth/index.js'
+import { toViemAccount } from '../adapters/viem.js'
+import {
+  createClient,
+  type ZeroDevWalletClient,
+  zeroDevWalletTransport,
+} from '../client/index.js'
+import {
+  DEFAULT_ORGANIZATION_ID,
+  DEFAULT_SESSION_EXPIRATION_IN_SECONDS,
+  KMS_SERVER_URL,
+} from '../constants.js'
+import { createIndexedDbStamper } from '../stampers/indexedDbStamper.js'
+import type { IndexedDbStamper } from '../stampers/types.js'
+import { createWebauthnStamper } from '../stampers/webauthnStamper.js'
+import { createWebStorageAdapter } from '../storage/adapters.js'
+import {
+  createStorageManager,
+  type StorageAdapter,
+} from '../storage/manager.js'
+import { SessionType, type ZeroDevWalletSession } from '../types/session.js'
+import {
+  base64UrlEncode,
+  generateCompressedPublicKeyFromKeyPair,
+  generateRandomBuffer,
+  humanReadableDateTime,
+  parseSession,
+} from '../utils/utils.js'
+export interface ZeroDevWalletConfig {
+  organizationId?: string
+  proxyBaseUrl?: string
+  projectId: string
+  sessionStorage?: StorageAdapter
+  rpId?: string
+}
+
+// Re-export EmailCustomization for convenience
+export type { EmailCustomization } from '../actions/auth/index.js'
+export type { StorageAdapter, StorageManager } from '../storage/manager.js'
+// Re-export new session types
+export type { StamperType, ZeroDevWalletSession } from '../types/session.js'
+
+export type AuthParams =
+  | {
+      type: 'oauth'
+      provider: string
+      redirectUrl?: string
+      credential: string
+    }
+  | {
+      type: 'passkey'
+      email: string
+      mode: 'register' | 'login'
+    }
+  | {
+      type: 'otp'
+      mode: 'sendOtp'
+      email: string
+      contact: {
+        type: 'email' | 'sms'
+        contact: string
+      }
+      emailCustomization?: EmailCustomization
+    }
+  | {
+      type: 'otp'
+      mode: 'verifyOtp'
+      otpId: string
+      otpCode: string
+      subOrganizationId: string
+    }
+
+export interface ZeroDevWalletSDK {
+  client: () => ZeroDevWalletClient | null
+  auth: (params: AuthParams) => Promise<any>
+
+  getPublicKey: () => Promise<string | null>
+
+  getSession: () => Promise<ZeroDevWalletSession | undefined>
+  getAllSessions: () => Promise<Record<string, ZeroDevWalletSession>>
+  switchSession: (
+    sessionId: string,
+  ) => Promise<ZeroDevWalletSession | undefined>
+  clearSession: (sessionId: string) => Promise<void>
+  clearAllSessions: () => Promise<void>
+  refreshSession: (
+    sessionId?: string,
+  ) => Promise<ZeroDevWalletSession | undefined>
+
+  logout: () => Promise<boolean>
+
+  toAccount: () => Promise<LocalAccount>
+}
+
+export async function createZeroDevWallet(
+  config: ZeroDevWalletConfig,
+): Promise<ZeroDevWalletSDK> {
+  const {
+    projectId,
+    sessionStorage,
+    rpId = window.location.hostname,
+    organizationId = DEFAULT_ORGANIZATION_ID,
+  } = config
+
+  const sessionStorageManager = createStorageManager(
+    sessionStorage || createWebStorageAdapter(),
+  )
+
+  const indexedDbStamper = await createIndexedDbStamper()
+
+  const webauthnStamper = await createWebauthnStamper({ rpId })
+
+  let currentClient: ZeroDevWalletClient | null = null
+
+  const indexedDbClient = createClient({
+    stamper: indexedDbStamper,
+    transport: zeroDevWalletTransport({
+      baseUrl: config.proxyBaseUrl || `${KMS_SERVER_URL}/api/v1`,
+    }),
+  })
+
+  const passkeyClient = createClient({
+    stamper: webauthnStamper,
+    transport: zeroDevWalletTransport({
+      baseUrl: config.proxyBaseUrl || `${KMS_SERVER_URL}/api/v1`,
+    }),
+  })
+
+  // Restore active session on initialization
+  const activeSession = await sessionStorageManager.getActiveSession()
+
+  if (activeSession) {
+    try {
+      if (activeSession.stamperType === 'indexedDb') {
+        currentClient = indexedDbClient
+      }
+    } catch (_error) {}
+  }
+
+  const getClient = () => {
+    return currentClient
+  }
+
+  return {
+    client: getClient,
+    async getPublicKey() {
+      await indexedDbClient.stamper.resetKeyPair()
+      const compressedPublicKey = await indexedDbClient.stamper.getPublicKey()
+      return compressedPublicKey
+    },
+
+    async getSession() {
+      return sessionStorageManager.getActiveSession()
+    },
+
+    async getAllSessions() {
+      const sessions = await sessionStorageManager.listSessions()
+      const sessionMap: Record<string, ZeroDevWalletSession> = {}
+      for (const session of sessions) {
+        sessionMap[session.id] = session
+      }
+      return sessionMap
+    },
+
+    async switchSession(sessionId: string) {
+      await sessionStorageManager.setActiveSession(sessionId)
+      const session = await sessionStorageManager.getActiveSession()
+
+      if (session) {
+        // Update current client based on session's stamper type
+        let stamper: IndexedDbStamper | undefined
+        if (session.stamperType === 'indexedDb') {
+          stamper = indexedDbStamper
+        }
+
+        if (stamper) {
+          currentClient = createClient({
+            stamper,
+            transport: zeroDevWalletTransport({
+              baseUrl: config.proxyBaseUrl || `${KMS_SERVER_URL}/api/v1`,
+            }),
+          })
+        }
+      }
+
+      return session
+    },
+
+    async clearSession(sessionId: string) {
+      await sessionStorageManager.clearSession(sessionId)
+    },
+
+    async clearAllSessions() {
+      await sessionStorageManager.clearAllSessions()
+      currentClient = null
+    },
+
+    async refreshSession(sessionId?: string) {
+      const activeSession = sessionId
+        ? await sessionStorageManager.getSession(sessionId)
+        : await sessionStorageManager.getActiveSession()
+      if (!activeSession) {
+        throw new Error('No active session')
+      }
+      if (activeSession.stamperType === 'indexedDb') {
+        const newKeyPair = await crypto.subtle.generateKey(
+          {
+            name: 'ECDSA',
+            namedCurve: 'P-256',
+          },
+          false,
+          ['sign', 'verify'],
+        )
+        const compressedPublicKeyHex =
+          await generateCompressedPublicKeyFromKeyPair(newKeyPair)
+        const data = await indexedDbClient.loginWithStamp({
+          targetPublicKey: compressedPublicKeyHex,
+          projectId,
+          organizationId: activeSession.organizationId,
+        })
+        await indexedDbClient.stamper.resetKeyPair(newKeyPair)
+        const parsedSession = parseSession(data.session)
+        const session: ZeroDevWalletSession = {
+          id: `session_indexedDb_${Date.now()}`,
+          userId: parsedSession.userId,
+          organizationId: parsedSession.organizationId,
+          stamperType: 'indexedDb',
+          sessionType: SessionType.READ_WRITE,
+          token: data.session,
+          expiry: parsedSession.expiry,
+          createdAt: Date.now(),
+        }
+        await sessionStorageManager.clearSession(activeSession.id)
+        await sessionStorageManager.storeSession(session, session.id)
+        currentClient = indexedDbClient
+        return session
+      }
+      throw new Error('Invalid session type')
+    },
+
+    // [TODO] refactor to smaller utils/actions
+    async auth(params: AuthParams) {
+      switch (params.type) {
+        case 'oauth': {
+          const { credential } = params
+          const targetPublicKey = await indexedDbClient.stamper.getPublicKey()
+
+          if (!targetPublicKey) {
+            throw new Error('Failed to get public key')
+          }
+
+          const data = await indexedDbClient.authenticateWithOAuth({
+            oidcToken: credential,
+            provider: 'google',
+            targetPublicKey,
+            projectId,
+          })
+
+          if (data.turnkeySession) {
+            // Parse the JWT to get session data
+            const parsedSession = parseSession(data.turnkeySession)
+            const session: ZeroDevWalletSession = {
+              id: `session_oauth_${Date.now()}`,
+              userId: parsedSession.userId,
+              organizationId: parsedSession.organizationId,
+              stamperType: 'indexedDb',
+              sessionType: parsedSession.sessionType || SessionType.READ_WRITE,
+              token: data.turnkeySession,
+              expiry: parsedSession.expiry,
+              createdAt: Date.now(),
+              publicKey: targetPublicKey,
+            }
+            await sessionStorageManager.storeSession(session, session.id)
+          }
+          currentClient = indexedDbClient
+          return data
+        }
+        case 'passkey': {
+          const { type } = params
+          if (
+            type === 'passkey' &&
+            'mode' in params &&
+            params.mode === 'register'
+          ) {
+            const { email } = params
+            await indexedDbClient.stamper.resetKeyPair()
+            const tempPublicKey = await indexedDbClient.stamper.getPublicKey()
+            if (!tempPublicKey) {
+              throw new Error('Failed to get public key')
+            }
+            const challenge = generateRandomBuffer()
+            const encodedChallenge = base64UrlEncode(challenge)
+            const authenticatorUserId = generateRandomBuffer()
+            const name = `ZeroDevWallet-${humanReadableDateTime()}-${email}`
+            const attestation = await getWebAuthnAttestation({
+              publicKey: {
+                rp: { id: rpId, name: '' },
+                challenge,
+                pubKeyCredParams: [
+                  {
+                    type: 'public-key',
+                    alg: -7,
+                  },
+                  {
+                    type: 'public-key',
+                    alg: -257,
+                  },
+                ],
+                user: {
+                  id: authenticatorUserId,
+                  name,
+                  displayName: name,
+                },
+              },
+            })
+            const data = await passkeyClient.registerWithPasskey({
+              email,
+              attestation,
+              challenge: encodedChallenge,
+              projectId,
+              encodedPublicKey: tempPublicKey,
+            })
+            const newKeyPair = await crypto.subtle.generateKey(
+              {
+                name: 'ECDSA',
+                namedCurve: 'P-256',
+              },
+              false,
+              ['sign', 'verify'],
+            )
+            const compressedPublicKeyHex =
+              await generateCompressedPublicKeyFromKeyPair(newKeyPair)
+            const loginData = await indexedDbClient.loginWithStamp({
+              projectId,
+              targetPublicKey: compressedPublicKeyHex,
+              organizationId: data.subOrganizationId,
+            })
+            await indexedDbClient.stamper.resetKeyPair(newKeyPair)
+            const parsedSession = parseSession(loginData.session)
+            const session: ZeroDevWalletSession = {
+              id: `session_indexedDb_${Date.now()}`,
+              stamperType: 'indexedDb',
+              createdAt: Date.now(),
+              sessionType: SessionType.READ_WRITE,
+              userId: parsedSession.userId,
+              organizationId: parsedSession.organizationId,
+              expiry:
+                Date.now() +
+                Number(DEFAULT_SESSION_EXPIRATION_IN_SECONDS) * 1000,
+              token: loginData.session,
+            }
+            await sessionStorageManager.storeSession(session, session.id)
+            currentClient = indexedDbClient
+            return data
+          }
+          if (
+            type === 'passkey' &&
+            'mode' in params &&
+            params.mode === 'login'
+          ) {
+            await indexedDbClient.stamper.resetKeyPair()
+            const generatedPublicKey =
+              await indexedDbClient.stamper.getPublicKey()
+            if (!generatedPublicKey) {
+              throw new Error('Failed to get public key')
+            }
+            const loginData = await passkeyClient.loginWithStamp({
+              targetPublicKey: generatedPublicKey,
+              projectId,
+              organizationId,
+            })
+            const parsedSession = parseSession(loginData.session)
+            const session: ZeroDevWalletSession = {
+              id: `session_indexedDb_${Date.now()}`,
+              stamperType: 'indexedDb',
+              createdAt: Date.now(),
+              sessionType: SessionType.READ_WRITE,
+              userId: parsedSession.userId,
+              organizationId: parsedSession.organizationId,
+              expiry:
+                Date.now() +
+                Number(DEFAULT_SESSION_EXPIRATION_IN_SECONDS) * 1000,
+              token: loginData.session,
+            }
+            await sessionStorageManager.storeSession(session, session.id)
+            currentClient = indexedDbClient
+            return loginData
+          }
+          throw new Error('Passkey authentication requires passkey parameter')
+        }
+        case 'otp': {
+          const { type, mode } = params
+
+          if (type === 'otp' && mode === 'sendOtp') {
+            const { email, contact, emailCustomization } = params
+
+            const data = await indexedDbClient.registerWithOTP({
+              email,
+              contact,
+              projectId,
+              ...(emailCustomization && { emailCustomization }),
+            })
+
+            return data
+          }
+
+          if (type === 'otp' && mode === 'verifyOtp') {
+            const { otpId, otpCode, subOrganizationId } = params
+            await indexedDbClient.stamper.resetKeyPair()
+            const targetPublicKey = await indexedDbClient.stamper.getPublicKey()
+
+            if (!targetPublicKey) {
+              throw new Error('Failed to get public key')
+            }
+
+            const data = await indexedDbClient.loginWithOTP({
+              otpId,
+              otpCode,
+              subOrganizationId,
+              encodedPublicKey: targetPublicKey,
+              projectId,
+            })
+
+            if (data.session) {
+              // Parse the JWT to get session data
+              const parsedSession = parseSession(data.session)
+              const session: ZeroDevWalletSession = {
+                id: `session_otp_${Date.now()}`,
+                userId: parsedSession.userId,
+                organizationId: parsedSession.organizationId,
+                stamperType: 'indexedDb',
+                sessionType:
+                  parsedSession.sessionType || SessionType.READ_WRITE,
+                token: data.session,
+                expiry: parsedSession.expiry,
+                createdAt: Date.now(),
+                publicKey: targetPublicKey,
+              }
+              await sessionStorageManager.storeSession(session, session.id)
+            }
+            currentClient = indexedDbClient
+            return data
+          }
+
+          throw new Error('OTP authentication requires mode parameter')
+        }
+        default:
+          throw new Error(`Unknown auth type: ${(params as any).type}`)
+      }
+    },
+
+    async logout() {
+      await sessionStorageManager.clearAllSessions()
+      currentClient = null
+      await indexedDbClient.stamper.resetKeyPair()
+      return true
+    },
+
+    async toAccount(): Promise<LocalAccount> {
+      const session = await sessionStorageManager.getActiveSession()
+      if (!session) {
+        throw new Error('No active session')
+      }
+      if (!currentClient) {
+        throw new Error('No client')
+      }
+
+      return toViemAccount({
+        client: currentClient,
+        organizationId: session.organizationId,
+        projectId,
+      })
+    },
+  }
+}

package/src/errors/request.ts

@@ -0,0 +1,36 @@
+export class RestRequestError extends Error {
+  constructor(
+    public url: string,
+    public status?: number,
+    public body?: unknown,
+    public override cause?: unknown,
+  ) {
+    // Extract error message from backend response format
+    // Backend format: { error: "error_code", message: "human readable message" }
+    let errorMessage = `Request failed (${status || 'unknown'}): `
+
+    if (body && typeof body === 'object') {
+      const errorBody = body as any
+
+      // Prefer message (detailed), fallback to error (code)
+      if (errorBody.message && errorBody.error) {
+        // Both present: show error code + message
+        errorMessage += `${errorBody.error} - ${errorBody.message}`
+      } else if (errorBody.message) {
+        errorMessage += `${errorBody.message}`
+      } else if (errorBody.error) {
+        errorMessage += `${errorBody.error}`
+      }
+    }
+
+    super(errorMessage)
+    this.name = 'RestRequestError'
+  }
+}
+
+export class RestTimeoutError extends Error {
+  constructor(public url: string) {
+    super(`Request timed out: ${url}`)
+    this.name = 'RestTimeoutError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+export type {
+  // Auth types
+  AuthenticateWithEmailParameters,
+  AuthenticateWithEmailReturnType,
+  AuthenticateWithOAuthParameters,
+  AuthenticateWithOAuthReturnType,
+  EmailCustomization,
+  // Wallet types
+  GetUserWalletParameters,
+  GetUserWalletReturnType,
+  GetWhoamiParameters,
+  GetWhoamiReturnType,
+  LoginWithOTPParameters,
+  LoginWithOTPReturnType,
+  OtpContact,
+  RegisterWithOTPParameters,
+  RegisterWithOTPReturnType,
+  SignRawPayloadParameters,
+  SignRawPayloadReturnType,
+  SignTransactionParameters,
+  SignTransactionReturnType,
+} from './actions/index.js'
+
+// Actions
+export {
+  // Auth actions
+  authenticateWithEmail,
+  authenticateWithOAuth,
+  // Wallet actions
+  getUserWallet,
+  getWhoami,
+  loginWithOTP,
+  registerWithOTP,
+  signRawPayload,
+  signTransaction,
+} from './actions/index.js'
+export type { ToViemAccountParams } from './adapters/viem.js'
+// Adapters
+export { toViemAccount } from './adapters/viem.js'
+export type { ZeroDevWalletActions } from './client/decorators/client.js'
+// Client decorators
+export { zeroDevWalletActions } from './client/decorators/client.js'
+export type { Client, ClientConfig, Transport } from './client/index.js'
+// Client
+export {
+  createBaseClient,
+  createClient,
+  type ZeroDevWalletClient,
+  zeroDevWalletTransport,
+} from './client/index.js'
+export type {
+  AuthParams,
+  ZeroDevWalletConfig,
+  ZeroDevWalletSDK,
+} from './core/createZeroDevWallet.js'
+// Core
+export { createZeroDevWallet } from './core/createZeroDevWallet.js'
+// Stampers
+export {
+  createIframeStamper,
+  createIndexedDbStamper,
+  createWebauthnStamper,
+} from './stampers/index.js'
+export type {
+  IframeStamper,
+  IndexedDbStamper,
+  WebauthnStamper,
+} from './stampers/types.js'
+// Storage
+export type { StorageAdapter, StorageManager } from './storage/manager.js'
+// Session types
+export type { StamperType, ZeroDevWalletSession } from './types/session.js'
+export { exportWallet } from './utils/exportWallet.js'
+// Utils
+export { normalizeTimestamp } from './utils/utils.js'

package/src/polyfills/window.ts

@@ -0,0 +1,24 @@
+const loadWindow = () => {
+  if (typeof window !== 'undefined') {
+    return window
+  }
+  return {
+    localStorage: {
+      getItem: (_key: string): string | null => {
+        return null
+      },
+      setItem: (_key: string, _value: string) => {},
+      removeItem: (_key: string) => {},
+      clear: () => {},
+      key: (_index: number): string | null => {
+        return null
+      },
+      length: 0,
+    },
+    location: {
+      hostname: '',
+    },
+  }
+}
+
+export default loadWindow()