@kingdomchain/wallet-client 0.1.0 → 0.4.1

package/README.md

@@ -1,12 +1,14 @@
 # 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 browser wallet connector for non-custodial signing.
+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 via `experimentalSuggestChain` + `OfflineDirectSigner`
+- **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`
 
@@ -80,6 +82,38 @@ Optional Vite env overrides (prefix `VITE_`):
 
 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()`

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { Registry, OfflineDirectSigner, EncodeObject } from '@cosmjs/proto-signing';
+import { Registry, OfflineDirectSigner, DirectSecp256k1Wallet, EncodeObject } from '@cosmjs/proto-signing';
 import { SigningStargateClient } from '@cosmjs/stargate';
+import SignClient from '@walletconnect/sign-client';
+import { SessionTypes, ProposalTypes } from '@walletconnect/types';
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 
 /** Must match x/compliance/types/keys.go AttestationTypeCitizenshipApplication */
@@ -156,25 +158,405 @@ declare class RpcConnectionError extends Error {
     readonly rpcUrl: string;
     constructor(rpcUrl: string, cause?: unknown);
 }
+/** Cosmostation exposes a Keplr-compatible provider at providers.keplr. */
+interface CosmostationWindowApi {
+    providers?: {
+        keplr?: BrowserWalletApi;
+    };
+}
 declare global {
     interface Window {
         keplr?: BrowserWalletApi;
         leap?: BrowserWalletApi;
+        cosmostation?: CosmostationWindowApi;
     }
 }
 /** Validate chain endpoint inputs before passing to Keplr/Leap. */
 declare function validateChainConfig(chainId: string, rpcUrl: string, restUrl: string): void;
 declare function isKeplrAvailable(): boolean;
 declare function isLeapAvailable(): boolean;
+/** Keplr-compatible API injected by the Cosmostation extension. */
+declare function getCosmostationKeplrApi(): BrowserWalletApi | undefined;
+declare function isCosmostationAvailable(): boolean;
 /** Build ChainInfo for Keplr/Leap experimentalSuggestChain. */
 declare function buildKingdomChainInfo(chainId: string, rpcUrl: string, restUrl: string, chainName?: string): ChainInfo;
 /** Suggest chain, request access, return CosmJS OfflineDirectSigner. */
 declare function suggestAndConnect(walletApi: BrowserWalletApi, chainInfo: ChainInfo, walletName?: string): Promise<OfflineDirectSigner>;
 declare function connectKeplr(chainInfo: ChainInfo): Promise<OfflineDirectSigner>;
 declare function connectLeap(chainInfo: ChainInfo): Promise<OfflineDirectSigner>;
+declare function connectCosmostation(chainInfo: ChainInfo): Promise<OfflineDirectSigner>;
 /** SigningStargateClient wired with Kingdom Chain custom message registry. */
 declare function createBrowserSigningClient(rpcUrl: string, signer: OfflineDirectSigner): Promise<SigningStargateClient>;
 
+declare const WALLETCONNECT_COSMOS_NAMESPACE = "cosmos";
+declare const WALLETCONNECT_COSMOS_METHODS: readonly ["cosmos_getAccounts", "cosmos_signDirect", "cosmos_signAmino"];
+interface WalletConnectMetadata {
+    name: string;
+    description: string;
+    url: string;
+    icons: string[];
+}
+interface WalletConnectChainConfig {
+    chainId: string;
+    projectId: string;
+    metadata: WalletConnectMetadata;
+    relayUrl?: string;
+}
+interface WalletConnectConnectResult {
+    uri: string;
+    session: SessionTypes.Struct;
+    signer: OfflineDirectSigner;
+}
+declare class WalletConnectNotInitializedError extends Error {
+    constructor();
+}
+declare class WalletConnectSessionError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+declare class WalletConnectSigningError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/** WalletConnect chain id: `cosmos:{chainId}`. */
+declare function toWalletConnectCosmosChainId(chainId: string): string;
+declare function parseWalletConnectAccount(account: string): {
+    namespace: string;
+    chainId: string;
+    address: string;
+};
+declare function buildRequiredCosmosNamespaces(chainId: string): ProposalTypes.RequiredNamespaces;
+declare function initWalletConnectClient(config: WalletConnectChainConfig): Promise<SignClient>;
+declare function createWalletConnectOfflineSigner(client: SignClient, session: SessionTypes.Struct, chainId: string): OfflineDirectSigner;
+/** Pair with a mobile wallet; returns WC URI (for QR) and approval promise. */
+declare function connectWalletConnect(client: SignClient, chainId: string, options?: {
+    pairingTopic?: string;
+}): Promise<WalletConnectConnectResult>;
+declare function disconnectWalletConnect(client: SignClient, session: SessionTypes.Struct, reason?: string): Promise<void>;
+declare function restoreWalletConnectSession(client: SignClient, chainId: string): Promise<{
+    session: SessionTypes.Struct;
+    signer: OfflineDirectSigner;
+} | null>;
+
+/** Embedded wallet vault format version. */
+declare const EMBEDDED_WALLET_VAULT_VERSION = 1;
+declare const EMBEDDED_WALLET_KDF_PRF: "webauthn-prf";
+declare const EMBEDDED_WALLET_KDF_PBKDF2: "pbkdf2-passkey";
+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 {
+    version: typeof EMBEDDED_WALLET_VAULT_VERSION;
+    kdf: EmbeddedWalletKdf;
+    credentialId: string;
+    publicAddress: string;
+    iv: string;
+    ciphertext: string;
+    /** PBKDF2 salt (base64). Empty when kdf=webauthn-prf. */
+    kdfSalt: string;
+    /** PBKDF2 iterations. Zero when kdf=webauthn-prf. */
+    kdfIterations: number;
+    /** PRF eval salt (base64). Empty when kdf=pbkdf2-passkey. */
+    prfSalt: string;
+    /** Hard gate: must be true before any transaction is permitted. */
+    backupAcknowledged: boolean;
+    backupAcknowledgedAt?: string;
+    createdAt: string;
+}
+interface EmbeddedWalletBackupFileV1 {
+    format: "kingdom-os-embedded-wallet-backup";
+    version: typeof EMBEDDED_WALLET_VAULT_VERSION;
+    vault: EmbeddedWalletVaultV1;
+    exportedAt: string;
+}
+declare class EmbeddedWalletBackupRequiredError extends Error {
+    constructor();
+}
+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 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>;
+/** PBKDF2-SHA256 fallback when WebAuthn PRF is unavailable (Safari cross-device QR, etc.). */
+declare function deriveKekFromPbkdf2(passkeyMaterial: Uint8Array, salt: Uint8Array, iterations?: number): Promise<Uint8Array>;
+declare function createPbkdf2Salt(): Uint8Array;
+declare function createPasskeyMaterialFromAssertion(authenticatorData: Uint8Array, clientDataJSON: Uint8Array): Uint8Array;
+declare function encryptWalletPayload(payload: EmbeddedWalletPlaintext, options: EncryptWalletOptions): Promise<EmbeddedWalletVaultV1>;
+declare function decryptWalletPayload(vault: EmbeddedWalletVaultV1, kek: Uint8Array): Promise<EmbeddedWalletPlaintext>;
+declare function markVaultBackupAcknowledged(vault: EmbeddedWalletVaultV1): EmbeddedWalletVaultV1;
+declare function assertVaultPermitsTransaction(vault: EmbeddedWalletVaultV1): void;
+
+/**
+ * WebAuthn PRF capability detection for embedded wallet KEK derivation.
+ *
+ * Safari does not expose PRF during cross-device QR-code WebAuthn flows — only
+ * direct iCloud-synced passkeys. Callers must fall back to PBKDF2 in that case.
+ */
+interface WebAuthnPrfCapabilities {
+    /** Browser exposes PublicKeyCredential. */
+    webAuthnAvailable: boolean;
+    /** PRF extension likely usable on this device/browser combo. */
+    prfLikelySupported: boolean;
+    /** Human-readable reason when prfLikelySupported is false. */
+    prfFallbackReason?: string;
+}
+/** Best-effort PRF support probe — PBKDF2 fallback remains mandatory. */
+declare function detectWebAuthnPrfCapabilities(): WebAuthnPrfCapabilities;
+/** Extract 32-byte PRF output from assertion clientExtensionResults. */
+declare function readPrfOutput(clientExtensionResults: AuthenticationExtensionsClientOutputs | undefined): Uint8Array | null;
+declare function selectEmbeddedWalletKdf(caps: WebAuthnPrfCapabilities, prfOutput: Uint8Array | null): "webauthn-prf" | "pbkdf2-passkey";
+
+declare function exportEncryptedBackup(vault: EmbeddedWalletVaultV1): EmbeddedWalletBackupFileV1;
+declare function parseEncryptedBackup(json: string): EmbeddedWalletBackupFileV1;
+declare function serializeBackupFile(backup: EmbeddedWalletBackupFileV1): string;
+
+declare const WEBAUTHN_RP_NAME = "Kingdom OS";
+interface PasskeyRegistrationResult {
+    credentialId: Uint8Array;
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+    prfOutput: Uint8Array | null;
+    prfSalt: Uint8Array;
+}
+interface PasskeyAssertionResult {
+    credentialId: Uint8Array;
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+    prfOutput: Uint8Array | null;
+}
+declare class WebAuthnUnavailableError extends Error {
+    constructor(message?: string);
+}
+declare class WebAuthnUserCancelledError extends Error {
+    constructor(message?: string);
+}
+/** Register a platform passkey; attempts PRF extension when supported. */
+declare function registerPasskey(options: {
+    userId: Uint8Array;
+    userName: string;
+    displayName: string;
+    rpId?: string;
+    prfSalt?: Uint8Array;
+}): Promise<PasskeyRegistrationResult>;
+/** Assert an existing passkey; re-derives PRF output when extension succeeds. */
+declare function assertPasskey(options: {
+    credentialId: Uint8Array;
+    rpId?: string;
+    prfSalt?: Uint8Array;
+}): Promise<PasskeyAssertionResult>;
+declare function encodeCredentialId(id: Uint8Array): string;
+declare function decodeCredentialId(encoded: string): Uint8Array;
+
+/** Build a CosmJS offline signer from decrypted vault plaintext. */
+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;
+    rpId?: string;
+}
+interface EmbeddedWalletSession {
+    address: string;
+    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 passcode-protected encrypted vault; does not unlock signer until backup is acknowledged. */
+declare function createEmbeddedWallet(options: CreateEmbeddedWalletOptions): Promise<{
+    address: string;
+    vault: EmbeddedWalletVaultV1;
+}>;
+/**
+ * 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;
+/** 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 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>;
+
 /**
  * Kingdom Chain on-chain denom and display metadata.
  *
@@ -217,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, DEFAULT_CHAIN_ID, DEFAULT_REST_URL, DEFAULT_RPC_URL, InvalidChainConfigError, MsgSubmitApplication, MsgSubmitRecoveryAttestation, RecoveryAttestationStatus, RpcConnectionError, type SubmitApplicationParams, UKDR_DECIMALS, UKDR_DISPLAY_DENOM, UKDR_MINIMAL_DENOM, WalletAccountError, WalletConnectionError, WalletConnectionRejectedError, WalletNotInstalledError, attestationSignPayload, buildKingdomChainInfo, buildSubmitApplicationMsg, connectKeplr, connectLeap, createBrowserSigningClient, createKingdomChainRegistry, isKeplrAvailable, isLeapAvailable, providerSeedFromHex, publicKeyFromPrivateSeed, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, 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 };