@zerodev/wallet-core 0.0.1-alpha.10

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@zerodev/wallet-core",
+  "version": "0.0.1-alpha.10",
+  "description": "ZeroDev Wallet SDK built on Turnkey",
+  "main": "./dist/_cjs/index.js",
+  "module": "./dist/_esm/index.js",
+  "types": "./dist/_types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/_types/index.d.ts",
+      "import": "./dist/_esm/index.js",
+      "require": "./dist/_cjs/index.js"
+    },
+    "./viem": {
+      "types": "./dist/_types/adapters/viem.d.ts",
+      "import": "./dist/_esm/adapters/viem.js",
+      "require": "./dist/_cjs/adapters/viem.js"
+    },
+    "./actions": {
+      "types": "./dist/_types/actions/index.d.ts",
+      "import": "./dist/_esm/actions/index.js",
+      "require": "./dist/_cjs/actions/index.js"
+    },
+    "./stampers": {
+      "types": "./dist/_types/stampers/index.d.ts",
+      "import": "./dist/_esm/stampers/index.js",
+      "require": "./dist/_cjs/stampers/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "./src/**/*.ts",
+    "!dist/_esm/**/*.tsbuildinfo",
+    "!dist/_cjs/**/*.tsbuildinfo",
+    "!dist/_types/**/*.tsbuildinfo",
+    "!.env",
+    "!./**/*.test.ts",
+    "!.changeset"
+  ],
+  "keywords": [
+    "wallet",
+    "offchainlabs",
+    "zerodev",
+    "wallet",
+    "signer",
+    "viem",
+    "account-abstraction",
+    "eip7702"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@turnkey/http": "^3.12.1",
+    "@turnkey/iframe-stamper": "^2.5.0",
+    "@turnkey/indexed-db-stamper": "^1.1.1",
+    "@turnkey/webauthn-stamper": "^0.6.0",
+    "json-canonicalize": "^2.0.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.38.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:cjs && pnpm run build:esm && pnpm run build:types",
+    "build:cjs": "tsc --project ./tsconfig.build.json --module commonjs --moduleResolution node --outDir ./dist/_cjs --removeComments --verbatimModuleSyntax false && printf '{\"type\":\"commonjs\"}' > ./dist/_cjs/package.json",
+    "build:esm": "tsc --project ./tsconfig.build.json --outDir ./dist/_esm && printf '{\"type\": \"module\",\"sideEffects\":false}' > ./dist/_esm/package.json",
+    "build:types": "tsc --project ./tsconfig.build.json --outDir ./dist/_types --emitDeclarationOnly --declaration --declarationMap",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit --project ./tsconfig.build.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/actions/auth/authenticateWithEmail.ts

@@ -0,0 +1,52 @@
+import type { Client } from '../../client/types.js'
+
+export type EmailCustomization = {
+  /** A template for the URL to be used in a magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`. */
+  magicLinkTemplate?: string
+}
+
+export type AuthenticateWithEmailParameters = {
+  /** The email address to authenticate */
+  email: string
+  /** The project ID for the request */
+  projectId: string
+  /** Target public key for authentication */
+  targetPublicKey: string
+  /** Optional email customization settings */
+  emailCustomization?: EmailCustomization
+}
+
+export type AuthenticateWithEmailReturnType = {
+  /** The user ID */
+  userId?: string
+  /** The wallet address */
+  walletAddress?: string
+  /** The sub-organization ID */
+  subOrganizationId?: string
+  /** Whether magic link is required */
+  requiresMagicLink?: boolean
+  /** The Turnkey session if available */
+  turnkeySession?: string
+}
+
+/**
+ * @deprecated Use {@link registerWithOTP} instead
+ * See {@link registerWithOTP} for more details on how to authenticate with email.
+ */
+export async function authenticateWithEmail(
+  client: Client,
+  params: AuthenticateWithEmailParameters,
+): Promise<AuthenticateWithEmailReturnType> {
+  const { email, projectId, targetPublicKey, emailCustomization } = params
+
+  return await client.request({
+    path: `${projectId}/auth/email-magic`,
+    method: 'POST',
+    body: {
+      email,
+      emailCustomization,
+      targetPublicKey,
+      projectId,
+    },
+  })
+}

package/src/actions/auth/authenticateWithOAuth.ts

@@ -0,0 +1,52 @@
+import type { Client } from '../../client/types.js'
+
+export type AuthenticateWithOAuthParameters = {
+  /** The OAuth provider (e.g., 'google') */
+  provider: string
+  /** The project ID for the request */
+  projectId: string
+}
+
+export type AuthenticateWithOAuthReturnType = {
+  /** The user ID */
+  userId?: string
+  /** The wallet address */
+  walletAddress?: string
+  /** The sub-organization ID */
+  subOrganizationId?: string
+  /** The Turnkey session */
+  session?: string
+}
+
+/**
+ * Authenticates a user with OAuth using cookie-based backend flow
+ *
+ * The backend reads the OAuth session from a cookie set during the OAuth flow.
+ * This requires the OAuth popup flow to complete first via the backend's
+ * /oauth/google/login endpoint.
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for OAuth authentication
+ * @returns The authentication result
+ *
+ * @example
+ * ```ts
+ * const result = await authenticateWithOAuth(client, {
+ *   provider: 'google',
+ *   projectId: 'proj_456',
+ * });
+ * ```
+ */
+export async function authenticateWithOAuth(
+  client: Client,
+  params: AuthenticateWithOAuthParameters,
+): Promise<AuthenticateWithOAuthReturnType> {
+  const { projectId } = params
+
+  return await client.request({
+    path: `${projectId}/auth/oauth`,
+    method: 'POST',
+    body: null,
+    credentials: 'include',
+  })
+}

package/src/actions/auth/getAuthProxyConfigId.ts

@@ -0,0 +1,20 @@
+import type { Client } from '../../client/types.js'
+
+export type GetAuthProxyConfigIdReturnType = {
+  authProxyConfigId: string
+}
+
+/**
+ * Fetches the auth proxy config ID from the backend
+ *
+ * @param client - The ZeroDev Wallet client
+ * @returns The auth proxy config ID
+ */
+export async function getAuthProxyConfigId(
+  client: Client,
+): Promise<GetAuthProxyConfigIdReturnType> {
+  return await client.request({
+    path: 'server-info/auth-proxy-id',
+    method: 'GET',
+  })
+}

package/src/actions/auth/getUserEmail.ts

@@ -0,0 +1,52 @@
+import type { Client } from '../../client/types.js'
+
+export type GetUserEmailParameters = {
+  /** The organization ID to query */
+  organizationId: string
+  /** The project ID for the request */
+  projectId: string
+  /** The session token for authorization */
+  token: string
+}
+
+export type GetUserEmailReturnType = {
+  /** The user's email address */
+  email: string
+}
+
+/**
+ * Gets the user's email address
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for the user email request
+ * @returns The user's email address
+ *
+ * @example
+ * ```ts
+ * const userEmail = await getUserEmail(client, {
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456',
+ *   token: 'session_token_abc',
+ * });
+ * console.log(userEmail.email); // 'user@example.com'
+ * ```
+ */
+export async function getUserEmail(
+  client: Client,
+  params: GetUserEmailParameters,
+): Promise<GetUserEmailReturnType> {
+  const { organizationId, projectId, token } = params
+
+  return await client.request({
+    path: `${projectId}/user-email`,
+    method: 'POST',
+    body: {
+      organizationId,
+    },
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+    stamp: true,
+    stampPostion: 'headers',
+  })
+}

package/src/actions/auth/getWhoami.ts

@@ -0,0 +1,51 @@
+import type { Client } from '../../client/types.js'
+
+export type GetWhoamiParameters = {
+  /** The organization ID to query */
+  organizationId: string
+  /** The project ID for the request */
+  projectId: string
+}
+
+export type GetWhoamiReturnType = {
+  /** The user's ID */
+  userId: string
+  /** The organization ID */
+  organizationId: string
+  /** The organization name */
+  organizationName?: string
+  /** The username */
+  username?: string
+}
+
+/**
+ * Gets the current user information
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for the whoami request
+ * @returns The user information
+ *
+ * @example
+ * ```ts
+ * const userInfo = await getWhoami(client, {
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456'
+ * });
+ * console.log(userInfo.userId); // 'user_789'
+ * ```
+ */
+export async function getWhoami(
+  client: Client,
+  params: GetWhoamiParameters,
+): Promise<GetWhoamiReturnType> {
+  const { organizationId, projectId } = params
+
+  return await client.request({
+    path: `${projectId}/whoami`,
+    method: 'POST',
+    body: {
+      organizationId,
+    },
+    stamp: true,
+  })
+}

package/src/actions/auth/index.ts

@@ -0,0 +1,47 @@
+export {
+  type AuthenticateWithEmailParameters,
+  type AuthenticateWithEmailReturnType,
+  authenticateWithEmail,
+  type EmailCustomization,
+} from './authenticateWithEmail.js'
+
+export {
+  type AuthenticateWithOAuthParameters,
+  type AuthenticateWithOAuthReturnType,
+  authenticateWithOAuth,
+} from './authenticateWithOAuth.js'
+export {
+  type GetAuthProxyConfigIdReturnType,
+  getAuthProxyConfigId,
+} from './getAuthProxyConfigId.js'
+export {
+  type GetUserEmailParameters,
+  type GetUserEmailReturnType,
+  getUserEmail,
+} from './getUserEmail.js'
+export {
+  type GetWhoamiParameters,
+  type GetWhoamiReturnType,
+  getWhoami,
+} from './getWhoami.js'
+export {
+  type LoginWithOTPParameters,
+  type LoginWithOTPReturnType,
+  loginWithOTP,
+} from './loginWithOTP.js'
+export {
+  type LoginWithStampParameters,
+  type LoginWithStampReturnType,
+  loginWithStamp,
+} from './loginWithStamp.js'
+export {
+  type OtpContact,
+  type RegisterWithOTPParameters,
+  type RegisterWithOTPReturnType,
+  registerWithOTP,
+} from './registerWithOTP.js'
+export {
+  type RegisterWithPasskeyParameters,
+  type RegisterWithPasskeyReturnType,
+  registerWithPasskey,
+} from './registerWithPasskey.js'

package/src/actions/auth/loginWithOTP.ts

@@ -0,0 +1,57 @@
+import type { Client } from '../../client/types.js'
+
+export type LoginWithOTPParameters = {
+  /** The verification token JWT from Auth Proxy's verifyOtp */
+  verificationToken: string
+  /** The raw r||s signature hex (64 bytes = 128 chars) */
+  clientSignature: string
+  /** The project ID for the request */
+  projectId: string
+}
+
+export type LoginWithOTPReturnType = {
+  /** The Turnkey session token */
+  session: string
+}
+
+/**
+ * Logs in a user with OTP (One-Time Password) authentication via the backend.
+ *
+ * The backend handles:
+ * 1. Parsing the verificationToken JWT to extract email and publicKey
+ * 2. Creating/retrieving sub-organization for (projectId, email)
+ * 3. Reconstructing the message for signature verification
+ * 4. Calling Turnkey.OtpLogin with the appropriate parameters
+ * 5. Returning the session to the SDK
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for OTP login
+ * @returns The login result with session token
+ *
+ * @example
+ * ```ts
+ * // After verifying OTP via Auth Proxy and building client signature
+ * const result = await loginWithOTP(client, {
+ *   verificationToken: '<jwt-from-auth-proxy>',
+ *   clientSignature: '<raw-signature-hex>',
+ *   projectId: 'proj_456'
+ * });
+ *
+ * // Use result.session for authenticated requests
+ * ```
+ */
+export async function loginWithOTP(
+  client: Client,
+  params: LoginWithOTPParameters,
+): Promise<LoginWithOTPReturnType> {
+  const { verificationToken, clientSignature, projectId } = params
+
+  return await client.request({
+    path: `${projectId}/auth/login/otp`,
+    method: 'POST',
+    body: {
+      verificationToken,
+      clientSignature,
+    },
+  })
+}

package/src/actions/auth/loginWithStamp.ts

@@ -0,0 +1,79 @@
+import { canonicalizeEx } from 'json-canonicalize'
+import type { Client } from '../../client/types.js'
+import type { Stamp } from '../../stampers/types.js'
+
+export type EmailCustomization = {
+  /** A template for the URL to be used in a magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`. */
+  magicLinkTemplate?: string
+}
+
+export type LoginWithStampParameters = {
+  /** The project ID for the request */
+  projectId: string
+  /** The organization ID for the request */
+  organizationId: string
+  /** The encoded public key for the request */
+  targetPublicKey: string
+  /** The stamper type for the request */
+  stampWith?: 'indexedDb' | 'webauthn'
+}
+
+export type LoginWithStampReturnType = {
+  /** The session */
+  session: string
+}
+
+/**
+ * Logs in a user with a stamp
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for login with a stamp
+ * @returns The login result
+ *
+ * @example
+ * ```ts
+ * const result = await loginWithStamp(client, {
+ *   organizationId: 'org_456',
+ *   projectId: 'proj_456',
+ *   targetPublicKey: 'encodedPublicKey',
+ * });
+ * ```
+ */
+export async function loginWithStamp(
+  client: Client,
+  params: LoginWithStampParameters,
+): Promise<LoginWithStampReturnType> {
+  const { projectId, targetPublicKey, organizationId, stampWith } = params
+
+  const timestampMs = Date.now()
+  const timestampMsString = timestampMs.toString()
+  const timestampIso = new Date(timestampMs).toISOString()
+
+  const stampPayload = canonicalizeEx({
+    organizationId,
+    parameters: {
+      publicKey: targetPublicKey,
+    },
+    timestampMs: timestampMsString,
+    type: 'ACTIVITY_TYPE_STAMP_LOGIN',
+  })
+  let stamp: Stamp
+  if (stampWith === 'indexedDb') {
+    stamp = await client.indexedDbStamper.stamp(stampPayload)
+  } else if (stampWith === 'webauthn') {
+    stamp = await client.webauthnStamper.stamp(stampPayload)
+  } else {
+    stamp = await client.indexedDbStamper.stamp(stampPayload)
+  }
+
+  return client.request({
+    path: `${projectId}/auth/login/stamp`,
+    method: 'POST',
+    body: {
+      subOrganizationId: organizationId,
+      targetPublicKey,
+      timestamp: timestampIso,
+      stamp,
+    },
+  })
+}

package/src/actions/auth/registerWithOTP.ts

@@ -0,0 +1,64 @@
+import type { Client } from '../../client/types.js'
+import type { EmailCustomization } from './authenticateWithEmail.js'
+
+export type OtpContact = {
+  /** The OTP delivery type (currently only 'email' is supported) */
+  type: 'email' | 'sms'
+  /** The contact information (email address or phone number) */
+  contact: string
+}
+
+export type RegisterWithOTPParameters = {
+  /** The email address to register */
+  email: string
+  /** The contact information for OTP delivery */
+  contact: OtpContact
+  /** The project ID for the request */
+  projectId: string
+  /** Optional email customization settings */
+  emailCustomization?: EmailCustomization
+}
+
+export type RegisterWithOTPReturnType = {
+  /** The OTP ID needed for verification */
+  otpId: string
+}
+
+/**
+ * Initiates OTP (One-Time Password) authentication
+ * This will send an OTP code to the specified contact method
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for OTP initiation
+ * @returns The result including otpId needed for verification
+ *
+ * @example
+ * ```ts
+ * const result = await registerWithOTP(client, {
+ *   email: 'user@example.com',
+ *   contact: {
+ *     type: 'email',
+ *     contact: 'user@example.com'
+ *   },
+ *   projectId: 'proj_456'
+ * });
+ *
+ * // Use result.otpId for the verification step
+ * ```
+ */
+export async function registerWithOTP(
+  client: Client,
+  params: RegisterWithOTPParameters,
+): Promise<RegisterWithOTPReturnType> {
+  const { email, contact, projectId, emailCustomization } = params
+
+  return await client.request({
+    path: `${projectId}/auth/init/otp`,
+    method: 'POST',
+    body: {
+      email,
+      contact,
+      emailCustomization,
+    },
+  })
+}

package/src/actions/auth/registerWithPasskey.ts

@@ -0,0 +1,72 @@
+import type { Client } from '../../client/types.js'
+
+export type EmailCustomization = {
+  /** A template for the URL to be used in a magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`. */
+  magicLinkTemplate?: string
+}
+
+export type RegisterWithPasskeyParameters = {
+  /** The email address to authenticate */
+  email: string
+  /** The project ID for the request */
+  projectId: string
+  /** The challenge for the request */
+  challenge: string
+  /** The attestation for the request */
+  attestation: {
+    attestationObject: string
+    clientDataJson: string
+    credentialId: string
+  }
+  /** The encoded public key for the request */
+  encodedPublicKey: string
+}
+
+export type RegisterWithPasskeyReturnType = {
+  /** The user ID */
+  userId: string
+  /** The wallet address */
+  walletAddress: string
+  /** The sub-organization ID */
+  subOrganizationId: string
+}
+
+/**
+ * Registers a passkey with the user's wallet
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for passkey registration
+ * @returns The passkey registration result
+ *
+ * @example
+ * ```ts
+ * const result = await registerWithPasskey(client, {
+ *   email: 'user@example.com',
+ *   projectId: 'proj_456',
+ *   challenge: 'challenge',
+ *   attestation: {
+ *     attestationObject: 'attestationObject',
+ *     clientDataJson: 'clientDataJson',
+ *     credentialId: 'credentialId'
+ *   },
+ *   encodedPublicKey: 'encodedPublicKey'
+ * });
+ * ```
+ */
+export async function registerWithPasskey(
+  client: Client,
+  params: RegisterWithPasskeyParameters,
+): Promise<RegisterWithPasskeyReturnType> {
+  const { email, projectId, challenge, attestation, encodedPublicKey } = params
+
+  return client.request({
+    path: `${projectId}/auth/register/passkey`,
+    method: 'POST',
+    body: {
+      email,
+      attestation,
+      challenge,
+      encodedPublicKey,
+    },
+  })
+}

package/src/actions/index.ts

@@ -0,0 +1,41 @@
+// Auth actions
+export {
+  type AuthenticateWithEmailParameters,
+  type AuthenticateWithEmailReturnType,
+  type AuthenticateWithOAuthParameters,
+  type AuthenticateWithOAuthReturnType,
+  authenticateWithEmail,
+  authenticateWithOAuth,
+  type EmailCustomization,
+  type GetAuthProxyConfigIdReturnType,
+  type GetUserEmailParameters,
+  type GetUserEmailReturnType,
+  type GetWhoamiParameters,
+  type GetWhoamiReturnType,
+  getAuthProxyConfigId,
+  getUserEmail,
+  getWhoami,
+  type LoginWithOTPParameters,
+  type LoginWithOTPReturnType,
+  loginWithOTP,
+  type OtpContact,
+  type RegisterWithOTPParameters,
+  type RegisterWithOTPReturnType,
+  type RegisterWithPasskeyParameters,
+  type RegisterWithPasskeyReturnType,
+  registerWithOTP,
+  registerWithPasskey,
+} from './auth/index.js'
+
+// Wallet actions
+export {
+  type GetUserWalletParameters,
+  type GetUserWalletReturnType,
+  getUserWallet,
+  type SignRawPayloadParameters,
+  type SignRawPayloadReturnType,
+  type SignTransactionParameters,
+  type SignTransactionReturnType,
+  signRawPayload,
+  signTransaction,
+} from './wallet/index.js'