@kingdomchain/wallet-client 0.4.1 → 0.4.3

package/README.md

@@ -1,130 +1,130 @@
-# Kingdom Chain TypeScript / CosmJS client
-
-Self-contained TypeScript package for constructing, signing, and broadcasting Kingdom Chain transactions via [CosmJS](https://github.com/cosmos/cosm-js). Includes a Keplr / Leap / Cosmostation browser wallet connector for non-custodial signing.
-
-## Scope (current)
-
-- **MsgSubmitApplication** (citizenship application)
-- **MsgSubmitRecoveryAttestation** (wallet recovery attestation)
-- **Browser wallet connector** (`src/browserSigner.ts`) — Keplr / Leap / Cosmostation via `experimentalSuggestChain` + `OfflineDirectSigner`
-- **WalletConnect mobile signer** (`src/walletConnectSigner.ts`) — WalletConnect v2 `OfflineDirectSigner` adapter
-- **Embedded passkey wallet** (`src/embeddedWallet/`) — WebAuthn PRF + PBKDF2 fallback, IndexedDB vault, mandatory backup gate
-- Ed25519 attestation signing ported from `x/compliance/types/attestation.go`
-- Proto codegen via `ts-proto` + `buf`
-
-## Setup
-
-```bash
-cd clients/ts
-npm install
-npm run codegen   # regenerate from ../../proto (requires buf + repo root)
-```
-
-## Testing
-
-```bash
-cd clients/ts
-npm test              # unit + property fuzz (1500 cross-lang iterations)
-npm run test:mutate   # Stryker mutation testing on attestation.ts + registry.ts
-```
-
-Cross-language fuzz compares TS `attestationSignPayload` against a compiled Go helper (`payload_attestation.go`) for 1000 citizenship + 500 recovery inputs.
-
-## Live E2E (Ona devnet)
-
-Requires a running node at `~/.kingdomchain-e2e` (see `scripts/citizen-compliance-e2e/run.sh`).
-
-```bash
-# Build CLI if needed
-go build -o /tmp/kingdomchaind ./cmd/kingdomchaind
-
-cd clients/ts
-npm run e2e:submit-application
-npm run e2e:submit-recovery
-```
-
-Environment overrides:
-
-| Variable | Default |
-|----------|---------|
-| `CHAIN_ID` | `kingdomchain-e2e` |
-| `RPC_URL` | `http://127.0.0.1:26657` |
-| `REST_URL` | `http://127.0.0.1:1317` |
-| `HOME_DIR` | `~/.kingdomchain-e2e` |
-| `KINGDOMCHAIND` | `/tmp/kingdomchaind` |
-| `PROVIDER_SEED_HEX` | devnet provider-alpha seed from e2e script |
-
-## Browser wallet demo (Keplr / Leap)
-
-Manual click-through demo for Isa — **not automated in CI**. Unit tests mock `window.keplr` / `window.leap`; the demo requires a real extension in your browser.
-
-1. Start the Ona devnet (`scripts/citizen-compliance-e2e/run.sh` or your existing node).
-2. Fund the Keplr/Leap account you will connect with (`ukdr` on `kingdomchain-e2e`).
-3. From `clients/ts`:
-
-```bash
-npm run demo
-```
-
-4. Open the printed URL (default `http://localhost:5173`) in a browser with Keplr or Leap installed.
-5. Click **Connect Keplr** or **Connect Leap**, approve the chain suggestion + connection, then **Submit test application**.
-
-Optional Vite env overrides (prefix `VITE_`):
-
-| Variable | Default |
-|----------|---------|
-| `VITE_CHAIN_ID` | `kingdomchain-e2e` |
-| `VITE_RPC_URL` | `http://127.0.0.1:26657` |
-| `VITE_REST_URL` | `http://127.0.0.1:1317` |
-| `VITE_PROVIDER_ID` | `provider-alpha` |
-| `VITE_POLICY_VERSION` | `policy-v1` |
-| `VITE_PROVIDER_SEED_HEX` | devnet provider-alpha seed |
-
-The demo signs the provider attestation off-chain (devnet seed) and broadcasts `MsgSubmitApplication` using your connected wallet as the on-chain tx signer.
-
-## Kingdom OS / Base44 reference wiring
-
-Copy-paste React integration lives in `clients/kingdom-os-reference/`:
-
-- `useKingdomWallet.js` — unified hook for Keplr, Leap, Cosmostation, WalletConnect, embedded passkey
-- `WalletStep.jsx` — onboarding UI with side-by-side connect buttons
-- `WalletConnectQrModal.jsx` — QR pairing modal (`VITE_WC_PROJECT_ID` required)
-- `EmbeddedWalletPanel.jsx` — create / unlock / mandatory backup gate
-
-See `clients/kingdom-os-reference/README.md` for env vars and usage.
-
-### Embedded wallet API (`src/embeddedWallet/`)
-
-- `createEmbeddedWallet({ userId, userName, displayName, rpId? })` — register passkey + encrypt vault in IndexedDB
-- `unlockEmbeddedWallet()` — passkey assertion → in-memory session
-- `getEmbeddedOfflineSigner()` — CosmJS signer; throws `EmbeddedWalletBackupRequiredError` until backup acknowledged
-- `acknowledgeEmbeddedBackup()` / `downloadEmbeddedBackupFile()` — mandatory backup gate
-- `importEmbeddedBackup(json)` — restore vault from user-held backup file
-- `hasEmbeddedWallet()` / `clearEmbeddedWallet()` — lifecycle helpers
-
-KDF selection: WebAuthn PRF when available, PBKDF2-passkey fallback (310k iterations — bump to 600k+ before production).
-
-**Recovery gap (phase 3):** The encrypted backup file requires the original passkey to decrypt. Option D (BIP39 mnemonic export for passkey loss without iCloud/Google sync) is approved in the ADR but **not implemented in phase 2** — see `docs/architecture/ADR-EMBEDDED-WALLET-ONBOARDING.md` § "Known gap: Option D mnemonic recovery".
-
-### WalletConnect API (`src/walletConnectSigner.ts`)
-
-- `initWalletConnectClient({ chainId, projectId, metadata })`
-- `connectWalletConnect(client, chainId)` → `{ uri, session, signer }` (display `uri` as QR)
-- `restoreWalletConnectSession(client, chainId)` — reconnect on page load
-- `createWalletConnectOfflineSigner(client, session, chainId)`
-- `disconnectWalletConnect(client, session)`
-
-### Browser wallet API (`src/browserSigner.ts`)
-
-- `isKeplrAvailable()` / `isLeapAvailable()`
-- `buildKingdomChainInfo(chainId, rpcUrl, restUrl)` — `ukdr` / KDR with **6 decimals** (`x/supply/types/constants.go`, `TOKENOMICS_COSMOS_SPEC.md`), bech32 prefix `king`, coin type 118
-- `connectKeplr(chainInfo)` / `connectLeap(chainInfo)` — suggest chain + enable + offline signer
-- `createBrowserSigningClient(rpcUrl, signer)` — `SigningStargateClient` + `createKingdomChainRegistry()`
-
-## Encoding notes (for Base44 frontend)
-
-1. **Custom protobuf registry** — CosmJS `SigningStargateClient` must be constructed with a `Registry` that includes Kingdom Chain message type URLs (e.g. `/isatheword.kingdomchain.compliance.v1.MsgSubmitApplication`) alongside `defaultRegistryTypes`.
-2. **Attestation signing is off-chain** — providers sign a canonical SHA256-payload (not the tx bytes). The TS port in `src/attestation.ts` must match Go `AttestationSignPayload` exactly; the E2E script cross-checks against `scripts/citizen-compliance-e2e/sign_attestation.go`.
-3. **Timestamps** — proto `google.protobuf.Timestamp` fields (`issued_at`, `expires_at`) are `Date` in generated TS; encoding uses `@bufbuild/protobuf` wire format.
-4. **Uint64 fields** — `provider_key_version` is `bigint` in generated types.
-5. **Tx signer** — `MsgSubmitApplication` signer is `applicant_wallet`; the fee payer / signer must be the applicant's secp256k1 account (`king` bech32 prefix, coin type 118).
+# Kingdom Chain TypeScript / CosmJS client
+
+Self-contained TypeScript package for constructing, signing, and broadcasting Kingdom Chain transactions via [CosmJS](https://github.com/cosmos/cosm-js). Includes a Keplr / Leap / Cosmostation browser wallet connector for non-custodial signing.
+
+## Scope (current)
+
+- **MsgSubmitApplication** (citizenship application)
+- **MsgSubmitRecoveryAttestation** (wallet recovery attestation)
+- **Browser wallet connector** (`src/browserSigner.ts`) — Keplr / Leap / Cosmostation via `experimentalSuggestChain` + `OfflineDirectSigner`
+- **WalletConnect mobile signer** (`src/walletConnectSigner.ts`) — WalletConnect v2 `OfflineDirectSigner` adapter
+- **Embedded passkey wallet** (`src/embeddedWallet/`) — WebAuthn PRF + PBKDF2 fallback, IndexedDB vault, mandatory backup gate
+- Ed25519 attestation signing ported from `x/compliance/types/attestation.go`
+- Proto codegen via `ts-proto` + `buf`
+
+## Setup
+
+```bash
+cd clients/ts
+npm install
+npm run codegen   # regenerate from ../../proto (requires buf + repo root)
+```
+
+## Testing
+
+```bash
+cd clients/ts
+npm test              # unit + property fuzz (1500 cross-lang iterations)
+npm run test:mutate   # Stryker mutation testing on attestation.ts + registry.ts
+```
+
+Cross-language fuzz compares TS `attestationSignPayload` against a compiled Go helper (`payload_attestation.go`) for 1000 citizenship + 500 recovery inputs.
+
+## Live E2E (Ona devnet)
+
+Requires a running node at `~/.kingdomchain-e2e` (see `scripts/citizen-compliance-e2e/run.sh`).
+
+```bash
+# Build CLI if needed
+go build -o /tmp/kingdomchaind ./cmd/kingdomchaind
+
+cd clients/ts
+npm run e2e:submit-application
+npm run e2e:submit-recovery
+```
+
+Environment overrides:
+
+| Variable | Default |
+|----------|---------|
+| `CHAIN_ID` | `kingdomchain-e2e` |
+| `RPC_URL` | `http://127.0.0.1:26657` |
+| `REST_URL` | `http://127.0.0.1:1317` |
+| `HOME_DIR` | `~/.kingdomchain-e2e` |
+| `KINGDOMCHAIND` | `/tmp/kingdomchaind` |
+| `PROVIDER_SEED_HEX` | devnet provider-alpha seed from e2e script |
+
+## Browser wallet demo (Keplr / Leap)
+
+Manual click-through demo for Isa — **not automated in CI**. Unit tests mock `window.keplr` / `window.leap`; the demo requires a real extension in your browser.
+
+1. Start the Ona devnet (`scripts/citizen-compliance-e2e/run.sh` or your existing node).
+2. Fund the Keplr/Leap account you will connect with (`ukdr` on `kingdomchain-e2e`).
+3. From `clients/ts`:
+
+```bash
+npm run demo
+```
+
+4. Open the printed URL (default `http://localhost:5173`) in a browser with Keplr or Leap installed.
+5. Click **Connect Keplr** or **Connect Leap**, approve the chain suggestion + connection, then **Submit test application**.
+
+Optional Vite env overrides (prefix `VITE_`):
+
+| Variable | Default |
+|----------|---------|
+| `VITE_CHAIN_ID` | `kingdomchain-e2e` |
+| `VITE_RPC_URL` | `http://127.0.0.1:26657` |
+| `VITE_REST_URL` | `http://127.0.0.1:1317` |
+| `VITE_PROVIDER_ID` | `provider-alpha` |
+| `VITE_POLICY_VERSION` | `policy-v1` |
+| `VITE_PROVIDER_SEED_HEX` | devnet provider-alpha seed |
+
+The demo signs the provider attestation off-chain (devnet seed) and broadcasts `MsgSubmitApplication` using your connected wallet as the on-chain tx signer.
+
+## Kingdom OS / Base44 reference wiring
+
+Copy-paste React integration lives in `clients/kingdom-os-reference/`:
+
+- `useKingdomWallet.js` — unified hook for Keplr, Leap, Cosmostation, WalletConnect, embedded passkey
+- `WalletStep.jsx` — onboarding UI with side-by-side connect buttons
+- `WalletConnectQrModal.jsx` — QR pairing modal (`VITE_WC_PROJECT_ID` required)
+- `EmbeddedWalletPanel.jsx` — create / unlock / mandatory backup gate
+
+See `clients/kingdom-os-reference/README.md` for env vars and usage.
+
+### Embedded wallet API (`src/embeddedWallet/`)
+
+- `createEmbeddedWallet({ userId, userName, displayName, rpId? })` — register passkey + encrypt vault in IndexedDB
+- `unlockEmbeddedWallet()` — passkey assertion → in-memory session
+- `getEmbeddedOfflineSigner()` — CosmJS signer; throws `EmbeddedWalletBackupRequiredError` until backup acknowledged
+- `acknowledgeEmbeddedBackup()` / `downloadEmbeddedBackupFile()` — mandatory backup gate
+- `importEmbeddedBackup(json)` — restore vault from user-held backup file
+- `hasEmbeddedWallet()` / `clearEmbeddedWallet()` — lifecycle helpers
+
+KDF selection: WebAuthn PRF when available, PBKDF2-passkey fallback (310k iterations — bump to 600k+ before production).
+
+**Recovery gap (phase 3):** The encrypted backup file requires the original passkey to decrypt. Option D (BIP39 mnemonic export for passkey loss without iCloud/Google sync) is approved in the ADR but **not implemented in phase 2** — see `docs/architecture/ADR-EMBEDDED-WALLET-ONBOARDING.md` § "Known gap: Option D mnemonic recovery".
+
+### WalletConnect API (`src/walletConnectSigner.ts`)
+
+- `initWalletConnectClient({ chainId, projectId, metadata })`
+- `connectWalletConnect(client, chainId)` → `{ uri, session, signer }` (display `uri` as QR)
+- `restoreWalletConnectSession(client, chainId)` — reconnect on page load
+- `createWalletConnectOfflineSigner(client, session, chainId)`
+- `disconnectWalletConnect(client, session)`
+
+### Browser wallet API (`src/browserSigner.ts`)
+
+- `isKeplrAvailable()` / `isLeapAvailable()`
+- `buildKingdomChainInfo(chainId, rpcUrl, restUrl)` — `ukdr` / KDR with **6 decimals** (`x/supply/types/constants.go`, `TOKENOMICS_COSMOS_SPEC.md`), bech32 prefix `king`, coin type 118
+- `connectKeplr(chainInfo)` / `connectLeap(chainInfo)` — suggest chain + enable + offline signer
+- `createBrowserSigningClient(rpcUrl, signer)` — `SigningStargateClient` + `createKingdomChainRegistry()`
+
+## Encoding notes (for Base44 frontend)
+
+1. **Custom protobuf registry** — CosmJS `SigningStargateClient` must be constructed with a `Registry` that includes Kingdom Chain message type URLs (e.g. `/isatheword.kingdomchain.compliance.v1.MsgSubmitApplication`) alongside `defaultRegistryTypes`.
+2. **Attestation signing is off-chain** — providers sign a canonical SHA256-payload (not the tx bytes). The TS port in `src/attestation.ts` must match Go `AttestationSignPayload` exactly; the E2E script cross-checks against `scripts/citizen-compliance-e2e/sign_attestation.go`.
+3. **Timestamps** — proto `google.protobuf.Timestamp` fields (`issued_at`, `expires_at`) are `Date` in generated TS; encoding uses `@bufbuild/protobuf` wire format.
+4. **Uint64 fields** — `provider_key_version` is `bigint` in generated types.
+5. **Tx signer** — `MsgSubmitApplication` signer is `applicant_wallet`; the fee payer / signer must be the applicant's secp256k1 account (`king` bech32 prefix, coin type 118).

package/dist/index.d.ts

@@ -301,6 +301,11 @@ declare class EmbeddedWalletBackupRequiredError extends Error {
 declare class EmbeddedWalletVaultError extends Error {
     constructor(message: string, cause?: unknown);
 }
+/** Thrown when AES-GCM decryption fails (wrong KEK or tampered ciphertext). */
+declare class EmbeddedWalletDecryptError extends EmbeddedWalletVaultError {
+    readonly code: "decrypt_failed";
+    constructor(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. */
@@ -402,14 +407,21 @@ declare function decodeCredentialId(encoded: string): Uint8Array;
 declare function embeddedPlaintextToSigner(plaintext: EmbeddedWalletPlaintext, prefix?: string): Promise<DirectSecp256k1Wallet>;
 declare function defaultEmbeddedHdPath(): string;
 
+/** Legacy unscoped vault key used before per-account scoping shipped. */
+declare const VAULT_LEGACY_KEY = "primary";
+interface VaultStorageOptions {
+    /** When set, vault is stored under this account-scoped key instead of {@link VAULT_LEGACY_KEY}. */
+    scopeId?: 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 resolveVaultStorageKey(scopeId?: string): string;
+declare function saveVaultToIndexedDb(vault: EmbeddedWalletVaultV1, options?: VaultStorageOptions): Promise<void>;
+declare function loadVaultFromIndexedDb(options?: VaultStorageOptions): Promise<EmbeddedWalletVaultV1 | null>;
+declare function clearVaultFromIndexedDb(options?: VaultStorageOptions): 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>;
@@ -420,6 +432,8 @@ declare const PASSCODE_LOCKOUT_FAILURE_THRESHOLD = 5;
 declare const PASSCODE_LOCKOUT_INITIAL_MS = 30000;
 /** Maximum lockout duration (15 minutes). */
 declare const PASSCODE_LOCKOUT_MAX_MS = 900000;
+/** Pure lockout duration for a tier (exported for property tests). */
+declare function computePasscodeLockoutDurationMs(tier: number): number;
 /** 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. */
@@ -429,8 +443,6 @@ declare function recordPasscodeUnlockSuccess(publicAddress: string): Promise<voi
 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;
@@ -453,8 +465,8 @@ declare const EMBEDDED_WALLET_PASSCODE_MAX_LENGTH = 128;
  * 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;
+/** Passkey PBKDF2 fallback iteration count (matches PIN path; OWASP 2023 guidance). */
+declare const EMBEDDED_WALLET_PASSKEY_PBKDF2_ITERATIONS = 600000;
 declare function normalizePasscode(passcode: string): string;
 /** Validate citizen-chosen passcode before KDF. */
 declare function assertValidPasscode(passcode: string): void;
@@ -479,16 +491,20 @@ declare function recoveryMnemonicAddress(mnemonic: string, keyType: EmbeddedWall
 /** Build the recovery phrase for an unlocked plaintext payload. */
 declare function recoveryMnemonicFromPlaintext(plaintext: EmbeddedWalletPlaintext): string;
 
-interface CreateEmbeddedWalletOptions {
+interface EmbeddedWalletScopeOptions {
+    /** Supabase user id or other account key — scopes IndexedDB vault storage per account. */
+    scopeId?: string;
+}
+interface CreateEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
     passcode: string;
 }
-interface UnlockEmbeddedWalletOptions {
+interface UnlockEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
     passcode?: string;
 }
-interface RevealEmbeddedRecoveryPhraseOptions {
+interface RevealEmbeddedRecoveryPhraseOptions extends EmbeddedWalletScopeOptions {
     passcode?: string;
 }
-interface RecoverEmbeddedWalletOptions {
+interface RecoverEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
     passcode: string;
     mnemonic: string;
     /** When omitted, inferred from expectedAddress or defaults to hd-derived. */
@@ -499,13 +515,25 @@ interface RecoverEmbeddedWalletOptions {
     /** When true, replaces an existing vault on this device (e.g. after device loss). */
     replaceExisting?: boolean;
 }
-interface EnableEmbeddedPasskeyUnlockOptions {
+interface EnableEmbeddedPasskeyUnlockOptions extends EmbeddedWalletScopeOptions {
     passcode: string;
     userId: Uint8Array;
     userName: string;
     displayName: string;
     rpId?: string;
 }
+interface MigrateLegacyEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
+    scopeId: string;
+    passcode?: string;
+}
+interface ImportEmbeddedBackupOptions extends EmbeddedWalletScopeOptions {
+    /** When true, replaces an existing vault on this device (e.g. intentional restore). */
+    replaceExisting?: boolean;
+}
+interface ClearEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
+}
+interface AcknowledgeEmbeddedBackupOptions extends EmbeddedWalletScopeOptions {
+}
 interface EmbeddedWalletSession {
     address: string;
     vault: EmbeddedWalletVaultV1;
@@ -513,8 +541,15 @@ interface EmbeddedWalletSession {
 }
 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>;
+/** Returns true if an encrypted vault exists under the given scope (not the legacy key). */
+declare function hasEmbeddedWallet(options?: EmbeddedWalletScopeOptions): Promise<boolean>;
+/** Returns true if an unscoped legacy vault still exists under the "primary" key. */
+declare function hasLegacyEmbeddedWallet(): Promise<boolean>;
+/**
+ * Verify ownership of a legacy "primary" vault, copy it to a scoped key, and remove the legacy entry.
+ * Does not run automatically — callers must confirm with the user first.
+ */
+declare function migrateLegacyEmbeddedWallet(options: MigrateLegacyEmbeddedWalletOptions): Promise<EmbeddedWalletSession>;
 /** Create passcode-protected encrypted vault; does not unlock signer until backup is acknowledged. */
 declare function createEmbeddedWallet(options: CreateEmbeddedWalletOptions): Promise<{
     address: string;
@@ -551,11 +586,11 @@ declare function getEmbeddedWalletSession(): EmbeddedWalletSession | null;
 /** Offline signer for CosmJS; enforces backup gate before signing. */
 declare function getEmbeddedOfflineSigner(): OfflineDirectSigner;
 /** Mark backup downloaded/acknowledged and persist. Returns backup file payload. */
-declare function acknowledgeEmbeddedBackup(): Promise<EmbeddedWalletBackupFileV1>;
+declare function acknowledgeEmbeddedBackup(options?: AcknowledgeEmbeddedBackupOptions): Promise<EmbeddedWalletBackupFileV1>;
 declare function downloadEmbeddedBackupFile(backup: EmbeddedWalletBackupFileV1, filename?: string): void;
 /** 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>;
+declare function importEmbeddedBackup(json: string, options?: ImportEmbeddedBackupOptions): Promise<EmbeddedWalletVaultV1>;
+declare function clearEmbeddedWallet(options?: ClearEmbeddedWalletOptions): Promise<void>;
 
 /**
  * Kingdom Chain on-chain denom and display metadata.
@@ -599,4 +634,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_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 };
+export { ATTESTATION_TYPE_CITIZENSHIP_APPLICATION, ATTESTATION_TYPE_RECOVERY, type AcknowledgeEmbeddedBackupOptions, ApplicationStatus, type AttestationPayloadInput, BECH32_PREFIX, type BrowserWalletApi, CHAIN_COIN_TYPE, type ChainCurrency, type ChainInfo, type ClearEmbeddedWalletOptions, 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, EmbeddedWalletDecryptError, type EmbeddedWalletKdf, type EmbeddedWalletKeyType, EmbeddedWalletLockoutError, type EmbeddedWalletPlaintext, type EmbeddedWalletRecoveryPhraseReveal, type EmbeddedWalletRecoveryPhraseWarning, type EmbeddedWalletScopeOptions, type EmbeddedWalletSession, EmbeddedWalletVaultError, type EmbeddedWalletVaultV1, EmbeddedWalletWeakPasscodeError, type EnableEmbeddedPasskeyUnlockOptions, type EncryptWalletOptions, type ImportEmbeddedBackupOptions, InvalidChainConfigError, type MigrateLegacyEmbeddedWalletOptions, 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, VAULT_LEGACY_KEY, type VaultStorageOptions, 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, clearPasscodeLockoutRecord, clearVaultFromIndexedDb, computePasscodeLockoutDurationMs, 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, hasLegacyEmbeddedWallet, hasMixedCharacterClasses, importEmbeddedBackup, initWalletConnectClient, isCosmostationAvailable, isKeplrAvailable, isLeapAvailable, loadPasscodeLockoutRecord, loadVaultFromIndexedDb, lockEmbeddedWallet, markVaultBackupAcknowledged, migrateLegacyEmbeddedWallet, normalizePasscode, normalizeRecoveryMnemonic, parseEncryptedBackup, parseWalletConnectAccount, plaintextFromRecoveryMnemonic, providerSeedFromHex, publicKeyFromPrivateSeed, readPrfOutput, recordPasscodeUnlockFailure, recordPasscodeUnlockSuccess, recoverEmbeddedWalletFromMnemonic, recoveryMnemonicAddress, recoveryMnemonicFromPlaintext, registerPasskey, resolvePlaintextKeyType, resolveVaultStorageKey, restoreWalletConnectSession, revealEmbeddedRecoveryPhrase, savePasscodeLockoutRecord, saveVaultToIndexedDb, selectEmbeddedWalletKdf, serializeBackupFile, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, toWalletConnectCosmosChainId, unlockEmbeddedWallet, validateChainConfig, vaultUsesPasscodeUnlock, vaultUsesPasskeyUnlock };