decane-connect-kit 2.26.1 → 2.27.0

package/dist/index.d.cts

@@ -147,6 +147,44 @@ interface DecaneConnectConfig {
      */
     persistSession?: boolean;
     /**
+     * How this device holds its share of the wallet. Default `'device'`.
+     *
+     *  - `'device'`: the share is wrapped at rest under a passkey (or the unlock
+     *    password) at creation and when a new device is provisioned. Sign-in asks
+     *    for it once per device; `requireAssertionPerSignature` is available.
+     *  - `'identity'`: nothing is stored on the device and nothing is asked for.
+     *    Every visit is a sign-in, after which the enclave provisions a fresh
+     *    device share against the JWT alone. No passkey, no password, no
+     *    recovery file — recovery IS signing in again. `resumeSessionAcrossTabs`
+     *    defaults to true here so a session is provisioned once, not per tab.
+     *
+     * THE SECURITY STATEMENT for the identity tier: a wallet is exactly as safe
+     * as the user's identity-provider account plus Decane (the JWT signing key
+     * and the attested enclave). Anyone who can obtain a valid Decane session
+     * for the user can sign. There is no device-bound factor. Mitigations: a
+     * new-device email on every provision from an unseen device, a per-user
+     * freeze switch operated by Decane, and (follow-up) a fresh sign-in
+     * requirement for high-value operations.
+     *
+     * The tier is a property of THIS client, not of the wallet: two apps on one
+     * project may hold the same wallet in different tiers (a marketplace with
+     * passkeys, a social app without). Same key, same addresses, same funds.
+     * Note the consequence: a per-signature assertion declared by one app
+     * protects that app's sessions, not the wallet — the other app's session
+     * signs without it.
+     *
+     * Switching an app from `'device'` to `'identity'` ports its users on their
+     * next sign-in with no loss of funds: an enrolled wallet (the normal case)
+     * simply provisions with no prompt; a wallet that was never enrolled but has
+     * a wrapped share on this device is unlocked with the existing passkey or
+     * password ONE last time, enrolled, and never prompted again (the client
+     * emits `migrated-to-identity`). Nothing is re-split, rotated or moved.
+     */
+    protection?: 'identity' | 'device';
+    /**
+     * @deprecated Use `protection: 'identity'`. Identical behaviour; kept as an
+     * alias so existing apps need no change.
+     *
      * 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
@@ -160,7 +198,8 @@ interface DecaneConnectConfig {
      */
     deferDeviceProtection?: boolean;
     /**
-     * Resume a live session in a NEW TAB, not just after a reload. Default false.
+     * Resume a live session in a NEW TAB, not just after a reload. Default
+     * false in the device tier, true in the identity tier (see `protection`).
      *
      * The session — handle plus JWT — normally lives in sessionStorage, so it
      * survives a reload and dies with the tab. That makes a second tab, or a
@@ -323,7 +362,14 @@ type SdkEvent = 'connected' | 'disconnected' | 'session-expired'
  * later unlocks; surface or report this if you want visibility rather than a
  * console line.
  */
- | 'enrolment-failed';
+ | 'enrolment-failed'
+/**
+ * An identity-tier client just unlocked a wallet that was never enrolled by
+ * prompting for the passkey or password that protected this device's share,
+ * and enrolled it. The one-off prompt will not appear again; apps that want
+ * to explain it to the user listen for this. Same key, same addresses.
+ */
+ | 'migrated-to-identity';
 interface DecaneConnect {
     connect(): Promise<ConnectResult>;
     connectWithGoogle(): Promise<ConnectResult>;
@@ -478,7 +524,8 @@ interface DecaneConnect {
      * Requires a live session; throws `WebAuthnNotSupportedError` where passkeys
      * are unavailable, and `NewDeviceError` when this device holds no share yet
      * (that case wants `connect()`, which provisions one and registers a passkey
-     * on the way).
+     * on the way). Throws `CallSequenceError` in the identity tier, which holds
+     * no share on the device for a passkey to wrap.
      */
     addPasskey(): Promise<void>;
     /**
@@ -493,7 +540,8 @@ interface DecaneConnect {
      * 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.
+     * to go on without protection; throws for anything else. A no-op returning
+     * false in the identity tier: that tier stores nothing on the device.
      */
     protectDevice(): Promise<boolean>;
     sessionExpiresAt(): number | null;
@@ -601,7 +649,7 @@ interface DecaneConnect {
     off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
 }
 interface WrappedShareMeta {
-    unlockMethod: 'passkey' | 'pin' | 'password' | 'deferred';
+    unlockMethod: 'passkey' | 'pin' | 'password' | 'deferred' | 'identity';
     credentialId?: string;
     prfSalt?: string;
     pinSalt?: string;
@@ -703,6 +751,13 @@ declare class ApiClient {
         evmAddress: string;
         solanaAddress: string;
         tronAddress: string;
+        /**
+         * The share is being written BEFORE the enclave has sealed the auth share.
+         * A backend that knows the flag treats the row as provisional: invisible to
+         * hasShare until enrolment lands, and replaced outright by a later
+         * creation. Omitted, the backend behaves as it always did.
+         */
+        pendingEnrolment?: boolean;
     }): Promise<void>;
     recordTransaction(jwt: string, tx: {
         chain: string;
@@ -926,6 +981,16 @@ interface SocialConfig {
      */
     showStatusOverlay?: boolean;
     /**
+     * How this device holds its share of the wallet: `'device'` (default) wraps
+     * it under a passkey or password; `'identity'` stores nothing and asks for
+     * nothing — sign-in is the whole ceremony, every visit. Mirrors the headless
+     * client's option of the same name; read it for the security statement
+     * before choosing `'identity'`.
+     */
+    protection?: 'identity' | 'device';
+    /**
+     * @deprecated Use `protection: 'identity'`. Same behaviour; kept as an alias.
+     *
      * 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;
@@ -1211,6 +1276,35 @@ declare class RecoveryWalletMismatchError extends DecaneConnectError {
 declare class ExportNotAuthorizedError extends DecaneConnectError {
     constructor();
 }
+/**
+ * Wallet creation stopped because the enclave did not seal the wallet's
+ * recovery share (enrolment). Creation blocks on that step in every tier,
+ * because a wallet that exists unenrolled cannot be provisioned to any other
+ * device — and in the identity tier not even to this one, once the session
+ * ends. The server share was uploaded as provisional and the device share, if
+ * one was stored, has been deleted: nothing is left behind, and the next
+ * sign-in creates a wallet from scratch. Retryable for exactly that reason.
+ */
+declare class WalletEnrolmentError extends DecaneConnectError {
+    constructor(cause?: unknown);
+}
+/**
+ * /signer/provision answered 429: this user has been issued device shares too
+ * often in the last hour. Distinct from NewDeviceError on purpose — the wallet
+ * is enrolled and fine, and sending the user to a recovery file they do not
+ * have (the old behaviour) was wrong. Wait, then sign in again.
+ */
+declare class ProvisioningRateLimitedError extends DecaneConnectError {
+    constructor();
+}
+/**
+ * A non-OK answer from the enclave on a call with no more specific mapping,
+ * carrying the status so a caller can decide whether trying again could help.
+ */
+declare class EnclaveHttpError extends DecaneConnectError {
+    status: number;
+    constructor(status: number, message: string);
+}
 
 declare class DecaneError extends Error {
     code: DecaneErrorCode;
@@ -1659,4 +1753,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, 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 };
+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, EnclaveHttpError, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningRateLimitedError, 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, WalletEnrolmentError, 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

@@ -147,6 +147,44 @@ interface DecaneConnectConfig {
      */
     persistSession?: boolean;
     /**
+     * How this device holds its share of the wallet. Default `'device'`.
+     *
+     *  - `'device'`: the share is wrapped at rest under a passkey (or the unlock
+     *    password) at creation and when a new device is provisioned. Sign-in asks
+     *    for it once per device; `requireAssertionPerSignature` is available.
+     *  - `'identity'`: nothing is stored on the device and nothing is asked for.
+     *    Every visit is a sign-in, after which the enclave provisions a fresh
+     *    device share against the JWT alone. No passkey, no password, no
+     *    recovery file — recovery IS signing in again. `resumeSessionAcrossTabs`
+     *    defaults to true here so a session is provisioned once, not per tab.
+     *
+     * THE SECURITY STATEMENT for the identity tier: a wallet is exactly as safe
+     * as the user's identity-provider account plus Decane (the JWT signing key
+     * and the attested enclave). Anyone who can obtain a valid Decane session
+     * for the user can sign. There is no device-bound factor. Mitigations: a
+     * new-device email on every provision from an unseen device, a per-user
+     * freeze switch operated by Decane, and (follow-up) a fresh sign-in
+     * requirement for high-value operations.
+     *
+     * The tier is a property of THIS client, not of the wallet: two apps on one
+     * project may hold the same wallet in different tiers (a marketplace with
+     * passkeys, a social app without). Same key, same addresses, same funds.
+     * Note the consequence: a per-signature assertion declared by one app
+     * protects that app's sessions, not the wallet — the other app's session
+     * signs without it.
+     *
+     * Switching an app from `'device'` to `'identity'` ports its users on their
+     * next sign-in with no loss of funds: an enrolled wallet (the normal case)
+     * simply provisions with no prompt; a wallet that was never enrolled but has
+     * a wrapped share on this device is unlocked with the existing passkey or
+     * password ONE last time, enrolled, and never prompted again (the client
+     * emits `migrated-to-identity`). Nothing is re-split, rotated or moved.
+     */
+    protection?: 'identity' | 'device';
+    /**
+     * @deprecated Use `protection: 'identity'`. Identical behaviour; kept as an
+     * alias so existing apps need no change.
+     *
      * 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
@@ -160,7 +198,8 @@ interface DecaneConnectConfig {
      */
     deferDeviceProtection?: boolean;
     /**
-     * Resume a live session in a NEW TAB, not just after a reload. Default false.
+     * Resume a live session in a NEW TAB, not just after a reload. Default
+     * false in the device tier, true in the identity tier (see `protection`).
      *
      * The session — handle plus JWT — normally lives in sessionStorage, so it
      * survives a reload and dies with the tab. That makes a second tab, or a
@@ -323,7 +362,14 @@ type SdkEvent = 'connected' | 'disconnected' | 'session-expired'
  * later unlocks; surface or report this if you want visibility rather than a
  * console line.
  */
- | 'enrolment-failed';
+ | 'enrolment-failed'
+/**
+ * An identity-tier client just unlocked a wallet that was never enrolled by
+ * prompting for the passkey or password that protected this device's share,
+ * and enrolled it. The one-off prompt will not appear again; apps that want
+ * to explain it to the user listen for this. Same key, same addresses.
+ */
+ | 'migrated-to-identity';
 interface DecaneConnect {
     connect(): Promise<ConnectResult>;
     connectWithGoogle(): Promise<ConnectResult>;
@@ -478,7 +524,8 @@ interface DecaneConnect {
      * Requires a live session; throws `WebAuthnNotSupportedError` where passkeys
      * are unavailable, and `NewDeviceError` when this device holds no share yet
      * (that case wants `connect()`, which provisions one and registers a passkey
-     * on the way).
+     * on the way). Throws `CallSequenceError` in the identity tier, which holds
+     * no share on the device for a passkey to wrap.
      */
     addPasskey(): Promise<void>;
     /**
@@ -493,7 +540,8 @@ interface DecaneConnect {
      * 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.
+     * to go on without protection; throws for anything else. A no-op returning
+     * false in the identity tier: that tier stores nothing on the device.
      */
     protectDevice(): Promise<boolean>;
     sessionExpiresAt(): number | null;
@@ -601,7 +649,7 @@ interface DecaneConnect {
     off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
 }
 interface WrappedShareMeta {
-    unlockMethod: 'passkey' | 'pin' | 'password' | 'deferred';
+    unlockMethod: 'passkey' | 'pin' | 'password' | 'deferred' | 'identity';
     credentialId?: string;
     prfSalt?: string;
     pinSalt?: string;
@@ -703,6 +751,13 @@ declare class ApiClient {
         evmAddress: string;
         solanaAddress: string;
         tronAddress: string;
+        /**
+         * The share is being written BEFORE the enclave has sealed the auth share.
+         * A backend that knows the flag treats the row as provisional: invisible to
+         * hasShare until enrolment lands, and replaced outright by a later
+         * creation. Omitted, the backend behaves as it always did.
+         */
+        pendingEnrolment?: boolean;
     }): Promise<void>;
     recordTransaction(jwt: string, tx: {
         chain: string;
@@ -926,6 +981,16 @@ interface SocialConfig {
      */
     showStatusOverlay?: boolean;
     /**
+     * How this device holds its share of the wallet: `'device'` (default) wraps
+     * it under a passkey or password; `'identity'` stores nothing and asks for
+     * nothing — sign-in is the whole ceremony, every visit. Mirrors the headless
+     * client's option of the same name; read it for the security statement
+     * before choosing `'identity'`.
+     */
+    protection?: 'identity' | 'device';
+    /**
+     * @deprecated Use `protection: 'identity'`. Same behaviour; kept as an alias.
+     *
      * 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;
@@ -1211,6 +1276,35 @@ declare class RecoveryWalletMismatchError extends DecaneConnectError {
 declare class ExportNotAuthorizedError extends DecaneConnectError {
     constructor();
 }
+/**
+ * Wallet creation stopped because the enclave did not seal the wallet's
+ * recovery share (enrolment). Creation blocks on that step in every tier,
+ * because a wallet that exists unenrolled cannot be provisioned to any other
+ * device — and in the identity tier not even to this one, once the session
+ * ends. The server share was uploaded as provisional and the device share, if
+ * one was stored, has been deleted: nothing is left behind, and the next
+ * sign-in creates a wallet from scratch. Retryable for exactly that reason.
+ */
+declare class WalletEnrolmentError extends DecaneConnectError {
+    constructor(cause?: unknown);
+}
+/**
+ * /signer/provision answered 429: this user has been issued device shares too
+ * often in the last hour. Distinct from NewDeviceError on purpose — the wallet
+ * is enrolled and fine, and sending the user to a recovery file they do not
+ * have (the old behaviour) was wrong. Wait, then sign in again.
+ */
+declare class ProvisioningRateLimitedError extends DecaneConnectError {
+    constructor();
+}
+/**
+ * A non-OK answer from the enclave on a call with no more specific mapping,
+ * carrying the status so a caller can decide whether trying again could help.
+ */
+declare class EnclaveHttpError extends DecaneConnectError {
+    status: number;
+    constructor(status: number, message: string);
+}
 
 declare class DecaneError extends Error {
     code: DecaneErrorCode;
@@ -1659,4 +1753,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, 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 };
+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, EnclaveHttpError, type EthereumProviderOptions, ExportNotAuthorizedError, InvalidAccessTokenError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, type KingsChatTokens, MIN_PASSWORD_LENGTH, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPasswordNotConfiguredError, PromptPinNotConfiguredError, ProvisioningRateLimitedError, 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, WalletEnrolmentError, WalletSelector, WeakPasswordError, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, WrongUnlockPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, validateUnlockPassword, verifyEmailCode };