decane-connect-kit 2.22.0 → 2.24.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`.
@@ -345,6 +358,19 @@ interface DecaneConnect {
     connectWithToken(token: string, opts?: {
         providerId?: string;
     }): Promise<ConnectResult>;
+    /**
+     * Adopt a Decane access token another app of the same project handed over
+     * (in a URL, say): signed in at once, unlocked on the first signature.
+     *
+     * The token is the one every API call carries as a Bearer. The backend
+     * judges it — a revoked or foreign token is refused — and the session lasts
+     * as long as the token does, at most two hours; when it lapses the client
+     * emits `session-expired` and reads as signed out. No enclave session is
+     * opened: the first `unlock()` (or any signing call) provisions or unwraps
+     * the device share as an ordinary returning sign-in would, and with
+     * `deferDeviceProtection` prompts for nothing.
+     */
+    connectWithAccessToken(token: string): Promise<ConnectResult>;
     verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
     /**
      * Send a 6-digit sign-in code by SMS (delivered via Termii).
@@ -428,6 +454,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 +574,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 +888,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`.
@@ -1095,6 +1143,9 @@ declare class PromptPasswordNotConfiguredError extends DecaneConnectError {
 declare class WrongUnlockPasswordError extends DecaneConnectError {
     constructor();
 }
+declare class InvalidAccessTokenError extends DecaneConnectError {
+    constructor(reason: string);
+}
 declare class UnlockTokenRejectedError extends DecaneConnectError {
     constructor();
 }
@@ -1388,6 +1439,7 @@ declare function useSocialAuth(): {
     signInWithToken: (token: string, opts?: {
         providerId?: string;
     }) => Promise<void>;
+    signInWithAccessToken: (token: string) => Promise<void>;
     signInWithCustomAuth: (() => Promise<void>) | undefined;
     signInWithPasskey: () => Promise<void>;
     unlock: () => Promise<void>;
@@ -1448,6 +1500,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>;
@@ -1561,4 +1615,4 @@ declare class WeakPasswordError extends Error {
  */
 declare function validateUnlockPassword(password: string): void;
 
-export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };
+export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };

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`.
@@ -345,6 +358,19 @@ interface DecaneConnect {
     connectWithToken(token: string, opts?: {
         providerId?: string;
     }): Promise<ConnectResult>;
+    /**
+     * Adopt a Decane access token another app of the same project handed over
+     * (in a URL, say): signed in at once, unlocked on the first signature.
+     *
+     * The token is the one every API call carries as a Bearer. The backend
+     * judges it — a revoked or foreign token is refused — and the session lasts
+     * as long as the token does, at most two hours; when it lapses the client
+     * emits `session-expired` and reads as signed out. No enclave session is
+     * opened: the first `unlock()` (or any signing call) provisions or unwraps
+     * the device share as an ordinary returning sign-in would, and with
+     * `deferDeviceProtection` prompts for nothing.
+     */
+    connectWithAccessToken(token: string): Promise<ConnectResult>;
     verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
     /**
      * Send a 6-digit sign-in code by SMS (delivered via Termii).
@@ -428,6 +454,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 +574,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 +888,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`.
@@ -1095,6 +1143,9 @@ declare class PromptPasswordNotConfiguredError extends DecaneConnectError {
 declare class WrongUnlockPasswordError extends DecaneConnectError {
     constructor();
 }
+declare class InvalidAccessTokenError extends DecaneConnectError {
+    constructor(reason: string);
+}
 declare class UnlockTokenRejectedError extends DecaneConnectError {
     constructor();
 }
@@ -1388,6 +1439,7 @@ declare function useSocialAuth(): {
     signInWithToken: (token: string, opts?: {
         providerId?: string;
     }) => Promise<void>;
+    signInWithAccessToken: (token: string) => Promise<void>;
     signInWithCustomAuth: (() => Promise<void>) | undefined;
     signInWithPasskey: () => Promise<void>;
     unlock: () => Promise<void>;
@@ -1448,6 +1500,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>;
@@ -1561,4 +1615,4 @@ declare class WeakPasswordError extends Error {
  */
 declare function validateUnlockPassword(password: string): void;
 
-export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };
+export { type ActiveSession, AttestationError, type AuthProfile, type AuthResult, BUILT_IN_CHAINS, type BalanceResult, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, DecaneLogo, DecaneMark, type DecaneProvider, DecaneWordmark, type Eip1193Provider, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningTimeoutError, ReconnectRequiredError, type RecordTransactionInput, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SignTypedDataRequest, type SignedAuthorization, type SocialAuthState, type SocialConfig, SocialWalletModal, StaleDeviceShareError, type Theme, type TransactionRecord, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UnlockTokenRejectedError, UserCancelledError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };

package/dist/index.js

@@ -15,6 +15,7 @@ __export(errors_exports, {
   CallSequenceError: () => CallSequenceError,
   DecaneConnectError: () => DecaneConnectError,
   ExportNotAuthorizedError: () => ExportNotAuthorizedError,
+  InvalidAccessTokenError: () => InvalidAccessTokenError,
   InvalidApiKeyError: () => InvalidApiKeyError,
   InvalidPinError: () => InvalidPinError,
   InvalidRecoveryFileError: () => InvalidRecoveryFileError,
@@ -37,7 +38,7 @@ __export(errors_exports, {
   WrongPasswordError: () => WrongPasswordError,
   WrongUnlockPasswordError: () => WrongUnlockPasswordError
 });
-var DecaneConnectError, InvalidApiKeyError, OriginNotAllowedError, SessionExpiredError, UnlockRequiredError, ReconnectRequiredError, UserCancelledError, WebAuthnNotSupportedError, InvalidPinError, CallSequenceError, NetworkError, ShareCorruptedError, ProvisioningTimeoutError, NewDeviceError, StaleDeviceShareError, PromptPinNotConfiguredError, PromptPasswordNotConfiguredError, WrongUnlockPasswordError, 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;
 var init_errors = __esm({
   "src/social/errors.ts"() {
     "use strict";
@@ -142,6 +143,11 @@ var init_errors = __esm({
         super("WRONG_UNLOCK_PASSWORD", "That password did not unlock this device");
       }
     };
+    InvalidAccessTokenError = class extends DecaneConnectError {
+      constructor(reason) {
+        super("INVALID_ACCESS_TOKEN", `That access token cannot open a session: ${reason}`);
+      }
+    };
     UnlockTokenRejectedError = class extends DecaneConnectError {
       constructor() {
         super("UNLOCK_TOKEN_REJECTED", "This device's unlock token is no longer valid \u2014 sign in normally to re-enable password unlock");
@@ -2273,6 +2279,20 @@ function b64ToBytes(b644) {
   return Uint8Array.from(atob(b644), (c) => c.charCodeAt(0));
 }
 
+// src/social/accessToken.ts
+function decodeAccessToken(token) {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) return null;
+    const json = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
+    if (typeof json.uid !== "string" || json.uid === "") return null;
+    if (typeof json.exp !== "number" || !Number.isFinite(json.exp)) return null;
+    return { userId: json.uid, expiresAt: json.exp * 1e3 };
+  } catch {
+    return null;
+  }
+}
+
 // src/social/storage.ts
 import { openDB } from "idb";
 var DB_NAME = "decane-connect-kit";
@@ -3667,8 +3687,10 @@ async function createDecaneConnect(config) {
   const durationMs = (config.sessionDurationMinutes ?? DEFAULT_SESSION_MINUTES) * 6e4;
   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 PERSIST_KEY = makePersistKey(config.appId);
+  const LAST_USER_KEY = makeLastUserKey(config.appId);
+  const LEGACY_PERSIST_KEY = makePersistKey(config.apiKey);
+  const LEGACY_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);
@@ -3681,9 +3703,17 @@ async function createDecaneConnect(config) {
   );
   let auth = null;
   let persisted = loadPersisted(PERSIST_KEY);
-  let lastUserId = loadLastUser(LAST_USER_KEY);
+  if (!persisted && LEGACY_PERSIST_KEY !== PERSIST_KEY) {
+    persisted = loadPersisted(LEGACY_PERSIST_KEY);
+    if (persisted) {
+      savePersisted(PERSIST_KEY, persisted);
+      clearPersisted(LEGACY_PERSIST_KEY);
+    }
+  }
+  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();
@@ -3743,12 +3773,13 @@ async function createDecaneConnect(config) {
       })
     ]).finally(() => clearTimeout(timer));
   }
-  const SESSION_KEY = sessionPersistKey(config.apiKey);
+  const SESSION_KEY = sessionPersistKey(config.appId);
+  const LEGACY_SESSION_KEY = sessionPersistKey(config.apiKey);
   function persistLiveSession() {
-    if (!persistSession) return;
+    if (!persistSession || !auth) return;
     const handle = session.getHandle();
-    const expiresAt = session.expiresAtTimestamp();
-    if (!handle || !auth || !expiresAt) return;
+    const expiresAt = handle ? session.expiresAtTimestamp() : decodeAccessToken(auth.jwt)?.expiresAt ?? null;
+    if (!expiresAt) return;
     saveSession(SESSION_KEY, {
       handle,
       jwt: auth.jwt,
@@ -3760,11 +3791,23 @@ async function createDecaneConnect(config) {
   function dropLiveSession() {
     clearSessionPersist(SESSION_KEY);
   }
+  let accessTokenExpiry = null;
+  function scheduleAccessTokenExpiry(jwt, expiresAt) {
+    if (accessTokenExpiry) clearTimeout(accessTokenExpiry);
+    accessTokenExpiry = setTimeout(() => {
+      accessTokenExpiry = null;
+      if (auth?.jwt !== jwt || session.isActive()) return;
+      auth = null;
+      dropLiveSession();
+      events.emit("session-expired");
+    }, Math.max(0, expiresAt - Date.now()));
+  }
   if (persistSession) {
-    const saved = loadSession(SESSION_KEY);
-    if (saved?.handle && saved.expiresAt > Date.now() + 5e3) {
+    const saved = loadSession(SESSION_KEY) ?? (LEGACY_SESSION_KEY !== SESSION_KEY ? loadSession(LEGACY_SESSION_KEY) : null);
+    if (saved && saved.expiresAt > Date.now() + 5e3) {
       try {
-        session.resume(saved.handle, saved.addresses, saved.expiresAt);
+        if (saved.handle) session.resume(saved.handle, saved.addresses, saved.expiresAt);
+        else scheduleAccessTokenExpiry(saved.jwt, saved.expiresAt);
         auth = { jwt: saved.jwt, userId: saved.userId, addresses: saved.addresses };
         persisted = { userId: saved.userId, addresses: saved.addresses };
       } catch {
@@ -3773,6 +3816,7 @@ async function createDecaneConnect(config) {
     } else if (saved) {
       dropLiveSession();
     }
+    if (LEGACY_SESSION_KEY !== SESSION_KEY) clearSessionPersist(LEGACY_SESSION_KEY);
   }
   events.on("session-expired", () => dropLiveSession());
   async function passwordSetup() {
@@ -3995,11 +4039,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 +4085,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 +4124,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 +4207,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 +4251,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 {
@@ -4484,6 +4534,27 @@ async function createDecaneConnect(config) {
       const result = await api.authExternal(token, opts?.providerId);
       return handleAuthResult(result);
     },
+    async connectWithAccessToken(token) {
+      const claims = decodeAccessToken(token);
+      if (!claims) throw new InvalidAccessTokenError("not a Decane access token");
+      if (claims.expiresAt <= Date.now() + 5e3) throw new InvalidAccessTokenError("it has expired");
+      const raw = await api.getAddresses(token);
+      if (!raw.evm || !raw.solana) throw new InvalidAccessTokenError("this account holds no wallet yet");
+      const addresses = { evm: raw.evm, solana: raw.solana, tron: raw.tron ?? evmToTronAddress2(raw.evm) };
+      if (session.isActive()) session.end();
+      auth = { jwt: token, userId: claims.userId, addresses };
+      persisted = { userId: claims.userId, addresses };
+      savePersisted(PERSIST_KEY, persisted);
+      events.emit("connected");
+      persistLiveSession();
+      scheduleAccessTokenExpiry(token, claims.expiresAt);
+      const stored = await storage.getShare(claims.userId);
+      return {
+        addresses,
+        isNewUser: false,
+        ...stored?.profile ? { profile: stored.profile } : {}
+      };
+    },
     async connectWithEmail(email) {
       await startEmailAuth(api, email);
       return { codeRequired: true };
@@ -4672,6 +4743,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 +7390,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 +7411,7 @@ function DecaneKit({ config, children }) {
       promptPin,
       promptUnlockPassword,
       requireAssertionPerSignature,
+      deferDeviceProtection,
       offerRecoveryAtSignup,
       onRecoveryShareOffer,
       onRecoveryFileReady,
@@ -7456,6 +7547,18 @@ function DecaneKit({ config, children }) {
       throw e;
     }
   }, [clearPhase]);
+  const connectWithAccessToken = useCallback3(async (token) => {
+    const sdk = socialRef.current;
+    if (!sdk) throw new Error("Social sign-in not configured");
+    try {
+      const result = await sdk.connectWithAccessToken(token);
+      applyResult(result);
+      setSelectorOpen(false);
+    } catch (e) {
+      clearPhase();
+      throw e;
+    }
+  }, [clearPhase]);
   const customAuthConfig = config?.social?.customAuth;
   const connectWithCustomAuth = useCallback3(async () => {
     if (!customAuthConfig) throw new Error("Custom auth not configured");
@@ -7567,6 +7670,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");
@@ -7638,6 +7751,7 @@ function DecaneKit({ config, children }) {
         connectWithPhone,
         verifyPhoneCode: verifyPhoneCode2,
         connectWithToken,
+        connectWithAccessToken,
         customAuthLabel: customAuthConfig?.label,
         connectWithCustomAuth: customAuthConfig ? connectWithCustomAuth : void 0,
         socialUnlock,
@@ -7659,6 +7773,8 @@ function DecaneKit({ config, children }) {
         socialHasRecoveryShare,
         socialHasPasskey,
         socialAddPasskey,
+        socialDeviceProtected,
+        socialProtectDevice,
         socialSetUnlockPassword,
         socialCanUnlockWithPassword,
         socialForgetLastUser,
@@ -7751,6 +7867,7 @@ function useSocialAuth() {
     connectWithPhone,
     verifyPhoneCode: verifyPhoneCode2,
     connectWithToken,
+    connectWithAccessToken,
     customAuthLabel,
     connectWithCustomAuth,
     signInWithPasskey: ctxSignInWithPasskey,
@@ -7859,6 +7976,18 @@ function useSocialAuth() {
       setTokenLoading(false);
     }
   }, [connectWithToken]);
+  const signInWithAccessToken = useCallback4(async (token) => {
+    setTokenLoading(true);
+    setError(null);
+    try {
+      await connectWithAccessToken(token);
+    } catch (e) {
+      setError(e.message);
+      throw e;
+    } finally {
+      setTokenLoading(false);
+    }
+  }, [connectWithAccessToken]);
   const signInWithCustomAuth = useCallback4(async () => {
     if (!connectWithCustomAuth) throw new Error("Custom auth not configured");
     setCustomLoading(true);
@@ -7941,6 +8070,7 @@ function useSocialAuth() {
     sendPhoneCode,
     confirmPhoneCode,
     signInWithToken,
+    signInWithAccessToken,
     signInWithCustomAuth: connectWithCustomAuth ? signInWithCustomAuth : void 0,
     signInWithPasskey,
     unlock,
@@ -7969,6 +8099,8 @@ function useSocialWallet() {
     socialHasRecoveryShare,
     socialHasPasskey,
     socialAddPasskey,
+    socialDeviceProtected,
+    socialProtectDevice,
     socialSetUnlockPassword,
     socialCanUnlockWithPassword,
     socialForgetLastUser,
@@ -8071,6 +8203,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 +8301,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.
@@ -8473,6 +8619,7 @@ export {
   DecaneMark,
   DecaneWordmark,
   ExportNotAuthorizedError,
+  InvalidAccessTokenError,
   InvalidApiKeyError,
   InvalidPinError,
   InvalidRecoveryFileError,