@kingdomchain/wallet-client 0.1.0 → 0.2.0

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,249 @@ 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";
+type EmbeddedWalletKdf = typeof EMBEDDED_WALLET_KDF_PRF | typeof EMBEDDED_WALLET_KDF_PBKDF2;
+/** Plaintext wallet payload — never persisted unencrypted. */
+interface EmbeddedWalletPlaintext {
+    privateKey: Uint8Array;
+    hdPath: string;
+    createdAt: string;
+}
+/** 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);
+}
+
+interface EncryptWalletOptions {
+    kdf: EmbeddedWalletKdf;
+    credentialId: Uint8Array;
+    publicAddress: string;
+    kek: Uint8Array;
+    /** Required when kdf=pbkdf2-passkey */
+    kdfSalt?: Uint8Array;
+    /** Required when kdf=webauthn-prf */
+    prfSalt?: Uint8Array;
+    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;
+
+declare function saveVaultToIndexedDb(vault: EmbeddedWalletVaultV1): Promise<void>;
+declare function loadVaultFromIndexedDb(): Promise<EmbeddedWalletVaultV1 | null>;
+declare function clearVaultFromIndexedDb(): Promise<void>;
+
+interface CreateEmbeddedWalletOptions {
+    userId: Uint8Array;
+    userName: string;
+    displayName: string;
+    rpId?: string;
+}
+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 createEmbeddedWallet(options: CreateEmbeddedWalletOptions): Promise<{
+    address: string;
+    vault: EmbeddedWalletVaultV1;
+}>;
+/** Unlock existing vault with passkey; requires backup acknowledged for signing. */
+declare function unlockEmbeddedWallet(): 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 (still requires 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 +443,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_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 };