@kingdomchain/wallet-client 0.2.0 → 0.4.1

package/dist/index.d.ts

@@ -240,12 +240,35 @@ declare function restoreWalletConnectSession(client: SignClient, chainId: string
 declare const EMBEDDED_WALLET_VAULT_VERSION = 1;
 declare const EMBEDDED_WALLET_KDF_PRF: "webauthn-prf";
 declare const EMBEDDED_WALLET_KDF_PBKDF2: "pbkdf2-passkey";
-type EmbeddedWalletKdf = typeof EMBEDDED_WALLET_KDF_PRF | typeof EMBEDDED_WALLET_KDF_PBKDF2;
+declare const EMBEDDED_WALLET_KDF_PIN: "pbkdf2-pin";
+type EmbeddedWalletKdf = typeof EMBEDDED_WALLET_KDF_PRF | typeof EMBEDDED_WALLET_KDF_PBKDF2 | typeof EMBEDDED_WALLET_KDF_PIN;
+/** How the wallet key relates to its recovery phrase. */
+declare const EMBEDDED_WALLET_KEY_HD_DERIVED: "hd-derived";
+declare const EMBEDDED_WALLET_KEY_DIRECT_ENTROPY: "direct-entropy";
+type EmbeddedWalletKeyType = typeof EMBEDDED_WALLET_KEY_HD_DERIVED | typeof EMBEDDED_WALLET_KEY_DIRECT_ENTROPY;
 /** Plaintext wallet payload — never persisted unencrypted. */
 interface EmbeddedWalletPlaintext {
     privateKey: Uint8Array;
     hdPath: string;
     createdAt: string;
+    /** Omitted in pre-phase-3 vaults; treated as direct-entropy when absent. */
+    keyType?: EmbeddedWalletKeyType;
+    /** Stored for hd-derived wallets so the phrase can be revealed later. */
+    mnemonic?: string;
+}
+/** Warnings shown before revealing a recovery phrase. */
+interface EmbeddedWalletRecoveryPhraseWarning {
+    id: "general" | "direct-entropy-portability";
+    title: string;
+    body: string;
+}
+declare const EMBEDDED_WALLET_RECOVERY_PHRASE_GENERAL_WARNING: EmbeddedWalletRecoveryPhraseWarning;
+declare const EMBEDDED_WALLET_RECOVERY_PHRASE_DIRECT_ENTROPY_WARNING: EmbeddedWalletRecoveryPhraseWarning;
+interface EmbeddedWalletRecoveryPhraseReveal {
+    mnemonic: string;
+    keyType: EmbeddedWalletKeyType;
+    address: string;
+    warnings: EmbeddedWalletRecoveryPhraseWarning[];
 }
 /** Encrypted vault stored in IndexedDB and exported backup files. */
 interface EmbeddedWalletVaultV1 {
@@ -278,16 +301,30 @@ declare class EmbeddedWalletBackupRequiredError extends Error {
 declare class EmbeddedWalletVaultError extends Error {
     constructor(message: string, cause?: unknown);
 }
+type PasscodeStrengthLabel = "weak" | "fair" | "good" | "strong";
+type PasscodeBlockReason = "denylist" | "too_weak" | "numeric_short";
+/** Thrown when too many failed passcode unlock attempts trigger a timed lockout. */
+declare class EmbeddedWalletLockoutError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+/** Thrown when a passcode is too weak or on the common-password denylist. */
+declare class EmbeddedWalletWeakPasscodeError extends Error {
+    readonly reason: PasscodeBlockReason;
+    constructor(reason: PasscodeBlockReason);
+}
 
 interface EncryptWalletOptions {
     kdf: EmbeddedWalletKdf;
     credentialId: Uint8Array;
     publicAddress: string;
     kek: Uint8Array;
-    /** Required when kdf=pbkdf2-passkey */
+    /** Required when kdf=pbkdf2-passkey or kdf=pbkdf2-pin */
     kdfSalt?: Uint8Array;
     /** Required when kdf=webauthn-prf */
     prfSalt?: Uint8Array;
+    /** Override PBKDF2 iterations (defaults vary by kdf type). */
+    kdfIterations?: number;
     backupAcknowledged?: boolean;
 }
 declare function deriveKekFromPrf(prfOutput: Uint8Array): Promise<Uint8Array>;
@@ -365,11 +402,105 @@ declare function decodeCredentialId(encoded: string): Uint8Array;
 declare function embeddedPlaintextToSigner(plaintext: EmbeddedWalletPlaintext, prefix?: string): Promise<DirectSecp256k1Wallet>;
 declare function defaultEmbeddedHdPath(): string;
 
+interface PasscodeLockoutRecord {
+    failedAttempts: number;
+    lockoutTier: number;
+    lockedUntil: string | null;
+}
 declare function saveVaultToIndexedDb(vault: EmbeddedWalletVaultV1): Promise<void>;
 declare function loadVaultFromIndexedDb(): Promise<EmbeddedWalletVaultV1 | null>;
 declare function clearVaultFromIndexedDb(): Promise<void>;
+declare function loadPasscodeLockoutRecord(publicAddress: string): Promise<PasscodeLockoutRecord | null>;
+declare function savePasscodeLockoutRecord(publicAddress: string, record: PasscodeLockoutRecord): Promise<void>;
+declare function clearPasscodeLockoutRecord(publicAddress: string): Promise<void>;
+
+/** Consecutive wrong passcodes before lockout triggers. */
+declare const PASSCODE_LOCKOUT_FAILURE_THRESHOLD = 5;
+/** First lockout duration (milliseconds). */
+declare const PASSCODE_LOCKOUT_INITIAL_MS = 30000;
+/** Maximum lockout duration (15 minutes). */
+declare const PASSCODE_LOCKOUT_MAX_MS = 900000;
+/** Throws when the vault is temporarily locked after too many failed unlock attempts. */
+declare function assertPasscodeUnlockAllowed(publicAddress: string): Promise<void>;
+/** Record a failed passcode unlock attempt; triggers lockout at threshold. */
+declare function recordPasscodeUnlockFailure(publicAddress: string): Promise<void>;
+/** Clear lockout state after a successful passcode unlock. */
+declare function recordPasscodeUnlockSuccess(publicAddress: string): Promise<void>;
+declare function getPasscodeLockoutState(publicAddress: string): Promise<PasscodeLockoutRecord & {
+    retryAfterMs: number;
+}>;
+/** @internal Test helper — reset lockout without clearing vault. */
+declare function clearPasscodeLockoutForTests(publicAddress: string): Promise<void>;
+
+interface PasscodeStrengthResult {
+    score: 0 | 1 | 2 | 3 | 4;
+    label: PasscodeStrengthLabel;
+    blocked: boolean;
+    blockReason?: "denylist" | "too_weak" | "numeric_short";
+}
+declare function hasMixedCharacterClasses(passcode: string): boolean;
+/** Score passcode strength for creation UI (denylist + zxcvbn). */
+declare function evaluatePasscodeStrength(passcode: string): PasscodeStrengthResult;
+/** Hard reject weak or common passcodes at wallet creation / recovery. */
+declare function assertPasscodeAllowedForCreation(passcode: string): void;
+
+/** Minimum passcode length — alphanumeric passcode, not a 4–6 digit PIN. */
+declare const EMBEDDED_WALLET_PASSCODE_MIN_LENGTH = 8;
+/** Maximum passcode length (DoS guard for PBKDF2 input). */
+declare const EMBEDDED_WALLET_PASSCODE_MAX_LENGTH = 128;
+/**
+ * OWASP-recommended PBKDF2-SHA256 iteration count (2023 guidance).
+ * Uses native Web Crypto — no WASM bundle required.
+ */
+declare const EMBEDDED_WALLET_PIN_PBKDF2_ITERATIONS = 600000;
+/** Legacy passkey PBKDF2 fallback iteration count (pre-PIN vaults). */
+declare const EMBEDDED_WALLET_PASSKEY_PBKDF2_ITERATIONS = 310000;
+declare function normalizePasscode(passcode: string): string;
+/** Validate citizen-chosen passcode before KDF. */
+declare function assertValidPasscode(passcode: string): void;
+declare function deriveKekFromPasscode(passcode: string, salt: Uint8Array, iterations?: number): Promise<Uint8Array>;
+
+/** Normalize user input: trim, lowercase, collapse whitespace. */
+declare function normalizeRecoveryMnemonic(mnemonic: string): string;
+declare function assertValidRecoveryMnemonic(mnemonic: string): void;
+declare function resolvePlaintextKeyType(plaintext: EmbeddedWalletPlaintext): EmbeddedWalletKeyType;
+/** Encode a legacy raw 32-byte key as a 24-word BIP-39 mnemonic (entropy encoding, no HD). */
+declare function encodeDirectEntropyMnemonic(privateKey: Uint8Array): string;
+/** Decode a direct-entropy mnemonic back to the original 32-byte key. */
+declare function decodeDirectEntropyMnemonic(mnemonic: string): Uint8Array;
+declare function derivePrivateKeyFromHdMnemonic(mnemonic: string, hdPath?: string): Promise<Uint8Array>;
+declare function addressFromPrivateKey(privateKey: Uint8Array, prefix?: string): Promise<string>;
+declare function addressFromHdMnemonic(mnemonic: string, hdPath?: string, prefix?: string): Promise<string>;
+declare function createHdDerivedPlaintext(createdAt: string, hdPath?: string): Promise<EmbeddedWalletPlaintext>;
+declare function plaintextFromRecoveryMnemonic(mnemonic: string, keyType: EmbeddedWalletKeyType, createdAt: string, hdPath?: string): Promise<EmbeddedWalletPlaintext>;
+/** Infer key type by matching an expected on-chain address, or default to hd-derived. */
+declare function detectRecoveryMnemonicKeyType(mnemonic: string, expectedAddress: string, hdPath?: string, prefix?: string): Promise<EmbeddedWalletKeyType>;
+declare function recoveryMnemonicAddress(mnemonic: string, keyType: EmbeddedWalletKeyType, hdPath?: string, prefix?: string): Promise<string>;
+/** Build the recovery phrase for an unlocked plaintext payload. */
+declare function recoveryMnemonicFromPlaintext(plaintext: EmbeddedWalletPlaintext): string;
 
 interface CreateEmbeddedWalletOptions {
+    passcode: string;
+}
+interface UnlockEmbeddedWalletOptions {
+    passcode?: string;
+}
+interface RevealEmbeddedRecoveryPhraseOptions {
+    passcode?: string;
+}
+interface RecoverEmbeddedWalletOptions {
+    passcode: string;
+    mnemonic: string;
+    /** When omitted, inferred from expectedAddress or defaults to hd-derived. */
+    keyType?: EmbeddedWalletKeyType;
+    /** Used to auto-detect legacy direct-entropy vs standard HD phrases. */
+    expectedAddress?: string;
+    hdPath?: string;
+    /** When true, replaces an existing vault on this device (e.g. after device loss). */
+    replaceExisting?: boolean;
+}
+interface EnableEmbeddedPasskeyUnlockOptions {
+    passcode: string;
     userId: Uint8Array;
     userName: string;
     displayName: string;
@@ -380,15 +511,40 @@ interface EmbeddedWalletSession {
     vault: EmbeddedWalletVaultV1;
     signer: OfflineDirectSigner;
 }
+declare function vaultUsesPasskeyUnlock(vault: EmbeddedWalletVaultV1): boolean;
+declare function vaultUsesPasscodeUnlock(vault: EmbeddedWalletVaultV1): boolean;
 /** Returns true if an encrypted vault exists in IndexedDB. */
 declare function hasEmbeddedWallet(): Promise<boolean>;
-/** Create passkey + encrypted vault; does not unlock signer until backup is acknowledged. */
+/** Create passcode-protected encrypted vault; does not unlock signer until backup is acknowledged. */
 declare function createEmbeddedWallet(options: CreateEmbeddedWalletOptions): Promise<{
     address: string;
     vault: EmbeddedWalletVaultV1;
 }>;
-/** Unlock existing vault with passkey; requires backup acknowledged for signing. */
-declare function unlockEmbeddedWallet(): Promise<EmbeddedWalletSession>;
+/**
+ * Re-authenticate and return the recovery phrase plus UI warnings.
+ * Call only after showing {@link EMBEDDED_WALLET_RECOVERY_PHRASE_GENERAL_WARNING} (and the
+ * direct-entropy portability warning when applicable).
+ */
+declare function revealEmbeddedRecoveryPhrase(options?: RevealEmbeddedRecoveryPhraseOptions): Promise<EmbeddedWalletRecoveryPhraseReveal>;
+/**
+ * Restore an embedded wallet on a new device from a recovery phrase.
+ * Sets a new passcode and stores an encrypted vault in IndexedDB.
+ */
+declare function recoverEmbeddedWalletFromMnemonic(options: RecoverEmbeddedWalletOptions): Promise<{
+    address: string;
+    vault: EmbeddedWalletVaultV1;
+    keyType: EmbeddedWalletKeyType;
+}>;
+/**
+ * Opt-in upgrade: re-wrap an existing passcode vault with passkey unlock.
+ * Does not change the underlying private key or address.
+ */
+declare function enableEmbeddedPasskeyUnlock(options: EnableEmbeddedPasskeyUnlockOptions): Promise<{
+    address: string;
+    vault: EmbeddedWalletVaultV1;
+}>;
+/** Unlock existing vault with passcode (default) or passkey (opt-in upgrade path). */
+declare function unlockEmbeddedWallet(options?: UnlockEmbeddedWalletOptions): Promise<EmbeddedWalletSession>;
 /** Clear in-memory signer. */
 declare function lockEmbeddedWallet(): void;
 declare function getEmbeddedWalletSession(): EmbeddedWalletSession | null;
@@ -397,7 +553,7 @@ declare function getEmbeddedOfflineSigner(): OfflineDirectSigner;
 /** Mark backup downloaded/acknowledged and persist. Returns backup file payload. */
 declare function acknowledgeEmbeddedBackup(): Promise<EmbeddedWalletBackupFileV1>;
 declare function downloadEmbeddedBackupFile(backup: EmbeddedWalletBackupFileV1, filename?: string): void;
-/** Restore vault from user-held backup file (still requires passkey to decrypt). */
+/** Restore vault from user-held backup file (requires passcode or passkey to decrypt). */
 declare function importEmbeddedBackup(json: string): Promise<EmbeddedWalletVaultV1>;
 declare function clearEmbeddedWallet(): Promise<void>;
 
@@ -443,4 +599,4 @@ declare function signCitizenshipAttestation(params: SubmitApplicationParams): Pr
     input: AttestationPayloadInput;
 }>;
 
-export { ATTESTATION_TYPE_CITIZENSHIP_APPLICATION, ATTESTATION_TYPE_RECOVERY, ApplicationStatus, type AttestationPayloadInput, BECH32_PREFIX, type BrowserWalletApi, CHAIN_COIN_TYPE, type ChainCurrency, type ChainInfo, type CosmostationWindowApi, type CreateEmbeddedWalletOptions, DEFAULT_CHAIN_ID, DEFAULT_REST_URL, DEFAULT_RPC_URL, EMBEDDED_WALLET_KDF_PBKDF2, EMBEDDED_WALLET_KDF_PRF, EMBEDDED_WALLET_VAULT_VERSION, type EmbeddedWalletBackupFileV1, EmbeddedWalletBackupRequiredError, type EmbeddedWalletKdf, type EmbeddedWalletPlaintext, type EmbeddedWalletSession, EmbeddedWalletVaultError, type EmbeddedWalletVaultV1, type EncryptWalletOptions, InvalidChainConfigError, MsgSubmitApplication, MsgSubmitRecoveryAttestation, type PasskeyAssertionResult, type PasskeyRegistrationResult, RecoveryAttestationStatus, RpcConnectionError, type SubmitApplicationParams, UKDR_DECIMALS, UKDR_DISPLAY_DENOM, UKDR_MINIMAL_DENOM, WALLETCONNECT_COSMOS_METHODS, WALLETCONNECT_COSMOS_NAMESPACE, WEBAUTHN_RP_NAME, WalletAccountError, type WalletConnectChainConfig, type WalletConnectConnectResult, type WalletConnectMetadata, WalletConnectNotInitializedError, WalletConnectSessionError, WalletConnectSigningError, WalletConnectionError, WalletConnectionRejectedError, WalletNotInstalledError, type WebAuthnPrfCapabilities, WebAuthnUnavailableError, WebAuthnUserCancelledError, acknowledgeEmbeddedBackup, assertPasskey, assertVaultPermitsTransaction, attestationSignPayload, buildKingdomChainInfo, buildRequiredCosmosNamespaces, buildSubmitApplicationMsg, clearEmbeddedWallet, clearVaultFromIndexedDb, connectCosmostation, connectKeplr, connectLeap, connectWalletConnect, createBrowserSigningClient, createEmbeddedWallet, createKingdomChainRegistry, createPasskeyMaterialFromAssertion, createPbkdf2Salt, createWalletConnectOfflineSigner, decodeCredentialId, decryptWalletPayload, defaultEmbeddedHdPath, deriveKekFromPbkdf2, deriveKekFromPrf, detectWebAuthnPrfCapabilities, disconnectWalletConnect, downloadEmbeddedBackupFile, embeddedPlaintextToSigner, encodeCredentialId, encryptWalletPayload, exportEncryptedBackup, getCosmostationKeplrApi, getEmbeddedOfflineSigner, getEmbeddedWalletSession, hasEmbeddedWallet, importEmbeddedBackup, initWalletConnectClient, isCosmostationAvailable, isKeplrAvailable, isLeapAvailable, loadVaultFromIndexedDb, lockEmbeddedWallet, markVaultBackupAcknowledged, parseEncryptedBackup, parseWalletConnectAccount, providerSeedFromHex, publicKeyFromPrivateSeed, readPrfOutput, registerPasskey, restoreWalletConnectSession, saveVaultToIndexedDb, selectEmbeddedWalletKdf, serializeBackupFile, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, toWalletConnectCosmosChainId, unlockEmbeddedWallet, validateChainConfig };
+export { ATTESTATION_TYPE_CITIZENSHIP_APPLICATION, ATTESTATION_TYPE_RECOVERY, ApplicationStatus, type AttestationPayloadInput, BECH32_PREFIX, type BrowserWalletApi, CHAIN_COIN_TYPE, type ChainCurrency, type ChainInfo, type CosmostationWindowApi, type CreateEmbeddedWalletOptions, DEFAULT_CHAIN_ID, DEFAULT_REST_URL, DEFAULT_RPC_URL, EMBEDDED_WALLET_KDF_PBKDF2, EMBEDDED_WALLET_KDF_PIN, EMBEDDED_WALLET_KDF_PRF, EMBEDDED_WALLET_KEY_DIRECT_ENTROPY, EMBEDDED_WALLET_KEY_HD_DERIVED, EMBEDDED_WALLET_PASSCODE_MAX_LENGTH, EMBEDDED_WALLET_PASSCODE_MIN_LENGTH, EMBEDDED_WALLET_PASSKEY_PBKDF2_ITERATIONS, EMBEDDED_WALLET_PIN_PBKDF2_ITERATIONS, EMBEDDED_WALLET_RECOVERY_PHRASE_DIRECT_ENTROPY_WARNING, EMBEDDED_WALLET_RECOVERY_PHRASE_GENERAL_WARNING, EMBEDDED_WALLET_VAULT_VERSION, type EmbeddedWalletBackupFileV1, EmbeddedWalletBackupRequiredError, type EmbeddedWalletKdf, type EmbeddedWalletKeyType, EmbeddedWalletLockoutError, type EmbeddedWalletPlaintext, type EmbeddedWalletRecoveryPhraseReveal, type EmbeddedWalletRecoveryPhraseWarning, type EmbeddedWalletSession, EmbeddedWalletVaultError, type EmbeddedWalletVaultV1, EmbeddedWalletWeakPasscodeError, type EnableEmbeddedPasskeyUnlockOptions, type EncryptWalletOptions, InvalidChainConfigError, MsgSubmitApplication, MsgSubmitRecoveryAttestation, PASSCODE_LOCKOUT_FAILURE_THRESHOLD, PASSCODE_LOCKOUT_INITIAL_MS, PASSCODE_LOCKOUT_MAX_MS, type PasscodeBlockReason, type PasscodeLockoutRecord, type PasscodeStrengthLabel, type PasscodeStrengthResult, type PasskeyAssertionResult, type PasskeyRegistrationResult, type RecoverEmbeddedWalletOptions, RecoveryAttestationStatus, type RevealEmbeddedRecoveryPhraseOptions, RpcConnectionError, type SubmitApplicationParams, UKDR_DECIMALS, UKDR_DISPLAY_DENOM, UKDR_MINIMAL_DENOM, type UnlockEmbeddedWalletOptions, WALLETCONNECT_COSMOS_METHODS, WALLETCONNECT_COSMOS_NAMESPACE, WEBAUTHN_RP_NAME, WalletAccountError, type WalletConnectChainConfig, type WalletConnectConnectResult, type WalletConnectMetadata, WalletConnectNotInitializedError, WalletConnectSessionError, WalletConnectSigningError, WalletConnectionError, WalletConnectionRejectedError, WalletNotInstalledError, type WebAuthnPrfCapabilities, WebAuthnUnavailableError, WebAuthnUserCancelledError, acknowledgeEmbeddedBackup, addressFromHdMnemonic, addressFromPrivateKey, assertPasscodeAllowedForCreation, assertPasscodeUnlockAllowed, assertPasskey, assertValidPasscode, assertValidRecoveryMnemonic, assertVaultPermitsTransaction, attestationSignPayload, buildKingdomChainInfo, buildRequiredCosmosNamespaces, buildSubmitApplicationMsg, clearEmbeddedWallet, clearPasscodeLockoutForTests, clearPasscodeLockoutRecord, clearVaultFromIndexedDb, connectCosmostation, connectKeplr, connectLeap, connectWalletConnect, createBrowserSigningClient, createEmbeddedWallet, createHdDerivedPlaintext, createKingdomChainRegistry, createPasskeyMaterialFromAssertion, createPbkdf2Salt, createWalletConnectOfflineSigner, decodeCredentialId, decodeDirectEntropyMnemonic, decryptWalletPayload, defaultEmbeddedHdPath, deriveKekFromPasscode, deriveKekFromPbkdf2, deriveKekFromPrf, derivePrivateKeyFromHdMnemonic, detectRecoveryMnemonicKeyType, detectWebAuthnPrfCapabilities, disconnectWalletConnect, downloadEmbeddedBackupFile, embeddedPlaintextToSigner, enableEmbeddedPasskeyUnlock, encodeCredentialId, encodeDirectEntropyMnemonic, encryptWalletPayload, evaluatePasscodeStrength, exportEncryptedBackup, getCosmostationKeplrApi, getEmbeddedOfflineSigner, getEmbeddedWalletSession, getPasscodeLockoutState, hasEmbeddedWallet, hasMixedCharacterClasses, importEmbeddedBackup, initWalletConnectClient, isCosmostationAvailable, isKeplrAvailable, isLeapAvailable, loadPasscodeLockoutRecord, loadVaultFromIndexedDb, lockEmbeddedWallet, markVaultBackupAcknowledged, normalizePasscode, normalizeRecoveryMnemonic, parseEncryptedBackup, parseWalletConnectAccount, plaintextFromRecoveryMnemonic, providerSeedFromHex, publicKeyFromPrivateSeed, readPrfOutput, recordPasscodeUnlockFailure, recordPasscodeUnlockSuccess, recoverEmbeddedWalletFromMnemonic, recoveryMnemonicAddress, recoveryMnemonicFromPlaintext, registerPasskey, resolvePlaintextKeyType, restoreWalletConnectSession, revealEmbeddedRecoveryPhrase, savePasscodeLockoutRecord, saveVaultToIndexedDb, selectEmbeddedWalletKdf, serializeBackupFile, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, toWalletConnectCosmosChainId, unlockEmbeddedWallet, validateChainConfig, vaultUsesPasscodeUnlock, vaultUsesPasskeyUnlock };