@kingdomchain/wallet-client 0.6.2 → 0.8.1

package/README.md

@@ -103,7 +103,31 @@ See `clients/kingdom-os-reference/README.md` for env vars and usage.
 - `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).
+#### PIN-only vault (0.8.0, recommended for new wallets)
+
+Like Exodus: the user remembers **one 6-digit PIN**. Fingerprint / Face ID is the quick door. The **24 words** are the backup.
+
+- `createEmbeddedWallet({ pin })` / `recoverEmbeddedWalletFromMnemonic({ mnemonic, pin })` — new vault with kdf `device-pin`.
+- `unlockEmbeddedWallet({ pin })` and `revealEmbeddedRecoveryPhrase({ pin })` — same 5-try timed lockout as the passcode path. A malformed PIN does not count as a try.
+- `setEmbeddedWalletPin({ pin, currentPin? | passcode? })` — change the PIN, or switch an old passcode vault to a PIN once (the passcode then stops working). Can be called without a secret right after a strong unlock. Fingerprint wrap and backup status are kept.
+- `enableEmbeddedPasskeyUnlock({ pin, ... })` works on PIN vaults.
+- `vaultUsesPinUnlock(vault)` — tells the UI which door to show.
+- No backup file: `exportEncryptedBackup` throws and `acknowledgeEmbeddedBackup` returns `null` for PIN vaults. The 24 words are the backup.
+
+Security: the vault is encrypted twice — with a PBKDF2-SHA256 (600k) key from the PIN **and** a non-extractable device key in IndexedDB. Copying the vault to another browser does not open it; a new device recovers with the 24 words. Limit (same as Exodus desktop): someone who copies this browser's files off the disk could brute-force 6 digits offline.
+
+#### Face ID (passkey) + quick PIN (vault unlock, 0.7.0)
+
+- `enableEmbeddedPasskeyUnlock({ userId, userName, displayName, rpId, passcode? })` — **adds** Face ID / fingerprint unlock to a passcode vault (`vault.passkeyWrap`). The passcode keeps working. `passcode` may be omitted right after an unlock in the same page. Pass the registrable domain as `rpId` (e.g. `theholykingdom.io`) so the passkey works on every subdomain.
+- `unlockEmbeddedWalletWithPasskey()` — Face ID unlock (also opens legacy passkey-only vaults).
+- `disableEmbeddedPasskeyUnlock()` — remove Face ID; passcode stays.
+- `revealEmbeddedRecoveryPhrase()` without `passcode` uses Face ID when the vault has a passkey wrap.
+- `setEmbeddedQuickUnlockPin({ pin })` — 6-digit PIN for this browser; only right after a Face ID or passcode unlock. Trivial PINs (000000, 123456, 121212 …) are rejected.
+- `unlockEmbeddedWalletWithPin({ pin })` / `getEmbeddedQuickUnlockStatus()` / `clearEmbeddedQuickUnlockPin()`.
+
+Rules: the PIN works for **7 days** after the last Face ID / passcode unlock (PIN unlocks do not extend it); **5 wrong PINs** delete the PIN record; the record is encrypted with a PIN-derived key **and** a non-extractable device key, so it cannot open the vault on any other browser. The PIN is a convenience door: an attacker who copies this browser's files off the disk could brute-force 6 digits offline within the 7-day window — the passcode and passkey records are not weakened by it.
+
+KDF selection: passkey unlock **requires** a WebAuthn PRF output. If the device returns none (at registration or on a follow-up assertion) `EmbeddedWalletPasskeyUnsupportedError` is thrown and the vault stays passcode-only. The old `pbkdf2-passkey` fallback derived its key from per-ceremony public data (it neither protected the vault nor reproduced on the next unlock) and is no longer used for new vaults; Safari is no longer excluded by user-agent sniffing (Safari 18+ supports PRF).
 
 **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".
 

package/dist/index.d.ts

@@ -241,7 +241,13 @@ 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;
+/**
+ * 6-digit PIN vault (0.8.0): the payload is encrypted with a PBKDF2 key from the
+ * PIN and again with a non-extractable device key that never leaves this browser.
+ * The 24 words are the only portable backup.
+ */
+declare const EMBEDDED_WALLET_KDF_DEVICE_PIN: "device-pin";
+type EmbeddedWalletKdf = typeof EMBEDDED_WALLET_KDF_PRF | typeof EMBEDDED_WALLET_KDF_PBKDF2 | typeof EMBEDDED_WALLET_KDF_PIN | typeof EMBEDDED_WALLET_KDF_DEVICE_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";
@@ -270,6 +276,25 @@ interface EmbeddedWalletRecoveryPhraseReveal {
     address: string;
     warnings: EmbeddedWalletRecoveryPhraseWarning[];
 }
+/**
+ * Optional second unlock path for a passcode vault: the same wallet payload,
+ * encrypted again under a KEK derived from a WebAuthn PRF output (Face ID /
+ * fingerprint passkey). The passcode wrap stays the primary record, so a device
+ * or browser without PRF can always fall back to the passcode.
+ */
+interface EmbeddedWalletPasskeyWrap {
+    /** WebAuthn credential id (base64). */
+    credentialId: string;
+    /** PRF eval salt (base64). */
+    prfSalt: string;
+    /** Relying party id the passkey was registered for (e.g. "theholykingdom.io"). */
+    rpId?: string;
+    /** AES-GCM IV (base64). */
+    iv: string;
+    /** AES-GCM ciphertext of the wallet payload under the PRF KEK (base64). */
+    ciphertext: string;
+    createdAt: string;
+}
 /** Encrypted vault stored in IndexedDB and exported backup files. */
 interface EmbeddedWalletVaultV1 {
     version: typeof EMBEDDED_WALLET_VAULT_VERSION;
@@ -288,6 +313,12 @@ interface EmbeddedWalletVaultV1 {
     backupAcknowledged: boolean;
     backupAcknowledgedAt?: string;
     createdAt: string;
+    /** Present when Face ID / passkey unlock was added on top of the passcode. */
+    passkeyWrap?: EmbeddedWalletPasskeyWrap;
+    /** kdf=device-pin only: non-extractable AES-GCM key bound to this browser. */
+    deviceKey?: CryptoKey;
+    /** kdf=device-pin only: IV (base64) of the outer device-key layer. */
+    deviceIv?: string;
 }
 interface EmbeddedWalletBackupFileV1 {
     format: "kingdom-os-embedded-wallet-backup";
@@ -318,6 +349,25 @@ declare class EmbeddedWalletWeakPasscodeError extends Error {
     readonly reason: PasscodeBlockReason;
     constructor(reason: PasscodeBlockReason);
 }
+/**
+ * Thrown when this device/browser cannot produce a WebAuthn PRF output, so a
+ * passkey cannot protect the vault. Callers keep the passcode path instead.
+ */
+declare class EmbeddedWalletPasskeyUnsupportedError extends EmbeddedWalletVaultError {
+    readonly code: "passkey_prf_unsupported";
+    constructor(message?: string);
+}
+type EmbeddedWalletQuickUnlockErrorCode = "not_set" | "expired" | "wrong_pin" | "wiped" | "invalid_pin" | "no_session";
+/**
+ * Quick-unlock (6-digit PIN) failures. `attemptsLeft` is set for `wrong_pin`.
+ * `wiped` means too many wrong PINs: the PIN record was deleted and a strong
+ * unlock (passkey or passcode) is required.
+ */
+declare class EmbeddedWalletQuickUnlockError extends Error {
+    readonly code: EmbeddedWalletQuickUnlockErrorCode;
+    readonly attemptsLeft?: number;
+    constructor(code: EmbeddedWalletQuickUnlockErrorCode, message: string, attemptsLeft?: number);
+}
 
 interface EncryptWalletOptions {
     kdf: EmbeddedWalletKdf;
@@ -332,6 +382,8 @@ interface EncryptWalletOptions {
     kdfIterations?: number;
     backupAcknowledged?: boolean;
 }
+declare function serializePlaintext(payload: EmbeddedWalletPlaintext): Uint8Array;
+declare function deserializePlaintext(bytes: Uint8Array): EmbeddedWalletPlaintext;
 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>;
@@ -341,12 +393,22 @@ declare function encryptWalletPayload(payload: EmbeddedWalletPlaintext, options:
 declare function decryptWalletPayload(vault: EmbeddedWalletVaultV1, kek: Uint8Array): Promise<EmbeddedWalletPlaintext>;
 declare function markVaultBackupAcknowledged(vault: EmbeddedWalletVaultV1): EmbeddedWalletVaultV1;
 declare function assertVaultPermitsTransaction(vault: EmbeddedWalletVaultV1): void;
+/** Encrypt a wallet payload under a raw 32-byte KEK (used for the passkey wrap). */
+declare function encryptPlaintextWithKek(payload: EmbeddedWalletPlaintext, kek: Uint8Array): Promise<{
+    iv: string;
+    ciphertext: string;
+}>;
+/** Decrypt a payload produced by {@link encryptPlaintextWithKek}. */
+declare function decryptPlaintextWithKek(iv: string, ciphertext: string, kek: Uint8Array): Promise<EmbeddedWalletPlaintext>;
 
 /**
  * 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.
+ * A passkey only protects the vault when the authenticator returns a PRF
+ * output (a secret it never reveals otherwise). Without PRF there is no secret
+ * to derive a key from, so the wallet keeps the passcode instead — the old
+ * "pbkdf2-passkey" mode built its key from per-assertion public data and is no
+ * longer used for new vaults.
  */
 interface WebAuthnPrfCapabilities {
     /** Browser exposes PublicKeyCredential. */
@@ -356,7 +418,7 @@ interface WebAuthnPrfCapabilities {
     /** Human-readable reason when prfLikelySupported is false. */
     prfFallbackReason?: string;
 }
-/** Best-effort PRF support probe — PBKDF2 fallback remains mandatory. */
+/** Best-effort PRF support probe; the real check is a PRF output at registration. */
 declare function detectWebAuthnPrfCapabilities(): WebAuthnPrfCapabilities;
 /** Extract 32-byte PRF output from assertion clientExtensionResults. */
 declare function readPrfOutput(clientExtensionResults: AuthenticationExtensionsClientOutputs | undefined): Uint8Array | null;
@@ -413,6 +475,35 @@ interface VaultStorageOptions {
     /** When set, vault is stored under this account-scoped key instead of {@link VAULT_LEGACY_KEY}. */
     scopeId?: string;
 }
+/**
+ * Encrypted, expiring session-unlock cache (see {@link file://./sessionCache.ts}).
+ * The `key` is a non-extractable AES-GCM {@link CryptoKey} stored directly in
+ * IndexedDB via structured clone — its raw bytes can never be read back out by
+ * any JavaScript. `ciphertext`/`iv` are base64; `expiresAt` is epoch millis.
+ */
+interface EmbeddedWalletSessionCacheRecord {
+    key: CryptoKey;
+    iv: string;
+    ciphertext: string;
+    expiresAt: number;
+}
+/**
+ * 6-digit PIN quick-unlock record (see {@link file://./quickUnlock.ts}). The
+ * wallet payload is encrypted twice: inside with a PBKDF2 key from the PIN,
+ * outside with a non-extractable device key that lives only in this browser.
+ */
+interface EmbeddedWalletQuickUnlockRecord {
+    deviceKey: CryptoKey;
+    publicAddress: string;
+    salt: string;
+    iterations: number;
+    innerIv: string;
+    outerIv: string;
+    ciphertext: string;
+    /** Epoch millis; refreshed only by a passkey or passcode unlock. */
+    expiresAt: number;
+    failedAttempts: number;
+}
 interface PasscodeLockoutRecord {
     failedAttempts: number;
     lockoutTier: number;
@@ -425,6 +516,45 @@ declare function clearVaultFromIndexedDb(options?: VaultStorageOptions): Promise
 declare function loadPasscodeLockoutRecord(publicAddress: string): Promise<PasscodeLockoutRecord | null>;
 declare function savePasscodeLockoutRecord(publicAddress: string, record: PasscodeLockoutRecord): Promise<void>;
 declare function clearPasscodeLockoutRecord(publicAddress: string): Promise<void>;
+declare function saveSessionCacheRecord(record: EmbeddedWalletSessionCacheRecord, options?: VaultStorageOptions): Promise<void>;
+declare function loadSessionCacheRecord(options?: VaultStorageOptions): Promise<EmbeddedWalletSessionCacheRecord | null>;
+declare function clearSessionCacheRecord(options?: VaultStorageOptions): Promise<void>;
+declare function saveQuickUnlockRecord(record: EmbeddedWalletQuickUnlockRecord, options?: VaultStorageOptions): Promise<void>;
+declare function loadQuickUnlockRecord(options?: VaultStorageOptions): Promise<EmbeddedWalletQuickUnlockRecord | null>;
+declare function clearQuickUnlockRecord(options?: VaultStorageOptions): Promise<void>;
+
+/**
+ * How long a passcode/passkey unlock stays valid across page reloads and new
+ * tabs (same browser, same device) before the unlock form is required again.
+ *
+ * Phase 1 session-persistent unlock: 12 hours of wall-clock time from the last
+ * unlock. Deliberately bounded — not "until tab closes" (too strict, reintroduces
+ * daily friction) and not "forever" (that is phase 2's job, backed by WebAuthn).
+ * Tune here; it is intentionally the single source of truth for the window.
+ */
+declare const EMBEDDED_WALLET_SESSION_TTL_MS: number;
+interface CacheUnlockedSessionOptions extends VaultStorageOptions {
+    /** Decrypted vault material needed to rebuild the signer without the passcode. */
+    plaintext: EmbeddedWalletPlaintext;
+    /** Override the default session window (mainly for tests). */
+    ttlMs?: number;
+}
+/**
+ * Encrypt the just-decrypted session material under a fresh non-extractable key
+ * and persist it (with an expiry) so a reload or new tab can restore the signer
+ * without re-prompting for the passcode. Best-effort: callers should not fail an
+ * unlock if this throws.
+ */
+declare function cacheUnlockedSession(options: CacheUnlockedSessionOptions): Promise<void>;
+/**
+ * Restore the decrypted session material from the cache for a scope, or return
+ * `null` when there is nothing valid cached. "No session" is a normal, expected
+ * state — this never throws for it. An expired or undecryptable record is wiped
+ * and treated as `null`.
+ */
+declare function restoreCachedSessionPlaintext(options?: VaultStorageOptions): Promise<EmbeddedWalletPlaintext | null>;
+/** Wipe the cached session key + ciphertext for a scope. */
+declare function clearUnlockedSession(options?: VaultStorageOptions): Promise<void>;
 
 /** Consecutive wrong passcodes before lockout triggers. */
 declare const PASSCODE_LOCKOUT_FAILURE_THRESHOLD = 5;
@@ -472,6 +602,107 @@ declare function normalizePasscode(passcode: string): string;
 declare function assertValidPasscode(passcode: string): void;
 declare function deriveKekFromPasscode(passcode: string, salt: Uint8Array, iterations?: number): Promise<Uint8Array>;
 
+/**
+ * 6-digit PIN quick unlock ("Exodus feel").
+ *
+ * Security model, stated plainly:
+ * - The PIN is a convenience door, never the real key. It can only be set right
+ *   after a strong unlock (passkey/Face ID or the long passcode), and only works
+ *   on this browser: the payload is also encrypted under a non-extractable
+ *   device key that no JavaScript can export.
+ * - It expires {@link QUICK_UNLOCK_TTL_MS} after the last strong unlock. A PIN
+ *   unlock does NOT extend it, so Face ID / passcode is needed at least weekly.
+ * - {@link QUICK_UNLOCK_MAX_ATTEMPTS} wrong PINs delete the record entirely.
+ * - A 6-digit PIN has only 1,000,000 values, so an attacker who copies this
+ *   browser's storage files off the disk (malware, stolen unlocked laptop) could
+ *   brute-force it offline. The short expiry bounds that window; the passkey
+ *   and passcode vault records are not weakened by the PIN.
+ */
+declare const QUICK_UNLOCK_PIN_LENGTH = 6;
+/** PIN stays usable for 7 days after the last passkey / passcode unlock. */
+declare const QUICK_UNLOCK_TTL_MS: number;
+/** Wrong PINs allowed before the quick-unlock record is wiped. */
+declare const QUICK_UNLOCK_MAX_ATTEMPTS = 5;
+/** PBKDF2-SHA256 iterations for the PIN-derived inner key. */
+declare const QUICK_UNLOCK_PBKDF2_ITERATIONS = 600000;
+interface EmbeddedQuickUnlockStatus {
+    /** A PIN record exists for this scope. */
+    enabled: boolean;
+    /** The record exists but is past its expiry (strong unlock needed). */
+    expired: boolean;
+    /** Epoch millis, or null when not enabled. */
+    expiresAt: number | null;
+    /** Wrong PINs left before the record is wiped. */
+    attemptsLeft: number;
+    /** Address the PIN opens, or null when not enabled. */
+    publicAddress: string | null;
+}
+/** Rejects anything but 6 digits, and PINs that are trivially guessable. */
+declare function assertQuickUnlockPinAllowed(pin: string): void;
+/** Same digit, straight runs (123456 / 654321) or short repeats (121212, 123123). */
+declare function isTrivialPin(pin: string): boolean;
+declare function derivePinKey(pin: string, salt: Uint8Array, iterations: number): Promise<CryptoKey>;
+/**
+ * Store a PIN record for the given decrypted payload. Callers must only invoke
+ * this right after a strong unlock — wallet.ts enforces that.
+ */
+declare function createQuickUnlockRecord(options: VaultStorageOptions & {
+    plaintext: EmbeddedWalletPlaintext;
+    publicAddress: string;
+    pin: string;
+    ttlMs?: number;
+    iterations?: number;
+}): Promise<EmbeddedWalletQuickUnlockRecord>;
+/**
+ * Open the PIN record. The failed-attempt counter is written BEFORE the PIN is
+ * checked, so killing the tab mid-check cannot be used to get free guesses.
+ */
+declare function openQuickUnlockRecord(options: VaultStorageOptions & {
+    pin: string;
+}): Promise<{
+    plaintext: EmbeddedWalletPlaintext;
+    publicAddress: string;
+}>;
+/** Status for the UI (show PIN pad vs Face ID / passcode). Never throws for "none". */
+declare function getQuickUnlockStatus(options?: VaultStorageOptions): Promise<EmbeddedQuickUnlockStatus>;
+/**
+ * Restart the 7-day window after a strong unlock. Only for the same address;
+ * a record for another wallet is wiped instead.
+ */
+declare function refreshQuickUnlockExpiry(options: VaultStorageOptions & {
+    publicAddress: string;
+    ttlMs?: number;
+}): Promise<void>;
+declare function clearQuickUnlock(options?: VaultStorageOptions): Promise<void>;
+
+/**
+ * PIN-only vault (0.8.0) — the one secret a citizen remembers.
+ *
+ * Two layers, both AES-GCM:
+ *  inner: key from PBKDF2-SHA256(PIN, salt, 600k)
+ *  outer: a fresh non-extractable device key stored with the vault in IndexedDB
+ * So the vault opens only in this browser AND only with the PIN. Wrong PINs go
+ * through the existing timed lockout (5 tries, then 30 s doubling to 15 min).
+ *
+ * Honest limit: someone who copies this browser's storage files off the disk
+ * (malware, stolen unlocked computer) could try all 1,000,000 PINs offline. The
+ * 24-word phrase stays the real, portable backup; Face ID / fingerprint
+ * (passkey) can be added on top.
+ */
+declare const DEVICE_PIN_PBKDF2_ITERATIONS = 600000;
+declare function vaultUsesPinUnlock(vault: EmbeddedWalletVaultV1): boolean;
+declare function encryptPlaintextWithDevicePin(plaintext: EmbeddedWalletPlaintext, pin: string, options: {
+    publicAddress: string;
+    backupAcknowledged?: boolean;
+    iterations?: number;
+}): Promise<EmbeddedWalletVaultV1>;
+/**
+ * Decrypt a PIN vault. A wrong PIN throws {@link EmbeddedWalletDecryptError}
+ * (counted by the lockout); a malformed PIN throws `invalid_pin` (not counted);
+ * a missing / broken device layer throws {@link EmbeddedWalletVaultError}.
+ */
+declare function decryptDevicePinVault(vault: EmbeddedWalletVaultV1, pin: string): Promise<EmbeddedWalletPlaintext>;
+
 /** Normalize user input: trim, lowercase, collapse whitespace. */
 declare function normalizeRecoveryMnemonic(mnemonic: string): string;
 declare function assertValidRecoveryMnemonic(mnemonic: string): void;
@@ -496,18 +727,27 @@ interface EmbeddedWalletScopeOptions {
     scopeId?: string;
 }
 interface CreateEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
-    passcode: string;
+    /** Legacy long passcode. Pass `pin` instead for the PIN-only vault (0.8.0). */
+    passcode?: string;
+    /** 6-digit PIN — creates a device-bound PIN vault (no passcode). */
+    pin?: string;
     /** When true, replaces an existing vault on this account (e.g. an intentional reset). */
     replaceExisting?: boolean;
 }
 interface UnlockEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
     passcode?: string;
+    /** 6-digit PIN for PIN vaults. */
+    pin?: string;
 }
 interface RevealEmbeddedRecoveryPhraseOptions extends EmbeddedWalletScopeOptions {
     passcode?: string;
+    pin?: string;
 }
 interface RecoverEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
-    passcode: string;
+    /** Legacy long passcode. Pass `pin` instead for the PIN-only vault. */
+    passcode?: string;
+    /** 6-digit PIN — the recovered wallet is stored as a PIN vault. */
+    pin?: string;
     mnemonic: string;
     /** When omitted, inferred from expectedAddress or defaults to hd-derived. */
     keyType?: EmbeddedWalletKeyType;
@@ -517,8 +757,22 @@ interface RecoverEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
     /** When true, replaces an existing vault on this device (e.g. after device loss). */
     replaceExisting?: boolean;
 }
+interface SetEmbeddedWalletPinOptions extends EmbeddedWalletScopeOptions {
+    /** The new 6-digit PIN. */
+    pin: string;
+    /** Current PIN (PIN vaults). Optional right after an unlock in this page. */
+    currentPin?: string;
+    /** Current passcode (switching an old passcode vault to a PIN). */
+    passcode?: string;
+}
 interface EnableEmbeddedPasskeyUnlockOptions extends EmbeddedWalletScopeOptions {
-    passcode: string;
+    /**
+     * Passcode to decrypt the vault. May be omitted right after an unlock in this
+     * page (the decrypted payload is still in memory for the same scope).
+     */
+    passcode?: string;
+    /** PIN to decrypt a PIN vault (same rule as passcode). */
+    pin?: string;
     userId: Uint8Array;
     userName: string;
     displayName: string;
@@ -534,6 +788,12 @@ interface ImportEmbeddedBackupOptions extends EmbeddedWalletScopeOptions {
 }
 interface ClearEmbeddedWalletOptions extends EmbeddedWalletScopeOptions {
 }
+interface SetEmbeddedQuickUnlockPinOptions extends EmbeddedWalletScopeOptions {
+    pin: string;
+}
+interface UnlockEmbeddedWalletWithPinOptions extends EmbeddedWalletScopeOptions {
+    pin: string;
+}
 interface AcknowledgeEmbeddedBackupOptions extends EmbeddedWalletScopeOptions {
 }
 interface EmbeddedWalletSession {
@@ -543,6 +803,9 @@ interface EmbeddedWalletSession {
 }
 declare function vaultUsesPasskeyUnlock(vault: EmbeddedWalletVaultV1): boolean;
 declare function vaultUsesPasscodeUnlock(vault: EmbeddedWalletVaultV1): boolean;
+
+/** True when Face ID / passkey can open this vault (added wrap or legacy passkey vault). */
+declare function vaultHasPasskeyUnlock(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. */
@@ -573,22 +836,68 @@ declare function recoverEmbeddedWalletFromMnemonic(options: RecoverEmbeddedWalle
     keyType: EmbeddedWalletKeyType;
 }>;
 /**
- * Opt-in upgrade: re-wrap an existing passcode vault with passkey unlock.
- * Does not change the underlying private key or address.
+ * Add Face ID / fingerprint (passkey) unlock to a passcode vault. The passcode
+ * keeps working; the same payload is additionally encrypted under a KEK from the
+ * passkey's PRF output. Does not change the private key or address.
+ *
+ * Throws {@link EmbeddedWalletPasskeyUnsupportedError} when the device returns no
+ * PRF output (the vault is left unchanged — keep using the passcode).
  */
 declare function enableEmbeddedPasskeyUnlock(options: EnableEmbeddedPasskeyUnlockOptions): Promise<{
     address: string;
     vault: EmbeddedWalletVaultV1;
 }>;
+/**
+ * Set or change the 6-digit PIN. Turns an old passcode vault into a PIN vault
+ * (the passcode stops working), or re-keys an existing PIN vault. Needs the
+ * current secret, or an unlock in this page. Keeps Face ID / fingerprint, the
+ * backup flag and the address unchanged.
+ */
+declare function setEmbeddedWalletPin(options: SetEmbeddedWalletPinOptions): Promise<{
+    address: string;
+    vault: EmbeddedWalletVaultV1;
+}>;
+/** Remove Face ID / passkey unlock; the passcode keeps working. */
+declare function disableEmbeddedPasskeyUnlock(options?: EmbeddedWalletScopeOptions): Promise<EmbeddedWalletVaultV1>;
+/**
+ * Unlock with Face ID / fingerprint. Works for vaults with an added passkey wrap
+ * and for legacy passkey-only vaults.
+ */
+declare function unlockEmbeddedWalletWithPasskey(options?: EmbeddedWalletScopeOptions): Promise<EmbeddedWalletSession>;
+/**
+ * Set (or replace) the 6-digit PIN for quick unlock on this browser. Allowed only
+ * while the wallet is open from a passkey or passcode unlock in this page — not
+ * from a restored session or a PIN unlock.
+ */
+declare function setEmbeddedQuickUnlockPin(options: SetEmbeddedQuickUnlockPinOptions): Promise<EmbeddedQuickUnlockStatus>;
+/** Unlock with the 6-digit PIN. Does not extend the 7-day PIN window. */
+declare function unlockEmbeddedWalletWithPin(options: UnlockEmbeddedWalletWithPinOptions): Promise<EmbeddedWalletSession>;
+/** PIN status for the UI: show the PIN pad, or ask for Face ID / passcode. */
+declare function getEmbeddedQuickUnlockStatus(options?: EmbeddedWalletScopeOptions): Promise<EmbeddedQuickUnlockStatus>;
+/** Remove the PIN from this browser. */
+declare function clearEmbeddedQuickUnlockPin(options?: EmbeddedWalletScopeOptions): Promise<void>;
 /** Unlock existing vault with passcode (default) or passkey (opt-in upgrade path). */
 declare function unlockEmbeddedWallet(options?: UnlockEmbeddedWalletOptions): Promise<EmbeddedWalletSession>;
-/** Clear in-memory signer. */
+/**
+ * Silently restore a still-valid unlock cached by a previous {@link unlockEmbeddedWallet}
+ * (this page load, a prior one, or another tab in the same browser), without the
+ * passcode. Returns the same session shape {@link unlockEmbeddedWallet} returns,
+ * or `null` when nothing valid is cached — "no session" is a normal state and is
+ * never thrown. The vault encryption/passcode mechanism is untouched; this only
+ * reads a parallel, expiring session cache.
+ */
+declare function tryRestoreUnlockedSession(options?: EmbeddedWalletScopeOptions): Promise<EmbeddedWalletSession | null>;
+/**
+ * Clear the in-memory signer and wipe the persistent session cache for the
+ * active scope. Wiring the cache clear here guarantees an explicit lock/logout
+ * never leaves a silent-unlock path alive.
+ */
 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(options?: AcknowledgeEmbeddedBackupOptions): Promise<EmbeddedWalletBackupFileV1>;
+declare function acknowledgeEmbeddedBackup(options?: AcknowledgeEmbeddedBackupOptions): Promise<EmbeddedWalletBackupFileV1 | null>;
 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, options?: ImportEmbeddedBackupOptions): Promise<EmbeddedWalletVaultV1>;
@@ -743,4 +1052,4 @@ interface MessageFns<T> {
     fromPartial(object: DeepPartial<T>): T;
 }
 
-export { ATTESTATION_TYPE_CITIZENSHIP_APPLICATION, ATTESTATION_TYPE_RECOVERY, type AcknowledgeEmbeddedBackupOptions, ApplicationStatus, type AttestationPayloadInput, BECH32_PREFIX, type BankBalanceResponse, type BroadcastConfirmOptions, type BroadcastConfirmResult, type BrowserWalletApi, CHAIN_COIN_TYPE, type ChainCurrency, type ChainInfo, CitizenTxError, type CitizenTxErrorCode, 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 FeeGrantAllowancesResponse, FinalizedReward, type ImportEmbeddedBackupOptions, InvalidChainConfigError, type MigrateLegacyEmbeddedWalletOptions, MsgClaimReward, 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, RestQueryError, type RevealEmbeddedRecoveryPhraseOptions, RpcConnectionError, type SubmitApplicationParams, UKDR_DECIMALS, UKDR_DISPLAY_DENOM, UKDR_MINIMAL_DENOM, type UnclaimedRewardsResponse, 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, broadcastAndConfirmTx, buildClaimRewardMsg, buildKingdomChainInfo, buildRequiredCosmosNamespaces, buildSendUkdrMsg, buildSubmitApplicationMsg, citizenTxErrorMessage, clearEmbeddedWallet, clearPasscodeLockoutRecord, clearVaultFromIndexedDb, computePasscodeLockoutDurationMs, connectCosmostation, connectKeplr, connectLeap, connectWalletConnect, createBrowserSigningClient, createEmbeddedWallet, createHdDerivedPlaintext, createKingdomChainRegistry, createPasskeyMaterialFromAssertion, createPbkdf2Salt, createWalletConnectOfflineSigner, decodeCredentialId, decodeDirectEntropyMnemonic, decryptWalletPayload, defaultEmbeddedHdPath, defaultUkdrTxFee, deriveKekFromPasscode, deriveKekFromPbkdf2, deriveKekFromPrf, derivePrivateKeyFromHdMnemonic, detectRecoveryMnemonicKeyType, detectWebAuthnPrfCapabilities, disconnectWalletConnect, downloadEmbeddedBackupFile, embeddedPlaintextToSigner, enableEmbeddedPasskeyUnlock, encodeCredentialId, encodeDirectEntropyMnemonic, encryptWalletPayload, evaluatePasscodeStrength, exportEncryptedBackup, fetchFeeGrantGranter, fetchUkdrBalance, fetchUnclaimedFinalizedRewards, formatUkdrAsKdr, getCosmostationKeplrApi, getEmbeddedOfflineSigner, getEmbeddedWalletSession, getPasscodeLockoutState, hasEmbeddedWallet, hasLegacyEmbeddedWallet, hasMixedCharacterClasses, importEmbeddedBackup, initWalletConnectClient, isCosmostationAvailable, isKeplrAvailable, isLeapAvailable, loadPasscodeLockoutRecord, loadVaultFromIndexedDb, lockEmbeddedWallet, markVaultBackupAcknowledged, migrateLegacyEmbeddedWallet, normalizePasscode, normalizeRecoveryMnemonic, parseEncryptedBackup, parseKdrToUkdr, parseWalletConnectAccount, plaintextFromRecoveryMnemonic, providerSeedFromHex, publicKeyFromPrivateSeed, readPrfOutput, recordPasscodeUnlockFailure, recordPasscodeUnlockSuccess, recoverEmbeddedWalletFromMnemonic, recoveryMnemonicAddress, recoveryMnemonicFromPlaintext, registerPasskey, resolvePlaintextKeyType, resolveVaultStorageKey, restoreWalletConnectSession, revealEmbeddedRecoveryPhrase, savePasscodeLockoutRecord, saveVaultToIndexedDb, selectEmbeddedWalletKdf, serializeBackupFile, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, toWalletConnectCosmosChainId, ukdrCoin, unlockEmbeddedWallet, validateChainConfig, vaultUsesPasscodeUnlock, vaultUsesPasskeyUnlock };
+export { ATTESTATION_TYPE_CITIZENSHIP_APPLICATION, ATTESTATION_TYPE_RECOVERY, type AcknowledgeEmbeddedBackupOptions, ApplicationStatus, type AttestationPayloadInput, BECH32_PREFIX, type BankBalanceResponse, type BroadcastConfirmOptions, type BroadcastConfirmResult, type BrowserWalletApi, CHAIN_COIN_TYPE, type CacheUnlockedSessionOptions, type ChainCurrency, type ChainInfo, CitizenTxError, type CitizenTxErrorCode, type ClearEmbeddedWalletOptions, type CosmostationWindowApi, type CreateEmbeddedWalletOptions, DEFAULT_CHAIN_ID, DEFAULT_REST_URL, DEFAULT_RPC_URL, DEVICE_PIN_PBKDF2_ITERATIONS, EMBEDDED_WALLET_KDF_DEVICE_PIN, 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_SESSION_TTL_MS, EMBEDDED_WALLET_VAULT_VERSION, type EmbeddedQuickUnlockStatus, type EmbeddedWalletBackupFileV1, EmbeddedWalletBackupRequiredError, EmbeddedWalletDecryptError, type EmbeddedWalletKdf, type EmbeddedWalletKeyType, EmbeddedWalletLockoutError, EmbeddedWalletPasskeyUnsupportedError, type EmbeddedWalletPasskeyWrap, type EmbeddedWalletPlaintext, EmbeddedWalletQuickUnlockError, type EmbeddedWalletQuickUnlockErrorCode, type EmbeddedWalletQuickUnlockRecord, type EmbeddedWalletRecoveryPhraseReveal, type EmbeddedWalletRecoveryPhraseWarning, type EmbeddedWalletScopeOptions, type EmbeddedWalletSession, type EmbeddedWalletSessionCacheRecord, EmbeddedWalletVaultError, type EmbeddedWalletVaultV1, EmbeddedWalletWeakPasscodeError, type EnableEmbeddedPasskeyUnlockOptions, type EncryptWalletOptions, type FeeGrantAllowancesResponse, FinalizedReward, type ImportEmbeddedBackupOptions, InvalidChainConfigError, type MigrateLegacyEmbeddedWalletOptions, MsgClaimReward, 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, QUICK_UNLOCK_MAX_ATTEMPTS, QUICK_UNLOCK_PBKDF2_ITERATIONS, QUICK_UNLOCK_PIN_LENGTH, QUICK_UNLOCK_TTL_MS, type RecoverEmbeddedWalletOptions, RecoveryAttestationStatus, RestQueryError, type RevealEmbeddedRecoveryPhraseOptions, RpcConnectionError, type SetEmbeddedQuickUnlockPinOptions, type SetEmbeddedWalletPinOptions, type SubmitApplicationParams, UKDR_DECIMALS, UKDR_DISPLAY_DENOM, UKDR_MINIMAL_DENOM, type UnclaimedRewardsResponse, type UnlockEmbeddedWalletOptions, type UnlockEmbeddedWalletWithPinOptions, 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, assertQuickUnlockPinAllowed, assertValidPasscode, assertValidRecoveryMnemonic, assertVaultPermitsTransaction, attestationSignPayload, broadcastAndConfirmTx, buildClaimRewardMsg, buildKingdomChainInfo, buildRequiredCosmosNamespaces, buildSendUkdrMsg, buildSubmitApplicationMsg, cacheUnlockedSession, citizenTxErrorMessage, clearEmbeddedQuickUnlockPin, clearEmbeddedWallet, clearPasscodeLockoutRecord, clearQuickUnlock, clearQuickUnlockRecord, clearSessionCacheRecord, clearUnlockedSession, clearVaultFromIndexedDb, computePasscodeLockoutDurationMs, connectCosmostation, connectKeplr, connectLeap, connectWalletConnect, createBrowserSigningClient, createEmbeddedWallet, createHdDerivedPlaintext, createKingdomChainRegistry, createPasskeyMaterialFromAssertion, createPbkdf2Salt, createQuickUnlockRecord, createWalletConnectOfflineSigner, decodeCredentialId, decodeDirectEntropyMnemonic, decryptDevicePinVault, decryptPlaintextWithKek, decryptWalletPayload, defaultEmbeddedHdPath, defaultUkdrTxFee, deriveKekFromPasscode, deriveKekFromPbkdf2, deriveKekFromPrf, derivePinKey, derivePrivateKeyFromHdMnemonic, deserializePlaintext, detectRecoveryMnemonicKeyType, detectWebAuthnPrfCapabilities, disableEmbeddedPasskeyUnlock, disconnectWalletConnect, downloadEmbeddedBackupFile, embeddedPlaintextToSigner, enableEmbeddedPasskeyUnlock, encodeCredentialId, encodeDirectEntropyMnemonic, encryptPlaintextWithDevicePin, encryptPlaintextWithKek, encryptWalletPayload, evaluatePasscodeStrength, exportEncryptedBackup, fetchFeeGrantGranter, fetchUkdrBalance, fetchUnclaimedFinalizedRewards, formatUkdrAsKdr, getCosmostationKeplrApi, getEmbeddedOfflineSigner, getEmbeddedQuickUnlockStatus, getEmbeddedWalletSession, getPasscodeLockoutState, getQuickUnlockStatus, hasEmbeddedWallet, hasLegacyEmbeddedWallet, hasMixedCharacterClasses, importEmbeddedBackup, initWalletConnectClient, isCosmostationAvailable, isKeplrAvailable, isLeapAvailable, isTrivialPin, loadPasscodeLockoutRecord, loadQuickUnlockRecord, loadSessionCacheRecord, loadVaultFromIndexedDb, lockEmbeddedWallet, markVaultBackupAcknowledged, migrateLegacyEmbeddedWallet, normalizePasscode, normalizeRecoveryMnemonic, openQuickUnlockRecord, parseEncryptedBackup, parseKdrToUkdr, parseWalletConnectAccount, plaintextFromRecoveryMnemonic, providerSeedFromHex, publicKeyFromPrivateSeed, readPrfOutput, recordPasscodeUnlockFailure, recordPasscodeUnlockSuccess, recoverEmbeddedWalletFromMnemonic, recoveryMnemonicAddress, recoveryMnemonicFromPlaintext, refreshQuickUnlockExpiry, registerPasskey, resolvePlaintextKeyType, resolveVaultStorageKey, restoreCachedSessionPlaintext, restoreWalletConnectSession, revealEmbeddedRecoveryPhrase, savePasscodeLockoutRecord, saveQuickUnlockRecord, saveSessionCacheRecord, saveVaultToIndexedDb, selectEmbeddedWalletKdf, serializeBackupFile, serializePlaintext, setEmbeddedQuickUnlockPin, setEmbeddedWalletPin, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, toWalletConnectCosmosChainId, tryRestoreUnlockedSession, ukdrCoin, unlockEmbeddedWallet, unlockEmbeddedWalletWithPasskey, unlockEmbeddedWalletWithPin, validateChainConfig, vaultHasPasskeyUnlock, vaultUsesPasscodeUnlock, vaultUsesPasskeyUnlock, vaultUsesPinUnlock };