@kingdomchain/wallet-client 0.2.0 → 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

@@ -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,35 @@ 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. */
+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,41 +407,190 @@ declare function decodeCredentialId(encoded: string): Uint8Array;
 declare function embeddedPlaintextToSigner(plaintext: EmbeddedWalletPlaintext, prefix?: string): Promise<DirectSecp256k1Wallet>;
 declare function defaultEmbeddedHdPath(): string;
 
-declare function saveVaultToIndexedDb(vault: EmbeddedWalletVaultV1): Promise<void>;
-declare function loadVaultFromIndexedDb(): Promise<EmbeddedWalletVaultV1 | null>;
-declare function clearVaultFromIndexedDb(): Promise<void>;
+/** 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 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>;
 
-interface CreateEmbeddedWalletOptions {
+/** 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;
+/** 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. */
+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;
+}>;
+
+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;
+/** 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;
+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 EmbeddedWalletScopeOptions {
+    /** Supabase user id or other account key — scopes IndexedDB vault storage per account. */
+    scopeId?: string;
+}
+interface CreateEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
+    passcode: string;
+}
+interface UnlockEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
+    passcode?: string;
+}
+interface RevealEmbeddedRecoveryPhraseOptions extends EmbeddedWalletScopeOptions {
+    passcode?: string;
+}
+interface RecoverEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
+    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 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;
     signer: OfflineDirectSigner;
 }
-/** 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. */
+declare function vaultUsesPasskeyUnlock(vault: EmbeddedWalletVaultV1): boolean;
+declare function vaultUsesPasscodeUnlock(vault: EmbeddedWalletVaultV1): 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;
     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;
 /** 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 (still requires passkey to decrypt). */
-declare function importEmbeddedBackup(json: string): Promise<EmbeddedWalletVaultV1>;
-declare function clearEmbeddedWallet(): Promise<void>;
+/** Restore vault from user-held backup file (requires passcode or passkey to decrypt). */
+declare function importEmbeddedBackup(json: string, options?: ImportEmbeddedBackupOptions): Promise<EmbeddedWalletVaultV1>;
+declare function clearEmbeddedWallet(options?: ClearEmbeddedWalletOptions): Promise<void>;
 
 /**
  * Kingdom Chain on-chain denom and display metadata.
@@ -443,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_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, 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 };