decane-connect-kit 2.21.0 → 2.23.0

package/dist/index.d.cts

@@ -146,6 +146,19 @@ interface DecaneConnectConfig {
      * page load (stricter, but the reload friction that motivated this returns).
      */
     persistSession?: boolean;
+    /**
+     * Do not wrap and store this device's share at wallet creation or when a
+     * device is first provisioned — so sign-in asks for no passkey and no
+     * password. The session works without a stored share: signing runs on the
+     * open session, and a later visit provisions a fresh share against a live
+     * sign-in. What the device loses until it is protected is the short way
+     * back in (passkey / password unlock) — every visit is a full sign-in.
+     *
+     * Call `protectDevice()` at the moment the app wants that step, typically
+     * before the user's first transaction. `deviceProtected()` says whether it
+     * has happened. Default false: the share is wrapped and stored at creation.
+     */
+    deferDeviceProtection?: boolean;
     /**
      * Offer to save a recovery-share file at signup. **Default false** since
      * 2.7.4 — opt in explicitly with `true`.
@@ -398,6 +411,14 @@ interface DecaneConnect {
     setUnlockPassword(password: string): Promise<void>;
     /** True when this device can open a session from a password alone. */
     canUnlockWithPassword(): Promise<boolean>;
+    /**
+     * "Use a different account." disconnect() keeps one fact about the account
+     * that signed out — its userId — so canSignInWithPasskey() and
+     * canUnlockWithPassword() can offer that account's own way back in even
+     * when several accounts are enrolled on this browser. This drops it. The
+     * device shares themselves are untouched.
+     */
+    forgetLastUser(): void;
     /** Open a session from the password alone — no provider, no passkey. */
     unlockWithPassword(password: string): Promise<ConnectResult>;
     /** Turn the password path off, revoking the token account-wide. */
@@ -420,6 +441,21 @@ interface DecaneConnect {
      * on the way).
      */
     addPasskey(): Promise<void>;
+    /**
+     * Whether this device holds a wrapped share for the signed-in account, i.e.
+     * whether a passkey or password protects the wallet here. False on a device
+     * created with `deferDeviceProtection`, or whose share was never written.
+     */
+    deviceProtected(): Promise<boolean>;
+    /**
+     * Wrap and store this device's share now: a passkey where the device can
+     * hold one, otherwise the unlock password (`promptUnlockPassword`). Needs a
+     * live session; provisions a fresh share from the enclave when the device
+     * has none. Idempotent — a protected device returns true at once. Resolves
+     * false when the user dismissed the prompt, so the app can decide whether
+     * to go on without protection; throws for anything else.
+     */
+    protectDevice(): Promise<boolean>;
     sessionExpiresAt(): number | null;
     signMessage(req: SignMessageRequest): Promise<string>;
     sendTransaction(req: SendTransactionRequest): Promise<string>;
@@ -525,7 +561,7 @@ interface DecaneConnect {
     off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
 }
 interface WrappedShareMeta {
-    unlockMethod: 'passkey' | 'pin' | 'password';
+    unlockMethod: 'passkey' | 'pin' | 'password' | 'deferred';
     credentialId?: string;
     prfSalt?: string;
     pinSalt?: string;
@@ -839,6 +875,13 @@ interface SocialConfig {
      * a silent multi-second pause reads as a broken page.
      */
     showStatusOverlay?: boolean;
+    /**
+     * Ask for no passkey or password at sign-in; protect the wallet on this
+     * device later, when the app calls `protectDevice()` (typically before the
+     * first transaction). Mirrors the headless client's option of the same name;
+     * see it for what a device gives up until then. Default false.
+     */
+    deferDeviceProtection?: boolean;
     /**
      * Offer to save a recovery-share file at signup. **Default false** since
      * 2.7.4 — opt in explicitly with `true`.
@@ -1440,10 +1483,13 @@ declare function useSocialWallet(): {
     getAccessToken: () => string | null;
     hasPasskey: () => Promise<boolean>;
     addPasskey: () => Promise<void>;
+    deviceProtected: () => Promise<boolean>;
+    protectDevice: () => Promise<boolean>;
     setUnlockPassword: (password: string) => Promise<void>;
     canUnlockWithPassword: () => Promise<boolean>;
     unlockWithPassword: (password: string) => Promise<void>;
     removeUnlockPassword: () => Promise<void>;
+    forgetLastUser: () => void;
     rotateShares: (opts: {
         password: string;
         passwordHint?: string;

package/dist/index.d.ts

@@ -146,6 +146,19 @@ interface DecaneConnectConfig {
      * page load (stricter, but the reload friction that motivated this returns).
      */
     persistSession?: boolean;
+    /**
+     * Do not wrap and store this device's share at wallet creation or when a
+     * device is first provisioned — so sign-in asks for no passkey and no
+     * password. The session works without a stored share: signing runs on the
+     * open session, and a later visit provisions a fresh share against a live
+     * sign-in. What the device loses until it is protected is the short way
+     * back in (passkey / password unlock) — every visit is a full sign-in.
+     *
+     * Call `protectDevice()` at the moment the app wants that step, typically
+     * before the user's first transaction. `deviceProtected()` says whether it
+     * has happened. Default false: the share is wrapped and stored at creation.
+     */
+    deferDeviceProtection?: boolean;
     /**
      * Offer to save a recovery-share file at signup. **Default false** since
      * 2.7.4 — opt in explicitly with `true`.
@@ -398,6 +411,14 @@ interface DecaneConnect {
     setUnlockPassword(password: string): Promise<void>;
     /** True when this device can open a session from a password alone. */
     canUnlockWithPassword(): Promise<boolean>;
+    /**
+     * "Use a different account." disconnect() keeps one fact about the account
+     * that signed out — its userId — so canSignInWithPasskey() and
+     * canUnlockWithPassword() can offer that account's own way back in even
+     * when several accounts are enrolled on this browser. This drops it. The
+     * device shares themselves are untouched.
+     */
+    forgetLastUser(): void;
     /** Open a session from the password alone — no provider, no passkey. */
     unlockWithPassword(password: string): Promise<ConnectResult>;
     /** Turn the password path off, revoking the token account-wide. */
@@ -420,6 +441,21 @@ interface DecaneConnect {
      * on the way).
      */
     addPasskey(): Promise<void>;
+    /**
+     * Whether this device holds a wrapped share for the signed-in account, i.e.
+     * whether a passkey or password protects the wallet here. False on a device
+     * created with `deferDeviceProtection`, or whose share was never written.
+     */
+    deviceProtected(): Promise<boolean>;
+    /**
+     * Wrap and store this device's share now: a passkey where the device can
+     * hold one, otherwise the unlock password (`promptUnlockPassword`). Needs a
+     * live session; provisions a fresh share from the enclave when the device
+     * has none. Idempotent — a protected device returns true at once. Resolves
+     * false when the user dismissed the prompt, so the app can decide whether
+     * to go on without protection; throws for anything else.
+     */
+    protectDevice(): Promise<boolean>;
     sessionExpiresAt(): number | null;
     signMessage(req: SignMessageRequest): Promise<string>;
     sendTransaction(req: SendTransactionRequest): Promise<string>;
@@ -525,7 +561,7 @@ interface DecaneConnect {
     off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
 }
 interface WrappedShareMeta {
-    unlockMethod: 'passkey' | 'pin' | 'password';
+    unlockMethod: 'passkey' | 'pin' | 'password' | 'deferred';
     credentialId?: string;
     prfSalt?: string;
     pinSalt?: string;
@@ -839,6 +875,13 @@ interface SocialConfig {
      * a silent multi-second pause reads as a broken page.
      */
     showStatusOverlay?: boolean;
+    /**
+     * Ask for no passkey or password at sign-in; protect the wallet on this
+     * device later, when the app calls `protectDevice()` (typically before the
+     * first transaction). Mirrors the headless client's option of the same name;
+     * see it for what a device gives up until then. Default false.
+     */
+    deferDeviceProtection?: boolean;
     /**
      * Offer to save a recovery-share file at signup. **Default false** since
      * 2.7.4 — opt in explicitly with `true`.
@@ -1440,10 +1483,13 @@ declare function useSocialWallet(): {
     getAccessToken: () => string | null;
     hasPasskey: () => Promise<boolean>;
     addPasskey: () => Promise<void>;
+    deviceProtected: () => Promise<boolean>;
+    protectDevice: () => Promise<boolean>;
     setUnlockPassword: (password: string) => Promise<void>;
     canUnlockWithPassword: () => Promise<boolean>;
     unlockWithPassword: (password: string) => Promise<void>;
     removeUnlockPassword: () => Promise<void>;
+    forgetLastUser: () => void;
     rotateShares: (opts: {
         password: string;
         passwordHint?: string;

package/dist/index.js

@@ -3607,6 +3607,29 @@ function clearPersisted(key) {
   } catch {
   }
 }
+function makeLastUserKey(apiKey) {
+  return `${makePersistKey(apiKey)}:last-user`;
+}
+function loadLastUser(key) {
+  try {
+    const raw = typeof localStorage !== "undefined" ? localStorage.getItem(key) : null;
+    return raw ? JSON.parse(raw).userId ?? null : null;
+  } catch {
+    return null;
+  }
+}
+function saveLastUser(key, userId) {
+  try {
+    localStorage.setItem(key, JSON.stringify({ userId }));
+  } catch {
+  }
+}
+function clearLastUser(key) {
+  try {
+    localStorage.removeItem(key);
+  } catch {
+  }
+}
 function sessionPersistKey(apiKey) {
   return `decane:sess:${apiKey.slice(0, 20)}`;
 }
@@ -3645,6 +3668,7 @@ async function createDecaneConnect(config) {
   const rpId = config.rpId ?? (typeof window !== "undefined" ? window.location.hostname : "localhost");
   const rpName = config.rpName ?? "Decane Connect";
   const PERSIST_KEY = makePersistKey(config.apiKey);
+  const LAST_USER_KEY = makeLastUserKey(config.apiKey);
   const teeUrl = config.teeUrl ?? DEFAULT_TEE_URL;
   const events = new EventEmitter();
   const api = new ApiClient(baseUrl, config.apiKey, config.appId);
@@ -3657,8 +3681,10 @@ async function createDecaneConnect(config) {
   );
   let auth = null;
   let persisted = loadPersisted(PERSIST_KEY);
+  let lastUserId = loadLastUser(LAST_USER_KEY);
   let ethProvider = null;
   const persistSession = config.persistSession !== false;
+  const deferDeviceProtection = config.deferDeviceProtection === true;
   const serverAssistedRecovery = true;
   const RECOVERY_OFFER_TIMEOUT_MS = 5 * 6e4;
   const selfHealAttempted = /* @__PURE__ */ new Set();
@@ -3802,6 +3828,10 @@ async function createDecaneConnect(config) {
       const stored = await storage.getShare(persisted.userId);
       return hasPasswordUnlock(stored) ? stored : null;
     }
+    if (lastUserId) {
+      const stored = await storage.getShare(lastUserId);
+      return hasPasswordUnlock(stored) ? stored : null;
+    }
     const candidates = (await storage.listShares()).filter(hasPasswordUnlock);
     return candidates.length === 1 ? candidates[0] : null;
   }
@@ -3966,11 +3996,12 @@ async function createDecaneConnect(config) {
   }
   async function firstTimeSetup(userId, jwt) {
     prewarmAttestation(teeUrl);
-    let unlockMethod;
-    let wrappingKey;
+    let unlockMethod = "password";
+    let wrappingKey = null;
     let meta = {};
     let unlockTokenKey = null;
-    if (isPasskeySupported()) {
+    if (deferDeviceProtection) {
+    } else if (isPasskeySupported()) {
       const prfSalt = generateRandomBytes(32);
       try {
         const { credentialId, prfOutput } = await registerWebAuthnCredential({ api, jwt, rpId, rpName, prfSalt });
@@ -4011,32 +4042,37 @@ async function createDecaneConnect(config) {
     } finally {
       zeroize(master);
     }
-    const iv = generateRandomBytes(12);
-    const wrappedDeviceShare = await aesGcmEncrypt(
-      wrappingKey,
-      shareSet.device,
-      iv
-    );
-    await storage.putShare({
-      userId,
-      wrappedDeviceShare,
-      iv,
-      unlockMethod,
-      credentialId: meta.credentialId ? b64uToBuffer(meta.credentialId) : void 0,
-      prfSalt: meta.prfSalt ? b64uToBuffer(meta.prfSalt) : void 0,
-      pinSalt: meta.pinSalt ? b64uToBuffer(meta.pinSalt) : void 0,
-      pinIterations: meta.pinIterations,
-      passwordSalt: meta.passwordSalt ? b64uToBuffer(meta.passwordSalt) : void 0,
-      passwordIterations: meta.passwordIterations,
-      version: 1
-    });
-    if (unlockTokenKey) await attachUnlockToken(userId, jwt, unlockTokenKey);
+    let wrappedDeviceShare = null;
+    let iv = null;
+    if (wrappingKey) {
+      iv = generateRandomBytes(12);
+      wrappedDeviceShare = await aesGcmEncrypt(
+        wrappingKey,
+        shareSet.device,
+        iv
+      );
+      await storage.putShare({
+        userId,
+        wrappedDeviceShare,
+        iv,
+        unlockMethod,
+        credentialId: meta.credentialId ? b64uToBuffer(meta.credentialId) : void 0,
+        prfSalt: meta.prfSalt ? b64uToBuffer(meta.prfSalt) : void 0,
+        pinSalt: meta.pinSalt ? b64uToBuffer(meta.pinSalt) : void 0,
+        pinIterations: meta.pinIterations,
+        passwordSalt: meta.passwordSalt ? b64uToBuffer(meta.passwordSalt) : void 0,
+        passwordIterations: meta.passwordIterations,
+        version: 1
+      });
+      if (unlockTokenKey) await attachUnlockToken(userId, jwt, unlockTokenKey);
+    }
     const serverIv = generateRandomBytes(12);
     await withDeadline(api.putShare(jwt, {
       ciphertext: shareSet.server,
       iv: serverIv,
       wrappedShareMeta: {
-        unlockMethod
+        // The server records this on the wallet_created event and nothing else.
+        unlockMethod: deferDeviceProtection ? "deferred" : unlockMethod
         // credential IDs, prfSalt, pinSalt stay on-device — never sent to server
       },
       evmAddress,
@@ -4045,7 +4081,7 @@ async function createDecaneConnect(config) {
     }), remainingBudget(), "storing your wallet");
     zeroize(shareSet.server);
     const addresses = { evm: evmAddress, solana: solanaAddress, tron: tronAddress };
-    if (unlockMethod === "passkey" && meta.credentialId && meta.prfSalt) {
+    if (unlockMethod === "passkey" && meta.credentialId && meta.prfSalt && wrappedDeviceShare && iv) {
       try {
         await api.putRecoveryBackup(jwt, {
           wrappedDeviceShare,
@@ -4128,7 +4164,7 @@ async function createDecaneConnect(config) {
           const tee = new TeeClient(teeUrl);
           const provisioned = await tee.provisionDeviceShare(jwt);
           if (provisioned) {
-            await persistProvisionedShare(userId, jwt, provisioned);
+            if (!deferDeviceProtection) await persistProvisionedShare(userId, jwt, provisioned);
             let addrs;
             try {
               addrs = await session.start(provisioned, jwt, recordedAddresses);
@@ -4172,7 +4208,7 @@ async function createDecaneConnect(config) {
       });
       deviceShare = recovered.deviceShare;
       joinedViaPasskeySync = recovered.flow === "passkey-sync";
-      if (!await storage.getShare(userId) && isPasskeySupported()) {
+      if (!deferDeviceProtection && !await storage.getShare(userId) && isPasskeySupported()) {
         await registerPasskeyAndBackup(userId, jwt, deviceShare);
       }
     } else {
@@ -4255,14 +4291,16 @@ async function createDecaneConnect(config) {
   async function passkeyDeviceCandidate() {
     if (!isPasskeySupported()) return null;
     if (persisted?.userId) return passkeyLoginCandidate();
+    if (lastUserId) return usablePasskeyShare(await storage.getShare(lastUserId));
     const candidates = (await storage.listShares()).map(usablePasskeyShare).filter(Boolean);
     return candidates.length === 1 ? candidates[0] : null;
   }
   async function canOfferPasskey() {
     if (!isPasskeySupported()) return false;
     if (await passkeyDeviceCandidate()) return true;
-    if (!persisted?.userId) return false;
-    return await storage.getShare(persisted.userId) == null;
+    const known = persisted?.userId ?? lastUserId;
+    if (!known) return false;
+    return await storage.getShare(known) == null;
   }
   async function rememberProfile(userId, profile) {
     const incoming = Object.fromEntries(Object.entries(profile).filter(([, v]) => v));
@@ -4475,8 +4513,9 @@ async function createDecaneConnect(config) {
     async signInWithPasskey() {
       const candidate = await passkeyDeviceCandidate();
       if (candidate) return passkeyLogin(candidate);
-      if (isPasskeySupported() && persisted?.userId && await storage.getShare(persisted.userId) == null) {
-        return passkeyLoginWithoutShare(persisted.userId);
+      const known = persisted?.userId ?? lastUserId;
+      if (isPasskeySupported() && known && await storage.getShare(known) == null) {
+        return passkeyLoginWithoutShare(known);
       }
       throw new NewDeviceError();
     },
@@ -4640,6 +4679,24 @@ async function createDecaneConnect(config) {
         zeroize(deviceShare);
       }
     },
+    async deviceProtected() {
+      if (!auth) return false;
+      return await storage.getShare(auth.userId) !== null;
+    },
+    async protectDevice() {
+      if (!auth) throw new ReconnectRequiredError();
+      if (await storage.getShare(auth.userId)) return true;
+      if (!serverAssistedRecovery) throw new NewDeviceError();
+      const tee = new TeeClient(teeUrl);
+      const provisioned = await tee.provisionDeviceShare(auth.jwt);
+      if (!provisioned) throw new NewDeviceError();
+      try {
+        await persistProvisionedShare(auth.userId, auth.jwt, provisioned);
+      } finally {
+        zeroize(provisioned);
+      }
+      return await storage.getShare(auth.userId) !== null;
+    },
     async unlock() {
       if (!auth) {
         const candidate = await passkeyLoginCandidate();
@@ -4816,12 +4873,21 @@ async function createDecaneConnect(config) {
         await api.revoke(auth.jwt).catch(() => {
         });
       }
+      const leaving = auth?.userId ?? persisted?.userId ?? null;
+      if (leaving) {
+        lastUserId = leaving;
+        saveLastUser(LAST_USER_KEY, leaving);
+      }
       auth = null;
       persisted = null;
       clearPersisted(PERSIST_KEY);
       dropLiveSession();
       events.emit("disconnected");
     },
+    forgetLastUser() {
+      lastUserId = null;
+      clearLastUser(LAST_USER_KEY);
+    },
     getAddresses() {
       return auth?.addresses ?? persisted?.addresses ?? null;
     },
@@ -7260,6 +7326,7 @@ function DecaneKit({ config, children }) {
       chains,
       rpcUrls,
       requireAssertionPerSignature,
+      deferDeviceProtection,
       // Recovery callbacks. Forwarding these is what makes recovery
       // configurable at all from <DecaneKit>; before, they were silently
       // dropped and the headless client was constructed without them.
@@ -7280,6 +7347,7 @@ function DecaneKit({ config, children }) {
       promptPin,
       promptUnlockPassword,
       requireAssertionPerSignature,
+      deferDeviceProtection,
       offerRecoveryAtSignup,
       onRecoveryShareOffer,
       onRecoveryFileReady,
@@ -7526,6 +7594,16 @@ function DecaneKit({ config, children }) {
     if (!sdk) throw new Error("Social wallet not connected");
     return sdk.addPasskey();
   }, []);
+  const socialDeviceProtected = useCallback3(async () => {
+    const sdk = socialRef.current;
+    if (!sdk) return false;
+    return sdk.deviceProtected();
+  }, []);
+  const socialProtectDevice = useCallback3(async () => {
+    const sdk = socialRef.current;
+    if (!sdk) throw new Error("Social wallet not connected");
+    return sdk.protectDevice();
+  }, []);
   const socialSetUnlockPassword = useCallback3(async (password) => {
     const sdk = socialRef.current;
     if (!sdk) throw new Error("Social wallet not connected");
@@ -7536,6 +7614,14 @@ function DecaneKit({ config, children }) {
     if (!sdk) return false;
     return sdk.canUnlockWithPassword();
   }, []);
+  const socialForgetLastUser = useCallback3(() => {
+    socialRef.current?.forgetLastUser();
+    const sdk = socialRef.current;
+    if (sdk) {
+      sdk.canSignInWithPasskey().then((can) => setSocialAuth((p) => ({ ...p, canUsePasskey: can }))).catch(() => {
+      });
+    }
+  }, []);
   const socialUnlockWithPassword = useCallback3(async (password) => {
     const sdk = socialRef.current;
     if (!sdk) throw new Error("Social wallet not connected");
@@ -7610,8 +7696,11 @@ function DecaneKit({ config, children }) {
         socialHasRecoveryShare,
         socialHasPasskey,
         socialAddPasskey,
+        socialDeviceProtected,
+        socialProtectDevice,
         socialSetUnlockPassword,
         socialCanUnlockWithPassword,
+        socialForgetLastUser,
         socialUnlockWithPassword,
         socialRemoveUnlockPassword,
         socialShouldPromptRecovery,
@@ -7919,8 +8008,11 @@ function useSocialWallet() {
     socialHasRecoveryShare,
     socialHasPasskey,
     socialAddPasskey,
+    socialDeviceProtected,
+    socialProtectDevice,
     socialSetUnlockPassword,
     socialCanUnlockWithPassword,
+    socialForgetLastUser,
     socialUnlockWithPassword,
     socialRemoveUnlockPassword,
     socialShouldPromptRecovery,
@@ -8020,6 +8112,16 @@ function useSocialWallet() {
       throw e;
     }
   }, [socialAddPasskey]);
+  const deviceProtected = useCallback4(() => run(() => socialDeviceProtected()), [socialDeviceProtected]);
+  const protectDevice = useCallback4(async () => {
+    setError(null);
+    try {
+      return await socialProtectDevice();
+    } catch (e) {
+      setError(e.message);
+      throw e;
+    }
+  }, [socialProtectDevice]);
   const setUnlockPassword = useCallback4(async (password) => {
     setError(null);
     try {
@@ -8029,6 +8131,7 @@ function useSocialWallet() {
       throw e;
     }
   }, [socialSetUnlockPassword]);
+  const forgetLastUser = useCallback4(() => socialForgetLastUser(), [socialForgetLastUser]);
   const canUnlockWithPassword = useCallback4(
     () => socialCanUnlockWithPassword(),
     [socialCanUnlockWithPassword]
@@ -8107,6 +8210,10 @@ function useSocialWallet() {
     // Passkey management for THIS device
     hasPasskey,
     addPasskey,
+    // Deferred protection (deferDeviceProtection): whether this device holds
+    // a wrapped share, and the call that stores one — passkey or password.
+    deviceProtected,
+    protectDevice,
     // "Unlock with your password": setUnlockPassword needs a live session;
     // canUnlockWithPassword and unlockWithPassword are the signed-out pair that
     // open one without an identity provider or a passkey.
@@ -8114,6 +8221,8 @@ function useSocialWallet() {
     canUnlockWithPassword,
     unlockWithPassword,
     removeUnlockPassword,
+    // "Use a different account": stop offering the account that signed out.
+    forgetLastUser,
     // Recovery (2-of-3 Shamir share set)
     rotateShares,
     exportPortableBackup,