decane-connect-kit 2.10.0 → 2.12.0

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<{
@@ -977,6 +1017,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);
 }
@@ -1126,9 +1175,14 @@ interface SocialAuthState {
      * Who the provider said the user is — `{ name?, email?, picture? }`.
      *
      * `null` until a sign-in returns one, and stays null for email sign-in and
-     * for providers the user withheld a profile from. It is not persisted across
-     * reloads: the backend stores no profile, so a restored session has an
-     * address but no name. Copy it somewhere durable if you need it to survive.
+     * for providers the user withheld a profile from.
+     *
+     * The backend stores no profile, so this cannot be re-fetched — but whatever
+     * a sign-in does reveal is kept beside this device's share, and a passkey
+     * login hands it back. A passkey sign-in therefore carries the same name and
+     * email the original Google sign-in did. A session merely restored from a
+     * reload still has an address and no name, so copy it somewhere durable if
+     * you need it in that state.
      */
     profile: AuthProfile | null;
     isUnlocked: boolean;
@@ -1222,6 +1276,7 @@ declare function useSocialAuth(): {
     } | null;
     sessionExpiresAt: number | null;
     canUsePasskey: boolean;
+    profile: AuthProfile | null;
     phase: "creating" | "unlocking" | null;
     isCreatingWallet: boolean;
     needsReconnect: boolean;
@@ -1307,6 +1362,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;
@@ -1403,4 +1462,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<{
@@ -977,6 +1017,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);
 }
@@ -1126,9 +1175,14 @@ interface SocialAuthState {
      * Who the provider said the user is — `{ name?, email?, picture? }`.
      *
      * `null` until a sign-in returns one, and stays null for email sign-in and
-     * for providers the user withheld a profile from. It is not persisted across
-     * reloads: the backend stores no profile, so a restored session has an
-     * address but no name. Copy it somewhere durable if you need it to survive.
+     * for providers the user withheld a profile from.
+     *
+     * The backend stores no profile, so this cannot be re-fetched — but whatever
+     * a sign-in does reveal is kept beside this device's share, and a passkey
+     * login hands it back. A passkey sign-in therefore carries the same name and
+     * email the original Google sign-in did. A session merely restored from a
+     * reload still has an address and no name, so copy it somewhere durable if
+     * you need it in that state.
      */
     profile: AuthProfile | null;
     isUnlocked: boolean;
@@ -1222,6 +1276,7 @@ declare function useSocialAuth(): {
     } | null;
     sessionExpiresAt: number | null;
     canUsePasskey: boolean;
+    profile: AuthProfile | null;
     phase: "creating" | "unlocking" | null;
     isCreatingWallet: boolean;
     needsReconnect: boolean;
@@ -1307,6 +1362,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;
@@ -1403,4 +1462,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 };