decane-connect-kit 2.26.1 → 2.28.0

package/dist/index.js

@@ -14,6 +14,7 @@ __export(errors_exports, {
   AttestationError: () => AttestationError,
   CallSequenceError: () => CallSequenceError,
   DecaneConnectError: () => DecaneConnectError,
+  EnclaveHttpError: () => EnclaveHttpError,
   ExportNotAuthorizedError: () => ExportNotAuthorizedError,
   InvalidAccessTokenError: () => InvalidAccessTokenError,
   InvalidApiKeyError: () => InvalidApiKeyError,
@@ -24,6 +25,7 @@ __export(errors_exports, {
   OriginNotAllowedError: () => OriginNotAllowedError,
   PromptPasswordNotConfiguredError: () => PromptPasswordNotConfiguredError,
   PromptPinNotConfiguredError: () => PromptPinNotConfiguredError,
+  ProvisioningRateLimitedError: () => ProvisioningRateLimitedError,
   ProvisioningTimeoutError: () => ProvisioningTimeoutError,
   ReconnectRequiredError: () => ReconnectRequiredError,
   RecoveryFailedError: () => RecoveryFailedError,
@@ -34,11 +36,13 @@ __export(errors_exports, {
   UnlockRequiredError: () => UnlockRequiredError,
   UnlockTokenRejectedError: () => UnlockTokenRejectedError,
   UserCancelledError: () => UserCancelledError,
+  WalletEnrolmentError: () => WalletEnrolmentError,
+  WalletExistsError: () => WalletExistsError,
   WebAuthnNotSupportedError: () => WebAuthnNotSupportedError,
   WrongPasswordError: () => WrongPasswordError,
   WrongUnlockPasswordError: () => WrongUnlockPasswordError
 });
-var DecaneConnectError, InvalidApiKeyError, OriginNotAllowedError, SessionExpiredError, UnlockRequiredError, ReconnectRequiredError, UserCancelledError, WebAuthnNotSupportedError, InvalidPinError, CallSequenceError, NetworkError, ShareCorruptedError, ProvisioningTimeoutError, NewDeviceError, StaleDeviceShareError, PromptPinNotConfiguredError, PromptPasswordNotConfiguredError, WrongUnlockPasswordError, InvalidAccessTokenError, UnlockTokenRejectedError, AttestationError, RecoveryFailedError, InvalidRecoveryFileError, WrongPasswordError, RecoveryWalletMismatchError, ExportNotAuthorizedError;
+var DecaneConnectError, InvalidApiKeyError, OriginNotAllowedError, SessionExpiredError, UnlockRequiredError, ReconnectRequiredError, UserCancelledError, WebAuthnNotSupportedError, InvalidPinError, CallSequenceError, NetworkError, ShareCorruptedError, ProvisioningTimeoutError, NewDeviceError, StaleDeviceShareError, PromptPinNotConfiguredError, PromptPasswordNotConfiguredError, WrongUnlockPasswordError, InvalidAccessTokenError, UnlockTokenRejectedError, AttestationError, RecoveryFailedError, InvalidRecoveryFileError, WrongPasswordError, RecoveryWalletMismatchError, ExportNotAuthorizedError, WalletExistsError, WalletEnrolmentError, ProvisioningRateLimitedError, EnclaveHttpError;
 var init_errors = __esm({
   "src/social/errors.ts"() {
     "use strict";
@@ -187,6 +191,36 @@ var init_errors = __esm({
         super("EXPORT_NOT_AUTHORIZED", "Export requires a fresh security check", true);
       }
     };
+    WalletExistsError = class extends DecaneConnectError {
+      constructor() {
+        super("WALLET_EXISTS", "This account already has a wallet; opening it instead.", true);
+      }
+    };
+    WalletEnrolmentError = class extends DecaneConnectError {
+      constructor(cause) {
+        super(
+          "WALLET_ENROLMENT_FAILED",
+          "Your wallet could not be set up: the signing enclave did not accept it. Nothing was created \u2014 sign in again to try again.",
+          true
+        );
+        if (cause !== void 0) this.cause = cause;
+      }
+    };
+    ProvisioningRateLimitedError = class extends DecaneConnectError {
+      constructor() {
+        super(
+          "PROVISIONING_RATE_LIMITED",
+          "This wallet has been opened on too many devices or tabs in the last hour. Wait a little and sign in again.",
+          true
+        );
+      }
+    };
+    EnclaveHttpError = class extends DecaneConnectError {
+      constructor(status, message) {
+        super("ENCLAVE_HTTP", message, status >= 500);
+        this.status = status;
+      }
+    };
   }
 });
 
@@ -1995,7 +2029,9 @@ var ERROR_MAP = {
   // The backend's authMiddleware code for an expired/revoked JWT. Surfacing it
   // as ReconnectRequiredError routes callers to the sign-in UI instead of a
   // generic failure message.
-  UNAUTHORIZED: ReconnectRequiredError
+  UNAUTHORIZED: ReconnectRequiredError,
+  // A restorable wallet already exists: the client provisions instead of creating.
+  WALLET_EXISTS: WalletExistsError
 };
 var REQUEST_TIMEOUT_MS = 3e4;
 var ApiClient = class {
@@ -2114,7 +2150,8 @@ var ApiClient = class {
         wrappedShareMeta: btoa(JSON.stringify(share.wrappedShareMeta)),
         evmAddress: share.evmAddress,
         solanaAddress: share.solanaAddress,
-        tronAddress: share.tronAddress
+        tronAddress: share.tronAddress,
+        ...share.pendingEnrolment === void 0 ? {} : { pendingEnrolment: share.pendingEnrolment }
       })
     });
   }
@@ -2399,7 +2436,7 @@ function dropCollateral(teeUrl) {
 // src/social/attestation.ts
 init_errors();
 
-// ../../infra/tee-measurement.json
+// ../infra/tee-measurement.json
 var tee_measurement_default = {
   signerVersion: "0.2.10",
   acceptedMrtd: [
@@ -2698,7 +2735,8 @@ var TeeClient = class {
     });
     if (!res.ok) {
       const detail = await res.text().catch(() => "");
-      throw new Error(
+      throw new EnclaveHttpError(
+        res.status,
         `auth share enrolment failed (HTTP ${res.status})${detail ? `: ${detail.slice(0, 200)}` : ""}`
       );
     }
@@ -2719,9 +2757,11 @@ var TeeClient = class {
       headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" }
     });
     if (res.status === 409) return null;
+    if (res.status === 429) throw new ProvisioningRateLimitedError();
     if (!res.ok) {
       const detail = await res.text().catch(() => "");
-      throw new Error(
+      throw new EnclaveHttpError(
+        res.status,
         `device share provisioning failed (HTTP ${res.status})${detail ? `: ${detail.slice(0, 200)}` : ""}`
       );
     }
@@ -2936,6 +2976,35 @@ var SessionManager = class {
   }
 };
 
+// src/social/identityTier.ts
+function resolveProtectionTier(config) {
+  if (config.protection) return config.protection;
+  return config.deferDeviceProtection === true ? "identity" : "device";
+}
+function resumeAcrossTabsDefault(config, identityTier) {
+  return config.resumeSessionAcrossTabs ?? identityTier;
+}
+var ENROL_BACKOFF_MS = [0, 1e3, 3e3];
+function enrolmentRetryable(status) {
+  return status !== 429 && status !== 403;
+}
+function shouldTryProvisionFirst(identityTier, hasStoredShare) {
+  return identityTier || !hasStoredShare;
+}
+function routeAfterProvision(input) {
+  switch (input.outcome) {
+    case "share":
+      return "session";
+    case "rate-limited":
+      return "fail";
+    case "not-enrolled":
+      if (!input.identityTier) return "recover";
+      return input.hasStoredShare ? "migrate" : "new-device";
+    case "error":
+      return input.identityTier ? "fail" : "recover";
+  }
+}
+
 // src/social/crypto/shares.ts
 import { secp256k1 } from "@noble/curves/secp256k1";
 import { split, combine } from "shamir-secret-sharing";
@@ -3846,7 +3915,8 @@ function clearSessionPersist(key) {
 async function createDecaneConnect(config) {
   if (!config.appId) throw new Error("decane-connect-kit: appId is required");
   if (!config.apiKey) throw new Error("decane-connect-kit: apiKey is required");
-  useCrossTabSessionStore(config.resumeSessionAcrossTabs === true);
+  const identityTier = resolveProtectionTier(config) === "identity";
+  useCrossTabSessionStore(resumeAcrossTabsDefault(config, identityTier));
   if (!config.chains?.length)
     throw new Error("decane-connect-kit: at least one chain is required");
   if (config.rotateOnNewDeviceRecovery && !config.onRecoveryRotated) {
@@ -3884,7 +3954,6 @@ async function createDecaneConnect(config) {
   let lastUserId = loadLastUser(LAST_USER_KEY) ?? (LEGACY_LAST_USER_KEY !== LAST_USER_KEY ? loadLastUser(LEGACY_LAST_USER_KEY) : null);
   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();
@@ -3905,22 +3974,27 @@ async function createDecaneConnect(config) {
       zeroize(share);
     }
   }
-  async function enrolInBackground(jwt, share) {
+  async function enrolBlocking(jwt, share, budgetMs) {
+    const startedAt = Date.now();
     try {
-      for (let attempt = 1; attempt <= 2; attempt++) {
+      let lastError;
+      for (const wait of ENROL_BACKOFF_MS) {
+        if (wait) await new Promise((r) => setTimeout(r, wait));
         try {
-          await new TeeClient(teeUrl).enrolAuthShare(jwt, share);
+          await withDeadline(
+            new TeeClient(teeUrl).enrolAuthShare(jwt, share),
+            budgetMs - (Date.now() - startedAt),
+            "enrolling your wallet"
+          );
           return;
         } catch (e) {
-          if (attempt === 2) {
-            events.emit("enrolment-failed");
-            console.warn(
-              "decane-connect-kit: could not enrol this wallet for server-assisted recovery. The wallet is fine and fully usable; it will be re-enrolled automatically on the next unlock. Until then a brand-new device would need a passkey backup or a recovery file.",
-              e
-            );
-          }
+          if (e instanceof AttestationError || e instanceof ProvisioningTimeoutError) throw e;
+          lastError = e;
+          if (!enrolmentRetryable(e.status)) break;
         }
       }
+      events.emit("enrolment-failed");
+      throw new WalletEnrolmentError(lastError);
     } finally {
       zeroize(share);
     }
@@ -4016,6 +4090,7 @@ async function createDecaneConnect(config) {
         else scheduleAccessTokenExpiry(saved.jwt, saved.expiresAt);
         auth = { jwt: saved.jwt, userId: saved.userId, addresses: saved.addresses };
         persisted = { userId: saved.userId, addresses: saved.addresses };
+        if (saved.handle) armTokenRefresh(saved.jwt);
       } catch {
         dropLiveSession();
       }
@@ -4025,6 +4100,13 @@ async function createDecaneConnect(config) {
     if (LEGACY_SESSION_KEY !== SESSION_KEY) clearSessionPersist(LEGACY_SESSION_KEY);
   }
   events.on("session-expired", () => dropLiveSession());
+  function armTokenRefresh(jwt) {
+    const expiresAt = decodeAccessToken(jwt)?.expiresAt;
+    if (expiresAt) scheduleTokenRefresh(jwt, expiresAt);
+  }
+  events.on("connected", () => {
+    if (auth) armTokenRefresh(auth.jwt);
+  });
   async function passwordSetup() {
     if (!config.promptUnlockPassword) throw new PromptPasswordNotConfiguredError();
     const password = await config.promptUnlockPassword({ kind: "set" });
@@ -4249,7 +4331,7 @@ async function createDecaneConnect(config) {
     let wrappingKey = null;
     let meta = {};
     let unlockTokenKey = null;
-    if (deferDeviceProtection) {
+    if (identityTier) {
     } else if (isPasskeySupported()) {
       const prfSalt = generateRandomBytes(32);
       try {
@@ -4316,19 +4398,47 @@ async function createDecaneConnect(config) {
       if (unlockTokenKey) await attachUnlockToken(userId, jwt, unlockTokenKey);
     }
     const serverIv = generateRandomBytes(12);
-    await withDeadline(api.putShare(jwt, {
-      ciphertext: shareSet.server,
-      iv: serverIv,
-      wrappedShareMeta: {
-        // 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,
-      solanaAddress,
-      tronAddress
-    }), remainingBudget(), "storing your wallet");
+    try {
+      await withDeadline(api.putShare(jwt, {
+        ciphertext: shareSet.server,
+        iv: serverIv,
+        wrappedShareMeta: {
+          // The server records this on the wallet_created event and nothing else.
+          unlockMethod: identityTier ? "identity" : unlockMethod
+          // credential IDs, prfSalt, pinSalt stay on-device — never sent to server
+        },
+        evmAddress,
+        solanaAddress,
+        tronAddress,
+        // Provisional until the enclave has sealed the auth share, just below. A
+        // backend that knows the flag keeps this row invisible to hasShare until
+        // then, so a creation that fails past this point leaves no wallet behind
+        // and the next sign-in simply creates again — with a new key, which is
+        // why the backend also replaces the recorded addresses outright.
+        pendingEnrolment: true
+      }), remainingBudget(), "storing your wallet");
+    } catch (e) {
+      if (e instanceof WalletExistsError) {
+        zeroize(shareSet.server);
+        zeroize(shareSet.device);
+        zeroize(shareSet.recovery);
+        if (wrappingKey) await storage2.deleteShare(userId).catch(() => {
+        });
+        events.emit("wallet-unlocking");
+        return returningUserUnlock(userId, jwt);
+      }
+      throw e;
+    }
     zeroize(shareSet.server);
+    try {
+      await enrolBlocking(jwt, new Uint8Array(shareSet.recovery), remainingBudget());
+    } catch (e) {
+      zeroize(shareSet.device);
+      zeroize(shareSet.recovery);
+      if (wrappingKey) await storage2.deleteShare(userId).catch(() => {
+      });
+      throw e;
+    }
     const addresses = { evm: evmAddress, solana: solanaAddress, tron: tronAddress };
     if (unlockMethod === "passkey" && meta.credentialId && meta.prfSalt && wrappedDeviceShare && iv) {
       try {
@@ -4357,10 +4467,7 @@ async function createDecaneConnect(config) {
     addresses.evm = evmAddress = confirmed.evm;
     addresses.solana = solanaAddress = confirmed.solana;
     addresses.tron = tronAddress = confirmed.tron ?? evmToTronAddress2(confirmed.evm);
-    if (serverAssistedRecovery) {
-      void enrolInBackground(jwt, new Uint8Array(shareSet.recovery));
-    }
-    if (config.offerRecoveryAtSignup === true && config.onRecoveryShareOffer) {
+    if (!identityTier && config.offerRecoveryAtSignup === true && config.onRecoveryShareOffer) {
       void offerRecoveryShare(
         jwt,
         new Uint8Array(shareSet.recovery),
@@ -4407,31 +4514,44 @@ async function createDecaneConnect(config) {
     const stored = await storage2.getShare(userId);
     let deviceShare;
     let joinedViaPasskeySync = false;
-    if (!stored) {
-      if (serverAssistedRecovery) {
+    let migrating = false;
+    if (serverAssistedRecovery && shouldTryProvisionFirst(identityTier, !!stored)) {
+      let provisioned = null;
+      let failure;
+      let outcome;
+      try {
+        provisioned = await new TeeClient(teeUrl).provisionDeviceShare(jwt);
+        outcome = provisioned ? "share" : "not-enrolled";
+      } catch (e) {
+        failure = e;
+        outcome = e instanceof ProvisioningRateLimitedError ? "rate-limited" : "error";
+      }
+      const route = routeAfterProvision({ identityTier, hasStoredShare: !!stored, outcome });
+      if (route === "session" && provisioned) {
+        if (!identityTier) await persistProvisionedShare(userId, jwt, provisioned);
+        let addrs;
         try {
-          const tee = new TeeClient(teeUrl);
-          const provisioned = await tee.provisionDeviceShare(jwt);
-          if (provisioned) {
-            if (!deferDeviceProtection) await persistProvisionedShare(userId, jwt, provisioned);
-            let addrs;
-            try {
-              addrs = await session.start(provisioned, jwt, recordedAddresses);
-            } finally {
-              zeroize(provisioned);
-            }
-            return addrs;
-          }
-          console.warn(
-            "decane-connect-kit: this wallet is not enrolled for server-assisted provisioning (/signer/provision returned 409 not_enrolled), so a device share cannot be issued from the JWT alone. Falling back to passkey sync, then the recovery file."
-          );
-        } catch (e) {
-          console.warn(
-            "decane-connect-kit: server-assisted provisioning unavailable; falling back to passkey/recovery-file recovery.",
-            e
-          );
+          addrs = await session.start(provisioned, jwt, recordedAddresses);
+        } finally {
+          zeroize(provisioned);
         }
+        return addrs;
+      }
+      if (route === "fail") throw failure;
+      if (route === "new-device") throw new NewDeviceError();
+      if (route === "migrate") migrating = true;
+      if (route === "recover" && outcome === "not-enrolled") {
+        console.warn(
+          "decane-connect-kit: this wallet is not enrolled for server-assisted provisioning (/signer/provision returned 409 not_enrolled), so a device share cannot be issued from the JWT alone. Falling back to passkey sync, then the recovery file."
+        );
+      } else if (route === "recover") {
+        console.warn(
+          "decane-connect-kit: server-assisted provisioning unavailable; falling back to passkey/recovery-file recovery.",
+          failure
+        );
       }
+    }
+    if (!stored) {
       if (!config.onRecoveryRotated) {
         throw new CallSequenceError(
           "Recovery rotates the share set and issues a new recovery file, but no onRecoveryRotated callback is configured to save it. Configure onRecoveryRotated before allowing recovery."
@@ -4457,7 +4577,7 @@ async function createDecaneConnect(config) {
       });
       deviceShare = recovered.deviceShare;
       joinedViaPasskeySync = recovered.flow === "passkey-sync";
-      if (!deferDeviceProtection && !await storage2.getShare(userId) && isPasskeySupported()) {
+      if (!identityTier && !await storage2.getShare(userId) && isPasskeySupported()) {
         await registerPasskeyAndBackup(userId, jwt, deviceShare);
       }
     } else {
@@ -4471,6 +4591,14 @@ async function createDecaneConnect(config) {
       } catch {
         throw stored.unlockMethod === "pin" ? new InvalidPinError() : new ShareCorruptedError();
       }
+      if (migrating) {
+        try {
+          await enrolBlocking(jwt, new Uint8Array(deviceShare), PROVISIONING_BUDGET_MS);
+        } catch (e) {
+          zeroize(deviceShare);
+          throw e;
+        }
+      }
     }
     let addresses;
     try {
@@ -4485,7 +4613,11 @@ async function createDecaneConnect(config) {
       }
       throw e;
     }
-    void selfHealEnrolment(userId, jwt, new Uint8Array(deviceShare));
+    if (migrating) {
+      events.emit("migrated-to-identity");
+    } else if (!identityTier) {
+      void selfHealEnrolment(userId, jwt, new Uint8Array(deviceShare));
+    }
     zeroize(deviceShare);
     if (recordedAddresses && recordedAddresses.evm.toLowerCase() !== addresses.evm.toLowerCase()) {
       console.warn(
@@ -4668,7 +4800,7 @@ async function createDecaneConnect(config) {
       if (auth && session.isActive()) {
         return { addresses: auth.addresses, isNewUser: false };
       }
-      const candidate = await passkeyLoginCandidate();
+      const candidate = identityTier ? null : await passkeyLoginCandidate();
       if (candidate) {
         try {
           return await passkeyLogin(candidate);
@@ -4778,9 +4910,15 @@ async function createDecaneConnect(config) {
       return handleAuthResult(result);
     },
     async canSignInWithPasskey() {
+      if (identityTier) return false;
       return canOfferPasskey();
     },
     async signInWithPasskey() {
+      if (identityTier) {
+        throw new CallSequenceError(
+          "signInWithPasskey() is not available in the identity tier (protection: 'identity'); use connect()."
+        );
+      }
       const candidate = await passkeyDeviceCandidate();
       if (candidate) return passkeyLogin(candidate);
       const known = persisted?.userId ?? lastUserId;
@@ -4916,6 +5054,11 @@ async function createDecaneConnect(config) {
       return stored?.unlockMethod === "passkey";
     },
     async addPasskey() {
+      if (identityTier) {
+        throw new CallSequenceError(
+          "addPasskey() is not available in the identity tier (protection: 'identity'): nothing is stored on the device for a passkey to protect."
+        );
+      }
       if (!auth) throw new ReconnectRequiredError();
       if (!isPasskeySupported()) throw new WebAuthnNotSupportedError();
       const stored = await storage2.getShare(auth.userId);
@@ -4954,6 +5097,7 @@ async function createDecaneConnect(config) {
       return await storage2.getShare(auth.userId) !== null;
     },
     async protectDevice() {
+      if (identityTier) return false;
       if (!auth) throw new ReconnectRequiredError();
       if (await storage2.getShare(auth.userId)) return true;
       if (!serverAssistedRecovery) throw new NewDeviceError();
@@ -4969,7 +5113,7 @@ async function createDecaneConnect(config) {
     },
     async unlock() {
       if (!auth) {
-        const candidate = await passkeyLoginCandidate();
+        const candidate = identityTier ? null : await passkeyLoginCandidate();
         if (candidate) {
           await passkeyLogin(candidate);
           return;
@@ -5138,6 +5282,8 @@ async function createDecaneConnect(config) {
     },
     async disconnect() {
       session.end();
+      if (tokenRefresh) clearTimeout(tokenRefresh);
+      tokenRefresh = null;
       if (auth?.jwt) {
         await api.revoke(auth.jwt).catch(() => {
         });
@@ -7595,6 +7741,7 @@ function DecaneKit({ config, children }) {
       chains,
       rpcUrls,
       requireAssertionPerSignature,
+      protection,
       deferDeviceProtection,
       resumeSessionAcrossTabs,
       // Recovery callbacks. Forwarding these is what makes recovery
@@ -7617,6 +7764,7 @@ function DecaneKit({ config, children }) {
       promptPin,
       promptUnlockPassword,
       requireAssertionPerSignature,
+      protection,
       deferDeviceProtection,
       resumeSessionAcrossTabs,
       offerRecoveryAtSignup,
@@ -8825,6 +8973,7 @@ export {
   DecaneLogo,
   DecaneMark,
   DecaneWordmark,
+  EnclaveHttpError,
   ExportNotAuthorizedError,
   InvalidAccessTokenError,
   InvalidApiKeyError,
@@ -8836,6 +8985,7 @@ export {
   OriginNotAllowedError,
   PromptPasswordNotConfiguredError,
   PromptPinNotConfiguredError,
+  ProvisioningRateLimitedError,
   ProvisioningTimeoutError,
   ReconnectRequiredError,
   RecoveryFailedError,
@@ -8847,6 +8997,8 @@ export {
   UnlockRequiredError,
   UnlockTokenRejectedError,
   UserCancelledError,
+  WalletEnrolmentError,
+  WalletExistsError,
   WalletSelector,
   WeakPasswordError,
   WebAuthnNotSupportedError,