@zerodev/wallet-core 0.0.1-alpha.16 → 0.0.1-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerodev/wallet-core",
-  "version": "0.0.1-alpha.16",
+  "version": "0.0.1-alpha.18",
   "description": "ZeroDev Wallet SDK built on Turnkey",
   "main": "./dist/_cjs/index.js",
   "module": "./dist/_esm/index.js",
@@ -49,6 +49,8 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@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",
@@ -59,6 +61,7 @@
     "viem": "^2.38.0"
   },
   "devDependencies": {
+    "@hpke/core": "^1.9.0",
     "@types/node": "^20.0.0",
     "typescript": "5.9.3"
   },

package/src/actions/auth/getAuthenticators.ts

@@ -9,31 +9,31 @@ export type GetAuthenticatorsParameters = {
   token: string
 }
 
-/** An OAuth authenticator linked to the user (PascalCase from Go default marshaling) */
+/** An OAuth authenticator linked to the user */
 export type OAuthAuthenticator = {
-  Provider?: string
-  ClientId?: string
-  Subject?: string
+  provider?: string
+  clientId?: string
+  subject?: string
   [key: string]: unknown
 }
 
-/** A passkey (WebAuthn) authenticator (PascalCase from Go default marshaling) */
+/** A passkey (WebAuthn) authenticator */
 export type PasskeyAuthenticator = {
-  RpId?: string
-  PublicKey?: string
-  CredentialId?: string
+  rpId?: string
+  publicKey?: string
+  credentialId?: string
   [key: string]: unknown
 }
 
-/** An email contact linked to the user (PascalCase from Go default marshaling) */
+/** An email contact linked to the user */
 export type EmailContact = {
-  Email?: string
+  email?: string
   [key: string]: unknown
 }
 
-/** An API key authenticator (PascalCase from Go default marshaling) */
+/** An API key authenticator */
 export type ApiKeyAuthenticator = {
-  ApiKey?: string
+  apiKey?: string
   [key: string]: unknown
 }
 

package/src/actions/auth/registerWithOTP.ts

@@ -31,6 +31,12 @@ export type RegisterWithOTPParameters = {
 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
 }
 
 /**

package/src/client/authProxy.ts

@@ -10,10 +10,11 @@ export type AuthProxyClientConfig = {
 export type AuthProxyVerifyOtpRequest = {
   /** The OTP ID from registration */
   otpId: string
-  /** The OTP code entered by the user */
-  otpCode: string
-  /** The public key to associate with the verification */
-  public_key: string
+  /**
+   * HPKE-sealed bundle containing `{otp_code, public_key}` encrypted to the
+   * enclave's per-session target key. Produced by `encryptOtpAttempt`.
+   */
+  encryptedOtpBundle: string
 }
 
 export type AuthProxyVerifyOtpResponse = {
@@ -62,15 +63,20 @@ export function createAuthProxyClient(config: AuthProxyClientConfig) {
 
   return {
     /**
-     * Verifies an OTP code with Turnkey's Auth Proxy
+     * Verifies an OTP attempt with Turnkey's Auth Proxy.
      *
-     * Returns a verificationToken that should be passed to the backend's
-     * /auth/login/otp endpoint along with a client signature.
+     * The `encryptedOtpBundle` is HPKE-sealed `{otp_code, public_key}` JSON
+     * (see `encryptOtpAttempt`). The auth proxy forwards the ciphertext to
+     * the TLS Fetcher enclave, which decrypts it, verifies the OTP code, and
+     * returns a `verificationToken` bound to the embedded public key.
+     *
+     * Pass the returned `verificationToken` to `/auth/login/otp` along with
+     * a client signature to complete the login.
      */
     async verifyOtp(
       params: AuthProxyVerifyOtpRequest,
     ): Promise<AuthProxyVerifyOtpResponse> {
-      return request<AuthProxyVerifyOtpResponse>('/v1/otp_verify', params)
+      return request<AuthProxyVerifyOtpResponse>('/v1/otp_verify_v2', params)
     },
   }
 }

package/src/constants.ts

@@ -3,3 +3,11 @@ 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 = '0d98e826-dd8f-44ca-a585-3afcd27d4002'
 export const KMS_SERVER_URL = 'https://kms.staging.zerodev.app'
+
+// Pinned ECDSA P-256 public key (uncompressed, 65 bytes hex) of Turnkey's
+// TLS Fetcher Sign enclave. Used to verify the signature on the OTP encryption
+// target bundle returned by /auth/init/otp before HPKE-encrypting the OTP
+// attempt. The bundle's `dataSignature` is verified against this key, so a
+// compromised proxy cannot substitute its own ephemeral key.
+export const TURNKEY_TLS_FETCHER_SIGN_PUBLIC_KEY =
+  '046b4f88421f76b6ba418afc2ea1d8ced671337d7db6b80478a60d8531bf8f17fa9a512f0fef96fc0c9b4cd9dff70b34992e520ce04c79d931f6ff6296b547d201'

package/src/core/createZeroDevWallet.ts

@@ -25,6 +25,7 @@ import {
 } from '../storage/manager.js'
 import { SessionType, type ZeroDevWalletSession } from '../types/session.js'
 import { buildClientSignature } from '../utils/buildClientSignature.js'
+import { encryptOtpAttempt } from '../utils/encryptOtpAttempt.js'
 import {
   base64UrlEncode,
   generateCompressedPublicKeyFromKeyPair,
@@ -72,6 +73,11 @@ export type AuthParams =
       mode: 'verifyOtp'
       otpId: string
       otpCode: string
+      /**
+       * The encryption target bundle returned by the matching `sendOtp` call.
+       * Required — used to HPKE-encrypt the OTP attempt to the enclave.
+       */
+      otpEncryptionTargetBundle: string
     }
   | {
       type: 'magicLink'
@@ -85,6 +91,11 @@ export type AuthParams =
       mode: 'verify'
       otpId: string
       code: string
+      /**
+       * The encryption target bundle returned by the matching `sendMagicLink`
+       * (a.k.a. magicLink `send`) call. Required for the encrypted-OTP flow.
+       */
+      otpEncryptionTargetBundle: string
     }
 
 export interface ZeroDevWalletSDK {
@@ -379,6 +390,7 @@ export async function createZeroDevWallet(
                 mode: 'verifyOtp',
                 otpId: params.otpId,
                 otpCode: params.code,
+                otpEncryptionTargetBundle: params.otpEncryptionTargetBundle,
               }
             }
           } else {
@@ -401,7 +413,7 @@ export async function createZeroDevWallet(
           }
 
           if (otpParams.mode === 'verifyOtp') {
-            const { otpId, otpCode } = otpParams
+            const { otpId, otpCode, otpEncryptionTargetBundle } = otpParams
 
             // Step 1: Generate new key pair
             await client.indexedDbStamper.resetKeyPair()
@@ -411,7 +423,15 @@ export async function createZeroDevWallet(
               throw new Error('Failed to get public key')
             }
 
-            // Step 2: Verify OTP via Auth Proxy
+            // Step 2a: HPKE-seal the OTP attempt to the enclave's per-session
+            // target key. The auth proxy never sees the plaintext OTP code.
+            const encryptedOtpBundle = await encryptOtpAttempt({
+              otpCode,
+              publicKey: targetPublicKey,
+              encryptionTargetBundle: otpEncryptionTargetBundle,
+            })
+
+            // Step 2b: Verify OTP via Auth Proxy
             if (!cachedAuthProxyConfigId) {
               const { authProxyConfigId } = await client.getAuthProxyConfigId()
               cachedAuthProxyConfigId = authProxyConfigId
@@ -422,8 +442,7 @@ export async function createZeroDevWallet(
 
             const { verificationToken } = await authProxyClient.verifyOtp({
               otpId,
-              otpCode,
-              public_key: targetPublicKey,
+              encryptedOtpBundle,
             })
 
             // Step 3: Build client signature

package/src/utils/encryptOtpAttempt.ts

@@ -0,0 +1,142 @@
+/**
+ * Wraps the OTP code + client public key in a Turnkey-compatible HPKE bundle
+ * for the `/v1/otp_verify_v2` auth-proxy endpoint.
+ *
+ * Bundle flow (RFC 9180 mode_base over Turnkey's TLS Fetcher enclave):
+ *   1. The backend's /init/otp returns a signed envelope that contains an
+ *      ephemeral HPKE public key (`targetPublic`) generated fresh by the
+ *      enclave for this OTP attempt.
+ *   2. We verify the envelope's ECDSA signature against a pinned production
+ *      key (`TURNKEY_TLS_FETCHER_SIGN_PUBLIC_KEY`) so a compromised proxy
+ *      cannot substitute its own ephemeral key.
+ *   3. We HPKE-seal `{otp_code, public_key}` to `targetPublic`. The auth proxy
+ *      forwards the ciphertext to the enclave; only the enclave can decrypt
+ *      it. The enclave then issues a `verificationToken` bound to the public
+ *      key embedded in the plaintext.
+ *
+ * See: tkhq/go-sdk `examples/email_otp` and `pkg/enclave_encrypt`.
+ */
+
+import { p256 } from '@noble/curves/nist.js'
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js'
+import { TURNKEY_TLS_FETCHER_SIGN_PUBLIC_KEY } from '../constants.js'
+import { hpkeSealP256 } from './hpke.js'
+
+const BUNDLE_DATA_VERSION = 'v1.0.0'
+
+type EncryptionTargetEnvelope = {
+  version: string
+  /** Hex-encoded JSON: `{ targetPublic, organizationId, userId? }` */
+  data: string
+  /** Hex-encoded ECDSA-P256 signature over the raw `data` bytes (DER). */
+  dataSignature: string
+  /** Hex-encoded uncompressed P-256 pubkey of the signing enclave. */
+  enclaveQuorumPublic: string
+}
+
+type SignedTargetData = {
+  targetPublic: string
+  organizationId?: string
+  userId?: string
+}
+
+export type EncryptOtpAttemptParams = {
+  /** The OTP code the user entered. */
+  otpCode: string
+  /**
+   * The client's session public key (compressed P-256 hex). The enclave binds
+   * this key into the `verificationToken` it issues.
+   */
+  publicKey: string
+  /** The signed envelope returned by `/auth/init/otp`. */
+  encryptionTargetBundle: string
+  /**
+   * Test-only override for the pinned signing key. Production callers should
+   * leave this undefined; it exists so tests don't have to use the real key.
+   */
+  dangerouslyOverrideSignerPublicKey?: string
+}
+
+/**
+ * Returns a JSON string ready to be sent as `encryptedOtpBundle` on
+ * `POST /v1/otp_verify_v2`.
+ */
+export async function encryptOtpAttempt({
+  otpCode,
+  publicKey,
+  encryptionTargetBundle,
+  dangerouslyOverrideSignerPublicKey,
+}: EncryptOtpAttemptParams): Promise<string> {
+  const expectedSignerHex =
+    dangerouslyOverrideSignerPublicKey ?? TURNKEY_TLS_FETCHER_SIGN_PUBLIC_KEY
+
+  let envelope: EncryptionTargetEnvelope
+  try {
+    envelope = JSON.parse(encryptionTargetBundle)
+  } catch (err) {
+    throw new Error(
+      `encryptOtpAttempt: failed to parse encryption target bundle: ${(err as Error).message}`,
+    )
+  }
+
+  if (envelope.version !== BUNDLE_DATA_VERSION) {
+    throw new Error(
+      `encryptOtpAttempt: unsupported bundle version ${envelope.version}`,
+    )
+  }
+
+  if (
+    envelope.enclaveQuorumPublic.toLowerCase() !==
+    expectedSignerHex.toLowerCase()
+  ) {
+    throw new Error(
+      'encryptOtpAttempt: enclave quorum public key does not match pinned signing key',
+    )
+  }
+
+  const dataBytes = hexToBytes(envelope.data)
+  const signatureBytes = hexToBytes(envelope.dataSignature)
+  const signerPublicKeyBytes = hexToBytes(envelope.enclaveQuorumPublic)
+
+  // The Go side does sha256(data) then ASN.1 DER ECDSA verify, without
+  // enforcing low-S. Match that here.
+  const valid = p256.verify(signatureBytes, dataBytes, signerPublicKeyBytes, {
+    prehash: true,
+    format: 'der',
+    lowS: false,
+  })
+  if (!valid) {
+    throw new Error('encryptOtpAttempt: invalid enclave signature on bundle')
+  }
+
+  let signedData: SignedTargetData
+  try {
+    signedData = JSON.parse(new TextDecoder().decode(dataBytes))
+  } catch (err) {
+    throw new Error(
+      `encryptOtpAttempt: failed to parse signed bundle data: ${(err as Error).message}`,
+    )
+  }
+  if (!signedData.targetPublic) {
+    throw new Error('encryptOtpAttempt: missing targetPublic in signed data')
+  }
+
+  const targetPublicKey = hexToBytes(signedData.targetPublic)
+
+  // Plaintext shape matches what the Go example marshals:
+  //   { otp_code: string, public_key: string }
+  const plaintext = new TextEncoder().encode(
+    JSON.stringify({ otp_code: otpCode, public_key: publicKey }),
+  )
+
+  const { encappedPublic, ciphertext } = await hpkeSealP256({
+    receiverPublicKey: targetPublicKey,
+    plaintext,
+  })
+
+  // Wire format = the Go SDK's `ClientSendMsg`: Bytes fields hex-encoded.
+  return JSON.stringify({
+    encappedPublic: bytesToHex(encappedPublic),
+    ciphertext: bytesToHex(ciphertext),
+  })
+}

package/src/utils/hpke.ts

@@ -0,0 +1,245 @@
+/**
+ * HPKE (RFC 9180) seal for Turnkey enclave-encrypted requests.
+ *
+ * Suite: DHKEM(P-256, HKDF-SHA256) / HKDF-SHA256 / AES-256-GCM
+ *   - KEM ID  = 0x0010 (DHKEM-P256-HKDF-SHA256)
+ *   - KDF ID  = 0x0001 (HKDF-SHA256)
+ *   - AEAD ID = 0x0002 (AES-256-GCM)
+ *
+ * Wire format and AAD construction match Turnkey's enclave_encrypt Go package:
+ *   info = "turnkey_hpke"
+ *   aad  = enc || pkR  (both 65-byte uncompressed P-256 points)
+ *
+ * References:
+ *   - RFC 9180 §4 / §5
+ *   - tkhq/go-sdk/pkg/enclave_encrypt
+ */
+
+import { p256 } from '@noble/curves/nist.js'
+import { expand, extract } from '@noble/hashes/hkdf.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+
+const KEM_ID = 0x0010
+const KDF_ID = 0x0001
+const AEAD_ID = 0x0002
+
+// Output sizes for the chosen primitives.
+const NH = 32 // SHA-256 output
+const NK = 32 // AES-256 key
+const NN = 12 // AES-GCM nonce
+const NPK = 65 // uncompressed P-256 point: 0x04 || X || Y
+
+const TURNKEY_HPKE_INFO = new TextEncoder().encode('turnkey_hpke')
+
+const HPKE_VERSION = new TextEncoder().encode('HPKE-v1')
+
+// suite_id for the HPKE context: "HPKE" || I2OSP(KEM,2) || I2OSP(KDF,2) || I2OSP(AEAD,2)
+const HPKE_SUITE_ID = concat(
+  new TextEncoder().encode('HPKE'),
+  i2osp(KEM_ID, 2),
+  i2osp(KDF_ID, 2),
+  i2osp(AEAD_ID, 2),
+)
+
+// suite_id for the KEM scope: "KEM" || I2OSP(KEM,2)
+const KEM_SUITE_ID = concat(new TextEncoder().encode('KEM'), i2osp(KEM_ID, 2))
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, p) => sum + p.length, 0)
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const p of parts) {
+    out.set(p, offset)
+    offset += p.length
+  }
+  return out
+}
+
+function i2osp(n: number, len: number): Uint8Array {
+  const out = new Uint8Array(len)
+  for (let i = len - 1; i >= 0; i--) {
+    out[i] = n & 0xff
+    n >>>= 8
+  }
+  return out
+}
+
+// LabeledExtract(salt, label, ikm, suite_id) =
+//   HKDF-Extract(salt, "HPKE-v1" || suite_id || label || ikm)
+function labeledExtract(
+  salt: Uint8Array,
+  label: string,
+  ikm: Uint8Array,
+  suiteId: Uint8Array,
+): Uint8Array {
+  const labeledIkm = concat(
+    HPKE_VERSION,
+    suiteId,
+    new TextEncoder().encode(label),
+    ikm,
+  )
+  return extract(sha256, labeledIkm, salt)
+}
+
+// LabeledExpand(prk, label, info, L, suite_id) =
+//   HKDF-Expand(prk, I2OSP(L,2) || "HPKE-v1" || suite_id || label || info, L)
+function labeledExpand(
+  prk: Uint8Array,
+  label: string,
+  info: Uint8Array,
+  length: number,
+  suiteId: Uint8Array,
+): Uint8Array {
+  const labeledInfo = concat(
+    i2osp(length, 2),
+    HPKE_VERSION,
+    suiteId,
+    new TextEncoder().encode(label),
+    info,
+  )
+  return expand(sha256, prk, labeledInfo, length)
+}
+
+// DHKEM Encap: returns (sharedSecret, enc)
+// sharedSecret is 32 bytes; enc is the serialized ephemeral pubkey (65 bytes uncompressed).
+function encap(receiverPublicKey: Uint8Array): {
+  sharedSecret: Uint8Array
+  enc: Uint8Array
+} {
+  const ephSk = p256.utils.randomSecretKey()
+  const ephPkUncompressed = p256.getPublicKey(ephSk, false)
+
+  // ECDH: returns the serialized shared point. Pass isCompressed=true so the
+  // first byte is the SEC1 prefix and bytes [1, 33) are the x-coordinate.
+  const sharedPoint = p256.getSharedSecret(
+    ephSk,
+    receiverPublicKey,
+    /* isCompressed */ true,
+  )
+  const dh = sharedPoint.slice(1, 33)
+
+  const kemContext = concat(ephPkUncompressed, receiverPublicKey)
+
+  const eaePrk = labeledExtract(new Uint8Array(0), 'eae_prk', dh, KEM_SUITE_ID)
+  const sharedSecret = labeledExpand(
+    eaePrk,
+    'shared_secret',
+    kemContext,
+    NH,
+    KEM_SUITE_ID,
+  )
+
+  return { sharedSecret, enc: ephPkUncompressed }
+}
+
+// KeySchedule for mode_base: returns (key, base_nonce).
+function keySchedule(
+  sharedSecret: Uint8Array,
+  info: Uint8Array,
+): { key: Uint8Array; baseNonce: Uint8Array } {
+  const empty = new Uint8Array(0)
+
+  const pskIdHash = labeledExtract(empty, 'psk_id_hash', empty, HPKE_SUITE_ID)
+  const infoHash = labeledExtract(empty, 'info_hash', info, HPKE_SUITE_ID)
+
+  // mode_base = 0x00 prepended to (psk_id_hash || info_hash)
+  const keyScheduleContext = concat(new Uint8Array([0]), pskIdHash, infoHash)
+
+  const secret = labeledExtract(sharedSecret, 'secret', empty, HPKE_SUITE_ID)
+
+  const key = labeledExpand(
+    secret,
+    'key',
+    keyScheduleContext,
+    NK,
+    HPKE_SUITE_ID,
+  )
+  const baseNonce = labeledExpand(
+    secret,
+    'base_nonce',
+    keyScheduleContext,
+    NN,
+    HPKE_SUITE_ID,
+  )
+
+  return { key, baseNonce }
+}
+
+// Web Crypto's BufferSource type rejects `Uint8Array<ArrayBufferLike>` (which
+// noble/v2 returns) under strict TS lib settings because the underlying buffer
+// could in principle be a SharedArrayBuffer. Copy into a fresh ArrayBuffer to
+// satisfy the type.
+function toArrayBuffer(u8: Uint8Array): ArrayBuffer {
+  const out = new ArrayBuffer(u8.byteLength)
+  new Uint8Array(out).set(u8)
+  return out
+}
+
+async function aesGcmSeal(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  aad: Uint8Array,
+  plaintext: Uint8Array,
+): Promise<Uint8Array> {
+  // Web Crypto returns ciphertext || tag (16 bytes appended). Matches the
+  // single-blob format Turnkey's `Sealer.Seal` produces.
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    toArrayBuffer(key),
+    { name: 'AES-GCM' },
+    /* extractable */ false,
+    ['encrypt'],
+  )
+  const ct = await crypto.subtle.encrypt(
+    {
+      name: 'AES-GCM',
+      iv: toArrayBuffer(nonce),
+      additionalData: toArrayBuffer(aad),
+      tagLength: 128,
+    },
+    cryptoKey,
+    toArrayBuffer(plaintext),
+  )
+  return new Uint8Array(ct)
+}
+
+export type HpkeSealResult = {
+  /** Ephemeral sender public key (uncompressed P-256, 65 bytes). */
+  encappedPublic: Uint8Array
+  /** AES-256-GCM ciphertext with a 16-byte authentication tag appended. */
+  ciphertext: Uint8Array
+}
+
+/**
+ * Single-shot HPKE seal in mode_base for Turnkey's TLS Fetcher enclave.
+ *
+ * Uses the fixed Turnkey `info = "turnkey_hpke"` and the AAD shape
+ * `enc || receiverPublicKey` so the resulting bundle is decryptable by
+ * `enclave_encrypt.EnclaveEncryptServer.Decrypt`.
+ *
+ * @param receiverPublicKey - The enclave's ephemeral target public key
+ *   (uncompressed P-256, 65 bytes), extracted from the encryption target bundle.
+ * @param plaintext - The bytes to encrypt (e.g. the JSON-encoded OTP attempt).
+ */
+export async function hpkeSealP256({
+  receiverPublicKey,
+  plaintext,
+}: {
+  receiverPublicKey: Uint8Array
+  plaintext: Uint8Array
+}): Promise<HpkeSealResult> {
+  if (receiverPublicKey.length !== NPK) {
+    throw new Error(
+      `hpkeSealP256: receiverPublicKey must be ${NPK} bytes (uncompressed P-256), got ${receiverPublicKey.length}`,
+    )
+  }
+
+  const { sharedSecret, enc } = encap(receiverPublicKey)
+  const { key, baseNonce } = keySchedule(sharedSecret, TURNKEY_HPKE_INFO)
+
+  // First message of the context, sequence 0 → nonce = base_nonce.
+  const aad = concat(enc, receiverPublicKey)
+  const ciphertext = await aesGcmSeal(key, baseNonce, aad, plaintext)
+
+  return { encappedPublic: enc, ciphertext }
+}