decane-connect-kit 2.11.0 → 2.12.1

package/dist/index.d.cts

@@ -104,6 +104,18 @@ interface DecaneConnectConfig {
     apiBaseUrl?: string;
     sessionDurationMinutes?: number;
     promptPin?: () => Promise<string>;
+    /**
+     * Prompts for the device unlock password. Required on any device that has
+     * one — both to set it (`kind: 'set'`, ask twice and confirm) and to use it
+     * (`kind: 'unlock'`).
+     *
+     * Unlike promptPin, this secret can open a session on its own, so treat it
+     * with the care a password deserves: never log it, never persist it, and let
+     * a password manager fill it.
+     */
+    promptUnlockPassword?: (ctx: {
+        kind: 'set' | 'unlock';
+    }) => Promise<string>;
     /**
      * Require a fresh WebAuthn assertion for every signature, instead of letting
      * an unlocked session sign freely until it expires. The TEE session stays
@@ -359,6 +371,18 @@ interface DecaneConnect {
     signInWithPasskey(): Promise<ConnectResult>;
     /** Whether THIS device's share is wrapped by a passkey rather than a PIN. */
     hasPasskey(): Promise<boolean>;
+    /**
+     * Turn on "unlock with your password": re-wraps the device share under the
+     * password and stores an unlock token beside it. Needs a live session.
+     * Throws WeakPasswordError if the password is too weak to carry a session.
+     */
+    setUnlockPassword(password: string): Promise<void>;
+    /** True when this device can open a session from a password alone. */
+    canUnlockWithPassword(): Promise<boolean>;
+    /** Open a session from the password alone — no provider, no passkey. */
+    unlockWithPassword(password: string): Promise<ConnectResult>;
+    /** Turn the password path off, revoking the token account-wide. */
+    removeUnlockPassword(): Promise<void>;
     /**
      * Add a passkey to this device after the fact, re-wrapping its device share
      * under it.
@@ -581,6 +605,22 @@ declare class ApiClient {
      */
     getWebAuthnLoginOptions(userId: string, rpId: string): Promise<_simplewebauthn_browser.PublicKeyCredentialRequestOptionsJSON | null>;
     postWebAuthnLogin(userId: string, response: _simplewebauthn_browser.AuthenticationResponseJSON, origin: string): Promise<AuthResult>;
+    /**
+     * Issue this device an unlock token. Returned in the clear once and never
+     * again — the backend stores only its hash — so the caller must encrypt and
+     * persist it before the value is dropped.
+     */
+    issueUnlockToken(jwt: string): Promise<{
+        token: string;
+        expiresInDays: number;
+    }>;
+    /** Redeem a decrypted unlock token for a session. */
+    exchangeUnlockToken(token: string): Promise<{
+        jwt: string;
+        userId: string;
+    }>;
+    /** Turn the password path off account-wide, so a lost device stops working. */
+    revokeUnlockTokens(jwt: string): Promise<void>;
     revoke(jwt: string): Promise<void>;
     hasRecoveryBackup(jwt: string): Promise<boolean>;
     getRecoveryBackup(jwt: string): Promise<{
@@ -715,6 +755,17 @@ interface SocialConfig {
      */
     kingsChatScopes?: string[];
     promptPin?: () => Promise<string>;
+    /**
+     * Called when the SDK needs the device unlock password — to choose one
+     * (`kind: 'set'`, ask twice) or to enter it (`kind: 'unlock'`).
+     *
+     * Required on any device using "unlock with your password". Unlike promptPin,
+     * this secret can open a session on its own, so never log or persist it and
+     * let a password manager fill it.
+     */
+    promptUnlockPassword?: (ctx: {
+        kind: 'set' | 'unlock';
+    }) => Promise<string>;
     apiBaseUrl?: string;
     chains?: string[];
     rpcUrls?: Record<string, string>;
@@ -977,6 +1028,15 @@ declare class StaleDeviceShareError extends DecaneConnectError {
 declare class PromptPinNotConfiguredError extends DecaneConnectError {
     constructor();
 }
+declare class PromptPasswordNotConfiguredError extends DecaneConnectError {
+    constructor();
+}
+declare class WrongUnlockPasswordError extends DecaneConnectError {
+    constructor();
+}
+declare class UnlockTokenRejectedError extends DecaneConnectError {
+    constructor();
+}
 declare class AttestationError extends DecaneConnectError {
     constructor(msg: string);
 }
@@ -1313,6 +1373,10 @@ declare function useSocialWallet(): {
     getAccessToken: () => string | null;
     hasPasskey: () => Promise<boolean>;
     addPasskey: () => Promise<void>;
+    setUnlockPassword: (password: string) => Promise<void>;
+    canUnlockWithPassword: () => Promise<boolean>;
+    unlockWithPassword: (password: string) => Promise<void>;
+    removeUnlockPassword: () => Promise<void>;
     rotateShares: (opts: {
         password: string;
         passwordHint?: string;
@@ -1409,4 +1473,16 @@ declare function useSignTypedData(): {
     reset: () => 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, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, 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, UserCancelledError, WalletSelector, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, verifyEmailCode };
+declare const MIN_PASSWORD_LENGTH = 12;
+declare class WeakPasswordError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject what cannot carry the weight this secret now bears.
+ *
+ * Intentionally not a strength meter: a score shown to a user is advice, and
+ * this is a floor. Anything above the floor is the user's call.
+ */
+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 };

package/dist/index.d.ts

@@ -104,6 +104,18 @@ interface DecaneConnectConfig {
     apiBaseUrl?: string;
     sessionDurationMinutes?: number;
     promptPin?: () => Promise<string>;
+    /**
+     * Prompts for the device unlock password. Required on any device that has
+     * one — both to set it (`kind: 'set'`, ask twice and confirm) and to use it
+     * (`kind: 'unlock'`).
+     *
+     * Unlike promptPin, this secret can open a session on its own, so treat it
+     * with the care a password deserves: never log it, never persist it, and let
+     * a password manager fill it.
+     */
+    promptUnlockPassword?: (ctx: {
+        kind: 'set' | 'unlock';
+    }) => Promise<string>;
     /**
      * Require a fresh WebAuthn assertion for every signature, instead of letting
      * an unlocked session sign freely until it expires. The TEE session stays
@@ -359,6 +371,18 @@ interface DecaneConnect {
     signInWithPasskey(): Promise<ConnectResult>;
     /** Whether THIS device's share is wrapped by a passkey rather than a PIN. */
     hasPasskey(): Promise<boolean>;
+    /**
+     * Turn on "unlock with your password": re-wraps the device share under the
+     * password and stores an unlock token beside it. Needs a live session.
+     * Throws WeakPasswordError if the password is too weak to carry a session.
+     */
+    setUnlockPassword(password: string): Promise<void>;
+    /** True when this device can open a session from a password alone. */
+    canUnlockWithPassword(): Promise<boolean>;
+    /** Open a session from the password alone — no provider, no passkey. */
+    unlockWithPassword(password: string): Promise<ConnectResult>;
+    /** Turn the password path off, revoking the token account-wide. */
+    removeUnlockPassword(): Promise<void>;
     /**
      * Add a passkey to this device after the fact, re-wrapping its device share
      * under it.
@@ -581,6 +605,22 @@ declare class ApiClient {
      */
     getWebAuthnLoginOptions(userId: string, rpId: string): Promise<_simplewebauthn_browser.PublicKeyCredentialRequestOptionsJSON | null>;
     postWebAuthnLogin(userId: string, response: _simplewebauthn_browser.AuthenticationResponseJSON, origin: string): Promise<AuthResult>;
+    /**
+     * Issue this device an unlock token. Returned in the clear once and never
+     * again — the backend stores only its hash — so the caller must encrypt and
+     * persist it before the value is dropped.
+     */
+    issueUnlockToken(jwt: string): Promise<{
+        token: string;
+        expiresInDays: number;
+    }>;
+    /** Redeem a decrypted unlock token for a session. */
+    exchangeUnlockToken(token: string): Promise<{
+        jwt: string;
+        userId: string;
+    }>;
+    /** Turn the password path off account-wide, so a lost device stops working. */
+    revokeUnlockTokens(jwt: string): Promise<void>;
     revoke(jwt: string): Promise<void>;
     hasRecoveryBackup(jwt: string): Promise<boolean>;
     getRecoveryBackup(jwt: string): Promise<{
@@ -715,6 +755,17 @@ interface SocialConfig {
      */
     kingsChatScopes?: string[];
     promptPin?: () => Promise<string>;
+    /**
+     * Called when the SDK needs the device unlock password — to choose one
+     * (`kind: 'set'`, ask twice) or to enter it (`kind: 'unlock'`).
+     *
+     * Required on any device using "unlock with your password". Unlike promptPin,
+     * this secret can open a session on its own, so never log or persist it and
+     * let a password manager fill it.
+     */
+    promptUnlockPassword?: (ctx: {
+        kind: 'set' | 'unlock';
+    }) => Promise<string>;
     apiBaseUrl?: string;
     chains?: string[];
     rpcUrls?: Record<string, string>;
@@ -977,6 +1028,15 @@ declare class StaleDeviceShareError extends DecaneConnectError {
 declare class PromptPinNotConfiguredError extends DecaneConnectError {
     constructor();
 }
+declare class PromptPasswordNotConfiguredError extends DecaneConnectError {
+    constructor();
+}
+declare class WrongUnlockPasswordError extends DecaneConnectError {
+    constructor();
+}
+declare class UnlockTokenRejectedError extends DecaneConnectError {
+    constructor();
+}
 declare class AttestationError extends DecaneConnectError {
     constructor(msg: string);
 }
@@ -1313,6 +1373,10 @@ declare function useSocialWallet(): {
     getAccessToken: () => string | null;
     hasPasskey: () => Promise<boolean>;
     addPasskey: () => Promise<void>;
+    setUnlockPassword: (password: string) => Promise<void>;
+    canUnlockWithPassword: () => Promise<boolean>;
+    unlockWithPassword: (password: string) => Promise<void>;
+    removeUnlockPassword: () => Promise<void>;
     rotateShares: (opts: {
         password: string;
         passwordHint?: string;
@@ -1409,4 +1473,16 @@ declare function useSignTypedData(): {
     reset: () => 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, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, 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, UserCancelledError, WalletSelector, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, createDecane, createDecaneConnect, createEthereumProvider, loginWithKingsChatPopup, startEmailAuth, useChainSwitch, useDecane, useEthereumProvider, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialBalance, useSocialWallet, useWalletSelector, verifyEmailCode };
+declare const MIN_PASSWORD_LENGTH = 12;
+declare class WeakPasswordError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject what cannot carry the weight this secret now bears.
+ *
+ * Intentionally not a strength meter: a score shown to a user is advice, and
+ * this is a floor. Anything above the floor is the user's call.
+ */
+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 };