decane-connect-kit 2.22.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`.
@@ -428,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>;
@@ -533,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;
@@ -847,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`.
@@ -1448,6 +1483,8 @@ 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>;

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`.
@@ -428,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>;
@@ -533,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;
@@ -847,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`.
@@ -1448,6 +1483,8 @@ 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>;

package/dist/index.js

@@ -3684,6 +3684,7 @@ async function createDecaneConnect(config) {
   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();
@@ -3995,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 });
@@ -4040,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,
@@ -4074,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,
@@ -4157,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);
@@ -4201,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 {
@@ -4672,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();
@@ -7301,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.
@@ -7321,6 +7347,7 @@ function DecaneKit({ config, children }) {
       promptPin,
       promptUnlockPassword,
       requireAssertionPerSignature,
+      deferDeviceProtection,
       offerRecoveryAtSignup,
       onRecoveryShareOffer,
       onRecoveryFileReady,
@@ -7567,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");
@@ -7659,6 +7696,8 @@ function DecaneKit({ config, children }) {
         socialHasRecoveryShare,
         socialHasPasskey,
         socialAddPasskey,
+        socialDeviceProtected,
+        socialProtectDevice,
         socialSetUnlockPassword,
         socialCanUnlockWithPassword,
         socialForgetLastUser,
@@ -7969,6 +8008,8 @@ function useSocialWallet() {
     socialHasRecoveryShare,
     socialHasPasskey,
     socialAddPasskey,
+    socialDeviceProtected,
+    socialProtectDevice,
     socialSetUnlockPassword,
     socialCanUnlockWithPassword,
     socialForgetLastUser,
@@ -8071,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 {
@@ -8159,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.