decane-connect-kit 1.0.3 → 2.0.0

package/dist/index.js

@@ -1,3 +1,145 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/social/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  AttestationError: () => AttestationError,
+  CallSequenceError: () => CallSequenceError,
+  DecaneConnectError: () => DecaneConnectError,
+  ExportNotAuthorizedError: () => ExportNotAuthorizedError,
+  InvalidApiKeyError: () => InvalidApiKeyError,
+  InvalidPinError: () => InvalidPinError,
+  InvalidRecoveryFileError: () => InvalidRecoveryFileError,
+  NetworkError: () => NetworkError,
+  NewDeviceError: () => NewDeviceError,
+  OriginNotAllowedError: () => OriginNotAllowedError,
+  PromptPinNotConfiguredError: () => PromptPinNotConfiguredError,
+  RecoveryFailedError: () => RecoveryFailedError,
+  RecoveryWalletMismatchError: () => RecoveryWalletMismatchError,
+  SessionExpiredError: () => SessionExpiredError,
+  ShareCorruptedError: () => ShareCorruptedError,
+  UnlockRequiredError: () => UnlockRequiredError,
+  UserCancelledError: () => UserCancelledError,
+  WebAuthnNotSupportedError: () => WebAuthnNotSupportedError,
+  WrongPasswordError: () => WrongPasswordError
+});
+var DecaneConnectError, InvalidApiKeyError, OriginNotAllowedError, SessionExpiredError, UnlockRequiredError, UserCancelledError, WebAuthnNotSupportedError, InvalidPinError, CallSequenceError, NetworkError, ShareCorruptedError, NewDeviceError, PromptPinNotConfiguredError, AttestationError, RecoveryFailedError, InvalidRecoveryFileError, WrongPasswordError, RecoveryWalletMismatchError, ExportNotAuthorizedError;
+var init_errors = __esm({
+  "src/social/errors.ts"() {
+    "use strict";
+    DecaneConnectError = class extends Error {
+      constructor(code, message, retryable = false) {
+        super(message);
+        this.name = "DecaneConnectError";
+        this.code = code;
+        this.retryable = retryable;
+      }
+    };
+    InvalidApiKeyError = class extends DecaneConnectError {
+      constructor() {
+        super("INVALID_API_KEY", "API key is invalid or revoked");
+      }
+    };
+    OriginNotAllowedError = class extends DecaneConnectError {
+      constructor(origin) {
+        super("ORIGIN_NOT_ALLOWED", `Origin ${origin} not in API key allowlist`);
+      }
+    };
+    SessionExpiredError = class extends DecaneConnectError {
+      constructor() {
+        super("SESSION_EXPIRED", "Session has expired \u2014 call unlock()", true);
+      }
+    };
+    UnlockRequiredError = class extends DecaneConnectError {
+      constructor() {
+        super("UNLOCK_REQUIRED", "Wallet must be unlocked before signing", true);
+      }
+    };
+    UserCancelledError = class extends DecaneConnectError {
+      constructor() {
+        super("USER_CANCELLED", "User cancelled the operation", true);
+      }
+    };
+    WebAuthnNotSupportedError = class extends DecaneConnectError {
+      constructor() {
+        super("WEBAUTHN_UNSUPPORTED", "This browser does not support WebAuthn");
+      }
+    };
+    InvalidPinError = class extends DecaneConnectError {
+      constructor() {
+        super("INVALID_PIN", "Incorrect PIN", true);
+      }
+    };
+    CallSequenceError = class extends DecaneConnectError {
+      constructor(msg) {
+        super("CALL_SEQUENCE", msg);
+      }
+    };
+    NetworkError = class extends DecaneConnectError {
+      constructor() {
+        super("NETWORK", "Network request failed", true);
+      }
+    };
+    ShareCorruptedError = class extends DecaneConnectError {
+      constructor() {
+        super("SHARE_CORRUPTED", "Stored device share is corrupted");
+      }
+    };
+    NewDeviceError = class extends DecaneConnectError {
+      constructor() {
+        super("NEW_DEVICE", "No device share found. Re-authenticate to set up this device.");
+      }
+    };
+    PromptPinNotConfiguredError = class extends DecaneConnectError {
+      constructor() {
+        super("PROMPT_PIN_NOT_CONFIGURED", "Passkey unavailable and no promptPin callback was provided in config");
+      }
+    };
+    AttestationError = class extends DecaneConnectError {
+      constructor(msg) {
+        super("ATTESTATION_FAILED", msg);
+      }
+    };
+    RecoveryFailedError = class extends DecaneConnectError {
+      constructor(reason) {
+        super("RECOVERY_FAILED", `Recovery failed: ${reason}`, true);
+      }
+    };
+    InvalidRecoveryFileError = class extends DecaneConnectError {
+      constructor() {
+        super("INVALID_RECOVERY_FILE", "This does not look like a valid recovery file", false);
+      }
+    };
+    WrongPasswordError = class extends DecaneConnectError {
+      constructor() {
+        super("WRONG_PASSWORD", "Incorrect password for this recovery file", true);
+      }
+    };
+    RecoveryWalletMismatchError = class extends DecaneConnectError {
+      constructor() {
+        super(
+          "RECOVERY_WALLET_MISMATCH",
+          "This recovery file is for a different wallet than the account you are signed into",
+          false
+        );
+      }
+    };
+    ExportNotAuthorizedError = class extends DecaneConnectError {
+      constructor() {
+        super("EXPORT_NOT_AUTHORIZED", "Export requires a fresh security check", true);
+      }
+    };
+  }
+});
+
 // src/core/emitter.ts
 function createEmitter() {
   const listeners = /* @__PURE__ */ new Map();
@@ -1734,94 +1876,10 @@ function createDecane(config = {}) {
 }
 
 // src/social/client.ts
+init_errors();
 import { Wallet } from "ethers";
 import { Transaction as Transaction2, VersionedTransaction, Keypair } from "@solana/web3.js";
 
-// src/social/errors.ts
-var DecaneConnectError = class extends Error {
-  constructor(code, message, retryable = false) {
-    super(message);
-    this.name = "DecaneConnectError";
-    this.code = code;
-    this.retryable = retryable;
-  }
-};
-var InvalidApiKeyError = class extends DecaneConnectError {
-  constructor() {
-    super("INVALID_API_KEY", "API key is invalid or revoked");
-  }
-};
-var OriginNotAllowedError = class extends DecaneConnectError {
-  constructor(origin) {
-    super("ORIGIN_NOT_ALLOWED", `Origin ${origin} not in API key allowlist`);
-  }
-};
-var SessionExpiredError = class extends DecaneConnectError {
-  constructor() {
-    super("SESSION_EXPIRED", "Session has expired \u2014 call unlock()", true);
-  }
-};
-var UnlockRequiredError = class extends DecaneConnectError {
-  constructor() {
-    super("UNLOCK_REQUIRED", "Wallet must be unlocked before signing", true);
-  }
-};
-var UserCancelledError = class extends DecaneConnectError {
-  constructor() {
-    super("USER_CANCELLED", "User cancelled the operation", true);
-  }
-};
-var WebAuthnNotSupportedError = class extends DecaneConnectError {
-  constructor() {
-    super("WEBAUTHN_UNSUPPORTED", "This browser does not support WebAuthn");
-  }
-};
-var InvalidPinError = class extends DecaneConnectError {
-  constructor() {
-    super("INVALID_PIN", "Incorrect PIN", true);
-  }
-};
-var CallSequenceError = class extends DecaneConnectError {
-  constructor(msg) {
-    super("CALL_SEQUENCE", msg);
-  }
-};
-var NetworkError = class extends DecaneConnectError {
-  constructor() {
-    super("NETWORK", "Network request failed", true);
-  }
-};
-var ShareCorruptedError = class extends DecaneConnectError {
-  constructor() {
-    super("SHARE_CORRUPTED", "Stored device share is corrupted");
-  }
-};
-var NewDeviceError = class extends DecaneConnectError {
-  constructor() {
-    super("NEW_DEVICE", "No device share found. Re-authenticate to set up this device.");
-  }
-};
-var PromptPinNotConfiguredError = class extends DecaneConnectError {
-  constructor() {
-    super("PROMPT_PIN_NOT_CONFIGURED", "Passkey unavailable and no promptPin callback was provided in config");
-  }
-};
-var AttestationError = class extends DecaneConnectError {
-  constructor(msg) {
-    super("ATTESTATION_FAILED", msg);
-  }
-};
-var RecoveryFailedError = class extends DecaneConnectError {
-  constructor(reason) {
-    super("RECOVERY_FAILED", `Recovery failed: ${reason}`, true);
-  }
-};
-var InvalidPhraseError = class extends DecaneConnectError {
-  constructor() {
-    super("INVALID_PHRASE", "Recovery phrase is invalid or corrupted", true);
-  }
-};
-
 // src/social/events.ts
 var EventEmitter = class {
   constructor() {
@@ -1840,6 +1898,7 @@ var EventEmitter = class {
 };
 
 // src/social/api.ts
+init_errors();
 var ERROR_MAP = {
   INVALID_API_KEY: InvalidApiKeyError,
   ORIGIN_NOT_ALLOWED: OriginNotAllowedError
@@ -1910,13 +1969,26 @@ var ApiClient = class {
       })
     });
   }
+  // ── WebAuthn registration (additive to the PRF-only passkey flow) ─────────
+  async getWebAuthnRegisterOptions(jwt, rpId, rpName) {
+    return this._request(`/webauthn/register-options?rpId=${encodeURIComponent(rpId)}&rpName=${encodeURIComponent(rpName)}`, {
+      headers: { Authorization: `Bearer ${jwt}` }
+    });
+  }
+  async postWebAuthnRegister(jwt, response, origin) {
+    await this._request("/webauthn/register", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${jwt}` },
+      body: JSON.stringify({ response, origin })
+    });
+  }
   async revoke(jwt) {
     await this._request("/auth/revoke", {
       method: "POST",
       headers: { Authorization: `Bearer ${jwt}` }
     });
   }
-  // ── Recovery (passkey-sync backup + phrase-saved flag) ────────────────────
+  // ── Recovery (passkey-sync backup + recovery-share-saved flag) ────────────
   async hasRecoveryBackup(jwt) {
     const data = await this._request("/recovery/backup/exists", {
       headers: { Authorization: `Bearer ${jwt}` }
@@ -1957,8 +2029,19 @@ var ApiClient = class {
       headers: { Authorization: `Bearer ${jwt}` }
     });
   }
-  async markPhraseSaved(jwt) {
-    await this._request("/recovery/phrase-saved", {
+  async markRecoveryShareSaved(jwt) {
+    await this._request("/recovery/share-saved", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${jwt}` }
+    });
+  }
+  async getRecoveryStatus(jwt) {
+    return this._request("/recovery/status", {
+      headers: { Authorization: `Bearer ${jwt}` }
+    });
+  }
+  async dismissRecoveryNag(jwt) {
+    await this._request("/recovery/nag-dismissed", {
       method: "POST",
       headers: { Authorization: `Bearer ${jwt}` }
     });
@@ -1967,8 +2050,8 @@ var ApiClient = class {
 function bytesToB64(bytes) {
   return btoa(String.fromCharCode(...bytes));
 }
-function b64ToBytes(b642) {
-  return Uint8Array.from(atob(b642), (c) => c.charCodeAt(0));
+function b64ToBytes(b644) {
+  return Uint8Array.from(atob(b644), (c) => c.charCodeAt(0));
 }
 
 // src/social/storage.ts
@@ -1994,7 +2077,11 @@ var Storage = class {
   }
 };
 
+// src/social/teeClient.ts
+import { startAuthentication } from "@simplewebauthn/browser";
+
 // src/social/attestation.ts
+init_errors();
 import { getCollateralAndVerify } from "@phala/dcap-qvl";
 
 // ../../infra/tee-measurement.json
@@ -2053,11 +2140,15 @@ async function verifyTeeAttestation(teeUrl, nonce) {
 }
 
 // src/social/teeClient.ts
+init_errors();
 function bytesToBase64(b) {
   let s = "";
   for (const byte of b) s += String.fromCharCode(byte);
   return btoa(s);
 }
+function base64ToBytes(s) {
+  return Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+}
 var TeeClient = class {
   constructor(teeUrl) {
     this.teeUrl = teeUrl;
@@ -2081,16 +2172,90 @@ var TeeClient = class {
     if (!res.ok) throw new Error("session open failed");
     this.handle = (await res.json()).handle;
   }
-  /** Verify a candidate device share (from a recovery phrase) without exposing shares. */
-  async verifyRecoveryCandidate(deviceShare, jwt) {
+  /**
+   * Flow B: exchange a recovery share (from a recovery-share file) for a
+   * fresh device share. The server verifies the reconstructed master
+   * actually matches this account's addresses before returning anything —
+   * see the security note in the TEE's /signer/recover handler. Rotates the
+   * whole share set: the caller MUST persist the returned recoveryShare as a
+   * new recovery-share file, since the old one stops working immediately.
+   */
+  async recoverWithShare(jwt, recoveryShare) {
     await this.ensureAttested();
-    const res = await fetch(`${this.teeUrl}/signer/verify-recovery`, {
+    const res = await fetch(`${this.teeUrl}/signer/recover`, {
       method: "POST",
       headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" },
-      body: JSON.stringify({ deviceShare: bytesToBase64(deviceShare) })
+      body: JSON.stringify({ recoveryShare: bytesToBase64(recoveryShare) })
     });
-    if (!res.ok) return false;
-    return (await res.json()).verified === true;
+    if (res.status === 403) {
+      const { RecoveryWalletMismatchError: RecoveryWalletMismatchError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+      throw new RecoveryWalletMismatchError2();
+    }
+    if (!res.ok) throw new Error("recovery failed");
+    const body = await res.json();
+    return {
+      deviceShare: base64ToBytes(body.deviceShare),
+      recoveryShare: base64ToBytes(body.recoveryShare),
+      shareSetVersion: body.shareSetVersion
+    };
+  }
+  /**
+   * Request a fresh WebAuthn assertion challenge and complete it in the
+   * browser via @simplewebauthn/browser's startAuthentication(), which
+   * handles all the base64url (de)serialization the raw navigator.credentials
+   * API requires. Shared by rotateShares() and exportPortableBackup() — both
+   * require proof of fresh authenticator possession, not just an active session.
+   */
+  async completeAssertion(jwt) {
+    const res = await fetch(`${this.teeUrl}/signer/assertion-challenge`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ rpId: window.location.hostname })
+    });
+    if (!res.ok) throw new ExportNotAuthorizedError();
+    const { challengeId, options } = await res.json();
+    let assertion;
+    try {
+      assertion = await startAuthentication({ optionsJSON: options });
+    } catch {
+      const { UserCancelledError: UserCancelledError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+      throw new UserCancelledError2();
+    }
+    return { challengeId, assertion };
+  }
+  /** Voluntary rotation — e.g. after a suspected device compromise, or to invalidate an old recovery file. */
+  async rotateShares(jwt) {
+    if (!this.handle) throw new Error("no session");
+    const { challengeId, assertion } = await this.completeAssertion(jwt);
+    const res = await fetch(`${this.teeUrl}/signer/rotate`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ handle: this.handle, challengeId, assertion, origin: window.location.origin })
+    });
+    if (!res.ok) throw new ExportNotAuthorizedError();
+    const body = await res.json();
+    return {
+      deviceShare: base64ToBytes(body.deviceShare),
+      recoveryShare: base64ToBytes(body.recoveryShare),
+      shareSetVersion: body.shareSetVersion
+    };
+  }
+  /** The two-share bearer portable backup — see recovery/portableBackup.ts. Rotates the set on export. */
+  async exportPortableBackup(jwt) {
+    if (!this.handle) throw new Error("no session");
+    const { challengeId, assertion } = await this.completeAssertion(jwt);
+    const res = await fetch(`${this.teeUrl}/signer/export-portable`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ handle: this.handle, challengeId, assertion, origin: window.location.origin })
+    });
+    if (!res.ok) throw new ExportNotAuthorizedError();
+    const body = await res.json();
+    return {
+      deviceShare: base64ToBytes(body.deviceShare),
+      recoveryShare: base64ToBytes(body.recoveryShare),
+      shareSetVersion: body.shareSetVersion
+    };
   }
   hasSession() {
     return this.handle !== null;
@@ -2123,6 +2288,7 @@ var TeeClient = class {
 };
 
 // src/social/session.ts
+init_errors();
 var SessionManager = class {
   constructor(events, durationMs, teeUrl) {
     this.events = events;
@@ -2178,24 +2344,27 @@ var SessionManager = class {
 };
 
 // src/social/crypto/shares.ts
-function xorBytes(a, b) {
-  if (a.length !== b.length) throw new Error("xorBytes: length mismatch");
-  const out = new Uint8Array(a.length);
-  for (let i = 0; i < a.length; i++) out[i] = a[i] ^ b[i];
-  return out;
-}
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { split, combine } from "shamir-secret-sharing";
 function generateRandomBytes(n) {
   return crypto.getRandomValues(new Uint8Array(n));
 }
-function generateWalletShares() {
-  const privateKey = generateRandomBytes(32);
-  const deviceShare = generateRandomBytes(32);
-  const serverShare = xorBytes(privateKey, deviceShare);
-  return { privateKey, deviceShare, serverShare };
-}
 function zeroize(bytes) {
   bytes.fill(0);
 }
+function generateMaster() {
+  let master;
+  do {
+    master = generateRandomBytes(32);
+  } while (!secp256k1.utils.isValidPrivateKey(master));
+  return master;
+}
+async function splitMaster(master, version = 1) {
+  if (master.length !== 32) throw new Error("master must be 32 bytes");
+  const parts = await split(master, 3, 2);
+  if (parts.length !== 3) throw new Error("unexpected share count");
+  return { device: parts[0], server: parts[1], recovery: parts[2], version };
+}
 
 // src/social/crypto/wrap.ts
 function buf(u) {
@@ -2240,6 +2409,8 @@ function validatePin(pin) {
 }
 
 // src/social/crypto/passkey.ts
+init_errors();
+import { startRegistration } from "@simplewebauthn/browser";
 function buf3(u) {
   return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
 }
@@ -2247,30 +2418,24 @@ function isPasskeySupported() {
   return typeof window !== "undefined" && !!window.PublicKeyCredential && "isUserVerifyingPlatformAuthenticatorAvailable" in window.PublicKeyCredential;
 }
 async function registerPasskey(opts) {
-  const challenge = crypto.getRandomValues(new Uint8Array(32));
-  let cred;
+  let response;
   try {
-    cred = await navigator.credentials.create({
-      publicKey: {
-        challenge: buf3(challenge),
-        rp: { id: opts.rpId, name: opts.rpName },
-        user: { id: buf3(opts.userId), name: opts.userName, displayName: opts.userName },
-        pubKeyCredParams: [
-          { type: "public-key", alg: -7 },
-          { type: "public-key", alg: -257 }
-        ],
-        authenticatorSelection: { userVerification: "required", residentKey: "preferred" },
-        extensions: { prf: { eval: { first: buf3(opts.prfSalt) } } }
-      }
-    });
+    response = await startRegistration({ optionsJSON: opts.optionsJSON });
   } catch (e) {
     if (e.name === "NotAllowedError") throw new UserCancelledError();
     throw e;
   }
-  const ext = cred.getClientExtensionResults();
-  const prfResults = ext?.prf?.results;
-  const prfOutput = prfResults?.first ? new Uint8Array(prfResults.first) : void 0;
-  return { credentialId: new Uint8Array(cred.rawId), prfOutput };
+  const extResults = response.clientExtensionResults;
+  const prfResults = extResults?.prf?.results;
+  let prfOutput;
+  if (prfResults?.first) {
+    prfOutput = typeof prfResults.first === "string" ? Uint8Array.from(atob(prfResults.first.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0)) : new Uint8Array(prfResults.first);
+  }
+  const credentialId = Uint8Array.from(
+    atob(response.id.replace(/-/g, "+").replace(/_/g, "/")),
+    (c) => c.charCodeAt(0)
+  );
+  return { credentialId, prfOutput, response };
 }
 async function getPrfOutput(opts) {
   const challenge = crypto.getRandomValues(new Uint8Array(32));
@@ -2295,6 +2460,28 @@ async function getPrfOutput(opts) {
   return new Uint8Array(prfResults.first);
 }
 
+// src/social/webauthnRegistration.ts
+function bufFromBytes(u) {
+  return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+}
+async function registerWebAuthnCredential(opts) {
+  const baseOptions = await opts.api.getWebAuthnRegisterOptions(opts.jwt, opts.rpId, opts.rpName);
+  const optionsJSON = {
+    ...baseOptions,
+    extensions: {
+      ...baseOptions.extensions,
+      prf: { eval: { first: bufFromBytes(opts.prfSalt) } }
+    }
+  };
+  const { credentialId, prfOutput, response } = await registerPasskey({ optionsJSON });
+  try {
+    await opts.api.postWebAuthnRegister(opts.jwt, response, window.location.origin);
+  } catch (e) {
+    console.warn("decane-connect-kit: WebAuthn server-side registration failed; PRF-based unlock still works, but rotateShares()/exportPortableBackup() will not until this is retried.", e);
+  }
+  return { credentialId, prfOutput };
+}
+
 // src/social/auth/email.ts
 async function startEmailAuth(api, email) {
   await api.authEmailStart(email);
@@ -2341,28 +2528,102 @@ async function fetchWrappedShareBackup(api, jwt) {
   return api.getRecoveryBackup(jwt);
 }
 
-// src/social/recovery/phrase.ts
-import { entropyToMnemonic, mnemonicToEntropy, validateMnemonic } from "@scure/bip39";
-import { wordlist } from "@scure/bip39/wordlists/english.js";
-function shareToPhrase(deviceShare) {
-  if (deviceShare.length !== 32) throw new Error("deviceShare must be 32 bytes");
-  return entropyToMnemonic(deviceShare, wordlist);
+// src/social/recovery/recoveryShareFile.ts
+init_errors();
+var PBKDF2_ITERATIONS2 = 6e5;
+var FILE_VERSION = 2;
+function b642(u) {
+  let s = "";
+  for (const b of u) s += String.fromCharCode(b);
+  return btoa(s);
+}
+function unb642(s) {
+  return Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+}
+function buf4(u) {
+  return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+}
+async function deriveFileKey(password, salt, iterations) {
+  const base = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(password),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt: buf4(salt), iterations, hash: "SHA-256" },
+    base,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function buildRecoveryShareFile(share, password, addresses, shareSetVersion, passwordHint) {
+  if (share.length !== 33) throw new Error("share must be 33 bytes");
+  if (password.length < 8) throw new Error("password must be at least 8 characters");
+  if (passwordHint && passwordHint.trim() === password) {
+    throw new Error("password hint must not be the password");
+  }
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await deriveFileKey(password, salt, PBKDF2_ITERATIONS2);
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt({ name: "AES-GCM", iv: buf4(iv) }, key, buf4(share))
+  );
+  return {
+    version: FILE_VERSION,
+    type: "decane-recovery-share",
+    shareSetVersion,
+    kdf: "pbkdf2-sha256",
+    kdfParams: { iterations: PBKDF2_ITERATIONS2, salt: b642(salt) },
+    cipher: "aes-256-gcm",
+    iv: b642(iv),
+    ciphertext: b642(ct),
+    addresses,
+    passwordHint: passwordHint?.trim() || null,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function parseRecoveryShareFile(json) {
+  const raw = json;
+  if (raw?.type === "decane-recovery") {
+    throw new InvalidRecoveryFileError();
+  }
+  const f = json;
+  if (!f || f.type !== "decane-recovery-share" || f.version !== FILE_VERSION || f.kdf !== "pbkdf2-sha256" || f.cipher !== "aes-256-gcm" || typeof f.iv !== "string" || typeof f.ciphertext !== "string" || typeof f.kdfParams?.salt !== "string" || typeof f.kdfParams?.iterations !== "number" || typeof f.shareSetVersion !== "number" || typeof f.addresses?.evm !== "string" || typeof f.addresses?.solana !== "string") {
+    throw new InvalidRecoveryFileError();
+  }
+  if (f.kdfParams.iterations < 1e5 || f.kdfParams.iterations > 5e6) {
+    throw new InvalidRecoveryFileError();
+  }
+  return f;
 }
-function phraseToShare(phrase) {
-  const normalized = phrase.trim().toLowerCase().split(/\s+/).join(" ");
-  if (!validateMnemonic(normalized, wordlist)) throw new InvalidPhraseError();
-  const entropy = mnemonicToEntropy(normalized, wordlist);
-  if (entropy.length !== 32) throw new InvalidPhraseError();
-  return entropy;
+async function decryptRecoveryShareFile(file, password) {
+  const salt = unb642(file.kdfParams.salt);
+  const iv = unb642(file.iv);
+  const ct = unb642(file.ciphertext);
+  const key = await deriveFileKey(password, salt, file.kdfParams.iterations);
+  let share;
+  try {
+    share = new Uint8Array(
+      await crypto.subtle.decrypt({ name: "AES-GCM", iv: buf4(iv) }, key, buf4(ct))
+    );
+  } catch {
+    throw new WrongPasswordError();
+  }
+  if (share.length !== 33) {
+    share.fill(0);
+    throw new InvalidRecoveryFileError();
+  }
+  return share;
 }
-function phraseConfirmationChallenge(phrase) {
-  const words = phrase.trim().split(/\s+/);
-  const chosen = /* @__PURE__ */ new Set();
-  while (chosen.size < 3) chosen.add(Math.floor(Math.random() * words.length));
-  return [...chosen].sort((a, b) => a - b).map((i) => ({ position: i + 1, expected: words[i] }));
+function recoveryShareFileName(evmAddress) {
+  return `decane-recovery-${evmAddress.slice(0, 8)}.json`;
 }
 
 // src/social/recovery/recoveryFlow.ts
+init_errors();
 async function recoverDeviceShare(input) {
   const backup = await fetchWrappedShareBackup(input.api, input.jwt);
   if (backup) {
@@ -2396,37 +2657,87 @@ async function recoverDeviceShare(input) {
       });
     }
   }
-  if (!input.promptForPhrase) throw new NewDeviceError();
-  input.onProgress?.({ type: "phrase-prompt" });
-  const phrase = await input.promptForPhrase();
-  if (!phrase) throw new NewDeviceError();
-  let candidate;
-  try {
-    candidate = phraseToShare(phrase);
-  } catch {
-    throw new InvalidPhraseError();
-  }
-  input.onProgress?.({ type: "phrase-verifying" });
+  if (!input.promptForRecoveryFile) throw new NewDeviceError();
+  input.onProgress?.({ type: "recovery-file-prompt" });
+  const supplied = await input.promptForRecoveryFile();
+  if (!supplied) throw new NewDeviceError();
+  const file = parseRecoveryShareFile(supplied.value);
+  input.onProgress?.({ type: "password-prompt", passwordHint: file.passwordHint });
+  const password = await supplied.getPassword();
+  if (!password) throw new NewDeviceError();
+  const recoveryShare = await decryptRecoveryShareFile(file, password);
+  input.onProgress?.({ type: "recovery-verifying" });
   const tee = new TeeClient(input.teeUrl);
-  const verified = await tee.verifyRecoveryCandidate(candidate, input.jwt);
-  if (!verified) {
-    zeroize(candidate);
-    throw new RecoveryFailedError("phrase-mismatch");
+  let result;
+  try {
+    result = await tee.recoverWithShare(input.jwt, recoveryShare);
+  } finally {
+    zeroize(recoveryShare);
   }
-  return candidate;
+  input.onProgress?.({ type: "rotated", shareSetVersion: result.shareSetVersion });
+  await input.onNewRecoveryShare?.(result.recoveryShare, result.shareSetVersion);
+  zeroize(result.recoveryShare);
+  return result.deviceShare;
 }
 
-// src/social/recovery/phraseUi.ts
-function buildPhraseResult(deviceShare) {
-  const phrase = shareToPhrase(deviceShare);
-  return { phrase, challenge: phraseConfirmationChallenge(phrase) };
+// src/social/recovery/portableBackup.ts
+init_errors();
+var PBKDF2_ITERATIONS3 = 6e5;
+var FILE_VERSION2 = 1;
+function b643(u) {
+  let s = "";
+  for (const b of u) s += String.fromCharCode(b);
+  return btoa(s);
 }
-function verifyConfirmationChallenge(challenge, userAnswers) {
-  if (userAnswers.length !== challenge.length) return false;
-  return challenge.every(({ position, expected }) => {
-    const answer = userAnswers.find((a) => a.position === position);
-    return !!answer && answer.word.trim().toLowerCase() === expected.toLowerCase();
-  });
+function buf5(u) {
+  return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+}
+async function deriveFileKey2(password, salt, iterations) {
+  const base = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(password),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt: buf5(salt), iterations, hash: "SHA-256" },
+    base,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function buildPortableBackup(deviceShare, recoveryShare, password, addresses, shareSetVersion, passwordHint) {
+  if (deviceShare.length !== 33 || recoveryShare.length !== 33) {
+    throw new Error("shares must be 33 bytes");
+  }
+  if (password.length < 8) throw new Error("password must be at least 8 characters");
+  if (passwordHint && passwordHint.trim() === password) {
+    throw new Error("password hint must not be the password");
+  }
+  const plaintext = new TextEncoder().encode(
+    JSON.stringify({ deviceShare: b643(deviceShare), recoveryShare: b643(recoveryShare) })
+  );
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await deriveFileKey2(password, salt, PBKDF2_ITERATIONS3);
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt({ name: "AES-GCM", iv: buf5(iv) }, key, buf5(plaintext))
+  );
+  return {
+    version: FILE_VERSION2,
+    type: "decane-portable-backup",
+    shareSetVersion,
+    kdf: "pbkdf2-sha256",
+    kdfParams: { iterations: PBKDF2_ITERATIONS3, salt: b643(salt) },
+    cipher: "aes-256-gcm",
+    iv: b643(iv),
+    ciphertext: b643(ct),
+    addresses,
+    passwordHint: passwordHint?.trim() || null,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
 }
 
 // src/social/client.ts
@@ -2517,15 +2828,7 @@ async function createDecaneConnect(config) {
     let credentialId;
     let prfOutput;
     try {
-      const authType = config.authMethods[0] ?? "social";
-      const dateStr = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-      const result = await registerPasskey({
-        rpId,
-        rpName,
-        userId: new TextEncoder().encode(userId),
-        userName: `decane-wallet-${authType}-${dateStr}`,
-        prfSalt
-      });
+      const result = await registerWebAuthnCredential({ api, jwt, rpId, rpName, prfSalt });
       credentialId = result.credentialId;
       prfOutput = result.prfOutput;
     } catch (e) {
@@ -2564,15 +2867,7 @@ async function createDecaneConnect(config) {
     if (isPasskeySupported()) {
       const prfSalt = generateRandomBytes(32);
       try {
-        const authType = config.authMethods[0] ?? "social";
-        const dateStr = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-        const { credentialId, prfOutput } = await registerPasskey({
-          rpId,
-          rpName,
-          userId: new TextEncoder().encode(userId),
-          userName: `decane-wallet-${authType}-${dateStr}`,
-          prfSalt
-        });
+        const { credentialId, prfOutput } = await registerWebAuthnCredential({ api, jwt, rpId, rpName, prfSalt });
         if (prfOutput) {
           unlockMethod = "passkey";
           wrappingKey = await importAesKey(prfOutput);
@@ -2595,19 +2890,21 @@ async function createDecaneConnect(config) {
       ({ wrappingKey, meta } = await pinSetup());
       unlockMethod = "pin";
     }
-    const { privateKey, deviceShare, serverShare } = generateWalletShares();
+    const master = generateMaster();
+    let shareSet;
     let evmAddress;
     let solanaAddress;
     try {
-      evmAddress = new Wallet(toHex(privateKey)).address;
-      solanaAddress = Keypair.fromSeed(privateKey).publicKey.toBase58();
+      evmAddress = new Wallet(toHex(master)).address;
+      solanaAddress = Keypair.fromSeed(master).publicKey.toBase58();
+      shareSet = await splitMaster(master, 1);
     } finally {
-      zeroize(privateKey);
+      zeroize(master);
     }
     const iv = generateRandomBytes(12);
     const wrappedDeviceShare = await aesGcmEncrypt(
       wrappingKey,
-      deviceShare,
+      shareSet.device,
       iv
     );
     await storage.putShare({
@@ -2623,7 +2920,7 @@ async function createDecaneConnect(config) {
     });
     const serverIv = generateRandomBytes(12);
     await api.putShare(jwt, {
-      ciphertext: serverShare,
+      ciphertext: shareSet.server,
       iv: serverIv,
       wrappedShareMeta: {
         unlockMethod
@@ -2632,7 +2929,7 @@ async function createDecaneConnect(config) {
       evmAddress,
       solanaAddress
     });
-    zeroize(serverShare);
+    zeroize(shareSet.server);
     const addresses = { evm: evmAddress, solana: solanaAddress };
     if (unlockMethod === "passkey" && meta.credentialId && meta.prfSalt) {
       try {
@@ -2647,19 +2944,27 @@ async function createDecaneConnect(config) {
         console.warn("decane-connect-kit: wrapped share backup failed; user can retry from settings.", e);
       }
     }
-    await session.start(deviceShare, jwt, addresses);
-    if (config.offerPhraseAtSignup !== false && config.onPhraseGenerated) {
+    await session.start(shareSet.device, jwt, addresses);
+    zeroize(shareSet.device);
+    if (config.offerRecoveryAtSignup !== false && config.onRecoveryShareOffer) {
       try {
-        const result = buildPhraseResult(deviceShare);
-        const { userConfirmed, userAnswers } = await config.onPhraseGenerated(result);
-        if (userConfirmed && verifyConfirmationChallenge(result.challenge, userAnswers)) {
-          await api.markPhraseSaved(jwt);
+        const choice = await config.onRecoveryShareOffer({ evmAddress, solanaAddress });
+        if (choice.wants) {
+          const file = await buildRecoveryShareFile(
+            shareSet.recovery,
+            choice.password,
+            addresses,
+            shareSet.version,
+            choice.passwordHint
+          );
+          await config.onRecoveryFileReady?.(file, recoveryShareFileName(evmAddress));
+          await api.markRecoveryShareSaved(jwt);
         }
       } catch (e) {
-        console.warn("decane-connect-kit: recovery phrase offer failed or was skipped.", e);
+        console.warn("decane-connect-kit: recovery share offer failed or was skipped.", e);
       }
     }
-    zeroize(deviceShare);
+    zeroize(shareSet.recovery);
     return addresses;
   }
   async function returningUserUnlock(userId, jwt) {
@@ -2681,7 +2986,17 @@ async function createDecaneConnect(config) {
         api,
         storage,
         onProgress: config.onRecoveryProgress,
-        promptForPhrase: config.promptForRecoveryPhrase
+        promptForRecoveryFile: config.promptForRecoveryFile,
+        onNewRecoveryShare: async (recoveryShare, shareSetVersion) => {
+          if (!config.onRecoveryRotated) {
+            console.warn("decane-connect-kit: share set rotated after recovery, but no onRecoveryRotated callback is configured \u2014 the user has no way to save a new recovery-share file.");
+            return;
+          }
+          const { password, passwordHint } = await config.onRecoveryRotated({ evmAddress: addresses.evm, solanaAddress: addresses.solana });
+          const file = await buildRecoveryShareFile(recoveryShare, password, addresses, shareSetVersion, passwordHint);
+          await config.onRecoveryFileReady?.(file, recoveryShareFileName(addresses.evm));
+          await api.markRecoveryShareSaved(jwt);
+        }
       });
       if (!await storage.getShare(userId) && isPasskeySupported()) {
         await registerPasskeyAndBackup(userId, jwt, deviceShare);
@@ -2856,23 +3171,82 @@ async function createDecaneConnect(config) {
     getAddresses() {
       return auth?.addresses ?? persisted?.addresses ?? null;
     },
-    async generateRecoveryPhrase() {
+    async rotateShares(opts) {
       if (!auth) throw new CallSequenceError("Not connected \u2014 call connect() first");
-      const stored = await storage.getShare(auth.userId);
-      if (!stored) throw new NewDeviceError();
-      const wrappingKey = await getWrappingKey(stored);
-      const deviceShare = await aesGcmDecrypt(wrappingKey, stored.wrappedDeviceShare, stored.iv);
+      const tee = session.requireActive();
+      const result = await tee.rotateShares(auth.jwt);
+      try {
+        const file = await buildRecoveryShareFile(
+          result.recoveryShare,
+          opts.password,
+          auth.addresses,
+          result.shareSetVersion,
+          opts.passwordHint
+        );
+        await api.markRecoveryShareSaved(auth.jwt);
+        return file;
+      } finally {
+        zeroize(result.deviceShare);
+        zeroize(result.recoveryShare);
+      }
+    },
+    async exportPortableBackup(opts) {
+      if (!auth) throw new CallSequenceError("Not connected \u2014 call connect() first");
+      const tee = session.requireActive();
+      const result = await tee.exportPortableBackup(auth.jwt);
       try {
-        return buildPhraseResult(deviceShare);
+        return await buildPortableBackup(
+          result.deviceShare,
+          result.recoveryShare,
+          opts.password,
+          auth.addresses,
+          result.shareSetVersion,
+          opts.passwordHint
+        );
       } finally {
-        zeroize(deviceShare);
+        zeroize(result.deviceShare);
+        zeroize(result.recoveryShare);
       }
     },
-    async markPhraseSaved(challenge, userAnswers) {
+    async hasRecoveryShare() {
       if (!auth) throw new CallSequenceError("Not connected \u2014 call connect() first");
-      if (!verifyConfirmationChallenge(challenge, userAnswers)) return false;
-      await api.markPhraseSaved(auth.jwt);
-      return true;
+      const status = await api.getRecoveryStatus(auth.jwt);
+      return status.hasRecoveryShare;
+    },
+    async shouldPromptRecovery() {
+      if (!auth) throw new CallSequenceError("Not connected \u2014 call connect() first");
+      const status = await api.getRecoveryStatus(auth.jwt);
+      if (status.hasRecoveryShare || status.nagged) return false;
+      try {
+        const checks = [];
+        if (auth.addresses.evm) {
+          const { JsonRpcProvider } = await import("ethers");
+          for (const chain of config.chains.filter((c) => c.startsWith("evm:"))) {
+            const rpcUrl = config.rpcUrls?.[chain] ?? DEFAULT_RPCS[chain];
+            if (!rpcUrl) continue;
+            checks.push(
+              new JsonRpcProvider(rpcUrl).getBalance(auth.addresses.evm).then((b) => b > 0n).catch(() => false)
+            );
+          }
+        }
+        if (auth.addresses.solana && config.chains.some((c) => c.startsWith("solana:"))) {
+          const { Connection, PublicKey } = await import("@solana/web3.js");
+          const solChain = config.chains.find((c) => c.startsWith("solana:")) ?? "solana:mainnet";
+          const cluster = solChain.slice("solana:".length);
+          const endpoint = cluster === "devnet" ? "https://api.devnet.solana.com" : "https://api.mainnet-beta.solana.com";
+          checks.push(
+            new Connection(endpoint).getBalance(new PublicKey(auth.addresses.solana)).then((b) => b > 0).catch(() => false)
+          );
+        }
+        const results = await Promise.all(checks);
+        return results.some(Boolean);
+      } catch {
+        return false;
+      }
+    },
+    async dismissRecoveryPrompt() {
+      if (!auth) throw new CallSequenceError("Not connected \u2014 call connect() first");
+      await api.dismissRecoveryNag(auth.jwt);
     },
     async hasBackup() {
       if (!auth) throw new CallSequenceError("Not connected \u2014 call connect() first");
@@ -2887,17 +3261,20 @@ async function createDecaneConnect(config) {
   };
   return client;
 }
-function bufferToB64u(buf4) {
-  return btoa(String.fromCharCode(...buf4)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+function bufferToB64u(buf6) {
+  return btoa(String.fromCharCode(...buf6)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
 function b64uToBuffer(b64u) {
-  const b642 = b64u.replace(/-/g, "+").replace(/_/g, "/");
-  return Uint8Array.from(atob(b642), (c) => c.charCodeAt(0));
+  const b644 = b64u.replace(/-/g, "+").replace(/_/g, "/");
+  return Uint8Array.from(atob(b644), (c) => c.charCodeAt(0));
 }
 function toHex(bytes) {
   return "0x" + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/social/index.ts
+init_errors();
+
 // src/ui/WalletSelector.tsx
 import React2, { useEffect, useCallback, useState } from "react";
 import { createPortal } from "react-dom";
@@ -4676,14 +5053,16 @@ export {
   DecaneError,
   DecaneErrorCode,
   DecaneKit,
+  ExportNotAuthorizedError,
   InvalidApiKeyError,
-  InvalidPhraseError,
   InvalidPinError,
+  InvalidRecoveryFileError,
   NetworkError,
   NewDeviceError,
   OriginNotAllowedError,
   PromptPinNotConfiguredError,
   RecoveryFailedError,
+  RecoveryWalletMismatchError,
   SessionExpiredError,
   ShareCorruptedError,
   SocialWalletModal,
@@ -4691,6 +5070,7 @@ export {
   UserCancelledError,
   WalletSelector,
   WebAuthnNotSupportedError,
+  WrongPasswordError,
   createDecane,
   createDecaneConnect,
   startEmailAuth,