@zerodev/wallet-core 0.0.1-alpha.9 → 0.0.1

package/package.json

@@ -1,15 +1,69 @@
 {
   "name": "@zerodev/wallet-core",
-  "version": "0.0.1-alpha.9",
+  "version": "0.0.1",
   "description": "ZeroDev Wallet SDK built on Turnkey",
+  "sideEffects": false,
   "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"
+      "react-native": {
+        "types": "./dist/_types/index.native.d.ts",
+        "default": "./dist/_esm/index.native.js"
+      },
+      "browser": {
+        "types": "./dist/_types/index.d.ts",
+        "default": "./dist/_esm/index.js"
+      },
+      "import": {
+        "types": "./dist/_types/index.d.ts",
+        "default": "./dist/_esm/index.js"
+      },
+      "require": {
+        "types": "./dist/_types/index.d.ts",
+        "default": "./dist/_cjs/index.js"
+      },
+      "default": {
+        "types": "./dist/_types/index.d.ts",
+        "default": "./dist/_esm/index.js"
+      }
+    },
+    "./react-native": {
+      "browser": "./dist/_esm/stubs/native-on-web.js",
+      "node": "./dist/_esm/stubs/native-on-web.js",
+      "import": {
+        "types": "./dist/_types/index.native.d.ts",
+        "default": "./dist/_esm/index.native.js"
+      },
+      "default": "./dist/_esm/index.native.js"
+    },
+    "./react-native/stampers/secure-store": {
+      "browser": "./dist/_esm/stubs/native-on-web.js",
+      "node": "./dist/_esm/stubs/native-on-web.js",
+      "import": {
+        "types": "./dist/_types/native/stampers/secureStore.d.ts",
+        "default": "./dist/_esm/native/stampers/secureStore.js"
+      },
+      "default": "./dist/_esm/native/stampers/secureStore.js"
+    },
+    "./react-native/stampers/passkey": {
+      "browser": "./dist/_esm/stubs/native-on-web.js",
+      "node": "./dist/_esm/stubs/native-on-web.js",
+      "import": {
+        "types": "./dist/_types/native/stampers/passkey.d.ts",
+        "default": "./dist/_esm/native/stampers/passkey.js"
+      },
+      "default": "./dist/_esm/native/stampers/passkey.js"
+    },
+    "./react-native/storage/async-storage": {
+      "browser": "./dist/_esm/stubs/native-on-web.js",
+      "node": "./dist/_esm/stubs/native-on-web.js",
+      "import": {
+        "types": "./dist/_types/native/storage/asyncStorage.d.ts",
+        "default": "./dist/_esm/native/storage/asyncStorage.js"
+      },
+      "default": "./dist/_esm/native/storage/asyncStorage.js"
     },
     "./viem": {
       "types": "./dist/_types/adapters/viem.d.ts",
@@ -20,11 +74,6 @@
       "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": [
@@ -49,6 +98,9 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
     "@turnkey/http": "^3.12.1",
     "@turnkey/iframe-stamper": "^2.5.0",
     "@turnkey/indexed-db-stamper": "^1.1.1",
@@ -56,11 +108,48 @@
     "json-canonicalize": "^2.0.0"
   },
   "peerDependencies": {
-    "viem": "^2.38.0"
+    "viem": "^2.38.0",
+    "@react-native-async-storage/async-storage": ">=2.0.0",
+    "@turnkey/api-key-stamper": ">=0.6.0",
+    "@turnkey/crypto": ">=2.8.0",
+    "@turnkey/react-native-passkey-stamper": ">=1.2.0",
+    "expo-secure-store": ">=14.0.0",
+    "react-native": ">=0.73.0",
+    "uuid": ">=11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "@turnkey/api-key-stamper": {
+      "optional": true
+    },
+    "@turnkey/crypto": {
+      "optional": true
+    },
+    "@turnkey/react-native-passkey-stamper": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    },
+    "uuid": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@hpke/core": "^1.9.0",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "@turnkey/api-key-stamper": "0.6.4",
+    "@turnkey/crypto": "2.8.13",
+    "@turnkey/react-native-passkey-stamper": "1.2.12",
     "@types/node": "^20.0.0",
-    "typescript": "5.9.3"
+    "expo-secure-store": "55.0.9",
+    "typescript": "5.9.3",
+    "uuid": "^13.0.0"
   },
   "scripts": {
     "build": "pnpm run clean && pnpm run build:cjs && pnpm run build:esm && pnpm run build:types",

package/src/actions/auth/authenticateWithEmail.ts

@@ -1,10 +1,5 @@
 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
@@ -12,8 +7,6 @@ export type AuthenticateWithEmailParameters = {
   projectId: string
   /** Target public key for authentication */
   targetPublicKey: string
-  /** Optional email customization settings */
-  emailCustomization?: EmailCustomization
 }
 
 export type AuthenticateWithEmailReturnType = {
@@ -37,14 +30,13 @@ export async function authenticateWithEmail(
   client: Client,
   params: AuthenticateWithEmailParameters,
 ): Promise<AuthenticateWithEmailReturnType> {
-  const { email, projectId, targetPublicKey, emailCustomization } = params
+  const { email, projectId, targetPublicKey } = params
 
   return await client.request({
     path: `${projectId}/auth/email-magic`,
     method: 'POST',
     body: {
       email,
-      emailCustomization,
       targetPublicKey,
       projectId,
     },

package/src/actions/auth/authenticateWithOAuth.ts

@@ -5,6 +5,10 @@ export type AuthenticateWithOAuthParameters = {
   provider: string
   /** The project ID for the request */
   projectId: string
+  /** The session ID from the OAuth callback URL */
+  sessionId: string
+  /** Proof-of-possession signature for `sessionId`. */
+  popSignature: string
 }
 
 export type AuthenticateWithOAuthReturnType = {
@@ -19,11 +23,11 @@ export type AuthenticateWithOAuthReturnType = {
 }
 
 /**
- * Authenticates a user with OAuth using cookie-based backend flow
+ * Authenticates a user with OAuth using a server-side session ID
  *
- * 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.
+ * The backend stores the OAuth session server-side and returns a session ID
+ * via the callback URL. The SDK extracts this session ID and sends it in
+ * the request body.
  *
  * @param client - The ZeroDev Wallet client
  * @param params - The parameters for OAuth authentication
@@ -34,6 +38,8 @@ export type AuthenticateWithOAuthReturnType = {
  * const result = await authenticateWithOAuth(client, {
  *   provider: 'google',
  *   projectId: 'proj_456',
+ *   sessionId: 'abc123',
+ *   popSignature: '3045022100...',
  * });
  * ```
  */
@@ -41,12 +47,11 @@ export async function authenticateWithOAuth(
   client: Client,
   params: AuthenticateWithOAuthParameters,
 ): Promise<AuthenticateWithOAuthReturnType> {
-  const { projectId } = params
+  const { projectId, sessionId, popSignature } = params
 
   return await client.request({
     path: `${projectId}/auth/oauth`,
     method: 'POST',
-    body: null,
-    credentials: 'include',
+    body: { sessionId, popSignature },
   })
 }

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

@@ -0,0 +1,89 @@
+import type { Client } from '../../client/types.js'
+
+export type GetAuthenticatorsParameters = {
+  /** The sub-organization ID to query authenticators for */
+  subOrganizationId: string
+  /** The project ID for the request */
+  projectId: string
+  /** The session token for authorization */
+  token: string
+}
+
+/** An OAuth authenticator linked to the user */
+export type OAuthAuthenticator = {
+  provider?: string
+  clientId?: string
+  subject?: string
+  [key: string]: unknown
+}
+
+/** A passkey (WebAuthn) authenticator */
+export type PasskeyAuthenticator = {
+  rpId?: string
+  publicKey?: string
+  credentialId?: string
+  [key: string]: unknown
+}
+
+/** An email contact linked to the user */
+export type EmailContact = {
+  email?: string
+  [key: string]: unknown
+}
+
+/** An API key authenticator */
+export type ApiKeyAuthenticator = {
+  apiKey?: string
+  [key: string]: unknown
+}
+
+export type GetAuthenticatorsReturnType = {
+  /** OAuth providers linked to the user (null if none) */
+  oauths: OAuthAuthenticator[] | null
+  /** Passkey authenticators registered for the user (null if none) */
+  passkeys: PasskeyAuthenticator[] | null
+  /** Email contacts associated with the user (null if none) */
+  emailContacts: EmailContact[] | null
+  /** API keys associated with the user (null if none) */
+  apiKeys: ApiKeyAuthenticator[] | null
+}
+
+/**
+ * Fetches all authenticators (oauths, passkeys, emailContacts, apiKeys) for
+ * the authenticated user within the given project/sub-organization.
+ *
+ * Corresponds to `POST /api/v1/{projectId}/authenticators`.
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for the authenticators request
+ * @returns The user's authenticators grouped by type
+ *
+ * @example
+ * ```ts
+ * const authenticators = await getAuthenticators(client, {
+ *   subOrganizationId: 'suborg_123',
+ *   projectId: 'proj_456',
+ *   token: 'session_token_abc',
+ * });
+ * console.log(authenticators.oauths, authenticators.passkeys);
+ * ```
+ */
+export async function getAuthenticators(
+  client: Client,
+  params: GetAuthenticatorsParameters,
+): Promise<GetAuthenticatorsReturnType> {
+  const { projectId, token } = params
+
+  // GET behind StampCheckUser: the backend resolves the user from the stamped
+  // credential (+ session JWT), so no body / sub-org is sent. The stamp signs
+  // the X-Timestamp value (see transport `stampPostion: 'timestamp'`).
+  return await client.request({
+    path: `${projectId}/authenticators`,
+    method: 'GET',
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+    stamp: true,
+    stampPostion: 'timestamp',
+  })
+}

package/src/actions/auth/getOAuthLoginUrl.ts

@@ -0,0 +1,48 @@
+import type { Client } from '../../client/types.js'
+
+export type GetOAuthLoginUrlParameters = {
+  /** OAuth provider — currently only `'google'` is supported. */
+  provider: 'google'
+  /** The project ID for the request. */
+  projectId: string
+  /**
+   * The session public key (compressed P-256 hex, lowercase, with or
+   * without `0x` prefix). The backend embeds `sha256(utf8(hex))` as the
+   * OIDC `nonce` so the SDK can verify the URL was minted for this key.
+   */
+  publicKey: string
+  /**
+   * Where the popup should land after the OAuth round-trip
+   * (e.g. `https://app.example.com/dashboard?oauth_success=true`).
+   * Must be on the project's whitelist.
+   */
+  returnTo: string
+}
+
+export type GetOAuthLoginUrlReturnType = string
+
+/**
+ * Fetches the Google OAuth authorization URL from the backend.
+ *
+ * The SDK must verify the returned URL's `nonce` against
+ * `sha256(utf8(publicKey))` (and the host is `accounts.google.com`)
+ * before opening it in a popup — the backend is not a trusted party.
+ * See audit finding TOB-KMS-1.
+ */
+export async function getOAuthLoginUrl(
+  client: Client,
+  params: GetOAuthLoginUrlParameters,
+): Promise<GetOAuthLoginUrlReturnType> {
+  if (params.provider !== 'google') {
+    throw new Error(`Unsupported OAuth provider: ${params.provider}`)
+  }
+  const query = new URLSearchParams({
+    project_id: params.projectId,
+    pub_key: params.publicKey.replace(/^0x/, '').toLowerCase(),
+    return_to: params.returnTo,
+  })
+  return await client.request<string>({
+    path: `oauth/google/login-url?${query.toString()}`,
+    method: 'GET',
+  })
+}

package/src/actions/auth/getParentOrgId.ts

@@ -0,0 +1,25 @@
+import type { Client } from '../../client/types.js'
+
+export type GetParentOrgIdReturnType = {
+  /** The Turnkey parent (base) organization ID configured on the backend. */
+  parentOrgId: string
+}
+
+/**
+ * Fetches the Turnkey parent (base) organization ID from the backend.
+ *
+ * Stamp-login payloads must be signed against this org — the backend relays the
+ * stamp under the parent org and derives the sub-org from the credential. The
+ * SDK fetches it (rather than hardcoding) so it works across environments
+ * (prod/staging/local) without a per-env override.
+ *
+ * Corresponds to `GET /api/v1/server-info/parent-org-id`.
+ */
+export async function getParentOrgId(
+  client: Client,
+): Promise<GetParentOrgIdReturnType> {
+  return await client.request({
+    path: 'server-info/parent-org-id',
+    method: 'GET',
+  })
+}

package/src/actions/auth/getWhoami.ts

@@ -1,3 +1,4 @@
+import { canonicalizeEx } from 'json-canonicalize'
 import type { Client } from '../../client/types.js'
 
 export type GetWhoamiParameters = {
@@ -5,6 +6,8 @@ export type GetWhoamiParameters = {
   organizationId: string
   /** The project ID for the request */
   projectId: string
+  /** The session token for authorization (required for session-based auth) */
+  token?: string
 }
 
 export type GetWhoamiReturnType = {
@@ -19,7 +22,11 @@ export type GetWhoamiReturnType = {
 }
 
 /**
- * Gets the current user information
+ * Gets the current user information.
+ *
+ * The whoami endpoint requires two stamps:
+ * 1. An inner stamp over the payload (for Turnkey verification) embedded in the body
+ * 2. An outer stamp over the full body (for KMS middleware) in the X-Stamp header
  *
  * @param client - The ZeroDev Wallet client
  * @param params - The parameters for the whoami request
@@ -29,7 +36,8 @@ export type GetWhoamiReturnType = {
  * ```ts
  * const userInfo = await getWhoami(client, {
  *   organizationId: 'org_123',
- *   projectId: 'proj_456'
+ *   projectId: 'proj_456',
+ *   token: 'session_token',
  * });
  * console.log(userInfo.userId); // 'user_789'
  * ```
@@ -38,14 +46,33 @@ export async function getWhoami(
   client: Client,
   params: GetWhoamiParameters,
 ): Promise<GetWhoamiReturnType> {
-  const { organizationId, projectId } = params
+  const { organizationId, projectId, token } = params
+
+  // Step 1: Inner stamp over the payload (for Turnkey verification)
+  const innerBody = { organizationId }
+  const innerBodyString = canonicalizeEx(innerBody)
+  const innerStamp = await client.apiKeyStamper.stamp(innerBodyString)
+
+  // Step 2: Build full body with inner stamp embedded
+  const fullBody = {
+    ...innerBody,
+    stamp: {
+      stampHeaderName: innerStamp.stampHeaderName,
+      stampHeaderValue: innerStamp.stampHeaderValue,
+    },
+  }
+
+  // Step 3: Outer stamp over full body (for KMS middleware)
+  const fullBodyString = canonicalizeEx(fullBody)
+  const outerStamp = await client.apiKeyStamper.stamp(fullBodyString)
 
   return await client.request({
     path: `${projectId}/whoami`,
     method: 'POST',
-    body: {
-      organizationId,
+    body: fullBody,
+    headers: {
+      [outerStamp.stampHeaderName]: outerStamp.stampHeaderValue,
+      ...(token && { Authorization: `Bearer ${token}` }),
     },
-    stamp: true,
   })
 }

package/src/actions/auth/index.ts

@@ -2,7 +2,6 @@ export {
   type AuthenticateWithEmailParameters,
   type AuthenticateWithEmailReturnType,
   authenticateWithEmail,
-  type EmailCustomization,
 } from './authenticateWithEmail.js'
 
 export {
@@ -11,10 +10,27 @@ export {
   authenticateWithOAuth,
 } from './authenticateWithOAuth.js'
 export {
-  type GetUserEmailParameters,
-  type GetUserEmailReturnType,
-  getUserEmail,
-} from './getUserEmail.js'
+  type ApiKeyAuthenticator,
+  type EmailContact,
+  type GetAuthenticatorsParameters,
+  type GetAuthenticatorsReturnType,
+  getAuthenticators,
+  type OAuthAuthenticator,
+  type PasskeyAuthenticator,
+} from './getAuthenticators.js'
+export {
+  type GetAuthProxyConfigIdReturnType,
+  getAuthProxyConfigId,
+} from './getAuthProxyConfigId.js'
+export {
+  type GetOAuthLoginUrlParameters,
+  type GetOAuthLoginUrlReturnType,
+  getOAuthLoginUrl,
+} from './getOAuthLoginUrl.js'
+export {
+  type GetParentOrgIdReturnType,
+  getParentOrgId,
+} from './getParentOrgId.js'
 export {
   type GetWhoamiParameters,
   type GetWhoamiReturnType,

package/src/actions/auth/loginWithStamp.ts

@@ -1,11 +1,7 @@
 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
-}
+import type { StamperType } from '../../types/session.js'
 
 export type LoginWithStampParameters = {
   /** The project ID for the request */
@@ -15,7 +11,7 @@ export type LoginWithStampParameters = {
   /** The encoded public key for the request */
   targetPublicKey: string
   /** The stamper type for the request */
-  stampWith?: 'indexedDb' | 'webauthn'
+  stampWith?: StamperType
 }
 
 export type LoginWithStampReturnType = {
@@ -58,19 +54,22 @@ export async function loginWithStamp(
     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)
+  if (stampWith === 'apiKey') {
+    stamp = await client.apiKeyStamper.stamp(stampPayload)
+  } else if (stampWith === 'passkey') {
+    stamp = await client.passkeyStamper.stamp(stampPayload)
   } else {
-    stamp = await client.indexedDbStamper.stamp(stampPayload)
+    stamp = await client.apiKeyStamper.stamp(stampPayload)
   }
 
   return client.request({
     path: `${projectId}/auth/login/stamp`,
     method: 'POST',
+    // The sub-org id is intentionally not sent: the backend derives it from
+    // the stamped credential. `organizationId` (the parent org) is only
+    // signed into `stampPayload` above so the stamp matches the body the
+    // backend relays to Turnkey — it is not part of the wire request.
     body: {
-      subOrganizationId: organizationId,
       targetPublicKey,
       timestamp: timestampIso,
       stamp,

package/src/actions/auth/registerWithOTP.ts

@@ -1,5 +1,4 @@
 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) */
@@ -15,19 +14,27 @@ export type RegisterWithOTPParameters = {
   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
+  /**
+   * Signed encryption target bundle issued by the TLS Fetcher enclave for
+   * this OTP session. Passed verbatim to the verify step so the SDK can
+   * HPKE-encrypt the OTP attempt to the enclave's ephemeral target key.
+   */
+  otpEncryptionTargetBundle: string
 }
 
 /**
  * Initiates OTP (One-Time Password) authentication
  * This will send an OTP code to the specified contact method
  *
+ * OTP code length/format and, when enabled, the magic-link URL template are
+ * configured per-project on the backend (`wallet.otp_configs`). The client no
+ * longer sends customization fields — they are ignored server-side.
+ *
  * @param client - The ZeroDev Wallet client
  * @param params - The parameters for OTP initiation
  * @returns The result including otpId needed for verification
@@ -50,7 +57,7 @@ export async function registerWithOTP(
   client: Client,
   params: RegisterWithOTPParameters,
 ): Promise<RegisterWithOTPReturnType> {
-  const { email, contact, projectId, emailCustomization } = params
+  const { email, contact, projectId } = params
 
   return await client.request({
     path: `${projectId}/auth/init/otp`,
@@ -58,7 +65,6 @@ export async function registerWithOTP(
     body: {
       email,
       contact,
-      emailCustomization,
     },
   })
 }

package/src/actions/auth/registerWithPasskey.ts

@@ -1,13 +1,6 @@
 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 */
@@ -41,7 +34,6 @@ export type RegisterWithPasskeyReturnType = {
  * @example
  * ```ts
  * const result = await registerWithPasskey(client, {
- *   email: 'user@example.com',
  *   projectId: 'proj_456',
  *   challenge: 'challenge',
  *   attestation: {
@@ -57,13 +49,12 @@ export async function registerWithPasskey(
   client: Client,
   params: RegisterWithPasskeyParameters,
 ): Promise<RegisterWithPasskeyReturnType> {
-  const { email, projectId, challenge, attestation, encodedPublicKey } = params
+  const { projectId, challenge, attestation, encodedPublicKey } = params
 
   return client.request({
     path: `${projectId}/auth/register/passkey`,
     method: 'POST',
     body: {
-      email,
       attestation,
       challenge,
       encodedPublicKey,